home *** CD-ROM | disk | FTP | other *** search
/ PC World 2003 November / PCWorld_2003-11_cd.bin / Komunik / apache / apache_2.0.47-win32-x86-no_ssl.msi / Data.Cab / F250779_htaccess.xml < prev    next >
Extensible Markup Language  |  2003-04-15  |  15KB  |  360 lines
  1. <?xml version='1.0' encoding='UTF-8' ?>
  2. <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
  3. <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
  4. <manualpage metafile="htaccess.xml.meta">
  5. <parentdocument href="./">How-To / Tutorials</parentdocument>
  6.  
  7. <title>Apache Tutorial: .htaccess files</title>
  8.  
  9. <summary>
  10. <p><code>.htaccess</code> files provide a way to make configuration
  11. changes on a per-directory basis.</p>
  12. </summary>
  13.  
  14. <section id="related"><title>.htaccess files</title>
  15.     <related>
  16.         <modulelist>
  17.             <module>core</module>
  18.             <module>mod_auth</module>
  19.             <module>mod_cgi</module>
  20.             <module>mod_include</module>
  21.             <module>mod_mime</module>
  22.         </modulelist>
  23.  
  24.         <directivelist>
  25.             <directive module="core">AccessFileName</directive>
  26.             <directive module="core">AllowOverride</directive>
  27.             <directive module="core">Options</directive>
  28.             <directive module="mod_mime">AddHandler</directive>
  29.             <directive module="core">SetHandler</directive>
  30.             <directive module="core">AuthType</directive>
  31.             <directive module="core">AuthName</directive>
  32.             <directive module="mod_auth">AuthUserFile</directive>
  33.             <directive module="mod_auth">AuthGroupFile</directive>
  34.             <directive module="core">Require</directive>
  35.         </directivelist>
  36.  
  37.     </related>
  38. </section>
  39.  
  40. <section id="what">
  41. <title>What they are/How to use them</title>
  42.  
  43.     <p><code>.htaccess</code> files (or "distributed configuration files")
  44.     provide a way to make configuration changes on a per-directory basis. A
  45.     file, containing one or more configuration directives, is placed in a
  46.     particular document directory, and the directives apply to that
  47.     directory, and all subdirectories thereof.</p>
  48.  
  49.     <note><title>Note:</title>
  50.       <p>If you want to call your <code>.htaccess</code> file something
  51.       else, you can change the name of the file using the <directive
  52.       module="core">AccessFileName</directive> directive. For example,
  53.       if you would rather call the file <code>.config</code> then you
  54.       can put the following in your server configuration file:</p>
  55.  
  56.       <example>
  57.         AccessFileName .config
  58.       </example>
  59.     </note>
  60.  
  61.     <p>What you can put in these files is determined by the <directive
  62.     module="core">AllowOverride</directive>
  63.     directive. This directive specifies, in categories, what directives
  64.     will be honored if they are found in a <code>.htaccess</code> file. If
  65.     a directive is permitted in a <code>.htaccess</code> file, the
  66.     documentation for that directive will contain an Override section,
  67.     specifying what value must be in <directive 
  68.     module="core">AllowOverride</directive> in order
  69.     for that directive to be permitted.</p>
  70.  
  71.     <p>For example, if you look at the documentation for the <directive
  72.     module="core">AddDefaultCharset</directive>
  73.     directive, you will find that it is permitted in <code>.htaccess</code>
  74.     files. (See the Context line in the directive summary.) The <a
  75.     href="../mod/directive-dict.html#Context">Override</a> line reads
  76.     <code>FileInfo</code>. Thus, you must have at least
  77.     <code>AllowOverride FileInfo</code> in order for this directive to be
  78.     honored in <code>.htaccess</code> files.</p>
  79.  
  80.     <example><title>Example:</title>
  81.       <table>
  82.         <tr>
  83.           <td><a
  84.           href="../mod/directive-dict.html#Context">Context:</a></td>
  85.           <td>server config, virtual host, directory, .htaccess</td>
  86.         </tr>
  87.  
  88.         <tr>
  89.           <td><a
  90.           href="../mod/directive-dict.html#Override">Override:</a></td>
  91.           <td>FileInfo</td>
  92.         </tr>
  93.       </table>
  94.     </example>
  95.  
  96.     <p>If you are unsure whether a particular directive is permitted in a
  97.     <code>.htaccess</code> file, look at the documentation for that
  98.     directive, and check the Context line for ".htaccess".</p>
  99.     </section>
  100.  
  101.     <section id="when"><title>When (not) to use .htaccess files</title>
  102.  
  103.     <p>In general, you should never use <code>.htaccess</code> files unless
  104.     you don't have access to the main server configuration file. There is,
  105.     for example, a prevailing misconception that user authentication should
  106.     always be done in <code>.htaccess</code> files. This is simply not the
  107.     case. You can put user authentication configurations in the main server
  108.     configuration, and this is, in fact, the preferred way to do
  109.     things.</p>
  110.  
  111.     <p><code>.htaccess</code> files should be used in a case where the
  112.     content providers need to make configuration changes to the server on a
  113.     per-directory basis, but do not have root access on the server system.
  114.     In the event that the server administrator is not willing to make
  115.     frequent configuration changes, it might be desirable to permit
  116.     individual users to make these changes in <code>.htaccess</code> files
  117.     for themselves. This is particularly true, for example, in cases where
  118.     ISPs are hosting multiple user sites on a single machine, and want
  119.     their users to be able to alter their configuration.</p>
  120.  
  121.     <p>However, in general, use of <code>.htaccess</code> files should be
  122.     avoided when possible. Any configuration that you would consider
  123.     putting in a <code>.htaccess</code> file, can just as effectively be
  124.     made in a <directive module="core"
  125.     type="section">Directory</directive> section in your main server 
  126.     configuration file.</p>
  127.  
  128.     <p>There are two main reasons to avoid the use of
  129.     <code>.htaccess</code> files.</p>
  130.  
  131.     <p>The first of these is performance. When <directive 
  132.     module="core">AllowOverride</directive>
  133.     is set to allow the use of <code>.htaccess</code> files, Apache will
  134.     look in every directory for <code>.htaccess</code> files. Thus,
  135.     permitting <code>.htaccess</code> files causes a performance hit,
  136.     whether or not you actually even use them! Also, the
  137.     <code>.htaccess</code> file is loaded every time a document is
  138.     requested.</p>
  139.  
  140.     <p>Further note that Apache must look for <code>.htaccess</code> files
  141.     in all higher-level directories, in order to have a full complement of
  142.     directives that it must apply. (See section on <a href="#how">how
  143.     directives are applied</a>.) Thus, if a file is requested out of a
  144.     directory <code>/www/htdocs/example</code>, Apache must look for the
  145.     following files:</p>
  146.  
  147.    <example>
  148.       /.htaccess<br />
  149.       /www/.htaccess<br />
  150.       /www/htdocs/.htaccess<br />
  151.       /www/htdocs/example/.htaccess
  152.    </example>
  153.  
  154.     <p>And so, for each file access out of that directory, there are 4
  155.     additional file-system accesses, even if none of those files are
  156.     present. (Note that this would only be the case if
  157.     <code>.htaccess</code> files were enabled for <code>/</code>, which
  158.     is not usually the case.)</p>
  159.  
  160.     <p>The second consideration is one of security. You are permitting
  161.     users to modify server configuration, which may result in changes over
  162.     which you have no control. Carefully consider whether you want to give
  163.     your users this privilege. Note also that giving users less
  164.     privileges than they need will lead to additional technical support
  165.     requests. Make sure you clearly tell your users what level of
  166.     privileges you have given them. Specifying exactly what you have set
  167.     <directive module="core">AllowOverride</directive> to, and pointing them
  168.     to the relevant documentation, will save yourself a lot of confusion
  169.     later.</p>
  170.  
  171.     <p>Note that it is completely equivalent to put a <code>.htaccess</code>
  172.     file in a directory <code>/www/htdocs/example</code> containing a
  173.     directive, and to put that same directive in a Directory section
  174.     <code><Directory /www/htdocs/example></code> in your main server
  175.     configuration:</p>
  176.  
  177.     <p><code>.htaccess</code> file in <code>/www/htdocs/example</code>:</p>
  178.  
  179.     <example><title>Contents of .htaccess file in
  180.     <code>/www/htdocs/example</code></title>
  181.         AddType text/example .exm
  182.     </example>
  183.  
  184.     <example><title>Section from your <code>httpd.conf</code>
  185.     file</title>
  186.       <Directory /www/htdocs/example><br />
  187.       <indent>
  188.         AddType text/example .exm<br />
  189.       </indent>
  190.       </Directory>
  191.     </example>
  192.  
  193.     <p>However, putting this configuration in your server configuration
  194.     file will result in less of a performance hit, as the configuration is
  195.     loaded once when Apache starts, rather than every time a file is
  196.     requested.</p>
  197.  
  198.     <p>The use of <code>.htaccess</code> files can be disabled completely
  199.     by setting the <directive module="core">AllowOverride</directive>
  200.     directive to <code>none</code>:</p>
  201.  
  202.     <example>
  203.       AllowOverride None
  204.     </example>
  205. </section>
  206.  
  207. <section id="how"><title>How directives are applied</title>
  208.  
  209.     <p>The configuration directives found in a <code>.htaccess</code> file
  210.     are applied to the directory in which the <code>.htaccess</code> file
  211.     is found, and to all subdirectories thereof. However, it is important
  212.     to also remember that there may have been <code>.htaccess</code> files
  213.     in directories higher up. Directives are applied in the order that they
  214.     are found. Therefore, a <code>.htaccess</code> file in a particular
  215.     directory may override directives found in <code>.htaccess</code> files
  216.     found higher up in the directory tree. And those, in turn, may have
  217.     overridden directives found yet higher up, or in the main server
  218.     configuration file itself.</p>
  219.  
  220.     <p>Example:</p>
  221.  
  222.     <p>In the directory <code>/www/htdocs/example1</code> we have a
  223.     <code>.htaccess</code> file containing the following:</p>
  224.  
  225.     <example>
  226.        Options +ExecCGI
  227.     </example>
  228.  
  229.     <p>(Note: you must have "<code>AllowOverride Options</code>" in effect
  230.     to permit the use of the "<directive
  231.     module="core">Options</directive>" directive in
  232.     <code>.htaccess</code> files.)</p>
  233.  
  234.     <p>In the directory <code>/www/htdocs/example1/example2</code> we have
  235.     a <code>.htaccess</code> file containing:</p>
  236.  
  237.     <example>
  238.        Options Includes
  239.     </example>
  240.  
  241.     <p>Because of this second <code>.htaccess</code> file, in the directory
  242.     <code>/www/htdocs/example1/example2</code>, CGI execution is not
  243.     permitted, as only <code>Options Includes</code> is in effect, which
  244.     completely overrides any earlier setting that may have been in
  245.     place.</p>
  246. </section>
  247.  
  248. <section id="auth"><title>Authentication example</title>
  249.  
  250.     <p>If you jumped directly to this part of the document to find out how
  251.     to do authentication, it is important to note one thing. There is a
  252.     common misconception that you are required to use
  253.     <code>.htaccess</code> files in order to implement password
  254.     authentication. This is not the case. Putting authentication directives
  255.     in a <directive module="core" type="section">Directory</directive>
  256.     section, in your main server configuration file, is the preferred way
  257.     to implement this, and <code>.htaccess</code> files should be used only
  258.     if you don't have access to the main server configuration file. See <a 
  259.     href="#when">above</a> for a discussion of when you should and should
  260.     not use <code>.htaccess</code> files.</p>
  261.  
  262.     <p>Having said that, if you still think you need to use a
  263.     <code>.htaccess</code> file, you may find that a configuration such as
  264.     what follows may work for you.</p>
  265.  
  266.     <p>You must have "<code>AllowOverride AuthConfig</code>" in effect for
  267.     these directives to be honored.</p>
  268.  
  269.     <p><code>.htaccess</code> file contents:</p>
  270.  
  271.     <example>
  272.           AuthType Basic<br />
  273.            AuthName "Password Required"<br />
  274.            AuthUserFile /www/passwords/password.file<br />
  275.            AuthGroupFile /www/passwords/group.file<br />
  276.            Require Group admins
  277.     </example>
  278.  
  279.     <p>Note that <code>AllowOverride AuthConfig</code> must be in effect
  280.     for these directives to have any effect.</p>
  281.  
  282.     <p>Please see the <a href="auth.html">authentication tutorial</a> for a
  283.     more complete discussion of authentication and authorization.</p>
  284. </section>
  285.  
  286. <section id="ssi"><title>Server Side Includes example</title>
  287.  
  288.     <p>Another common use of <code>.htaccess</code> files is to enable
  289.     Server Side Includes for a particular directory. This may be done with
  290.     the following configuration directives, placed in a
  291.     <code>.htaccess</code> file in the desired directory:</p>
  292.  
  293.     <example>
  294.        Options +Includes<br />
  295.        AddType text/html shtml<br />
  296.        AddHandler server-parsed shtml
  297.     </example>
  298.  
  299.     <p>Note that <code>AllowOverride Options</code> and <code>AllowOverride
  300.     FileInfo</code> must both be in effect for these directives to have any
  301.     effect.</p>
  302.  
  303.     <p>Please see the <a href="ssi.html">SSI tutorial</a> for a more
  304.     complete discussion of server-side includes.</p>
  305. </section>
  306.  
  307. <section id="cgi"><title>CGI example</title>
  308.  
  309.     <p>Finally, you may wish to use a <code>.htaccess</code> file to permit
  310.     the execution of CGI programs in a particular directory. This may be
  311.     implemented with the following configuration:</p>
  312.  
  313.     <example>
  314.        Options +ExecCGI<br />
  315.        AddHandler cgi-script cgi pl
  316.     </example>
  317.  
  318.     <p>Alternately, if you wish to have all files in the given directory be
  319.     considered to be CGI programs, this may be done with the following
  320.     configuration:</p>
  321.  
  322.     <example>
  323.        Options +ExecCGI<br />
  324.        SetHandler cgi-script
  325.     </example>
  326.  
  327.     <p>Note that <code>AllowOverride Options</code> and <code>AllowOverride
  328.     FileInfo</code> must both be in effect for these directives to have any
  329.     effect.</p>
  330.  
  331.     <p>Please see the <a href="cgi.html">CGI tutorial</a> for a more
  332.     complete discussion of CGI programming and configuration.</p>
  333.  
  334. </section>
  335.  
  336. <section id="troubleshoot"><title>Troubleshooting</title>
  337.  
  338.     <p>When you put configuration directives in a <code>.htaccess</code>
  339.     file, and you don't get the desired effect, there are a number of
  340.     things that may be going wrong.</p>
  341.  
  342.     <p>Most commonly, the problem is that <directive
  343.     module="core">AllowOverride</directive> is not
  344.     set such that your configuration directives are being honored. Make
  345.     sure that you don't have a <code>AllowOverride None</code> in effect
  346.     for the file scope in question. A good test for this is to put garbage
  347.     in your <code>.htaccess</code> file and reload. If a server error is
  348.     not generated, then you almost certainly have <code>AllowOverride
  349.     None</code> in effect.</p>
  350.  
  351.     <p>If, on the other hand, you are getting server errors when trying to
  352.     access documents, check your Apache error log. It will likely tell you
  353.     that the directive used in your <code>.htaccess</code> file is not
  354.     permitted. Alternately, it may tell you that you had a syntax error,
  355.     which you will then need to fix.</p>
  356.  
  357. </section>
  358.  
  359. </manualpage>
  360.