User-based Directories¶

• Table of contents
• User-based Directories
  • Description
  • Options
    • userdir.path (required option)
    • userdir.exclude-user
    • userdir.include-user
    • userdir.basepath
  • Should I use mod_userdir?
  • Troubleshooting

Module mod_userdir

Description¶

The userdir module provides a simple way to link user-based directories into the global namespace of the webserver.

Requests in the form /~user/page.html are rewritten to take the file page.html from the home directory of the user.
If userdir.path is set, the path will be appended to the home directory building the classic mapping of:

# URL: http://www.example.org/~jan/index.html 
# Path: /home/jan/public_html/

userdir.path = "public_html" 

To control which users should be able to use this feature you can set a list of usernames to include or exclude.

In case your mapping is independent of /etc/passwd you can use userdir.basepath:

# URL: http://www.example.org/~jan/index.html
# Path: /var/www/users/jan/htdocs/index.html

userdir.path = "htdocs" 
userdir.basepath = "/var/www/users/" 

Options¶

userdir.path (required option)¶

usually it should be set to "public_html" to take ~/public_html/ as the document root
default: unset (mod_userdir disabled; set it to "" if you want the home directory to be the document root as it was the default before 1.4.19)
Example:

userdir.path = "public_html"

userdir.exclude-user¶

list of usernames which may not use this feature
default: empty (all users may use it)
Example:

userdir.exclude-user = ( "root", "postmaster" )

userdir.include-user¶

if set, only users from this list may use the feature
default: empty (all users may use it)

userdir.basepath¶

if set, use userdir.basepath plus username instead of checking /etc/passwd for homedir

Should I use mod_userdir?¶

The concept of serving files from userdirs is historical and dates back to the 1990's when having an internet-connected server was rare/expensive and server access was often shared by many users. Websites at the time were also typically static content, not as dynamic (e.g. using Python or PHP) as many popular sites are today.

mod_userdir is a simple lighttpd module and lighttpd provides this option.
However, your system must be configured to allow lighttpd mod_userdir to function.

If serving files from userdirs is an explicit requirement and part of your systems design, then lighttpd mod_userdir may be an appropriate solution.

If not, then using mod_userdir is probably a suboptimal solution.

• Using subfolders in the web server document root may be a simpler and better solution.
• Using mod_userdir with userdir.basepath is another alternative rather than serving files from underneath user home directories.
• For more advanced users, having each user control and run their own instance of lighttpd under their own user account might be better solution to delegate. A single lighttpd instance run by the administrator can use lighttpd mod_proxy to reverse proxy specific sites or URL-paths to each advanced user's own lighttpd instance.
• ...

For security reasons, home directories are generally private by default in modern OS distributions, and this privacy breaks the historical (and discouraged) userdir pattern.
e.g. https://ubuntu.com/blog/private-home-directories-for-ubuntu-21-04

Troubleshooting¶

mod_userdir is a simple lighttpd module.
However, your system must be configured to allow lighttpd mod_userdir to function.

If you choose to use mod_userdir, at what level do you classify your own expertise?

• Are you an expert administering systems and do you know that mod_userdir fits your requirements?
• Are you not an expert administering systems?
  You probably should not use mod_userdir and might want to reconsider why you think you need mod_userdir.

This site is for the lighttpd web server. This site is not kindergarten for basic systems administration.
Basic systems administration tasks outside the scope of lighttpd include, but are not limited to, configuring user accounts, filesystem permissions, SELinux, networking, and firewalls.

Why such a blunt distinction? Among those who are not experts in administering systems, too many tend not to understand how to manage multiple user accounts and filesystem permissions. Such people tend to make poor assumptions about how systems work, and then some of those people further get frustrated that people everywhere on the internet are not bending over backwards to teach them what they do not know and have not taken a few moments to learn on their own. That is not a recipe for success. It is unfortunate that this must be written so rudely and bluntly here. If you understand this, then this was not aimed at you. If you had to be pointed here, then this message is aimed specifically at you. To repeat: this site is for the lighttpd web server. This site is not kindergarten for basic systems administration.

If lighttpd mod_userdir does not have permission to access files, then lighttpd mod_userdir does not have permission to access files. It means exactly that. The ability to access files is a property of user accounts and filesystem permissions, potentially involving SELinux. That is not a shortcoming of lighttpd mod_userdir. If you are unable to understand or to troubleshoot filesystem permissions, then you probably should not use lighttpd mod_userdir. Instead, you might use the document root configured by the lighttpd package installed on your system. That path is often something such as /var/www/.