OpenSSL INSTALLATION --------------------
This document describes installation on all supported operating
systems (the Unix/Linux family (which includes Mac OS/X), OpenVMS,
and Windows).
To install OpenSSL, you will need:
* A make implementation
* Perl 5 with core modules (please read NOTES.PERL)
* The Perl module Text:: Template (please read NOTES.PERL)
* an ANSI C compiler
* a development environment in the form of development libraries and C
header files
* a supported operating system
For additional platform-specific requirements, solutions to specific
issues and other details, please read one of these:
* NOTES.UNIX (any supported Unix like system)
* NOTES.VMS (OpenVMS)
* NOTES.WIN (any supported Windows)
* NOTES.DJGPP (DOS platform with DJGPP)
* NOTES.ANDROID (obviously Android [NDK])
Quick Start -----------
If you want to just get on with it, do:
on Unix (again, this includes Mac OS/X):
$ ./config
$ make
$ make test
$ make install on OpenVMS:
$ @config
$ mms
$ mms test
$ mms install on Windows (only pick one of the targets for configuration):
$ perl Configure { VC-WIN32 | VC-WIN64A | VC-WIN64I | VC-CE }
$ nmake
$ nmake test
$ nmake install If any of these steps fails, see section Installation in Detail below.
This will build and install OpenSSL in the default location, which is:
Unix: normal installation directories under /usr/local
OpenVMS: SYS$COMMON:[OPENSSL-'version'...], where 'version' is the OpenSSL version number with underscores instead of periods.
Windows: C:\Program Files\OpenSSL or C:\Program Files (x86)\OpenSSL
If you want to install it anywhere else, run config like this:
On Unix:
$ ./config --prefix=/opt/openssl --openssldir=/usr/local/sslOn OpenVMS:
$ @config --prefix=PROGRAM:[INSTALLS] --openssldir=SYS$MANAGER:[OPENSSL]Displaying configuration data -----------------------------
For more information about configuration data, please do:
Unix
$ ./configdata.pm --help or
Windows and VMS
$ perl configdata.pm --help Installation in Detail ----------------------
Configure OpenSSL for your operation system automatically: NOTE: This is not available on Windows.
Unix
$ ./config [[ options ]] or
OpenVMS
$ @config [[ options ]] For the remainder of this text, the Unix form will be used in all
examples, please use the appropriate form for your platform.
This guesses at your operating system (and compiler, if necessary) and
configures OpenSSL based on this guess. Run ./config -t to see
if it guessed correctly. If you want to use a different compiler, you
are cross-compiling for another platform, or the ./config guess was
wrong for other reasons, Configure OpenSSL manually.
On some systems, you can include debugging information as follows: $ ./config -d [[ options ]]Configure OpenSSL for your operating system manually
OpenSSL knows about a range of different operating system, hardware and
compiler combinations. To see the ones it knows about, run
Unix
$ ./Configure or
All other platforms
$ perl Configure For the remainder of this text, the Unix form will be used in all
examples, please use the appropriate form for your platform.
Pick a suitable name from the list that matches your system. For most
operating systems there is a choice between using "cc" or "gcc". When
you have identified your system (and if necessary compiler) use this name
as the argument to Configure. For example, a "linux-elf" user would
run:
$ ./Configure linux-elf [[ options ]] If your system isn't listed, you will have to create a configuration
file named Configurations/{{ something }}.conf and add the correct
configuration for your system. See the available configs as examples
and read Configurations/README and Configurations/README.design for
more information.
The generic configurations "cc" or "gcc" should usually work on 32 bit
Unix-like systems.
Configure creates a build file ("Makefile" on Unix, "makefile" on Windows
and "descrip.mms" on OpenVMS) from a suitable template in Configurations,
and defines various macros in include/openssl/opensslconf.h (generated from
include/openssl/opensslconf.h.in).
Configure OpenSSL for building outside of the source tree. OpenSSL can be configured to build in a build directory separate from
the directory with the source code. It's done by placing yourself in
some other directory and invoking the configuration commands from
there.
Unix example:
$ mkdir /var/tmp/openssl-build
$ cd /var/tmp/openssl-build
$ /PATH/TO/OPENSSL/SOURCE/config [[ options ]] or
$ /PATH/TO/OPENSSL/SOURCE/Configure {{ target }} [[ options ]] OpenVMS example:
$ set default sys$login:
$ create/dir [.tmp.openssl-build]
$ set default [.tmp.openssl-build]
$ @[PATH.TO.OPENSSL.SOURCE]config [[ options ]] or
$ @[PATH.TO.OPENSSL.SOURCE]Configure {{ target }} [[ options ]] Windows example:
$ C:
$ mkdir \temp-openssl
$ cd \temp-openssl
$ perl d:\PATH\TO\OPENSSL\SOURCE\Configure {{ target }} [[ options ]] Paths can be relative just as well as absolute. Configure will
do its best to translate them to relative paths whenever possible.
Build OpenSSL by running: $ make # Unix
$ mms ! (or mmk) OpenVMS
$ nmake # Windows This will build the OpenSSL libraries (libcrypto.a and libssl.a on
Unix, corresponding on other platforms) and the OpenSSL binary
("openssl"). The libraries will be built in the top-level directory,
and the binary will be in the "apps" subdirectory.
Troubleshooting:
If the build fails, look at the output. There may be reasons
for the failure that aren't problems in OpenSSL itself (like
missing standard headers).
If the build succeeded previously, but fails after a source or
configuration change, it might be helpful to clean the build tree
before attempting another build. Use this command:
$ make clean # Unix
$ mms clean ! (or mmk) OpenVMS
$ nmake clean # Windows Assembler error messages can sometimes be sidestepped by using the
"no-asm" configuration option.
Compiling parts of OpenSSL with gcc and others with the system
compiler will result in unresolved symbols on some systems.
If you are still having problems you can get help by sending an email
to the openssl-users email list (see
https://www.openssl.org/community/mailinglists.html for details). If
it is a bug with OpenSSL itself, please open an issue on GitHub, at
https://github.com/openssl/openssl/issues. Please review the existing
ones first; maybe the bug was already reported or has already been
fixed.
After a successful build, the libraries should be tested. Run:
$ make test # Unix
$ mms test ! OpenVMS
$ nmake test # Windows NOTE: you MUST run the tests from an unprivileged account (or
disable your privileges temporarily if your platform allows it).
If some tests fail, look at the output. There may be reasons for
the failure that isn't a problem in OpenSSL itself (like a
malfunction with Perl). You may want increased verbosity, that
can be accomplished like this:
$ make VERBOSE=1 test # Unix
$ mms /macro=(VERBOSE=1) test ! OpenVMS
$ nmake VERBOSE=1 test # Windows If you want to run just one or a few specific tests, you can use
the make variable TESTS to specify them, like this:
$ make TESTS='test_rsa test_dsa' test # Unix
$ mms/macro="TESTS=test_rsa test_dsa" test ! OpenVMS
$ nmake TESTS='test_rsa test_dsa' test # Windows And of course, you can combine (Unix example shown):
$ make VERBOSE=1 TESTS='test_rsa test_dsa' test
You can find the list of available tests like this:
$ make list-tests # Unix
$ mms list-tests ! OpenVMS
$ nmake list-tests # Windows Have a look at the manual for the perl module Test::Harness to
see what other HARNESS_* variables there are.
If you find a problem with OpenSSL itself, try removing any
compiler optimization flags from the CFLAGS line in Makefile and
run "make clean; make" or corresponding.
To report a bug please open an issue on GitHub, at
https://github.com/openssl/openssl/issues.
For more details on how the make variables TESTS can be used,
see section TESTS in Detail below.
If everything tests ok, install OpenSSL with
$ make install # Unix
$ mms install ! OpenVMS
$ nmake install # Windows This will install all the software components in this directory
tree under PREFIX (the directory given with --prefix):
Unix:
bin/ Contains the openssl binary and a few other
utility scripts.
include/openssl
Contains the header files needed if you want
to build your own programs that use libcrypto
or libssl.
lib Contains the OpenSSL library files.
lib/engines Contains the OpenSSL dynamically loadable engines.
share/man/man1 Contains the OpenSSL command line man-pages.
share/man/man3 Contains the OpenSSL library calls man-pages.
share/man/man5 Contains the OpenSSL configuration format man-pages.
share/man/man7 Contains the OpenSSL other misc man-pages.
share/doc/openssl/html/man1
share/doc/openssl/html/man3
share/doc/openssl/html/man5
share/doc/openssl/html/man7
Contains the HTML rendition of the man-pages.
OpenVMS ('arch' is replaced with the architecture name, "Alpha"
or "ia64", 'sover' is replaced with the shared library version
(0101 for 1.1), and 'pz' is replaced with the pointer size
OpenSSL was built with):
[.EXE.'arch'] Contains the openssl binary.
[.EXE] Contains a few utility scripts.
[.include.openssl]
Contains the header files needed if you want
to build your own programs that use libcrypto
or libssl.
[.LIB.'arch'] Contains the OpenSSL library files.
[.ENGINES'sover''pz'.'arch']
Contains the OpenSSL dynamically loadable engines.
[.SYS$STARTUP] Contains startup, login and shutdown scripts.
These define appropriate logical names and
command symbols.
[.SYSTEST] Contains the installation verification procedure.
[.HTML] Contains the HTML rendition of the manual pages.
Additionally, install will add the following directories under
OPENSSLDIR (the directory given with --openssldir or its default)
for you convenience:
certs Initially empty, this is the default location
for certificate files.
private Initially empty, this is the default location
for private key files.
misc Various scripts.
Package builders who want to configure the library for standard
locations, but have the package installed somewhere else so that
it can easily be packaged, can use
$ make DESTDIR=/tmp/package-root install # Unix
$ mms/macro="DESTDIR=TMP:[PACKAGE-ROOT]" install ! OpenVMS The specified destination directory will be prepended to all
installation target paths.
