Lighttpd secure digest authentication (mod_auth)

last updated in Categories lighttpd, Security
Lighttpd logo

This method transfers the username and the password in cleartext over the network (base64 encoded) and might result in security problems if not used in conjunction with a crypted channel between client and server.


The Digest method only transfers a hashed value over the network which performs a lot of work to harden the authentication process in insecure networks.

There are total three steps to configure Lighttpd secure digest authentication:
=> Setup username and password using htdigest (Apache program)
=> Configure lighttpd core directives
=> Apply restrictions to selected directories aka set password protected directory

Step # 1: Setup username and password using htdigest (Apache program)

Command htdigest is used to create and update the flat-files used to store usernames, realm and password for digest authentication of HTTP users. Genreal syntax is as follows:
htdigest -c /path/to/password/file ‘Realm’ username

For example add a user called tom:
# htdigest -c /etc/lighttpd/.passwd 'Authorized users only' tom


  • -c: Create the /etc/lighttpd/.passwd
  • /etc/lighttpd/.passwd: Password file name. It contain the username, realm and password. If -c is given, this file is created if it does not already exist, or deleted and recreated if it does exist.
  • ‘Authorized users only’: The realm name to which the user name belongs
  • tom: The user name (tom) to create or update in /etc/lighttpd/.passwd. If username does not exist is this file, an entry is added. If it does exist, the password is changed.

Step # 2: Configure lighttpd core directives

Open /etc/lighttpd.conf file.# vi /etc/lighttpd.confMake sure mod_auth is loaded:
server.modules += ( "mod_auth" )Now, append following 3 lines:
auth.backend = "htdigest"
auth.backend.htdigest.userfile = "/etc/lighttpd/.passwd"
auth.debug = 2

Step # 3: Apply restrictions to selected directories aka set password protected directory
Let us say you would like to protect directory called /docs ( Append following directives (/etc/lighttpd.conf file):
auth.require = ( "/docs/" =>
"method" => "digest",
"realm" => "Authorized users only",
"require" => "valid-user"

Save and close the file.

Restart the lighttpd:
# /etc/init.d/lighttpd restart

You can always find more debugging information in your error log file -/var/log/lighttpd/error.log:
# tail -f /var/log/lighttpd/error.log

Point a web browser to or http://localhost/docs/ or http://ip-address/docs. You should be prompted for a username (for e.g. tom) and password (your password).

For additional security it is recommended that you use SSL configuration.


Posted by: Vivek Gite

The author is the creator of nixCraft and a seasoned sysadmin, DevOps engineer, and a trainer for the Linux operating system/Unix shell scripting. Get the latest tutorials on SysAdmin, Linux/Unix and open source topics via RSS/XML feed or weekly email newsletter.

17 comment

  1. Great article. Works after one small type correction.

    you wrote:

    auth.backend.htdigest.userfile = "/etc/lighttpd/.passwd "

    I copied and pasted the above and couldn’t restart lighttpd. There’s a space after .passed and before the ending quote. Removing the space, lighty started fine.

    Thanks for this tutorial and all the others.

  2. hi,
    if i have some fils in the http folder and in browser i write

    it gives me an error 404 not found and in have done secure digest authentication on the http folder

    why i m getting this problem i m not able to figure it out.

    please help me. Thanks in advance

  3. Unfortunately lighttpd still doesnt write meaningful entries into error.log on failed logins so its hard to check for wordbook attacks etc.

  4. htdigest is available on apache2-utils, if you don’t have it, you can install it by this cmd on debian system

    apt-get install apache2-utils

  5. what should be the correct unix permissions for .passwd?

    I’m getting this error:
    2008-07-22 11:44:23: (http_auth.c.151) opening digest-userfile /etc/lighttpd/.passwd failed: Permission denied

  6. Peter,

    You should set permission to lighttpd or www i.e. lighttpd server username using chmod command.

  7. # ls -la /etc/lighttpd/
    drw-r—– 2 www www 512 Jul 22 19:16 .
    drwxr-xr-x 21 root wheel 2048 Jul 21 14:30 ..
    -rw-r–r– 1 www www 60 Jul 22 19:16 .passwd

    # tail -f /var/log/lighttpd.error.log
    2008-07-22 19:27:50: (http_auth.c.1002) username xpto
    2008-07-22 19:27:50: (http_auth.c.1003) realm Authorized users only
    2008-07-22 19:27:50: (http_auth.c.1004) nonce 27292a400655857236e04710538278ba
    2008-07-22 19:27:50: (http_auth.c.1005) uri /wordpress/wp-admin/
    2008-07-22 19:27:50: (http_auth.c.1006) algorigthm MD5
    2008-07-22 19:27:50: (http_auth.c.1007) qop auth
    2008-07-22 19:27:50: (http_auth.c.1008) cnonce 21nkwLwMcFj1CHbiIF9IzfvpLzHgiNpzNzZEJzptCcW=
    2008-07-22 19:27:50: (http_auth.c.1009) nc 00000001
    2008-07-22 19:27:50: (http_auth.c.1010) response 96649fb136d6c4fc4bfd21e13a7d7f23
    2008-07-22 19:27:50: (http_auth.c.151) opening digest-userfile /etc/lighttpd/.passwd failed: Permission denied

  8. What is output of the following command?
    grep -i server.username /etc/lighttpd/lighttpd.conf
    You need to use that username, also make sure, /etc/lighttpd also owned by that user.

  9. # grep -i server.username /usr/local/etc/lighttpd.conf
    server.username = “www”

    I created the .passwd on another machine running apache, but I think that’s not the cause of this error

  10. When we do this is there any way to prevent browser pop-up ..i want to process response in my javascript but 401 gives control to browser.

    Is any alternative to get nonce &pass it to javascript (like creating socket & GET request on server side with cgi & then changing 401 code to something random). I want gui of my javascript.

    Please reply

    1. You would need to write a login script manually with PHP in order to do that as far as I know, it is the browser makers who control what the login box looks like with this method.

  11. Hi I am able to setup the wholw thing and the site is asking for authentication. Now the problem is I want to change the appearance of the authentication dialog box. So can anyone help me find where exactly the call point for this dialog box is present, so that i can map my dialog box to it.

    Have a question? Post it on our forum!