≡ Menu

Lighttpd setup a password protected directory (directories)

Lighttpd logo

If you require authentication on certain directories using the Lighttpd web server, you can use Lighttpd’s mod_auth module. It allows you to protect any directory in web server with access restrictions (just like Apache’s password protected directory) .

Lighttpd supports both basic and digest authentication methods. Now consider following sample setup:

  1. Domain name: theos.in
  2. Directory (DocRoot) to protect with a password: /home/lighttpd/theos.in/http/docs
  3. Username: vivek
  4. Lighttpd password file: /home/lighttpd/.lighttpdpassword (this file should be outside default http document root)

How do I use Basic authentication method?

Easy to implement and password stored in cleartext format using files. If you are going to use this method make sure you use SSL (Secure Socket Layer) connection/encryption.

Step #1: Open /etc/lighttpd/lighttpd.conf file

Make sure mod_auth is loaded:
server.modules += ( "mod_auth" )

Now add following three directives:
auth.debug = 2
auth.backend = "plain"
auth.backend.plain.userfile = "/home/lighttpd/.lighttpdpassword"


  • auth.debug = 2 : Specify debug level (0 turns off debug message, 1 for authentication ok message and 2 for detailed/verbose debugging message). This is useful for troubleshooting authentication problem. It logs message in access.log and error.log files
  • auth.backend = “plain” : You are using plain text backend (other options are ldap, htpasswd and others)
  • auth.backend.plain.userfile = “/home/lighttpd/.lighttpdpassword” : Filename of the username:password storage

Next, you need specify which directory you want to password protect. For example, consider directory /home/lighttpd/theos.in/http/docs directory. Find out your domains virtual hosting section (theos.in) and append following text:
auth.require = ( "/docs/" =>
"method" => "basic",
"realm" => "Password protected area",
"require" => "user=vivek"


  • auth.require = ( “/docs/” => : Directory name
  • “method” => “basic”, : Authentication type
  • “realm” => “Password protected area”, : Password realm/message
  • “require” => “user=vivek” : Only user vivek can use /docs/

At the end, your configuration should read as follows:
$HTTP["host"] == "theos.in" {
server.document-root = "/home/lighttpd/theos.in/http"
server.errorlog = "/var/log/lighttpd/theos.in/error.log"
accesslog.filename = "/var/log/lighttpd/theos.in/access.log"
auth.require = ( "/docs/" =>
"method" => "basic",
"realm" => "Password protected area",
"require" => "user=vivek"

Save and close the file.

Step # 2: Create a password file

Create a plain text username (vivek) and password file:
# vi /home/lighttpd/.lighttpdpassword

Append username:password:


  • vivek – is the name of a user. Please note that do not use a system user stored in /etc/passwd file. It is recommended that you use a different username that only exists for the purpose of authenticating password protected directories.
  • mysecretepassword – is the password for user vivek (must be in clear text format for plain text method)

Save and close the file. Make sure file /home/lighttpd/.lighttpdpassword is readable by lighttpd:
# chown lighttpd:lighttpd /home/lighttpd/.lighttpdpassword

Finally, restart lighttpd server:
# /etc/init.d/lighttpd restart

Step # 3: Test your configuration

Fire your browser and point a web browser to http://yourdomain.com/docs/ or http://localhost/docs/ or http://ip-address/docs. You should be prompted for a username and password.

Lighttpd password dialog

This way you can restrict access to certain areas of your website. Make sure you also use SSL encryption for authenticating users and secure digest authentication.

Share this on:

Your support makes a big difference:
I have a small favor to ask. More people are reading the nixCraft. Many of you block advertising which is your right, and advertising revenues are not sufficient to cover my operating costs. So you can see why I need to ask for your help. The nixCraft, takes a lot of my time and hard work to produce. If you use nixCraft, who likes it, helps me with donations:
Become a Supporter →    Make a contribution via Paypal/Bitcoin →   

Don't Miss Any Linux and Unix Tips

Get nixCraft in your inbox. It's free:

{ 56 comments… add one }
  • Bryan September 6, 2006, 5:53 am


    Great post .I am new to lightTPD and having trouble implementing the changes to the lighttpd.conf file.

    Is there a way you could post the conf in its entirety?



  • nixCraft September 6, 2006, 8:05 am

    You want to see my sample conf file…

  • Bryan September 6, 2006, 4:46 pm

    Yeah, that would be great. I am having a hard time inserting the tutorial items into my existing conf file.

  • nixCraft September 6, 2006, 5:57 pm

    Sorry for trouble. It was CSS code that was causing the problem. It is fixed now. You can now copy and paste instructions. Or just grab my configuration file:


  • Bryan September 7, 2006, 5:58 am

    Thanks, I was able to get it working using your sample as a reference.

  • Fabian October 5, 2006, 11:01 pm

    Do you have somehting like this for samba….??? I can’t get samba to ask for authentication crednetials after having worked on the config file and retsarted the daemon [and also tried restarted the server].

  • Fabian October 10, 2006, 4:47 pm

    As you describe in this detailed post, using plain text password is not secure enough without SSL.

    Question: What about using basic htpasswd or htdigest? Are these susceptible to replay attacks also?


  • nixCraft October 10, 2006, 7:26 pm


    There only 2 methods:
    a) Basic – username nad password in cleartext over the network
    b) Digest – The Digest method only transfers a hashed value over the network hence more secure

    digest onlysupport plaintext or htdigest backend to store username/password information.

    Question: What about using basic htpasswd or htdigest? Are these susceptible to replay attacks also?

    To be frank, your password is more secure as compare to plain text, there are two things you need to consider:
    Not all browser supports digest method (only IE 5.0+, Mozilla/FF 1.0.1. Netscape 7+, Opera4+ etc supports digest)
    Second if an attacker knows http protocol very well he can still find out your password (a rare case)

    In short which ever method you use, get SSL support. You can also use your own SSL certificate if you cannot afford to purchase original one.

  • Hans May 30, 2007, 1:15 pm

    Great article, just what I was looking for. I have everything, except for the Chown command. I get the error message stating that there is no such group (or user) as lighttpd. Hope you can help!

  • nixCraft May 30, 2007, 3:21 pm

    Open your lighttpd config file and find out username and apply the same to .password file

  • Mike July 4, 2007, 2:49 pm

    If you only want to secure a file (not the entire directory), just add the full path information, e.g.:

    auth.require = ( “/docs/secretpage.html” =>
    “method” => “basic”,
    “realm” => “Password protected area”,
    “require” => “user=vivek”

  • Patrick July 8, 2007, 7:59 pm

    Just tried to implement this, however I get stuck at the chown and the restart.(running lighttpd on my dns323)

    So I skipped those and went to:
    ./lighttpd -D -f lighttpd.conf

    Then I get the message:
    can’t handle ‘$HTTP[url] =~ …’ as you compiled without pcre support.
    two questions, what is pcre support, and what do Ihave to put in stead of the [url]


  • nixCraft July 8, 2007, 9:41 pm

    PCRE support requires for perl style regex config option such as $HTTP[url] =~ ‘^/patj/to’ etc

    Please add support package pcre-devel or pcre-lib and recompile lighttpd.

  • kunal July 30, 2007, 2:43 am


    this configuration is not working i m not getting any username or password filed is i try to open the doc folders and its files in the browsers.

    It shows me error 404- File Not Found

    can you explain me why this error is coming

    Thanks in advance

  • kunal July 30, 2007, 3:46 am


    Aforsaid configuration is working now its my fault.
    but now the problem is i have restriced a folder name d as docs in auth.require module and it has a file name as index.htm in it now when ever i run the website in my browser as https://mysite.com/docs/then it will ask me for username and password and after entering the username and password it shows error 404- File Not Found but i have index.htm in the doc folder.

    what is the reason for this error.hope you will reply soon

    Thanks in advance

  • kunal July 30, 2007, 6:37 am


    sorry guys its me again.
    no problem in ur article its fully my fault and i figured out where i was doing wrong.

    sorry again ur tutorial helps me a lot starting from installing and configuring to protecting directories
    i m really thankful to you

    thanks a lot

  • influenza December 28, 2007, 5:38 pm


    I’ve a question regarding all this. I don’t kno if it’s possible at all. My nas uses lighttpd for it’s administrative tasks. I use the build in lighttpd as well to serve some pages etc. Now I want to set a password on a folder. The admin function uses a password already and I want the same, I just want to add my folder that needs password protection. I have been trying to alter the conf file, but with no luck. Maybe you can shed some light on it? conf file pasted below:

    server.document-root = “/usr/www/lib/”
    server.pid-file = “/var/run/lighttpd.pid”
    server.errorlog = “/var/log/lighttpd/error.log”
    dir-listing.activate = “enable”

    server.port = 5000

    server.username = “www-data”
    server.groupname = “www-data”

    server.modules = (

    server.errorfile-prefix = “/usr/www/lib/error-”

    mimetype.assign = (
    “.html” => “text/html”,
    “.txt” => “text/plain”,
    “.jpg” => “image/jpeg”,
    “.png” => “image/png”,
    “.gif” => “image/gif”,
    “.css” => “text/css”

    accesslog.filename = “/var/log/lighttpd/access.log”

    static-file.exclude-extensions = ( “.fcgi”, “.php”, “.rb”, “~”, “.inc”, “.cgi” )
    index-file.names = ( “nasMaster.pl” )

    # bruce – I don’t think we need this now…
    #cgi.assign = ( “.cgi” => “/usr/bin/perl” )

    alias.url = ( “/auth” => “/usr/www/lib” )

    auth.backend = “htdigest”
    auth.backend.htdigest.userfile = “/var/private/lighttpd.htdigest.user”
    auth.require = ( “/auth” =>
    “method” => “digest”,
    “realm” => “nas admin”,
    “require” => “valid-user”
    # bruce – removed user=
    # “require” => “user=admin”



    fastcgi.debug = 0

    # Bruce – Removed host & port and replaced with a socket
    # “host” => “”,
    # “port” => 1026,
    fastcgi.server = ( “.pl” =>
    (( “socket” => “/tmp/lighttpd.fcgi.socket”,
    “bin-path” => “/usr/www/lib/nasMaster.pl”,
    “check-local” => “disable”,
    “min-procs” => 1,
    “max-procs” => 1,
    “idle-timeout” => 30,
    “bin-environment” => (
    # Environment variables for nasMaster.pl
    “PERL5LIB” => “/usr/www/lib”,
    “NAS_NBIN” => “/usr/www/nbin”,
    “nasMaster.pl” => (( “socket” => “/tmp/lighttpd.fcgi.socket”,
    “check-local” => “disable”,

  • Vincent January 21, 2008, 5:46 pm


    I use the htdigest authentication, by adding a line to /var/private/lighttpd.htdigest.user .
    Somehow, this added line is disappearing, so it seems the file is overwritten every now and then.

    Anyone knows when and how?

  • nixCraft January 21, 2008, 6:37 pm


    Make file readonly using chattr or chmod.

  • paul February 7, 2008, 8:03 am

    How do I setup multiple user IDs? This example show only for one “user=vivek”

  • nixCraft February 7, 2008, 10:07 am


    Just append a new user / password


  • nitin February 14, 2008, 1:07 am

    Hi…I have the same problem as influenza. I am trying to add a authentication to my nas (mybook). Has anyone figured this out.

  • pille February 21, 2008, 12:49 pm

    you can add multiple users by sparating them with a tilde.
    “require” => “user=user1|user=user2”

  • ak.from.wf March 7, 2008, 9:36 pm

    Is there a way to suppress directory listings?

  • nixCraft March 8, 2008, 5:34 am

    directory listings can be enabled or disabled using

    server.dir-listing = "enable"

    Turn on listing for /docs/ only:

    $HTTP["url"] =~ "^/docs($|/)" {   server.dir-listing = "enable"   }
  • all2ez July 17, 2008, 7:48 pm

    Thx, this is exactly what I needed to protect my “private” pages on my iPod Touch lighttpd server!

  • mesut July 24, 2008, 1:16 pm


    Is there a way to protect different directories with different password files.

  • hoff August 7, 2008, 3:21 pm


    Is it possible to use lighttpd to authenticate http requests to a specific url instead of a directory? for example, I have a site http://www.example.com that is public facing, but I also have a webservice at service.example.com. Any request to service.example.com gets redirected to an application listening on some other port, not to a directory. I want lighttpd to authenticate any request to service.example.com. How can this be done?

  • FreeBSD4Me August 18, 2008, 6:11 pm

    mesut had a good question. Does anyone know how to password protect different directories with different user/password?

    domain.com/stuff restricted to guest
    domain.com/mystuff restricted to userx


  • FreeBSD4Me August 18, 2008, 6:30 pm

    Here is the answer to the question of authenticating multiple directories with different user/passwd


  • DanielS September 17, 2008, 5:32 am

    Just a quick note as far as step one, a simple command would be lighty-enable-mod auth
    Otherwise Great Post! Thanks!

  • mad December 20, 2008, 8:28 pm


    how can I password protect main folder (server.document-root=/usr/local/www)


  • dikshie January 24, 2009, 3:07 pm

    i just migrate apache to lighttpd. i found i can not find easy and straightforward way
    to enable auth for every users since all my users has .htpassword in public_html
    any straightforward way to enable auth for every /home/$user/public_html/ ?


  • yannick coulombe March 3, 2009, 3:51 pm


    without having to do some more google searches !!

  • Marcus March 24, 2009, 3:28 pm

    Along the lines of what Paul posted, I’m trying to password protect a directory for multiple users. You posted that you should simply append a new user to the end of the /etc/lighttpd/lighttpd.conf file, but I’m confused about the formatting. Should it look like:

    auth.require = ( "/media/" =>
    "method" => "basic",
    "realm" => "Media",
    "require" => "user=user1"
    "require" => "user=user2"

    Or should it look like:

    auth.require = ( "/media/" =>
    "method" => "basic",
    "realm" => "Media",
    "require" => "user=user1|user=user2"


    Also, what should the password file look like in order to do this? Thanks!

  • Clive June 11, 2009, 7:51 pm


    I’m just wondering if password protection is the answer to my problem. I want to only allow files to be downloaded via pages on my website and nowhere else, I can stop hotlinking from other sites with the following:

    $HTTP[“referer”] !~ “^($|http://www\.mydomain\.com)” {
    url.access-deny = ( “.mp3”, “.zip” )

    But that doesnt prevent people from typing the url of a file directly into the browser, they can still download it that way. Is there any other way to prevent this? I’d prefer to just have a 403 forbidden to appear if a file is accessed directly or from another site, but I cant find a solution anywhere so I may consider using a password protected directory.

  • Clive June 11, 2009, 10:59 pm

    yeah thats the second time that has been suggested to me, I should really have said I’ve already looked at mod_secure_download. The php app has to be written to make use of it so it’s not an option. I was hoping for a solution by the webserver only, something to put in the lighttpd.conf file to achieve this but its looking like it isnt possible :(

  • Pep September 5, 2009, 9:15 am

    I followed this how-to. I get it to state, when it says no errors. But authentification still doesn`t work. I would like to describe it more in detail but all I can say is: no errors; web works as before setting authentification; but webpage doesn`t require any username and password. I`ve restarted OpenWRT, which maked no difference.
    Thank you for help.

  • Charlie January 6, 2010, 1:05 am

    My web server is DNS-323 with fun_plug 0,5 and lighttpd
    I have changed the lighttpd.conf to include the following:

    server.modules              = (
                                    "mod_accesslog" )
    server.document-root        = "/mnt/HD_a2/www/pages/"
    $HTTP["url"] =~ "^/Yuemeng/" {
    auth.debug = 2
    auth.backend = "plain"
    auth.backend.plain.userfile = "/mnt/HD_a2/www/pwd/.pwd_Yuemeng"
    auth.require = ( "/Yuemeng/" =>
    	"method" => "basic",
    	"realm" => "Password protected area",
    	"require" => "user=TEST"

    Only one line in the file /mnt/HD_a2/www/pwd/.pwd_Yuemeng

    The “Yuemeng” is sub directory of “/mnt/HD_a2/www/pages/”

    after restart lighttpd, I do got popup window asking for username and password,
    but entering the usename and passwod will not let me to got in the Yuemeng directory. after trying three times, It give me “401 – Unauthorized”

    I could not figure out what is wrong.

    I do not know my server has SSL support or not, Do I need SSL to make it wroks?


    • nixCraft January 6, 2010, 7:59 am

      Check error log and the following debug options and restart lighttpd:
      auth.debug = 2
      Take a look at your error.log for detailed info.

  • Charlie January 6, 2010, 5:38 pm

    Thanks, Vivek.
    I looked the error.log file. The message are password mismatch. I figured out that the problem is with password file “.pwd_Yuemeng”. One user without line feed at the end of line will make it work. However, for two users “user=TEST|user=TEST2”, The password file have two lines, the first line with line feed, the second line without line feed. The first user cannot login, but second folder can login. Do you have any idea to deal with the line feed issue? Can some other symbol to put at the end of line to make it works?

  • Lopes March 1, 2010, 10:33 pm

    Thanks Vivek!

    Just a question how can I protect two folders? Using same user and password?

  • lopes March 1, 2010, 10:44 pm


    How I can use the same password and user for two folder? How I can setup this?

    Many thanks

  • Tapas Mallick March 29, 2010, 9:53 am

    I believe there should have a post on “Access restriction based on IP/Subnet Address” (like: order allow, deny; allow from; deny from all; directives normally used in apache)

  • mahal24 April 15, 2010, 6:02 am

    Can somebody please tell me if Lighttpd supports “GROUP” authentication and if it does how do you configure it? Thanks in advance!

  • Chalai April 30, 2010, 1:10 am

    How to restrict access to a folder/subfolder only?
    Using Apache I can restrict user access to a folder/subfolder only by setting a value for open_basedir and include_path, how do I do that with Lighttpd?

  • kurt krueckeberg April 5, 2011, 2:20 pm

    Great article. The most helpful one I’ve found.

  • przemek June 16, 2011, 7:22 am

    what is domain name? i got index.php as my website in ww folder and how i do domain name?

  • michiel December 8, 2011, 12:40 pm


    I got plain authorization working, but it seems there is a very long timeout before you have to enter login&password again. Is there a way to set it to about 30 minutes or so?

  • shahzaib June 23, 2012, 10:50 am

    does lighttpd supports subdirectories for secure streaming?

  • Nypias August 18, 2012, 9:59 pm

    Thanks a lot for this explanation ;D

  • barul January 13, 2014, 11:59 am

    Thanks a lot for this post! It still works today without any settings change.

  • kulland March 30, 2014, 12:49 am

    How would i set it to ask to the user/pass every time from the same computer or session?

  • Raj December 30, 2014, 5:38 pm

    Thanks for the crisp and clear post. I could get the password protection for the directory but the login credentials currently entered on a popup window. I can create a login page then do I need to enter credentials twice in popup window and login page? Were you able to establish sessions for the user logged in such as automatically logged out after certain inactivity?

  • Dane March 7, 2016, 1:39 am

    if auth is applied to / is there a way to override this to allow anonymous access to a specific file or paths?

Leave a Comment

   Tagged with: , , , , , , , , ,