source: server/major/apache.xml@ de2551f

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!-- <!ENTITY apache-download-http "http://www.apache.org/dist/httpd/httpd-&apache-version;.tar.bz2"> -->
  <!ENTITY apache-download-http "http://archive.apache.org/dist/httpd/httpd-&apache-version;.tar.bz2">
  <!ENTITY apache-download-ftp  "ftp://apache.mirrors.pair.com/httpd/httpd-&apache-version;.tar.bz2">
  <!ENTITY apache-md5sum        "3e98bcb14a7122c274d62419566431bb">
  <!ENTITY apache-size          "4.9 MB">
  <!ENTITY apache-buildsize     "83 MB">
  <!ENTITY apache-time          "2.1 SBU">
]>

<sect1 id="apache" xreflabel="Apache-&apache-version;">
  <?dbhtml filename="apache.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>Apache-&apache-version;</title>

  <indexterm zone="apache">
    <primary sortas="a-Apache">Apache</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Apache</title>

    <para>The <application>Apache</application> package contains an
    open-source HTTP server. It is useful for creating local intranet
    web sites or running huge web serving operations.</para>

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Download (HTTP): <ulink url="&apache-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&apache-download-ftp;"/></para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &apache-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &apache-size;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &apache-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &apache-time;</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing='compact'>
      <listitem>
        <para>Required patch: <ulink
        url="&patch-root;/httpd-&apache-version;-config-1.patch"/></para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Apache Dependencies</bridgehead>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional"><xref linkend="db"/>,
    <xref linkend="openssl"/>,
    <xref linkend="openldap"/>,
    <xref linkend="pcre"/>,
    <ulink url="http://apr.apache.org/">APR</ulink>,
    <ulink url="http://apr.apache.org/">APR-util</ulink>, and
    <ulink url="http://www.distcache.org/">distcache</ulink></para>

    <bridgehead renderas="sect4">Optional (Only if Using the Bundled
    APR-util)</bridgehead>
    <para role="optional"><!-- <xref linkend="pkgconfig"/>, -->
    <xref linkend="expat"/>,
    <!-- <xref linkend="gdbm"/>, -->
    <xref linkend="postgresql"/>, and
    <xref linkend="sqlite"/></para>

    <para>Though you can install APR and APR-util as separate components,
    it is recommended to use the bundled versions that come with the Apache
    HTTPD tarball.</para>

    <para condition="html" role="usernotes">User Notes:
    <ulink url="&blfs-wiki;/apache"/></para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of Apache</title>

    <para>For security reasons, running the server as an unprivileged user and
    group is strongly encouraged. Create the following group and user using the
    following commands
    (as <systemitem class="username">root</systemitem>):</para>

<screen role="root"><userinput>groupadd -g 25 apache &amp;&amp;
useradd -c "Apache Server" -d /dev/null -g apache \
        -s /bin/false -u 25 apache</userinput></screen>

    <note><para>The above command directs the <application>Apache</application>
    user's home directory to <filename>/dev/null</filename>.  This may not work
    for some add-ons such as <ulink
    url='http://www.viewvc.org/'><application>ViewVC</application></ulink>, a
    browser interface for CVS and Subversion version control repositories.
    See the User Notes for details for specific applications.</para></note>

    <para>The following patch modifies the layout of destination
    directories and among them, the build directory at
    <filename class="directory">/usr/lib/apache/build</filename>. This
    will allow the modules added to <application>Apache</application>
    to be configured without errors. Apply the patch:</para>

<screen><userinput>patch -Np1 -i ../httpd-&apache-version;-config-1.patch</userinput></screen>

    <note>
      <para>You may wish to review the output from
      <command>./configure --help</command> and include whatever parameters
      are necessary to the <command>configure</command> command below to build
      the modules required for your installation. There are as many as 62
      additional parameters you can add to the <command>configure</command>
      command to build additional modules. Some of the extra parameters which
      aren't described or mentioned in the <parameter>--help</parameter>
      information are listed in the <quote>Command Explanations</quote> section
      below.</para>

      <para>If you are using the bundled version of
      <application>APR-util</application> and you are going to install
      <application>Subversion</application> with
      <application>Berkeley DB</application> back-end support, ensure you use
      the parameters shown in the <quote>Command Explanations</quote> section
      below.</para>

      <para>While it is not built by default when using the following commands,
      the ISAPI DSO module can be created by adding the <option>--enable-isapi</option>
      option. Even the module will compile, install and load fine, the module is 
      <emphasis>only</emphasis> supported and functional in Win32
      environments.</para>
    </note>

    <para>Build and install <application>Apache</application> by running the
    following commands:</para>

<screen><userinput>./configure --enable-layout=FHS --enable-mods-shared=all &amp;&amp;
make</userinput></screen>

    <para>This package does not come with a test suite.</para>

    <para>Now, as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>make install &amp;&amp;
chown -v root:root /usr/lib/apache/httpd.exp \
    /usr/sbin/{apxs,apachectl,dbmmanage,envvars{,-std}} \
    /usr/share/man/man1/{dbmmanage,ht{dbm,digest,passwd}}.1 \
    /usr/share/man/man8/{ab,apachectl,apxs,htcacheclean,httpd}.8 \
    /usr/share/man/man8/{logresolve,rotatelogs,suexec}.8 &amp;&amp;
chown -v -R apache:apache /srv/www</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <!-- This is not required any longer. Finds and uses system installed
         version of Expat without any issues
    <para><option>-with-expat=/usr</option>: Uses the system installed
    <application>expat</application>. <emphasis role="strong">If you have
    installed  <application>expat</application> and do not use this switch, the
    <application>Apache</application> installation may overwrite some files
    from the <application>expat</application> installation.</emphasis></para>
    -->

    <para><parameter>--enable-mods-shared=all</parameter>: The modules
    should be compiled and used as Dynamic Shared Objects
    (DSOs) so they can be included and excluded from the
    server using the run-time configuration directives.</para>

    <para><option>--enable-ssl</option>: Use this parameter
    to create the <filename class="libraryfile">mod_ssl</filename>
    module and enable SSL support. This parameter is mentioned as one of many
    parameters which can be passed to the <command>configure</command> command
    to create additional DSO modules.</para>

    <para><option>--with-pcre</option>: Add this parameter to use the system
    installed version of the <application>PCRE</application> library.</para>

    <para><option>--with-z</option>: Add this parameter to use the system
    installed version of the <application>Zlib</application> library.</para>

    <para><option>--with-ldap</option>: This parameter is required if you
    passed the <option>--enable-authnz-ldap</option> or
    <option>--enable-ldap</option> options to <command>configure</command>
    and enabled the <application>OpenLDAP</application> modules.</para>

    <para><option>--with-dbm=db45 --with-berkeley-db</option>: Use these
    parameters if you require <application>Berkeley DB</application> support in
    the bundled version of <application>APR-util</application> (required for
    <application>Berkeley DB</application> back-end support in
    <application>Subversion</application>).</para>

    <para><command>chown root:root ...</command>: This command changes the
    ownership of some installed files, the result of building the package as
    a user other than <systemitem class="username">root</systemitem>.</para>

    <para><command>chown -R apache:apache /srv/www</command>: By default, the
    installation process installs files (documentation, error messages, default
    icons, etc.) with the ownership of the user that extracted the files from
    the tar file. If you want to change the ownership to another user, you
    should do so at this point. The only requirement is that the document
    directories need to be accessible by the <command>httpd</command> process
    with (r-x) permissions and files need to be readable (r--) by the
    <systemitem class="username">apache</systemitem> user.</para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring Apache</title>

    <sect3 id="apache-config">
      <title>Config Files</title>

      <para><filename>/etc/apache/*</filename></para>

      <indexterm zone="apache apache-config">
        <primary sortas="e-etc-apache">/etc/apache/*</primary>
      </indexterm>

      <indexterm zone="apache apache-config">
        <primary sortas="e-etc-apache-httpd.conf">/etc/apache/httpd.conf</primary>
      </indexterm>

    </sect3>

    <sect3>
      <title>Configuration Information</title>

      <para>The main configuration file is named
      <filename>/etc/apache/httpd.conf</filename>. Modify it so that the HTTP
      server runs as the dedicated user and group:</para>

<screen role="root"><userinput>sed -i -e "s/User daemon/User apache/" \
       -e "s/Group daemon/Group apache/" \
    /etc/apache/httpd.conf</userinput></screen>

      <para>See <ulink url="http://httpd.apache.org/docs-2.2/configuring.html"/>
      for detailed instructions on customizing your
      <application>Apache</application> HTTP server configuration file.</para>

<!--
      <para>There's a problem with the ISAPI DSO module caused from compiling
      with <application>GCC</application>-&gcc-version;. If you included the
      parameter to build the module, comment out the module's load command
      in the configuration file with the following command:</para>

<screen role="root"><userinput>sed -i "s/^LoadModule isapi_module/# &amp;/" \
    /etc/apache/httpd.conf</userinput></screen>
-->
    </sect3>

    <sect3  id="apache-init">
      <title>Boot Script</title>

      <para>If you want the <application>Apache</application> server to
      start automatically when the system is booted, install the
      <filename>/etc/rc.d/init.d/apache</filename> init script included
      in the <xref linkend="bootscripts"/> package.</para>

      <indexterm zone="apache apache-init">
        <primary sortas="f-apache">apache</primary>
      </indexterm>

<screen role="root"><userinput>make install-apache</userinput></screen>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>ab, apachectl, apr-config, apu-config, apxs, checkgid, dbmmanage,
        htdbm, htdigest, htpasswd, httpd, instdso.sh, logresolve, and
        rotatelogs</seg>
        <seg>libapr-1.{so,a}, libaprutil-1.{so,a}, and /usr/lib/apache/*.so</seg>
        <seg>/etc/apache, /srv/www, /usr/include/apache, /usr/lib/apache, and
        /var/log/apache</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="ab">
        <term><command>ab</command></term>
        <listitem>
          <para>is a tool for benchmarking your
          <application>Apache</application> HTTP server.</para>
          <indexterm zone="apache ab">
            <primary sortas="b-ab">ab</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="apachectl">
        <term><command>apachectl</command></term>
        <listitem>
          <para>is a front end to the <application>Apache</application>
          HTTP server which is designed to help the administrator
          control the functioning of the <application>Apache</application>
          httpd daemon.</para>
          <indexterm zone="apache apachectl">
            <primary sortas="b-apachectl">apachectl</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="apxs">
        <term><command>apxs</command></term>
        <listitem>
          <para>is a tool for building and installing extension modules for
          the <application>Apache</application> HTTP server.</para>
          <indexterm zone="apache apxs">
            <primary sortas="b-apxs">apxs</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="dbmmanage">
        <term><command>dbmmanage</command></term>
        <listitem>
          <para>is used to create and update the DBM format files used to store
          usernames and passwords for basic authentication of HTTP users.</para>
          <indexterm zone="apache dbmmanage">
            <primary sortas="b-dbmmanage">dbmmanage</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="htdigest">
        <term><command>htdigest</command></term>
        <listitem>
          <para>is used to create and update the flat-files used to store
          usernames, realms and passwords for digest authentication of
          HTTP users.</para>
          <indexterm zone="apache htdigest">
            <primary sortas="b-htdigest">htdigest</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="htpasswd">
        <term><command>htpasswd</command></term>
        <listitem>
          <para>is used to create and update the flat-files used to store
          usernames and passwords for basic authentication of HTTP users.</para>
          <indexterm zone="apache htpasswd">
            <primary sortas="b-htpasswd">htpasswd</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="httpd">
        <term><command>httpd</command></term>
        <listitem>
          <para>is the <application>Apache</application>
          HTTP server program.</para>
          <indexterm zone="apache httpd">
            <primary sortas="b-httpd">httpd</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="instdso.sh">
        <term><command>instdso.sh</command></term>
        <listitem>
          <para>is a script which installs <application>Apache</application>
          DSO modules.</para>
          <indexterm zone="apache instdso.sh">
            <primary sortas="b-instdso.sh">instdso.sh</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="logresolve">
        <term><command>logresolve</command></term>
        <listitem>
          <para>is a post-processing program to resolve IP-addresses
          in <application>Apache</application>'s access log files.</para>
          <indexterm zone="apache logresolve">
            <primary sortas="b-logresolve">logresolve</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="rotatelogs">
        <term><command>rotatelogs</command></term>
        <listitem>
          <para>is a simple program for use in conjunction with
          <application>Apache</application>'s piped log file feature.</para>
          <indexterm zone="apache rotatelogs">
            <primary sortas="b-rotatelogs">rotatelogs</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>