granicus.if.org Git - apache/blob - docs/manual/mod/mod_userdir.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.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 <modulesynopsis metafile="mod_userdir.xml.meta">
  24
  25 <name>mod_userdir</name>
  26 <description>User-specific directories</description>
  27 <status>Base</status>
  28 <sourcefile>mod_userdir.c</sourcefile>
  29 <identifier>userdir_module</identifier>
  30
  31 <summary>
  32 <p>This module allows user-specific directories to be accessed using the
  33 <code>http://example.com/~user/</code> syntax.</p>
  34 </summary>
  35
  36 <seealso><a href="../urlmapping.html">Mapping URLs to the
  37 Filesystem</a></seealso>
  38 <seealso><a href="../howto/public_html.html">public_html
  39 tutorial</a></seealso>
  40
  41 <directivesynopsis>
  42
  43 <name>UserDir</name>
  44 <description>Location of the user-specific directories</description>
  45 <syntax>UserDir <em>directory-filename</em> [<em>directory-filename</em>] ...
  46 </syntax>
  47 <contextlist><context>server config</context> <context>virtual
  48 host</context></contextlist>
  49
  50 <usage>
  51
  52     <p>The <directive>UserDir</directive> directive sets the real
  53     directory in a user's home directory to use when a request for a
  54     document for a user is received. <em>Directory-filename</em> is
  55     one of the following:</p>
  56
  57     <ul>
  58       <li>The name of a directory or a pattern such as those shown
  59       below.</li>
  60
  61       <li>The keyword <code>disabled</code>. This turns off
  62       <em>all</em> username-to-directory translations except those
  63       explicitly named with the <code>enabled</code> keyword (see
  64       below).</li>
  65
  66       <li>The keyword <code>disabled</code> followed by a
  67       space-delimited list of usernames. Usernames that appear in
  68       such a list will <em>never</em> have directory translation
  69       performed, even if they appear in an <code>enabled</code>
  70       clause.</li>
  71
  72       <li>The keyword <code>enabled</code> followed by a
  73       space-delimited list of usernames. These usernames will have
  74       directory translation performed even if a global disable is
  75       in effect, but not if they also appear in a
  76       <code>disabled</code> clause.</li>
  77     </ul>
  78
  79     <p>If neither the <code>enabled</code> nor the
  80     <code>disabled</code> keywords appear in the
  81     <code>Userdir</code> directive, the argument is treated as a
  82     filename pattern, and is used to turn the name into a directory
  83     specification. A request for
  84     <code>http://www.example.com/~bob/one/two.html</code> will be
  85     translated to:</p>
  86
  87     <table>
  88       <tr><th>UserDir directive used</th>
  89           <th>Translated path</th></tr>
  90       <tr><td>UserDir public_html</td>
  91           <td>~bob/public_html/one/two.html</td></tr>
  92       <tr><td>UserDir /usr/web</td>
  93           <td>/usr/web/bob/one/two.html</td></tr>
  94       <tr><td>UserDir /home/*/www</td>
  95           <td>/home/bob/www/one/two.html</td></tr>
  96     </table>
  97
  98     <p>The following directives will send redirects to the client:</p>
  99
 100     <table>
 101       <tr><th>UserDir directive used</th>
 102           <th>Translated path</th></tr>
 103       <tr><td>UserDir http://www.example.com/users</td>
 104           <td>http://www.example.com/users/bob/one/two.html</td></tr>
 105       <tr><td>UserDir http://www.example.com/*/usr</td>
 106           <td>http://www.example.com/bob/usr/one/two.html</td></tr>
 107       <tr><td>UserDir http://www.example.com/~*/</td>
 108           <td>http://www.example.com/~bob/one/two.html</td></tr>
 109     </table>
 110
 111     <note>
 112       <strong>Be careful when using this directive; for instance,
 113       <code>"UserDir ./"</code> would map <code>"/~root"</code> to
 114       <code>"/"</code> - which is probably undesirable. It is strongly
 115       recommended that your configuration include a "<code>UserDir
 116       disabled root</code>" declaration.  See also the <directive
 117       module="core">Directory</directive> directive and the <a
 118       href="../misc/security_tips.html">Security Tips</a> page for
 119       more information.</strong>
 120     </note>
 121
 122     <p>Additional examples:</p>
 123
 124     <p>To allow a few users to have <code>UserDir</code> directories, but
 125     not anyone else, use the following:</p>
 126
 127     <highlight language="config">
 128 UserDir disabled
 129 UserDir enabled user1 user2 user3
 130     </highlight>
 131
 132     <p>To allow most users to have <code>UserDir</code> directories, but
 133     deny this to a few, use the following:</p>
 134
 135     <highlight language="config">
 136       UserDir disabled user4 user5 user6
 137     </highlight>
 138
 139     <p>It is also possible to specify alternative user directories.
 140     If you use a command like:</p>
 141
 142     <highlight language="config">
 143       UserDir public_html /usr/web http://www.example.com/
 144     </highlight>
 145
 146     <p>With a request for
 147     <code>http://www.example.com/~bob/one/two.html</code>, will try to
 148     find the page at <code>~bob/public_html/one/two.html</code> first, then
 149     <code>/usr/web/bob/one/two.html</code>, and finally it will send a
 150     redirect to <code>http://www.example.com/bob/one/two.html</code>.</p>
 151
 152     <p>If you add a redirect, it must be the last alternative in the list.
 153     Apache httpd cannot determine if the redirect succeeded or not, so if you have
 154     the redirect earlier in the list, that will always be the alternative
 155     that is used.</p>
 156
 157     <p>User directory substitution is not active by default in versions
 158     2.1.4 and later.  In earlier versions, <code>UserDir public_html</code>
 159     was assumed if no <directive module="mod_userdir">UserDir</directive>
 160     directive was present.</p>
 161
 162     <note><title>Merging details</title>
 163     <p> Lists of specific enabled and disabled users are replaced, not merged,
 164     from global to virtual host scope</p></note>
 165
 166 </usage>
 167
 168 <seealso>
 169   <a href="../howto/public_html.html">Per-user web directories tutorial</a>
 170 </seealso>
 171
 172 </directivesynopsis>
 173 </modulesynopsis>
 174
 175