-
Notifications
You must be signed in to change notification settings - Fork 5
/
apache2.README.Debian
439 lines (301 loc) · 14.6 KB
/
apache2.README.Debian
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
Contents
========
Apache2 Configuration under Debian GNU/Linux
Files and Directories in '/etc/apache2'
Tools
Using mod_cache_disk
SSL
Enabling SSL
Creating self-signed certificates
SSL workaround for MSIE
Suexec
Documentation
Upgrades
Common Problems
For Developers
Apache2 Configuration under Debian GNU/Linux
============================================
Debian's default Apache2 installation attempts to make adding and
removing modules, virtual hosts, and extra configuration directives as
flexible as possible, in order to make automating the changes and
administering the server as easy as possible.
Please be aware that this layout is quite different from the standard
Apache configuration. Due to the use of environment variables, apache2
needs to be started/stopped with '/etc/init.d/apache2', apachectl, or
apache2ctl. Calling '/usr/bin/apache2' directly will not work with the
default configuration. To call apache2 with specific command line
arguments, just call apache2ctl with the same arguments.
Files and Directories in '/etc/apache2':
---------------------------------------
apache2.conf
This is the main configuration file. It does not include any
actual configuration we expect to be adapted on your site, so
where possible please do not touch it. This file is the
foundation stone of the Apache configuration in Debian and should
be up to date after upgrades to make sure all configuration pieces
are properly included.
If you want to extend the global configuration, you can customize
the Apache web server by including configuration files through the
conf-available mechanism. To change listening ports and socket
configuration use ports.conf (see below).
ports.conf
Configuration directives for which ports and IP addresses to
listen to.
magic
Patterns for mod_mime_magic. This is not compatible with the format
used by current versions of the file/libmagic packages.
envvars
This contains environment variables that may be used in the
configuration. Some settings, like user and pid file, need to
go in here so that other scripts can use them. It can also
be used to change some default settings used by apache2ctl,
including the ulimit value for the maximum number of open files.
The default LANG=C setting is also here, and can be changed to a
different language.
conf-available/
Files in this directory are included in the global server scope by
this line in apache2.conf:
# Include generic snippets of statements
IncludeOptional conf-enabled/*.conf
This is a good place to add additional configuration
directives. All configuration snippets need a '.conf' suffix to be
included as actual configuration. The local administrator should
use file names starting with 'local-' to avoid name clashes with
files installed by packages.
Configuration snippets can be enabled and disabled by using the
a2enconf and a2disconf executables. This works similarly to the
approach used for modules and sites below.
Configuration snippets can of course also be included in individual
virtual hosts.
conf-enabled/
Like mods-enabled/ and sites-enabled/, a piece of configuration is
enabled by symlinking a file from conf-available/ into this
directory. The a2enconf helper is provided to assist this task.
mods-available/
This directory contains a series of .load and .conf files.
The .load files contain the Apache configuration directive
necessary to load the module in question. The corresponding
.conf files contain configuration directives necessary to
utilize the module in question.
mods-enabled/
To actually enable a module for Apache2, it is necessary to
create a symlink in this directory to the .load (and .conf, if
it exists) files associated with the module in
mods-available/. For example:
cgi.load -> /etc/apache2/mods-available/cgi.load
The a2enmod helper can be used to enable a module.
sites-available/
Like mods-available/, except that it contains configuration
directives for different virtual hosts that might be used with
apache2. Note that the hostname doesn't have to correspond
exactly with the filename. '000-default.conf' is the default
host which is provided by Debian.
sites-enabled/
Similar in functionality to mods-enabled/, sites-enabled
contains symlinks to sites in sites-available/ that the
administrator wishes to enable.
Apache uses the first VirtualHost that matches the IP/Port
as default for named virtual hosts. Therefore the 'default'
site should be called '000-default' to make sure it sorts before
other sites.
Example:
dedasys.conf -> /etc/apache2/sites-available/dedasys.conf
The a2ensite helper can be used to enable a site.
The Include directives ignore files with names that do not end with a
.conf suffix. This behavior has changed from previous releases!
In some cases you may want to enable a specific piece of configuration
(think of files shipped in conf-available/) for a particular virtual
host only and not globally as is our default. In such cases you can
disable the configuration at a global scope for example by doing
a2disconf some-configuration
Then it can be included in a particular virtual host within a file in
sites-enabled/. You may want to add
Include conf-available/some-configuration.conf
in that site configuration. However, be careful, as this may not work for
some configurations, depending on the context and implications of some
directives.
Tools
-----
a2enmod and a2dismod are available for enabling and disabling modules utilizing
the above configuration system.
a2ensite and a2dissite do essentially the same thing as the above tools, but
for sites rather than modules. Finally a2enconf and a2disconf are the
corresponding tools for configuration snippets.
a2query is a helper script providing runtime information about the running
server instance. For example it can be used to query enabled modules, the
selected MPM, and other information. This tool is primarily meant for package
maintainers who need to interact with the Apache packages to activate
their configurations upon package installation, but it can be used by users
as well.
apxs2 -a/-A is modified to use a2enmod to activate newly installed modules.
Using mod_cache_disk
====================
To ensure that the disk cache does not grow indefinitely, htcacheclean is
started when mod_cache_disk is enabled. Both daemon and cron (daily) mode
are supported. The configuration (run mode, cache size, etc.) is in
'/etc/default/apache2'.
Normally, htcacheclean is automatically started and stopped by
'/etc/init.d/apache2'. However, if you change the state of mod_cache_disk or
the configuration of htcacheclean while apache2 is running, you may need to
manually start/stop htcacheclean with "/etc/init.d/apache2 start-htcacheclean"
or "/etc/init.d/apache2 stop-htcacheclean".
Note that mod_cache_disk was named mod_disk_cache in versions 2.2 and earlier.
SSL
===
Enabling SSL
------------
To enable SSL, type (as user root):
a2ensite default-ssl
a2enmod ssl
If you want to use self-signed certificates, you should install the ssl-cert
package (see below). Otherwise, just adjust the SSLCertificateKeyFile and
SSLCertificateFile directives in '/etc/apache2/sites-available/default-ssl.conf'
to point to your SSL certificate. Then restart apache:
service apache2 restart
The SSL key file should only be readable by root; the certificate file may be
globally readable. These files are read by the Apache parent process which runs
as root, and it is therefore not necessary to make the files readable by the
www-data user.
Creating self-signed certificates
---------------------------------
If you install the ssl-cert package, a self-signed certificate will be
automatically created using the hostname currently configured on your computer.
You can recreate that certificate (e.g. after you have changed '/etc/hosts' or
DNS to give the correct hostname) as user root with:
make-ssl-cert generate-default-snakeoil --force-overwrite
To create more certificates with different host names, you can use
make-ssl-cert /usr/share/ssl-cert/ssleay.cnf /path/to/cert-file.crt
This will ask you for the hostname and place both SSL key and certificate in
the file '/path/to/cert-file.crt'. Use this file with the SSLCertificateFile
directive in the Apache config (you don't need the SSLCertificateKeyFile in
this case as it also contains the key). The file '/path/to/cert-file.crt'
should only be readable by root. A good directory to use for the additional
certificates/keys is '/etc/ssl/private'.
SSL workaround for MSIE
-----------------------
The SSL workaround for MS Internet Explorer needs to be added to your SSL
VirtualHost section (it was previously in ssl.conf but caused keepalive to be
disabled even for non-SSL connections):
BrowserMatch "MSIE [2-6]" \
nokeepalive ssl-unclean-shutdown \
downgrade-1.0 force-response-1.0
BrowserMatch "MSIE [17-9]" ssl-unclean-shutdown
The default SSL virtual host in '/etc/apache2/sites-available/default-ssl.conf'
already contains this workaround.
Suexec
======
Debian ships two version of the suexec helper program required by
mod_suexec. It is not installed by default, to avoid possible security
issues. The package apache2-suexec-pristine contains the standard version
that works only with document root /var/www, userdir suffix public_html,
and Apache run user www-data. The package apache2-suexec-custom contains a
customizable version that can be configured with a config file to use
different settings (like /srv/www as document root). For more information
see the suexec(8) man page in the apache2-suexec-custom package.
Since apache2-suexec-custom has received less testing and might be slightly
slower, apache2-suexec is the recommended version unless you need the features
from apache2-suexec-custom.
Starting with Apache 2.4 both alternatives can be installed at the same
time and the default suexec mechanism can be picked by using the
update-alternatives(8) system.
Documentation
=============
The full Apache 2 documentation can be found on the web at
http://httpd.apache.org/docs/2.4/
or, if you have installed the apache2-doc package, in
/usr/share/doc/apache2-doc/manual/
or at
http://localhost/manual/
There is also a wiki that contains useful information:
http://wiki.apache.org/httpd/
Some hints about securing Apache 2 on Debian are available at
http://wiki.debian.org/Apache/Hardening
Upgrades
========
Changes in the Apache packages that require manual configuration adjustments
are announced in NEWS.Debian. Installing the apt-listchanges package is
recommended. It will display the relevant NEWS.Debian sections before
upgrades.
Multiple instances
==================
There is some support for running multiple instances of Apache2 on the same
machine. See '/usr/share/doc/apache2/README.multiple-instances' for more
information.
Common Problems
===============
1) Error message "Could not reliably determine the server's fully qualified
domain name, using 127.0.0.1 for ServerName" during start
This can usually be ignored but it means that Apache httpd was unable to obtain
a fully-qualified hostname by doing a reverse lookup on your server's IP
address. You may want to add the fully-qualified hostname to '/etc/hosts'.
An alternative is to specify "ServerName 127.0.0.1" in the global server
context of the configuration, e.g. in
'/etc/apache2/conf-enabled/local-servername.conf'.
2) Error message "mod_rewrite: could not create rewrite_log_lock"
This probably means that there are some stale SYSV semaphores around. This
usually happens after apache2 has been killed with kill -9 (SIGKILL). You can
clean up the semaphores with:
ipcs -s | grep www-data | awk ' { print $2 } ' | xargs ipcrm sem
3) Message "File does not exist: /etc/apache2/htdocs" in error log
In most cases this means that no matching VirtualHost definition could be
found for an incoming request. Check that the target IP address/port and the
name in the Host: header of the request actually match one of the virtual
hosts.
4) Message "Couldn't create pollset in child; check user or system limits" in
error log
On Linux kernels since 2.6.27.8, the value in
/proc/sys/fs/epoll/max_user_instances
needs to be larger than
for prefork/itk MPM: 2 * MaxClients
for worker/event MPM: MaxClients + MaxClients/ThreadsPerChild
It can be set on boot by adding a line like
fs.epoll.max_user_instances=1024
to '/etc/sysctl.conf'.
There are several other error messages related to creating a pollset that can
appear for the same reason.
On the other hand, errors about adding to a pollset are related to the setting
fs.epoll.max_user_watches. On most systems, max_user_watches should be high
enough by default.
5) Message "Server should be SSL-aware but has no certificate configured" in
error log
Since 2.2.12, Apache is stricter about certain misconfigurations concerning
name based SSL virtual hosts. See NEWS.Debian.gz for more details.
XXX: TODO: document "Listen 443 http" quirk
6) Apache does not pass Authorization header to CGI scripts
This is intentional to avoid security holes. If you really want to change it,
you can use mod_rewrite:
RewriteCond %{HTTP:Authorization} (.*)
RewriteRule . - [env=HTTP_AUTHORIZATION:%1]
7) mod_dav is behaving strangely
In general, if you use mod_dav_fs, you need to disable multiviews and script
execution for that directory. For example:
<Directory /var/www/dav>
Dav on
Options -MultiViews -ExecCGI
SetHandler none
<IfModule mod_php5.c>
php_admin_value engine Off
</IfModule>
</Directory>
8) Message "apache2: bad user name ${APACHE_RUN_USER}" when starting apache2
directly
Use apache2ctl (it accepts all the same options as apache2).
9) Apache is using a lot of memory and is not freeing it even when idle
By default, Apache will not give back unused memory but keep it around for
later use.
* Tune StartServers, MaxConnectionsPerChild, MinSpareThreads/MinSpareServers,
MaxSpareThreads/MaxSpareServers in '/etc/apache2/mods-enabled/mpm_*.conf'
* If you are really starved for memory, try adding 'MaxMemFree 4' to your
Apache configuration. This will reduce Apache's performance.
Because of the way Apache's memory allocator interacts with glibc's malloc,
higher values of MaxMemFree don't have much effect.
10) A PUT with mod_dav_fs fails with "Unable to PUT new contents for /...
[403, #0]" even if Apache has permission to write the file.
Apache also needs write permission to the directory containing the file, in
order to replace it atomically.
For Developers
==============
The Apache 2 web server package provides several helpers to assist
packagers to interact with the web server for both, build and installation
time. Please refer to the PACKAGING file in the apache2 package for
detailed information.