3.5. CouchDB HTTP Server

3.5.1. HTTP Server Options

[chttpd]

Note

In CouchDB 2.x and 3.x, the chttpd section refers to the standard, clustered port. All use of CouchDB, aside from a few specific maintenance tasks as described in this documentation, should be performed over this port.

  • bind_address

    Defines the IP address by which the clustered port is available:

    1. [chttpd]
    2. bind_address = 127.0.0.1

    To let CouchDB listen any available IP address, use 0.0.0.0:

    1. [chttpd]
    2. bind_address = 0.0.0.0

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

    1. [chttpd]
    2. bind_address = ::1

    or :: for any available:

    1. [chttpd]
    2. bind_address = ::

  • port

    Defines the port number to listen:

    1. [chttpd]
    2. port = 5984

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

    1. [chttpd]
    2. port = 0

  • prefer_minimal

    If a request has the header "Prefer": "return=minimal", CouchDB will only send the headers that are listed for the prefer_minimal configuration.:

    1. [chttpd]
    2. prefer_minimal = Cache-Control, Content-Length, Content-Range, Content-Type, ETag, Server, Transfer-Encoding, Vary

    Warning

    Removing the Server header from the settings will mean that the CouchDB server header is replaced with the MochiWeb server header.

  • authentication_handlers

    List of authentication handlers 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:

    1. [chttpd]
    2. authentication_handlers = {chttpd_auth, cookie_authentication_handler}, {chttpd_auth, default_authentication_handler}

    • {chttpd_auth, cookie_authentication_handler}: used for Cookie auth;

    • {chttpd_auth, proxy_authentication_handler}: used for Proxy auth;

    • {chttpd_auth, jwt_authentication_handler}: used for JWT auth;

    • {chttpd_auth, default_authentication_handler}: used for Basic auth;

    • {couch_httpd_auth, null_authentication_handler}: disables auth, breaks CouchDB.

  • buffer_response

    Changed in version 3.1.1.

    Set this to true to delay the start of a response until the end has been calculated. This increases memory usage, but simplifies client error handling as it eliminates the possibility that a response may be deliberately terminated midway through, due to a timeout. This config value may be changed at runtime, without impacting any in-flight responses.

    Even if this is set to false (the default), buffered responses can be enabled on a per-request basis for any delayed JSON response call by adding ?buffer_response=true to the request’s parameters.

  • allow_jsonp

    Changed in version 3.2: moved from [httpd] to [chttpd] section

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

    1. [chttpd]
    2. allow_jsonp = false

  • changes_timeout

    Changed in version 3.2: moved from [httpd] to [chttpd] section

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

    1. [chttpd]
    2. changes_timeout = 60000 ; 60 seconds

  • config_whitelist

    Changed in version 3.2: moved from [httpd] to [chttpd] section

    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 {chttpd,config_whitelist} itself. Excluding it from the list would require editing this file to update the whitelist:

    1. [chttpd]
    2. config_whitelist = [{chttpd,config_whitelist}, {log,level}, {etc,etc}]

  • enable_cors

    New in version 1.3.

    Changed in version 3.2: moved from [httpd] to [chttpd] section

    Controls CORS feature:

    1. [chttpd]
    2. enable_cors = false

  • secure_rewrites

    Changed in version 3.2: moved from [httpd] to [chttpd] section

    This option allow to isolate databases via subdomains:

    1. [chttpd]
    2. secure_rewrites = true

  • x_forwarded_host

    Changed in version 3.2: moved from [httpd] to [chttpd] section

    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:

    1. [chttpd]
    2. x_forwarded_host = X-Forwarded-Host

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

  • x_forwarded_proto

    Changed in version 3.2: moved from [httpd] to [chttpd] section

    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:

    1. [chttpd]
    2. x_forwarded_proto = X-Forwarded-Proto

  • x_forwarded_ssl

    Changed in version 3.2: moved from [httpd] to [chttpd] section

    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:

    1. [chttpd]
    2. x_forwarded_ssl = X-Forwarded-Ssl

  • enable_xframe_options

    Changed in version 3.2: moved from [httpd] to [chttpd] section

    Controls Enables or disabled feature:

    1. [chttpd]
    2. enable_xframe_options = false

  • max_http_request_size

    Changed in version 3.2: moved from [httpd] to [chttpd] section

    Limit the maximum size of the HTTP request body. This setting applies to all requests and it doesn’t discriminate between single vs. multi-document operations. So setting it to 1MB would block a PUT of a document larger than 1MB, but it might also block a _bulk_docs update of 1000 1KB documents, or a multipart/related update of a small document followed by two 512KB attachments. This setting is intended to be used as a protection against maliciously large HTTP requests rather than for limiting maximum document sizes.

    1. [chttpd]
    2. max_http_request_size = 4294967296 ; 4 GB

    Warning

    Before version 2.1.0 couchdb/max_document_size was implemented effectively as max_http_request_size. That is, it checked HTTP request bodies instead of document sizes. After the upgrade, it is advisable to review the usage of these configuration settings.

[httpd]

Changed in version 3.2: These options were moved to [chttpd] section: allow_jsonp, changes_timeout, config_whitelist, enable_cors, secure_rewrites, x_forwarded_host, x_forwarded_proto, x_forwarded_ssl, enable_xframe_options, max_http_request_size.

  • server_options

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

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

    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.

  • socket_options

    The socket options for the listening socket in CouchDB, as set at the beginning of ever request, can be specified as a list of tuples. For example:

    1. [httpd]
    2. socket_options = [{sndbuf, 262144}]

    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.

3.5.2. HTTPS (SSL/TLS) Options

[ssl]

CouchDB supports TLS/SSL natively, without the use of a proxy server.

HTTPS 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 have an official 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 go through the hassle of obtaining an official certificate, 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.

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

Now, you need to edit CouchDB’s configuration, by editing your local.ini file. Here is what you need to do.

Under the [ssl] section, enable HTTPS and set up the newly generated certificates:

  1. [ssl]
  2. enable = true
  3. cert_file = /etc/couchdb/cert/couchdb.pem
  4. 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:

  1. shell> curl https://127.0.0.1:6984/
  2. curl: (60) SSL certificate problem, verify that the CA cert is OK. Details:
  3. error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed
  4. More details here: http://curl.haxx.se/docs/sslcerts.html
  6. curl performs SSL certificate verification by default, using a "bundle"
  7. of Certificate Authority (CA) public keys (CA certs). If the default
  8. bundle file isn't adequate, you can specify an alternate file
  9. using the --cacert option.
  10. If this HTTPS server uses a certificate signed by a CA represented in
  11. the bundle, the certificate verification probably failed due to a
  12. problem with the certificate (it might be expired, or the name might
  13. not match the domain name in the URL).
  14. If you'd like to turn off curl's verification of the certificate, use
  15. 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:

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

All done.

For performance reasons, and for ease of setup, you may still wish to terminate HTTPS connections at your load balancer / reverse proxy, then use unencrypted HTTP between it and your CouchDB cluster. This is a recommended approach.

Additional detail may be available in the CouchDB wiki.

  • 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:

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

  • cert_file

    Path to a file containing the user’s certificate:

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

  • key_file

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

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

  • password

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

    1. [ssl]
    2. password = somepassword

  • ssl_certificate_max_depth

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

    1. [ssl]
    2. ssl_certificate_max_depth = 1

  • verify_fun

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

    1. [ssl]
    2. verify_fun = {Module, VerifyFun}

  • verify_ssl_certificates

    Set to true to validate peer certificates:

    1. [ssl]
    2. 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):

    1. [ssl]
    2. fail_if_no_peer_cert = false

  • secure_renegotiate

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

    1. [ssl]
    2. 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”.

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

  • tls_versions

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

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

3.5.3. Cross-Origin Resource Sharing

[cors]

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

Changed in version 3.2: moved from [httpd] to [chttpd] section

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 chttpd/enable_cors option have true value:

  1. [chttpd]
  2. 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.

    1. [cors]
    2. 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:

    1. [cors]
    2. origins = *

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

    1. [cors]
    2. 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:

    1. [cors]
    2. headers = X-Couch-Id, X-Couch-Rev

  • methods

    List of accepted methods:

    1. [cors]
    2. methods = GET,POST

  • max_age

    Sets the Access-Control-Max-Age header in seconds. Use it to avoid repeated OPTIONS requests.

    [cors] max_age = 3600

See also

Original JIRA implementation ticket

Standards and References:

Mozilla Developer Network Resources:

Client-side CORS support and usage:

3.5.3.1. Per Virtual Host Configuration

Warning

Virtual Hosts are deprecated in CouchDB 3.0, and will be removed in CouchDB 4.0.

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:

  1. [cors:example.com]
  2. credentials = false
  3. ; List of origins separated by a comma
  4. origins = *
  5. ; List of accepted headers separated by a comma
  6. headers = X-CouchDB-Header
  7. ; List of accepted methods
  8. methods = HEAD, GET

A video from 2010 on vhost and rewrite configuration is available, but is not guaranteed to match current syntax or behaviour.

3.5.4. Virtual Hosts

Warning

Virtual Hosts are deprecated in CouchDB 3.0, and will be removed in CouchDB 4.0.

[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:

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

Test that this is working:

  1. $ ping -n 2 couchdb.local
  2. PING couchdb.local (127.0.0.1) 56(84) bytes of data.
  3. 64 bytes from localhost (127.0.0.1): icmp_req=1 ttl=64 time=0.025 ms
  4. 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:

  1. [vhosts]
  2. couchdb.local:5984 = /example
  3. *.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.

3.5.4.1. 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:

  1. [vhosts]
  2. *.couchdb.local = /*
  3. :dbname. = /:dbname
  4. :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.

3.5.5. X-Frame-Options

X-Frame-Options is a response header that controls whether a http response can be embedded in a <frame>, <iframe> or <object>. This is a security feature to help against clickjacking.

[x_frame_options] ; Settings same-origin will return X-Frame-Options: SAMEORIGIN. ; If same origin is set, it will ignore the hosts setting ; same_origin = true ; Settings hosts will ; return X-Frame-Options: ALLOW-FROM https://example.com/ ; List of hosts separated by a comma. * means accept all ; hosts =

If xframe_options is enabled it will return X-Frame-Options: DENY by default. If same_origin is enabled it will return X-Frame-Options: SAMEORIGIN. A X-FRAME-OPTIONS: ALLOW-FROM url will be returned when same_origin is false, and the HOST header matches one of the urls in the hosts config. Otherwise a X-Frame-Options: DENY will be returned.