444 lines
15 KiB
Text
444 lines
15 KiB
Text
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/apache-htcacheclean'.
|
|
|
|
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 000-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/000-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/000-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.
|
|
|
|
|
|
Unicode File Name Normalization
|
|
===============================
|
|
|
|
Using Apache with the document root on a file system that does unicode
|
|
normalization on the filenames can cause security issues. In Debian,
|
|
this affects ZFS with the non-default option to enable filename normalization,
|
|
and HFS+. It is strongly recommended not to use Apache with such file systems.
|
|
More information about this issue can be found by searching the web for
|
|
CVE-2013-0966.
|
|
|
|
|
|
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.
|
|
|
|
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) 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.
|
|
|
|
10) When starting/reloading Apache, there is the error message
|
|
"ulimit: open files: cannot modify limit: Operation not permitted"
|
|
|
|
If you are running Apache in a vserver environment, the start script may not
|
|
be allowed to set the maximum number of open files. You should adjust
|
|
APACHE_ULIMIT_MAX_FILES in /etc/apache2/envvars to your setup. You can
|
|
disable changing the limits by setting APACHE_ULIMIT_MAX_FILES=true .
|
|
|
|
|
|
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.
|