apache2_yast_i.xml

<?xml version="1.0"?>
<!DOCTYPE sect2
[
  <!ENTITY % entities SYSTEM "generic-entities.ent">
    %entities;
]>
<sect2 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="sec-apache2-configuration-yast">
 <title>Configuring Apache with &yast;</title>
 <info>
  <meta name="description">Learn how to configure your Web server using YaST by selecting Network Services HTTP Server and following the HTTP Server Wizard's five-step process</meta>
  <dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
   <dm:bugtracker/>
   <dm:translation>yes</dm:translation>
  </dm:docmanager>
 </info>
 <para>
  To configure your Web server with &yast;, start &yast; and select
  <menuchoice> <guimenu>Network Services</guimenu> <guimenu>HTTP
  Server</guimenu> </menuchoice>. When starting the module for the first time,
  the <guimenu>HTTP Server Wizard</guimenu> starts, prompting you to make a few
  basic decisions concerning administration of the server. After having
  finished the wizard, the <guimenu>HTTP Server Configuration</guimenu> dialog
  starts each time you call the <guimenu>HTTP Server</guimenu> module. For more
  information, see
  <xref linkend="sec-apache2-configuration-yast-server-configuration"/>.
 </para>
 <sect3 xml:id="sec-apache2-configuration-yast-wizard">
  <title>HTTP Server Wizard</title>
  <para>
   The HTTP Server Wizard consists of five steps. In the last step of the
   dialog, you may enter the expert configuration mode to make even more
   specific settings.
  </para>
  <sect4 xml:id="sec-apache2-configuration-yast-wizard-network-device">
   <title>Network Device Selection</title>
   <para>
    Here, specify the network interfaces and ports Apache uses to listen for
    incoming requests. You can select any combination of existing network
    interfaces and their respective IP addresses. Ports from all three ranges
    (well-known ports, registered ports, and dynamic or private ports) that are
    not reserved by other services can be used. The default setting is to
    listen on all network interfaces (IP addresses) on port
    <systemitem>80</systemitem>.
   </para>
   <para>
    Check <guimenu>Open Port In Firewall</guimenu> to open the ports in the
    firewall that the Web server listens on. This is necessary to make the Web
    server available on the network, which can be a LAN, WAN, or the public
    Internet. Keeping the port closed is only useful in test situations where
    no external access to the Web server is necessary. If you have multiple
    network interfaces, click <guimenu>Firewall Details</guimenu> to specify on
    which interface(s) the port(s) should be opened.
   </para>
   <para>
    Click <guimenu>Next</guimenu> to continue with the configuration.
   </para>
  </sect4>
  <sect4 xml:id="sec-apache2-configuration-yast-wizard-modules">
   <title>Modules</title>
   <para>
    The <guimenu>Modules</guimenu> configuration option allows for the
    activation or deactivation of the script languages that the Web server
    should support. For the activation or deactivation of other modules, refer
    to
    <xref linkend="sec-apache2-configuration-yast-server-configuration-modules"/>.
    Click <guimenu>Next</guimenu> to advance to the next dialog.
   </para>
  </sect4>
  <sect4 xml:id="sec-apache2-configuration-yast-wizard-default-host">
   <title>Default Host</title>
   <para>
    This option pertains to the default Web server. As explained in
    <xref linkend="sec-apache2-configuration-manually-vhost"/>, Apache can
    serve multiple virtual hosts from a single physical machine. The first
    declared virtual host in the configuration file is commonly called the
    <emphasis>default host</emphasis>. Each virtual host inherits the default
    host's configuration.
   </para>
   <para>
    To edit the host settings (also called <emphasis>directives</emphasis>),
    select the appropriate entry in the table then click
    <guimenu>Edit</guimenu>. To add new directives, click
    <guimenu>Add</guimenu>. To delete a directive, select it and click
    <guimenu>Delete</guimenu>.
   </para>
   <figure xml:id="fig-apache2-configuration-yast-host">
    <title>HTTP Server Wizard: Default Host</title>
    <mediaobject>
     <imageobject role="fo">
      <imagedata width="75%" fileref="yast2_apache_wizard3.png"/>
     </imageobject>
     <imageobject role="html">
      <imagedata fileref="yast2_apache_wizard3.png"/>
     </imageobject>
    </mediaobject>
   </figure>
   <para>
    Here is list of the default settings of the server:
   </para>
   <variablelist>
    <varlistentry>
     <term><systemitem>Document Root</systemitem>
     </term>
     <listitem>
      <para>
       Path to the directory from which Apache serves files for this host.
       <filename>/srv/www/htdocs</filename> is the default location.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>Alias</systemitem>
     </term>
     <listitem>
      <para>
       Using <systemitem>Alias</systemitem> directives, URLs can be
       mapped to physical file system locations. This means that a certain path
       even outside the <literal>Document Root</literal> in the file system can
       be accessed via a URL aliasing that path.
      </para>
      <para>
       The default &productname; <systemitem>Alias</systemitem>
       <filename>/icons</filename> points to
       <filename>/usr/share/apache2/icons</filename> for the Apache icons
       displayed in the directory index view.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>ScriptAlias</systemitem>
     </term>
     <listitem>
      <para>
       Similar to the <systemitem>Alias</systemitem> directive, the
       <systemitem>ScriptAlias</systemitem> directive maps a URL to a file
       system location. The difference is that
       <systemitem>ScriptAlias</systemitem> designates the target directory as
       a CGI location, meaning that CGI scripts should be executed in that
       location.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>Directory</systemitem>
     </term>
     <listitem>
      <para>
       With <systemitem>Directory</systemitem> settings, you can enclose a
       group of configuration options that will only apply to the specified
       directory.
      </para>
      <para>
       Access and display options for the directories
       <filename>/srv/www/htdocs</filename>,
       <filename>/usr/share/apache2/icons</filename> and
       <filename>/srv/www/cgi-bin</filename> are configured here. It should not
       be necessary to change the defaults.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>Include</systemitem>
     </term>
     <listitem>
      <para>
       With include, additional configuration files can be specified. Two
       <systemitem>Include</systemitem> directives are already preconfigured:
       <filename>/etc/apache2/conf.d/</filename> is the directory containing
       the configuration files that come with external modules. With this
       directive, all files in this directory ending in
       <filename>.conf</filename> are included. With the second directive,
       <filename>/etc/apache2/conf.d/apache2-manual.conf</filename>, the
       <filename>apache2-manual</filename> configuration file is included.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>Server Name</systemitem>
     </term>
     <listitem>
      <para>
       This specifies the default URL used by clients to contact the Web
       server. Use a fully qualified domain name (FQDN) to reach the Web server
       at <literal>http://<replaceable>FQDN</replaceable>/</literal> or its IP
       address. You cannot choose an arbitrary name here&mdash;the server must
       be <quote>known</quote> under this name.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><systemitem>Server Administrator E-Mail</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>
<!--  This option is no longer available -->
<!--
    <varlistentry>
     <term><systemitem>Server Resolution</systemitem></term>
     <listitem>
      <para>
       This option refers to <xref
        linkend="sec-apache2-configuration-manually-vhost"/>.
       <guimenu>Determine Request Server by HTTP Headers</guimenu> lets
       a <literal>VirtualHost</literal> answer on a request to its
       server name (see <xref
        linkend="sec-apache2-configuration-manually-vhost-named-vhosts"/>).
       <guimenu>Determine Request Server by Server IP Address</guimenu>
       makes Apache select the requested host by the HTTP header
       information the client sends. See <xref
        linkend="sec-apache2-configuration-manually-vhost-ip-vhosts"/>
       for more details on IP-based virtual hosts.
      </para>
     </listitem>
    </varlistentry>
-->
   </variablelist>
   <para>
    After finishing with the <guimenu>Default Host</guimenu> step, click
    <guimenu>Next</guimenu> to continue with the configuration.
   </para>
  </sect4>
  <sect4 xml:id="sec-apache2-configuration-yast-wizard-virtual-hosts">
   <title>Virtual Hosts</title>
   <para>
    In this step, the wizard displays a list of already configured virtual
    hosts (see <xref linkend="sec-apache2-configuration-manually-vhost"/>). If
    you have not made manual changes prior to starting the &yast; HTTP wizard,
    no virtual host is present.
   </para>
   <para>
    To add a host, click <guimenu>Add</guimenu> to open a dialog in which to
    enter basic information about the host, such as <guimenu>Server
    Name</guimenu>, <guimenu>Server Contents Root</guimenu>
    (<systemitem>DocumentRoot</systemitem>), and the <guimenu>Administrator
    E-Mail</guimenu>. <guimenu>Server Resolution</guimenu> is used to determine
    how a host is identified (name based or IP based). Specify the name or IP
    address with <guimenu>Change Virtual Host ID</guimenu>
   </para>
   <para>
    Clicking <guimenu>Next</guimenu> advances to the second part of the virtual
    host configuration dialog.
   </para>
   <para>
    In part two of the virtual host configuration you can specify whether to
    enable CGI scripts and which directory to use for these scripts. It is also
    possible to enable SSL. If you do so, you must specify the path to the
    certificate as well. See <xref linkend="sec-apache2-ssl-configuration"/>
    for details on SSL and certificates. With the <guimenu>Directory
    Index</guimenu> option, you can specify which file to display when the
    client requests a directory (by default, <filename>index.html</filename>).
    Add one or more file names (space-separated) to change this.
    With <guimenu>Enable Public HTML</guimenu>, the content of the users public
    directories
    (<filename>~<replaceable>USER</replaceable>/public_html/</filename>) is
    made available on the server under
    <literal>http://www.&exampledomain;/~<replaceable>USER</replaceable></literal>.
   </para>
   <important>
    <title>Creating Virtual Hosts</title>
    <para>
     It is not possible to add virtual hosts at will. If using name-based
     virtual hosts, each host name must be resolved on the network. If using
     IP-based virtual hosts, you can assign only one host to each IP address
     available.
    </para>
   </important>
  </sect4>
  <sect4 xml:id="sec-apache2-configuration-yast-wizard-summary">
   <title>Summary</title>
   <para>
    This is the final step of the wizard. Here, determine how and when the
    Apache server is started: when booting or manually. Also see a short
    summary of the configuration made so far. If you are satisfied with your
    settings, click <guimenu>Finish</guimenu> to complete configuration. To change something, click <guimenu>Back</guimenu> until you have
    reached the desired dialog. Clicking <guimenu>HTTP Server Expert
    Configuration</guimenu> opens the dialog described in
    <xref linkend="sec-apache2-configuration-yast-server-configuration"/>.
   </para>
   <figure xml:id="fig-apache2-configuration-yast-summary">
    <title>HTTP Server Wizard: Summary</title>
    <mediaobject>
     <imageobject role="fo">
      <imagedata width="75%" fileref="yast2_apache_wizard5.png"/>
     </imageobject>
     <imageobject role="html">
      <imagedata fileref="yast2_apache_wizard5.png"/>
     </imageobject>
    </mediaobject>
   </figure>
  </sect4>
 </sect3>
 <sect3 xml:id="sec-apache2-configuration-yast-server-configuration">
  <title>HTTP Server Configuration</title>
  <para>
   The <guimenu>HTTP Server Configuration</guimenu> dialog also lets you make
   even more adjustments to the configuration than the wizard (which only runs
   if you configure your Web server for the first time). It consists of four
   tabs described in the following. No configuration option you change here is
   effective immediately&mdash;you always must confirm your changes with
   <guimenu>Finish</guimenu> to make them effective. Clicking
   <guimenu>Abort</guimenu> leaves the configuration module and discards your
   changes.
  </para>
  <sect4 xml:id="sec-apache2-configuration-yast-server-configuration-listen">
   <title>Listen Ports and Addresses</title>
   <para>
    In <guimenu>HTTP Service</guimenu>, select whether Apache should be running
    (<guimenu>Enabled</guimenu>) or stopped (<guimenu>Disabled</guimenu>). In
    <guimenu>Listen on Ports</guimenu>, <guimenu>Add</guimenu>,
    <guimenu>Edit</guimenu>, or <guimenu>Delete</guimenu> addresses and ports
    on which the server should be available. The default is to listen on all
    interfaces on port <literal>80</literal>. You should always check
    <guimenu>Open Port In Firewall</guimenu>, because otherwise the Web server
    is not reachable from outside. Keeping the port closed is only useful in
    test situations where no external access to the Web server is necessary. If
    you have multiple network interfaces, click <guimenu>Firewall
    Details</guimenu> to specify on which interface(s) the port(s) should be
    opened.
   </para>
   <para>
    With <guimenu>Log Files</guimenu>, watch either the access log file or the
    error log file. This is useful if you want to test your configuration. The
    log file opens in a separate window from which you can also restart or
    reload the Web server. For details, see
    <xref linkend="sec-apache2-start-stop"/>. These commands are effective
    immediately and their log messages are also displayed immediately.
   </para>
   <figure xml:id="fig-apache2-configuration-yast-server-configuration-listen">
    <title>HTTP Server Configuration: Listen Ports and Addresses</title>
    <mediaobject>
     <imageobject role="fo">
      <imagedata width="75%" fileref="yast2_apache_config_listen.png"/>
     </imageobject>
     <imageobject role="html">
      <imagedata fileref="yast2_apache_config_listen.png"/>
     </imageobject>
    </mediaobject>
   </figure>
  </sect4>
  <sect4 xml:id="sec-apache2-configuration-yast-server-configuration-modules">
   <title>Server Modules</title>
   <para>
    You can change the status (enabled or disabled) of Apache2 modules by
    clicking <guimenu>Toggle Status</guimenu>. Click <guimenu>Add
    Module</guimenu> to add a new module that is already installed but not yet
    listed. Learn more about modules in <xref linkend="sec-apache2-modules"/>.
   </para>
   <figure xml:id="fig-apache2-configuration-yast-server-configuration-modules">
    <title>HTTP Server Configuration: Server Modules</title>
    <mediaobject>
     <imageobject role="fo">
      <imagedata width="75%" fileref="yast2_apache_config_modules.png"/>
     </imageobject>
     <imageobject role="html">
      <imagedata fileref="yast2_apache_config_modules.png"/>
     </imageobject>
    </mediaobject>
   </figure>
  </sect4>
  <sect4 xml:id="sec-apache2-configuration-yast-server-configuration-host">
   <title>Main Host or Hosts</title>
   <para>
    These dialogs are identical to the ones already described. Refer to
    <xref linkend="sec-apache2-configuration-yast-wizard-default-host"/> and
    <xref linkend="sec-apache2-configuration-yast-wizard-virtual-hosts"/>.
   </para>
  </sect4>
 </sect3>
</sect2>