1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
|
_ _
_ __ ___ ___ __| | ___ ___| | mod_ssl
| '_ ` _ \ / _ \ / _` | / __/ __| | Apache Interface to OpenSSL
| | | | | | (_) | (_| | \__ \__ \ | www.modssl.org
|_| |_| |_|\___/ \__,_|___|___/___/_| ftp.modssl.org
|_____|
_____________________________________________________________________________
``The world does not really need
Apache-SSL easier to install.''
-- Ben Laurie, Apache-SSL author
INSTALLATION (Unix)
Introduction
____________
Because mod_ssl is a complex package there are a lot of installation
variants and options. For this different documents exists which explain
special things: Read this document when you want to install Apache+mod_ssl
under Unix. Read the INSTALL.Win32 document when you want to install it
under the Win32 (Windows 95/98/NT) platform.
Prerequisites
_____________
To use mod_ssl you need the following packages:
o Package: Apache
Version: 1.3.x
Description: The Apache Group HTTP Server
Reason: The webserver base package on which all is based
Homepage: http://www.apache.org/
Distribution: http://www.apache.org/dist/
Tarball: apache_1.3.x.tar.gz
Location: SF, USA
Author(s): The Apache Group <apache@apache.org>
Type: MANDATORY
o Package: mod_ssl
Version: 2.8.x
Description: The Apache Interface to OpenSSL
Reason: The interface module for Apache
Homepage: http://www.modssl.org/
Distribution: ftp://ftp.modssl.org/source/
Tarball: mod_ssl-2.8.x-1.3.x.tar.gz
Location: Zurich, Switzerland, Europe
Author(s): Ralf S. Engelschall <rse@engelschall.com>
Type: MANDATORY
o Package: OpenSSL
Version: 0.9.x
Description: The Open Source Toolkit for SSL/TLS
Reason: The library which implements SSL/TLS
Homepage: http://www.openssl.org/
Distribution: ftp://ftp.openssl.org/source/
Tarball: openssl-0.9.x.tar.gz
Location: Zurich, Switzerland, Europe
Author(s): The OpenSSL Project <openssl@openssl.org>
Type: MANDATORY
o Package: MM
Version: 1.1.x
Description: Shared Memory Library
Reason: The portable library for shared memory in Apache/EAPI
Homepage: http://www.engelschall.com/sw/mm/
Distribution: http://www.engelschall.com/sw/mm/
Tarball: mm-1.1.x.tar.gz
Location: Zurich, Switzerland, Europe
Author(s): Ralf S. Engelschall <rse@engelschall.com>
Type: OPTIONAL
o Package: GZip
Version: 1.2.4
Description: The compression utility
Reason: To unpack the above tarballs
Homepage: http://www.gnu.org/
Distribution: ftp://ftp.gnu.org/pub/gnu/
Tarball: gzip-1.2.4.tar.Z
Location: USA
Author(s): Free Software Foundation (FSF)
Type: MANDATORY
o Package: Perl
Version: 5.6.0
Description: The Practical Extraction and Reporting Language
Reason: To configure OpenSSL and for APXS tool in Apache
Homepage: http://www.perl.com/
Distribution: http://www.cpan.org/src/5.0/
Tarball: perl-5.6.0.tar.gz
Location: USA
Author(s): Larry Wall
Type: MANDATORY
Installation
____________
The following is a step-by-step list on how to install an SSL-aware Apache.
The actual steps you have to perform depend on the location where _YOU_ and
your webserver stay. So the commands are marked at the right-side with the
following tags:
EU ........ Command has to be run by citizens of a European state ONLY
ALL ....... Command has to be run by ANYONE, independent of location
OPTIONAL .. Command is optional and not really needed
Now follow these steps:
(the syntax is for a Bourne-Shell style shell, when you're using a C-Shell
style shell you've to adjust the commands according to your shell's manual)
1. Make sure GZip and Perl are already installed and available through the
commands `gzip' and `perl'. They are needed for unpacking the tarballs
and for configuring OpenSSL. When you've these packages still not
installed, do this first.
2. Extract the required packages:
$ gzip -d -c apache_1.3.x.tar.gz | tar xvf - ALL
$ gzip -d -c mod_ssl-2.8.x-1.3.x.tar.gz | tar xvf - ALL
$ gzip -d -c openssl-0.9.x.tar.gz | tar xvf - ALL
$ gzip -d -c mm-1.1.x.tar.gz | tar xvf - OPTIONAL
3. Configure and build the OpenSSL library:
$ cd openssl-0.9.x ALL
$ sh config \ ALL
no-idea \ EU
no-threads \ OPTIONAL
-fPIC OPTIONAL
$ make ALL
$ make test OPTIONAL
$ cd .. ALL
NOTE: OpenSSL understands a lot more options on the `config'
command line. For instance you can add some command line
options (like `-DSSL_FORBID_ENULL' for not allowing Null
encryptions, or adding `-DSSL_ALLOW_ADH' for allowing
Anonymous Diffie-Hellman ciphers, etc) to adjust the OpenSSL
internals (see OpenSSL's top-level Makefile for details).
NOTE: When your system already has OpenSSL installed (for instance some
Linux distributions ship with OpenSSL installed out-of-the-box) in
system locations you can ignore the OpenSSL steps above, too. Then
use `SSL_BASE=SYSTEM' instead of `SSL_BASE=../openssl-0.9.x' below
and mod_ssl will search for OpenSSL's binary, header and library
files in $PATH and system locations.
NOTE: The -fPIC option builds OpenSSL with Position Independent Code
(PIC) which is only important when building mod_ssl as a
Dynamic Shared Object (DSO). Please notice, that you really
have to use -fPIC and not -fpic, as the latter will usually
cause the build to fail. See below for more details.
NOTE: The optional `no-threads' keyword above is to increase
performance inside OpenSSL, because Apache 1.3 does not
use threads anyway. However, OpenSSL, if built without
`no-threads', by default builds with multi-threading support.
This multi-threading support involves using locking around a
lot of internal object manipulation (esp. reference counts).
The fact that it is not possible in Apache 1.3 to have
threads racing on any kind of object internal to OpenSSL
means that any overhead (memory and/or time) relating to
these locking mechanisms is wasted by default.
4. Optionally you now can build the MM Shared Memory library when you want
shared memory support in Apache/EAPI. For instance this allows mod_ssl to
use a high-performance RAM-based session cache instead of a disk-based
one.
$ cd mm-1.1.x OPTIONAL
$ ./configure --disable-shared OPTIONAL
$ make OPTIONAL
$ cd .. OPTIONAL
NOTE: When your system already has MM installed in system locations
you can ignore the steps above and then use `EAPI_MM=SYSTEM'
instead of `EAPI_MM=../mm-1.1.x' below.
NOTE: Do not forget the --disable-shared option above. Else you've
to establish an explicit LD_LIBRARY_PATH which includes the
/path/to/mm-1.1.x/.libs/ directory or the compilation of Apache
will fail because the shared library cannot be found.
5. Now apply the mod_ssl source extension and source patches to the Apache
source tree, configure the Apache sources and build Apache with mod_ssl
and OpenSSL.
Actually here you have three options:
(dependent on your situation and personal skill ;-)
a) The All-In-One mod_ssl+APACI way [FOR JOE AVERAGE]:
You configure Apache semi-automatically from within mod_ssl's
`configure' script. You don't have to fiddle with the SSL_BASE
variable but get no intermediate chance to add more third-party
Apache modules (e.g. mod_perl, PHP3, etc).
$ cd mod_ssl-2.8.x-1.3.x ALL
$ ./configure \ ALL
--with-apache=../apache_1.3.x \ ALL
--with-ssl=../openssl-0.9.x \ ALL
--with-mm=../mm-1.1.x \ OPTIONAL
--with-crt=/path/to/your/server.crt \ OPTIONAL
--with-key=/path/to/your/server.key \ OPTIONAL
--prefix=/path/to/apache \ ALL
[--enable-shared=ssl] \ OPTIONAL
[--disable-rule=SSL_COMPAT] \ OPTIONAL
[--enable-rule=SSL_SDBM] \ OPTIONAL
[--enable-rule=SSL_EXPERIMENTAL] \ OPTIONAL
[--enable-rule=SSL_VENDOR] \ OPTIONAL
[...more APACI options...] OPTIONAL
$ cd .. ALL
$ cd apache_1.3.x ALL
$ make ALL
$ make certificate OPTIONAL
$ make install ALL
$ cd .. ALL
NOTE: The --enable-shared=ssl option enables the building of mod_ssl
as a DSO `libssl.so'. Read the INSTALL and
htdocs/manual/dso.html documents in the Apache source tree for
more information about DSO support in Apache. We strongly advise
ISPs and package maintainers to use the DSO facility for maximum
flexibility with mod_ssl. But notice that DSO is not supported
by Apache on all platforms.
Additionally OpenSSL has problems under DSO situations on some
platforms. For instance under smart ix86 platforms like Linux
and FreeBSD when you compile a the standard OpenSSL
libcrypto.a/libssl.a libraries and link those to a mod_ssl DSO
libssl.so all works fine. While on other platforms like Solaris
2.6 on a SPARC OpenSSL's code will dump core under run-time.
When this is the case for you, then try to recompile OpenSSL
with Position Independent Code (PIC) by adding a `-fPIC' (for
GCC) or `-KPIC' (for SVR4-style compilers) to the platform
configuration line in OpenSSL's `Configure' script. The
-fPIC option above when you build OpenSSL.
NOTE: The --disable-rule=SSL_COMPAT option disables the building of
SSL compatibility code for older mod_ssl versions and other
Apache SSL solutions like Apache-SSL, Sioux, Stronghold, etc.
NOTE: The --enable-rule=SSL_SDBM option enabled the use of the
built-in SDBM library instead of a custom defined or vendor
supplied DBM library. This can be useful when the vendor DBM
library is buggy or restricts the data size too dramatically
(for SSL sessions to be cacheable the DBM library should allow
more than 1KB of data to be stored under a particular key).
NOTE: The --enable-rule=SSL_EXPERIMENTAL and --enable-rule=SSL_VENDOR
options enable various experimental and vendor extension code.
Please read the src/Configuration.tmpl file inside the Apache
source tree for more details.
NOTE: You either use `--with-crt'/`--with-key' or `make certificate'
above - but never both. The `--with-crt'/`--with-key' options is
used only when you already have a real server certificate and
private key at hand while `make certificate' is to create a test
server test certificate. Read the message box which occurs after
the `make' command when building Apache for details.
b) The flexible APACI-only way [FOR REAL HACKERS]:
You configure Apache manually and have the chance to configure
and add third-party Apache modules like mod_perl, mod_php,
mod_frontpage, mod_dav, etc. But you have to provide the
SSL_BASE and EAPI_MM variables manually and either copy your
existing certificate manually to conf/ssl.crt/server.crt or use
`make certificate':
$ cd mod_ssl-2.8.x-1.3.x ALL
$ ./configure \ ALL
--with-apache=../apache_1.3.x \ ALL
--with-crt=/path/to/your/server.crt \ OPTIONAL
--with-key=/path/to/your/server.key OPTIONAL
$ cd .. ALL
[...Now add more Apache modules to the Apache source tree...] OPTIONAL
$ cd apache_1.3.x ALL
$ SSL_BASE=../openssl-0.9.x \ ALL
EAPI_MM=../mm-1.1.x \ OPTIONAL
./configure \ ALL
--enable-module=ssl \ ALL
--prefix=/path/to/apache \ ALL
[--enable-shared=ssl] \ OPTIONAL
[--disable-rule=SSL_COMPAT] \ OPTIONAL
[--enable-rule=SSL_SDBM] \ OPTIONAL
[--enable-rule=SSL_EXPERIMENTAL] \ OPTIONAL
[--enable-rule=SSL_VENDOR] \ OPTIONAL
[...more APACI options...] OPTIONAL
$ make ALL
$ make certificate OPTIONAL
$ make install OPTIONAL
$ cd .. ALL
NOTE: The optional --enable-shared=ssl option enables the building
of mod_ssl as a DSO `libssl.so'. Read the INSTALL and
htdocs/manual/dso.html documents in the Apache source tree for
more information about DSO support in Apache. We strongly advise
ISPs and package maintainers to use the DSO facility for maximum
flexibility with mod_ssl. But notice that DSO is not supported
by Apache on all platforms.
Additionally OpenSSL has problems under DSO situations on some
platforms. For instance under smart ix86 platforms like Linux
and FreeBSD when you compile a the standard OpenSSL
libcrypto.a/libssl.a libraries and link those to a mod_ssl DSO
libssl.so all works fine. While on other platforms like Solaris
2.6 on a SPARC OpenSSL's code will dump core under run-time.
When this is the case for you, then try to recompile OpenSSL
with Position Independent Code (PIC) by adding a `-fPIC' (for
GCC) or `-KPIC' (for SVR4-style compilers) to the platform
configuration line in OpenSSL's `Configure' script. The
-fPIC option above when you build OpenSSL.
NOTE: The --disable-rule=SSL_COMPAT option disables the building of
SSL compatibility code for older mod_ssl versions and other
Apache SSL solutions like Apache-SSL, Sioux, Stronghold, etc.
NOTE: The --enable-rule=SSL_SDBM option enabled the use of the
built-in SDBM library instead of a custom defined or vendor
supplied DBM library. This can be useful when the vendor DBM
library is buggy or restricts the data size too dramatically
(for SSL sessions to be cacheable the DBM library should allow
more than 1KB of data to be stored under a particular key).
NOTE: The --enable-rule=SSL_EXPERIMENTAL and --enable-rule=SSL_VENDOR
options enable various experimental and vendor extension code.
Please read the src/Configuration.tmpl file inside the Apache
source tree for more details.
c) The poor mans way known from Apache 1.2 [FOR COMPATIBILITY]:
You configure Apache manually by editing the src/Configuration
file and running the deep-level src/Configure script. The
advantage here is that this directly follows the steps you might
be familiar with from Apache 1.2 and additionally you also have
a chance to add more third-party Apache modules like mod_perl or
mod_php because anything is done manually. But you have to edit
the SSL_BASE and EAPI_MM variables manually and more important:
you have to install the Apache package manually, too. But feel
free to be masochistic ;-)
$ cd mod_ssl-2.8.x-1.3.x ALL
$ ./configure \ ALL
--with-apache=../apache_1.3.x \ ALL
--with-crt=/path/to/your/server.crt \ OPTIONAL
--with-key=/path/to/your/server.key OPTIONAL
$ cd .. ALL
[...Add more Apache modules to the Apache source tree...] OPTIONAL
$ cd apache_1.3.x/src ALL
$ cp Configuration.tmpl Configuration ALL
$ vi Configuration ALL
[...edit the SSL_BASE variable...] ALL
[...edit the EAPI_MM variable...] OPTIONAL
[...edit the `AddModule' line of libssl.a...] ALL
$ ./Configure ALL
$ make ALL
$ make certificate OPTIONAL
Up to this point it can be acceptable, yeah? But now the friendly
world stops. The remaining installation steps have to be done manually
by coping the various files to /path/to/apache, including your
certificate, etc. That's the price for staying with the good old
days...
6. Try out Apache without SSL (only HTTP protocol possible):
$ /path/to/apache/bin/apachectl start ALL
$ netscape http://<local-host-name>/ ALL
$ /path/to/apache/bin/apachectl stop ALL
7. Try out Apache with SSL (both HTTP and HTTPS protocol possible):
$ /path/to/apache/bin/apachectl startssl ALL
$ netscape http://<local-host-name><http-port>/ ALL
$ netscape https://<local-host-name><https-port>/ ALL
$ /path/to/apache/bin/apachectl stop ALL
NOTE: Replace the `<local-host-name>' with the official name of your
host. Do not enter `localhost' here, because this name has to match
the Common Name (CN) of the Subject's Distinguished Name (DN)
inside your server certificate.
NOTE: If you have built and installed under root (uid 0),
leave out the the `<http-port>' and `<https-port>' strings above.
If you have built and installed under a different user than root,
replace `<http-port>' with `:8080' and `<https-port>' with `:8443'
above. The reason just is that Apache pre-configures the installed
configuration file for direct use (at least as long the APACI
option --without-confadjust is not used). For using the official
ports (80 for HTTP and 443 for HTTPS) root priviledges are required
under run-time, so APACI assumes that it has to use alternate ports
(8080 for HTTP and 8443 for HTTPS) if the built and installation is
done under non-root users.
NOTE: When the above tests (steps 6 and 7) fail for some reasons
you are _STRONGLY ADVISED_ to look into the Apache error logfile
before you ask someone other for help. In the error logfile there
should be a hint where to find the reason for the failure.
NOTE: When you *re*install Apache many times, make sure you restart your
browsers between the tests if you created test or custom
certificates. Else connections might fail because the browser
cached the certificate details of the previous installation.
8. Finally you're advised to do the following:
o Read the mod_ssl user manual very carefully to
understand the SSL-part of your Apache configuration:
$ netscape http://www.modssl.org/docs/2.8/ (official)
$ netscape http://localhost/manual/mod/mod_ssl/ (local copy)
o Adjust your Apache configuration to your personal requirements.
The configuration is already pre-configured for SSL, but usually it has
to be tweaked a little bit more to fit the local situation. When you
had already a httpd.conf file, this one is preserved. Then look inside
/path/to/apache/etc/httpd.conf.default for the pre-configured SSL
configuration and take it over manually into httpd.conf.
$ vi /path/to/apache/etc/httpd.conf
o Subscribe to the modssl-users@modssl.org support mailing list
with the provided web interface:
$ netscape http://www.modssl.org/news/list.html
8. Bask in the glow ;-)
Upgrading with APXS (EXPERTS ONLY)
__________________________________
Once you've built and installed Apache with mod_ssl as a DSO (libssl.so) you
can easily upgrade this libssl.so file with a stand-alone built procedure as
long as the Extended API (EAPI) didn't change and you've OpenSSL installed
somewhere. For this you can use the following procedure:
$ cd mod_ssl-2.8.x-1.3.x ALL
$ ./configure \ ALL
--with-apxs[=/path/to/apache/bin/apxs] \ ALL
--with-ssl=/path/to/openssl ALL
$ make ALL
$ make install ALL
$ make distclean ALL
This will build mod_ssl locally inside the pkg.modssl/ directory and then
upgrades your existing libssl.so file. This approach is also interesting for
package vendors. Because those can create an Apache+EAPI package (with the
use of --with-eapi-only) and a APXS-based mod_ssl package (with the use of
--with-apxs).
Examples
________
As you noticed above there are a lot of possibilities, variants and options
for installing mod_ssl. So, in the following we provide some step-by-step
examples where you can see how to build mod_ssl with other third-party
modules to form your SSL-aware Apache. For simplification we assume some
prerequisites for each example. If these don't fit your situation you have
to adjust the steps with the help of the above detailed instructions, of
course.
o Apache + mod_ssl/OpenSSL + mod_perl/Perl
---------------------------------------
Prerequisites:
o Apache should be installed to /path/to/apache
o Perl is installed and `perl' is in $PATH
o OpenSSL is installed under /path/to/openssl
Steps:
# extract the packages
$ gzip -d -c apache_1.3.x.tar.gz | tar xvf -
$ gzip -d -c mod_ssl-2.8.x-1.3.x.tar.gz | tar xvf -
$ gzip -d -c mod_perl-1.xx.tar.gz | tar xvf -
# apply mod_ssl to Apache source tree
$ cd mod_ssl-2.8.x-1.3.x
$ ./configure \
--with-apache=../apache_1.3.x
$ cd ..
# apply mod_perl to Apache source tree
# and build/install the Perl-side of mod_perl
$ cd mod_perl-1.xx
$ perl Makefile.PL \
EVERYTHING=1 \
APACHE_SRC=../apache_1.3.x/src \
USE_APACI=1 \
PREP_HTTPD=1 \
DO_HTTPD=1
$ make
$ make install
$ cd ..
# build/install Apache with mod_ssl and mod_perl
$ cd apache_1.3.x
$ SSL_BASE=/path/to/openssl \
./configure \
--prefix=/path/to/apache \
--enable-module=ssl \
--activate-module=src/modules/perl/libperl.a \
--enable-module=perl
$ make
$ make certificate
$ make install
$ cd ..
# cleanup after work
$ rm -rf mod_perl-1.xx
$ rm -rf mod_ssl-2.8.x-1.3.x
$ rm -rf apache_1.3.x
o Apache + mod_ssl/OpenSSL + PHP3/MySQL
-------------------------------------
Prerequisites:
o Apache should be installed to /path/to/apache
o MySQL is installed under /path/to/mysql
o OpenSSL is installed under /path/to/openssl
o GNU Make is available as `gmake' in $PATH
Steps:
# extract the packages
$ gzip -d -c apache_1.3.x.tar.gz | tar xvf -
$ gzip -d -c mod_ssl-2.8.x-1.3.x.tar.gz | tar xvf -
$ gzip -d -c php-3.0.x.tar.gz | tar xvf -
# apply mod_ssl to Apache source tree
$ cd /mod_ssl-2.8.x-1.3.x
$ ./configure \
--with-apache=../apache_1.3.x
$ cd ..
# pre-configure Apache for PHP3's configure step
$ cd apache_1.3.x
$ ./configure \
--prefix=/path/to/apache
$ cd ..
# configure PHP3 and apply it to the Apache source tree
$ cd ../php-3.0.x
$ CFLAGS='-O2 -I/path/to/openssl/include' \
./configure \
--with-apache=../apache_1.3.x \
--with-mysql=/path/to/mysql \
--enable-memory-limit=yes \
--enable-debug=no
$ gmake
$ gmake install
$ cd ..
# build/install Apache with mod_ssl and PHP3
$ cd apache_1.3.x
$ SSL_BASE=/path/to/openssl \
./configure \
--prefix=/path/to/apache \
--enable-module=ssl \
--activate-module=src/modules/php3/libphp3.a \
--enable-module=php3
$ make
$ make certificate
$ make install
$ cd ..
# cleanup after work
$ rm -rf php-3.0.x
$ rm -rf mod_ssl-2.8.x-1.3.x
$ rm -rf apache_1.3.x
|
