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