### Navigation

- index
- next |
- previous |
- Apache CouchDB 1.3 Manual »

# 5. Configuring CouchDB

## 5.1. CouchDB Configuration Files

## 5.2. Configuration File Locations

CouchDB reads files from the following locations, in the following order.

1. `PREFIX/default.ini`
2. `PREFIX/default.d/*`
3. `PREFIX/local.ini`
4. `PREFIX/local.d/*`

Settings in successive documents override the settings in earlier entries. For example, setting the `bind_address` parameter in `local.ini` would override any setting in `default.ini`.

Warning

The `default.ini` file may be overwritten during an upgrade or re-installation, so localised changes should be made to the `local.ini` file or files within the `local.d` directory.

## 5.3. Update Notifications

## 5.4. MochiWeb Server Options

Server options for the MochiWeb component of CouchDB can be added to the configuration files. Settings should be added to the `server_options` option of the `[httpd]` section of `local.ini`. For example:

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

## 5.5. Socket Options Configuration Setting

The socket options for the listening socket in CouchDB can now be set within the CouchDB configuration file. The setting should be added to the `[httpd]` section of the file using the option name `socket_options`. The specification is 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.

## 5.6. `vhosts` definitions

Similar to the rewrites section of a `_design` document, the `vhosts` system uses variables in the form of `:varname` or wildcards in the form of asterisks. The variable results can be output into the resulting path as they are in the rewriter.

## 5.7. Configuring Server Administrators

A default CouchDB install provides admin-level access to all connecting users. This configuration is known as `Admin Party`, and is not recommended for in-production usage. You can crash the party simply by creating the first admin account. CouchDB server administrators and passwords are not stored in the `_users` database, but in the `local.ini` file, which should be appropriately secured and readable only by system administrators.

    [admins]
    ;admin = mysecretpassword
    admin = -hashed-6d3c30241ba0aaa4e16c6ea99224f915687ed8cd,7f4a3e05e0cbc6f48a0035e3508eef90
    architect = -pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000

Administrators can be added directly to the `[admins]` section, and when CouchDB is restarted, the passwords will be salted and encrypted. By using the HTTP, administrator accounts may be created immediately without needing a restart, nor of storing the plaintext password temporarily. The HTTP `_config/admins` endpoint supports querying, deleting or creating new administrator accounts:

    shell> GET /_config/admins HTTP/1.1
        Accept: application/json
        Host: localhost:5984

    HTTP/1.1 200 OK
        Cache-Control: must-revalidate
        Content-Length: 196
        Content-Type: application/json
        Date: Fri, 30 Nov 2012 11:37:18 GMT
        Server: CouchDB/1.3.0 (Erlang OTP/R15B02)

    {
        "admin": "-hashed-6d3c30241ba0aaa4e16c6ea99224f915687ed8cd,7f4a3e05e0cbc6f48a0035e3508eef90",
        "architect": "-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
    }

Further details are available in `security_`, including configuring the work factor for `PBKDF2`, and the algorithm itself at PBKDF2 (RFC-2898).

New in version 1.3.0: `PBKDF2` server-side hashed salted password support added, now as a synchronous call for the `_config/admins` API.

### Navigation

- index
- next |
- previous |
- Apache CouchDB 1.3 Manual »