2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
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
14 http://www.apache.org/licenses/LICENSE-2.0
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.
23 <modulesynopsis metafile="mod_userdir.xml.meta">
25 <name>mod_userdir</name>
26 <description>User-specific directories</description>
28 <sourcefile>mod_userdir.c</sourcefile>
29 <identifier>userdir_module</identifier>
32 <p>This module allows user-specific directories to be accessed using the
33 <code>http://example.com/~user/</code> syntax.</p>
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>
44 <description>Location of the user-specific directories</description>
45 <syntax>UserDir <em>directory-filename</em></syntax>
46 <contextlist><context>server config</context> <context>virtual
47 host</context></contextlist>
51 <p>The <directive>UserDir</directive> directive sets the real
52 directory in a user's home directory to use when a request for a
53 document for a user is received. <em>Directory-filename</em> is
54 one of the following:</p>
57 <li>The name of a directory or a pattern such as those shown
60 <li>The keyword <code>disabled</code>. This turns off
61 <em>all</em> username-to-directory translations except those
62 explicitly named with the <code>enabled</code> keyword (see
65 <li>The keyword <code>disabled</code> followed by a
66 space-delimited list of usernames. Usernames that appear in
67 such a list will <em>never</em> have directory translation
68 performed, even if they appear in an <code>enabled</code>
71 <li>The keyword <code>enabled</code> followed by a
72 space-delimited list of usernames. These usernames will have
73 directory translation performed even if a global disable is
74 in effect, but not if they also appear in a
75 <code>disabled</code> clause.</li>
78 <p>If neither the <code>enabled</code> nor the
79 <code>disabled</code> keywords appear in the
80 <code>Userdir</code> directive, the argument is treated as a
81 filename pattern, and is used to turn the name into a directory
82 specification. A request for
83 <code>http://www.foo.com/~bob/one/two.html</code> will be
87 <tr><th>UserDir directive used</th>
88 <th>Translated path</th></tr>
89 <tr><td>UserDir public_html</td><td>~bob/public_html/one/two.html</td></tr>
90 <tr><td>UserDir /usr/web</td><td>/usr/web/bob/one/two.html</td></tr>
91 <tr><td>UserDir /home/*/www</td><td>/home/bob/www/one/two.html</td></tr>
94 <p>The following directives will send redirects to the client:</p>
97 <tr><th>UserDir directive used</th>
98 <th>Translated path</th></tr>
99 <tr><td>UserDir http://www.foo.com/users</td><td>http://www.foo.com/users/bob/one/two.html</td></tr>
101 http://www.foo.com/*/usr</td><td>http://www.foo.com/bob/usr/one/two.html</td></tr>
103 http://www.foo.com/~*/</td><td>http://www.foo.com/~bob/one/two.html</td></tr>
107 <strong>Be careful when using this directive; for instance,
108 <code>"UserDir ./"</code> would map <code>"/~root"</code> to
109 <code>"/"</code> - which is probably undesirable. It is strongly
110 recommended that your configuration include a "<code>UserDir
111 disabled root</code>" declaration. See also the <directive
112 module="core">Directory</directive> directive and the <a
113 href="../misc/security_tips.html">Security Tips</a> page for
114 more information.</strong>
117 <p>Additional examples:</p>
119 <p>To allow a few users to have <code>UserDir</code> directories, but
120 not anyone else, use the following:</p>
123 UserDir disabled<br />
124 UserDir enabled user1 user2 user3
127 <p>To allow most users to have <code>UserDir</code> directories, but
128 deny this to a few, use the following:</p>
131 UserDir enabled<br />
132 UserDir disabled user4 user5 user6
135 <p>It is also possible to specify alternative user directories.
136 If you use a command like:</p>
138 Userdir public_html /usr/web http://www.foo.com/
140 <p>With a request for http://www.foo.com/~bob/one/two.html, will try to
141 find the page at ~bob/public_html/one/two.html first, then
142 /usr/web/bob/one/two.html, and finally it will send a redirect
143 to http://www.foo.com/bob/one/two.html.</p>
144 <p>If you add a redirect, it must be the last alternative in the list.
145 Apache cannot determine if the redirect succeeded or not, so if you have
146 the redirect earlier in the list, that will always be the alternative
149 <p>User directory substitution is not active by default in versions
150 2.1.4 and later. In earlier versions, <code>UserDir public_html</code>
151 was assumed if no <directive module="mod_userdir">UserDir</directive>
152 directive was present.</p>
156 <seealso><a href="../howto/public_html.html">public_html
157 tutorial</a></seealso>