≡ Menu

Lighttpd secure digest authentication (mod_auth)

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 (http://domain.com/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 http://domain.com/docs/ 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.

Share this on:

{ 16 comments… add one }

  • Thai Mai July 5, 2007, 1:49 pm

    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.

  • nixCraft July 5, 2007, 3:16 pm


    Opps, sorry for typo, post has been updated.

    Appreciate your post!

  • kunal July 27, 2007, 9:05 am

    if i have some fils in the http folder and in browser i write http://mydomain.com/http/some.jpg

    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

  • anon January 31, 2008, 8:13 am

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

  • mumuri May 18, 2008, 2:26 pm

    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

  • peter July 22, 2008, 10:52 am

    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

  • nixCraft July 22, 2008, 12:33 pm


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

  • Peter July 22, 2008, 6:32 pm

    # 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

  • nixCraft July 22, 2008, 8:07 pm

    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.

  • Peter July 22, 2008, 8:38 pm

    # 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

  • max October 5, 2008, 1:15 pm

    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

    • Starbeamrainbowlabs November 2, 2014, 2:54 pm

      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.

  • George February 28, 2009, 1:54 pm

    apt-get install apache2-utils

    to get htdigest.

  • Lindon July 8, 2011, 7:26 pm


    is php needed for this to work?

  • Sandeep April 22, 2013, 6:26 am

    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.

  • Starbeamrainbowlabs November 2, 2014, 2:55 pm

    An alternative to the htdigest command found in apache2-utils can be found on this page: http://redmine.lighttpd.net/projects/1/wiki/Docs_ModAuth

Leave a Comment