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     <highlight language="config">
  40       #Include conf/extra/httpd-userdir.conf
  41     </highlight>
  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     <directive module="core" type="section">Directory</directive> block
  46     within the main config file.</p>
  47 </summary>
  48
  49 <seealso><a href="../urlmapping.html">Mapping URLs to the Filesystem</a></seealso>
  50
  51   <section id="related">
  52     <title>Per-user web directories</title>
  53     <related>
  54       <modulelist>
  55         <module>mod_userdir</module>
  56       </modulelist>
  57       <directivelist>
  58         <directive module="mod_userdir">UserDir</directive>
  59         <directive module="core">DirectoryMatch</directive>
  60         <directive module="core">AllowOverride</directive>
  61       </directivelist>
  62     </related>
  63     </section>
  64
  65     <section id="userdir">
  66     <title>Setting the file path with UserDir</title>
  67
  68     <p>The <directive module="mod_userdir">UserDir</directive>
  69     directive specifies a directory out of which per-user
  70     content is loaded. This directive may take several different forms.</p>
  71
  72     <p>If a path is given which does not start with a leading slash, it is
  73     assumed to be a directory path relative to the home directory of the
  74     specified user. Given this configuration:</p>
  75
  76     <highlight language="config">
  77 UserDir public_html
  78     </highlight>
  79
  80     <p>the URL <code>http://example.com/~rbowen/file.html</code> will be
  81     translated to the file path
  82     <code>/home/rbowen/public_html/file.html</code></p>
  83
  84     <p>If a path is given starting with a slash, a directory path will be
  85     constructed using that path, plus the username specified. Given this
  86     configuration:</p>
  87
  88     <highlight language="config">
  89 UserDir /var/html
  90     </highlight>
  91
  92     <p>the URL <code>http://example.com/~rbowen/file.html</code> will be
  93     translated to the file path <code>/var/html/rbowen/file.html</code></p>
  94
  95     <p>If a path is provided which contains an asterisk (*), a path is used
  96     in which the asterisk is replaced with the username. Given this
  97     configuration:</p>
  98
  99     <highlight language="config">
 100 UserDir /var/www/*/docs
 101     </highlight>
 102
 103     <p>the URL <code>http://example.com/~rbowen/file.html</code> will be
 104     translated to the file path
 105     <code>/var/www/rbowen/docs/file.html</code></p>
 106
 107     <p>Multiple directories or directory paths can also be set.</p>
 108
 109     <highlight language="config">
 110 UserDir public_html /var/html
 111     </highlight>
 112
 113     <p>For the URL <code>http://example.com/~rbowen/file.html</code>,
 114     Apache will search for <code>~rbowen</code>. If it isn't found,
 115     Apache will search for <code>rbowen</code> in <code>/var/html</code>. If
 116     found, the above URL will then be translated to the file path
 117     <code>/var/html/rbowen/file.html</code></p>
 118
 119   </section>
 120
 121   <section id="redirect">
 122     <title>Redirecting to external URLs</title>
 123     <p>The <directive module="mod_userdir">UserDir</directive> directive can be
 124       used to redirect user directory requests to external URLs.</p>
 125
 126     <highlight language="config">
 127 UserDir http://example.org/users/*/
 128     </highlight>
 129
 130     <p>The above example will redirect a request for
 131     <code>http://example.com/~bob/abc.html</code> to
 132     <code>http://example.org/users/bob/abc.html</code>.</p>
 133   </section>
 134
 135   <section id="enable">
 136     <title>Restricting what users are permitted to use this
 137     feature</title>
 138
 139     <p>Using the syntax shown in the UserDir documentation, you can restrict
 140     what users are permitted to use this functionality:</p>
 141
 142     <highlight language="config">
 143 UserDir disabled root jro fish
 144     </highlight>
 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     <highlight language="config">
 152 UserDir disabled
 153 UserDir enabled rbowen krietz
 154     </highlight>
 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     <highlight language="config">
 170 &lt;Directory "/home/*/public_html/cgi-bin/"&gt;
 171     Options ExecCGI
 172     SetHandler cgi-script
 173 &lt;/Directory&gt;
 174     </highlight>
 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 changes. 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>