← Full reference

htpasswd

A login and password file for HTTP Basic auth — creating, bcrypt, deleting, verifying, nginx auth_basic

htpasswd (package apache2-utils) maintains a file of login:password_hash lines — one line per user. Apache and nginx (auth_basic_user_file) read such a file to put part of a site behind a password. The password itself isn't stored in the file — only its hash.

Syntax

htpasswd [-c] [-B] file user            # asks for the password twice
htpasswd -b [-c] [-B] file user password  # password from the command line
htpasswd -n[b] [-B] user [password]       # don't touch the file, print the line
htpasswd -D file user                   # delete
htpasswd -v[b] file user [password]       # verify the password

Without -c the file must already exist; the user is added to it or their password is changed.

Options

What to do

OptionWhat it does
-ccreate the file; if it exists — overwrite it from scratch
-ndon't touch the file, print the login:hash line to stdout
-Ddelete a user
-vverify a user's password: code 0 — correct, 3 — not

Where the password comes from

OptionWhat it does
(none)ask twice in the terminal
-btake it from the last argument (visible in ps and shell history)
-iread from stdin, without repeating — for scripts

Hash algorithm

OptionHashPrefix in the file
-mApache's MD5 variant (default)$apr1$
-Bbcrypt — recommended$2y$
-C Nbcrypt "cost", 4–17 (default 5); higher — slower brute force
-sunsalted SHA-1, insecure{SHA}
-dold crypt, password truncated to 8 characters
-pplain text — don't use

Exit codes

CodeMeaning
0success
1file problem: no file without -c, no permissions
2command line syntax error
3password mismatch (with -v or when re-entering)
5value too long
6invalid character in the name (e.g. :)
7the file doesn't look like a password file

nginx: auth_basic

location /admin/ {
    auth_basic           "Restricted";            # text in the browser dialog
    auth_basic_user_file /etc/nginx/.htpasswd;    # file from htpasswd
}

auth_basic off; in a nested location removes the protection. After editing the config: nginx -t && nginx -s reload. nginx rereads the password file itself on every request — no reload is needed after htpasswd.

Examples

# create a file with the first user, bcrypt, prompts for the password
htpasswd -c -B /etc/nginx/.htpasswd alice

# add another one (without -c!), password in the argument
htpasswd -B -b /etc/nginx/.htpasswd bob 'S3cret!'

# password from stdin — doesn't show up in the process list
printf '%s\n' "$PASS" | htpasswd -i -B /etc/nginx/.htpasswd carol

# change a password — the same command as adding
htpasswd -B /etc/nginx/.htpasswd alice

# delete a user
htpasswd -D /etc/nginx/.htpasswd bob

# verify a password
htpasswd -v -b /etc/nginx/.htpasswd alice 'S3cret!' && echo correct

# get the line without touching the file (e.g. for a Kubernetes Secret)
htpasswd -nbB alice 'S3cret!'

# test the protection: 401 without a password, 200 with it
curl -s -o /dev/null -w '%{http_code}\n' http://localhost/admin/
curl -s -o /dev/null -w '%{http_code}\n' -u alice:'S3cret!' http://localhost/admin/

Pitfalls

  • -c on an existing file wipes all users. Add new ones without -c.
  • The default is MD5 ($apr1$), not bcrypt. For new files specify -B explicitly.
  • The file must be readable by nginx workers (user www-data). With 600 permissions and root as owner, nginx returns 500, and error.log shows open() "…/.htpasswd" failed (13: Permission denied). 640 with group www-data, or 644, will do.
  • 401 and 500 are different problems. 401 — wrong login or password (in error.log: password mismatch or user … was not found); 500 — nginx couldn't read the file.
  • -D of a nonexistent user returns 0 and only prints User … not found. Don't rely on the exit code.
  • -b leaves the password in the shell history and in ps. Use -i in scripts.
  • -n prints an extra empty line after the entry — remove it when copying into a config or YAML.
  • A colon in the name is forbidden — it's the field separator (username contains illegal character ':', code 6).
  • Basic auth without HTTPS sends the password almost in plain text (base64). Protect only what goes over TLS or an internal network this way.

See also

nginx · curl · openssl · base64 · chmod · ab