apache2.xml

<?xml version="1.0"?>
<!DOCTYPE chapter [
  <!ENTITY % entities SYSTEM "generic-entities.ent">
  %entities;
]>

<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="cha-apache2">
 <title>The Apache HTTP Server</title>
 <info>
  <meta name="description">Learn how to install, configure, and operate the popular Apache Web Server, which includes version 2.4</meta>
  <abstract>
   <para>
    According to the survey from <link xlink:href="http://www.netcraft.com/"/>,
    the Apache HTTP Server (Apache) is the world's most widely-used Web server.
    Developed by the Apache Software Foundation
    (<link xlink:href="http://www.apache.org/"/>), it is available for most
    operating systems. &productnamereg; includes Apache version 2.4. 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.
   </para>
  </abstract>
  <dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
   <dm:bugtracker/>
   <dm:translation>yes</dm:translation>
  </dm:docmanager>
 <revhistory xml:id="rh-cha-apache2">
   <revision>
     <date>2026-04-09</date>
     <revdescription>
       <para/>
     </revdescription>
   </revision>
 </revhistory>
</info>
 <sect1 xml:id="sec-apache2-quickstart">
  <title>Quick Start</title>

  <para>
   With this section, quickly set up and start Apache. You must be &rootuser;
   to install and configure Apache.
  </para>

  <sect2 xml:id="sec-apache-quickstart-requirements">
   <title>Requirements</title>
   <para>
    Make sure the following requirements are met before trying to set up the
    Apache Web server:
   </para>
   <orderedlist spacing="normal">
    <listitem>
     <para>
      The machine's network is configured properly. For more information about
      this topic, refer to <xref linkend="cha-basicnet"/>.
     </para>
    </listitem>
    <listitem>
     <para>
      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 <xref linkend="cha-netz-xntp"/> to learn more
      about this topic.
     </para>
    </listitem>
    <listitem>
     <para>
      The latest security updates are installed. If in doubt, run a &yast;
      Online Update.
     </para>
    </listitem>
    <listitem>
     <para>
      The default Web server port (<literal>80</literal>) is opened in the
      firewall. For this, configure the &susefirewall; to allow the service
      <guimenu>HTTP Server</guimenu> in the external zone. This can be done
      using &yast;. See <xref linkend="sec-security-firewall-SuSE-yast"/> for
      details.
     </para>
    </listitem>
   </orderedlist>
  </sect2>

  <sect2 xml:id="sec-apache2-quickstart-installation">
   <title>Installation</title>
   <para>
    Apache on &productname; is not installed by default. To install it with a
    standard, predefined configuration that runs <quote>out of the box</quote>,
    proceed as follows:
   </para>
   <procedure>
    <title>Installing Apache with the Default Configuration</title>
    <step>
     <para>
      Start &yast; and select <menuchoice> <guimenu>Software</guimenu>
      <guimenu>Software Management</guimenu> </menuchoice>.
     </para>
    </step>
    <step>
     <para>
      Choose <menuchoice> <guimenu>View</guimenu> <guimenu>Patterns</guimenu>
      </menuchoice> and select <guimenu>Web and LAMP Server</guimenu>.
     </para>
    </step>
    <step>
     <para>
      Confirm the installation of the dependent packages to finish the
      installation process.
     </para>
    </step>
   </procedure>
  </sect2>

  <sect2 xml:id="sect-apache-quickstart-start">
   <title>Start</title>
   <para>
    You can start Apache automatically at boot time or start it manually.
   </para>
   <para>
    To make sure that Apache is automatically started during boot in the
    targets <literal>multi-user.target</literal> and
    <literal>graphical.target</literal>, execute the following command:
   </para>
<screen>&prompt.root;systemctl enable apache2</screen>
   <para>
    <remark>taroth 2014-02-11: commenting the following procedure as it is unsure
      how to enable a service for certain targets with YaST Services Manager,
      filed bnc# 863333 for it
     UPDATE tbazant 2015-08-20: still not clear, leaving commented out
     </remark>
   </para>
   <para>
    For more information about the systemd targets in &productname; and a
    description of the &yast; <guimenu>&ycc_runlevel;</guimenu>, refer to
    <xref linkend="sec-boot-runlevel-edit"/>.
   </para>
   <para>
    To manually start Apache using the shell, run <command>systemctl start
    apache2</command>.
   </para>
   <procedure>
    <title>Checking if Apache is Running</title>
    <para>
     If you do not receive error messages when starting Apache, this usually
     indicates that the Web server is running. To test this:
    </para>
    <step>
     <para>
      Start a browser and open <uri>http://localhost/</uri>.
     </para>
     <para>
      If Apache is up and running, you get a test page stating <quote>It
      works!</quote>.
     </para>
    </step>
    <step>
     <para>
      If you do not see this page, refer to
      <xref linkend="sec-apache2-troubleeshooting"/>.
     </para>
    </step>
   </procedure>
   <para>
    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.
   </para>
  </sect2>
 </sect1>
 <sect1 xml:id="sec-apache2-configuration">
  <title>Configuring Apache</title>

  <para>
   &productname; offers two configuration options:
  </para>

  <itemizedlist mark="bullet" spacing="normal">
   <listitem>
    <para>
     <xref linkend="sec-apache2-configuration-manually" xrefstyle="select:title"/>
    </para>
   </listitem>
   <listitem>
    <para>
     <xref linkend="sec-apache2-configuration-yast" xrefstyle="select:title"/>
    </para>
   </listitem>
  </itemizedlist>

  <para>
   Manual configuration offers a higher level of detail, but lacks the
   convenience of the &yast; GUI.
  </para>

  <important>
   <title>Reload or Restart Apache after Configuration Changes</title>
   <para>
    Most configuration changes require a reload (some also a restart) of Apache
    to take effect. Manually reload Apache with <command>systemctl reload
    apache2</command> or use one of the restart options as described in
    <xref linkend="sec-apache2-start-stop"/>.
   </para>
   <para>
    If you configure Apache with &yast;, this can be taken care of
    automatically if you set <guimenu>HTTP Service</guimenu> to
    <guimenu>Enabled</guimenu> as described in
    <xref linkend="sec-apache2-configuration-yast-server-configuration"/>.
   </para>
  </important>

  <sect2 xml:id="sec-apache2-configuration-manually-configfiles">
   <title>Apache Configuration Files</title>
   <para>
    This section gives an overview of the Apache configuration files. If you
    use &yast; for configuration, you do not need to touch these
    files&mdash;however, the information might be useful for you if you want to
    switch to manual configuration later on.
   </para>
   <para>
    Apache configuration files can be found in two different locations:
   </para>
   <itemizedlist mark="bullet" spacing="normal">
    <listitem>
     <para>
      <xref linkend="sec-apache2-configuration-manually-configfiles-etc-sysconfig-apache2" xrefstyle="select:title"/>
     </para>
    </listitem>
    <listitem>
     <para>
      <xref linkend="sec-apache2-configuration-manually-configfiles-etc-apache2" xrefstyle="select:title"/>
     </para>
    </listitem>
   </itemizedlist>
   <sect3 xml:id="sec-apache2-configuration-manually-configfiles-etc-sysconfig-apache2">
    <title><filename>/etc/sysconfig/apache2</filename></title>
    <para>
     <filename>/etc/sysconfig/apache2</filename> 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
     <filename>/etc/sysconfig/apache2</filename> should be sufficient for any
     configuration needs.
    </para>
   </sect3>
   <sect3 xml:id="sec-apache2-configuration-manually-configfiles-etc-apache2">
    <title><filename>/etc/apache2/</filename></title>
    <para>
     <filename>/etc/apache2/</filename> hosts all configuration files for
     Apache. In the following, the purpose of each file is explained. Each file
     includes several configuration options (also called
     <emphasis>directives</emphasis>). Every configuration option in these
     files is extensively documented and therefore not mentioned here.
    </para>
    <para>
     The Apache configuration files are organized as follows:
    </para>
<screen>/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</screen>
    <variablelist>
     <title>Apache Configuration Files in /etc/apache2/</title>
     <varlistentry>
      <term><filename>charset.conv</filename>
      </term>
      <listitem>
       <para>
        Specifies which character sets to use for different languages. Do not
        edit this file.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><filename>conf.d/*.conf</filename>
      </term>
      <listitem>
       <para>
        Configuration files added by other modules. These configuration files
        can be included into your virtual host configuration where needed. See
        <filename>vhosts.d/vhost.template</filename> for examples. By doing so,
        you can provide different module sets for different virtual hosts.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><filename>default-server.conf</filename>
      </term>
      <listitem>
       <para>
        Global configuration for all virtual hosts with reasonable defaults.
        Instead of changing the values, overwrite them with a virtual host
        configuration.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><filename>errors.conf</filename>
      </term>
      <listitem>
       <para>
        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.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><filename>httpd.conf</filename>
      </term>
      <listitem>
       <para>
        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.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><filename>listen.conf</filename>
      </term>
      <listitem>
       <para>
        Binds Apache to specific IP addresses and ports. Name-based virtual
        hosting is also configured here. For details, see
        <xref linkend="sec-apache2-configuration-manually-vhost-named-vhosts"/>.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><filename>magic</filename>
      </term>
      <listitem>
       <para>
        Data for the mime_magic module that helps Apache automatically
        determine the MIME type of an unknown file. Do not change this file.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><filename>mime.types</filename>
      </term>
      <listitem>
       <para>
        MIME types known by the system (this actually is a link to
        <filename>/etc/mime.types</filename>). Do not edit this file. If you
        need to add MIME types not listed here, add them to
        <filename>mod_mime-defaults.conf</filename>.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><filename>mod_*.conf</filename>
      </term>
      <listitem>
       <para>
        Configuration files for the modules that are installed by default.
        Refer to <xref linkend="sec-apache2-modules"/> for details. Note that
        configuration files for optional modules reside in the directory
        <filename>conf.d</filename>.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><filename>server-tuning.conf</filename>
      </term>
      <listitem>
       <para>
        Contains configuration directives for the different MPMs (see
        <xref linkend="sec-apache2-modules-mpm"/>) and general configuration
        options that control Apache's performance. Properly test your Web
        server when making changes here.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><filename>ssl-global.conf</filename> and <filename>ssl.*</filename>
      </term>
      <listitem>
       <para>
        Global SSL configuration and SSL certificate data. Refer to
        <xref linkend="sec-apache2-ssl"/> for details.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><filename>sysconfig.d/*.conf</filename>
      </term>
      <listitem>
       <para>
        Configuration files automatically generated from
        <filename>/etc/sysconfig/apache2</filename>. Do not change any of these
        files&mdash;edit <filename>/etc/sysconfig/apache2</filename> instead.
        Do not put other configuration files in this directory.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><filename>uid.conf</filename>
      </term>
      <listitem>
       <para>
        Specifies under which user and group ID Apache runs. Do not change this
        file.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><filename>vhosts.d/*.conf</filename>
      </term>
      <listitem>
       <para>
        Your virtual host configuration should be located here. The directory
        contains template files for virtual hosts with and without SSL. Every
        file in this directory ending with <filename>.conf</filename> is
        automatically included in the Apache configuration. Refer to
        <xref linkend="sec-apache2-configuration-manually-vhost"/> for details.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </sect3>
  </sect2>

  <sect2 xml:id="sec-apache2-configuration-manually">
   <title>Configuring Apache Manually</title>
   <para>
    Configuring Apache manually involves editing plain text configuration files
    as user <systemitem class="username">root</systemitem>.
   </para>
   <sect3 xml:id="sec-apache2-configuration-manually-vhost">
    <title>Virtual Host Configuration</title>
    <para>
     The term <emphasis>virtual host</emphasis> refers to Apache's ability to
     serve multiple universal resource identifiers (URIs) from the same
     physical machine. This means that several domains, such as &wwwname; and
     &wwwname1;, are run by a single Web server on one physical machine.
    </para>
    <para>
     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.
    </para>
    <para>
     To list all existing virtual hosts, use the command
     <command>apache2ctl</command> <option>-S</option>. 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.
    </para>
    <para>
     Virtual hosts can be configured via &yast; as described in
     <xref linkend="sec-apache2-configuration-yast-wizard-virtual-hosts"/> or
     by manually editing a configuration file. By default, Apache in
     &productname; is prepared for one configuration file per virtual host in
     <filename>/etc/apache2/vhosts.d/</filename>. All files in this directory
     with the extension <filename>.conf</filename> are automatically included
     to the configuration. A basic template for a virtual host is provided in
     this directory (<filename>vhost.template</filename> or
     <filename>vhost-ssl.template</filename> for a virtual host with SSL
     support).
    </para>
    <tip>
     <title>Always Create a Virtual Host Configuration</title>
     <para>
      It is recommended to always create a virtual host configuration file,
      even if your Web server only hosts one domain. By 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.
     </para>
     <para>
      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 file name, start the file name of the default virtual
      host configuration with an underscore character (<literal>_</literal>) to
      make sure it is loaded first (for example:
      <filename>_default_vhost.conf</filename>).
     </para>
    </tip>
    <para>
     The
     <systemitem>&lt;VirtualHost&gt;</systemitem><systemitem>&lt;/VirtualHost&gt;</systemitem>
     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
     <link xlink:href="http://httpd.apache.org/docs/2.4/mod/quickreference.html"/>
     for further information about Apache's configuration directives.
    </para>
    <sect4 xml:id="sec-apache2-configuration-manually-vhost-named-vhosts">
     <title>Name-Based Virtual Hosts</title>
     <para>
      With name-based virtual hosts, more than one Web site is served per IP
      address. Apache uses the host field in the HTTP header that is sent by
      the client to connect the request to a matching
      <systemitem>ServerName</systemitem> entry of one of the virtual host
      declarations. If no matching <systemitem>ServerName</systemitem> is
      found, the first specified virtual host is used as a default.
     </para>
     <para>
      The first step is to create a <literal>&lt;VirtualHost&gt;</literal>
      block for each different name-based host that you want to serve. Inside
      each <literal>&lt;VirtualHost&gt;</literal> block, you will need at
      minimum a <literal>ServerName</literal> directive to designate which host
      is served and a <literal>DocumentRoot</literal> directive to show where
      in the file system the content for that host resides.
     </para>
     <example xml:id="ex-apache2-virtual-hosts-name-based">
      <title>Basic Examples of Name-Based <systemitem>VirtualHost</systemitem> Entries</title>
<screen>&lt;VirtualHost *:80&gt;
# This first-listed virtual host is also the default for *:80
ServerName www.example.com
ServerAlias example.com
DocumentRoot /srv/www/htdocs/domain
&lt;/VirtualHost&gt;

&lt;VirtualHost *:80&gt;
ServerName other.example.com
DocumentRoot /srv/www/htdocs/otherdomain
&lt;/VirtualHost&gt;</screen>
     </example>
     <para>
      The opening <systemitem>VirtualHost</systemitem> tag takes the IP address
      (or fully qualified domain name) as an argument in a name-based virtual
      host configuration. A port number directive is optional.
     </para>
     <para>
      The wild card <emphasis>*</emphasis> is also allowed as a substitute for
      the IP address. When using IPv6 addresses, the address must be included
      in square brackets.
     </para>
     <example xml:id="ex-apache-directives-virtualhost-name-based">
      <title>Name-Based <systemitem>VirtualHost</systemitem> Directives</title>
<screen>&lt;VirtualHost &wwwip;:80&gt;
  ...
&lt;/VirtualHost&gt;

&lt;VirtualHost &wwwip;&gt;
  ...
&lt;/VirtualHost&gt;

&lt;VirtualHost *:80&gt;
  ...
&lt;/VirtualHost&gt;

&lt;VirtualHost *&gt;
  ...
&lt;/VirtualHost&gt;

&lt;VirtualHost [&wwwipv6;]&gt;
  ...
&lt;/VirtualHost&gt;</screen>
     </example>
    </sect4>
    <sect4 xml:id="sec-apache2-configuration-manually-vhost-ip-vhosts">
     <title>IP-Based Virtual Hosts</title>
     <para>
      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.
     </para>
     <para>
      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.
     </para>
     <para>
      The following example shows Apache running on a machine with the IP
      <systemitem class="ipaddress">&wwwip;</systemitem>, hosting two domains
      on the additional IPs <systemitem class="ipaddress">&wwwip1;</systemitem>
      and <systemitem class="ipaddress">&wwwip2;</systemitem>. A separate
      <systemitem>VirtualHost</systemitem> block is needed for every virtual
      server.
     </para>
     <example xml:id="ex-apache-directives-virtualhost-ip-based">
      <title>IP-Based <systemitem>VirtualHost</systemitem> Directives</title>
<screen>&lt;VirtualHost &wwwip1;&gt;
  ...
&lt;/VirtualHost&gt;

&lt;VirtualHost &wwwip2;&gt;
  ...
&lt;/VirtualHost&gt;</screen>
     </example>
     <para>
      Here, <systemitem>VirtualHost</systemitem> directives are only specified
      for interfaces other than <systemitem>&wwwip;</systemitem>. When a
      <systemitem>Listen</systemitem> directive is also configured for
      <systemitem>&wwwip;</systemitem>, a separate IP-based virtual host must
      be created to answer HTTP requests to that interface&mdash;otherwise the
      directives found in the default server configuration
      (<filename>/etc/apache2/default-server.conf</filename>) are applied.
     </para>
    </sect4>
    <sect4 xml:id="sec-apache2-configuration-manually-vhost-basic-configuration">
     <title>Basic Virtual Host Configuration</title>
     <para>
      At least the following directives should be in each virtual host
      configuration to set up a virtual host. See
      <filename>/etc/apache2/vhosts.d/vhost.template</filename> for more
      options.
     </para>
     <variablelist>
      <varlistentry>
       <term><systemitem>ServerName</systemitem>
       </term>
       <listitem>
        <para>
         The fully qualified domain name under which the host should be
         addressed.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term><systemitem>DocumentRoot</systemitem>
       </term>
       <listitem>
        <para>
         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 <systemitem>Directory</systemitem> container.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term><systemitem>ServerAdmin</systemitem>
       </term>
       <listitem>
        <para>
         E-mail address of the server administrator. This address is, for
         example, shown on error pages Apache creates.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term><systemitem>ErrorLog</systemitem>
       </term>
       <listitem>
        <para>
         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. <filename>/var/log/apache2/</filename> is the default
         directory for Apache's log files.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term><systemitem>CustomLog</systemitem>
       </term>
       <listitem>
        <para>
         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.
         <filename>/var/log/apache2/</filename> is the default directory for
         Apache's log files.
        </para>
       </listitem>
      </varlistentry>
     </variablelist>
     <para>
      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&mdash;for example the <systemitem>DocumentRoot</systemitem>:
     </para>
<screen>&lt;Directory "/srv/www/&wwwname;/htdocs"&gt;
  Require all granted
&lt;/Directory&gt;</screen>
     <note>
      <title><literal>Require all granted</literal></title>
      <para>
       In previous versions of Apache, the statement <literal>Require all
       granted</literal> was expressed as:
      </para>
<screen>Order allow,deny
Allow from all</screen>
      <para>
       This old syntax is still supported by the
       <literal>mod_access_compat</literal> module.
      </para>
     </note>
     <para>
      The complete configuration file looks like this:
     </para>
     <example xml:id="ex-apache-directives-virtualhost-basic-configuration">
      <title>Basic <systemitem>VirtualHost</systemitem> Configuration</title>
<screen>&lt;VirtualHost &wwwip;&gt;
  ServerName &wwwname;
  DocumentRoot /srv/www/&wwwname;/htdocs
  ServerAdmin webmaster@&exampledomain;
  ErrorLog /var/log/apache2/&wwwname;_log
  CustomLog /var/log/apache2/&wwwname;-access_log common
  &lt;Directory "/srv/www/&wwwname;/htdocs"&gt;
  Require all granted
  &lt;/Directory&gt;
&lt;/VirtualHost&gt;</screen>
     </example>
    </sect4>
   </sect3>
  </sect2>

<!-- YaST configuration -->

  <xi:include href="apache2_yast_i.xml"/>

<!-- /YaST configuration -->
 </sect1>
 <sect1 xml:id="sec-apache2-start-stop">
  <title>Starting and Stopping Apache</title>

  <remark>taroth 2014-02-11: @file-maintainer: please give the following a
 thorough check - so far I only replaced the rc* commands by the systemctl
 (and where those are not available, by apachectl commands as advised by
 crrodriguez), but the descriptions might need adjustment and some commands
 are probably no longer around, therefore I commented them</remark>

  <para>
   If configured with &yast; as described in
   <xref linkend="sec-apache2-configuration-yast"/>, Apache is started at boot
   time in the <systemitem>multi-user.target</systemitem> and
   <systemitem>graphical.target</systemitem>. You can change this behavior
   using &yast;'s <guimenu>&ycc_runlevel;</guimenu> or with the
   <command>systemctl</command> command line tool (<command>systemctl
   enable</command> or <command>systemctl disable</command>).
  </para>

  <para>
   To start, stop, or manipulate Apache on a running system, use either the
   <command>systemctl</command> or the <command>apachectl</command> commands as
   described below.
  </para>

  <para>
   For general information about <command>systemctl</command> commands, refer
   to <xref linkend="sec-boot-systemd-basics-services"/>.
  </para>

  <variablelist>
   <varlistentry>
    <term><command>systemctl status apache2</command>
    </term>
    <listitem>
     <para>
      Checks if Apache is started.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><command>systemctl start apache2</command>
    </term>
    <listitem>
     <para>
      Starts Apache if it is not already running.
     </para>
    </listitem>
   </varlistentry>
<!-- taroth 2014-02-11: startssl no longer supported, can be achieched
    differently now, see
    http://httpd.apache.org/docs/2.4/programs/apachectl.html-->
<!--
  <varlistentry>
    <term><option>startssl</option>
   </term>
    <listitem>
     <para>
      Starts Apache with SSL support if it is not already running. For more
      information about SSL support, refer to
      <xref
        linkend="sec-apache2-ssl"/>.
     </para>
    </listitem>
   </varlistentry>
  -->
   <varlistentry>
    <term><command>systemctl stop apache2</command>
    </term>
    <listitem>
     <para>
      Stops Apache by terminating the parent process.
     </para>
    </listitem>
   </varlistentry>
<!--   -->
   <varlistentry>
    <term><command>systemctl restart apache2</command>
    </term>
    <listitem>
     <para>
      Stops and then restarts Apache. Starts the Web server if it was not
      running before.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><command>systemctl try-restart apache2</command>
    </term>
    <listitem>
     <para>
      Stops then restarts Apache only if it is already running.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><command>systemctl reload apache2</command>
    </term>
    <listitem>
     <para>
      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 a complete
      <quote>restart</quote> of Apache.
     </para>
     <tip>
      <title>Restarting Apache in Production Environments</title>
      <para>
       This command allows activating changes in the Apache configuration
       without causing connection break-offs.
      </para>
     </tip>
    </listitem>
   </varlistentry>
   <!-- <varlistentry>
    <term><command>apachectl -k graceful</command></term>
    <listitem>
     <para>
      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
      <systemitem>GracefulShutdownTimeout</systemitem>.
     </para>
     <para>
      This command is useful either when upgrading to a new version or when
      having changed configuration options that require a restart. Using this
      option ensures a minimum server downtime.
     </para>
     <para>
      If <systemitem>GracefulShutdownTimeout</systemitem> is set to zero, the
      server will wait indefinitely until all remaining requests have been
      fully served.
     </para>
     <para>
      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.
     </para>
    </listitem>
   </varlistentry> -->
   <varlistentry>
    <term><command>systemctl stop apache2</command></term>
    <listitem>
     <para>
      Stops the Web server after a defined period of time configured with
      <systemitem>GracefulShutdownTimeout</systemitem> to ensure that existing
      requests can be finished.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><command>apachectl configtest</command>
    </term>
    <listitem>
     <para>
      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).
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><command>apachectl status</command> and
      <command>apachectl fullstatus</command>
    </term>
    <listitem>
     <para>
      Dumps a short or full status screen, respectively. Requires the module
      <systemitem>mod_status</systemitem> to be enabled and a text-based
      browser (such as <command>links</command> or
      <command>w3m</command>) installed.
      <remark>
       FIXME: Not sure about whether the following bit has changed since SLE
       11 and rcapache2. - sknorr, 2017-06-07
      </remark>
      In addition to that,
      <literal>status</literal> must be added to
      <systemitem>APACHE_SERVER_FLAGS</systemitem> in the file
      <filename>/etc/sysconfig/apache2</filename>.
     </para>
    </listitem>
   </varlistentry>
<!-- rcapache2 could do the following two, apachectl/systemctl cannot. -
sknorr, 2017-06-07 -->
<!-- original code:
  cmdline=$(echo $apache_bin -f $httpd_conf $server_flags "$@")
  out=$(su - nobody -c "$cmdline" 2>&1)
  case $out in
  *make_sock:\ could\ not\ bind\ to\ address*) echo Syntax: OK; rc_failed=0;;
  *) echo Syntax: NOT OK:; echo $out; rc_failed=1;;
  esac
  rc_exit -->
<!--The <option>extreme-configtest</option> options start the Web server as
      user <systemitem class="username">nobody</systemitem> and actually
      load 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
      <systemitem
       class="username">nobody</systemitem>.-->
<!--<varlistentry>
    <term><option>probe</option>
    </term>
    <listitem>
     <para>
      Probes for the necessity of a reload (checks whether the configuration
      has changed) and suggests the required arguments for the
      <command>rcapache2</command> command.
     </para>
    </listitem>
   </varlistentry>-->
<!-- original code:
  for i in $httpd_conf \
    $APACHE_CONF_INCLUDE_FILES \
    $APACHE_CONF_INCLUDE_DIRS
  do
  if [ $i -nt $pidfile ]; then
    echo reload
  break
  fi -->
  </variablelist>

  <tip>
   <title>Additional Flags</title>
   <para>
    If you specify additional flags to the commands,
    these are passed through to the Web server.
   </para>
  </tip>
 </sect1>
 <sect1 xml:id="sec-apache2-modules">
  <title>Installing, Activating, and Configuring Modules</title>

  <para>
   The Apache software is built in a modular fashion: all functionality except
   some core tasks are handled by modules. This has progressed so far that even
   HTTP is processed by a module (<systemitem>http_core</systemitem>).
  </para>

  <para>
   Apache modules can be compiled into the Apache binary at build time or
   be dynamically loaded at runtime. Refer to
   <xref linkend="sec-apache2-modules-activating"/> for details of how to load
   modules dynamically.
  </para>

  <para>
   Apache modules can be divided into four different categories:
  </para>

  <variablelist>
   <varlistentry>
    <term>Base Modules</term>
    <listitem>
     <para>
      Base modules are compiled into Apache by default. Apache in &productname;
      has only <systemitem>mod_so</systemitem> (needed to load other modules)
      and <systemitem>http_core</systemitem> compiled in. All others are
      available as shared objects: rather than being included in the server
      binary itself, they can be included at runtime.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Extension Modules</term>
    <listitem>
     <para>
      In general, modules labeled as extensions are included in the Apache
      software package, but are usually not compiled into the server
      statically. In &productname;, they are available as shared objects that
      can be loaded into Apache at runtime.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>External Modules</term>
    <listitem>
     <para>
      Modules labeled external are not included in the official Apache
      distribution. However, &productname; provides several of them.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Multiprocessing Modules (MPMs)</term>
    <listitem>
     <para>
      MPMs are responsible for accepting and handling requests to the Web
      server, representing the core of the Web server software.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

  <sect2 xml:id="sec-apache2-modules-installing">
   <title>Module Installation</title>
   <para>
    If you have done a default installation as described in
    <xref linkend="sec-apache2-quickstart-installation"/>, the following
    modules are already installed: all base and extension modules, the
    multiprocessing module Prefork MPM, and the external module
    <systemitem>mod_python</systemitem>.
   </para>
   <para>
    You can install additional external modules by starting &yast; and choosing
    <menuchoice><guimenu>Software</guimenu> <guimenu>Software
    Management</guimenu></menuchoice>. Now choose
    <menuchoice><guimenu>View</guimenu> <guimenu>Search</guimenu></menuchoice>
    and search for <emphasis>apache</emphasis>. Among other packages, the
    results list contains all available external Apache modules.
   </para>
  </sect2>

  <sect2 xml:id="sec-apache2-modules-activating">
   <title>Activation and Deactivation</title>
   <para>
    Activate or deactivate particular modules either manually or with &yast;.
    In &yast;, script language modules (PHP5, Perl, and Python) need to be
    enabled or disabled with the module configuration described in
    <xref linkend="sec-apache2-configuration-yast-wizard"/>. All other modules
    can be enabled or disabled as described in
    <xref linkend="sec-apache2-configuration-yast-server-configuration-modules"/>.
   </para>
   <para>
    If you prefer to activate or deactivate the modules manually, use the
    commands <command>a2enmod</command> <replaceable>MODULE</replaceable> or
    <command>a2dismod</command> <replaceable>MODULE</replaceable>,
    respectively. <command>a2enmod -l</command> outputs a list of all currently
    active modules.
   </para>
   <important>
    <title>Including Configuration Files for External Modules</title>
    <para>
     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
     <filename>/etc/apache2/conf.d/</filename> and are loaded in
     <filename>/etc/apache2/default-server.conf</filename> by default. For more
     fine-grained control you can comment out the inclusion in
     <filename>/etc/apache2/default-server.conf</filename> and add it to
     specific virtual hosts only. See
     <filename>/etc/apache2/vhosts.d/vhost.template</filename> for examples.
    </para>
   </important>
  </sect2>

  <sect2 xml:id="sec-apache2-modules-base-extension">
   <title>Base and Extension Modules</title>
   <para>
    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
    <link xlink:href="http://httpd.apache.org/docs/2.4/mod/">http://httpd.apache.org/docs/2.4/mod/</link>
    to learn details about each module.
   </para>
   <remark>taroth 2010-07-07: new module "mod_reqtimeout" to set timeouts and
    minimum data rates for receiving requests from a client (see changelog entry
    from Mar 08th 2010) -- module classified as "experimental" on the Apache
    Web site </remark>
   <variablelist>
    <varlistentry>
     <term><systemitem>mod_actions</systemitem>
     </term>
     <listitem>
      <para>
       Provides methods to execute a script whenever a certain MIME type (such
       as <systemitem>application/pdf</systemitem>), a file with a specific
       extension (like <filename>.rpm</filename>), or a certain request method
       (such as <systemitem>GET</systemitem>) is requested. This module is
       enabled by default.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_alias</systemitem>
     </term>
     <listitem>
      <para>
       Provides <systemitem>Alias</systemitem> and
       <systemitem>Redirect</systemitem> directives with which you can map a
       URL to a specific directory (<systemitem>Alias</systemitem>) or redirect
       a requested URL to another location. This module is enabled by default.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_auth*</systemitem>
     </term>
     <listitem>
      <para>
       The authentication modules provide different authentication methods:
       basic authentication with <systemitem>mod_auth_basic</systemitem> or
       digest authentication with <systemitem>mod_auth_digest</systemitem>.
      </para>
      <para>
       <systemitem>mod_auth_basic</systemitem> and
       <systemitem>mod_auth_digest</systemitem> must be combined with an
       authentication provider module, <systemitem>mod_authn_*</systemitem>
       (for example, <systemitem>mod_authn_file</systemitem> for text
       file&ndash;based authentication) and with an authorization module
       <systemitem>mod_authz_*</systemitem> (for example,
       <systemitem>mod_authz_user</systemitem> for user authorization).
      </para>
      <para>
       More information about this topic is available in the
       <citetitle>Authentication HOWTO</citetitle> at
       <link xlink:href="http://httpd.apache.org/docs/2.4/howto/auth.html"/>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_autoindex</systemitem>
     </term>
     <listitem>
      <para>
       Autoindex generates directory listings when no index file (for example,
       <filename>index.html</filename>) 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
       <systemitem>Options</systemitem> directive&mdash;overwrite this setting
       in your virtual host configuration. The default configuration file for
       this module is located at
       <filename>/etc/apache2/mod_autoindex-defaults.conf</filename>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_cgi</systemitem>
     </term>
     <listitem>
      <para>
       <systemitem>mod_cgi</systemitem> is needed to execute CGI scripts. This
       module is enabled by default.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_deflate</systemitem>
     </term>
     <listitem>
      <para>
       Using this module, Apache can be configured to compress given file types
       on the fly before delivering them.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_dir</systemitem>
     </term>
     <listitem>
      <para>
       <systemitem>mod_dir</systemitem> provides the
       <systemitem>DirectoryIndex</systemitem> directive with which you can
       configure which files are automatically delivered when a directory is
       requested (<filename>index.html</filename> 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.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_env</systemitem>
     </term>
     <listitem>
      <para>
       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.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_expires</systemitem>
     </term>
     <listitem>
      <para>
       With <systemitem>mod_expires</systemitem>, you can control how often
       proxy and browser caches refresh your documents by sending an
       <systemitem>Expires</systemitem> header. This module is enabled by
       default.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_http2</systemitem>
     </term>
     <listitem>
      <para>
       With <systemitem>mod_http2</systemitem>, Apache gains support for the
       HTTP/2 protocol. It can be enabled by specifying
       <literal>Protocols h2 http/1.1</literal> in a
       <systemitem>VirtualHost</systemitem>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_include</systemitem>
     </term>
     <listitem>
      <para>
       <systemitem>mod_include</systemitem> lets you use Server Side Includes
       (SSI), which provide a basic functionality to generate HTML pages
       dynamically. This module is enabled by default.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_info</systemitem>
     </term>
     <listitem>
      <para>
       Provides a comprehensive overview of the server configuration under
       <uri>http://localhost/server-info/</uri>. For security reasons, you should always
       limit access to this URL. By default only
       <systemitem class="domainname">localhost</systemitem> is allowed to
       access this URL. <systemitem>mod_info</systemitem> is configured at
       <filename>/etc/apache2/mod_info.conf</filename>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_log_config</systemitem>
     </term>
     <listitem>
      <para>
       With this module, you can configure the look of the Apache log files.
       This module is enabled by default.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_mime</systemitem>
     </term>
     <listitem>
      <para>
       The mime module ensures that a file is delivered with the correct
       MIME header based on the file name's extension (for example
       <systemitem>text/html</systemitem> for HTML documents). This module is
       enabled by default.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_negotiation</systemitem>
     </term>
     <listitem>
      <para>
       Necessary for content negotiation. See
       <link xlink:href="http://httpd.apache.org/docs/2.4/content-negotiation.html">http://httpd.apache.org/docs/2.4/content-negotiation.html</link>
       for more information. This module is enabled by default.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_rewrite</systemitem>
     </term>
     <listitem>
      <para>
       Provides the functionality of <systemitem>mod_alias</systemitem>, but
       offers more features and flexibility. With
       <systemitem>mod_rewrite</systemitem>, you can redirect URLs based on
       multiple rules, request headers, and more.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_setenvif</systemitem>
     </term>
     <listitem>
      <para>
       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.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_spelling</systemitem>
     </term>
     <listitem>
      <para>
       <systemitem>mod_spelling</systemitem> attempts to automatically correct
       typographical errors in URLs, such as capitalization errors.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_ssl</systemitem>
     </term>
     <listitem>
      <para>
       Enables encrypted connections between Web server and clients. See
       <xref linkend="sec-apache2-ssl"/> for details. This module is enabled by
       default.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_status</systemitem>
     </term>
     <listitem>
      <para>
       Provides information on server activity and performance under
       <uri>http://localhost/server-status/</uri>. For security reasons, you should always
       limit access to this URL. By default, only
       <systemitem class="domainname">localhost</systemitem> is allowed to
       access this URL. <systemitem>mod_status</systemitem> is configured at
       <filename>/etc/apache2/mod_status.conf</filename>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_suexec</systemitem>
     </term>
     <listitem>
      <para>
       <systemitem>mod_suexec</systemitem> lets you run CGI scripts under a
       different user and group. This module is enabled by default.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_userdir</systemitem>
     </term>
     <listitem>
      <para>
       Enables user-specific directories available under
       <filename>~<replaceable>USER</replaceable>/</filename>. The
       <systemitem>UserDir</systemitem> directive must be specified in the
       configuration. This module is enabled by default.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </sect2>

  <sect2 xml:id="sec-apache2-modules-mpm">
   <title>Multiprocessing Modules</title>
   <para>
    &productname; provides two different multiprocessing modules (MPMs) for use
    with Apache:
   </para>
   <itemizedlist mark="bullet" spacing="normal">
    <listitem>
     <para>
      <xref linkend="sec-apache2-modules-mpm-prefork" xrefstyle="select:title"/>
     </para>
    </listitem>
    <listitem>
     <para>
      <xref linkend="sec-apache2-modules-mpm-worker" xrefstyle="select:title"/>
     </para>
    </listitem>
   </itemizedlist>
   <sect3 xml:id="sec-apache2-modules-mpm-prefork">
    <title>Prefork MPM</title>
    <para>
     The prefork MPM implements a non-threaded, preforking Web server. It makes
     the Web server behave similarly to Apache version 1.x. In this version 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.
    </para>
    <para>
     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.
    </para>
    <important>
     <title>MPMs in This Document</title>
     <para>
      This document assumes Apache is used with the prefork MPM.
     </para>
    </important>
   </sect3>
   <sect3 xml:id="sec-apache2-modules-mpm-worker">
    <title>Worker MPM</title>
    <para>
     The worker MPM provides a multi-threaded Web server. A thread is a
     <quote>lighter</quote> 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 multi-threaded. This approach
     makes Apache perform better by consuming fewer system resources than the
     prefork MPM.
    </para>
    <para>
     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 because of 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 with the worker MPM.
    </para>
    <warning>
     <title>Using PHP Modules with MPMs</title>
     <para>
      Not all available PHP modules are thread-safe. Using the worker MPM with
      <systemitem>mod_php</systemitem> is strongly discouraged.
     </para>
    </warning>
   </sect3>
  </sect2>

  <sect2 xml:id="sec-apache2-modules-external">
   <title>External Modules</title>
   <para>
    Find a list of all external modules shipped with &productname; here. Find
    the module's documentation in the listed directory.
   </para>
   <variablelist>
    <varlistentry>
     <term><systemitem>mod_apparmor</systemitem>
     </term>
     <listitem>
      <para>
       Adds support to Apache to provide &aa; confinement to individual CGI
       scripts handled by modules like <systemitem>mod_php5</systemitem> and
       <systemitem>mod_perl</systemitem>.
      </para>
      <simplelist>
       <member>
        Package Name: <systemitem>apache2-mod_apparmor</systemitem>
       </member>
       <member>
        More Information: <xref linkend="part-apparmor"/>
       </member>
      </simplelist>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_perl</systemitem>
     </term>
     <listitem>
      <para>
       <systemitem>mod_perl</systemitem> 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.
      </para>
      <simplelist>
       <member>
        Package Name: <systemitem>apache2-mod_perl</systemitem>
       </member>
       <member>
        Configuration File: <filename>/etc/apache2/conf.d/mod_perl.conf</filename>
       </member>
       <member>
        More Information:
        <filename>/usr/share/doc/packages/apache2-mod_perl</filename>
       </member>
      </simplelist>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_php5</systemitem>
     </term>
     <listitem>
      <para>
       PHP is a server-side, cross-platform HTML embedded scripting language.
      </para>
      <simplelist>
       <member>
        Package Name: <systemitem>apache2-mod_php5</systemitem>
       </member>
       <member>
        Configuration File: <filename>/etc/apache2/conf.d/php5.conf</filename>
       </member>
       <member>
        More Information:
        <filename>/usr/share/doc/packages/apache2-mod_php5</filename>
       </member>
      </simplelist>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_python</systemitem>
     </term>
     <listitem>
      <para>
       <systemitem>mod_python</systemitem> allows embedding Python within the
       Apache HTTP server for a considerable boost in performance and added
       flexibility in designing Web-based applications.
      </para>
      <simplelist>
       <member>
        Package Name: <systemitem>apache2-mod_python</systemitem>
       </member>
       <member>
        More Information:
        <filename>/usr/share/doc/packages/apache2-mod_python</filename>
       </member>
      </simplelist>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_security</systemitem>
     </term>
     <listitem>
      <para>
       <systemitem>mod_security</systemitem> provides a Web application
       firewall to protect Web applications from a range of attacks. It also
       enables HTTP traffic monitoring and real-time analysis.
      </para>
      <simplelist>
       <member>
        Package Name: <systemitem>apache2-mod_security2</systemitem>
       </member>
       <member>
        Configuration File: <filename>/etc/apache2/conf.d/mod_security2.conf</filename>
       </member>
       <member>
        More Information: <filename>/usr/share/doc/packages/apache2-mod_security2</filename>
       </member>
       <member>
        Documentation: <link xlink:href="http://modsecurity.org/documentation/"/>
       </member>
      </simplelist>
     </listitem>
    </varlistentry>
   </variablelist>
  </sect2>

  <sect2 xml:id="sec-apache2-modules-building-modules">
   <title>Compilation</title>
   <para>
    Apache can be extended by advanced users by writing custom modules. To
    develop modules for Apache or compile third-party modules, the package
    <systemitem>apache2-devel</systemitem> is required along with the
    corresponding development tools. <systemitem>apache2-devel</systemitem>
    also contains the <command>apxs2</command> tools, which are necessary for
    compiling additional modules for Apache.
   </para>
   <para>
    <command>apxs2</command> enables the compilation and installation of
    modules from source code (including the required changes to the
    configuration files), which creates <emphasis>dynamic shared
    objects</emphasis> (DSOs) that can be loaded into Apache at runtime.
   </para>
   <para>
    The <command>apxs2</command> binaries are located under
    <filename>/usr/sbin</filename>:
   </para>
   <itemizedlist mark="bullet" spacing="normal">
    <listitem>
     <para>
      <filename>/usr/sbin/apxs2</filename>&mdash;suitable for building an
      extension module that works with any MPM. The installation location is
      <filename>/usr/lib64/apache2</filename>.
     </para>
    </listitem>
    <listitem>
     <para>
      <filename>/usr/sbin/apxs2-prefork</filename>&mdash;suitable for prefork
      MPM modules. The installation location is
      <filename>/usr/lib64/apache2-prefork</filename>.
     </para>
    </listitem>
    <listitem>
     <para>
      <filename>/usr/sbin/apxs2-worker</filename>&mdash;suitable for worker MPM
      modules. The installation location is
      <filename>/usr/lib64/apache2-worker</filename>.
     </para>
    </listitem>
   </itemizedlist>
   <para>
    Install and activate a module from source code with the following commands:
   </para>
<screen>cd /path/to/module/source
apxs2 -cia <replaceable>MODULE</replaceable>.c</screen>
   <para>
    where <option>-c</option> compiles the module, <option>-i</option> installs
    it, and <option>-a</option> activates it. Other options of
    <command>apxs2</command> are described in the
    <systemitem>apxs2(1)</systemitem> man page.
   </para>
  </sect2>
 </sect1>
 <sect1 xml:id="sec-apache2-cgi">
  <title>Enabling CGI Scripts</title>

  <para>
   Apache's Common Gateway Interface (CGI) lets you create dynamic content with
   programs or scripts usually called CGI scripts. CGI scripts can be written
   in any programming language. Usually, script languages such as Perl or PHP
   are used.
  </para>

  <para>
   To enable Apache to deliver content created by CGI scripts,
   <systemitem>mod_cgi</systemitem> needs to be activated.
   <systemitem>mod_alias</systemitem> is also needed. Both modules are enabled
   by default. Refer to <xref linkend="sec-apache2-modules-activating"/> for
   details on activating modules.
  </para>

  <warning>
   <title>CGI Security</title>
   <para>
    Allowing the server to execute CGI scripts is a potential security hole.
    Refer to <xref linkend="sec-apache2-security"/> for additional information.
   </para>
  </warning>

  <sect2 xml:id="sec-apache2-cgi-configuration">
   <title>Apache Configuration</title>
   <para>
    In &productname;, the execution of CGI scripts is only allowed in the
    directory <filename>/srv/www/cgi-bin/</filename>. This location is already
    configured to execute CGI scripts. If you have created a virtual host
    configuration (see
    <xref linkend="sec-apache2-configuration-manually-vhost"/>) and want to
    place your scripts in a host-specific directory, you must unlock and
    configure this directory.
   </para>
   <example xml:id="ex-apache2-cgi-configuration">
    <title>VirtualHost CGI Configuration</title>
<screen>ScriptAlias /cgi-bin/ "/srv/www/&wwwname;/cgi-bin/"<co xml:id="co-apache2-cgi-script-alias"/>

&lt;Directory "/srv/www/&wwwname;/cgi-bin/"&gt;
 Options +ExecCGI<co xml:id="co-apache2-cgi-options"/>
 AddHandler cgi-script .cgi .pl<co xml:id="co-apache2-cgi-handler"/>
 Require all granted<co xml:id="co-apache2-cgi-order"/>
&lt;/Directory&gt;</screen>
    <calloutlist>
     <callout arearefs="co-apache2-cgi-script-alias">
      <para>
       Tells Apache to handle all files within this directory as CGI scripts.
      </para>
     </callout>
     <callout arearefs="co-apache2-cgi-options">
      <para>
       Enables CGI script execution
      </para>
     </callout>
     <callout arearefs="co-apache2-cgi-handler">
      <para>
       Tells the server to treat files with the extensions .pl and .cgi as CGI
       scripts. Adjust according to your needs.
      </para>
     </callout>
     <callout arearefs="co-apache2-cgi-order">
      <para>
       The <systemitem>Require</systemitem> directive controls the default
       access state. In this case, access is granted to the specified directory
       without limitation. For more information on authentication and
       authorization, see
       <link xlink:href="http://httpd.apache.org/docs/2.4/howto/auth.html"/>.
      </para>
     </callout>
    </calloutlist>
   </example>
  </sect2>

  <sect2 xml:id="sec-apache2-cgi-example-script">
   <title>Running an Example Script</title>
   <para>
    CGI programming differs from "regular" programming in that the CGI programs
    and scripts must be preceded by a MIME-Type header such as
    <literal>Content-type: text/html</literal>. 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&mdash;HTML usually, or plain text or images, for example.
   </para>
   <para>
    A simple test script available under
    <filename>/usr/share/doc/packages/apache2/test-cgi</filename> is part of
    the Apache package. It outputs the content of some environment variables as
    plain text. Copy this script to either
    <filename>/srv/www/cgi-bin/</filename> or the script directory of your
    virtual host (<filename>/srv/www/&wwwname;/cgi-bin/</filename>) and name it
    <filename>test.cgi</filename>. Edit the file to have
    <literal>#!/bin/sh</literal> as the first line.
   </para>
   <para>
    Files accessible by the Web server should be owned by the user
    <systemitem class="username">root</systemitem>. For additional information
    see <xref linkend="sec-apache2-security"/>. 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
    <command>chmod 755 test.cgi</command> to apply the proper permissions.
   </para>
   <para>
    Now call <uri>http://localhost/cgi-bin/test.cgi</uri> or
    <literal>http://&wwwname;/cgi-bin/test.cgi</literal>. You should see the
    <quote>CGI/1.0 test script report</quote>.
   </para>
  </sect2>

  <sect2 xml:id="sec-apache2-cgi-troubleshooting">
   <title>CGI Troubleshooting</title>
   <para>
    If you do not see the output of the test program but an error message
    instead, check the following:
   </para>
   <itemizedlist mark="bullet" spacing="normal">
    <title>CGI Troubleshooting</title>
    <listitem>
     <para>
      <emphasis>Have you reloaded the server after having changed the
      configuration?</emphasis>
      If not, reload with <command>systemctl reload apache2</command>
     </para>
    </listitem>
    <listitem>
     <para>
      <emphasis>If you have configured your custom CGI directory, is it
      configured properly?</emphasis>
      If in doubt, try the script within the default CGI directory
      <filename>/srv/www/cgi-bin/</filename> and call it with
      <literal>http://localhost/cgi-bin/test.cgi</literal>.
     </para>
    </listitem>
    <listitem>
     <para>
      <emphasis>Are the file permissions correct?</emphasis>
      Change into the CGI directory and
      execute <command>ls -l test.cgi</command>. The output should start with
     </para>
<screen>-rwxr-xr-x  1 root root</screen>
    </listitem>
    <listitem>
     <para>
      Make sure that the script does not contain programming errors. If you
      have not changed <filename>test.cgi</filename>, this should not be the
      case, but if you are using your own programs, always make sure that they
      do not contain programming errors.
     </para>
    </listitem>
   </itemizedlist>
  </sect2>
 </sect1>
 <sect1 xml:id="sec-apache2-ssl">
  <title>Setting Up a Secure Web Server with SSL</title>

  <para>
   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.  <systemitem>mod_ssl</systemitem> 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/TLS, a private connection between Web server and client is
   established. Data integrity is ensured and client and server can
   authenticate each other.
  </para>

  <para>
   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.
  </para>

  <para>
   <systemitem>mod_ssl</systemitem> does not implement the SSL/TLS protocols
   itself, but acts as an interface between Apache and an SSL library. In
   &productname;, the OpenSSL library is used. OpenSSL is automatically
   installed with Apache.
  </para>

  <para>
   The most visible effect of using <systemitem>mod_ssl</systemitem> with
   Apache is that URLs are prefixed with <literal>https://</literal> instead of
   <literal>http://</literal>.
  </para>

  <sect2 xml:id="sec-apache2-ssl-certificate">
   <title>Creating an SSL Certificate</title>
   <para>
    To use SSL/TLS 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.
   </para>
   <para>
    There are three types of certificates you can create: a
    <quote>dummy</quote> 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).
   </para>
   <para>
    Creating a certificate is a two step process. First, a private key for the
    certificate authority is generated then the server certificate is signed
    with this key.
   </para>
   <tip>
    <title>For More Information</title>
    <para>
     To learn more about concepts and definitions of TLS/SSL, refer to
     <link xlink:href="https://httpd.apache.org/docs/2.4/ssl/ssl_intro.html"/>.
    </para>
   </tip>
   <sect3 xml:id="sec-apache2-ssl-certificate-dummy">
    <title>Creating a <quote>Dummy</quote> Certificate</title>
    <para>
     To generate a dummy certificate, call the script
     <command>/usr/bin/gensslcert</command>. It creates or overwrites the files
     listed below. Use <command>gensslcert</command>'s optional switches to
     fine-tune the certificate. Call <command>/usr/bin/gensslcert </command>
     <option>-h</option> for more information.
    </para>
    <itemizedlist mark="bullet" spacing="normal">
     <listitem>
      <para>
       <filename>/etc/apache2/ssl.crt/ca.crt</filename>
      </para>
     </listitem>
     <listitem>
      <para>
       <filename>/etc/apache2/ssl.crt/server.crt</filename>
      </para>
     </listitem>
     <listitem>
      <para>
       <filename>/etc/apache2/ssl.key/server.key</filename>
      </para>
     </listitem>
     <listitem>
      <para>
       <filename>/etc/apache2/ssl.csr/server.csr</filename>
      </para>
     </listitem>
    </itemizedlist>
    <para>
     A copy of <filename>ca.crt</filename> is also placed at
     <filename>/srv/www/htdocs/CA.crt</filename> for download.
    </para>
    <important>
     <title>For Testing Purposes Only</title>
     <para>
      A dummy certificate should never be used on a production system. Only use
      it for testing purposes.
     </para>
    </important>
   </sect3>
   <sect3 xml:id="sec-apache2-ssl-certificate-custom">
    <title>Creating a Self-Signed Certificate</title>
    <para>
     If you are setting up a secure Web server for an intranet or for a defined
     circle of users, it is probably sufficient if you sign a certificate with
     your own certificate authority (CA). Note that visitors to such a site
     will see a warning like <quote>this is an untrusted site</quote>, as Web
     browsers do not recognize self-signed certificates.
    </para>
    <important>
     <title>Self-Signed Certificates</title>
     <para>
      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 for a public shop, for example.
     </para>
    </important>
    <para>
     First you need to generate a certificate signing request (CSR). You are
     going to use <command>openssl</command>, with <literal>PEM</literal> as
     the certificate format. During this step, you will be asked for a
     passphrase, and to answer several questions. Remember the passphrase you
     enter as you will need it in the future.
    </para>
<screen>sudo openssl req -new &gt; new.cert.csr
Generating a 1024 bit RSA private key
..++++++
.........++++++
writing new private key to 'privkey.pem'
Enter PEM pass phrase:<co xml:id="co-ssl-self-pass1"/>
Verifying - Enter PEM pass phrase:<co xml:id="co-ssl-self-pass2"/>
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:<co xml:id="co-ssl-self-country"/>
State or Province Name (full name) [Some-State]:<co xml:id="co-ssl-self-state"/>
Locality Name (eg, city) []:<co xml:id="co-ssl-self-city"/>
Organization Name (eg, company) [Internet Widgits Pty Ltd]:<co xml:id="co-ssl-self-org"/>
Organizational Unit Name (eg, section) []:<co xml:id="co-ssl-self-uname"/>
Common Name (for example server FQDN, or YOUR name) []:<co xml:id="co-ssl-self-cname"/>
Email Address []:<co xml:id="co-ssl-self-email"/>

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:<co xml:id="co-ssl-self-challenge"/>
An optional company name []:<co xml:id="co-ssl-self-optional"/></screen>
    <calloutlist>
     <callout arearefs="co-ssl-self-pass1">
      <para>
       Fill in your passphrase,
      </para>
     </callout>
     <callout arearefs="co-ssl-self-pass2">
      <para>
       ...fill it in once more (and remember it).
      </para>
     </callout>
     <callout arearefs="co-ssl-self-country">
      <para>
       Fill in your 2 letter country code, such as <literal>GB</literal> or
       <literal>CZ</literal>.
      </para>
     </callout>
     <callout arearefs="co-ssl-self-state">
      <para>
       Fill in the name of the state where you live.
      </para>
     </callout>
     <callout arearefs="co-ssl-self-city">
      <para>
       Fill in the city name, such as <literal>Prague</literal>.
      </para>
     </callout>
     <callout arearefs="co-ssl-self-org">
      <para>
       Fill in the name of the organization you work for.
      </para>
     </callout>
     <callout arearefs="co-ssl-self-uname">
      <para>
       Fill in your organization unit, or leave blank if you have none.
      </para>
     </callout>
     <callout arearefs="co-ssl-self-cname">
      <para>
       Fill in either the domain name of the server, or your first and last
       name.
      </para>
     </callout>
     <callout arearefs="co-ssl-self-email">
      <para>
       Fill in your work e-mail address.
      </para>
     </callout>
     <callout arearefs="co-ssl-self-challenge">
      <para>
       Leave the challenge password empty, otherwise you will need to enter it
       every time you restart the Apache Web server.
      </para>
     </callout>
     <callout arearefs="co-ssl-self-optional">
      <para>
       Fill in the optional company name, or leave blank.
      </para>
     </callout>
    </calloutlist>
    <para>
     Now you can generate the certificate. You are going to use
     <command>openssl</command> again, and the format of the certificate is the
     default <literal>PEM</literal>.
    </para>
    <procedure>
     <title>Generating the Certificate</title>
     <step>
      <para>
       Export the private part of the key to <filename>new.cert.key</filename>.
       You will be prompted for the passphrase you entered when creating the
       certificate signing request (CSR).
      </para>
<screen>sudo openssl rsa -in privkey.pem -out new.cert.key</screen>
     </step>
     <step>
      <para>
       Generate the public part of the certificate according to the information
       you filled out in the signing request. The <option>-days</option> option
       specifies the length of time before the certificate expires. You can
       revoke a certificate, or replace one before it expires.
      </para>
<screen>sudo openssl x509 -in new.cert.csr -out new.cert.cert -req \
-signkey new.cert.key -days 365</screen>
     </step>
     <step>
      <para>
       Copy the certificate files to the relevant directories, so that the
       Apache server can read them. Make sure that the private key
       <filename>/etc/apache2/ssl.key/server.key</filename> is not
       world-readable, while the public PEM certificate
       <filename>/etc/apache2/ssl.crt/server.crt</filename> is.
      </para>
<screen>sudo cp new.cert.cert /etc/apache2/ssl.crt/server.crt
sudo cp new.cert.key /etc/apache2/ssl.key/server.key</screen>
     </step>
    </procedure>
    <tip>
     <title>Public Certificate Location</title>
     <para>
      The last step is to copy the public certificate file from
      <filename>/etc/apache2/ssl.crt/server.crt</filename> to a location where
      your users can access it 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.
     </para>
    </tip>
   </sect3>
   <sect3 xml:id="sec-apache2-ssl-certificate-official">
    <title>Getting an Officially Signed Certificate</title>
    <para>
     There are several 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
     an officially signed certificate.  A list of the most used Certificate
     Authorities (CAs) is available at <link xlink:href="https://en.wikipedia.org/wiki/Certificate_authority#Providers"/>.
    </para>
    <para>
     When requesting an officially signed certificate, you do not send a
     certificate to the CA. Instead, issue a Certificate Signing Request
<!-- 2015-08-24, tbazant: replacing CA.sh with openssl
     (http://doccomments.provo.novell.com/comments/28367)

     (CSR). To create a CSR, call the script
     <command>/usr/share/ssl/misc/CA.sh -newreq</command>.

     -->
     (CSR). To create a CSR, run the following command:
    </para>
<screen>openssl req -new -newkey rsa:2048 -nodes -keyout newkey.pem -out newreq.pem</screen>
    <para>
<!-- First the script asks for a password with which the CSR should be
     encrypted. -->
     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&mdash;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 <quote>.</quote>. Common
     name is the name of the CA itself&mdash;choose a significant name, such as
     <replaceable>My company</replaceable> CA. Last, a challenge password and
     an alternative company name must be entered.
    </para>
    <para>
     Find the CSR in the directory from which you called the script. The file
     is named <filename>newreq.pem</filename>.
    </para>
   </sect3>
  </sect2>

  <sect2 xml:id="sec-apache2-ssl-configuration">
   <title>Configuring Apache with SSL</title>
   <para>
    The default port for SSL and TLS requests on the Web server side is 443.
    There is no conflict between a <quote>regular</quote> 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.
   </para>
   <important>
    <title>Firewall Configuration</title>
    <para>
     Do not forget to open the firewall for SSL-enabled Apache on port 443.
     This can be done with &yast; as described in
     <xref linkend="sec-security-firewall-SuSE-yast"/>.
    </para>
   </important>
   <para>
    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: <command>a2enmod ssl</command>. To finally enable SSL, the server
    needs to be started with the flag <quote>SSL</quote>. To do so, call
    <command>a2enflag SSL</command> (case-sensitive!).  If you have chosen to
    encrypt your server certificate with a password, you should also increase
    the value for <systemitem>APACHE_TIMEOUT</systemitem> in
    <filename>/etc/sysconfig/apache2</filename>, 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.
   </para>
   <para>
    The virtual host configuration directory contains a template
    <filename>/etc/apache2/vhosts.d/vhost-ssl.template</filename> with
    SSL-specific directives that are extensively documented. Refer to
    <xref linkend="sec-apache2-configuration-manually-vhost"/> for the general
    virtual host configuration.
   </para>
   <para>
    To get started, copy the template to
    <filename>/etc/apache2/vhosts.d/<replaceable>MYSSL-HOST</replaceable>.conf</filename>
    and edit it. Adjusting the values for the following directives should be
    sufficient:
   </para>
   <itemizedlist mark="bullet" spacing="normal">
    <listitem>
     <para>
      <systemitem>DocumentRoot</systemitem>
     </para>
    </listitem>
    <listitem>
     <para>
      <systemitem>ServerName</systemitem>
     </para>
    </listitem>
    <listitem>
     <para>
      <systemitem>ServerAdmin</systemitem>
     </para>
    </listitem>
    <listitem>
     <para>
      <systemitem>ErrorLog</systemitem>
     </para>
    </listitem>
    <listitem>
     <para>
      <systemitem>TransferLog</systemitem>
     </para>
    </listitem>
   </itemizedlist>
   <sect3 xml:id="sec-apache2-ssl-configuration-name-based">
    <title>Name-Based Virtual Hosts and SSL</title>
    <para>
     By default it is not possible to run multiple SSL-enabled virtual hosts on
     a server with only one IP address. Name-based virtual hosting requires
     that Apache knows which server name has been requested. The problem with
     SSL connections is, that such a request can only be read after the SSL
     connection has already been established (by using the default virtual
     host). As a result, users will receive a warning message stating that the
     certificate does not match the server name.
    </para>
    <para>
     &productname; comes with an extension to the SSL protocol called Server
     Name Indication (SNI) addresses this issue by sending the name of the
     virtual domain as part of the SSL negotiation. This enables the server to
     <quote>switch</quote> to the correct virtual domain early and present the
     browser the correct certificate.
    </para>
    <para>
     SNI is enabled by default on &productname;. To enable Name-Based Virtual
     Hosts for SSL, configure the server as described in
     <xref linkend="sec-apache2-configuration-manually-vhost-named-vhosts"/>
     (note that you need to use port <literal>443</literal> rather than port
     <literal>80</literal> with SSL).
    </para>
    <important>
     <title>SNI Browser Support</title>
     <para>
      SNI must also be supported on the client side. However, SNI is
      supported by most browsers, except for certain older browsers. For more
      information, see
      <link xlink:href="https://en.wikipedia.org/wiki/Server_Name_Indication#Support"/>.
     </para>
     <para>
      To configure handling of non-SNI capable browsers, use the directive
      <systemitem>SSLStrictSNIVHostCheck</systemitem>. When set to
      <literal>on</literal> in the server configuration, non-SNI capable
      browser will be rejected for all virtual hosts. When set to
      <literal>on</literal> within a <systemitem>VirtualHost</systemitem>
      directive, access to this particular host will be rejected.
     </para>
     <para>
      When set to <literal>off</literal> in the server configuration, the
      server will behave as if not having SNI support. SSL requests will be
      handled by the <emphasis>first</emphasis> virtual host defined (for port
      443).
     </para>
    </important>
   </sect3>
  </sect2>
 </sect1>
 <sect1 xml:id="sec-apache2-multiple-instances">
  <title>Running Multiple Apache Instances on the Same Server</title>

  <para>
   As of &productnamereg; <phrase os="sles;sled">12 SP1</phrase><phrase os="osuse">42.1</phrase>, you can run multiple Apache instances on the same
   server. This has several advantages over running multiple virtual hosts (see
   <xref linkend="sec-apache2-configuration-manually-vhost"/>):
  </para>

  <itemizedlist>
   <listitem>
    <para>
     When a virtual host needs to be disabled for some time, you need to change
     the Web server configuration and restart it so that the change takes
     effect.
    </para>
   </listitem>
   <listitem>
    <para>
     In case of problems with one virtual host, you need to restart all of
     them.
    </para>
   </listitem>
  </itemizedlist>

  <para>
   You can run the default Apache instance as usual:
  </para>

<screen>sytemctl start apache2</screen>

  <para>
   It reads the default <filename>/etc/sysconfig/apache2</filename> file. If
   the file is not present, or it is present but it does not set the
   <systemitem>APACHE_HTTPD_CONF</systemitem> variable, it reads
   <filename>/etc/apache2/httpd.conf</filename>.
  </para>

  <para>
   To activate another Apache instance, run:
  </para>

<screen>systemctl start apache2@<replaceable>INSTANCE_NAME</replaceable></screen>

  <para>
   For example:
  </para>

<screen>systemctl start apache2@example_web.org</screen>

  <para>
   By default, the instance uses
   <filename>/etc/apache2@example_web.org/httpd.conf</filename> as a main
   configuration file, which can be overwritten by setting
   <systemitem>APACHE_HTTPD_CONF</systemitem> in
   <filename>/etc/sysconfig/apache2@example_web.org</filename>.
  </para>

  <para>
   An example to set up an additional instance of Apache follows. Note that you
   need to execute all the commands as &rootuser;.
  </para>

  <procedure>
   <title>Configuring an Additional Apache Instance</title>
   <step>
    <para>
     Create a new configuration file based on
     <filename>/etc/sysconfig/apache2</filename>, for example
     <filename>/etc/sysconfig/apache2@example_web.org</filename>:
    </para>
<screen>cp /etc/sysconfig/apache2 /etc/sysconfig/apache2@example_web.org</screen>
   </step>
   <step>
    <para>
     Edit the file <filename>/etc/sysconfig/apache2@example_web.org</filename>
     and change the line containing
    </para>
<screen>APACHE_HTTPD_CONF</screen>
    <para>
     to
    </para>
<screen>APACHE_HTTPD_CONF="/etc/apache2/httpd@example_web.org.conf"</screen>
   </step>
   <step>
    <para>
     Create the file
     <filename>/etc/apache2/httpd@example_web.org.conf</filename> based on
     <filename>/etc/apache2/httpd.conf</filename>.
    </para>
<screen>cp /etc/apache2/httpd.conf /etc/apache2/httpd@example_web.org.conf</screen>
   </step>
   <step>
    <para>
     Edit <filename>/etc/apache2/httpd@example_web.org.conf</filename> and
     change
    </para>
<screen>Include /etc/apache2/listen.conf</screen>
    <para>
     to
    </para>
<screen>Include /etc/apache2/listen@example_web.org.conf</screen>
    <para>
     Review all the directives and change them to fit your needs. You will
     probably want to change
    </para>
<screen>Include /etc/apache2/global.conf</screen>
    <para>
     and create new <filename>global@example_web.org.conf</filename> for each
     instance. We suggest to change
    </para>
<screen>ErrorLog /var/log/apache2/error_log</screen>
    <para>
     to
    </para>
<screen>ErrorLog /var/log/apache2/error@example_web.org_log</screen>
    <para>
     to have separate logs for each instance.
    </para>
   </step>
   <step>
    <para>
     Create <filename>/etc/apache2/listen@example_web.org.conf</filename> based
     on <filename>/etc/apache2/listen.conf</filename>.
    </para>
<screen>cp /etc/apache2/listen.conf /etc/apache2/listen@example_web.org.conf</screen>
   </step>
   <step>
    <para>
     Edit <filename>/etc/apache2/listen@example_web.org.conf</filename> and
     change
    </para>
<screen>Listen 80</screen>
    <para>
     to the port number you want the new instance to run on, for example 82:
    </para>
<screen>Listen 82</screen>
    <para>
     To run the new Apache instance over a secured protocol (see
     <xref linkend="sec-apache2-ssl"/>), change also the line
    </para>
<screen>Listen 443</screen>
    <para>
     for example to
    </para>
<screen>Listen 445</screen>
   </step>
   <step>
    <para>
     Start the new Apache instance:
    </para>
<screen>systemctl start apache2@example_web.org</screen>
   </step>
   <step>
    <para>
     Check if the server is running by pointing your Web browser at
     <literal>http://server_name:82</literal>. If you previously changed the
     name of the error log file for the new instance, you can check it:
    </para>
<screen>tail -f /var/log/apache2/error@example_web.org_log</screen>
   </step>
  </procedure>

  <para>
   Here are several points to consider when setting up more Apache instances on
   the same server:
  </para>

  <itemizedlist>
   <listitem>
    <para>
     The file
     <filename>/etc/sysconfig/apache2@<replaceable>INSTANCE_NAME</replaceable></filename>
     can include the same variables as
     <filename>/etc/sysconfig/apache2</filename>, including module loading and
     MPM setting.
    </para>
   </listitem>
   <listitem>
    <para>
     The default Apache instance does not need to be running while other
     instances run.
    </para>
   </listitem>
   <listitem>
    <para>
     The Apache helper utilities <command>a2enmod</command>,
     <command>a2dismod</command> and <command>apachectl</command> operate on
     the default Apache instance if not specified otherwise with the
     <systemitem>HTTPD_INSTANCE</systemitem> environment variable. The
     following example
    </para>
<screen>export HTTPD_INSTANCE=example_web.org
a2enmod access_compat
a2enmod status
apachectl start</screen>
    <para>
     will add <systemitem>access_compat</systemitem> and
     <systemitem>status</systemitem> modules to the
     <systemitem>APACHE_MODULES</systemitem> variable of
     <filename>/etc/sysconfig/apache2@example_web.org</filename>, and then
     start the <literal>example_web.org</literal> instance.
    </para>
   </listitem>
  </itemizedlist>
 </sect1>
 <sect1 xml:id="sec-apache2-security">
  <title>Avoiding Security Problems</title>

  <para>
   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.
  </para>

  <sect2 xml:id="sec-apache2-security-up-to-date">
   <title>Up-to-Date Software</title>
   <para>
    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 when possible. The &suse;
    security announcements are available from the following locations:
   </para>
   <itemizedlist mark="bullet" spacing="normal">
    <listitem>
     <formalpara>
      <title>Web Page</title>
      <para>
       <link xlink:href="https://www.suse.com/support/security/"/>
      </para>
     </formalpara>
    </listitem>
    <listitem>
     <formalpara>
      <title>Mailing List Archive</title>
      <para>
       <link xlink:href="https://lists.opensuse.org/opensuse-security-announce/"/>
      </para>
     </formalpara>
    </listitem>
    <listitem>
     <formalpara>
      <title>List of Security Announcements</title>
      <para>
       <link xlink:href="https://www.suse.com/support/update/"/>
      </para>
     </formalpara>
    </listitem>
   </itemizedlist>
  </sect2>

  <sect2 xml:id="sec-apache2-security-permissions">
   <title>DocumentRoot Permissions</title>
   <para>
    By default in &productname;, the <systemitem>DocumentRoot</systemitem>
    directory <filename>/srv/www/htdocs</filename> and the CGI directory
    <filename>/srv/www/cgi-bin</filename> belong to the user and group
    <systemitem>root</systemitem>. You should not change these permissions. If
    the directories are writable for all, any user can place files into them.
    These files might then be executed by Apache with the permissions of
    <systemitem>wwwrun</systemitem>, which may give the user unintended access
    to file system resources. Use subdirectories of
    <filename>/srv/www</filename> to place the
    <systemitem>DocumentRoot</systemitem> and CGI directories for your virtual
    hosts and make sure that directories and files belong to user and group
    <systemitem class="username">root</systemitem>.
   </para>
  </sect2>

  <sect2 xml:id="sec-apache2-security-filesystem">
   <title>File System Access</title>
   <para>
    By default, access to the whole file system is denied in
    <filename>/etc/apache2/httpd.conf</filename>. You should never overwrite
    these directives, but specifically enable access to all directories Apache
    should be able to read. For details, see
    <xref linkend="sec-apache2-configuration-manually-vhost-basic-configuration"/>.
    In doing so, ensure that no critical files, such as password or system
    configuration files, can be read from the outside.
   </para>
  </sect2>

  <sect2 xml:id="sec-apache2-security-cgi">
   <title>CGI Scripts</title>
   <para>
    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&mdash;allowing
    users to run their own scripts is generally not a good idea. It is also
    recommended to do security audits for all scripts.
   </para>
   <para>
    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
    <systemitem>ScriptAlias</systemitem> and <systemitem>Option
    ExecCGI</systemitem> are used for configuration. The &productname; default
    configuration does not allow execution of CGI scripts from everywhere.
   </para>
   <para>
    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.
   </para>
  </sect2>

  <sect2 xml:id="sec-apache2-security-users">
   <title>User Directories</title>
   <para>
    When enabling user directories (with <systemitem>mod_userdir</systemitem>
    or <systemitem>mod_rewrite</systemitem>) you should strongly consider not
    allowing <filename>.htaccess</filename> files, which would allow users to
    overwrite security settings. At least you should limit the user's
    engagement by using the directive <systemitem>AllowOverRide</systemitem>.
    In &productname;, <filename>.htaccess</filename> files are enabled by
    default, but the user is not allowed to overwrite any
    <systemitem>Option</systemitem> directives when using
    <systemitem>mod_userdir</systemitem> (see the
    <filename>/etc/apache2/mod_userdir.conf</filename> configuration file).
   </para>
  </sect2>
 </sect1>
 <sect1 xml:id="sec-apache2-troubleeshooting">
  <title>Troubleshooting</title>

  <para>
   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:
  </para>

  <variablelist>
   <varlistentry>
    <term>Output of the <systemitem class="service">apache2.service</systemitem>
     subcommand:</term>
    <listitem>
     <para>
      Instead of starting and stopping the Web server with the binary
      <filename>/usr/sbin/apache2ctl</filename>, rather use the
      <command>systemctl</command> commands instead (described in <xref linkend="sec-apache2-start-stop"/>). <command>systemctl status
      apache2</command> is verbose about errors, and it even provides tips and
      hints for fixing configuration errors.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Log Files and Verbosity</term>
    <listitem>
     <para>
      In case of both fatal and nonfatal errors, check the Apache log files for
      causes, mainly the error log file located at
      <filename>/var/log/apache2/error_log</filename> by default. Additionally,
      you can control the verbosity of the logged messages with the
      <systemitem>LogLevel</systemitem> directive if more detail is needed in
      the log files.
     </para>
     <tip>
      <title>A Simple Test</title>
      <para>
       Watch the Apache log messages with the command <command>tail -F
       /var/log/apache2/<replaceable>MY_ERROR_LOG</replaceable></command>.
       Then run
       <command>systemctl restart apache2</command>. Now, try to connect with a
       browser and check the output.
      </para>
     </tip>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term>Firewall and Ports</term>
    <listitem>
     <para>
      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
      <xref linkend="sec-apache2-configuration-yast"/>). If you are configuring
      Apache manually, open firewall ports for HTTP and HTTPS via &yast;'s
      firewall module.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

  <para>
   If the error cannot be tracked down with any of these, check the online
   Apache bug database at
   <link xlink:href="http://httpd.apache.org/bug_report.html"/>. Additionally,
   the Apache user community can be reached via a mailing list available at
   <link xlink:href="http://httpd.apache.org/userslist.html"/>.
  </para>
 </sect1>
 <sect1 xml:id="sec-apache2-more-information">
  <title>For More Information</title>

  <para>
   The package <systemitem>apache2-doc</systemitem> contains the complete
   Apache manual in various localizations for local installation and reference.
   It is not installed by default&mdash;the quickest way to install it is to
   use the command <command>zypper in apache2-doc</command>. having been
   installed, the Apache manual is available at
   <uri>http://localhost/manual/</uri>. You may also access it on the
   Web at <link xlink:href="https://httpd.apache.org/docs/2.4/"/>. SUSE-specific
   configuration hints are available in the directory
   <filename>/usr/share/doc/packages/apache2/README.*</filename>.
  </para>

  <sect2 xml:id="sec-apache2-more-information-apache22">
   <title>Apache 2.4</title>
   <para>
    For a list of new features in Apache 2.4, refer to
    <link xlink:href="http://httpd.apache.org/docs/2.4/new_features_2_4.html"/>.
    Information about upgrading from version 2.2 to 2.4 is available at
    <link xlink:href="http://httpd.apache.org/docs-2.4/upgrading.html"/>.
   </para>
  </sect2>

  <sect2 xml:id="sec-apache2-more-information-modules">
   <title>Apache Modules</title>
   <para>
    More information about external Apache modules that are briefly described
    in <xref linkend="sec-apache2-modules-external"/> is available at the
    following locations:
   </para>
   <variablelist>
    <varlistentry>
     <term><systemitem>mod_apparmor</systemitem>
     </term>
     <listitem>
      <para>
       <link xlink:href="https://en.opensuse.org/SDB:AppArmor"/>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_auth_kerb</systemitem>
     </term>
     <listitem>
      <para>
       <link xlink:href="http://modauthkerb.sourceforge.net/"/>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_perl</systemitem>
     </term>
     <listitem>
      <para>
       <link xlink:href="http://perl.apache.org/"/>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_php5</systemitem>
     </term>
     <listitem>
      <para>
       <link xlink:href="http://www.php.net/manual/en/install.unix.apache2.php"/>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_python</systemitem>
     </term>
     <listitem>
      <para>
       <link xlink:href="http://www.modpython.org/"/>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>mod_security</systemitem>
     </term>
     <listitem>
      <para>
       <link xlink:href="http://modsecurity.org/"/>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </sect2>

  <sect2 xml:id="sec-apache2-more-information-cgi">
   <title>Development</title>
   <para>
    More information about developing Apache modules or about getting involved
    in the Apache Web server project are available at the following locations:
   </para>
   <variablelist>
    <varlistentry>
     <term>Apache Developer Information</term>
     <listitem>
      <para>
       <link xlink:href="http://httpd.apache.org/dev/"/>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term>Apache Developer Documentation</term>
     <listitem>
      <para>
       <link xlink:href="http://httpd.apache.org/docs/2.4/developer/"/>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </sect2>

  <sect2 xml:id="sec-apache2-more-information-miscellaneous-sources" os="sles;sled">
   <title>Miscellaneous Sources</title>
   <para>
    If you experience difficulties specific to Apache in &productname;, take a
    look at the Technical Information Search at
    <link xlink:href="https://www.suse.com/support"/>. The history of Apache is
    provided at <link xlink:href="https://httpd.apache.org/ABOUT_APACHE.html"/>.
    This page also explains why the server is called Apache.
   </para>
  </sect2>
 </sect1>
</chapter>