<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<!-- $LastChangedRevision$ -->

<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->

<manualpage metafile="security_tips.xml.meta">
  <parentdocument href="./">Miscellaneous Documentation</parentdocument>

  <title>Security Tips</title>

  <summary>
    <p>Some hints and tips on security issues in setting up a web server.
    Some of the suggestions will be general, others specific to Apache.</p>
  </summary>

  <section id="uptodate"><title>Keep up to Date</title>

    <p>The Apache HTTP Server has a good record for security and a
    developer community highly concerned about security issues.  But
    it is inevitable that some problems -- small or large -- will be
    discovered in software after it is released.  For this reason, it
    is crucial to keep aware of updates to the software.  If you have
    obtained your version of the HTTP Server directly from Apache, we
    highly recommend you subscribe to the <a
    href="http://httpd.apache.org/lists.html#http-announce">Apache
    HTTP Server Announcements List</a> where you can keep informed of
    new releases and security updates.  Similar services are available
    from most third-party distributors of Apache software.</p>

    <p>Of course, most times that a web server is compromised, it is
    not because of problems in the HTTP Server code.  Rather, it comes
    from problems in add-on code, CGI scripts, or the underlying
    Operating System.  You must therefore stay aware of problems and
    updates with all the software on your system.</p>

  </section>

  <section id="dos">

    <title>Denial of Service (DoS) attacks</title>

    <p>All network servers can be subject to denial of service attacks
    that attempt to prevent responses to clients by tying up the
    resources of the server.  It is not possible to prevent such
    attacks entirely, but you can do certain things to mitigate the
    problems that they create.</p>

    <p>Often the most effective anti-DoS tool will be a firewall or
    other operating-system configurations.  For example, most
    firewalls can be configured to restrict the number of simultaneous
    connections from any individual IP address or network, thus
    preventing a range of simple attacks.  Of course this is no help
    against Distributed Denial of Service attacks (DDoS).</p>

    <p>There are also certain Apache HTTP Server configuration
    settings that can help mitigate problems:</p>

    <ul>
      <li>The <directive module="mod_reqtimeout">RequestReadTimeout</directive>
      directive allows to limit the time a client may take to send the
      request.</li>

      <li>The <directive module="core">TimeOut</directive> directive
      should be lowered on sites that are subject to DoS attacks.
      Setting this to as low as a few seconds may be appropriate.
      As <directive module="core">TimeOut</directive> is currently
      used for several different operations, setting it to a low value
      introduces problems with long running CGI scripts.</li>

      <li>The <directive module="core">KeepAliveTimeout</directive>
      directive may be also lowered on sites that are subject to DoS
      attacks.  Some sites even turn off the keepalives completely via
      <directive module="core">KeepAlive</directive>, which has of course
      other drawbacks on performance.</li>

      <li>The values of various timeout-related directives provided by
      other modules should be checked.</li>

      <li>The directives
      <directive module="core">LimitRequestBody</directive>,
      <directive module="core">LimitRequestFields</directive>,
      <directive module="core">LimitRequestFieldSize</directive>,
      <directive module="core">LimitRequestLine</directive>, and
      <directive module="core">LimitXMLRequestBody</directive>
      should be carefully configured to limit resource consumption
      triggered by client input.</li>

      <li>On operating systems that support it, make sure that you use
      the <directive module="core">AcceptFilter</directive> directive
      to offload part of the request processing to the operating
      system.  This is active by default in Apache httpd, but may
      require reconfiguration of your kernel.</li>

      <li>Tune the <directive
      module="mpm_common">MaxRequestWorkers</directive> directive to allow
      the server to handle the maximum number of simultaneous
      connections without running out of resources.  See also the <a
      href="perf-tuning.html">performance tuning
      documentation</a>.</li>

      <li>The use of a threaded <a href="../mpm.html">mpm</a> may
      allow you to handle more simultaneous connections, thereby
      mitigating DoS attacks.  Further, the 
      <module>event</module> mpm
      uses asynchronous processing to avoid devoting a thread to each
      connection. Due to the nature of the OpenSSL library the
      <module>event</module> mpm is currently incompatible with
      <module>mod_ssl</module> and other input filters. In these
      cases it falls back to the behaviour of the
      <module>worker</module> mpm.</li>

      <li>There are a number of third-party modules available through
      <a
      href="http://modules.apache.org/">http://modules.apache.org/</a>
      that can restrict certain client behaviors and thereby mitigate
      DoS problems.</li>

    </ul>

  </section>


  <section id="serverroot">

    <title>Permissions on ServerRoot Directories</title>

    <p>In typical operation, Apache is started by the root user, and it
    switches to the user defined by the <directive
    module="mod_unixd">User</directive> directive to serve hits. As is the
    case with any command that root executes, you must take care that it is
    protected from modification by non-root users. Not only must the files
    themselves be writeable only by root, but so must the directories, and
    parents of all directories. For example, if you choose to place
    ServerRoot in  <code>/usr/local/apache</code> then it is suggested that
    you create that directory as root, with commands like these:</p>

    <example>
      mkdir /usr/local/apache <br />
      cd /usr/local/apache <br />
      mkdir bin conf logs <br />
      chown 0 . bin conf logs <br />
      chgrp 0 . bin conf logs <br />
      chmod 755 . bin conf logs
    </example>

    <p>It is assumed that <code>/</code>, <code>/usr</code>, and
    <code>/usr/local</code> are only modifiable by root. When you install the
    <program>httpd</program> executable, you should ensure that it is
    similarly protected:</p>

    <example>
      cp httpd /usr/local/apache/bin <br />
      chown 0 /usr/local/apache/bin/httpd <br />
      chgrp 0 /usr/local/apache/bin/httpd <br />
      chmod 511 /usr/local/apache/bin/httpd
    </example>

    <p>You can create an htdocs subdirectory which is modifiable by other
    users -- since root never executes any files out of there, and shouldn't
    be creating files in there.</p>

    <p>If you allow non-root users to modify any files that root either
    executes or writes on then you open your system to root compromises.
    For example, someone could replace the <program>httpd</program> binary so
    that the next time you start it, it will execute some arbitrary code. If
    the logs directory is writeable (by a non-root user), someone could replace
    a log file with a symlink to some other system file, and then root
    might overwrite that file with arbitrary data. If the log files
    themselves are writeable (by a non-root user), then someone may be
    able to overwrite the log itself with bogus data.</p>

  </section>

  <section id="ssi">

    <title>Server Side Includes</title>

    <p>Server Side Includes (SSI) present a server administrator with
    several potential security risks.</p>

    <p>The first risk is the increased load on the server. All
    SSI-enabled files have to be parsed by Apache, whether or not
    there are any SSI directives included within the files. While this
    load increase is minor, in a shared server environment it can become
    significant.</p>

    <p>SSI files also pose the same risks that are associated with CGI
    scripts in general. Using the <code>exec cmd</code> element, SSI-enabled
    files can execute any CGI script or program under the permissions of the
    user and group Apache runs as, as configured in
    <code>httpd.conf</code>.</p>

    <p>There are ways to enhance the security of SSI files while still
    taking advantage of the benefits they provide.</p>

    <p>To isolate the damage a wayward SSI file can cause, a server
    administrator can enable <a href="../suexec.html">suexec</a> as
    described in the <a href="#cgi">CGI in General</a> section.</p>

    <p>Enabling SSI for files with <code>.html</code> or <code>.htm</code>
    extensions can be dangerous. This is especially true in a shared, or high
    traffic, server environment. SSI-enabled files should have a separate
    extension, such as the conventional <code>.shtml</code>. This helps keep
    server load at a minimum and allows for easier management of risk.</p>

    <p>Another solution is to disable the ability to run scripts and
    programs from SSI pages. To do this replace <code>Includes</code>
    with <code>IncludesNOEXEC</code> in the <directive
    module="core">Options</directive> directive.  Note that users may
    still use <code>&lt;--#include virtual="..." --&gt;</code> to execute CGI
    scripts if these scripts are in directories designated by a <directive
    module="mod_alias">ScriptAlias</directive> directive.</p>

  </section>

  <section id="cgi">

    <title>CGI in General</title>

    <p>First of all, you always have to remember that you must trust the
    writers of the CGI scripts/programs or your ability to spot potential
    security holes in CGI, whether they were deliberate or accidental. CGI
    scripts can run essentially arbitrary commands on your system with the
    permissions of the web server user and can therefore be extremely
    dangerous if they are not carefully checked.</p>

    <p>All the CGI scripts will run as the same user, so they have potential
    to conflict (accidentally or deliberately) with other scripts e.g. User
    A hates User B, so he writes a script to trash User B's CGI database. One
    program which can be used to allow scripts to run as different users is
    <a href="../suexec.html">suEXEC</a> which is included with Apache as of
    1.2 and is called from special hooks in the Apache server code. Another
    popular way of doing this is with
    <a href="http://cgiwrap.sourceforge.net/">CGIWrap</a>.</p>

  </section>

  <section id="nsaliasedcgi">

    <title>Non Script Aliased CGI</title>

    <p>Allowing users to execute CGI scripts in any directory should only be
    considered if:</p>

    <ul>
      <li>You trust your users not to write scripts which will deliberately
          or accidentally expose your system to an attack.</li>
      <li>You consider security at your site to be so feeble in other areas,
          as to make one more potential hole irrelevant.</li>
      <li>You have no users, and nobody ever visits your server.</li>
    </ul>

  </section>

  <section id="saliasedcgi">

    <title>Script Aliased CGI</title>

    <p>Limiting CGI to special directories gives the admin control over what
    goes into those directories. This is inevitably more secure than non
    script aliased CGI, but only if users with write access to the
    directories are trusted or the admin is willing to test each
    new CGI script/program for potential security holes.</p>

    <p>Most sites choose this option over the non script aliased CGI
    approach.</p>

  </section>

   <section id="dynamic">

  <title>Other sources of dynamic content</title>

  <p>Embedded scripting options which run as part of the server itself,
  such as <code>mod_php</code>, <code>mod_perl</code>, <code>mod_tcl</code>,
  and <code>mod_python</code>, run under the identity of the server itself
  (see the <directive module="mod_unixd">User</directive> directive), and
  therefore scripts executed by these engines potentially can access anything
  the server user can. Some scripting engines may provide restrictions, but
  it is better to be safe and assume not.</p>

  </section>
   <section id="dynamicsec">

  <title>Dynamic content security</title>

  <p>When setting up dynamic content, such as <code>mod_php</code>,
  <code>mod_perl</code> or <code>mod_python</code>, many security considerations
  get out of the scope of <code>httpd</code> itself, and you need to consult
  documentation from those modules. For example, PHP lets you setup <a
  href="http://www.php.net/manual/en/ini.sect.safe-mode.php">Safe Mode</a>,
  which is most usually disabled by default. Another example is <a
  href="http://www.hardened-php.net/suhosin/">Suhosin</a>, a PHP addon for more
  security. For more information about those, consult each project
  documentation.</p>

  <p>At the Apache level, a module named <a href="http://modsecurity.org/">mod_security</a>
  can be seen as a HTTP firewall and, provided you configure it finely enough,
  can help you enhance your dynamic content security.</p>

  </section>

  <section id="systemsettings">

    <title>Protecting System Settings</title>

    <p>To run a really tight ship, you'll want to stop users from setting
    up <code>.htaccess</code> files which can override security features
    you've configured. Here's one way to do it.</p>

    <p>In the server configuration file, put</p>

    <highlight language="config">
&lt;Directory "/"&gt;
    AllowOverride None
&lt;/Directory&gt;
    </highlight>

    <p>This prevents the use of <code>.htaccess</code> files in all
    directories apart from those specifically enabled.</p>

    <p>Note that this setting is the default since Apache 2.3.9.</p>

  </section>

  <section id="protectserverfiles">

    <title>Protect Server Files by Default</title>

    <p>One aspect of Apache which is occasionally misunderstood is the
    feature of default access. That is, unless you take steps to change it,
    if the server can find its way to a file through normal URL mapping
    rules, it can serve it to clients.</p>

    <p>For instance, consider the following example:</p>

    <example>
      # cd /; ln -s / public_html <br />
      Accessing <code>http://localhost/~root/</code>
    </example>

    <p>This would allow clients to walk through the entire filesystem. To
    work around this, add the following block to your server's
    configuration:</p>

    <highlight language="config">
&lt;Directory "/"&gt;
    Require all denied
&lt;/Directory&gt;
    </highlight>

    <p>This will forbid default access to filesystem locations. Add
    appropriate <directive module="core">Directory</directive> blocks to
    allow access only in those areas you wish. For example,</p>

    <highlight language="config">
&lt;Directory "/usr/users/*/public_html"&gt;
    Require all granted
&lt;/Directory&gt;
&lt;Directory "/usr/local/httpd"&gt;
    Require all granted
&lt;/Directory&gt;
    </highlight>

    <p>Pay particular attention to the interactions of <directive
    module="core">Location</directive> and <directive
    module="core">Directory</directive> directives; for instance, even
    if <code>&lt;Directory "/"&gt;</code> denies access, a <code>
    &lt;Location "/"&gt;</code> directive might overturn it.</p>

    <p>Also be wary of playing games with the <directive
    module="mod_userdir">UserDir</directive> directive; setting it to
    something like <code>./</code> would have the same effect, for root, as
    the first example above. We strongly
    recommend that you include the following line in your server
    configuration files:</p>

    <highlight language="config">UserDir disabled root</highlight>

  </section>

  <section id="watchyourlogs">

    <title>Watching Your Logs</title>

    <p>To keep up-to-date with what is actually going on against your server
    you have to check the <a href="../logs.html">Log Files</a>.  Even though
    the log files only reports what has already happened, they will give you
    some understanding of what attacks is thrown against the server and
    allow you to check if the necessary level of security is present.</p>

    <p>A couple of examples:</p>

    <example>
      grep -c "/jsp/source.jsp?/jsp/ /jsp/source.jsp??" access_log <br />
      grep "client denied" error_log | tail -n 10
    </example>

    <p>The first example will list the number of attacks trying to exploit the
    <a href="http://online.securityfocus.com/bid/4876/info/">Apache Tomcat
    Source.JSP Malformed Request Information Disclosure Vulnerability</a>,
    the second example will list the ten last denied clients, for example:</p>

    <example>
      [Thu Jul 11 17:18:39 2002] [error] [client foo.example.com] client denied
      by server configuration: /usr/local/apache/htdocs/.htpasswd
    </example>

    <p>As you can see, the log files only report what already has happened, so
    if the client had been able to access the <code>.htpasswd</code> file you
    would have seen something similar to:</p>

    <example>
      foo.example.com - - [12/Jul/2002:01:59:13 +0200] "GET /.htpasswd HTTP/1.1"
    </example>

    <p>in your <a href="../logs.html#accesslog">Access Log</a>. This means
    you probably commented out the following in your server configuration
    file:</p>

    <highlight language="config">
&lt;Files ".ht*"&gt;
    Require all denied
&lt;/Files&gt;
    </highlight>

  </section>

  <section id="merging">

    <title>Merging of configuration sections</title>

    <p> The merging of configuration sections is complicated and sometimes
    directive specific.  Always test your changes when creating dependencies
    on how directives are merged.</p>

    <p> For modules that don't implement any merging logic, such as 
    <directive>mod_access_compat</directive>, the behavior in later sections
    depends on whether the later section has any directives
    from the module.  The configuration is inherited until a change is made, 
    at which point the configuration is <em>replaced</em> and not merged.</p>
  </section>

</manualpage>
