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
| Option | What it does |
|---|---|
-c | create the file; if it exists — overwrite it from scratch |
-n | don't touch the file, print the login:hash line to stdout |
-D | delete a user |
-v | verify a user's password: code 0 — correct, 3 — not |
Where the password comes from
| Option | What it does |
|---|---|
| (none) | ask twice in the terminal |
-b | take it from the last argument (visible in ps and shell history) |
-i | read from stdin, without repeating — for scripts |
Hash algorithm
| Option | Hash | Prefix in the file |
|---|---|---|
-m | Apache's MD5 variant (default) | $apr1$ |
-B | bcrypt — recommended | $2y$ |
-C N | bcrypt "cost", 4–17 (default 5); higher — slower brute force | |
-s | unsalted SHA-1, insecure | {SHA} |
-d | old crypt, password truncated to 8 characters | |
-p | plain text — don't use |
Exit codes
| Code | Meaning |
|---|---|
0 | success |
1 | file problem: no file without -c, no permissions |
2 | command line syntax error |
3 | password mismatch (with -v or when re-entering) |
5 | value too long |
6 | invalid character in the name (e.g. :) |
7 | the 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
-con an existing file wipes all users. Add new ones without-c.- The default is MD5 (
$apr1$), not bcrypt. For new files specify-Bexplicitly. - The file must be readable by nginx workers (user
www-data). With600permissions and root as owner, nginx returns500, anderror.logshowsopen() "…/.htpasswd" failed (13: Permission denied).640with groupwww-data, or644, will do. 401and500are different problems.401— wrong login or password (inerror.log:password mismatchoruser … was not found);500— nginx couldn't read the file.-Dof a nonexistent user returns0and only printsUser … not found. Don't rely on the exit code.-bleaves the password in the shell history and inps. Use-iin scripts.-nprints 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 ':', code6). - Basic auth without HTTPS sends the password almost in plain text (base64). Protect only what goes over TLS or an internal network this way.