2 INSTALLATION ON THE UNIX PLATFORM
3 ---------------------------------
5 [Installation on Windows, OpenVMS and MacOS (before MacOS X) is described
6 in INSTALL.W32, INSTALL.VMS and INSTALL.MacOS.]
8 To install OpenSSL, you will need:
12 * a supported Unix operating system
17 If you want to just get on with it, do:
24 [If any of these steps fails, see section Installation in Detail below.]
26 This will build and install OpenSSL in the default location, which is (for
27 historical reasons) /usr/local/ssl. If you want to install it anywhere else,
30 $ ./config --prefix=/usr/local --openssldir=/usr/local/openssl
36 There are several options to ./config (or ./Configure) to customize
39 --prefix=DIR Install in DIR/bin, DIR/lib, DIR/include/openssl.
40 Configuration files used by OpenSSL will be in DIR/ssl
41 or the directory specified by --openssldir.
43 --openssldir=DIR Directory for OpenSSL files. If no prefix is specified,
44 the library files and binaries are also installed there.
46 rsaref Build with RSADSI's RSAREF toolkit (this assumes that
47 librsaref.a is in the library search path).
49 no-threads Don't try to build with support for multi-threaded
52 threads Build with support for multi-threaded applications.
53 This will usually require additional system-dependent options!
54 See "Note on multi-threading" below.
56 no-shared Don't try to create shared libraries.
58 shared In addition to the usual static libraries, create shared
59 libraries on platforms where it's supported. See "Note on
60 shared libraries" below.
62 no-asm Do not use assembler code.
64 386 Use the 80386 instruction set only (the default x86 code is
65 more efficient, but requires at least a 486).
67 no-<cipher> Build without the specified cipher (bf, cast, des, dh, dsa,
68 hmac, md2, md5, mdc2, rc2, rc4, rc5, rsa, sha).
69 The crypto/<cipher> directory can be removed after running
72 -Dxxx, -lxxx, -Lxxx, -fxxx, -Kxxx These system specific options will
73 be passed through to the compiler to allow you to
74 define preprocessor symbols, specify additional libraries,
75 library directories or other compiler options.
78 Installation in Detail
79 ----------------------
81 1a. Configure OpenSSL for your operation system automatically:
85 This guesses at your operating system (and compiler, if necessary) and
86 configures OpenSSL based on this guess. Run ./config -t to see
87 if it guessed correctly. If you want to use a different compiler, you
88 are cross-compiling for another platform, or the ./config guess was
89 wrong for other reasons, go to step 1b. Otherwise go to step 2.
91 On some systems, you can include debugging information as follows:
93 $ ./config -d [options]
95 1b. Configure OpenSSL for your operating system manually
97 OpenSSL knows about a range of different operating system, hardware and
98 compiler combinations. To see the ones it knows about, run
102 Pick a suitable name from the list that matches your system. For most
103 operating systems there is a choice between using "cc" or "gcc". When
104 you have identified your system (and if necessary compiler) use this name
105 as the argument to ./Configure. For example, a "linux-elf" user would
108 $ ./Configure linux-elf [options]
110 If your system is not available, you will have to edit the Configure
111 program and add the correct configuration for your system. The
112 generic configurations "cc" or "gcc" should usually work on 32 bit
115 Configure creates the file Makefile.ssl from Makefile.org and
116 defines various macros in crypto/opensslconf.h (generated from
117 crypto/opensslconf.h.in).
119 2. Build OpenSSL by running:
123 This will build the OpenSSL libraries (libcrypto.a and libssl.a) and the
124 OpenSSL binary ("openssl"). The libraries will be built in the top-level
125 directory, and the binary will be in the "apps" directory.
127 If "make" fails, please report the problem to <openssl-bugs@openssl.org>
128 (note that your message will be forwarded to a public mailing list).
129 Include the output of "make report" in your message.
131 [If you encounter assembler error messages, try the "no-asm"
132 configuration option as an immediate fix.]
134 Compiling parts of OpenSSL with gcc and others with the system
135 compiler will result in unresolved symbols on some systems.
137 3. After a successful build, the libraries should be tested. Run:
141 If a test fails, try removing any compiler optimization flags from
142 the CFLAGS line in Makefile.ssl and run "make clean; make". Please
143 send a bug report to <openssl-bugs@openssl.org>, including the
144 output of "make report".
146 4. If everything tests ok, install OpenSSL with
150 This will create the installation directory (if it does not exist) and
151 then the following subdirectories:
153 certs Initially empty, this is the default location
154 for certificate files.
155 man/man1 Manual pages for the 'openssl' command line tool
156 man/man3 Manual pages for the libraries (very incomplete)
157 misc Various scripts.
158 private Initially empty, this is the default location
159 for private key files.
161 If you didn't choose a different installation prefix, the
162 following additional subdirectories will be created:
164 bin Contains the openssl binary and a few other
166 include/openssl Contains the header files needed if you want to
167 compile programs with libcrypto or libssl.
168 lib Contains the OpenSSL library files themselves.
170 Package builders who want to configure the library for standard
171 locations, but have the package installed somewhere else so that
172 it can easily be packaged, can use
174 $ make INSTALL_PREFIX=/tmp/package-root install
176 (or specify "--install_prefix=/tmp/package-root" as a configure
177 option). The specified prefix will be prepended to all
178 installation target filenames.
181 NOTE: The header files used to reside directly in the include
182 directory, but have now been moved to include/openssl so that
183 OpenSSL can co-exist with other libraries which use some of the
184 same filenames. This means that applications that use OpenSSL
185 should now use C preprocessor directives of the form
187 #include <openssl/ssl.h>
189 instead of "#include <ssl.h>", which was used with library versions
190 up to OpenSSL 0.9.2b.
192 If you install a new version of OpenSSL over an old library version,
193 you should delete the old header files in the include directory.
195 Compatibility issues:
197 * COMPILING existing applications
199 To compile an application that uses old filenames -- e.g.
200 "#include <ssl.h>" --, it will usually be enough to find
201 the CFLAGS definition in the application's Makefile and
202 add a C option such as
204 -I/usr/local/ssl/include/openssl
208 But don't delete the existing -I option that points to
209 the ..../include directory! Otherwise, OpenSSL header files
210 could not #include each other.
212 * WRITING applications
214 To write an application that is able to handle both the new
215 and the old directory layout, so that it can still be compiled
216 with library versions up to OpenSSL 0.9.2b without bothering
217 the user, you can proceed as follows:
219 - Always use the new filename of OpenSSL header files,
220 e.g. #include <openssl/ssl.h>.
222 - Create a directory "incl" that contains only a symbolic
223 link named "openssl", which points to the "include" directory
225 For example, your application's Makefile might contain the
226 following rule, if OPENSSLDIR is a pathname (absolute or
227 relative) of the directory where OpenSSL resides:
231 cd $(OPENSSLDIR) # Check whether the directory really exists
232 -ln -s `cd $(OPENSSLDIR); pwd`/include incl/openssl
234 You will have to add "incl/openssl" to the dependencies
235 of those C files that include some OpenSSL header file.
237 - Add "-Iincl" to your CFLAGS.
239 With these additions, the OpenSSL header files will be available
240 under both name variants if an old library version is used:
241 Your application can reach them under names like <openssl/foo.h>,
242 while the header files still are able to #include each other
243 with names of the form <foo.h>.
246 Note on multi-threading
247 -----------------------
249 For some systems, the OpenSSL Configure script knows what compiler options
250 are needed to generate a library that is suitable for multi-threaded
251 applications. On these systems, support for multi-threading is enabled
252 by default; use the "no-threads" option to disable (this should never be
255 On other systems, to enable support for multi-threading, you will have
256 to specify at least two options: "threads", and a system-dependent option.
257 (The latter is "-D_REENTRANT" on various systems.) The default in this
258 case, obviously, is not to include support for multi-threading (but
259 you can still use "no-threads" to suppress an annoying warning message
260 from the Configure script.)
263 Note on shared libraries
264 ------------------------
266 For some systems, the OpenSSL Configure script knows what is needed to
267 build shared libraries for libcrypto and libssl. On these systems,
268 the shared libraries are currently not created by default, but giving
269 the option "shared" will get them created. This method supports Makefile
270 targets for shared library creation, like linux-shared. Those targets
271 can currently be used on their own just as well, but this is expected
272 to change in future versions of OpenSSL.