CouchDB exposes an HTTP API and a web admin interface, so hardening starts with strict network controls and authenticated access. This guide provides security best practices for production deployments.
In local.ini, bind to trusted interfaces only:
[chttpd]
bind_address = 127.0.0.1 ; For single node, or private IP for clusters
port = 5984
Production network pattern:
5984/4369 and Erlang distribution ports between cluster nodes only# Example iptables rules for single node
sudo iptables -A INPUT -p tcp --dport 5984 -s 127.0.0.1 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 5984 -s 10.0.0.0/8 -j ACCEPT # Private network
sudo iptables -A INPUT -p tcp --dport 5984 -j DROP
# For clustered deployments, allow specific node IPs
sudo iptables -A INPUT -p tcp --dport 5984 -s NODE_IP_1 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 5984 -s NODE_IP_2 -j ACCEPT
Create explicit admin accounts and ensure admin party mode is not active:
[admins]
admin = -pbkdf2-xxx,salt,iterations ; Use hashed passwords
Best practices:
_users database for user authenticationDeploy CouchDB behind a reverse proxy with TLS termination:
# Example nginx configuration
server {
listen 443 ssl;
server_name couchdb.example.com;
ssl_certificate /path/to/certificate.crt;
ssl_certificate_key /path/to/private.key;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers off;
location / {
proxy_pass http://127.0.0.1:5984;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
CouchDB can also handle TLS directly, though this is less common:
[ssl]
enable = true
cert_file = /path/to/server-cert.pem
key_file = /path/to/server-key.pem
cacert_file = /path/to/ca-cert.pem
If browser access is required, configure CORS narrowly:
[cors]
enable_cors = false ; Keep disabled unless required
origins = https://yourdomain.com,https://anotherdomain.com ; Specific domains only
credentials = true
headers = accept, authorization, content-type, origin
methods = GET, PUT, POST, HEAD, DELETE
max_age = 3600
Additional API security measures:
For clustered deployments:
/opt/couchdb/etc/vm.args):-setcookie your_secret_cookie
chmod 600 /opt/couchdb/etc/vm.argsSecure file system access:
# Ensure proper ownership and permissions
sudo chown -R couchdb:couchdb /opt/couchdb/
sudo chown -R couchdb:couchdb /var/lib/couchdb/
sudo chown -R couchdb:couchdb /var/log/couchdb/
# Secure configuration files
sudo chmod 600 /opt/couchdb/etc/local.ini
sudo chmod 600 /opt/couchdb/etc/vm.args
Enable logging:
[log]
level = info ; Use 'debug' only temporarily for troubleshooting
writer = file
file = /var/log/couchdb/couchdb.log
Monitor for suspicious activities:
_users and _replicator database access