Contents
Abstract
With a share of more than 50%, the Apache HTTP Server (Apache) is the world's most widely-used Web server according to the Survey from http://www.netcraft.com/. Apache, developed by the Apache Software Foundation (http://www.apache.org/), is available for most operating systems. openSUSE® includes Apache version 2.2. In this chapter, learn how to install, configure and set up a Web server; how to use SSL, CGI, and additional modules; and how to troubleshoot Apache.
With the help of this section, quickly set up and start Apache. You must
be root
to install and configure Apache.
Make sure that the following requirements are met before trying to set up the Apache Web server:
The machine's network is configured properly. For more information about this topic, refer to Chapter 21, Basic Networking.
The machine's exact system time is maintained by synchronizing with a time server. This is necessary because parts of the HTTP protocol depend on the correct time. See Chapter 25, Time Synchronization with NTP to learn more about this topic.
The latest security updates are installed. If in doubt, run a YaST Online Update.
The default Web server port (port 80) is opened in the firewall. For this, configure the SUSEFirewall2 to allow the service
in the external zone. This can be done using YaST. Section “Configuring the Firewall with YaST” (Chapter 14, Masquerading and Firewalls, ↑Security Guide) gives details.Apache on openSUSE is not installed by default. To install it, start YaST and select
+ . Now choose + and select under . Confirm the installation of the dependent packages to finish the installation process.
Apache is installed with a standard, predefined configuration that runs
“out of the box”. The installation includes the
multiprocessing module apache2-prefork
as well
the PHP5 module. Refer to Section 28.4, “Installing, Activating, and Configuring Modules” for more
information about modules.
To start Apache and make sure that it is automatically started during boot, start YaST and select apache2 and the service. The Web server starts immediately. By saving your changes with , the system is configured to automatically start Apache in runlevels 3 and 5 during boot. For more information about the runlevels in openSUSE and a description of the YaST runlevel editor, refer to Section 16.2.3, “Configuring System Services (Runlevel) with YaST”.
+ . Search forTo start Apache using the shell, run rcapache2 start. To make sure that Apache is automatically started during boot in runlevels 3 and 5, use chkconfig -a apache2.
If you do not receive error messages when starting Apache, the Web server should be running. Start a browser and open http://localhost/. You should see an Apache test page stating “It works!”. If you do not see this page, refer to Section 28.8, “Troubleshooting”.
Now that the Web server is running, you can add your own documents, adjust the configuration according to your needs, or add functionality by installing modules.
Apache in openSUSE can be configured in two different ways: with YaST or manually. Manual configuration offers a higher level of detail, but lacks the convenience of the YaST GUI.
![]() | Configuration Changes |
---|---|
Changes to most configuration values for Apache only take effect after
Apache is restarted or reloaded. This happens automatically when using
YaST and finishing the configuration with Section 28.3, “Starting and Stopping Apache”. Most
configuration changes only require a reload with rcapache2
|
Configuring Apache manually involves editing the plain text
configuration files as the user
root
.
Apache configuration files can be found in two different locations:
/etc/sysconfig/apache2
/etc/apache2/
/etc/sysconfig/apache2
controls some global
settings of Apache, like modules to load, additional configuration
files to include, flags with which the server should be started, and
flags that should be added to the command line. Every configuration
option in this file is extensively documented and therefore not
mentioned here. For a general-purpose Web server, the settings in
/etc/sysconfig/apache2
should be sufficient for
any configuration needs.
/etc/apache2/
hosts all configuration files for
Apache. In the following, the purpose of each file is explained. Each
file includes several configuration options (also referred to as
directives). Every configuration option in these
files is extensively documented and therefore not mentioned here.
The Apache configuration files are organized as follows:
/etc/apache2/ | |- charset.conv |- conf.d/ | | | |- *.conf | |- default-server.conf |- errors.conf |- httpd.conf |- listen.conf |- magic |- mime.types |- mod_*.conf |- server-tuning.conf |- ssl.* |- ssl-global.conf |- sysconfig.d | | | |- global.conf | |- include.conf | |- loadmodule.conf . . | |- uid.conf |- vhosts.d | |- *.conf
Apache Configuration Files in /etc/apache2/
charset.conv
Specifies which character sets to use for different languages. Do not edit.
conf.d/*.conf
Configuration files added by other modules. These configuration
files can be included into your virtual host configuration where
needed. See vhosts.d/vhost.template
for
examples. By doing so, you can provide different module sets for
different virtual hosts.
default-server.conf
Global configuration for all virtual hosts with reasonable defaults. Instead of changing the values, overwrite them with a virtual host configuration.
errors.conf
Defines how Apache responds to errors. To customize these messages for all virtual hosts, edit this file. Otherwise overwrite these directives in your virtual host configurations.
httpd.conf
The main Apache server configuration file. Avoid changing this file. It primarily contains include statements and global settings. Overwrite global settings in the pertinent configuration files listed here. Change host-specific settings (such as document root) in your virtual host configuration.
listen.conf
Binds Apache to specific IP addresses and ports. Name-based virtual hosting (see Section 28.2.1.2.1, “Name-Based Virtual Hosts” is also configured here.
magic
Data for the mime_magic module that helps Apache automatically determine the MIME type of an unknown file. Do not change.
mime.types
MIME types known by the system (this actually is a link to
/etc/mime.types
). Do not edit. If you need to
add MIME types not listed here, add them to
mod_mime-defaults.conf
.
mod_*.conf
Configuration files for the modules that are installed by default.
Refer to Section 28.4, “Installing, Activating, and Configuring Modules” for details. Note
that configuration files for optional modules reside in the
directory conf.d
.
server-tuning.conf
Contains configuration directives for the different MPMs (see Section 28.4.4, “Multiprocessing Modules”) as well as general configuration options that control Apache's performance. Properly test your Web server when making changes here.
ssl-global.conf
and ssl.*
Global SSL configuration and SSL certificate data. Refer to Section 28.6, “Setting Up a Secure Web Server with SSL” for details.
sysconfig.d/*.conf
Configuration files automatically generated from
/etc/sysconfig/apache2
. Do not change any of
these files—edit /etc/sysconfig/apache2
instead. Put no other configuration files in this directory.
uid.conf
Specifies under which user and group ID Apache runs. Do not change.
vhosts.d/*.conf
Your virtual host configuration should go here.The directory
contains template files for virtual hosts with and without SSL.
Every file in this directory ending in .conf
is automatically included in the Apache configuration. Refer to
Section 28.2.1.2, “Virtual Host Configuration” for
details.
The term virtual host refers to Apache's ability to serve multiple URIs (universal resource identifiers) from the same physical machine. This means that several domains, such as www.example.com and www.example.net, are run by a single Web server on one physical machine.
It is common practice to use virtual hosts to save administrative effort (only a single Web server needs to be maintained) and hardware expenses (each domain does not require a dedicated server). Virtual hosts can be name based, IP based, or port based.
To list all existing virtual hosts, use the command httpd2
-S
. This outputs a list showing the default
server and all virtual hosts together with their IP addresses and
listening ports. Furthermore, the list also contains an entry for each
virtual host showing its location in the configuration files.
Virtual hosts can be configured via YaST (see
Section 28.2.2.1.4, “Virtual Hosts”)
or by manually editing a configuration file. By default, Apache in
openSUSE is prepared for one configuration file per virtual host
in /etc/apache2/vhosts.d/
. All files in this
directory with the extension .conf
are
automatically included to the configuration. A basic template for a
virtual host is provided in this directory
(vhost.template
or
vhost-ssl.template
for a virtual host with SSL
support).
![]() | Always Create a Virtual Host Configuration |
---|---|
It is recommended to always create a virtual host configuration file, even if your Web server only hosts one domain. In doing so, you not only have the domain-specific configuration in one file, but you can always fall back to a working basic configuration by simply moving, deleting, or renaming the configuration file for the virtual host. For the same reason, you should also create separate configuration files for each virtual host.
When using name-based virtual hosts it is recommended to set up a
default configuration that will be used when a domain name does not
match a virtual host configuration. The default virtual host is the
one whose configuration is loaded first. Since the order of the
configuration files is determined by filename, start the filename of
the default virtual host configuration with an “_”, e.g.
|
The
<VirtualHost>
</VirtualHost>
block holds the information that applies to a particular domain. When
Apache receives a client request for a defined virtual host, it uses
the directives enclosed in this section. Almost all directives can be
used in a virtual host context. See
http://httpd.apache.org/docs/2.2/mod/quickreference.html
for further information about Apache's configuration directives.
With name-based virtual hosts, more than one Web site is served per IP
address. Apache uses the host field in the HTTP header sent by the
client to connect the request to a matching
ServerName
entry of one of the virtual host
declarations. If no matching ServerName
is
found, the first specified virtual host is used as a default.
The directive NameVirtualHost
tells Apache on
which IP address and, optionally, which port to listen for requests by
clients containing the domain name in the HTTP header. This option is
configured in the configuration file
/etc/apache2/listen.conf
.
The first argument can be a fully qualified domain name, but it is
recommended to use the IP address. The second argument is the port and
is optional. By default, port 80 is used and is configured via the
Listen
directive.
The wild card *
can be used for both the IP address
and the port number to receive requests on all interfaces. IPv6
addresses must be enclosed in square brackets.
Example 28.1. Variations of Name-Based VirtualHost
Entries
# NameVirtualHostIP-address
[:Port]
NameVirtualHost 192.168.3.100:80 NameVirtualHost 192.168.3.100 NameVirtualHost *:80 NameVirtualHost * NameVirtualHost [2002:c0a8:364::]:80
The opening VirtualHost
tag takes the IP
address (or fully qualified domain name) previously declared with the
NameVirtualHost
as an argument in a
name-based virtual host configuration. A port number previously
declared with the NameVirtualHost
directive
is optional.
The wild card * is also allowed as a substitute
for the IP address. This syntax is only valid in combination with the
wild card usage in NameVirtualHost *
. When
using IPv6 addresses, the address must be included in square brackets.
Example 28.2. Name-Based VirtualHost
Directives
<VirtualHost 192.168.3.100:80> ... </VirtualHost> <VirtualHost 192.168.3.100> ... </VirtualHost> <VirtualHost *:80> ... </VirtualHost> <VirtualHost *> ... </VirtualHost> <VirtualHost [2002:c0a8:364::]> ... </VirtualHost>
This alternative virtual host configuration requires the setup of multiple IPs for a machine. One instance of Apache hosts several domains, each of which is assigned a different IP.
The physical server must have one IP address for each IP-based virtual host. If the machine does not have multiple network cards, virtual network interfaces (IP aliasing) can also be used.
The following example shows Apache running on a machine with the IP
192.168.3.100
, hosting two
domains on the additional IPs
192.168.3.101
and
192.168.3.102
. A separate
VirtualHost
block is needed for every virtual
server.
Example 28.3. IP-Based VirtualHost
Directives
<VirtualHost 192.168.3.101> ... </VirtualHost> <VirtualHost 192.168.3.102> ... </VirtualHost>
Here, VirtualHost
directives are only
specified for interfaces other than 192.168.3.100
.
When a Listen
directive is also configured
for 192.168.3.100
, a separate IP-based virtual host
must be created to answer HTTP requests to that
interface—otherwise the directives found in the default server
configuration (/etc/apache2/default-server.conf
)
are applied.
At least the following directives should be present in each virtual
host configuration in order to set up a virtual host. See
/etc/apache2/vhosts.d/vhost.template
for more
options.
ServerName
The fully qualified domain name under which the host should be addressed.
DocumentRoot
Path to the directory from which Apache should serve files for this
host. For security reasons, access to the entire file system is
forbidden by default, so you must explicitly unlock this directory
within a Directory
container.
ServerAdmin
E-mail address of the server administrator. This address is, for example, shown on error pages Apache creates.
ErrorLog
The error log file for this virtual host. Although it is not
necessary to create separate error log files for each virtual host,
it is common practice to do so, because it makes the debugging of
errors much easier. /var/log/apache2/
is the
default directory for Apache's log files.
CustomLog
The access log file for this virtual host. Although it is not
necessary to create separate access log files for each virtual
host, it is common practice to do so, because it allows the
separate analysis of access statistics for each host.
/var/log/apache2/
is the default directory for
Apache's log files.
As mentioned above, access to the whole file system is forbidden by
default for security reasons. Therefore, explicitly unlock the
directories in which you have placed the files Apache should
serve—for example the DocumentRoot
:
<Directory "/srv/www/www.example.com/htdocs"> Order allow,deny Allow from all </Directory>
The complete configuration file looks like this:
Example 28.4. Basic VirtualHost
Configuration
<VirtualHost 192.168.3.100> ServerName www.example.com DocumentRoot /srv/www/www.example.com/htdocs ServerAdmin webmaster@example.com ErrorLog /var/log/apache2/www.example.com_log CustomLog /var/log/apache2/www.example.com-access_log common <Directory "/srv/www/www.example.com/htdocs"> Order allow,deny Allow from all </Directory> </VirtualHost>
To configure your Web server with YaST, start YaST and select
HTTP Server Wizard
starts, prompting you to
make a few basic decisions concerning administration of the server. After
having finished the wizard, the dialog in
Section 28.2.2.2, “HTTP Server Configuration”
starts each time you call the module.
The HTTP Server Wizard consists of five steps. In the last step of the dialog, you are given the opportunity to enter the expert configuration mode to make even more specific settings.
Here, specify the network interfaces and ports Apache uses to listen for incoming requests. You can select any combination of existing network interfaces and their respective IP addresses. Ports from all three ranges (well-known ports, registered ports, and dynamic or private ports) that are not reserved by other services can be used. The default setting is to listen on all network interfaces (IP addresses) on port 80.
Check
to open the ports in the firewall that the Web server listens on. This is necessary to make the Web server available on the network, which can be a LAN, WAN, or the public Internet. Keeping the port closed is only useful in test situations where no external access to the Web server is necessary. If you have multiple network interfaces, click on to specify on which interface(s) the port(s) should be opened.Click
to continue with configuration.The Section 28.2.2.2.2, “Server Modules”. Click to advance to the next dialog.
configuration option allows for the activation or deactivation of the script languages, the Web server should support. For the activation or deactivation of other modules, refer toThis option pertains to the default Web server. As explained in Section 28.2.1.2, “Virtual Host Configuration”, Apache can serve multiple virtual hosts from a single physical machine. The first declared virtual host in the configuration file is commonly referred to as the default host. Each virtual host inherits the default host's configuration.
To edit the host settings (also called directives), choose the appropriate entry in the table then click . To add new directives, click . To delete a directive, select it and click .
Here is list of the default settings of the server:
Document Root
Path to the directory from which Apache serves files for this host.
/srv/www/htdocs
is the default location.
Alias
With the help of Alias
directives, URLs can
be mapped to physical file system locations. This means that a
certain path even outside the Document Root
in the
file system can be accessed via a URL aliasing that path.
The default openSUSE Alias
/icons
points to
/usr/share/apache2/icons
for the Apache icons
displayed in the directory index view.
ScriptAlias
Similar to the Alias
directive, the
ScriptAlias
directive maps a URL to a file
system location. The difference is that
ScriptAlias
designates the target directory
as a CGI location, meaning that CGI scripts should be executed in
that location.
Directory
With Directory
settings, you can enclose a
group of configuration options that will only apply to the specified
directory.
Access and display options for the directories
/srv/www/htdocs
,
/usr/share/apache2/icons
and
/srv/www/cgi-bin
are configured here. It should
not be necessary to change the defaults.
Include
With include, additional configuration files can be specified. Two
Include
directives are already
preconfigured: /etc/apache2/conf.d/
is the
directory containing the configuration files that come with external
modules. With this directive, all files in this directory ending in
.conf
are included. With the second directive,
/etc/apache2/conf.d/apache2-manual.conf
, the
apache2-manual
configuration file is included.
Server Name
This specifies the default URL used by clients to contact the Web
server. Use a fully qualified domain name (FQDN) to reach the Web
server at http://
or its IP address. You cannot choose an arbitrary name here—the
server must be “known” under this name.
FQDN
/
Server Administrator E-Mail
E-mail address of the server administrator. This address is, for example, shown on error pages Apache creates.
After finishing with the
step, click to continue with the configuration.In this step, the wizard displays a list of already configured virtual hosts (see Section 28.2.1.2, “Virtual Host Configuration”). If you have not made manual changes prior to starting the YaST HTTP wizard, no virtual host is present.
To add a host, click DocumentRoot
), and the . is used to
determine how a host is identified (name based or IP based). Specify the
name or IP address with
Clicking
advances to the second part of the virtual host configuration dialog.
In part two of the virtual host configuration you can specify whether or
not to enable CGI scripts and which directory to use for these scripts.
It is also possible to enable SSL. If you do so, you must specify the
path to the certificate as well. See
Section 28.6.2, “Configuring Apache with SSL” for details on SSL and
certificates. With the option, you
can specify which file to display when the client requests a directory
(by default, index.html). Add one or more filenames (space-separated) if
you want to change this. With , the
content of the users public directories
(~
) is
made available on the server under
user
/public_html/http://www.example.com/~
.
user
![]() | Creating Virtual Hosts |
---|---|
It is not possible to add virtual hosts at will. If using name-based virtual hosts, each hostname must be resolved on the network. If using IP-based virtual hosts, you can assign only one host to each IP address available. |
This is the final step of the wizard. Here, determine how and when the Apache server is started: when booting or manually. Also see a short summary of the configuration made so far. If you are satisfied with your settings, click Section 28.2.2.2, “HTTP Server Configuration”.
to complete configuration. If you want to change something, click until you have reached the desired dialog. Clicking opens the dialog described inThe
dialog also lets you make even more adjustments to the configuration than the wizard (which only runs if you configure your Web server for the first time). It consists of four tabs described in the following. No configuration option you change here is effective immediately—you always must confirm your changes with to make them effective. Clicking leaves the configuration module and discards your changes.In
, select whether Apache should be running ( ) or stopped ( ). In , , , or addresses and ports on which the server should be available. The default is to listen on all interfaces on port 80. You should always check , because otherwise the Web server is not reachable from the outside. Keeping the port closed is only useful in test situations where no external access to the Web server is necessary. If you have multiple network interfaces, click on to specify on which interface(s) the port(s) should be opened.With Section 28.3, “Starting and Stopping Apache” for details). These commands are effective immediately and their log messages are also displayed immediately.
, watch either the access log or the error log. This is useful if you want to test your configuration. The log file opens in a separate window from which you can also restart or reload the Web server (seeYou can change the status (enabled or disabled) of Apache2 modules by clicking Section 28.4, “Installing, Activating, and Configuring Modules”.
. Click to add a new module that is already installed but not yet listed. Learn more about modules inThese dialogs are identical to the ones already described. Refer to Section 28.2.2.1.3, “Default Host” and Section 28.2.2.1.4, “Virtual Hosts”.
If configured with YaST (see Section 28.2.2, “Configuring Apache with YaST”), Apache is started at boot time in runlevels 3 and 5 and stopped in runlevels 0, 1, 2, and 6. You can change this behavior using YaST's runlevel editor or the command line tool chkconfig.
To start, stop, or manipulate Apache on a running system, use the init script /usr/sbin/rcapache2 (refer to Section 16.2.2, “Init Scripts” for a general information about init scripts.). The rcapache2 command takes the following parameters:
status
Checks if Apache is started.
start
Starts Apache if it is not already running.
startssl
Starts Apache with SSL support if it is not already running. For more information about SSL support, refer to Section 28.6, “Setting Up a Secure Web Server with SSL”.
stop
Stops Apache by terminating the parent process.
restart
Stops and then restarts Apache. Starts the Web server if it was not running before.
try-restart
Stops then restarts Apache only if it is already running.
reload
or graceful
Stops the Web server by advising all forked Apache processes to first finish their requests before shutting down. As each process dies, it is replaced by a newly started one, resulting in complete “restart” of Apache.
![]() | |
rcapache2 |
restart-graceful
Starts a second Web server that immediately serves all incoming
requests. The previous instance of the Web server continues to handle
all existing requests for a defined period of time configured with
GracefulShutdownTimeout
.
rcapache2 restart-graceful
is
either useful when upgrading to a new version or when having changed
configuration options that require a restart. Using this option
ensures a minimum server downtime.
GracefulShutdownTimeout
needs to be set,
otherwise restart-graceful
will result in a regular
restart. If set to zero, the server will wait indefinitely until all
remaining requests have been fully served.
A graceful restart can fail if the original Apache instance is not able to clear all necessary resources. In this case, the command will result in a graceful stop.
stop-graceful
Stops the Web server after a defined period of time configured with
GracefulShutdownTimeout
in order to ensure
that existing requests can be finished.
GracefulShutdownTimeout
needs to be set,
otherwise stop-graceful
will result in a regular
restart. If set to zero, the server will wait indefinitely until all
remaining requests have been fully served.
configtest
or extreme-configtest
Checks the syntax of the configuration files without affecting a
running Web server. Because this check is forced every time the server
is started, reloaded, or restarted, it is usually not necessary to run
the test explicitly (if a configuration error is found, the Web server
is not started, reloaded, or restarted). The
extreme-configtest
options starts the Web server as
user nobody
and actually
loads the configuration, so more errors can be detected. Note that
although the configuration is loaded, it is not possible to test the
SSL setup because the SSL certificates cannot be read by
nobody
.
probe
Probes for the necessity of a reload (checks whether the configuration has changed) and suggests the required arguments for the rcapache2 command.
server-status and full-server-status
Dumps a short or full status screen, respectively. Requires either
lynx or w3m installed as well as the module mod_status enabled. In
addition to that, status
must be added to
APACHE_SERVER_FLAGS
in the file
/etc/sysconfig/apache2
.
![]() | Additional Flags |
---|---|
If you specify additional flags to the rcapache2, these are passed through to the Web server. |
The Apache software is built in a modular fashion: all functionality except some core tasks is handled by modules. This has progressed so far that even HTTP is processed by a module (http_core).
Apache modules can be compiled into the Apache binary at build time or dynamically loaded at runtime. Refer to Section 28.4.2, “Activation and Deactivation” for details of how to load modules dynamically.
Apache modules can be divided into four different categories:
Base modules are compiled into Apache by default. Apache in openSUSE has only mod_so (needed to load other modules) and http_core compiled in. All others are available as shared objects: rather than being included in the server binary itself, they can be included at runtime.
In general, modules labeled as extensions are included in the Apache software package, but are usually not compiled into the server statically. In openSUSE, they are available as shared objects that can be loaded into Apache at runtime.
Modules labeled external are not included in the official Apache distribution. openSUSE provides several of them readily available for use.
MPMs are responsible for accepting and handling requests to the Web server, representing the core of the Web server software.
If you have followed the default way of installing Apache (described in Section 28.1.2, “Installation”), it is installed with all base and extension modules, the multiprocessing module Prefork MPM, and the external modules mod_php5 and mod_python.
You can install additional external modules by starting YaST and choosing apache. Among other packages, the results list contains all available external Apache modules.
+ . Now choose + and search forUsing YaST, you can activate or deactivate the script language modules (PHP5, Perl, and Python) with the module configuration described in Section 28.2.2.1, “HTTP Server Wizard”. All other modules can be enabled or disabled as described in Section 28.2.2.2.2, “Server Modules”.
If you prefer to activate or deactivate the modules manually, use the
commands a2enmod mod_foo
or a2dismod mod_foo
,
respectively. a2enmod -l outputs a list of all
currently active modules.
![]() | Including Configuration Files for External Modules |
---|---|
If you have activated external modules manually, make sure to load
their configuration files in all virtual host configurations.
Configuration files for external modules are located under
|
All base and extension modules are described in detail in the Apache documentation. Only a brief description of the most important modules is available here. Refer to http://httpd.apache.org/docs/2.2/mod/ to learn details about each module.
Provides methods to execute a script whenever a certain MIME type
(such as application/pdf
), a file with a
specific extension (like .rpm
), or a certain
request method (such as GET
) is requested.
This module is enabled by default.
Provides Alias
and
Redirect
directives with which you can map a
URl to a specific directory (Alias
) or
redirect a requested URL to another location. This module is enabled
by default.
The authentication modules provide different authentication methods: basic authentication with mod_auth_basic or digest authentication with mod_auth_digest. Digest authentication in Apache 2.2 is considered experimental.
mod_auth_basic and mod_auth_digest must be combined with an authentication provider module, mod_authn_* (for example, mod_authn_file for text file–based authentication) and with an authorization module mod_authz_* (for example, mod_authz_user for user authorization).
More information about this topic is available in the “Authentication HOWTO” at http://httpd.apache.org/docs/2.2/howto/auth.html
Autoindex generates directory listings when no index file (for
example, index.html
) is present. The look and
feel of these indexes is configurable. This module is enabled by
default. However, directory listings are disabled by default via the
Options
directive—overwrite this
setting in your virtual host configuration. The default configuration
file for this module is located at
/etc/apache2/mod_autoindex-defaults.conf
.
mod_cgi is needed to execute CGI scripts. This module is enabled by default.
Using this module, Apache can be configured to compress given file types on the fly before delivering them.
mod_dir provides the DirectoryIndex
directive with which you can configure which files are automatically
delivered when a directory is requested
(index.html
by default). It also provides an
automatic redirect to the correct URl when a directory request does
not contain a trailing slash. This module is enabled by default.
Controls the environment that is passed to CGI scripts or SSI pages. Environment variables can be set or unset or passed from the shell that invoked the httpd process. This module is enabled by default.
With mod_expires, you can control how often proxy and browser caches
refresh your documents by sending an Expires
header. This module is enabled by default.
mod_include lets you use Server Side Includes (SSI), which provide a basic functionality to generate HTML pages dynamically. This module is enabled by default.
Provides a comprehensive overview of the server configuration under
http://localhost/server-info/. For security reasons, you should
always limit access to this URL. By default only
localhost
is allowed to
access this URL. mod_info is configured at
/etc/apache2/mod_info.conf
With this module, you can configure the look of the Apache log files. This module is enabled by default.
The mime module makes certain that a file is delivered with the
correct MIME header based on the filename's extension (for example
text/html
for HTML documents). This module
is enabled by default.
Necessary for content negotiation. See http://httpd.apache.org/docs/2.2/content-negotiation.html for more information. This module is enabled by default.
Provides the functionality of mod_alias, but offers more features and flexibility. With mod_rewrite, you can redirect URLs based on multiple rules, request headers, and more.
Sets environment variables based on details of the client's request, such as the browser string the client sends, or the client's IP address. This module is enabled by default.
mod_speling attempts to automatically correct typographical errors in URLs, such as capitalization errors.
Enables encrypted connections between Web server and clients. See Section 28.6, “Setting Up a Secure Web Server with SSL” for details. This module is enabled by default.
Provides information on server activity and performance under
http://localhost/server-status/. For security reasons, you should
always limit access to this URL. By default, only
localhost
is allowed to
access this URl. mod_status is configured at
/etc/apache2/mod_status.conf
mod_suexec lets you run CGI scripts under a different user and group. This module is enabled by default.
Enables user-specific directories available under
~
. The
user
/UserDir
directive must be specified in the
configuration. This module is enabled by default.
openSUSE provides two different multiprocessing modules (MPMs) for use with Apache.
The prefork MPM implements a nonthreaded, preforking Web server. It makes the Web server behave similarly to Apache version 1.x in that it isolates each request and handles it by forking a separate child process. Thus problematic requests cannot affect others, avoiding a lockup of the Web server.
While providing stability with this process-based approach, the prefork MPM consumes more system resources than its counterpart, the worker MPM. The prefork MPM is considered the default MPM for Unix-based operating systems.
![]() | MPMs in This Document |
---|---|
This document assumes Apache is used with the prefork MPM. |
The worker MPM provides a multithreaded Web server. A thread is a “lighter” form of a process. The advantage of a thread over a process is its lower resource consumption. Instead of only forking child processes, the worker MPM serves requests by using threads with server processes. The preforked child processes are multithreaded. This approach makes Apache perform better by consuming fewer system resources than the prefork MPM.
One major disadvantage is the stability of the worker MPM: if a thread becomes corrupt, all threads of a process can be affected. In the worst case, this may result in a server crash. Especially when using the Common Gateway Interface (CGI) with Apache under heavy load, internal server errors might occur due to threads being unable to communicate with system resources. Another argument against using the worker MPM with Apache is that not all available Apache modules are thread-safe and thus cannot be used in conjunction with the worker MPM.
![]() | Using PHP Modules with MPMs |
---|---|
Not all available PHP modules are thread-safe. Using the worker MPM with mod_php is strongly discouraged. |
Find a list of all external modules shipped with openSUSE here. Find the module's documentation in the listed directory.
Adds support to Apache to provide Novell AppArmor confinement to individual CGI scripts handled by modules like mod_php5 and mod_perl.
Package Name: apache2-mod_apparmor
|
More Information: Part “Confining Privileges with Novell AppArmor” (↑Security Guide) |
Using mod_mono allows you to run ASP.NET pages in your server.
Package Name: apache2-mod_mono
|
Configuration File:
/etc/apache2/conf.d/mod_mono.conf
|
mod_perl enables you to run Perl scripts in an embedded interpreter. The persistent interpreter embedded in the server avoids the overhead of starting an external interpreter and the penalty of Perl start-up time.
Package Name: apache2-mod_perl
|
Configuration File: /etc/apache2/conf.d/mod_perl.conf
|
More Information:
/usr/share/doc/packages/apache2-mod_perl
|
PHP is a server-side, cross-platform HTML embedded scripting language.
Package Name: apache2-mod_php5
|
Configuration File: /etc/apache2/conf.d/php5.conf
|
More Information:
/usr/share/doc/packages/apache2-mod_php5
|
mod_python allows embedding Python within the Apache HTTP server for a considerable boost in performance and added flexibility in designing Web-based applications.
Package Name: apache2-mod_python
|
More Information:
/usr/share/doc/packages/apache2-mod_python
|
mod_tidy validates each outgoing HTML page by means of the TidyLib. In case of a validation error, a page with an error list is delivered. Otherwise the original HTML page is delivered.
Package Name: apache2-mod_tidy
|
Configuration File: /etc/apache2/mod_tidy.conf
|
More Information: /usr/share/doc/packages/apache2-mod_tidy
|
Apache can be extended by advanced users by writing custom modules. To
develop modules for Apache or compile third-party modules, the package
apache2-devel
is required along with the
corresponding development tools. apache2-devel
also contains the apxs2 tools, which are necessary
for compiling additional modules for Apache.
apxs2 enables the compilation and installation of modules from source code (including the required changes to the configuration files), which creates dynamic shared objects (DSOs) that can be loaded into Apache at runtime.
The apxs2 binaries are located under
/usr/sbin
:
/usr/sbin/apxs2
—suitable for building an
extension module that works with any MPM. The installation location is
/usr/lib/apache2
.
/usr/sbin/apxs2-prefork
—suitable for
prefork MPM modules. The installation location is
/usr/lib/apache2-prefork
.
/usr/sbin/apxs2-worker
—suitable for worker
MPM modules. The installation location is
/usr/lib/apache2-worker
.
Install and activate a module from source code with the commands
cd /path/to/module/source; apxs2 -cia
mod_foo
.c (-c
compiles the module, -i
installs it, and
-a
activates it). Other options of
apxs2 are described in the
apxs2(1)
man page.
Apache's Common Gateway Interface (CGI) lets you create dynamic content with programs or scripts usually referred to as CGI scripts. CGI scripts can be written in any programming language. Usually, script languages such as Perl or PHP are used.
To enable Apache to deliver content created by CGI scripts, mod_cgi needs to be activated. mod_alias is also needed. Both modules are enabled by default. Refer to Section 28.4.2, “Activation and Deactivation” for details on activating modules.
![]() | CGI Security |
---|---|
Allowing the server to execute CGI scripts is a potential security hole. Refer to Section 28.7, “Avoiding Security Problems” for additional information. |
In openSUSE, the execution of CGI scripts is only allowed in the
directory /srv/www/cgi-bin/
. This location is
already configured to execute CGI scripts. If you have created a virtual
host configuration (see
Section 28.2.1.2, “Virtual Host Configuration”) and
want to place your scripts in a host-specific directory, you must unlock
and configure this directory.
Example 28.5. VirtualHost CGI Configuration
ScriptAlias /cgi-bin/ "/srv/www/www.example.com/cgi-bin/"<Directory "/srv/www/www.example.com/cgi-bin/"> Options +ExecCGI
AddHandler cgi-script .cgi .pl
Order allow,deny
Allow from all </Directory>
Tells Apache to handle all files within this directory as CGI scripts. | |
Enables CGI script execution | |
Tells the server to treat files with the extensions .pl and .cgi as CGI scripts. Adjust according to your needs. | |
The |
CGI programming differs from "regular" programming in that the CGI
programs and scripts must be preceded by a MIME-Type header such as
Content-type: text/html
. This header is sent to the
client, so it understands what kind of content it receives. Secondly,
the script's output must be something the client, usually a Web browser,
understands—HTML in most cases or plain text or images, for
example.
A simple test script available under
/usr/share/doc/packages/apache2/test-cgi
is part of
the Apache package. It outputs the content of some environment variables
as plain text. Copy this script to either
/srv/www/cgi-bin/
or the script directory of your
virtual host (/srv/www/www.example.com/cgi-bin/
) and name
it test.cgi
.
Files accessible by the Web server should be owned by to the user
root
(see
Section 28.7, “Avoiding Security Problems” for additional information).
Because the Web server runs with a different user, the CGI scripts must
be world-executable and world-readable. Change into the CGI directory
and use the command chmod 755 test.cgi to apply the
proper permissions.
Now call http://localhost/cgi-bin/test.cgi
or
http://www.example.com/cgi-bin/test.cgi
. You should see the
“CGI/1.0 test script report”.
If you do not see the output of the test program but an error message instead, check the following:
CGI Troubleshooting
Have you reloaded the server after having changed the configuration? Check with rcapache2 probe.
If you have configured your custom CGI directory, is it configured
properly? If in doubt, try the script within the default CGI directory
/srv/www/cgi-bin/
and call it with
http://localhost/cgi-bin/test.cgi
.
Are the file permissions correct? Change into the CGI directory and execute the ls -l test.cgi. Its output should start with
-rwxr-xr-x 1 root root
Make sure that the script does not contain programming errors. If you have not changed test.cgi, this should not be the case, but if you are using your own programs, always make sure that they do not contain programming errors.
Whenever sensitive data, such as credit card information, is transferred between Web server and client, it is desirable to have a secure, encrypted connection with authentication. mod_ssl provides strong encryption using the secure sockets layer (SSL) and transport layer security (TLS) protocols for HTTP communication between a client and the Web server. Using SSL/TSL, a private connection between Web server and client is established. Data integrity is ensured and client and server are able to authenticate each other.
For this purpose, the server sends an SSL certificate that holds information proving the server's valid identity before any request to a URL is answered. In turn, this guarantees that the server is the uniquely correct end point for the communication. Additionally, the certificate generates an encrypted connection between client and server that can transport information without the risk of exposing sensitive, plain-text content.
mod_ssl does not implement the SSL/TSL protocols itself, but acts as an interface between Apache and an SSL library. In openSUSE, the OpenSSL library is used. OpenSSL is automatically installed with Apache.
The most visible effect of using mod_ssl with Apache is that URLs are
prefixed with https://
instead of
http://
.
![]() | Example Certificate |
---|---|
An example certificate for a hypothetical company “Snake
Oil” is available when installing the package
|
In order to use SSL/TSL with the Web server, you need to create an SSL certificate. This certificate is needed for the authorization between Web server and client, so that each party can clearly identify the other party. To ensure the integrity of the certificate, it must be signed by a party every user trusts.
There are three types of certificates you can create: a “dummy” certificate for testing purposes only, a self-signed certificate for a defined circle of users that trust you, and a certificate signed by an independent, publicly-known certificate authority (CA).
Creating a certificate is basically a two step process. First, a private key for the certificate authority is generated then the server certificate is signed with this key.
![]() | For More Information |
---|---|
To learn more about concepts and definitions of SSL/TSL, refer to http://httpd.apache.org/docs/2.2/ssl/ssl_intro.html. |
Generating a dummy certificate is simple. Just call the script
/usr/bin/gensslcert. It creates or overwrites the
files listed below. Make use of gensslcert's
optional switches to fine-tune the certificate. Call
/usr/bin/gensslcert -h
for
more information.
/etc/apache2/ssl.crt/ca.crt
/etc/apache2/ssl.crt/server.crt
/etc/apache2/ssl.key/server.key
/etc/apache2/ssl.csr/server.csr
/root/.mkcert.cfg
A copy of ca.crt
is also placed at
/srv/www/htdocs/CA.crt
for download.
![]() | |
A dummy certificate should never be used on a production system. Only use it for testing purposes. |
If you are setting up a secure Web server for an Intranet or for a defined circle of users, it might be sufficient if you sign a certificate with your own certificate authority (CA).
Creating a self-signed certificate is an interactive nine-step process.
Change into the directory
/usr/share/doc/packages/apache2
and run the
following command: ./mkcert.sh
make --no-print-directory /usr/bin/openssl /usr/sbin/
custom
. Do not attempt to run this command from
outside this directory. The program provides a series of prompts, some
of which require user input.
Procedure 28.1. Creating a Self-Signed Certificate with mkcert.sh
Decide the signature algorithm used for certificates
Choose RSA (R, the default), because some older browsers have problems with DSA.
Generating RSA private key for CA (1024 bit)
No interaction needed.
Generating X.509 certificate signing request for
CA
Create the CA's distinguished name here. This requires you to answer
a few questions, such as country name or organization name. Enter
valid data, because everything you enter here later shows up in the
certificate. You do not need to answer every question. If one does
not apply to you or you want to leave it blank, use “.”.
Common name is the name of the CA itself—choose a significant
name, such as My company
CA.
![]() | Common Name of the CA |
---|---|
The common name of the CA must be different from the server's common name, so do not choose the fully qualified hostname in this step. |
Generating X.509 certificate for CA signed by
itself
Choose certificate version 3 (the default).
Generating RSA private key for SERVER (1024 bit)
No interaction needed.
Generating X.509 certificate signing request for
SERVER
Create the distinguished name for the server key here. Questions are almost identical to the ones already answered for the CA's distinguished name. The data entered here applies to the Web server and does not necessarily need to be identical to the CA's data (for example, if the server is located elsewhere).
![]() | Selecting a Common Name |
---|---|
The common name you enter here must be the fully qualified hostname of your secure server (for example, www.example.com). Otherwise the browser issues a warning that the certificate does not match the server when accessing the Web server. |
Generating X.509 certificate signed by own CA
Choose certificate version 3 (the default).
Encrypting RSA private key of CA with a pass phrase for
security
It is strongly recommended to encrypt the private key of the CA with a password, so choose Y and enter a password.
Encrypting RSA private key of SERVER with a pass phrase for
security
Encrypting the server key with a password requires you to enter this password every time you start the Web server. This makes it difficult to automatically start the server on boot or to restart the Web server. Therefore, it is common sense to say N to this question. Keep in mind that your key is unprotected when not encrypted with a password and make sure that only authorized persons have access to the key.
![]() | Encrypting the Server Key |
---|---|
If you choose to encrypt the server key with a password, increase
the value for |
The script's result page presents a list of certificates and keys it
has generated. Contrary to what the script outputs, the files have not
been generated in the local directory conf
, but to
the correct locations under /etc/apache2/
.
The last step is to copy the CA certificate file from
/etc/apache2/ssl.crt/ca.crt
to a location where
your users can access it in order to incorporate it into the list of
known and trusted CAs in their Web browsers. Otherwise a browser
complains that the certificate was issued by an unknown authority. The
certificate is valid for one year.
![]() | Self-Signed Certificates |
---|---|
Only use a self-signed certificate on a Web server that is accessed by people who know and trust you as a certificate authority. It is not recommended to use such a certificate on a public shop, for example. |
There are a number of official certificate authorities that sign your certificates. The certificate is signed by a trustworthy third party, so can be fully trusted. Publicly operating secure Web servers usually have got an officially signed certificate.
The best-known official CAs are Thawte (http://www.thawte.com/) or Verisign (http://www.verisign.com). These and other CAs are already compiled into all browsers, so certificates signed by these certificate authorities are automatically accepted by the browser.
When requesting an officially signed certificate, you do not send a certificate to the CA. Instead, issue a Certificate Signing Request (CSR). To create a CSR, call the script /usr/share/ssl/misc/CA.sh -newreq.
First the script asks for a password with which the CSR should be
encrypted. Then you are asked to enter a distinguished name. This
requires you to answer a few questions, such as country name or
organization name. Enter valid data—everything you enter here
later shows up in the certificate and is checked. You do not need to
answer every question. If one does not apply to you or you want to
leave it blank, use “.”. Common name is the name of the CA
itself—choose a significant name, such as My
company
CA. Last, a challenge password and an alternative
company name must be entered.
Find the CSR in the directory from which you called the script. The
file is named newreq.pem
.
The default port for SSL and TLS requests on the Web server side is 443. There is no conflict between a “regular” Apache listening on port 80 and an SSL/TLS-enabled Apache listening on port 443. In fact, HTTP and HTTPS can be run with the same Apache instance. Usually separate virtual hosts are used to dispatch requests to port 80 and port 443 to separate virtual servers.
![]() | Firewall Configuration |
---|---|
Do not forget to open the firewall for SSL-enabled Apache on port 443. This can be done with YaST as described in Section “Configuring the Firewall with YaST” (Chapter 14, Masquerading and Firewalls, ↑Security Guide). |
The SSL module is enabled by default in the global server configuration.
In case it has been disabled on your host, activate it with the
following command: a2enmod ssl. To finally enable
SSL, the server needs to be started with the flag “SSL”. To
do so, call a2enflag SSL. If you have chosen to
encrypt your server certificate with a password, you should also
increase the value for APACHE_TIMEOUT
in
/etc/sysconfig/apache2
, so you have enough time to
enter the passphrase when Apache starts. Restart the server to make
these changes active. A reload is not sufficient.
The virtual host configuration directory contains a template
/etc/apache2/vhosts.d/vhost-ssl.template
with
SSL-specific directives that are extensively documented. Refer to
Section 28.2.1.2, “Virtual Host Configuration” for the
general virtual host configuration.
To get started, copy the template to
/etc/apache2/vhosts.d/
and edit it. Adjusting the values for the following directives should be
sufficient:
mySSL-host
.conf
DocumentRoot
ServerName
ServerAdmin
ErrorLog
TransferLog
![]() | Name-Based Virtual Hosts and SSL |
---|---|
It is not possible to run multiple SSL-enabled virtual hosts on a server with only one IP address. Users connecting to such a setup receive a warning message stating that the certificate does not match the server name every time they visit the URL. A separate IP address or port is necessary for every SSL-enabled domain to achieve communication based on a valid SSL certificate. |
A Web server exposed to the public Internet requires an ongoing administrative effort. It is inevitable that security issues appear, both related to the software and to accidental misconfiguration. Here are some tips for how to deal with them.
If there are vulnerabilities found in the Apache software, a security advisory will be issued by SUSE. It contains instructions for fixing the vulnerabilities, which in turn should be applied as soon as possible. The SUSE security announcements are available from the following locations:
By default in openSUSE, the DocumentRoot
directory /srv/www/htdocs
and the CGI directory
/srv/www/cgi-bin
belong to the user and group
root
. You should not change these permissions.
If the directories were writable for all, any user could place files
into them. These files might then be executed by Apache with the
permissions of wwwrun
, which may give the user
unintended access to file system resources. Use subdirectories of
/srv/www
to place the
DocumentRoot
and CGI directories for your
virtual hosts and make sure that directories and files belong to user
and group root
.
By default, access to the whole file system is denied in
/etc/apache2/httpd.conf
. You should never overwrite
these directives, but specifically enable access to all directories
Apache should be able to read (see
Section 28.2.1.2.3, “Basic Virtual Host Configuration”
for details). In doing so, ensure that no critical files, such as
password or system configuration files, can be read from the outside.
Interactive scripts in Perl, PHP, SSI, or any other programming language can essentially run arbitrary commands and therefore present a general security issue. Scripts that will be executed from the server should only be installed from sources the server administrator trusts—allowing users to run their own scripts is generally not a good idea. It is also recommended to do security audits for all scripts.
To make the administration of scripts as easy as possible, it is common
practice to limit the execution of CGI scripts to specific directories
instead of globally allowing them. The directives
ScriptAlias
and Option
ExecCGI
are used for configuration. The openSUSE
default configuration does not allow execution of CGI scripts from
everywhere.
All CGI scripts run as the same user, so different scripts can potentially conflict with each other. The module suEXEC lets you run CGI scripts under a different user and group.
When enabling user directories (with mod_userdir or mod_rewrite) you
should strongly consider not allowing .htaccess
files, which would allow users to overwrite security settings. At least
you should limit the user's engagement by using the directive
AllowOverRide
. In openSUSE,
.htaccess
files are enabled by default, but the
user is not allowed to overwrite any Option
directives when using mod_userdir (see the
/etc/apache2/mod_userdir.conf
configuration file).
If Apache does not start, the Web page is not accessible, or users cannot connect to the Web server, it is important to find the cause of the problem. Here are some typical places to look for error explanations and important things to check.
First, rcapache2 (described in
Section 28.3, “Starting and Stopping Apache”) is verbose about errors, so can
be quite helpful if it is actually used for operating Apache. Sometimes
it is tempting to use the binary /usr/sbin/httpd2
for starting or stopping the Web server. Avoid doing this and use the
rcapache2 script instead. rcapache2
even provides tips and hints for solving configuration errors.
Second, the importance of log files cannot be overemphasized. In case of
both fatal and nonfatal errors, the Apache log files, mainly the error
log file, are the places to look for causes. Additionally, you can
control the verbosity of the logged messages with the
LogLevel
directive if more detail is needed in
the log files. By default, the error log file is located at
/var/log/apache2/error_log
.
![]() | A Simple Test |
---|---|
Watch the Apache log messages with the command tail -F
/var/log/apache2/ |
A common mistake is to not open the ports for Apache in the firewall configuration of the server. If you configure Apache with YaST, there is a separate option available to take care of this specific issue (see Section 28.2.2, “Configuring Apache with YaST”). If you are configuring Apache manually, open firewall ports for HTTP and HTTPS via YaST's firewall module.
If the error cannot be tracked down with the help of any these, check the online Apache bug database at http://httpd.apache.org/bug_report.html. Additionally, the Apache user community can be reached via a mailing list available at http://httpd.apache.org/userslist.html. A recommended newsgroup is comp.infosystems.www.servers.unix.
The package apache2-doc
contains the complete
Apache manual in various localizations for local installation and
reference. It is not installed by default—the quickest way to
install it is to use the command zypper in
apache2-doc. Once installed, the Apache manual is available at
http://localhost/manual/. You may also access it on
the Web at http://httpd.apache.org/docs-2.2/.
SUSE-specific configuration hints are available in the directory
/usr/share/doc/packages/apache2/README.*
.
For a list of new features in Apache 2.2, refer to http://httpd.apache.org/docs/2.2/new_features_2_2.html. Information about upgrading from version 2.0 to 2.2 is available at http://httpd.apache.org/docs-2.2/upgrading.html.
More information about external Apache modules from Section 28.4.5, “External Modules” is available at the following locations:
More information about developing Apache modules or about getting involved in the Apache Web server project are available at the following locations:
If you experience difficulties specific to Apache in openSUSE, take a look at the openSUSE wiki at http://en.opensuse.org/Apache. The history of Apache is provided at http://httpd.apache.org/ABOUT_APACHE.html. This page also explains why the server is called Apache.