You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by kx...@apache.org on 2015/02/20 01:26:48 UTC
[15/26] documentation commit: updated refs/heads/master to 5a81ace
src/config now follows the style
Project: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/commit/71a4fc90
Tree: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/tree/71a4fc90
Diff: http://git-wip-us.apache.org/repos/asf/couchdb-documentation/diff/71a4fc90
Branch: refs/heads/master
Commit: 71a4fc908022a3cddb12220a337e56a26d67ce31
Parents: 8d0d049
Author: Maria Andersson <ma...@dualpose.com>
Authored: Fri Feb 6 22:22:35 2015 +0100
Committer: Maria Andersson <ma...@dualpose.com>
Committed: Fri Feb 6 22:22:35 2015 +0100
----------------------------------------------------------------------
src/config/auth.rst | 497 ++++++++++++-------------
src/config/compaction.rst | 172 +++++----
src/config/couchdb.rst | 230 +++++-------
src/config/externals.rst | 176 +++++----
src/config/http-handlers.rst | 309 +++++++---------
src/config/http.rst | 753 ++++++++++++++++++--------------------
src/config/index.rst | 28 +-
src/config/intro.rst | 99 +++--
src/config/logging.rst | 80 ++--
src/config/misc.rst | 349 +++++++++---------
src/config/proxying.rst | 64 ++--
src/config/query-servers.rst | 172 +++++----
src/config/replicator.rst | 215 +++++------
src/config/services.rst | 147 +++-----
14 files changed, 1511 insertions(+), 1780 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/71a4fc90/src/config/auth.rst
----------------------------------------------------------------------
diff --git a/src/config/auth.rst b/src/config/auth.rst
index 8311140..ff39767 100644
--- a/src/config/auth.rst
+++ b/src/config/auth.rst
@@ -25,80 +25,81 @@ Server Administrators
.. config:section:: admins :: 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. You may
- also use the HTTP interface to create administrator accounts; this way,
- you don't need to restart CouchDB, and there's no need to temporarily store
- or transmit passwords in plaintext. The HTTP ``_config/admins`` endpoint
- supports querying, deleting or creating new admin accounts:
-
- .. code-block:: http
-
- GET /_config/admins HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- .. code-block:: http
-
- 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 (Erlang/OTP)
-
- .. code-block:: json
-
- {
- "admin": "-hashed-6d3c30241ba0aaa4e16c6ea99224f915687ed8cd,7f4a3e05e0cbc6f48a0035e3508eef90",
- "architect": "-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
- }
-
- If you already have a salted, encrypted password string (for example,
- from an old ``local.ini`` file, or from a different CouchDB server), then
- you can store the "raw" encrypted string, without having CouchDB doubly
- encrypt it.
-
- .. code-block:: http
-
- PUT /_config/admins/architect?raw=true HTTP/1.1
- Accept: application/json
- Content-Type: application/json
- Content-Length: 89
- Host: localhost:5984
-
- "-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 89
- Content-Type: application/json
- Date: Fri, 30 Nov 2012 11:39:18 GMT
- Server: CouchDB (Erlang/OTP)
-
- "-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) <http://tools.ietf.org/html/rfc2898>`_.
-
- .. versionchanged:: 1.4 `PBKDF2` server-side hashed salted password support
- added, now as a synchronous call for the ``_config/admins`` API.
-
+ 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. You may
+ also use the HTTP interface to create administrator accounts; this way,
+ you don't need to restart CouchDB, and there's no need to temporarily store
+ or transmit passwords in plaintext. The HTTP ``_config/admins`` endpoint
+ supports querying, deleting or creating new admin accounts:
+
+ .. code-block:: http
+
+ GET /_config/admins HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+ .. code-block:: http
+
+ 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 (Erlang/OTP)
+
+ .. code-block:: json
+
+ {
+ "admin": "-hashed-6d3c30241ba0aaa4e16c6ea99224f915687ed8cd,7f4a3e05e0cbc6f48a0035e3508eef90",
+ "architect": "-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
+ }
+
+ If you already have a salted, encrypted password string (for example, from
+ an old ``local.ini`` file, or from a different CouchDB server), then you
+ can store the "raw" encrypted string, without having CouchDB doubly encrypt
+ it.
+
+ .. code-block:: http
+
+ PUT /_config/admins/architect?raw=true HTTP/1.1
+ Accept: application/json
+ Content-Type: application/json
+ Content-Length: 89
+ Host: localhost:5984
+
+ "-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 89
+ Content-Type: application/json
+ Date: Fri, 30 Nov 2012 11:39:18 GMT
+ Server: CouchDB (Erlang/OTP)
+
+ "-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) <http://tools.ietf.org/html/rfc2898>`_.
+
+ .. versionchanged::
+ 1.4 `PBKDF2` server-side hashed salted password support added, now as a
+ synchronous call for the ``_config/admins`` API.
.. _config/couch_httpd_auth:
@@ -107,206 +108,165 @@ Authentication Configuration
.. config:section:: couch_httpd_auth :: Authentication Configuration
+ .. config:option:: allow_persistent_cookies :: Persistent cookies
- .. config:option:: allow_persistent_cookies :: Persistent cookies
-
- Makes cookies persistent if ``true``.
-
- ::
-
- [couch_httpd_auth]
- allow_persistent_cookies = false
-
-
- .. config:option:: auth_cache_size :: Authentication cache
-
- Number of :ref:`userctx_object` to cache in memory, to reduce disk lookups.
-
- ::
-
- [couch_httpd_auth]
- auth_cache_size = 50
-
-
- .. config:option:: authentication_db :: Users database
-
- Specifies the name of the system database for storing CouchDB users.
-
- ::
+ Makes cookies persistent if ``true``. ::
- [couch_httpd_auth]
- authentication_db = _users
+ [couch_httpd_auth]
+ allow_persistent_cookies = false
- .. warning::
- If you change the database name, do not forget to remove or clean
- up the old database, since it will no longer be protected by CouchDB.
+ .. config:option:: auth_cache_size :: Authentication cache
+ Number of :ref:`userctx_object` to cache in memory, to reduce disk
+ lookups. ::
- .. config:option:: authentication_redirect :: Default redirect for authentication requests
+ [couch_httpd_auth]
+ auth_cache_size = 50
- Specifies the location for redirection on successful authentication if a
- ``text/html`` response is accepted by the client (via an ``Accept`` header).
+ .. config:option:: authentication_db :: Users database
- ::
+ Specifies the name of the system database for storing CouchDB users. ::
- [couch_httpd_auth]
- authentication_redirect = /_utils/session.html
+ [couch_httpd_auth]
+ authentication_db = _users
+ .. warning::
+ If you change the database name, do not forget to remove or clean
+ up the old database, since it will no longer be protected by
+ CouchDB.
- .. config:option:: iterations :: PBKDF2 iterations count
+ .. config:option:: authentication_redirect :: Default redirect for authentication requests
- .. versionadded:: 1.3
+ Specifies the location for redirection on successful authentication if
+ a ``text/html`` response is accepted by the client (via an ``Accept``
+ header). ::
- The number of iterations for password hashing by the PBKDF2 algorithm.
- A higher number provides better hash durability, but comes at a cost in
- performance for each request that requires authentication.
+ [couch_httpd_auth]
+ authentication_redirect = /_utils/session.html
- ::
+ .. config:option:: iterations :: PBKDF2 iterations count
- [couch_httpd_auth]
- iterations = 10000
+ .. versionadded:: 1.3
- .. config:option:: min_iterations :: Minimum PBKDF2 iterations count
+ The number of iterations for password hashing by the PBKDF2 algorithm.
+ A higher number provides better hash durability, but comes at a cost
+ in performance for each request that requires authentication. ::
- .. versionadded:: 1.6
+ [couch_httpd_auth]
+ iterations = 10000
- The minimum number of iterations allowed for passwords hashed by
- the PBKDF2 algorithm. Any user with fewer iterations is forbidden.
+ .. config:option:: min_iterations :: Minimum PBKDF2 iterations count
- ::
+ .. versionadded:: 1.6
- [couch_httpd_auth]
- min_iterations = 100
+ The minimum number of iterations allowed for passwords hashed by the
+ PBKDF2 algorithm. Any user with fewer iterations is forbidden. ::
- .. config:option:: max_iterations :: Maximum PBKDF2 iterations count
+ [couch_httpd_auth]
+ min_iterations = 100
- .. versionadded:: 1.6
+ .. config:option:: max_iterations :: Maximum PBKDF2 iterations count
- The maximum number of iterations allowed for passwords hashed by
- the PBKDF2 algorithm. Any user with greater iterations is forbidden.
+ .. versionadded:: 1.6
- ::
+ The maximum number of iterations allowed for passwords hashed by the
+ PBKDF2 algorithm. Any user with greater iterations is forbidden. ::
- [couch_httpd_auth]
- max_iterations = 100000
+ [couch_httpd_auth]
+ max_iterations = 100000
+ .. config:option:: proxy_use_secret :: Force proxy auth use secret token
- .. config:option:: proxy_use_secret :: Force proxy auth use secret token
+ When this option is set to ``true``, the
+ :option:`couch_httpd_auth/secret` option is required for
+ :ref:`api/auth/proxy`. ::
- When this option is set to ``true``, the :option:`couch_httpd_auth/secret`
- option is required for :ref:`api/auth/proxy`.
+ [couch_httpd_auth]
+ proxy_use_secret = false
- ::
+ .. config:option:: public_fields :: User documents public fields
- [couch_httpd_auth]
- proxy_use_secret = false
+ .. versionadded:: 1.4
+ A comma-separated list of field names in user documents (in
+ :option:`couch_httpd_auth/authentication_db`) that can be read by any
+ user. If unset or not specified, authenticated users can only retrieve
+ their own document. ::
- .. config:option:: public_fields :: User documents public fields
+ [couch_httpd_auth]
+ public_fields = first_name, last_name, contacts, url
- .. versionadded:: 1.4
+ .. note::
+ Using the ``public_fields`` whitelist for user document properties
+ requires setting the :option:`couch_httpd_auth/users_db_public`
+ option to ``true`` (the latter option has no other purpose)::
- A comma-separated list of field names in user documents (in
- :option:`couch_httpd_auth/authentication_db`) that can
- be read by any user. If unset or not specified, authenticated users can only
- retrieve their own document.
+ [couch_httpd_auth]
+ users_db_public = true
- ::
+ .. config:option:: require_valid_user :: Force user authentication
- [couch_httpd_auth]
- public_fields = first_name, last_name, contacts, url
+ When this option is set to ``true``, no requests are allowed from
+ anonymous users. Everyone must be authenticated. ::
- .. note::
- Using the ``public_fields`` whitelist for user document properties
- requires setting the :option:`couch_httpd_auth/users_db_public`
- option to ``true`` (the latter option has no other purpose)::
+ [couch_httpd_auth]
+ require_valid_user = false
- [couch_httpd_auth]
- users_db_public = true
+ .. config:option:: secret :: Proxy Auth secret token
+ The secret token used for :ref:`api/auth/proxy` method. ::
- .. config:option:: require_valid_user :: Force user authentication
+ [couch_httpd_auth]
+ secret = 92de07df7e7a3fe14808cef90a7cc0d91
- When this option is set to ``true``, no requests are allowed from anonymous
- users. Everyone must be authenticated.
+ .. config:option:: timeout :: Session timeout
- ::
+ Number of seconds since the last request before sessions will be
+ expired. ::
- [couch_httpd_auth]
- require_valid_user = false
+ [couch_httpd_auth]
+ timeout = 600
+ .. config:option:: users_db_public :: Publish user documents
- .. config:option:: secret :: Proxy Auth secret token
+ .. versionadded:: 1.4
- The secret token used for :ref:`api/auth/proxy` method.
+ Allow all users to view user documents. By default, only admins may
+ browse all users documents, while users may browse only their own
+ document. ::
- ::
+ [couch_httpd_auth]
+ users_db_public = false
- [couch_httpd_auth]
- secret = 92de07df7e7a3fe14808cef90a7cc0d91
+ .. config:option:: x_auth_roles :: Proxy Auth roles header
+ The HTTP header name (``X-Auth-CouchDB-Roles`` by default) that
+ contains the list of a user's roles, separated by a comma. Used for
+ :ref:`api/auth/proxy`. ::
- .. config:option:: timeout :: Session timeout
+ [couch_httpd_auth]
+ x_auth_roles = X-Auth-CouchDB-Roles
- Number of seconds since the last request before sessions will be expired.
+ .. config:option:: x_auth_token :: Proxy Auth token header
- ::
+ The HTTP header name (``X-Auth-CouchDB-Token`` by default) containing
+ the token used to authenticate the authorization. This token is an
+ `HMAC-SHA1` created from the :option:`couch_httpd_auth/secret` and
+ :option:`couch_httpd_auth/x_auth_username`. The secret key should be
+ the same on the client and the CouchDB node. This token is optional if
+ the value of the :option:`couch_httpd_auth/proxy_use_secret` option is
+ not ``true``. Used for :ref:`api/auth/proxy`. ::
- [couch_httpd_auth]
- timeout = 600
+ [couch_httpd_auth]
+ x_auth_roles = X-Auth-CouchDB-Token
+ .. config:option:: x_auth_username :: Proxy Auth username header
- .. config:option:: users_db_public :: Publish user documents
-
- .. versionadded:: 1.4
-
- Allow all users to view user documents. By default, only admins may browse
- all users documents, while users may browse only their own document.
-
- ::
-
- [couch_httpd_auth]
- users_db_public = false
-
-
- .. config:option:: x_auth_roles :: Proxy Auth roles header
-
- The HTTP header name (``X-Auth-CouchDB-Roles`` by default) that contains the
- list of a user's roles, separated by a comma. Used for
- :ref:`api/auth/proxy`.
-
- ::
-
- [couch_httpd_auth]
- x_auth_roles = X-Auth-CouchDB-Roles
-
-
- .. config:option:: x_auth_token :: Proxy Auth token header
-
- The HTTP header name (``X-Auth-CouchDB-Token`` by default) containing the
- token used to authenticate the authorization. This token is an `HMAC-SHA1`
- created from the :option:`couch_httpd_auth/secret` and
- :option:`couch_httpd_auth/x_auth_username`. The secret key should be
- the same on the client and the CouchDB node. This token is optional if
- the value of the :option:`couch_httpd_auth/proxy_use_secret` option is not
- ``true``. Used for :ref:`api/auth/proxy`.
-
- ::
-
- [couch_httpd_auth]
- x_auth_roles = X-Auth-CouchDB-Token
-
-
- .. config:option:: x_auth_username :: Proxy Auth username header
-
- The HTTP header name (``X-Auth-CouchDB-UserName`` by default) containing the
- username. Used for :ref:`api/auth/proxy`.
-
- ::
-
- [couch_httpd_auth]
- x_auth_username = X-Auth-CouchDB-UserName
+ The HTTP header name (``X-Auth-CouchDB-UserName`` by default)
+ containing the username. Used for :ref:`api/auth/proxy`. ::
+ [couch_httpd_auth]
+ x_auth_username = X-Auth-CouchDB-UserName
.. _config/couch_httpd_oauth:
@@ -315,42 +275,41 @@ HTTP OAuth Configuration
.. config:section:: couch_httpd_oauth :: HTTP OAuth Configuration
- .. versionadded:: 1.2
-
- .. config:option:: use_users_db
-
- CouchDB is able to store OAuth credentials within user documents instead of
- config file by using this option::
-
- [couch_httpd_oauth]
- use_users_db = true
-
- If set to ``true``, OAuth token and consumer secrets will be looked up in the
- :option:`authentication database <couch_httpd_auth/authentication_db>`.
- These secrets are stored in a top level field named ``"oauth"`` in user
- documents, as below.
-
- .. code-block:: javascript
-
- {
- "_id": "org.couchdb.user:joe",
- "type": "user",
- "name": "joe",
- "password_sha": "fe95df1ca59a9b567bdca5cbaf8412abd6e06121",
- "salt": "4e170ffeb6f34daecfd814dfb4001a73"
- "roles": ["foo", "bar"],
- "oauth": {
- "consumer_keys": {
- "consumerKey1": "key1Secret",
- "consumerKey2": "key2Secret"
- },
- "tokens": {
- "token1": "token1Secret",
- "token2": "token2Secret"
- }
- }
- }
-
+ .. versionadded:: 1.2
+
+ .. config:option:: use_users_db
+
+ CouchDB is able to store OAuth credentials within user documents instead of
+ config file by using this option::
+
+ [couch_httpd_oauth]
+ use_users_db = true
+
+ If set to ``true``, OAuth token and consumer secrets will be looked up in
+ the :option:`authentication database <couch_httpd_auth/authentication_db>`.
+ These secrets are stored in a top level field named ``"oauth"`` in user
+ documents, as below.
+
+ .. code-block:: javascript
+
+ {
+ "_id": "org.couchdb.user:joe",
+ "type": "user",
+ "name": "joe",
+ "password_sha": "fe95df1ca59a9b567bdca5cbaf8412abd6e06121",
+ "salt": "4e170ffeb6f34daecfd814dfb4001a73"
+ "roles": ["foo", "bar"],
+ "oauth": {
+ "consumer_keys": {
+ "consumerKey1": "key1Secret",
+ "consumerKey2": "key2Secret"
+ },
+ "tokens": {
+ "token1": "token1Secret",
+ "token2": "token2Secret"
+ }
+ }
+ }
.. _config/oauth:
@@ -359,26 +318,20 @@ OAuth Configuration
.. config:section:: oauth_* :: OAuth Configuration
- To let users be authenticated by :ref:`api/auth/oauth` (:rfc:`5849`), three
- special sections must be set up in the :ref:`configuration <config>` file:
-
- 1. The Consumer secret:
-
- ::
-
- [oauth_consumer_secrets]
- consumer1 = sekr1t
+ To let users be authenticated by :ref:`api/auth/oauth` (:rfc:`5849`), three
+ special sections must be set up in the :ref:`configuration <config>` file:
- 2. Token secrets:
+ #. The Consumer secret::
- ::
+ [oauth_consumer_secrets]
+ consumer1 = sekr1t
- [oauth_token_secrets]
- token1 = tokensekr1t
+ #. Token secrets::
- 3. A mapping from tokens to users:
+ [oauth_token_secrets]
+ token1 = tokensekr1t
- ::
+ #. A mapping from tokens to users::
- [oauth_token_users]
- token1 = couchdb_username
+ [oauth_token_users]
+ token1 = couchdb_username
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/71a4fc90/src/config/compaction.rst
----------------------------------------------------------------------
diff --git a/src/config/compaction.rst b/src/config/compaction.rst
index 39311a0..9beb872 100644
--- a/src/config/compaction.rst
+++ b/src/config/compaction.rst
@@ -11,7 +11,6 @@
.. the License.
.. default-domain:: config
-
.. highlight:: ini
========================
@@ -25,22 +24,20 @@ Database Compaction Options
.. config:section:: database_compaction :: Database Compaction Options
- .. config:option:: doc_buffer_size :: Documents buffer size
-
- Specifies the copy buffer's maximum size in bytes::
-
- [database_compaction]
- doc_buffer_size = 524288
+ .. config:option:: doc_buffer_size :: Documents buffer size
+ Specifies the copy buffer's maximum size in bytes::
- .. config:option:: checkpoint_after :: Checkpoint trigger
+ [database_compaction]
+ doc_buffer_size = 524288
- Triggers a checkpoint after the specified amount of bytes were successfully
- copied to the compacted database::
+ .. config:option:: checkpoint_after :: Checkpoint trigger
- [database_compaction]
- checkpoint_after = 5242880
+ Triggers a checkpoint after the specified amount of bytes were
+ successfully copied to the compacted database::
+ [database_compaction]
+ checkpoint_after = 5242880
.. _config/compactions:
@@ -49,86 +46,88 @@ Compaction Daemon Rules
.. config:section:: compactions :: Compaction Daemon Rules
- A list of rules to determine when to run automatic compaction. The
- :option:`daemons/compaction_daemon` compacts databases and their respective
- view groups when all the condition parameters are satisfied. Configuration
- can be per-database or global, and it has the following format::
-
- [compactions]
- database_name = [ {ParamName, ParamValue}, {ParamName, ParamValue}, ... ]
- _default = [ {ParamName, ParamValue}, {ParamName, ParamValue}, ... ]
-
+ A list of rules to determine when to run automatic compaction. The
+ :option:`daemons/compaction_daemon` compacts databases and their respective
+ view groups when all the condition parameters are satisfied. Configuration
+ can be per-database or global, and it has the following format::
- For example::
+ [compactions]
+ database_name = [ {ParamName, ParamValue}, {ParamName, ParamValue}, ... ]
+ _default = [ {ParamName, ParamValue}, {ParamName, ParamValue}, ... ]
- [compactions]
- _default = [{db_fragmentation, "70%"}, {view_fragmentation, "60%"}, {from, "23:00"}, {to, "04:00"}]
+ For example::
- - ``db_fragmentation``: If the ratio of legacy data, including metadata, to
- current data in the database file size is equal to or greater than this
- value, this condition is satisfied. The percentage is expressed as an
- integer percentage. This value is computed as::
+ [compactions]
+ _default = [{db_fragmentation, "70%"}, {view_fragmentation, "60%"}, {from, "23:00"}, {to, "04:00"}]
- (file_size - data_size) / file_size * 100
+ - ``db_fragmentation``: If the ratio of legacy data, including metadata, to
+ current data in the database file size is equal to or greater than this
+ value, this condition is satisfied. The percentage is expressed as an
+ integer percentage. This value is computed as::
- The data_size and file_size values can be obtained when
- querying :http:get:`/{db}`.
+ (file_size - data_size) / file_size * 100
- - ``view_fragmentation``: If the ratio of legacy data, including metadata, to
- current data in a view index file size is equal to or greater then this
- value, this database compaction condition is satisfied. The percentage is
- expressed as an integer percentage. This value is computed as::
+ The data_size and file_size values can be obtained when
+ querying :http:get:`/{db}`.
- (file_size - data_size) / file_size * 100
+ - ``view_fragmentation``: If the ratio of legacy data, including metadata,
+ to current data in a view index file size is equal to or greater then
+ this value, this database compaction condition is satisfied. The
+ percentage is expressed as an integer percentage. This value is computed
+ as::
- The data_size and file_size values can be obtained when querying a
- :ref:`view group's information URI <api/ddoc/info>`.
+ (file_size - data_size) / file_size * 100
- - ``from`` and ``to``: The period for which a database (and its view group)
- compaction is allowed. The value for these parameters must obey the format::
+ The data_size and file_size values can be obtained when querying a
+ :ref:`view group's information URI <api/ddoc/info>`.
- HH:MM - HH:MM (HH in [0..23], MM in [0..59])
+ - ``from`` and ``to``: The period for which a database (and its view group)
+ compaction is allowed. The value for these parameters must obey the
+ format::
- - ``strict_window``: If a compaction is still running after the end of the
- allowed period, it will be canceled if this parameter is set to `true`.
- It defaults to `false` and is meaningful only if the *period* parameter is
- also specified.
+ HH:MM - HH:MM (HH in [0..23], MM in [0..59])
- - ``parallel_view_compaction``: If set to `true`, the database and its views
- are compacted in parallel. This is only useful on certain setups, like
- for example when the database and view index directories point to different
- disks. It defaults to `false`.
+ - ``strict_window``: If a compaction is still running after the end of the
+ allowed period, it will be canceled if this parameter is set to `true`.
+ It defaults to `false` and is meaningful only if the *period* parameter
+ is also specified.
- Before a compaction is triggered, an estimation of how much free disk space is
- needed is computed. This estimation corresponds to two times the data size of
- the database or view index. When there's not enough free disk space to compact
- a particular database or view index, a warning message is logged.
+ - ``parallel_view_compaction``: If set to `true`, the database and its
+ views are compacted in parallel. This is only useful on certain setups,
+ like for example when the database and view index directories point to
+ different disks. It defaults to `false`.
- Examples:
+ Before a compaction is triggered, an estimation of how much free disk space
+ is needed is computed. This estimation corresponds to two times the data
+ size of the database or view index. When there's not enough free disk space
+ to compact a particular database or view index, a warning message is
+ logged.
- #. ``[{db_fragmentation, "70%"}, {view_fragmentation, "60%"}]``
+ Examples:
- The `foo` database is compacted if its fragmentation is 70% or more.
- Any view index of this database is compacted only if its fragmentation
- is 60% or more.
+ #. ``[{db_fragmentation, "70%"}, {view_fragmentation, "60%"}]``
- #. ``[{db_fragmentation, "70%"}, {view_fragmentation, "60%"}, {from, "00:00"}, {to, "04:00"}]``
+ The `foo` database is compacted if its fragmentation is 70% or more. Any
+ view index of this database is compacted only if its fragmentation is
+ 60% or more.
- Similar to the preceding example but a compaction (database or view index)
- is only triggered if the current time is between midnight and 4 AM.
+ #. ``[{db_fragmentation, "70%"}, {view_fragmentation, "60%"}, {from, "00:00"}, {to, "04:00"}]``
- #. ``[{db_fragmentation, "70%"}, {view_fragmentation, "60%"}, {from, "00:00"}, {to, "04:00"}, {strict_window, true}]``
+ Similar to the preceding example but a compaction (database or view
+ index) is only triggered if the current time is between midnight and 4
+ AM.
- Similar to the preceding example - a compaction (database or view index)
- is only triggered if the current time is between midnight and 4 AM. If at
- 4 AM the database or one of its views is still compacting, the compaction
- process will be canceled.
+ #. ``[{db_fragmentation, "70%"}, {view_fragmentation, "60%"}, {from, "00:00"}, {to, "04:00"}, {strict_window, true}]``
- #. ``[{db_fragmentation, "70%"}, {view_fragmentation, "60%"}, {from, "00:00"}, {to, "04:00"}, {strict_window, true}, {parallel_view_compaction, true}]``
+ Similar to the preceding example - a compaction (database or view index)
+ is only triggered if the current time is between midnight and 4 AM. If
+ at 4 AM the database or one of its views is still compacting, the
+ compaction process will be canceled.
- Similar to the preceding example, but a database and its views can be
- compacted in parallel.
+ #. ``[{db_fragmentation, "70%"}, {view_fragmentation, "60%"}, {from, "00:00"}, {to, "04:00"}, {strict_window, true}, {parallel_view_compaction, true}]``
+ Similar to the preceding example, but a database and its views can be
+ compacted in parallel.
.. _config/compaction_daemon:
@@ -137,26 +136,22 @@ Configuration of Compaction Daemon
.. config:section:: compaction_daemon :: Configuration of Compaction Daemon
- .. config:option:: check_interval
+ .. config:option:: check_interval
- The delay, in seconds, between each check for which database and view
- indexes need to be compacted::
+ The delay, in seconds, between each check for which database and view
+ indexes need to be compacted::
- [compaction_daemon]
- check_interval = 300
+ [compaction_daemon]
+ check_interval = 300
+ .. config:option:: min_file_size
- .. config:option:: min_file_size
-
- If a database or view index file is smaller than this value (in bytes),
- compaction will not happen. Very small files always have high fragmentation,
- so compacting them is inefficient.
-
- ::
-
- [compaction_daemon]
- min_file_size = 131072
+ If a database or view index file is smaller than this value (in bytes),
+ compaction will not happen. Very small files always have high
+ fragmentation, so compacting them is inefficient. ::
+ [compaction_daemon]
+ min_file_size = 131072
.. _config/view_compaction:
@@ -165,10 +160,9 @@ Views Compaction Options
.. config:section:: view_compaction :: Views Compaction Options
+ .. config:option:: keyvalue_buffer_size :: Key-Values buffer size
- .. config:option:: keyvalue_buffer_size :: Key-Values buffer size
-
- Specifies maximum copy buffer size in bytes used during compaction::
+ Specifies maximum copy buffer size in bytes used during compaction::
- [view_compaction]
- keyvalue_buffer_size = 2097152
+ [view_compaction]
+ keyvalue_buffer_size = 2097152
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/71a4fc90/src/config/couchdb.rst
----------------------------------------------------------------------
diff --git a/src/config/couchdb.rst b/src/config/couchdb.rst
index 6f3c022..48d8d65 100644
--- a/src/config/couchdb.rst
+++ b/src/config/couchdb.rst
@@ -11,7 +11,6 @@
.. the License.
.. default-domain:: config
-
.. highlight:: ini
==================
@@ -25,176 +24,145 @@ Base CouchDB Options
.. config:section:: couchdb :: Base CouchDB Options
+ .. config:option:: attachment_stream_buffer_size :: Attachment streaming buffer
- .. config:option:: attachment_stream_buffer_size :: Attachment streaming buffer
-
- Higher values may result in better read performance due to fewer read
- operations and/or more OS page cache hits. However, they can also increase
- overall response time for writes when there are many attachment write
- requests in parallel.
-
- ::
-
- [couchdb]
- attachment_stream_buffer_size = 4096
-
-
- .. config:option:: database_dir :: Databases location directory
-
- Specifies location of CouchDB database files (``*.couch`` named).
- This location should be writable and readable for the user the CouchDB
- service runs as (``couchdb`` by default).
-
- ::
-
- [couchdb]
- database_dir = /var/lib/couchdb
-
-
- .. config:option:: delayed_commits :: Delayed commits
-
- When this config value as ``false`` the CouchDB provides guaranty of `fsync`
- call before return :http:statuscode:`201` response on each document saving.
- Setting this config value as ``true`` may raise some overall performance
- with cost of losing durability - it's strongly not recommended to do such
- in production::
-
- [couchdb]
- delayed_commits = false
-
- .. warning::
-
- Delayed commits are a feature of CouchDB that allows it to achieve better
- write performance for some workloads while sacrificing a small amount of
- durability. The setting causes CouchDB to wait up to a full second before
- committing new data after an update. If the server crashes before
- the header is written then any writes since the last commit are lost.
-
-
- .. config:option:: file_compression :: Compression method for documents
-
- .. versionchanged:: 1.2 Added `Google Snappy`_ compression algorithm.
-
- Method used to compress everything that is appended to database and
- view index files, except for attachments (see the :section:`attachments`
- section). Available methods are:
-
- * ``none``: no compression
- * ``snappy``: use Google Snappy, a very fast compressor/decompressor
- * ``deflate_N``: use zlib's deflate; ``N`` is the compression level which
- ranges from ``1`` (fastest, lowest compression ratio) to ``9`` (slowest,
- highest compression ratio)
-
- ::
-
- [couchdb]
- file_compression = snappy
-
- .. _Google Snappy: http://code.google.com/p/snappy/
-
+ Higher values may result in better read performance due to fewer read
+ operations and/or more OS page cache hits. However, they can also
+ increase overall response time for writes when there are many
+ attachment write requests in parallel. ::
- .. config:option:: fsync_options :: Fsync options
+ [couchdb]
+ attachment_stream_buffer_size = 4096
- Specifies when to make `fsync` calls. `fsync` makes sure that
- the contents of any file system buffers kept by the operating system are
- flushed to disk. There is generally no need to modify this parameter.
+ .. config:option:: database_dir :: Databases location directory
- ::
+ Specifies location of CouchDB database files (``*.couch`` named). This
+ location should be writable and readable for the user the CouchDB
+ service runs as (``couchdb`` by default). ::
- [couchdb]
- fsync_options = [before_header, after_header, on_file_open]
+ [couchdb]
+ database_dir = /var/lib/couchdb
+ .. config:option:: delayed_commits :: Delayed commits
- .. config:option:: max_dbs_open :: Limit of simultaneously opened databases
+ When this config value as ``false`` the CouchDB provides guaranty of
+ `fsync` call before return :http:statuscode:`201` response on each
+ document saving. Setting this config value as ``true`` may raise some
+ overall performance with cost of losing durability - it's strongly not
+ recommended to do such in production::
- This option places an upper bound on the number of databases that can be
- open at once. CouchDB reference counts database accesses internally and will
- close idle databases as needed. Sometimes it is necessary to keep more than
- the default open at once, such as in deployments where many databases will
- be replicating continuously.
+ [couchdb]
+ delayed_commits = false
- ::
+ .. warning::
+ Delayed commits are a feature of CouchDB that allows it to achieve
+ better write performance for some workloads while sacrificing a
+ small amount of durability. The setting causes CouchDB to wait up
+ to a full second before committing new data after an update. If the
+ server crashes before the header is written then any writes since
+ the last commit are lost.
- [couchdb]
- max_dbs_open = 100
+ .. config:option:: file_compression :: Compression method for documents
+ .. versionchanged:: 1.2 Added `Google Snappy`_ compression algorithm.
- .. config:option:: max_document_size :: Maximum document size
+ Method used to compress everything that is appended to database and
+ view index files, except for attachments (see the
+ :section:`attachments` section). Available methods are:
- .. versionchanged:: 1.3 This option now actually works.
+ * ``none``: no compression
+ * ``snappy``: use Google Snappy, a very fast compressor/decompressor
+ * ``deflate_N``: use zlib's deflate; ``N`` is the compression level
+ which ranges from ``1`` (fastest, lowest compression ratio) to ``9``
+ (slowest, highest compression ratio)
- Defines a maximum size for JSON documents, in bytes. This limit does not
- apply to attachments, since they are transferred as a stream of chunks.
- If you set this to a small value, you might be unable to modify
- configuration options, database security and other larger documents until
- a larger value is restored by editing the configuration file.
+ ::
- ::
+ [couchdb]
+ file_compression = snappy
- [couchdb]
- max_document_size = 4294967296 ; 4 GB
+ .. _Google Snappy: http://code.google.com/p/snappy/
+ .. config:option:: fsync_options :: Fsync options
- .. config:option:: os_process_timeout :: External processes time limit
+ Specifies when to make `fsync` calls. `fsync` makes sure that the
+ contents of any file system buffers kept by the operating system are
+ flushed to disk. There is generally no need to modify this parameter. ::
- If an external process, such as a query server or external process, runs for
- this amount of microseconds without returning any results, it will be
- terminated. Keeping this value smaller ensures you get expedient errors, but
- you may want to tweak it for your specific needs.
+ [couchdb]
+ fsync_options = [before_header, after_header, on_file_open]
- ::
+ .. config:option:: max_dbs_open :: Limit of simultaneously opened databases
- [couchdb]
- os_process_timeout = 5000 ; 5 sec
+ This option places an upper bound on the number of databases that can
+ be open at once. CouchDB reference counts database accesses internally
+ and will close idle databases as needed. Sometimes it is necessary to
+ keep more than the default open at once, such as in deployments where
+ many databases will be replicating continuously. ::
+ [couchdb]
+ max_dbs_open = 100
- .. config:option:: uri_file :: Discovery CouchDB help file
+ .. config:option:: max_document_size :: Maximum document size
- This file contains the full `URI`_ that can be used to access this
- instance of CouchDB. It is used to help discover the port CouchDB is running
- on (if it was set to ``0`` (e.g. automatically assigned any free one).
- This file should be writable and readable for the user that runs the CouchDB
- service (``couchdb`` by default).
+ .. versionchanged:: 1.3 This option now actually works.
- ::
+ Defines a maximum size for JSON documents, in bytes. This limit does
+ not apply to attachments, since they are transferred as a stream of
+ chunks. If you set this to a small value, you might be unable to modify
+ configuration options, database security and other larger documents
+ until a larger value is restored by editing the configuration file. ::
- [couchdb]
- uri_file = /var/run/couchdb/couchdb.uri
+ [couchdb]
+ max_document_size = 4294967296 ; 4 GB
- .. _URI: http://en.wikipedia.org/wiki/URI
+ .. config:option:: os_process_timeout :: External processes time limit
+ If an external process, such as a query server or external process,
+ runs for this amount of microseconds without returning any results, it
+ will be terminated. Keeping this value smaller ensures you get
+ expedient errors, but you may want to tweak it for your specific
+ needs. ::
- .. config:option:: util_driver_dir :: CouchDB binary utility drivers
+ [couchdb]
+ os_process_timeout = 5000 ; 5 sec
- Specifies location of binary drivers (`icu`, `ejson`, etc.). This location
- and its contents should be readable for the user that runs the CouchDB
- service.
+ .. config:option:: uri_file :: Discovery CouchDB help file
- ::
+ This file contains the full `URI`_ that can be used to access this
+ instance of CouchDB. It is used to help discover the port CouchDB is
+ running on (if it was set to ``0`` (e.g. automatically assigned any
+ free one). This file should be writable and readable for the user that
+ runs the CouchDB service (``couchdb`` by default). ::
- [couchdb]
- util_driver_dir = /usr/lib/couchdb/erlang/lib/couch-1.5.0/priv/lib
+ [couchdb]
+ uri_file = /var/run/couchdb/couchdb.uri
+ .. _URI: http://en.wikipedia.org/wiki/URI
- .. config:option:: uuid :: CouchDB server UUID
+ .. config:option:: util_driver_dir :: CouchDB binary utility drivers
- .. versionadded:: 1.3
+ Specifies location of binary drivers (`icu`, `ejson`, etc.). This
+ location and its contents should be readable for the user that runs the
+ CouchDB service. ::
- Unique identifier for this CouchDB server instance.
+ [couchdb]
+ util_driver_dir = /usr/lib/couchdb/erlang/lib/couch-1.5.0/priv/lib
- ::
+ .. config:option:: uuid :: CouchDB server UUID
- [couchdb]
- uuid = 0a959b9b8227188afc2ac26ccdf345a6
+ .. versionadded:: 1.3
+ Unique identifier for this CouchDB server instance. ::
- .. config:option:: view_index_dir :: View indexes location directory
+ [couchdb]
+ uuid = 0a959b9b8227188afc2ac26ccdf345a6
- Specifies location of CouchDB view index files. This location should be
- writable and readable for the user that runs the CouchDB service
- (``couchdb`` by default).
+ .. config:option:: view_index_dir :: View indexes location directory
- ::
+ Specifies location of CouchDB view index files. This location should be
+ writable and readable for the user that runs the CouchDB service
+ (``couchdb`` by default). ::
- [couchdb]
- view_index_dir = /var/lib/couchdb
+ [couchdb]
+ view_index_dir = /var/lib/couchdb
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/71a4fc90/src/config/externals.rst
----------------------------------------------------------------------
diff --git a/src/config/externals.rst b/src/config/externals.rst
index c05fe05..9ce0f2f 100644
--- a/src/config/externals.rst
+++ b/src/config/externals.rst
@@ -11,7 +11,6 @@
.. the License.
.. default-domain:: config
-
.. highlight:: ini
==================
@@ -25,83 +24,81 @@ OS Daemons
.. config:section:: os_daemons :: OS Daemons
- This is a simple feature that allows users to configure CouchDB so that it
- maintains a given OS level process alive. If the process dies for any reason,
- CouchDB will restart it. If the process restarts too often, then CouchDB will
- mark it has halted and not attempt to restart it. The default max restart rate
- is ``3`` times in the last ``5`` seconds. These parameters are
- :section:`adjustable <os_daemon_settings>`.
-
- Commands that are started in this manner will have access to a simple
- API over stdio to request configuration parameters or to add log
- statements to CouchDB's logs.
+ This is a simple feature that allows users to configure CouchDB so that it
+ maintains a given OS level process alive. If the process dies for any
+ reason, CouchDB will restart it. If the process restarts too often, then
+ CouchDB will mark it has halted and not attempt to restart it. The default
+ max restart rate is ``3`` times in the last ``5`` seconds. These parameters
+ are :section:`adjustable <os_daemon_settings>`.
- To configure an OS process as a CouchDB os_daemon, create a section
- in your `local.ini` like such::
+ Commands that are started in this manner will have access to a simple API
+ over stdio to request configuration parameters or to add log statements to
+ CouchDB's logs.
- [os_daemons]
- daemon_name = /path/to/command -with args
+ To configure an OS process as a CouchDB os_daemon, create a section in your
+ `local.ini` like such::
- This will make CouchDB bring up the command and attempt to keep it
- alive. To request a configuration parameter, an `os_daemon` can write
- a simple JSON message to stdout like such::
+ [os_daemons]
+ daemon_name = /path/to/command -with args
- ["get", "os_daemons"]\n
+ This will make CouchDB bring up the command and attempt to keep it alive.
+ To request a configuration parameter, an `os_daemon` can write a simple
+ JSON message to stdout like such::
- which would return::
+ ["get", "os_daemons"]\n
- {"daemon_name": "/path/to/command -with args"}\n
+ which would return::
- Or::
+ {"daemon_name": "/path/to/command -with args"}\n
- ["get", "os_daemons", "daemon_name"]\n
+ Or::
- which would return::
+ ["get", "os_daemons", "daemon_name"]\n
- "/path/to/command -with args"\n
+ which would return::
- There's no restriction on what configuration variables are visible.
- There's also no method for altering the configuration.
+ "/path/to/command -with args"\n
- If you would like your OS daemon to be restarted in the event that
- the configuration changes, you can send the following messages::
+ There's no restriction on what configuration variables are visible. There's
+ also no method for altering the configuration.
- ["register", $(SECTION)]\n
+ If you would like your OS daemon to be restarted in the event that the
+ configuration changes, you can send the following messages::
- When anything in that section changes, your OS process will be
- rebooted so it can pick up the new configuration settings. If you
- want to listen for changes on a specific key, you can send something
- like::
+ ["register", $(SECTION)]\n
- ["register", $(SECTION), $(KEY)]\n
+ When anything in that section changes, your OS process will be rebooted so
+ it can pick up the new configuration settings. If you want to listen for
+ changes on a specific key, you can send something like::
- In this case, CouchDB will only restart your daemon if that exact
- section/key pair changes, instead of anything in that entire section.
+ ["register", $(SECTION), $(KEY)]\n
- Logging commands look like::
+ In this case, CouchDB will only restart your daemon if that exact
+ section/key pair changes, instead of anything in that entire section.
- ["log", $(JSON_MESSAGE)]\n
+ Logging commands look like::
- Where ``$(JSON_MESSAGE)`` is arbitrary JSON data. These messages are
- logged at the 'info' level. If you want to log at a different level
- you can pass messages like such::
+ ["log", $(JSON_MESSAGE)]\n
- ["log", $(JSON_MESSAGE), {"level": $(LEVEL)}]\n
+ Where ``$(JSON_MESSAGE)`` is arbitrary JSON data. These messages are logged
+ at the 'info' level. If you want to log at a different level you can pass
+ messages like such::
- Where ``$(LEVEL)`` is one of "debug", "info", or "error".
+ ["log", $(JSON_MESSAGE), {"level": $(LEVEL)}]\n
- When implementing a daemon process to be managed by CouchDB you
- should remember to use a method like checking the parent process
- id or if stdin has been closed. These flags can tell you if
- your daemon process has been orphaned so you can exit cleanly.
+ Where ``$(LEVEL)`` is one of "debug", "info", or "error".
- There is no interactivity between CouchDB and the running process, but
- you can use the OS Daemons service to create new HTTP servers and
- responders and then use the new proxy service to redirect requests and
- output to the CouchDB managed service. For more information on proxying,
- see :ref:`http-proxying`. For further background on the OS Daemon service,
- see :ref:`externals`.
+ When implementing a daemon process to be managed by CouchDB you should
+ remember to use a method like checking the parent process id or if stdin
+ has been closed. These flags can tell you if your daemon process has been
+ orphaned so you can exit cleanly.
+ There is no interactivity between CouchDB and the running process, but you
+ can use the OS Daemons service to create new HTTP servers and responders
+ and then use the new proxy service to redirect requests and output to the
+ CouchDB managed service. For more information on proxying, see
+ :ref:`http-proxying`. For further background on the OS Daemon service,
+ see :ref:`externals`.
.. _config/os_daemon_settings:
@@ -110,23 +107,20 @@ OS Daemons settings
.. config:section:: os_daemon_settings :: OS Daemons settings
+ .. config:option:: max_retries :: Maximum restart retries
- .. config:option:: max_retries :: Maximum restart retries
-
- Specifies maximum attempts to run :section:`os_daemons` before
- mark them halted::
-
- [os_daemon_settings]
- max_retries = 3
+ Specifies maximum attempts to run :section:`os_daemons` before mark
+ them halted::
+ [os_daemon_settings]
+ max_retries = 3
- .. config:option:: retry_time :: Delay between restart attempts
+ .. config:option:: retry_time :: Delay between restart attempts
- Delay in seconds between :section:`os_daemons` restarts::
-
- [os_daemon_settings]
- retry_time = 5
+ Delay in seconds between :section:`os_daemons` restarts::
+ [os_daemon_settings]
+ retry_time = 5
.. _update-notifications:
.. _config/update_notification:
@@ -136,44 +130,42 @@ Update notifications
.. config:section:: update_notification :: Update notifications
- CouchDB is able to spawn OS processes to notify them about recent databases
- updates. The notifications are in form of JSON messages sent as a line of
- text, terminated by ``CR`` (``\n``) character, to the OS processes through
- `stdout`::
-
- [update_notification]
- ;unique notifier name=/full/path/to/exe -with "cmd line arg"
- index_updater = ruby /usr/local/bin/index_updater.rb
-
- The update notification messages are depend upon of event type:
-
- - **Database created**:
+ CouchDB is able to spawn OS processes to notify them about recent databases
+ updates. The notifications are in form of JSON messages sent as a line of
+ text, terminated by ``CR`` (``\n``) character, to the OS processes through
+ `stdout`::
- .. code-block:: javascript
+ [update_notification]
+ ;unique notifier name=/full/path/to/exe -with "cmd line arg"
+ index_updater = ruby /usr/local/bin/index_updater.rb
- {"type":"created","db":"dbname"}
+ The update notification messages are depend upon of event type:
+ - **Database created**:
- - **Database updated**: this event raises when any document gets updated for
- specified database:
+ .. code-block:: javascript
- .. code-block:: javascript
+ {"type":"created","db":"dbname"}
- {"type":"updated","db":"dbname"}
+ - **Database updated**: this event raises when any document gets updated
+ for specified database:
+ .. code-block:: javascript
- - **Design document updated**: for design document updates there is special
- event raised in additional to regular db update one:
+ {"type":"updated","db":"dbname"}
- .. code-block:: javascript
+ - **Design document updated**: for design document updates there is special
+ event raised in additional to regular db update one:
- {"type":"ddoc_updated","db":"dbname","id":"_design/ddoc_name"}
+ .. code-block:: javascript
+ {"type":"ddoc_updated","db":"dbname","id":"_design/ddoc_name"}
- - **Database deleted**:
+ - **Database deleted**:
- .. code-block:: javascript
+ .. code-block:: javascript
- {"type":"deleted","db":"dbname"}
+ {"type":"deleted","db":"dbname"}
- .. note:: New line (``\n``) trailing character was removed from examples.
+ .. note::
+ New line (``\n``) trailing character was removed from examples.
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/71a4fc90/src/config/http-handlers.rst
----------------------------------------------------------------------
diff --git a/src/config/http-handlers.rst b/src/config/http-handlers.rst
index 0c0f8f3..9dbfcf4 100644
--- a/src/config/http-handlers.rst
+++ b/src/config/http-handlers.rst
@@ -23,138 +23,118 @@ Global HTTP Handlers
.. config:section:: httpd_global_handlers :: Global HTTP Handlers
- These HTTP resources are provided for CouchDB server root level.
+ These HTTP resources are provided for CouchDB server root level.
- .. config:option:: /
+ .. config:option:: /
- ::
+ ::
- [httpd_global_handlers]
- / = {couch_httpd_misc_handlers, handle_welcome_req, <<"Welcome">>}
+ [httpd_global_handlers]
+ / = {couch_httpd_misc_handlers, handle_welcome_req, <<"Welcome">>}
+ .. config:option:: favicon.ico
+ The favicon handler looks for `favicon.ico` file within specified
+ directory::
- .. config:option:: favicon.ico
+ [httpd_global_handlers]
+ favicon.ico = {couch_httpd_misc_handlers, handle_favicon_req, "/usr/share/couchdb/www"}
- The favicon handler looks for `favicon.ico` file within specified directory::
+ .. config:option:: _active_tasks
- [httpd_global_handlers]
- favicon.ico = {couch_httpd_misc_handlers, handle_favicon_req, "/usr/share/couchdb/www"}
+ ::
+ [httpd_global_handlers]
+ _active_tasks = {couch_httpd_misc_handlers, handle_task_status_req}
+ .. config:option:: _all_dbs
- .. config:option:: _active_tasks
+ Provides a list of all server's databases::
- ::
+ [httpd_global_handlers]
+ _all_dbs = {couch_httpd_misc_handlers, handle_all_dbs_req}
- [httpd_global_handlers]
- _active_tasks = {couch_httpd_misc_handlers, handle_task_status_req}
+ .. note::
+ Sometimes you don't want to disclose database names for everyone,
+ but you also don't like/want/able to setup any proxies in front of
+ CouchDB. Removing this handler disables ``_all_dbs`` resource and
+ there will be no way to get list of available databases.
+ The same also is true for other resource handlers.
+ .. config:option:: _config
- .. config:option:: _all_dbs
+ Provides resource to work with CouchDB config
+ :ref:`remotely <api/config>`. Any config changes that was made via HTTP
+ API are applied automatically on fly and doesn't requires server
+ instance to be restarted::
- Provides a list of all server's databases::
+ [httpd_global_handlers]
+ _config = {couch_httpd_misc_handlers, handle_config_req}
- [httpd_global_handlers]
- _all_dbs = {couch_httpd_misc_handlers, handle_all_dbs_req}
+ .. config:option:: _log
- .. note::
+ ::
- Sometimes you don't want to disclose database names for everyone, but
- you also don't like/want/able to setup any proxies in front of CouchDB.
- Removing this handler disables ``_all_dbs`` resource and there will be
- no way to get list of available databases.
+ [httpd_global_handlers]
+ _log = {couch_httpd_misc_handlers, handle_log_req}
- The same also is true for other resource handlers.
+ .. config:option:: _oauth
+ ::
+ [httpd_global_handlers]
+ _oauth = {couch_httpd_oauth, handle_oauth_req}
- .. config:option:: _config
+ .. config:option:: _replicate
- Provides resource to work with CouchDB config :ref:`remotely <api/config>`.
- Any config changes that was made via HTTP API are applied automatically on
- fly and doesn't requires server instance to be restarted::
+ Provides an API to run
+ :ref:`temporary replications <api/server/replicate>`::
- [httpd_global_handlers]
- _config = {couch_httpd_misc_handlers, handle_config_req}
+ [httpd_global_handlers]
+ _replicate = {couch_replicator_httpd, handle_req}
+ .. config:option:: _restart
+ ::
- .. config:option:: _log
+ [httpd_global_handlers]
+ _restart = {couch_httpd_misc_handlers, handle_restart_req}
- ::
+ .. config:option:: _session
- [httpd_global_handlers]
- _log = {couch_httpd_misc_handlers, handle_log_req}
+ Provides a resource with information about the current user's session::
+ [httpd_global_handlers]
+ _session = {couch_httpd_auth, handle_session_req}
+ .. config:option:: _stats
- .. config:option:: _oauth
+ ::
- ::
+ [httpd_global_handlers]
+ _stats = {couch_httpd_stats_handlers, handle_stats_req}
- [httpd_global_handlers]
- _oauth = {couch_httpd_oauth, handle_oauth_req}
+ .. config:option:: _utils
+ The :ref:`_utils <api/server/utils>` handler serves `Futon`'s web
+ administration page::
+ [httpd_global_handlers]
+ _utils = {couch_httpd_misc_handlers, handle_utils_dir_req, "/usr/share/couchdb/www"}
- .. config:option:: _replicate
+ In similar way, you may setup custom handler to let CouchDB serve any
+ static files.
- Provides an API to run :ref:`temporary replications <api/server/replicate>`::
+ .. config:option:: _uuids
- [httpd_global_handlers]
- _replicate = {couch_replicator_httpd, handle_req}
+ Provides a resource to get UUIDs generated by CouchDB::
+ [httpd_global_handlers]
+ _uuids = {couch_httpd_misc_handlers, handle_uuids_req}
-
- .. config:option:: _restart
-
- ::
-
- [httpd_global_handlers]
- _restart = {couch_httpd_misc_handlers, handle_restart_req}
-
-
-
- .. config:option:: _session
-
- Provides a resource with information about the current user's session::
-
- [httpd_global_handlers]
- _session = {couch_httpd_auth, handle_session_req}
-
-
- .. config:option:: _stats
-
- ::
-
- [httpd_global_handlers]
- _stats = {couch_httpd_stats_handlers, handle_stats_req}
-
-
- .. config:option:: _utils
-
- The :ref:`_utils <api/server/utils>` handler serves `Futon`'s web administration
- page::
-
- [httpd_global_handlers]
- _utils = {couch_httpd_misc_handlers, handle_utils_dir_req, "/usr/share/couchdb/www"}
-
- In similar way, you may setup custom handler to let CouchDB serve any static
- files.
-
-
- .. config:option:: _uuids
-
- Provides a resource to get UUIDs generated by CouchDB::
-
- [httpd_global_handlers]
- _uuids = {couch_httpd_misc_handlers, handle_uuids_req}
-
- This is useful when your client environment isn't capable of providing truly
- random IDs (web browsers e.g.).
-
+ This is useful when your client environment isn't capable of providing
+ truly random IDs (web browsers e.g.).
.. _config/httpd_db_handlers:
@@ -163,79 +143,63 @@ Database HTTP Handlers
.. config:section:: httpd_db_handlers :: Database HTTP Handlers
- These HTTP resources are available on every CouchDB database.
-
-
- .. config:option:: _all_docs
-
- ::
+ These HTTP resources are available on every CouchDB database.
- [httpd_db_handlers]
- _all_docs = {couch_mrview_http, handle_all_docs_req}
+ .. config:option:: _all_docs
+ ::
+ [httpd_db_handlers]
+ _all_docs = {couch_mrview_http, handle_all_docs_req}
- .. config:option:: _local_docs
+ .. config:option:: _local_docs
- ::
+ ::
- [httpd_db_handlers]
- _local_docs = {couch_mrview_http, handle_local_docs_req}
+ [httpd_db_handlers]
+ _local_docs = {couch_mrview_http, handle_local_docs_req}
+ .. config:option:: _design_docs
+ ::
- .. config:option:: _design_docs
+ [httpd_db_handlers]
+ _design_docs = {couch_mrview_http, handle_design_docs_req}
- ::
+ .. config:option:: _changes
- [httpd_db_handlers]
- _design_docs = {couch_mrview_http, handle_design_docs_req}
+ ::
+ [httpd_db_handlers]
+ _changes = {couch_httpd_db, handle_changes_req}
+ .. config:option:: _compact
- .. config:option:: _changes
+ ::
- ::
+ [httpd_db_handlers]
+ _compact = {couch_httpd_db, handle_compact_req}
- [httpd_db_handlers]
- _changes = {couch_httpd_db, handle_changes_req}
+ .. config:option:: _design
+ ::
+ [httpd_db_handlers]
+ _design = {couch_httpd_db, handle_design_req}
- .. config:option:: _compact
+ .. config:option:: _temp_view
- ::
+ ::
- [httpd_db_handlers]
- _compact = {couch_httpd_db, handle_compact_req}
+ [httpd_db_handlers]
+ _temp_view = {couch_mrview_http, handle_temp_view_req}
+ .. config:option:: _view_cleanup
+ ::
- .. config:option:: _design
-
- ::
-
- [httpd_db_handlers]
- _design = {couch_httpd_db, handle_design_req}
-
-
-
- .. config:option:: _temp_view
-
- ::
-
- [httpd_db_handlers]
- _temp_view = {couch_mrview_http, handle_temp_view_req}
-
-
-
- .. config:option:: _view_cleanup
-
- ::
-
- [httpd_db_handlers]
- _view_cleanup = {couch_mrview_http, handle_cleanup_req}
-
+ [httpd_db_handlers]
+ _view_cleanup = {couch_mrview_http, handle_cleanup_req}
.. _config/httpd_design_handlers:
@@ -246,64 +210,51 @@ Design Documents HTTP Handlers
These HTTP resources are provided for design documents.
+ .. config:option:: _compact
- .. config:option:: _compact
-
- ::
-
- [httpd_design_handlers]
- _compact = {couch_mrview_http, handle_compact_req}
-
-
-
- .. config:option:: _info
-
- ::
-
- [httpd_design_handlers]
- _info = {couch_mrview_http, handle_info_req}
-
-
-
- .. config:option:: _list
-
- ::
-
- [httpd_design_handlers]
- _list = {couch_mrview_show, handle_view_list_req}
-
+ ::
+ [httpd_design_handlers]
+ _compact = {couch_mrview_http, handle_compact_req}
- .. config:option:: _rewrite
+ .. config:option:: _info
- ::
+ ::
- [httpd_design_handlers]
- _rewrite = {couch_httpd_rewrite, handle_rewrite_req}
+ [httpd_design_handlers]
+ _info = {couch_mrview_http, handle_info_req}
+ .. config:option:: _list
+ ::
- .. config:option:: _show
+ [httpd_design_handlers]
+ _list = {couch_mrview_show, handle_view_list_req}
- ::
+ .. config:option:: _rewrite
- [httpd_design_handlers]
- _show = {couch_mrview_show, handle_doc_show_req}
+ ::
+ [httpd_design_handlers]
+ _rewrite = {couch_httpd_rewrite, handle_rewrite_req}
+ .. config:option:: _show
- .. config:option:: _update
+ ::
- ::
+ [httpd_design_handlers]
+ _show = {couch_mrview_show, handle_doc_show_req}
- [httpd_design_handlers]
- _update = {couch_mrview_show, handle_doc_update_req}
+ .. config:option:: _update
+ ::
+ [httpd_design_handlers]
+ _update = {couch_mrview_show, handle_doc_update_req}
- .. config:option:: _view
+ .. config:option:: _view
- ::
+ ::
- [httpd_design_handlers]
- _view = {couch_mrview_http, handle_view_req}
+ [httpd_design_handlers]
+ _view = {couch_mrview_http, handle_view_req}