httpauth Command - Webinoly

Overview

The httpauth command manages HTTP Basic Authentication (username/password protection) for your sites. Secure entire sites, WordPress admin areas, or specific URL paths.

Basic Usage

sudo httpauth [domain] <option> <argument>

Managing Users

Add User

Add HTTP authentication user:

# Global user (interactive)
sudo httpauth -add

# Site-specific user (interactive)
sudo httpauth example.com -add

# Unattended mode
sudo httpauth -add=[username,password]
sudo httpauth example.com -add=[username,password]

-add

string

Add user:

true - Interactive mode (prompts for credentials)
[username,password] - Unattended mode with credentials

Example:

# Interactive
sudo httpauth -add
# Prompts:
# HTTP-Auth User: admin
# HTTP-Auth Password: ********

# Unattended
sudo httpauth -add=[admin,secretpass123]

Usernames cannot contain colons (:)
Passwords cannot contain colons (:)
Global users work on all sites
Site-specific users only work on that domain

List Users

List authentication users:

# List global users
sudo httpauth -list

# List site-specific users
sudo httpauth example.com -list

Example output:

+ admin
+ developer
+ john

Delete User

Remove authentication user:

# Interactive
sudo httpauth -delete

# Direct
sudo httpauth -delete=username
sudo httpauth example.com -delete=username

-delete

string

Delete user:

true - Prompts for username
username - Delete specific user

WordPress Admin Protection

Enable/Disable Global WP-Admin Auth

Set default for all new WordPress sites:

# Enable for all new WP sites
sudo httpauth -wp-admin=on

# Disable for all new WP sites
sudo httpauth -wp-admin=off

This setting only affects new WordPress installations. Existing sites are not changed.

Enable/Disable Per-Site WP-Admin Auth

Control WordPress admin authentication for specific sites:

# Enable for site
sudo httpauth example.com -wp-admin=on

# Disable for site
sudo httpauth example.com -wp-admin=off

# Enable for subfolder installation
sudo httpauth example.com -wp-admin=on -subfolder=/blog

-wp-admin

string

WordPress admin authentication:

on - Enable HTTP auth for /wp-admin/ and wp-login.php
off - Disable HTTP auth for WordPress admin

Protected paths when enabled:

/wp-admin/ (WordPress admin dashboard)
/wp-login.php (WordPress login page)

You must create at least one HTTP auth user (global or site-specific) before enabling WP-Admin protection.

Path Protection

Protect URL Path

Add HTTP authentication to specific URL paths:

# Protect path (interactive)
sudo httpauth example.com -path

# Protect specific path
sudo httpauth example.com -path=/admin

# Protect with exact match only
sudo httpauth example.com -path=/api/auth -exact

# Protect entire site
sudo httpauth example.com -path=/

-path

string

URL path to protect:

true - Interactive mode (prompts for path)
/path - Specific URL path
/ - Entire site

-exact

boolean

Exact path match only (don’t match prefixes)

Path matching: Without -exact:

sudo httpauth example.com -path=/admin
# Protects:
# /admin
# /admin/
# /admin/users
# /admin/settings/security

With -exact:

sudo httpauth example.com -path=/api/auth -exact
# Protects only:
# /api/auth
# Does NOT protect:
# /api/auth/
# /api/auth/login

Reserved Paths

These paths cannot be protected (already handled by WordPress config): Regular paths:

/wp-admin
/wp-content/uploads/

Exact paths:

/favicon.ico
/robots.txt
/wp-login.php
/wp-config.txt

List Protected Paths

View all protected paths for a site:

sudo httpauth example.com -list=protected

Example output:

+ /
+ /admin
+ /api/v1 (Exact)
+ /secret/area

Remove Path Protection

Remove HTTP authentication from paths:

# Interactive
sudo httpauth example.com -path -delete

# Remove specific path
sudo httpauth example.com -path=/admin -delete

# Remove entire site protection
sudo httpauth example.com -path=/ -delete

# Remove all protected paths
sudo httpauth example.com -path -delete-all

Force delete all (no confirmation):

sudo httpauth example.com -path -delete-all=force

IP Whitelist

Allow specific IP addresses to bypass HTTP authentication:

Add to Whitelist

# Interactive
sudo httpauth -whitelist

# Add specific IP
sudo httpauth -whitelist=192.168.1.100

# Add multiple IPs
sudo httpauth -whitelist=192.168.1.100,192.168.1.101,192.168.1.102

# Add IP range (CIDR)
sudo httpauth -whitelist=192.168.1.0/24

-whitelist

string

IP address to whitelist:

true - Interactive mode
IP_ADDRESS - Single IP (e.g., 192.168.1.100)
IP,IP,IP - Multiple IPs comma-separated
CIDR - IP range (e.g., 192.168.1.0/24)

List Whitelisted IPs

sudo httpauth -whitelist -list

Example output:

+ 192.168.1.100
+ 192.168.1.101
+ 10.0.0.0/8
+ 2001:db8::1

Remove from Whitelist

# Interactive
sudo httpauth -whitelist -delete

# Remove specific IP
sudo httpauth -whitelist=192.168.1.100 -delete

# Remove multiple IPs
sudo httpauth -whitelist=192.168.1.100,192.168.1.101 -delete

# Remove all whitelisted IPs
sudo httpauth -whitelist -delete-all

# Force remove all (no confirmation)
sudo httpauth -whitelist -delete-all=force

Whitelist applies globally to all sites and paths. Whitelisted IPs bypass all HTTP authentication.

Subfolder Support

HTTP authentication works with WordPress subfolder installations:

# Add user for subfolder
sudo httpauth example.com -add -subfolder=/blog

# Enable WP-Admin auth for subfolder
sudo httpauth example.com -wp-admin=on -subfolder=/blog

# Protect path in subfolder context
sudo httpauth example.com -path=/api -subfolder=/blog

Subfolder support is only available for -wp-admin and -path options.

File Locations

Global Auth File

/etc/nginx/.htpasswd

Stores global HTTP auth users (work on all sites).

Site-Specific Auth Files

/etc/nginx/apps.d/.htpasswd-example.com
/etc/nginx/apps.d/.htpasswd-www.example.com

Stores site-specific users.

Whitelist Configuration

/etc/nginx/apps.d/whitelist-acl.conf

Contains whitelisted IP addresses.

Path Protection Configurations

/etc/nginx/apps.d/[domain]-nginx.conf

Custom Nginx configuration for protected paths.

Examples

Secure WordPress Admin

# Create admin user
sudo httpauth example.com -add=[admin,strongpass123]

# Enable WP-Admin protection
sudo httpauth example.com -wp-admin=on

# Whitelist your office IP
sudo httpauth -whitelist=203.0.113.100

Protect Staging Site

# Create staging user
sudo httpauth staging.example.com -add=[developer,devpass456]

# Protect entire site
sudo httpauth staging.example.com -path=/

Secure API Endpoints

# Create API user
sudo httpauth api.example.com -add=[apiuser,secretkey789]

# Protect API paths
sudo httpauth api.example.com -path=/v1/admin
sudo httpauth api.example.com -path=/v1/users

# Whitelist application server
sudo httpauth -whitelist=10.0.1.50

Development Environment

# Add developer users
sudo httpauth dev.example.com -add=[alice,alicepass]
sudo httpauth dev.example.com -add=[bob,bobpass]

# Protect entire dev site
sudo httpauth dev.example.com -path=/

# Whitelist local network
sudo httpauth -whitelist=192.168.1.0/24

Multi-User Setup

# Add multiple users
sudo httpauth example.com -add=[admin,pass1]
sudo httpauth example.com -add=[editor,pass2]
sudo httpauth example.com -add=[developer,pass3]

# List users
sudo httpauth example.com -list

# Enable for WP admin
sudo httpauth example.com -wp-admin=on

Security Best Practices

Strong Passwords

Use strong, unique passwords for HTTP auth users:

# Good: Random, long password
sudo httpauth -add=[admin,9Kf$mL2@pNx7qRt!]

# Bad: Weak password
sudo httpauth -add=[admin,password123]

IP Whitelisting

Combine HTTP auth with IP whitelisting:

# Protect admin area
sudo httpauth example.com -path=/admin

# Only allow from trusted IPs
sudo httpauth -whitelist=203.0.113.0/24

Layer Security

Use HTTP auth as an additional layer, not the only security:

# Layer 1: Firewall (limit SSH, etc.)
# Layer 2: HTTP Auth
sudo httpauth example.com -wp-admin=on
# Layer 3: WordPress login
# Layer 4: Two-factor authentication

Regular Audits

# Review users periodically
sudo httpauth -list
sudo httpauth example.com -list

# Review protected paths
sudo httpauth example.com -list=protected

# Review whitelist
sudo httpauth -whitelist -list

Troubleshooting

Authentication Not Working

Check if users exist:
```
sudo httpauth example.com -list
```

Verify path protection:

sudo httpauth example.com -list=protected

Check Nginx config:

sudo nginx -t
cat /etc/nginx/sites-available/example.com

Check auth file:

sudo cat /etc/nginx/apps.d/.htpasswd-example.com

Locked Out

If you’re locked out and can’t authenticate:

# Disable WP-Admin auth
sudo httpauth example.com -wp-admin=off

# Or remove path protection
sudo httpauth example.com -path=/ -delete

# Reload Nginx
sudo systemctl reload nginx

Whitelist Not Working

Check whitelist file:

sudo cat /etc/nginx/apps.d/whitelist-acl.conf

Verify IP format:

# Should look like:
allow 192.168.1.100;
allow 10.0.0.0/8;

Test Nginx config:
```
sudo nginx -t
```

Notes

All commands require sudo (root privileges)
HTTP auth uses the standard HTTP Basic Authentication protocol
Passwords are encrypted with OpenSSL before storage
Nginx is automatically reloaded after configuration changes
Global users can authenticate on any site
Site-specific users only work on their designated site
Whitelist is global and affects all sites
Use -help to see all available options

Commands

Options Reference

​Overview

​Basic Usage

​Managing Users

​Add User

​List Users

​Delete User

​WordPress Admin Protection

​Enable/Disable Global WP-Admin Auth

​Enable/Disable Per-Site WP-Admin Auth

​Path Protection

​Protect URL Path

​Reserved Paths

​List Protected Paths

​Remove Path Protection

​IP Whitelist

​Add to Whitelist

​List Whitelisted IPs

​Remove from Whitelist

​Subfolder Support

​File Locations

​Global Auth File

​Site-Specific Auth Files

​Whitelist Configuration

​Path Protection Configurations

​Examples

​Secure WordPress Admin

​Protect Staging Site

​Secure API Endpoints

​Development Environment

​Multi-User Setup

​Security Best Practices

​Strong Passwords

​IP Whitelisting

​Layer Security

​Regular Audits

​Troubleshooting

​Authentication Not Working

​Locked Out

​Whitelist Not Working

​Notes

​See Also

Build docs developers (and LLMs) love

Overview

Basic Usage

Managing Users

Add User

List Users

Delete User

WordPress Admin Protection

Enable/Disable Global WP-Admin Auth

Enable/Disable Per-Site WP-Admin Auth

Path Protection

Protect URL Path

Reserved Paths

List Protected Paths

Remove Path Protection

IP Whitelist

Add to Whitelist

List Whitelisted IPs

Remove from Whitelist

Subfolder Support

File Locations

Global Auth File

Site-Specific Auth Files

Whitelist Configuration

Path Protection Configurations

Examples

Secure WordPress Admin

Protect Staging Site

Secure API Endpoints

Development Environment

Multi-User Setup

Security Best Practices

Strong Passwords

IP Whitelisting

Layer Security

Regular Audits

Troubleshooting

Authentication Not Working

Locked Out

Whitelist Not Working

Notes

See Also