apache/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, 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     <example>
  76       UserDir public_html
  77     </example>
  78
  79     <p>the URL <code>http://example.com/~rbowen/file.html</code> will be
  80     translated to the file path
  81     <code>/home/rbowen/public_html/file.html</code></p>
  82
  83     <p>If a path is given starting with a slash, a directory path will be
  84     constructed using that path, plus the username specified. Given this
  85     configuration:</p>
  86
  87     <example>
  88       UserDir /var/html
  89     </example>
  90
  91     <p>the URL <code>http://example.com/~rbowen/file.html</code> will be
  92     translated to the file path <code>/var/html/rbowen/file.html</code></p>
  93
  94     <p>If a path is provided which contains an asterisk (*), a path is used
  95     in which the asterisk is replaced with the username. Given this
  96     configuration:</p>
  97
  98     <example>
  99       UserDir /var/www/*/docs
 100     </example>
 101
 102     <p>the URL <code>http://example.com/~rbowen/file.html</code> will be
 103     translated to the file path
 104     <code>/var/www/rbowen/docs/file.html</code></p>
 105
 106     <p>Multiple directories or directory paths can also be set.</p>
 107
 108     <example>
 109       UserDir public_html /var/html
 110     </example>
 111
 112     <p>For the URL <code>http://example.com/~rbowen/file.html</code>,
 113     Apache will search for <code>~rbowen</code>. If it isn't found,
 114     Apache will search for <code>rbowen</code> in <code>/var/html</code>. If
 115     found, the above URL will then be translated to the file path
 116     <code>/var/html/rbowen/file.html</code></p>
 117
 118   </section>
 119
 120   <section id="redirect">
 121     <title>Redirecting to external URLs</title>
 122     <p>The <directive module="mod_userdir">UserDir</directive> directive can be
 123       used to redirect user directory requests to external URLs.</p>
 124
 125     <example>
 126       UserDir http://example.org/users/*/
 127     </example>
 128
 129     <p>The above example will redirect a request for
 130     <code>http://example.com/~bob/abc.html</code> to
 131     <code>http://example.org/users/bob/abc.html</code>.</p>
 132   </section>
 133
 134   <section id="enable">
 135     <title>Restricting what users are permitted to use this
 136     feature</title>
 137
 138     <p>Using the syntax shown in the UserDir documentation, you can restrict
 139     what users are permitted to use this functionality:</p>
 140
 141     <example>
 142       UserDir enabled<br />
 143       UserDir disabled root jro fish
 144     </example>
 145
 146     <p>The configuration above will enable the feature for all users
 147     except for those listed in the <code>disabled</code> statement.
 148     You can, likewise, disable the feature for all but a few users by
 149     using a configuration like the following:</p>
 150
 151     <example>
 152       UserDir disabled<br />
 153       UserDir enabled rbowen krietz
 154     </example>
 155
 156     <p>See <directive module="mod_userdir">UserDir</directive>
 157     documentation for additional examples.</p>
 158
 159   </section>
 160
 161   <section id="cgi">
 162   <title>Enabling a cgi directory for each user</title>
 163
 164    <p>In order to give each user their own cgi-bin directory, you can use
 165     a <directive module="core" type="section">Directory</directive>
 166     directive to make a particular subdirectory of a user's home directory
 167     cgi-enabled.</p>
 168
 169     <example>
 170       &lt;Directory /home/*/public_html/cgi-bin/&gt;<br />
 171        Options ExecCGI<br />
 172        SetHandler cgi-script<br />
 173        &lt;/Directory&gt;
 174     </example>
 175
 176     <p>Then, presuming that <code>UserDir</code> is set to
 177     <code>public_html</code>, a cgi program <code>example.cgi</code>
 178     could be loaded from that directory as:</p>
 179
 180     <example>
 181     http://example.com/~rbowen/cgi-bin/example.cgi
 182     </example>
 183
 184     </section>
 185
 186     <section id="htaccess">
 187     <title>Allowing users to alter configuration</title>
 188
 189     <p>If you want to allows users to modify the server configuration in
 190     their web space, they will need to use <code>.htaccess</code> files to
 191     make these changed. Ensure that you have set <directive
 192     module="core">AllowOverride</directive> to a
 193     value sufficient for the directives that you want to permit the users
 194     to modify. See the <a href="htaccess.html">.htaccess tutorial</a> for
 195     additional details on how this works.</p>
 196
 197   </section>
 198
 199 </manualpage>