src/api/server/configuration.rst - couchdb-documentation - Git at Google

 .. Licensed under the Apache License, Version 2.0 (the "License"); you may not
 .. use this file except in compliance with the License. You may obtain a copy of
 .. the License at
 ..
 ..   http://www.apache.org/licenses/LICENSE-2.0
 ..
 .. Unless required by applicable law or agreed to in writing, software
 .. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 .. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 .. License for the specific language governing permissions and limitations under
 .. the License.

 .. _api/config:

 =============
 Configuration
 =============

 The CouchDB Server Configuration API provide an interface to query and update
 the various configuration values within a running CouchDB instance.

 Accessing the local node's configuration
 ========================================

 The literal string ``_local`` serves as an alias for the local node name, so
 for all configuration URLs, ``{node-name}`` may be replaced with ``_local``, to
 interact with the local node's configuration.

 ``/_node/{node-name}/_config``
 ==============================

 .. http:get:: /_node/{node-name}/_config
     :synopsis: Obtains a list of the entire server configuration

     Returns the entire CouchDB server configuration as a JSON structure. The
     structure is organized by different configuration sections, with
     individual values.

     :<header Accept: - :mimetype:`application/json`
                      - :mimetype:`text/plain`
     :>header Content-Type: - :mimetype:`application/json`
                            - :mimetype:`text/plain; charset=utf-8`
     :code 200: Request completed successfully
     :code 401: CouchDB Server Administrator privileges required

     **Request**

     .. code-block:: http

         GET /_node/nonode@nohost/_config HTTP/1.1
         Accept: application/json
         Host: localhost:5984

     **Response**:

     .. code-block:: http

         HTTP/1.1 200 OK
         Cache-Control: must-revalidate
         Content-Length: 4148
         Content-Type: application/json
         Date: Sat, 10 Aug 2013 12:01:42 GMT
         Server: CouchDB (Erlang/OTP)

         {
             "attachments": {
                 "compressible_types": "text/*, application/javascript, application/json,  application/xml",
                 "compression_level": "8"
             },
             "couchdb": {
                 "users_db_suffix": "_users",
                 "database_dir": "/var/lib/couchdb",
                 "max_attachment_chunk_size": "4294967296",
                 "max_dbs_open": "100",
                 "os_process_timeout": "5000",
                 "uri_file": "/var/lib/couchdb/couch.uri",
                 "util_driver_dir": "/usr/lib64/couchdb/erlang/lib/couch-1.5.0/priv/lib",
                 "view_index_dir": "/var/lib/couchdb"
             },
             "chttpd": {
                 "allow_jsonp": "false",
                 "backlog": "512",
                 "bind_address": "0.0.0.0",
                 "port": "5984",
                 "require_valid_user": "false",
                 "socket_options": "[{sndbuf, 262144}, {nodelay, true}]",
                 "server_options": "[{recbuf, undefined}]",
                 "secure_rewrites": "true"
             },
             "httpd": {
                 "authentication_handlers": "{couch_httpd_auth, cookie_authentication_handler}, {couch_httpd_auth, default_authentication_handler}",
                 "bind_address": "192.168.0.2",
                 "max_connections": "2048",
                 "port": "5984",
             },
             "log": {
                 "writer": "file",
                 "file": "/var/log/couchdb/couch.log",
                 "include_sasl": "true",
                 "level": "info"
             },
             "query_server_config": {
                 "reduce_limit": "true"
             },
             "replicator": {
                 "max_http_pipeline_size": "10",
                 "max_http_sessions": "10"
             },
             "stats": {
                 "interval": "10"
             },
             "uuids": {
                 "algorithm": "utc_random"
             }
         }

 .. versionchanged: 2.0.0 The config endpoint from ``/_config`` to
    ``/_node/{node-name}/_config``.

 .. _api/config/section:

 ``/_node/{node-name}/_config/{section}``
 ========================================

 .. http:get:: /_node/{node-name}/_config/{section}
     :synopsis: Returns all the configuration values for the specified section

     Gets the configuration structure for a single section.

     :param section: Configuration section name
     :<header Accept: - :mimetype:`application/json`
                      - :mimetype:`text/plain`
     :>header Content-Type: - :mimetype:`application/json`
                            - :mimetype:`text/plain; charset=utf-8`
     :code 200: Request completed successfully
     :code 401: CouchDB Server Administrator privileges required

     **Request**:

     .. code-block:: http

         GET /_node/nonode@nohost/_config/httpd HTTP/1.1
         Accept: application/json
         Host: localhost:5984

     **Response**:

     .. code-block:: http

         HTTP/1.1 200 OK
         Cache-Control: must-revalidate
         Content-Length: 444
         Content-Type: application/json
         Date: Sat, 10 Aug 2013 12:10:40 GMT
         Server: CouchDB (Erlang/OTP)

         {
             "authentication_handlers": "{couch_httpd_auth, cookie_authentication_handler}, {couch_httpd_auth, default_authentication_handler}",
             "bind_address": "127.0.0.1",
             "default_handler": "{couch_httpd_db, handle_request}",
             "port": "5984"
         }

 .. _api/config/section/key:

 ``/_node/{node-name}/_config/{section}/{key}``
 ==============================================

 .. http:get:: /_node/{node-name}/_config/{section}/{key}
     :synopsis: Returns a specific section/configuration value

     Gets a single configuration value from within a specific configuration
     section.

     :param section: Configuration section name
     :param key: Configuration option name
     :<header Accept: - :mimetype:`application/json`
                      - :mimetype:`text/plain`
     :>header Content-Type: - :mimetype:`application/json`
                            - :mimetype:`text/plain; charset=utf-8`
     :code 200: Request completed successfully
     :code 401: CouchDB Server Administrator privileges required

     **Request**:

     .. code-block:: http

         GET /_node/nonode@nohost/_config/log/level HTTP/1.1
         Accept: application/json
         Host: localhost:5984

     **Response**:

     .. code-block:: http

         HTTP/1.1 200 OK
         Cache-Control: must-revalidate
         Content-Length: 8
         Content-Type: application/json
         Date: Sat, 10 Aug 2013 12:12:59 GMT
         Server: CouchDB (Erlang/OTP)

         "debug"

     .. note::
         The returned value will be the JSON of the value, which may be a string
         or numeric value, or an array or object. Some client environments may
         not parse simple strings or numeric values as valid JSON.

 .. http:put:: /_node/{node-name}/_config/{section}/{key}
     :synopsis: Sets the specified configuration value

     Updates a configuration value. The new value should be supplied in the
     request body in the corresponding JSON format. If you are setting a string
     value, you must supply a valid JSON string. In response CouchDB sends old
     value for target section key.

     :param section: Configuration section name
     :param key: Configuration option name
     :<header Accept: - :mimetype:`application/json`
                      - :mimetype:`text/plain`
     :<header Content-Type: :mimetype:`application/json`
     :>header Content-Type: - :mimetype:`application/json`
                            - :mimetype:`text/plain; charset=utf-8`
     :code 200: Request completed successfully
     :code 400: Invalid JSON request body
     :code 401: CouchDB Server Administrator privileges required
     :code 500: Error setting configuration

     **Request**:

     .. code-block:: http

         PUT /_node/nonode@nohost/_config/log/level HTTP/1.1
         Accept: application/json
         Content-Length: 7
         Content-Type: application/json
         Host: localhost:5984

         "info"

     **Response**:

     .. code-block:: http

         HTTP/1.1 200 OK
         Cache-Control: must-revalidate
         Content-Length: 8
         Content-Type: application/json
         Date: Sat, 10 Aug 2013 12:12:59 GMT
         Server: CouchDB (Erlang/OTP)

         "debug"

 .. http:delete:: /_node/{node-name}/_config/{section}/{key}
     :synopsis: Removes the current setting

     Deletes a configuration value. The returned JSON will be the value of the
     configuration parameter before it was deleted.

     :param section: Configuration section name
     :param key: Configuration option name
     :<header Accept: - :mimetype:`application/json`
                      - :mimetype:`text/plain`
     :>header Content-Type: - :mimetype:`application/json`
                            - :mimetype:`text/plain; charset=utf-8`
     :code 200: Request completed successfully
     :code 401: CouchDB Server Administrator privileges required
     :code 404: Specified configuration option not found

     **Request**:

     .. code-block:: http

         DELETE /_node/nonode@nohost/_config/log/level HTTP/1.1
         Accept: application/json
         Host: localhost:5984

     **Response**:

     .. code-block:: http

         HTTP/1.1 200 OK
         Cache-Control: must-revalidate
         Content-Length: 7
         Content-Type: application/json
         Date: Sat, 10 Aug 2013 12:29:03 GMT
         Server: CouchDB (Erlang/OTP)

         "info"

 .. _api/config/reload:

 ``/_node/{node-name}/_config/_reload``
 ======================================

 .. versionadded:: 3.0

 .. http:post:: /_node/{node-name}/_config/_reload
     :synopsis: Reload the configuration from disk

     Reloads the configuration from disk. This has a side effect of
     flushing any in-memory configuration changes that have not been
     committed to disk.

     **Request**:

     .. code-block:: http

         POST /_node/nonode@nohost/_config/_reload HTTP/1.1
         Host: localhost:5984

     **Response**:

     .. code-block:: http

         HTTP/1.1 200 OK
         Cache-Control: must-revalidate
         Content-Length: 12
         Content-Type: application/json
         Date: Tues, 21 Jan 2020 11:09:35
         Server: CouchDB/3.0.0 (Erlang OTP)

         {"ok":true}
	.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
	.. use this file except in compliance with the License. You may obtain a copy of
	.. the License at
	..
	.. http://www.apache.org/licenses/LICENSE-2.0
	..
	.. Unless required by applicable law or agreed to in writing, software
	.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
	.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
	.. License for the specific language governing permissions and limitations under
	.. the License.

	.. _api/config:

	=============
	Configuration
	=============

	The CouchDB Server Configuration API provide an interface to query and update
	the various configuration values within a running CouchDB instance.

	Accessing the local node's configuration
	========================================

	The literal string ``_local`` serves as an alias for the local node name, so
	for all configuration URLs, ``{node-name}`` may be replaced with ``_local``, to
	interact with the local node's configuration.

	``/_node/{node-name}/_config``
	==============================

	.. http:get:: /_node/{node-name}/_config
	:synopsis: Obtains a list of the entire server configuration

	Returns the entire CouchDB server configuration as a JSON structure. The
	structure is organized by different configuration sections, with
	individual values.

	:<header Accept: - :mimetype:`application/json`
	- :mimetype:`text/plain`
	:>header Content-Type: - :mimetype:`application/json`
	- :mimetype:`text/plain; charset=utf-8`
	:code 200: Request completed successfully
	:code 401: CouchDB Server Administrator privileges required

	Request

	.. code-block:: http

	GET /_node/nonode@nohost/_config HTTP/1.1
	Accept: application/json
	Host: localhost:5984

	Response:

	.. code-block:: http

	HTTP/1.1 200 OK
	Cache-Control: must-revalidate
	Content-Length: 4148
	Content-Type: application/json
	Date: Sat, 10 Aug 2013 12:01:42 GMT
	Server: CouchDB (Erlang/OTP)

	{
	"attachments": {
	"compressible_types": "text/*, application/javascript, application/json, application/xml",
	"compression_level": "8"
	},
	"couchdb": {
	"users_db_suffix": "_users",
	"database_dir": "/var/lib/couchdb",
	"max_attachment_chunk_size": "4294967296",
	"max_dbs_open": "100",
	"os_process_timeout": "5000",
	"uri_file": "/var/lib/couchdb/couch.uri",
	"util_driver_dir": "/usr/lib64/couchdb/erlang/lib/couch-1.5.0/priv/lib",
	"view_index_dir": "/var/lib/couchdb"
	},
	"chttpd": {
	"allow_jsonp": "false",
	"backlog": "512",
	"bind_address": "0.0.0.0",
	"port": "5984",
	"require_valid_user": "false",
	"socket_options": "[{sndbuf, 262144}, {nodelay, true}]",
	"server_options": "[{recbuf, undefined}]",
	"secure_rewrites": "true"
	},
	"httpd": {
	"authentication_handlers": "{couch_httpd_auth, cookie_authentication_handler}, {couch_httpd_auth, default_authentication_handler}",
	"bind_address": "192.168.0.2",
	"max_connections": "2048",
	"port": "5984",
	},
	"log": {
	"writer": "file",
	"file": "/var/log/couchdb/couch.log",
	"include_sasl": "true",
	"level": "info"
	},
	"query_server_config": {
	"reduce_limit": "true"
	},
	"replicator": {
	"max_http_pipeline_size": "10",
	"max_http_sessions": "10"
	},
	"stats": {
	"interval": "10"
	},
	"uuids": {
	"algorithm": "utc_random"
	}
	}

	.. versionchanged: 2.0.0 The config endpoint from ``/_config`` to
	``/_node/{node-name}/_config``.

	.. _api/config/section:

	``/_node/{node-name}/_config/{section}``
	========================================

	.. http:get:: /_node/{node-name}/_config/{section}
	:synopsis: Returns all the configuration values for the specified section

	Gets the configuration structure for a single section.

	:param section: Configuration section name
	:<header Accept: - :mimetype:`application/json`
	- :mimetype:`text/plain`
	:>header Content-Type: - :mimetype:`application/json`
	- :mimetype:`text/plain; charset=utf-8`
	:code 200: Request completed successfully
	:code 401: CouchDB Server Administrator privileges required

	Request:

	.. code-block:: http

	GET /_node/nonode@nohost/_config/httpd HTTP/1.1
	Accept: application/json
	Host: localhost:5984

	Response:

	.. code-block:: http

	HTTP/1.1 200 OK
	Cache-Control: must-revalidate
	Content-Length: 444
	Content-Type: application/json
	Date: Sat, 10 Aug 2013 12:10:40 GMT
	Server: CouchDB (Erlang/OTP)

	{
	"authentication_handlers": "{couch_httpd_auth, cookie_authentication_handler}, {couch_httpd_auth, default_authentication_handler}",
	"bind_address": "127.0.0.1",
	"default_handler": "{couch_httpd_db, handle_request}",
	"port": "5984"
	}

	.. _api/config/section/key:

	``/_node/{node-name}/_config/{section}/{key}``
	==============================================

	.. http:get:: /_node/{node-name}/_config/{section}/{key}
	:synopsis: Returns a specific section/configuration value

	Gets a single configuration value from within a specific configuration
	section.

	:param section: Configuration section name
	:param key: Configuration option name
	:<header Accept: - :mimetype:`application/json`
	- :mimetype:`text/plain`
	:>header Content-Type: - :mimetype:`application/json`
	- :mimetype:`text/plain; charset=utf-8`
	:code 200: Request completed successfully
	:code 401: CouchDB Server Administrator privileges required

	Request:

	.. code-block:: http

	GET /_node/nonode@nohost/_config/log/level HTTP/1.1
	Accept: application/json
	Host: localhost:5984

	Response:

	.. code-block:: http

	HTTP/1.1 200 OK
	Cache-Control: must-revalidate
	Content-Length: 8
	Content-Type: application/json
	Date: Sat, 10 Aug 2013 12:12:59 GMT
	Server: CouchDB (Erlang/OTP)

	"debug"

	.. note::
	The returned value will be the JSON of the value, which may be a string
	or numeric value, or an array or object. Some client environments may
	not parse simple strings or numeric values as valid JSON.

	.. http:put:: /_node/{node-name}/_config/{section}/{key}
	:synopsis: Sets the specified configuration value

	Updates a configuration value. The new value should be supplied in the
	request body in the corresponding JSON format. If you are setting a string
	value, you must supply a valid JSON string. In response CouchDB sends old
	value for target section key.

	:param section: Configuration section name
	:param key: Configuration option name
	:<header Accept: - :mimetype:`application/json`
	- :mimetype:`text/plain`
	:<header Content-Type: :mimetype:`application/json`
	:>header Content-Type: - :mimetype:`application/json`
	- :mimetype:`text/plain; charset=utf-8`
	:code 200: Request completed successfully
	:code 400: Invalid JSON request body
	:code 401: CouchDB Server Administrator privileges required
	:code 500: Error setting configuration

	Request:

	.. code-block:: http

	PUT /_node/nonode@nohost/_config/log/level HTTP/1.1
	Accept: application/json
	Content-Length: 7
	Content-Type: application/json
	Host: localhost:5984

	"info"

	Response:

	.. code-block:: http

	HTTP/1.1 200 OK
	Cache-Control: must-revalidate
	Content-Length: 8
	Content-Type: application/json
	Date: Sat, 10 Aug 2013 12:12:59 GMT
	Server: CouchDB (Erlang/OTP)

	"debug"

	.. http:delete:: /_node/{node-name}/_config/{section}/{key}
	:synopsis: Removes the current setting

	Deletes a configuration value. The returned JSON will be the value of the
	configuration parameter before it was deleted.

	:param section: Configuration section name
	:param key: Configuration option name
	:<header Accept: - :mimetype:`application/json`
	- :mimetype:`text/plain`
	:>header Content-Type: - :mimetype:`application/json`
	- :mimetype:`text/plain; charset=utf-8`
	:code 200: Request completed successfully
	:code 401: CouchDB Server Administrator privileges required
	:code 404: Specified configuration option not found

	Request:

	.. code-block:: http

	DELETE /_node/nonode@nohost/_config/log/level HTTP/1.1
	Accept: application/json
	Host: localhost:5984

	Response:

	.. code-block:: http

	HTTP/1.1 200 OK
	Cache-Control: must-revalidate
	Content-Length: 7
	Content-Type: application/json
	Date: Sat, 10 Aug 2013 12:29:03 GMT
	Server: CouchDB (Erlang/OTP)

	"info"

	.. _api/config/reload:

	``/_node/{node-name}/_config/_reload``
	======================================

	.. versionadded:: 3.0

	.. http:post:: /_node/{node-name}/_config/_reload
	:synopsis: Reload the configuration from disk

	Reloads the configuration from disk. This has a side effect of
	flushing any in-memory configuration changes that have not been
	committed to disk.

	Request:

	.. code-block:: http

	POST /_node/nonode@nohost/_config/_reload HTTP/1.1
	Host: localhost:5984

	Response:

	.. code-block:: http

	HTTP/1.1 200 OK
	Cache-Control: must-revalidate
	Content-Length: 12
	Content-Type: application/json
	Date: Tues, 21 Jan 2020 11:09:35
	Server: CouchDB/3.0.0 (Erlang OTP)

	{"ok":true}