granicus.if.org Git - apache/blob - docs/manual/howto/public_html.xml

   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 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <manualpage metafile="public_html.xml.meta">
  24 <parentdocument href="./">How-To / Tutorials</parentdocument>
  25
  26   <title>Per-user web directories</title>
  27
  28 <summary>
  29 <p>On systems with multiple users, each user can be permitted to have a
  30     web site in their home directory using the <directive
  31     module="mod_userdir">UserDir</directive> directive. Visitors
  32     to a URL <code>http://example.com/~username/</code> will get content
  33     out of the home directory of the user "<code>username</code>", out of
  34     the subdirectory specified by the <directive
  35     module="mod_userdir">UserDir</directive> directive.</p>
  36 <p>Note that, by default, access to these directories is <strong>not</strong>
  37     enabled. You can enable access when using <directive module="mod_userdir"
  38     >UserDir</directive> by uncommenting the line</p>
  39     <example>
  40       #Include conf/extra/httpd-userdir.conf
  41     </example>
  42     <p>in the default config file <code>conf/httpd.conf</code>, and adapting the <code
  43     >httpd-userdir.conf</code>
  44     file as necessary, or by including the appropriate directives in a
  45     <code>Directory</code> block within the main config file.</p>
  46 </summary>
  47
  48 <seealso><a href="../urlmapping.html">Mapping URLs to the Filesystem</a></seealso>
  49
  50   <section id="related">
  51     <title>Per-user web directories</title>
  52     <related>
  53       <modulelist>
  54         <module>mod_userdir</module>
  55       </modulelist>
  56       <directivelist>
  57         <directive module="mod_userdir">UserDir</directive>
  58         <directive module="core">DirectoryMatch</directive>
  59         <directive module="core">AllowOverride</directive>
  60       </directivelist>
  61     </related>
  62     </section>
  63
  64     <section id="userdir">
  65     <title>Setting the file path with UserDir</title>
  66
  67     <p>The <directive module="mod_userdir">UserDir</directive>
  68     directive specifies a directory out of which per-user
  69     content is loaded. This directive may take several different forms.</p>
  70
  71     <p>If a path is given which does not start with a leading slash, it is
  72     assumed to be a directory path relative to the home directory of the
  73     specified user. Given this configuration:</p>
  74
  75     <highlight language="config">UserDir public_html</highlight>
  76
  77     <p>the URL <code>http://example.com/~rbowen/file.html</code> will be
  78     translated to the file path
  79     <code>/home/rbowen/public_html/file.html</code></p>
  80
  81     <p>If a path is given starting with a slash, a directory path will be
  82     constructed using that path, plus the username specified. Given this
  83     configuration:</p>
  84
  85     <highlight language="config">UserDir /var/html</highlight>
  86
  87     <p>the URL <code>http://example.com/~rbowen/file.html</code> will be
  88     translated to the file path <code>/var/html/rbowen/file.html</code></p>
  89
  90     <p>If a path is provided which contains an asterisk (*), a path is used
  91     in which the asterisk is replaced with the username. Given this
  92     configuration:</p>
  93
  94     <highlight language="config">UserDir /var/www/*/docs</highlight>
  95
  96     <p>the URL <code>http://example.com/~rbowen/file.html</code> will be
  97     translated to the file path
  98     <code>/var/www/rbowen/docs/file.html</code></p>
  99
 100     <p>Multiple directories or directory paths can also be set.</p>
 101
 102     <highlight language="config">UserDir public_html /var/html</highlight>
 103
 104     <p>For the URL <code>http://example.com/~rbowen/file.html</code>,
 105     Apache will search for <code>~rbowen</code>. If it isn't found,
 106     Apache will search for <code>rbowen</code> in <code>/var/html</code>. If
 107     found, the above URL will then be translated to the file path
 108     <code>/var/html/rbowen/file.html</code></p>
 109
 110   </section>
 111
 112   <section id="redirect">
 113     <title>Redirecting to external URLs</title>
 114     <p>The <directive module="mod_userdir">UserDir</directive> directive can be
 115       used to redirect user directory requests to external URLs.</p>
 116
 117     <highlight language="config">UserDir http://example.org/users/*/</highlight>
 118
 119     <p>The above example will redirect a request for
 120     <code>http://example.com/~bob/abc.html</code> to
 121     <code>http://example.org/users/bob/abc.html</code>.</p>
 122   </section>
 123
 124   <section id="enable">
 125     <title>Restricting what users are permitted to use this
 126     feature</title>
 127
 128     <p>Using the syntax shown in the UserDir documentation, you can restrict
 129     what users are permitted to use this functionality:</p>
 130
 131     <highlight language="config">UserDir disabled root jro fish</highlight>
 132
 133     <p>The configuration above will enable the feature for all users
 134     except for those listed in the <code>disabled</code> statement.
 135     You can, likewise, disable the feature for all but a few users by
 136     using a configuration like the following:</p>
 137
 138     <highlight language="config">
 139 UserDir disabled
 140 UserDir enabled rbowen krietz
 141     </highlight>
 142
 143     <p>See <directive module="mod_userdir">UserDir</directive>
 144     documentation for additional examples.</p>
 145
 146   </section>
 147
 148   <section id="cgi">
 149   <title>Enabling a cgi directory for each user</title>
 150
 151    <p>In order to give each user their own cgi-bin directory, you can use
 152     a <directive module="core" type="section">Directory</directive>
 153     directive to make a particular subdirectory of a user's home directory
 154     cgi-enabled.</p>
 155
 156     <highlight language="config">
 157 &lt;Directory "/home/*/public_html/cgi-bin/"&gt;
 158     Options ExecCGI
 159     SetHandler cgi-script
 160 &lt;/Directory&gt;
 161     </highlight>
 162
 163     <p>Then, presuming that <code>UserDir</code> is set to
 164     <code>public_html</code>, a cgi program <code>example.cgi</code>
 165     could be loaded from that directory as:</p>
 166
 167     <example>
 168     http://example.com/~rbowen/cgi-bin/example.cgi
 169     </example>
 170
 171     </section>
 172
 173     <section id="htaccess">
 174     <title>Allowing users to alter configuration</title>
 175
 176     <p>If you want to allows users to modify the server configuration in
 177     their web space, they will need to use <code>.htaccess</code> files to
 178     make these changes. Ensure that you have set <directive
 179     module="core">AllowOverride</directive> to a
 180     value sufficient for the directives that you want to permit the users
 181     to modify. See the <a href="htaccess.html">.htaccess tutorial</a> for
 182     additional details on how this works.</p>
 183
 184   </section>
 185
 186 </manualpage>