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> [<em>directory-filename</em>] ...
47 <contextlist><context>server config</context> <context>virtual
48 host</context></contextlist>
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>
58 <li>The name of a directory or a pattern such as those shown
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
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>
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>
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
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>
98 <p>The following directives will send redirects to the client:</p>
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>
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>
122 <p>Additional examples:</p>
124 <p>To allow a few users to have <code>UserDir</code> directories, but
125 not anyone else, use the following:</p>
127 <highlight language="config">
129 UserDir enabled user1 user2 user3
132 <p>To allow most users to have <code>UserDir</code> directories, but
133 deny this to a few, use the following:</p>
135 <highlight language="config">
136 UserDir disabled user4 user5 user6
139 <p>It is also possible to specify alternative user directories.
140 If you use a command like:</p>
142 <highlight language="config">
143 UserDir public_html /usr/web http://www.example.com/
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>
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
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>
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>
169 <a href="../howto/public_html.html">Per-user web directories tutorial</a>