3.3. CouchDB HTTP Server

3.3.1. HTTP Server Options

[httpd]

allow_jsonp

The true value of this option enables JSONP support (it’s false by default):

[httpd]
allow_jsonp = false

authentication_handlers

List of used authentication handlers that used by CouchDB. You may extend them via third-party plugins or remove some of them if you won’t let users to use one of provided methods:

[httpd]
authentication_handlers = {couch_httpd_oauth, oauth_authentication_handler}, {couch_httpd_auth, cookie_authentication_handler}, {couch_httpd_auth, default_authentication_handler}

• {couch_httpd_oauth, oauth_authentication_handler}: handles OAuth;
• {couch_httpd_auth, cookie_authentication_handler}: used for Cookie auth;
• {couch_httpd_auth, proxy_authentication_handler}: used for Proxy auth;
• {couch_httpd_auth, default_authentication_handler}: used for Basic auth;
• {couch_httpd_auth, null_authentication_handler}: disables auth. Everlasting Admin Party!

bind_address

Defines the IP address by which CouchDB will be accessible:

[httpd]
bind_address = 127.0.0.1

To let CouchDB listen any available IP address, just set up 0.0.0.0 value:

[httpd]
bind_address = 0.0.0.0

For IPv6 support you need to set ::1 if you want to let CouchDB listen local address:

[httpd]
bind_address = ::1

or :: for any available:

[httpd]
bind_address = ::

changes_timeout

Specifies default timeout value for Changes Feed in milliseconds (60000 by default):

[httpd]
changes_feed = 60000 ; 60 seconds

config_whitelist

Sets the configuration modification whitelist. Only whitelisted values may be changed via the config API. To allow the admin to change this value over HTTP, remember to include {httpd,config_whitelist} itself. Excluding it from the list would require editing this file to update the whitelist:

[httpd]
config_whitelist = [{httpd,config_whitelist}, {log,level}, {etc,etc}]

default_handler

Specifies default HTTP requests handler:

[httpd]
default_handler = {couch_httpd_db, handle_request}

enable_cors

New in version 1.3.

Controls CORS feature:

[httpd]
enable_cors = false

log_max_chunk_size

Defines maximum chunk size in bytes for _log resource:

[httpd]
log_max_chunk_size = 1000000

port

Defined the port number to listen:

[httpd]
port = 5984

To let CouchDB handle any free port, set this option to 0:

[httpd]
port = 0

After that, CouchDB URI could be located within the URI file.

redirect_vhost_handler

This option customizes the default function that handles requests to virtual hosts:

[httpd]
redirect_vhost_handler = {Module, Fun}

The specified function take 2 arguments: the Mochiweb request object and the target path.

server_options

Server options for the MochiWeb component of CouchDB can be added to the configuration files:

[httpd]
server_options = [{backlog, 128}, {acceptor_pool_size, 16}]

secure_rewrites

This option allow to isolate databases via subdomains:

[httpd]
secure_rewrites = true

socket_options

The socket options for the listening socket in CouchDB can be specified as a list of tuples. For example:

[httpd]
socket_options = [{recbuf, 262144}, {sndbuf, 262144}, {nodelay, true}]

The options supported are a subset of full options supported by the TCP/IP stack. A list of the supported options are provided in the Erlang inet documentation.

vhost_global_handlers

List of global handlers that are available for virtual hosts:

[httpd]
vhost_global_handlers = _utils, _uuids, _session, _oauth, _users

x_forwarded_host

The x_forwarded_host header (X-Forwarded-Host by default) is used to forward the original value of the Host header field in case, for example, if a reverse proxy is rewriting the “Host” header field to some internal host name before forward the request to CouchDB:

[httpd]
x_forwarded_host = X-Forwarded-Host

This header has higher priority above Host one, if only it exists in the request.

x_forwarded_proto

x_forwarded_proto header (X-Forwarder-Proto by default) is used for identifying the originating protocol of an HTTP request, since a reverse proxy may communicate with CouchDB instance using HTTP even if the request to the reverse proxy is HTTPS:

[httpd]
x_forwarded_proto = X-Forwarded-Proto

x_forwarded_ssl

The x_forwarded_ssl header (X-Forwarded-Ssl by default) tells CouchDB that it should use the https scheme instead of the http. Actually, it’s a synonym for X-Forwarded-Proto: https header, but used by some reverse proxies:

[httpd]
x_forwarded_ssl = X-Forwarded-Ssl

WWW-Authenticate

Set this option to trigger basic-auth popup on unauthorized requests:

[httpd]
WWW-Authenticate = Basic realm="Welcome to the Couch!"

3.3.2. Secure Socket Level Options

[ssl]

CouchDB supports SSL natively. All your secure connection needs can now be served without needing to set up and maintain a separate proxy server that handles SSL.

SSL setup can be tricky, but the configuration in CouchDB was designed to be as easy as possible. All you need is two files; a certificate and a private key. If you bought an official SSL certificate from a certificate authority, both should be in your possession already.

If you just want to try this out and don’t want to pay anything upfront, you can create a self-signed certificate. Everything will work the same, but clients will get a warning about an insecure certificate.

You will need the OpenSSL command line tool installed. It probably already is.

shell> mkdir /etc/couchdb/cert
shell> cd /etc/couchdb/cert
shell> openssl genrsa > privkey.pem
shell> openssl req -new -x509 -key privkey.pem -out couchdb.pem -days 1095
shell> chmod 600 privkey.pem couchdb.pem
shell> chown couchdb privkey.pem couchdb.pem

Now, you need to edit CouchDB’s configuration, either by editing your local.ini file or using the /_config API calls or the configuration screen in Futon. Here is what you need to do in local.ini, you can infer what needs doing in the other places.

At first, enable the HTTPS daemon:

[daemons]
httpsd = {couch_httpd, start_link, [https]}

Next, under the [ssl] section set up the newly generated certificates:

[ssl]
cert_file = /etc/couchdb/cert/couchdb.pem
key_file = /etc/couchdb/cert/privkey.pem

For more information please read certificates HOWTO.

Now start (or restart) CouchDB. You should be able to connect to it using HTTPS on port 6984:

shell> curl https://127.0.0.1:6984/
curl: (60) SSL certificate problem, verify that the CA cert is OK. Details:
error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed
More details here: http://curl.haxx.se/docs/sslcerts.html

curl performs SSL certificate verification by default, using a "bundle"
of Certificate Authority (CA) public keys (CA certs). If the default
bundle file isn't adequate, you can specify an alternate file
using the --cacert option.
If this HTTPS server uses a certificate signed by a CA represented in
the bundle, the certificate verification probably failed due to a
problem with the certificate (it might be expired, or the name might
not match the domain name in the URL).
If you'd like to turn off curl's verification of the certificate, use
the -k (or --insecure) option.

Oh no! What happened?! Remember, clients will notify their users that your certificate is self signed. curl is the client in this case and it notifies you. Luckily you trust yourself (don’t you?) and you can specify the -k option as the message reads:

shell> curl -k https://127.0.0.1:6984/
{"couchdb":"Welcome","version":"1.5.0"}

All done.

cacert_file

The path to a file containing PEM encoded CA certificates. The CA certificates are used to build the server certificate chain, and for client authentication. Also the CAs are used in the list of acceptable client CAs passed to the client when a certificate is requested. May be omitted if there is no need to verify the client and if there are not any intermediate CAs for the server certificate:

[ssl]
cacert_file = /etc/ssl/certs/ca-certificates.crt

cert_file

Path to a file containing the user’s certificate:

[ssl]
cert_file = /etc/couchdb/cert/couchdb.pem

key_file

Path to file containing user’s private PEM encoded key:

[ssl]
key_file = /etc/couchdb/cert/privkey.pem

password

String containing the user’s password. Only used if the private keyfile is password protected:

[ssl]
password = somepassword

ssl_certificate_max_depth

Maximum peer certificate depth (must be set even if certificate validation is off):

[ssl]
ssl_certificate_max_depth = 1

verify_fun

The verification fun (optional) if not specified, the default verification fun will be used:

[ssl]
verify_fun = {Module, VerifyFun}

verify_ssl_certificates

Set to true to validate peer certificates:

[ssl]
verify_ssl_certificates = false

fail_if_no_peer_cert

Set to true to terminate the TLS/SSL handshake with a handshake_failure alert message if the client does not send a certificate. Only used if verify_ssl_certificates is true. If set to false it will only fail if the client sends an invalid certificate (an empty certificate is considered valid):

[ssl]
fail_if_no_peer_cert = false

secure_renegotiate

Set to true to reject renegotiation attempt that does not live up to RFC 5746:

[ssl]
secure_renegotiate = true

ciphers

Set to the cipher suites that should be supported which can be specified in erlang format “{ecdhe_ecdsa,aes_128_cbc,sha256}” or in OpenSSL format “ECDHE-ECDSA-AES128-SHA256”.

[ssl]
ciphers = ["ECDHE-ECDSA-AES128-SHA256", "ECDHE-ECDSA-AES128-SHA"]

tls_versions

Set to a list of permitted SSL/TLS protocol versions:

[ssl]
tls_versions = [tlsv1 | 'tlsv1.1' | 'tlsv1.2']

3.3.3. Cross-Origin Resource Sharing

[cors]

New in version 1.3: added CORS support, see JIRA COUCHDB-431

CORS, or “Cross-Origin Resource Sharing”, allows a resource such as a web page running JavaScript inside a browser, to make AJAX requests (XMLHttpRequests) to a different domain, without compromising the security of either party.

A typical use case is to have a static website hosted on a CDN make requests to another resource, such as a hosted CouchDB instance. This avoids needing an intermediary proxy, using JSONP or similar workarounds to retrieve and host content.

While CouchDB’s integrated HTTP server has support for document attachments makes this less of a constraint for pure CouchDB projects, there are many cases where separating the static content from the database access is desirable, and CORS makes this very straightforward.

By supporting CORS functionality, a CouchDB instance can accept direct connections to protected databases and instances, without the browser functionality being blocked due to same-origin constraints. CORS is supported today on over 90% of recent browsers.

CORS support is provided as experimental functionality in 1.3, and as such will need to be enabled specifically in CouchDB’s configuration. While all origins are forbidden from making requests by default, support is available for simple requests, preflight requests and per-vhost configuration.

This section requires httpd/enable_cors option have true value:

[httpd]
enable_cors = true

credentials

By default, neither authentication headers nor cookies are included in requests and responses. To do so requires both setting XmlHttpRequest.withCredentials = true on the request object in the browser and enabling credentials support in CouchDB.

[cors]
credentials = true

CouchDB will respond to a credentials-enabled CORS request with an additional header, Access-Control-Allow-Credentials=true.

origins

List of origins separated by a comma, * means accept all. You can’t set origins = * and credentials = true option at the same time:

[cors]
origins = *

Access can be restricted by protocol, host and optionally by port. Origins must follow the scheme: http://example.com:80:

[cors]
origins = http://localhost, https://localhost, http://couch.mydev.name:8080

Note that by default, no origins are accepted. You must define them explicitly.

headers

List of accepted headers separated by a comma:

[cors]
headers = X-Couch-Id, X-Couch-Rev

methods

List of accepted methods:

[cors]
methods = GET,POST

See also

Original JIRA implementation ticket

Standards and References:

• IETF RFCs relating to methods: RFC 2618, RFC 2817, RFC 5789
• IETF RFC for Web Origins: RFC 6454
• W3C CORS standard

Mozilla Developer Network Resources:

• Same origin policy for URIs
• HTTP Access Control
• Server-side Access Control
• JavaScript same origin policy

Client-side CORS support and usage:

• CORS browser support matrix
• COS tutorial
• XHR with CORS

Per Virtual Host Configuration

To set the options for a vhosts, you will need to create a section with the vhost name prefixed by cors:. Example case for the vhost example.com:

[cors:example.com]
credentials = false
; List of origins separated by a comma
origins = *
; List of accepted headers separated by a comma
headers = X-CouchDB-Header
; List of accepted methods
methods = HEAD, GET

3.3.4. Cross-site Request Forgery protection

[csrf]

New in version 2.0: added CSRF protection, see JIRA COUCHDB-2762

CSRF, or “Cross-site Request Forgery” is a web-based exploit where an attacker can cause a user agent to make an authenticated form post or XHR request against a foreign site without their consent. The attack works because a user agent will send any cookies it has along with the request. The attacker does not see the response, nor can they see the user agent’s cookies. The attacker hopes to gain indirectly, e.g, by posting to a password reset form or cause damage by issuing a database delete request.

To prevent this, CouchDB can require a matching request header before processing any write request (defined as any method other than GET, HEAD or OPTIONS). The correct value of this header is unknown to the attacker and so their attack fails.

To enable CSRF protection, add the custom request header X-CouchDB-CSRF wih value true to any request. The response will return a cookie named CouchDB-CSRF.

If CouchDB sees the CouchDB-CSRF cookie in a request it expects the same value to be sent in the X-CouchDB-CSRF header. If the header is missing or does not match the cookie, a 403 Forbidden response is generated. Additionally, CouchDB logs a warning, to allow administrators to detect potential CSRF attacks in progress.

Careful clients can verify whether their requests were protected from CSRF by examining the X-CouchDB-CSRF-Valid response header. It should be present and its value should be true.

CSRF cookies expire after a configurable period of time but will automatically be refreshed by CouchDB on subsequent requests. An expired CSRF cookie is equivalent to not sending the cookie (and thus the request will not be protected from CSRF).

The following pseudo-code shows how to use the CSRF protection in an opportunistic fashion, gracefully degrading when the mechanism is not available.

if (hasCookie("CouchDB-CSRF")) {
  setRequestHeader("X-CouchDB-CSRF", cookieValue("CouchDB-CSRF"));
} else {
  setRequestHeader("X-CouchDB-CSRF", "true");
}

mandatory

CouchDB can insist on CSRF Cookie/Header for all requests (except those to the welcome handler, /, so you can acquire a cookie) with this setting. The default is false:

[csrf]
mandatory = true

secret

All CSRF cookies are signed by the server using this value. A random value will be chosen if you don’t specify it, but we recommend setting it yourself, especially if you are running a cluster of more than one node. The secret must match on all nodes in a cluster to avoid sadness:

[csrf]
secret = b6fdf2e8213a36dbcca34e61e4000967

timeout

All CSRF cookies expire after timeout seconds. The default is an hour:

[csrf]
timeout = 3600

3.3.5. Virtual Hosts

[vhosts]

CouchDB can map requests to different locations based on the Host header, even if they arrive on the same inbound IP address.

This allows different virtual hosts on the same machine to map to different databases or design documents, etc. The most common use case is to map a virtual host to a Rewrite Handler, to provide full control over the application’s URIs.

To add a virtual host, add a CNAME pointer to the DNS for your domain name. For development and testing, it is sufficient to add an entry in the hosts file, typically /etc/hosts` on Unix-like operating systems:

# CouchDB vhost definitions, refer to local.ini for further details
127.0.0.1       couchdb.local

Test that this is working:

$ ping -n 2 couchdb.local
PING couchdb.local (127.0.0.1) 56(84) bytes of data.
64 bytes from localhost (127.0.0.1): icmp_req=1 ttl=64 time=0.025 ms
64 bytes from localhost (127.0.0.1): icmp_req=2 ttl=64 time=0.051 ms

Finally, add an entry to your configuration file in the [vhosts] section:

[vhosts]
couchdb.local:5984 = /example
*.couchdb.local:5984 = /example

If your CouchDB is listening on the the default HTTP port (80), or is sitting behind a proxy, then you don’t need to specify a port number in the vhost key.

The first line will rewrite the request to display the content of the example database. This rule works only if the Host header is couchdb.local and won’t work for CNAMEs. The second rule, on the other hand, matches all CNAMEs to example db, so that both www.couchdb.local and db.couchdb.local will work.

Rewriting Hosts to a Path

Like in the _rewrite handler you can match some variable and use them to create the target path. Some examples:

[vhosts]
*.couchdb.local = /*
:dbname. = /:dbname
:ddocname.:dbname.example.com = /:dbname/_design/:ddocname/_rewrite

The first rule passes the wildcard as dbname. The second one does the same, but uses a variable name. And the third one allows you to use any URL with ddocname in any database with dbname.

You could also change the default function to handle request by changing the setting httpd/redirect_vhost_handler.