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 2013/10/01 11:39:23 UTC
[1/3] Add configuration domain.
Updated Branches:
refs/heads/master b14405041 -> 6f31ffd97
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/whatsnew/1.4.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/whatsnew/1.4.rst b/share/doc/src/whatsnew/1.4.rst
index 06577f6..cf10bef 100644
--- a/share/doc/src/whatsnew/1.4.rst
+++ b/share/doc/src/whatsnew/1.4.rst
@@ -47,7 +47,7 @@ Version 1.4.0
updates and deletion of databases. :commit:`917d8988`
* :issue:`1772`: Prevent invalid JSON output when using `all_or_nothing`
:ref:`of bulk API <api/db/bulk_docs>`. :commit:`dfd39d57`
-* Add a :ref:`configurable whitelist <config/couch_httpd_auth/public_fields>`
+* Add a :config:option:`configurable whitelist <couch_httpd_auth/public_fields>`
of user document properties. :commit:`8d7ab8b1`
* :issue:`1852`: Support Last-Event-ID header in EventSource changes feeds.
:commit:`dfd2199a`
[2/3] Add configuration domain.
Posted by kx...@apache.org.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/config/http.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/http.rst b/share/doc/src/config/http.rst
index 68981bf..41b8b9d 100644
--- a/share/doc/src/config/http.rst
+++ b/share/doc/src/config/http.rst
@@ -10,6 +10,8 @@
.. License for the specific language governing permissions and limitations under
.. the License.
+.. default-domain:: config
+
.. highlight:: ini
===================
@@ -18,301 +20,250 @@ CouchDB HTTP Server
.. _config/httpd:
-``[httpd]`` :: HTTP Server Options
-==================================
-
-These options are under ``[httpd]`` section.
-
-.. _config/httpd/allow_jsonp:
-
-``allow_jsonp`` :: Enables JSONP support
-----------------------------------------
-
-The ``true`` value of this option enables `JSONP`_ support (it's ``false`` by
-default)::
-
- [httpd]
- allow_jsonp = false
-
-
-.. _JSONP: http://www.json-p.org/
-
-
-.. _config/httpd/authentication_handlers:
-
-``authentication_handlers`` :: Authentication handlers
-------------------------------------------------------
-
-List of used authentication handlers that used by CouchDB. You may extend them
-via third-party plugins or remove some of them if you won't let users to use one
-of provided methods::
-
- [httpd]
- authentication_handlers = {couch_httpd_oauth, oauth_authentication_handler}, {couch_httpd_auth, cookie_authentication_handler}, {couch_httpd_auth, default_authentication_handler}
-
-- ``{couch_httpd_oauth, oauth_authentication_handler}``: handles OAuth;
-- ``{couch_httpd_auth, cookie_authentication_handler}``: used for Cookie auth;
-- ``{couch_httpd_auth, proxy_authentication_handler}``: used for Proxy auth;
-- ``{couch_httpd_auth, default_authentication_handler}``: used for Basic auth;
-- ``{couch_httpd_auth, null_authentication_handler}``: disables auth.
- Everlasting `Admin Party`!
-
-
-.. _config/httpd/bind_address:
-
-``bind_address`` :: Listen IP address
--------------------------------------
-
-Defines the IP address by which CouchDB will be accessible::
-
- [httpd]
- bind_address = 127.0.0.1
-
-To let CouchDB listen any available IP address, just setup ``0.0.0.0`` value::
-
- [httpd]
- bind_address = 0.0.0.0
+HTTP Server Options
+===================
-For IPv6 support you need to set ``::1`` if you want to let CouchDB listen local
-address::
+.. config:section:: httpd :: HTTP Server Options
- [httpd]
- bind_address = ::1
+ .. config:option:: allow_jsonp :: Enables JSONP support
-or ``::`` for any available::
+ The ``true`` value of this option enables `JSONP`_ support (it's ``false`` by
+ default)::
- [httpd]
- bind_address = ::
+ [httpd]
+ allow_jsonp = false
+ .. _JSONP: http://www.json-p.org/
-.. _config/httpd/changes_timeout:
-``changes_timeout`` :: Changes feed timeout
--------------------------------------------
+ .. config:option:: authentication_handlers :: Authentication handlers
-Specifies default `timeout` value for :ref:`Changes Feed <changes>` in
-milliseconds (60000 by default)::
+ List of used authentication handlers that used by CouchDB. You may extend
+ them via third-party plugins or remove some of them if you won't let users
+ to use one of provided methods::
- [httpd]
- changes_feed = 60000 ; 60 seconds
+ [httpd]
+ authentication_handlers = {couch_httpd_oauth, oauth_authentication_handler}, {couch_httpd_auth, cookie_authentication_handler}, {couch_httpd_auth, default_authentication_handler}
+ - ``{couch_httpd_oauth, oauth_authentication_handler}``: handles OAuth;
+ - ``{couch_httpd_auth, cookie_authentication_handler}``: used for Cookie auth;
+ - ``{couch_httpd_auth, proxy_authentication_handler}``: used for Proxy auth;
+ - ``{couch_httpd_auth, default_authentication_handler}``: used for Basic auth;
+ - ``{couch_httpd_auth, null_authentication_handler}``: disables auth.
+ Everlasting `Admin Party`!
-.. _config/httpd/config_whitelist:
-``config_whitelist`` :: Config options while list
--------------------------------------------------
+ .. config:option:: bind_address :: Listen IP address
-Sets the configuration modification whitelist. Only whitelisted values may be
-changed via the :ref:`config API <api/config>`. To allow the admin to change
-this value over HTTP, remember to include ``{httpd,config_whitelist}`` itself.
-Excluding it from the list would require editing this file to update the
-whitelist::
+ Defines the IP address by which CouchDB will be accessible::
- [httpd]
- config_whitelist = [{httpd,config_whitelist}, {log,level}, {etc,etc}]
+ [httpd]
+ bind_address = 127.0.0.1
+ To let CouchDB listen any available IP address, just setup ``0.0.0.0``
+ value::
-.. _config/httpd/default_handler:
+ [httpd]
+ bind_address = 0.0.0.0
-``default_handler`` :: Default request handler
-----------------------------------------------
+ For IPv6 support you need to set ``::1`` if you want to let CouchDB listen
+ local address::
-Specifies default HTTP requests handler::
+ [httpd]
+ bind_address = ::1
- [httpd]
- default_handler = {couch_httpd_db, handle_request}
+ or ``::`` for any available::
+ [httpd]
+ bind_address = ::
-.. _config/httpd/enable_cors:
-``enable_cors`` :: Activates CORS
----------------------------------
+ .. config:option:: changes_timeout :: Changes feed timeout
-.. versionadded:: 1.3
+ Specifies default `timeout` value for :ref:`Changes Feed <changes>` in
+ milliseconds (60000 by default)::
-Controls :ref:`CORS <config/cors>` feature::
+ [httpd]
+ changes_feed = 60000 ; 60 seconds
- [httpd]
- enable_cors = false
+ .. config:option:: config_whitelist :: Config options while list
-.. _config/httpd/log_max_chunk_size:
+ Sets the configuration modification whitelist. Only whitelisted values
+ may be changed via the :ref:`config API <api/config>`. To allow the admin
+ to change this value over HTTP, remember to include
+ ``{httpd,config_whitelist}`` itself. Excluding it from the list would
+ require editing this file to update the whitelist::
-``log_max_chunk_size`` :: Logs chunk size
------------------------------------------
+ [httpd]
+ config_whitelist = [{httpd,config_whitelist}, {log,level}, {etc,etc}]
-Defines maximum chunk size in bytes for :ref:`_log <api/server/log>` resource::
- [httpd]
- log_max_chunk_size = 1000000
+ .. config:option:: default_handler :: Default request handler
+ Specifies default HTTP requests handler::
-.. _config/httpd/port:
+ [httpd]
+ default_handler = {couch_httpd_db, handle_request}
-``port`` :: Listen port
------------------------
-Defined the port number to listen::
+ .. config:option:: enable_cors :: Activates CORS
- [httpd]
- port = 5984
+ .. versionadded:: 1.3
-To let CouchDB handle any free port, set this option to ``0``::
+ Controls :ref:`CORS <config/cors>` feature::
- [httpd]
- port = 0
+ [httpd]
+ enable_cors = false
-After that, CouchDB URI could be located within the URI file.
+ .. config:option:: log_max_chunk_size :: Logs chunk size
-.. _config/httpd/redirect_vhost_handler:
+ Defines maximum chunk size in bytes for :ref:`_log <api/server/log>`
+ resource::
-``redirect_vhost_handler`` :: Virtual Hosts custom redirect handler
--------------------------------------------------------------------
+ [httpd]
+ log_max_chunk_size = 1000000
-This option customizes the default function that handles requests to
-:ref:`virtual hosts <config/vhosts>`::
- [httpd]
- redirect_vhost_handler = {Module, Fun}
+ .. config:option:: port :: Listen port
-The specified function take 2 arguments: the Mochiweb request object and the
-target path.
+ Defined the port number to listen::
+ [httpd]
+ port = 5984
-.. _config/httpd/server_options:
+ To let CouchDB handle any free port, set this option to ``0``::
-``server_options`` :: MochiWeb Server Options
----------------------------------------------
+ [httpd]
+ port = 0
-Server options for the `MochiWeb`_ component of CouchDB can be added to the
-configuration files::
+ After that, CouchDB URI could be located within the URI file.
- [httpd]
- server_options = [{backlog, 128}, {acceptor_pool_size, 16}]
+ .. config:option:: redirect_vhost_handler :: Virtual Hosts custom redirect handler
-.. _MochiWeb: https://github.com/mochi/mochiweb
+ This option customizes the default function that handles requests to
+ :section:`virtual hosts <vhosts>`::
+ [httpd]
+ redirect_vhost_handler = {Module, Fun}
-.. _config/httpd/secure_rewrites:
+ The specified function take 2 arguments: the Mochiweb request object and the
+ target path.
-``secure_rewrites`` :: Default request handler
-----------------------------------------------
-This option allow to isolate databases via subdomains::
+ .. config:option:: server_options :: MochiWeb Server Options
- [httpd]
- secure_rewrites = true
+ Server options for the `MochiWeb`_ component of CouchDB can be added to the
+ configuration files::
+ [httpd]
+ server_options = [{backlog, 128}, {acceptor_pool_size, 16}]
-.. _config/httpd/socket_options:
+ .. _MochiWeb: https://github.com/mochi/mochiweb
-``socket_options`` :: Socket Options
-------------------------------------
-The socket options for the listening socket in CouchDB can be specified as a
-list of tuples. For example::
+ .. config:option:: secure_rewrites :: Default request handler
- [httpd]
- socket_options = [{recbuf, 262144}, {sndbuf, 262144}, {nodelay, true}]
+ This option allow to isolate databases via subdomains::
-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.
+ [httpd]
+ secure_rewrites = true
-.. _Erlang inet: http://www.erlang.org/doc/man/inet.html#setopts-2
+ .. config:option:: socket_options :: Socket Options
-.. _config/httpd/vhost_global_handlers:
+ The socket options for the listening socket in CouchDB can be specified as
+ a list of tuples. For example::
-``vhost_global_handlers`` :: Virtual hosts global handlers
-----------------------------------------------------------
+ [httpd]
+ socket_options = [{recbuf, 262144}, {sndbuf, 262144}, {nodelay, true}]
-List of global handlers that are available for
-:ref:`virtual hosts <config/vhosts>`::
+ 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.
- [httpd]
- vhost_global_handlers = _utils, _uuids, _session, _oauth, _users
+ .. _Erlang inet: http://www.erlang.org/doc/man/inet.html#setopts-2
-.. _config/httpd/x_forwarded_host:
+ .. config:option:: vhost_global_handlers :: Virtual hosts global handlers
-``x_forwarded_host`` :: X-Forwarder-Host
-----------------------------------------
+ List of global handlers that are available for :section:`virtual hosts
+ <vhosts>`::
-The `x_forwarded_host` header (``X-Forwarded-Host`` by default) is used to
-forward the original value of the ``Host`` header field in case, for example,
-if a reverse proxy is rewriting the "Host" header field to some internal host
-name before forward the request to CouchDB::
+ [httpd]
+ vhost_global_handlers = _utils, _uuids, _session, _oauth, _users
- [httpd]
- x_forwarded_host = X-Forwarded-Host
-This header has higher priority above ``Host`` one, if only it exists in the
-request.
+ .. config:option:: x_forwarded_host :: X-Forwarder-Host
-.. _config/httpd/x_forwarded_proto:
+ 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::
-``x_forwarded_proto`` :: X-Forwarder-Proto
-------------------------------------------
+ [httpd]
+ x_forwarded_host = X-Forwarded-Host
-`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::
+ This header has higher priority above ``Host`` one, if only it exists in
+ the request.
- [httpd]
- x_forwarded_proto = X-Forwarded-Proto
+ .. config:option:: x_forwarded_proto :: X-Forwarder-Proto
-.. _config/httpd/x_forwarded_ssl:
+ `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::
-``x_forwarded_ssl`` :: X-Forwarder-Ssl
---------------------------------------
+ [httpd]
+ x_forwarded_proto = X-Forwarded-Proto
-The `x_forwarded_ssl` header (``X-Forwarded-Ssl`` by default) tells CouchDB that
-it should use the `https` scheme instead of the `http`. Actually, it's a synonym
-for ``X-Forwarded-Proto: https`` header, but used by some reverse proxies::
- [httpd]
- x_forwarded_ssl = X-Forwarded-Ssl
+ .. config:option:: x_forwarded_ssl :: X-Forwarder-Ssl
+ The `x_forwarded_ssl` header (``X-Forwarded-Ssl`` by default) tells CouchDB
+ that it should use the `https` scheme instead of the `http`. Actually, it's
+ a synonym for ``X-Forwarded-Proto: https`` header, but used by some reverse
+ proxies::
-.. _config/httpd/WWW-Authenticate:
+ [httpd]
+ x_forwarded_ssl = X-Forwarded-Ssl
-``WWW-Authenticate`` :: Force basic auth
-----------------------------------------
-Set this option to trigger basic-auth popup on unauthorized requests::
+ .. config:option:: WWW-Authenticate :: Force basic auth
- [httpd]
- WWW-Authenticate = Basic realm="Welcome to the Couch!"
+ Set this option to trigger basic-auth popup on unauthorized requests::
+ [httpd]
+ WWW-Authenticate = Basic realm="Welcome to the Couch!"
.. _config/ssl:
-``[ssl]`` :: Secure Socket Level Options
-========================================
+Secure Socket Level Options
+===========================
-CouchDB supports SSL natively. All your secure connection needs can
-now be served without needing to setup and maintain a separate proxy server
-that handles SSL.
+.. config:section:: ssl :: Secure Socket Level Options
-SSL setup can be tricky, but the configuration in CouchDB was designed
-to be as easy as possible. All you need is two files; a certificate and
-a private key. If you bought an official SSL certificate from a
-certificate authority, both should be in your possession already.
+ CouchDB supports SSL natively. All your secure connection needs can
+ now be served without needing to setup and maintain a separate proxy server
+ that handles SSL.
-If you just want to try this out and don't want to pay anything upfront,
-you can create a self-signed certificate. Everything will work the same,
-but clients will get a warning about an insecure certificate.
+ SSL setup can be tricky, but the configuration in CouchDB was designed
+ to be as easy as possible. All you need is two files; a certificate and
+ a private key. If you bought an official SSL certificate from a
+ certificate authority, both should be in your possession already.
-You will need the `OpenSSL`_ command line tool installed. It probably
-already is.
+ If you just want to try this out and don't want to pay anything upfront,
+ you can create a self-signed certificate. Everything will work the same,
+ but clients will get a warning about an insecure certificate.
-.. code-block:: bash
+ You will need the `OpenSSL`_ command line tool installed. It probably
+ already is.
+
+ .. code-block:: bash
shell> mkdir /etc/couchdb/cert
shell> cd /etc/couchdb/cert
@@ -321,28 +272,28 @@ already is.
shell> chmod 600 privkey.pem couchdb.pem
shell> chown couchdb privkey.pem couchdb.pem
-Now, you need to edit CouchDB's configuration, either by editing your
-``local.ini`` file or using the ``/_config`` API calls or the
-configuration screen in Futon. Here is what you need to do in
-``local.ini``, you can infer what needs doing in the other places.
+ Now, you need to edit CouchDB's configuration, either by editing your
+ ``local.ini`` file or using the ``/_config`` API calls or the
+ configuration screen in Futon. Here is what you need to do in
+ ``local.ini``, you can infer what needs doing in the other places.
-At first, :ref:`enable HTTPS daemon <config/daemons/httpsd>`::
+ At first, :option:`enable HTTPS daemon <daemons/httpsd>`::
- [daemons]
- httpsd = {couch_httpd, start_link, [https]}
+ [daemons]
+ httpsd = {couch_httpd, start_link, [https]}
-Next, under ``[ssl]`` section setup newly generated certificates::
+ Next, under ``[ssl]`` section setup newly generated certificates::
- [ssl]
- cert_file = /etc/couchdb/cert/couchdb.pem
- key_file = /etc/couchdb/cert/privkey.pem
+ [ssl]
+ cert_file = /etc/couchdb/cert/couchdb.pem
+ key_file = /etc/couchdb/cert/privkey.pem
-For more information please read `certificates HOWTO`_.
+ 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:
+ Now start (or restart) CouchDB. You should be able to connect to it
+ using HTTPS on port 6984:
-.. code-block:: bash
+ .. code-block:: bash
shell> curl https://127.0.0.1:6984/
curl: (60) SSL certificate problem, verify that the CA cert is OK. Details:
@@ -360,221 +311,205 @@ using HTTPS on port 6984:
If you'd like to turn off curl's verification of the certificate, use
the -k (or --insecure) option.
-Oh no what happened?! — Remember, clients will notify their users that
-your certificate is self signed. ``curl`` is the client in this case and
-it notifies you. Luckily you trust yourself (don't you?) and you can
-specify the ``-k`` option as the message reads:
+ 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:
-.. code-block:: bash
+ .. code-block:: bash
shell> curl -k https://127.0.0.1:6984/
{"couchdb":"Welcome","version":"1.5.0"}
-All done.
-
-.. _`certificates HOWTO`: http://www.openssl.org/docs/HOWTO/certificates.txt
-.. _OpenSSL: http://www.openssl.org/
-
-.. _config/ssl/cacert_file:
-
-``cacert_file`` :: CA Certificate file
---------------------------------------
-
-Path to file containing PEM encoded CA certificates (trusted certificates used
-for verifying a peer certificate). May be omitted if you do not want to verify
-the peer::
-
- [ssl]
- cacert_file = /etc/ssl/certs/ca-certificates.crt
+ All done.
+ .. _`certificates HOWTO`: http://www.openssl.org/docs/HOWTO/certificates.txt
+ .. _OpenSSL: http://www.openssl.org/
-.. _config/ssl/cert_file:
-``cert_file`` :: Certificate file
----------------------------------
+ .. config:option:: cacert_file :: CA Certificate file
-Path to a file containing the user's certificate::
+ Path to file containing PEM encoded CA certificates (trusted certificates
+ used for verifying a peer certificate). May be omitted if you do not want
+ to verify the peer::
- [ssl]
- cert_file = /etc/couchdb/cert/couchdb.pem
+ [ssl]
+ cacert_file = /etc/ssl/certs/ca-certificates.crt
-.. _config/ssl/key_file:
+ .. config:option:: cert_file :: Certificate file
-``key_file`` :: Certificate key file
-------------------------------------
+ Path to a file containing the user's certificate::
-Path to file containing user's private PEM encoded key::
+ [ssl]
+ cert_file = /etc/couchdb/cert/couchdb.pem
- [ssl]
- key_file = /etc/couchdb/cert/privkey.pem
+ .. config:option:: key_file :: Certificate key file
-.. _config/ssl/password:
+ Path to file containing user's private PEM encoded key::
-``password`` :: Certificate key password
-----------------------------------------
+ [ssl]
+ key_file = /etc/couchdb/cert/privkey.pem
-String containing the user's password. Only used if the private keyfile is
-password protected::
- [ssl]
- password = somepassword
+ .. config:option:: password :: Certificate key password
+ String containing the user's password. Only used if the private keyfile is
+ password protected::
-.. _config/ssl/ssl_certificate_max_depth:
+ [ssl]
+ password = somepassword
-``ssl_certificate_max_depth`` :: Maximum peer certificate depth
----------------------------------------------------------------
-Maximum peer certificate depth (must be set even if certificate validation is
-off)::
+ .. config:option:: ssl_certificate_max_depth :: Maximum peer certificate depth
- [ssl]
- ssl_certificate_max_depth = 1
+ Maximum peer certificate depth (must be set even if certificate validation
+ is off)::
+ [ssl]
+ ssl_certificate_max_depth = 1
-.. _config/ssl/verify_fun:
-``verify_fun`` :: SSL verification function
--------------------------------------------
+ .. config:option:: verify_fun :: SSL verification function
-The verification fun (optional) if not specified, the default
-verification fun will be used::
+ The verification fun (optional) if not specified, the default
+ verification fun will be used::
- [ssl]
- verify_fun = {Module, VerifyFun}
+ [ssl]
+ verify_fun = {Module, VerifyFun}
-.. _config/ssl/verify_ssl_certificates:
+ .. config:option:: verify_ssl_certificates :: Enable certificate verification
-``verify_ssl_certificates`` :: Enable certificate verification
---------------------------------------------------------------
-
-Set to `true` to validate peer certificates::
-
- [ssl]
- verify_ssl_certificates = false
+ Set to `true` to validate peer certificates::
+ [ssl]
+ verify_ssl_certificates = false
.. _cors:
.. _config/cors:
-``[cors]`` :: Cross-Origin Resource Sharing
-===========================================
+Cross-Origin Resource Sharing
+=============================
-.. versionadded:: 1.3 added CORS support, see JIRA :issue:`431`
+.. config:section:: cors :: Cross-Origin Resource Sharing
-`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.
+ .. versionadded:: 1.3 added CORS support, see JIRA :issue:`431`
-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.
+ `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.
-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.
+ 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.
-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.
+ 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.
-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.
+ 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.
-This section requires :ref:`enable_cors <config/httpd/enable_cors>` option have
-``true`` value::
+ 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.
- [httpd]
- enable_cors = true
+ This section requires :option:`httpd/enable_cors` option have
+ ``true`` value::
+ [httpd]
+ enable_cors = true
-Global Setup
-------------
-These options are under ``[cors]`` section. They are have global affect for
-all CORS-enabled instances.
+ .. config:option:: 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.
-.. _config/cors/credentials:
+ ::
-``credentials``
-^^^^^^^^^^^^^^^
+ [cors]
+ credentials = true
-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.
+ CouchDB will respond to a credentials-enabled CORS request with an
+ additional header, ``Access-Control-Allow-Credentials=true``.
-::
- [cors]
- credentials = true
+ .. config:option:: origins
-CouchDB will respond to a credentials-enabled CORS request with an additional
-header, ``Access-Control-Allow-Credentials=true``.
+ List of origins separated by a comma, ``*`` means accept all.
+ You can’t set ``origins = *`` and ``credentials = true`` option at the same
+ time::
+ [cors]
+ origins = *
-.. _config/cors/origins:
+ Access can be restricted by protocol, host and optionally by port. Origins
+ must follow the scheme: http://example.com:80::
-``origins``
-^^^^^^^^^^^
+ [cors]
+ origins = http://localhost, https://localhost, http://couch.mydev.name:8080
-List of origins separated by a comma, ``*`` means accept all.
-You can’t set ``origins = *`` and ``credentials = true`` option at the same
-time::
+ Note that by default, no origins are accepted. You must define them
+ explicitly.
- [cors]
- origins = *
-Access can be restricted by protocol, host and optionally by port. Origins must
-follow the scheme: http://example.com:80::
+ .. config:option:: headers
+
+ List of accepted headers separated by a comma::
- [cors]
- origins = http://localhost, https://localhost, http://couch.mydev.name:8080
+ [cors]
+ headers = X-Couch-Id, X-Couch-Rev
-Note that by default, no origins are accepted. You must define them explicitly.
+ .. config:option:: methods
-.. _config/cors/headers:
+ List of accepted methods::
-``headers``
-^^^^^^^^^^^
+ [cors]
+ methods = GET,POST
-List of accepted headers separated by a comma::
+ .. seealso::
- [cors]
- headers = X-Couch-Id, X-Couch-Rev
+ Original JIRA `implementation ticket <https://issues.apache.org/jira/browse/COUCHDB-431>`_
+ Standards and References:
-.. _config/cors/methods:
+ - IETF RFCs relating to methods: :rfc:`2618`, :rfc:`2817`, :rfc:`5789`
+ - IETF RFC for Web Origins: :rfc:`6454`
+ - W3C `CORS standard <http://www.w3.org/TR/cors>`_
-``methods``
-^^^^^^^^^^^
+ Mozilla Developer Network Resources:
-List of accepted methods::
+ - `Same origin policy for URIs <https://developer.mozilla.org/en-US/docs/Same-origin_policy_for_file:_URIs>`_
+ - `HTTP Access Control <https://developer.mozilla.org/En/HTTP_access_control>`_
+ - `Server-side Access Control <https://developer.mozilla.org/En/Server-Side_Access_Control>`_
+ - `Javascript same origin policy <https://developer.mozilla.org/en-US/docs/Same_origin_policy_for_JavaScript>`_
- [cors]
- methods = GET,POST
+ Client-side CORS support and usage:
+ - `CORS browser support matrix <http://caniuse.com/cors>`_
+ - `COS tutorial <http://www.html5rocks.com/en/tutorials/cors/>`_
+ - `XHR with CORS <http://hacks.mozilla.org/2009/07/cross-site-xmlhttprequest-with-cors/>`_
-.. _config/cors/vhost:
Per Virtual Host Configuration
------------------------------
-To set the options for a :ref:`config/vhosts`, you will need to create a section
-with the vhost name prefixed by ``cors:`` .
-Example case for the vhost `example.com`::
+To set the options for a :section:`vhosts`, you will need to create a section
+with the vhost name prefixed by ``cors:``. Example case for the vhost
+`example.com`::
[cors:example.com]
credentials = false
@@ -585,80 +520,58 @@ Example case for the vhost `example.com`::
; List of accepted methods
methods = HEAD, GET
-.. seealso::
-
- Original JIRA `implementation ticket <https://issues.apache.org/jira/browse/COUCHDB-431>`_
-
- Standards and References:
-
- - IETF RFCs relating to methods: :rfc:`2618`, :rfc:`2817`, :rfc:`5789`
- - IETF RFC for Web Origins: :rfc:`6454`
- - W3C `CORS standard <http://www.w3.org/TR/cors>`_
-
- Mozilla Developer Network Resources:
-
- - `Same origin policy for URIs <https://developer.mozilla.org/en-US/docs/Same-origin_policy_for_file:_URIs>`_
- - `HTTP Access Control <https://developer.mozilla.org/En/HTTP_access_control>`_
- - `Server-side Access Control <https://developer.mozilla.org/En/Server-Side_Access_Control>`_
- - `Javascript same origin policy <https://developer.mozilla.org/en-US/docs/Same_origin_policy_for_JavaScript>`_
-
- Client-side CORS support and usage:
-
- - `CORS browser support matrix <http://caniuse.com/cors>`_
- - `COS tutorial <http://www.html5rocks.com/en/tutorials/cors/>`_
- - `XHR with CORS <http://hacks.mozilla.org/2009/07/cross-site-xmlhttprequest-with-cors/>`_
-
.. _config/vhosts:
-``[vhosts]`` :: Virtual Hosts
-=============================
+Virtual Hosts
+=============
-CouchDB can map requests to different locations based on the ``Host`` header,
-even if they arrive on the some inbound IP address.
+.. config:section:: vhosts :: Virtual Hosts
-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 :ref:`Rewrite Handler <api/ddoc/rewrite>`, to provide full
-control over the application's URIs.
+ CouchDB can map requests to different locations based on the ``Host`` header,
+ even if they arrive on the some inbound IP address.
-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:
+ 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 :ref:`Rewrite Handler <api/ddoc/rewrite>`, to provide full
+ control over the application's URIs.
-.. code-block:: text
+ To add a virtual host, add a `CNAME` pointer to the DNS for your domain
+ name. For development and testing, it is sufficient to add an entry in
+ the hosts file, typically `/etc/hosts`` on Unix-like operating systems:
- # CouchDB vhost definitions, refer to local.ini for further details
- 127.0.0.1 couchdb.local
+ .. code-block:: text
-Test that this is working:
+ # CouchDB vhost definitions, refer to local.ini for further details
+ 127.0.0.1 couchdb.local
-.. code-block:: bash
+ Test that this is working:
- $ ping -n 2 couchdb.local
- PING couchdb.local (127.0.0.1) 56(84) bytes of data.
- 64 bytes from localhost (127.0.0.1): icmp_req=1 ttl=64 time=0.025 ms
- 64 bytes from localhost (127.0.0.1): icmp_req=2 ttl=64 time=0.051 ms
+ .. code-block:: bash
-Finally, add an entry to your :ref:`configuration file <config>` in the
-``[vhosts]`` section::
+ $ ping -n 2 couchdb.local
+ PING couchdb.local (127.0.0.1) 56(84) bytes of data.
+ 64 bytes from localhost (127.0.0.1): icmp_req=1 ttl=64 time=0.025 ms
+ 64 bytes from localhost (127.0.0.1): icmp_req=2 ttl=64 time=0.051 ms
- [vhosts]
- couchdb.local:5984 = /example
- *.couchdb.local:5984 = /example
+ Finally, add an entry to your :ref:`configuration file <config>` in the
+ ``[vhosts]`` section::
-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.
+ [vhosts]
+ couchdb.local:5984 = /example
+ *.couchdb.local:5984 = /example
-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.
+ 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.
-.. _config/vhosts/rewriting:
Rewriting Hosts to a Path
-------------------------
@@ -672,9 +585,9 @@ variable and use them to create the target path. Some examples::
: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`.
+The first rule passes the wildcard as `dbname`. The second one does the same,
+but uses a variable name. And the third one allows you to use any URL with
+`ddocname` in any database with `dbname`.
You could also change the default function to handle request by changing
-the setting :ref:`redirect_vhost_handler <config/httpd/redirect_vhost_handler>`
-in :ref:`httpd <config/httpd>` config section.
+the setting :option:`httpd/redirect_vhost_handler`.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/config/intro.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/intro.rst b/share/doc/src/config/intro.rst
index f8cffbe..0198af2 100644
--- a/share/doc/src/config/intro.rst
+++ b/share/doc/src/config/intro.rst
@@ -10,6 +10,8 @@
.. License for the specific language governing permissions and limitations under
.. the License.
+.. default-domain:: config
+
.. highlight:: ini
.. _config/intro:
@@ -52,8 +54,8 @@ CouchDB configuration::
/etc/couchdb/local.d/vendor.ini
Settings in successive documents override the settings in earlier entries.
-For example, setting the :ref:`bind_address <config/httpd/bind_address>`
-parameter in ``local.ini`` would override any setting in ``default.ini``.
+For example, setting the :option:`httpd/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
@@ -112,8 +114,8 @@ specification, empty (space and newline characters only) or `commented` line.
You can setup `inline` commentaries for `sections` or `parameters`.
The `section` defines group of parameters that are belongs to some specific
-CouchDB subsystem. For instance, :ref:`httpd <config/httpd>` section holds not
-only HTTP server parameters, but also others that directly interacts with it.
+CouchDB subsystem. For instance, :section:`httpd` section holds not only HTTP
+server parameters, but also others that directly interacts with it.
The `parameter` specification contains two parts divided by the `equal` sign
(``=``): the parameter name on the left side and the parameter value on the
@@ -154,7 +156,7 @@ In the response the old parameter's value returns::
You should be careful with changing configuration via the HTTP API since it's
easy to make CouchDB unavailable. For instance, you'd like to change the
-:ref:`bind_address <config/httpd/bind_address>` for new one::
+:option:`httpd/bind_address` for new one::
curl -X PUT http://localhost:5984/_config/httpd/bind_address -d '"10.10.0.128"'
@@ -162,7 +164,7 @@ However, if you would made a typo or the specified IP address is not available
from your network, you'll make CouchDB unavailable for you in both cases and
you will have the only way to fix the problem by edit the configuration file
and restart the server. To protect yourself against such accidents you may
-setup the :ref:`whilelist <config/httpd/config_whitelist>` of configuration
-parameters that are allowed to edit via the HTTP API. For others you'll need to
-directly edit the configuration file so you may quick fix any problems that had
-occurred due to misconfiguring.
+setup the :option:`httpd/config_whitelist` of configuration parameters that
+are allowed to edit via the HTTP API. For others you'll need to directly edit
+the configuration file so you may quick fix any problems that had occurred due
+to misconfiguring.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/config/logging.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/logging.rst b/share/doc/src/config/logging.rst
index 9c3bbaa..086749f 100644
--- a/share/doc/src/config/logging.rst
+++ b/share/doc/src/config/logging.rst
@@ -10,6 +10,8 @@
.. License for the specific language governing permissions and limitations under
.. the License.
+.. default-domain:: config
+
.. highlight:: ini
=======
@@ -18,77 +20,75 @@ Logging
.. _config/log:
-``[log]`` :: Logging options
-============================
+Logging options
+================
-CouchDB logging configuration.
+.. config:section:: log :: Logging options
-.. _config/log/file:
+ CouchDB logging configuration.
-``file`` :: Logging file path
------------------------------
+ .. config:option:: file :: Logging file path
-Specifies the location of file for logging output::
+ Specifies the location of file for logging output::
- [log]
- file = /var/log/couchdb/couch.log
+ [log]
+ file = /var/log/couchdb/couch.log
-This path should be readable and writable for user that runs CouchDB service
-(`couchdb` by default).
+ This path should be readable and writable for user that runs CouchDB service
+ (`couchdb` by default).
-.. _config/log/level:
-``level`` :: Logging verbose level
-----------------------------------
+ .. config:option:: level :: Logging verbose level
-.. versionchanged:: 1.3: Added ``warning`` level.
+ .. versionchanged:: 1.3: Added ``warning`` level.
-Logging level defines how verbose and detailed logging will be::
+ Logging level defines how verbose and detailed logging will be::
- [log]
- level = info
+ [log]
+ level = info
-Available levels:
+ Available levels:
-- ``debug``: Very informative and detailed debug logging. Includes HTTP headers,
- external processes communications, authorization information and more;
-- ``info``: Informative logging. Includes HTTP requests headlines, startup of
- external processes etc.
-- ``warning``: Warning messages are alerts about edge situations that may lead
- to errors. For instance, compaction daemon alerts about low or insufficient
- disk space at this level.
-- ``error``: Error level includes only things that going wrong, crush reports
- and HTTP error responses (5xx codes).
-- ``none``: Disables logging any messages.
+ - ``debug``: Very informative and detailed debug logging. Includes HTTP
+ headers, external processes communications, authorization information and
+ more;
+ - ``info``: Informative logging. Includes HTTP requests headlines, startup
+ of an external processes etc.
+ - ``warning``: Warning messages are alerts about edge situations that may
+ lead to errors. For instance, compaction daemon alerts about low or
+ insufficient disk space at this level.
+ - ``error``: Error level includes only things that going wrong, crush
+ reports and HTTP error responses (5xx codes).
+ - ``none``: Disables logging any messages.
-.. _config/log/include_sasl:
-``include_sasl``
-----------------
+ .. config:option:: include_sasl
-Includes `SASL`_ information in logs::
+ Includes `SASL`_ information in logs::
- [log]
- include_sasl = true
+ [log]
+ include_sasl = true
-.. _SASL: http://www.erlang.org/doc/apps/sasl/
+ .. _SASL: http://www.erlang.org/doc/apps/sasl/
.. _config/log_level_by_module:
-``[log_level_by_module]`` :: Per module logging
-===============================================
+Per module logging
+==================
+
+.. config:section:: log_level_by_module :: Per module logging
-.. versionadded:: 1.3
+ .. versionadded:: 1.3
-In this section you can specify :ref:`log level <config/log/level>` on a
-per-module basis::
+ In this section you can specify :option:`log level <log/level>` on a
+ per-module basis::
- [log_level_by_module]
- couch_httpd = debug
- couch_replicator = info
- couch_query_servers = error
+ [log_level_by_module]
+ couch_httpd = debug
+ couch_replicator = info
+ couch_query_servers = error
-See `src/*/*.erl`_ for available modules.
+ See `src/*/*.erl`_ for available modules.
-.. _src/*/*.erl: https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=tree;f=src;hb=HEAD
+ .. _src/*/*.erl: https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=tree;f=src;hb=HEAD
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/config/misc.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/misc.rst b/share/doc/src/config/misc.rst
index 079f2f4..753d0e2 100644
--- a/share/doc/src/config/misc.rst
+++ b/share/doc/src/config/misc.rst
@@ -10,6 +10,8 @@
.. License for the specific language governing permissions and limitations under
.. the License.
+.. default-domain:: config
+
.. highlight:: ini
========================
@@ -18,204 +20,204 @@ Miscellaneous Parameters
.. _config/attachments:
-``[attachments]`` :: Configuration of Attachment Storage
-========================================================
-
-.. _config/attachments/compression_level:
-
-``compression_level``
----------------------
-
-Defines zlib compression level for the attachments from ``1`` (lowest, fastest)
-to ``9`` (highest, slowest). A value of ``0`` disables compression::
+Configuration of Attachment Storage
+===================================
- [attachments]
- compression_level = 8
+.. config:section:: attachments :: Configuration of Attachment Storage
+ .. config:option:: compression_level
+
+ Defines zlib compression level for the attachments from ``1`` (lowest,
+ fastest) to ``9`` (highest, slowest). A value of ``0`` disables compression
-.. _config/attachments/compressible_types:
+ ::
+
+ [attachments]
+ compression_level = 8
+
-``compressible_types``
-----------------------
-
-Since compression is ineffective for some types of files, it is possible to let
-CouchDB compress only some types of attachments, specified by their MIME type::
-
- [attachments]
- compressible_types = text/*, application/javascript, application/json, application/xml
+ .. config:option:: compressible_types
+
+ Since compression is ineffective for some types of files, it is possible
+ to let CouchDB compress only some types of attachments, specified by their
+ MIME type::
+
+ [attachments]
+ compressible_types = text/*, application/javascript, application/json, application/xml
.. _config/stats:
-``[stats]`` :: Statistic Calculation
-====================================
-
-.. _config/stats/rate:
-
-``rate``
---------
+Statistic Calculation
+=====================
+
+.. config:section:: stats :: Statistic Calculation
+
+
+ .. config:option:: rate
+
+ Rate of statistics gathering in milliseconds::
+
+ [stats]
+ rate = 1000
+
+
+ .. config:option:: samples
+
+ Samples are used to track the mean and standard value deviation within
+ specified intervals (in seconds)::
+
+ [stats]
+ samples = [0, 60, 300, 900]
-Rate of statistics gathering in milliseconds::
- [stats]
- rate = 1000
-
-
-.. _config/stats/samples:
-
-``samples``
------------
-
-Samples are used to track the mean and standard value deviation within specified
-intervals (in seconds)::
-
- [stats]
- samples = [0, 60, 300, 900]
+.. _config/uuids:
+UUIDs Configuration
+===================
+
+.. config:section:: uuids :: UUIDs Configuration
+
+ .. config:option:: algorithm :: Generation Algorithm
+
+ .. versionchanged:: 1.3 Added ``utc_id`` algorithm.
+
+ CouchDB provides various algorithms to generate the UUID values that are
+ used for document `_id`'s by default::
+
+ [uuids]
+ algorithm = sequential
+
+ Available algorithms:
+
+ - ``random``: 128 bits of random awesome. All awesome, all the time:
+
+ .. code-block:: javascript
+
+ {
+ "uuids": [
+ "5fcbbf2cb171b1d5c3bc6df3d4affb32",
+ "9115e0942372a87a977f1caf30b2ac29",
+ "3840b51b0b81b46cab99384d5cd106e3",
+ "b848dbdeb422164babf2705ac18173e1",
+ "b7a8566af7e0fc02404bb676b47c3bf7",
+ "a006879afdcae324d70e925c420c860d",
+ "5f7716ee487cc4083545d4ca02cd45d4",
+ "35fdd1c8346c22ccc43cc45cd632e6d6",
+ "97bbdb4a1c7166682dc026e1ac97a64c",
+ "eb242b506a6ae330bda6969bb2677079"
+ ]
+ }
+
+ - ``sequential``: Monotonically increasing ids with random increments.
+ The first 26 hex characters are random, the last 6 increment in random
+ amounts until an overflow occurs. On overflow, the random prefix is
+ regenerated and the process starts over.
+
+ .. code-block:: javascript
+
+ {
+ "uuids": [
+ "4e17c12963f4bee0e6ec90da54804894",
+ "4e17c12963f4bee0e6ec90da5480512f",
+ "4e17c12963f4bee0e6ec90da54805c25",
+ "4e17c12963f4bee0e6ec90da54806ba1",
+ "4e17c12963f4bee0e6ec90da548072b3",
+ "4e17c12963f4bee0e6ec90da54807609",
+ "4e17c12963f4bee0e6ec90da54807718",
+ "4e17c12963f4bee0e6ec90da54807754",
+ "4e17c12963f4bee0e6ec90da54807e5d",
+ "4e17c12963f4bee0e6ec90da54808d28"
+ ]
+ }
+
+ - ``utc_random``: The time since Jan 1, 1970 UTC, in microseconds. The first
+ 14 characters are the time in hex. The last 18 are random.
+
+ .. code-block:: javascript
+
+ {
+ "uuids": [
+ "04dd32b3af699659b6db9486a9c58c62",
+ "04dd32b3af69bb1c2ac7ebfee0a50d88",
+ "04dd32b3af69d8591b99a8e86a76e0fb",
+ "04dd32b3af69f4a18a76efd89867f4f4",
+ "04dd32b3af6a1f7925001274bbfde952",
+ "04dd32b3af6a3fe8ea9b120ed906a57f",
+ "04dd32b3af6a5b5c518809d3d4b76654",
+ "04dd32b3af6a78f6ab32f1e928593c73",
+ "04dd32b3af6a99916c665d6bbf857475",
+ "04dd32b3af6ab558dd3f2c0afacb7d66"
+ ]
+ }
+
+ - ``utc_id``: The time since Jan 1, 1970 UTC, in microseconds, plus
+ the ``utc_id_suffix`` string. The first 14 characters are the time in hex.
+ The :option:`uuids/utc_id_suffix` string value is appended to these.
+
+ .. code-block:: javascript
+
+ {
+ "uuids": [
+ "04dd32bd5eabcc@mycouch",
+ "04dd32bd5eabee@mycouch",
+ "04dd32bd5eac05@mycouch",
+ "04dd32bd5eac28@mycouch",
+ "04dd32bd5eac43@mycouch",
+ "04dd32bd5eac58@mycouch",
+ "04dd32bd5eac6e@mycouch",
+ "04dd32bd5eac84@mycouch",
+ "04dd32bd5eac98@mycouch",
+ "04dd32bd5eacad@mycouch"
+ ]
+ }
+
+ .. note::
+
+ **Impact of UUID choices:** the choice of UUID has a significant impact
+ on the layout of the B-tree, prior to compaction.
+
+ For example, using a sequential UUID algorithm while uploading a large
+ batch of documents will avoid the need to rewrite many intermediate
+ B-tree nodes. A random UUID algorithm may require rewriting intermediate
+ nodes on a regular basis, resulting in significantly decreased throughput
+ and wasted disk space space due to the append-only B-tree design.
+
+ It is generally recommended to set your own UUIDs, or use the sequential
+ algorithm unless you have a specific need and take into account
+ the likely need for compaction to re-balance the B-tree and reclaim
+ wasted space.
+
+
+ .. config:option:: utc_id_suffix :: UTC ID Suffix
+
+ .. versionadded:: 1.3
+
+ The ``utc_id_suffix`` value will be appended to UUIDs generated by the
+ ``utc_id`` algorithm. Replicating instances should have unique
+ ``utc_id_suffix`` values to ensure uniqueness of ``utc_id`` ids.
+
+ ::
+
+ [uuid]
+ utc_id_suffix = my-awesome-suffix
-.. _config/uuids:
-.. _config/uuids/algorithm:
-
-``[uuids]`` :: UUID Generation Algorithm
-========================================
-
-.. versionchanged:: 1.3 ``utc_id`` algorithm.
-
-CouchDB provides various algorithms to generate the UUID values that are used
-for document `_id`'s by default::
-
- [uuids]
- algorithm = sequential
-
-Available algorithms:
-
-- ``random``: 128 bits of random awesome. All awesome, all the time:
-
- .. code-block:: javascript
-
- {
- "uuids": [
- "5fcbbf2cb171b1d5c3bc6df3d4affb32",
- "9115e0942372a87a977f1caf30b2ac29",
- "3840b51b0b81b46cab99384d5cd106e3",
- "b848dbdeb422164babf2705ac18173e1",
- "b7a8566af7e0fc02404bb676b47c3bf7",
- "a006879afdcae324d70e925c420c860d",
- "5f7716ee487cc4083545d4ca02cd45d4",
- "35fdd1c8346c22ccc43cc45cd632e6d6",
- "97bbdb4a1c7166682dc026e1ac97a64c",
- "eb242b506a6ae330bda6969bb2677079"
- ]
- }
-
-- ``sequential``: Monotonically increasing ids with random increments.
- The first 26 hex characters are random, the last 6 increment in random
- amounts until an overflow occurs. On overflow, the random prefix is
- regenerated and the process starts over.
-
- .. code-block:: javascript
-
- {
- "uuids": [
- "4e17c12963f4bee0e6ec90da54804894",
- "4e17c12963f4bee0e6ec90da5480512f",
- "4e17c12963f4bee0e6ec90da54805c25",
- "4e17c12963f4bee0e6ec90da54806ba1",
- "4e17c12963f4bee0e6ec90da548072b3",
- "4e17c12963f4bee0e6ec90da54807609",
- "4e17c12963f4bee0e6ec90da54807718",
- "4e17c12963f4bee0e6ec90da54807754",
- "4e17c12963f4bee0e6ec90da54807e5d",
- "4e17c12963f4bee0e6ec90da54808d28"
- ]
- }
-
-- ``utc_random``: The time since Jan 1, 1970 UTC, in microseconds. The first
- 14 characters are the time in hex. The last 18 are random.
-
- .. code-block:: javascript
-
- {
- "uuids": [
- "04dd32b3af699659b6db9486a9c58c62",
- "04dd32b3af69bb1c2ac7ebfee0a50d88",
- "04dd32b3af69d8591b99a8e86a76e0fb",
- "04dd32b3af69f4a18a76efd89867f4f4",
- "04dd32b3af6a1f7925001274bbfde952",
- "04dd32b3af6a3fe8ea9b120ed906a57f",
- "04dd32b3af6a5b5c518809d3d4b76654",
- "04dd32b3af6a78f6ab32f1e928593c73",
- "04dd32b3af6a99916c665d6bbf857475",
- "04dd32b3af6ab558dd3f2c0afacb7d66"
- ]
- }
-
-- ``utc_id``: The time since Jan 1, 1970 UTC, in microseconds, plus
- the ``utc_id_suffix`` string. The first 14 characters are the time in hex.
- The :ref:`config/uuids/utc_id_suffix` string value is appended to these.
-
- .. code-block:: javascript
-
- {
- "uuids": [
- "04dd32bd5eabcc@mycouch",
- "04dd32bd5eabee@mycouch",
- "04dd32bd5eac05@mycouch",
- "04dd32bd5eac28@mycouch",
- "04dd32bd5eac43@mycouch",
- "04dd32bd5eac58@mycouch",
- "04dd32bd5eac6e@mycouch",
- "04dd32bd5eac84@mycouch",
- "04dd32bd5eac98@mycouch",
- "04dd32bd5eacad@mycouch"
- ]
- }
-
-.. note::
-
- **Impact of UUID choices:** the choice of UUID has a significant impact on
- the layout of the B-tree, prior to compaction.
-
- For example, using a sequential UUID algorithm while uploading a large batch
- of documents will avoid the need to rewrite many intermediate B-tree nodes.
- A random UUID algorithm may require rewriting intermediate nodes on a regular
- basis, resulting in significantly decreased throughput and wasted disk space
- space due to the append-only B-tree design.
-
- It is generally recommended to set your own UUIDs, or use the sequential
- algorithm unless you have a specific need and take into account the likely
- need for compaction to re-balance the B-tree and reclaim wasted space.
-
-
-.. _config/uuids/utc_id_suffix:
-
-UTC ID Suffix
--------------
-
-.. versionadded:: 1.3
-
-The ``utc_id_suffix`` value will be appended to UUIDs generated by the
-``utc_id`` algorithm. Replicating instances should have unique
-``utc_id_suffix`` values to ensure uniqueness of ``utc_id`` ids.
-
-::
-
- [uuid]
- utc_id_suffix = my-awesome-suffix
.. _config/vendor:
-``[vendor]`` :: Vendor information
-==================================
+Vendor information
+==================
+
+.. config:section:: vendor :: Vendor information
-.. versionadded:: 1.3
+ .. versionadded:: 1.3
-CouchDB distributors have the option of customizing CouchDB's welcome
-message. This is returned when requesting ``GET /``.
+ CouchDB distributors have the option of customizing CouchDB's welcome
+ message. This is returned when requesting ``GET /``.
-::
+ ::
- [vendor]
- name = The Apache Software Foundation
- version = 1.5.0
+ [vendor]
+ name = The Apache Software Foundation
+ version = 1.5.0
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/config/query-servers.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/query-servers.rst b/share/doc/src/config/query-servers.rst
index 0dbe5c8..36092bf 100644
--- a/share/doc/src/config/query-servers.rst
+++ b/share/doc/src/config/query-servers.rst
@@ -18,147 +18,144 @@ Query Servers
.. _config/query_servers:
-``[query_servers]`` :: Query Servers Definition
-===============================================
+Query Servers Definition
+========================
-.. versionchanged:: 1.2: Added CoffeeScript query server
+.. config:section:: query_servers :: Query Servers Definition
-CouchDB delegates computation of :ref:`design documents <ddocs>` functions to
-external query servers. The external query server is a special OS process which
-communicates with CouchDB over standard input/output using a very simple
-line-based protocol with JSON messages.
+ .. versionchanged:: 1.2: Added CoffeeScript query server
-The external query server may be defined in configuration file following next
-pattern::
+ CouchDB delegates computation of :ref:`design documents <ddocs>` functions to
+ external query servers. The external query server is a special OS process which
+ communicates with CouchDB over standard input/output using a very simple
+ line-based protocol with JSON messages.
- [query_servers]
- LANGUAGE = PATH ARGS
+ The external query server may be defined in configuration file following next
+ pattern::
-Where:
+ [query_servers]
+ LANGUAGE = PATH ARGS
-- ``LANGUAGE``: is a programming language which code this query server may
- execute. For instance, there are `python`, `ruby`, `clojure` and other query
- servers in wild. This value is also used for `ddoc` field ``language``
- to determine query server that will process his functions.
+ Where:
- Note, that you may setup multiple query servers for the same programming
- language, but you have to name them different (like `python-dev` etc.).
+ - ``LANGUAGE``: is a programming language which code this query server may
+ execute. For instance, there are `python`, `ruby`, `clojure` and other query
+ servers in wild. This value is also used for `ddoc` field ``language``
+ to determine query server that will process his functions.
-- ``PATH``: is a system path to the executable binary program that runs the
- query server.
+ Note, that you may setup multiple query servers for the same programming
+ language, but you have to name them different (like `python-dev` etc.).
-- ``ARGS``: optionally, you may specify additional command line arguments for
- the executable ``PATH``.
+ - ``PATH``: is a system path to the executable binary program that runs the
+ query server.
-The default query server is written in :ref:`JavaScript <query-server/js>`,
-running via `Mozilla SpiderMonkey`_::
+ - ``ARGS``: optionally, you may specify additional command line arguments for
+ the executable ``PATH``.
- [query_servers]
- javascript = /usr/bin/couchjs /usr/share/couchdb/server/main.js
- coffeescript = /usr/bin/couchjs /usr/share/couchdb/server/main-coffee.js
+ The default query server is written in :ref:`JavaScript <query-server/js>`,
+ running via `Mozilla SpiderMonkey`_::
+ [query_servers]
+ javascript = /usr/bin/couchjs /usr/share/couchdb/server/main.js
+ coffeescript = /usr/bin/couchjs /usr/share/couchdb/server/main-coffee.js
-.. _Mozilla SpiderMonkey: https://developer.mozilla.org/en/docs/SpiderMonkey
-.. seealso::
- :ref:`Native Erlang Query Server <config/native_query_servers>` that allows
- to process Erlang `ddocs` and runs within CouchDB bypassing stdio
- communication and JSON serialization/deserialization round trip overhead.
+ .. _Mozilla SpiderMonkey: https://developer.mozilla.org/en/docs/SpiderMonkey
+ .. seealso::
+ :ref:`Native Erlang Query Server <config/native_query_servers>` that allows
+ to process Erlang `ddocs` and runs within CouchDB bypassing stdio
+ communication and JSON serialization/deserialization round trip overhead.
-.. _config/query_server_config:
-
-``[query_server_config]`` :: Query Servers Configuration
-========================================================
+.. _config/query_server_config:
-.. _config/query_server_config/commit_freq:
+Query Servers Configuration
+===========================
-``commit_freq`` :: View index commit delay
-------------------------------------------
+.. config:section:: query_server_config :: Query Servers Configuration
-Specifies the delay in seconds before view index changes are committed to disk.
-The default value is ``5``::
- [query_server_config]
- commit_freq = 5
+ .. config:option:: commit_freq :: View index commit delay
+ Specifies the delay in seconds before view index changes are committed to disk.
+ The default value is ``5``::
-.. _config/query_server_config/os_process_limit:
+ [query_server_config]
+ commit_freq = 5
-``os_process_limit`` :: Query Server operation timeout
-------------------------------------------------------
-Amount of time in seconds that the Query Server may process CouchDB command::
+ .. config:option:: os_process_limit :: Query Server operation timeout
- [query_server_config]
- os_process_limit = 10
+ Amount of time in seconds that the Query Server may process CouchDB command::
-CouchDB will raise `os_process_timeout` error and kill the process in case the
-Query Server doesn't return any result within this limit.
+ [query_server_config]
+ os_process_limit = 10
+ CouchDB will raise `os_process_timeout` error and kill the process in case the
+ Query Server doesn't return any result within this limit.
-.. _config/query_server_config/reduce_limit:
-``reduce_limit`` :: Reduce limit control
-----------------------------------------
+ .. config:option:: reduce_limit :: Reduce limit control
-Controls `Reduce overflow` error that raises when output of
-:ref:`reduce functions <reducefun>` is too big::
+ Controls `Reduce overflow` error that raises when output of
+ :ref:`reduce functions <reducefun>` is too big::
- [query_server_config]
- reduce_limit = true
+ [query_server_config]
+ reduce_limit = true
-Normally, you don't have to disable (by setting ``false`` value) this option
-since main propose of `reduce` functions is to *reduce* the input.
+ Normally, you don't have to disable (by setting ``false`` value) this option
+ since main propose of `reduce` functions is to *reduce* the input.
.. _config/native_query_servers:
-``[native_query_servers]`` :: Native Erlang Query Server
-========================================================
+Native Erlang Query Server
+==========================
+
+.. config:section:: native_query_servers :: Native Erlang Query Server
-.. warning::
+ .. warning::
- Due to security restrictions, the Erlang query server is disabled by
- default.
+ Due to security restrictions, the Erlang query server is disabled by
+ default.
- Unlike the JavaScript query server, the Erlang one does not runs in a sandbox
- mode. This means that Erlang code has full access to your OS,
- filesystem and network, which may lead to security issues. While Erlang
- functions are faster than JavaScript ones, you need to be careful
- about running them, especially if they were written by someone else.
+ Unlike the JavaScript query server, the Erlang one does not runs in a sandbox
+ mode. This means that Erlang code has full access to your OS,
+ filesystem and network, which may lead to security issues. While Erlang
+ functions are faster than JavaScript ones, you need to be careful
+ about running them, especially if they were written by someone else.
-CouchDB has a native Erlang query server, allowing you to write your map/reduce
-functions in Erlang.
+ CouchDB has a native Erlang query server, allowing you to write your map/reduce
+ functions in Erlang.
-First, you'll need to edit your `local.ini` to include a
-``[native_query_servers]`` section::
+ First, you'll need to edit your `local.ini` to include a
+ ``[native_query_servers]`` section::
- [native_query_servers]
- erlang = {couch_native_process, start_link, []}
+ [native_query_servers]
+ erlang = {couch_native_process, start_link, []}
-To see these changes you will also need to restart the server.
-To test out using :ref:`Erlang views <query-server/erlang>`, visit the
-`Futon` admin interface, create a new database and open a temporary view.
-You should now be able to select ``erlang`` from the language drop-down.
+ To see these changes you will also need to restart the server.
+ To test out using :ref:`Erlang views <query-server/erlang>`, visit the
+ `Futon` admin interface, create a new database and open a temporary view.
+ You should now be able to select ``erlang`` from the language drop-down.
-Let's try an example of map/reduce functions which count the total documents at
-each number of revisions (there are x many documents at version "1", and y
-documents at "2"... etc). Add a few documents to the database, then enter the
-following functions as a temporary view:
+ Let's try an example of map/reduce functions which count the total documents at
+ each number of revisions (there are x many documents at version "1", and y
+ documents at "2"... etc). Add a few documents to the database, then enter the
+ following functions as a temporary view:
-.. code-block:: erlang
+ .. code-block:: erlang
- %% Map Function
- fun({Doc}) ->
- <<K,_/binary>> = proplists:get_value(<<"_rev">>, Doc, null),
- V = proplists:get_value(<<"_id">>, Doc, null),
- Emit(<<K>>, V)
- end.
+ %% Map Function
+ fun({Doc}) ->
+ <<K,_/binary>> = proplists:get_value(<<"_rev">>, Doc, null),
+ V = proplists:get_value(<<"_id">>, Doc, null),
+ Emit(<<K>>, V)
+ end.
- %% Reduce Function
- fun(Keys, Values, ReReduce) -> length(Values) end.
+ %% Reduce Function
+ fun(Keys, Values, ReReduce) -> length(Values) end.
-If all has gone well, after running the view you should see a list of the total
-number of documents at each revision number.
+ If all has gone well, after running the view you should see a list of the total
+ number of documents at each revision number.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/config/replicator.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/replicator.rst b/share/doc/src/config/replicator.rst
index bac4d49..45451c1 100644
--- a/share/doc/src/config/replicator.rst
+++ b/share/doc/src/config/replicator.rst
@@ -18,176 +18,150 @@ Replicator
.. _config/replicator:
-``[replicator]`` :: Replicator Database Configuration
-=====================================================
+Replicator Database Configuration
+=================================
-.. versionadded:: 1.2
+.. config:section:: replicator :: Replicator Database Configuration
-.. _config/replicator/db:
+ .. versionadded:: 1.2
-``db``
-------
-Specifies replicator database name::
+ .. config:option:: db
- [replicator]
- db = _replicator
+ Specifies replicator database name::
+ [replicator]
+ db = _replicator
-.. _config/replicator/max_replication_retry_count:
-``max_replication_retry_count``
--------------------------------
-Maximum replication retry count can be a non-negative integer or "infinity"::
+ .. config:option:: max_replication_retry_count
- [replicator]
- max_replication_retry_count = 10
+ Maximum replication retry count can be a non-negative integer or "infinity"
+ ::
+ [replicator]
+ max_replication_retry_count = 10
-.. _config/replicator/worker_batch_size:
-``worker_batch_size``
----------------------
-With lower batch sizes checkpoints are done more frequently. Lower batch sizes
-also reduce the total amount of used RAM memory::
+ .. config:option:: worker_batch_size
- [replicator]
- worker_batch_size = 500
+ With lower batch sizes checkpoints are done more frequently. Lower batch
+ sizes also reduce the total amount of used RAM memory::
+ [replicator]
+ worker_batch_size = 500
-.. _config/replicator/worker_processes:
-``worker_processes``
---------------------
-More worker processes can give higher network throughput but can also imply more
-disk and network IO::
+ .. config:option:: worker_processes
- [replicator]
- worker_processes = 4
+ More worker processes can give higher network throughput but can also imply
+ more disk and network IO::
+ [replicator]
+ worker_processes = 4
-.. _config/replicator/http_connections:
-``http_connections``
---------------------
-Maximum number of HTTP connections per replication::
+ .. config:option:: http_connections
- [replicator]
- http_connections = 20
+ Maximum number of HTTP connections per replication::
+ [replicator]
+ http_connections = 20
-.. _config/replicator/connection_timeout:
-``connection_timeout``
-----------------------
-HTTP connection timeout per replication.
-Even for very fast/reliable networks it might need to be increased if a remote
-database is too busy::
+ .. config:option:: connection_timeout
- [replicator]
- connection_timeout = 30000
+ HTTP connection timeout per replication.
+ Even for very fast/reliable networks it might need to be increased if
+ a remote database is too busy::
+ [replicator]
+ connection_timeout = 30000
-.. _config/replicator/retries_per_request:
-``retries_per_request``
------------------------
-If a request fails, the replicator will retry it up to N times::
+ .. config:option:: retries_per_request
- [replicator]
- retries_per_request = 10
+ If a request fails, the replicator will retry it up to N times::
+ [replicator]
+ retries_per_request = 10
-.. _config/replicator/socket_options:
-``socket_options``
-------------------
-Some socket options that might boost performance in some scenarios:
+ .. config:option:: socket_options
-- ``{nodelay, boolean()}``
-- ``{sndbuf, integer()}``
-- ``{recbuf, integer()}``
-- ``{priority, integer()}``
+ Some socket options that might boost performance in some scenarios:
-See the `inet`_ Erlang module's man page for the full list of options::
+ - ``{nodelay, boolean()}``
+ - ``{sndbuf, integer()}``
+ - ``{recbuf, integer()}``
+ - ``{priority, integer()}``
- [replicator]
- socket_options = [{keepalive, true}, {nodelay, false}]
+ See the `inet`_ Erlang module's man page for the full list of options::
-.. _inet: http://www.erlang.org/doc/man/inet.html#setopts-2
+ [replicator]
+ socket_options = [{keepalive, true}, {nodelay, false}]
+ .. _inet: http://www.erlang.org/doc/man/inet.html#setopts-2
-.. _config/replicator/cert_file:
-``cert_file``
--------------
-Path to a file containing the user's certificate::
+ .. config:option:: cert_file
- [replicator]
- cert_file = /full/path/to/server_cert.pem
+ Path to a file containing the user's certificate::
+ [replicator]
+ cert_file = /full/path/to/server_cert.pem
-.. _config/replicator/key_file:
-``key_file``
-------------
-Path to file containing user's private PEM encoded key::
+ .. config:option:: key_file
- [replicator]
- key_file = /full/path/to/server_key.pem
+ Path to file containing user's private PEM encoded key::
+ [replicator]
+ key_file = /full/path/to/server_key.pem
-.. _config/replicator/password:
-``password``
-------------
-String containing the user's password. Only used if the private keyfile is
-password protected::
+ .. config:option:: password
- [replicator]
- password = somepassword
+ String containing the user's password. Only used if the private keyfile is
+ password protected::
+ [replicator]
+ password = somepassword
-.. _config/replicator/verify_ssl_certificates:
-``verify_ssl_certificates``
----------------------------
-Set to true to validate peer certificates::
+ .. config:option:: verify_ssl_certificates
- [replicator]
- verify_ssl_certificates = false
+ Set to true to validate peer certificates::
+ [replicator]
+ verify_ssl_certificates = false
-.. _config/replicator/ssl_trusted_certificates_file:
-``ssl_trusted_certificates_file``
----------------------------------
-File containing a list of peer trusted certificates (in the PEM format)::
+ .. config:option:: ssl_trusted_certificates_file
- [replicator]
- ssl_trusted_certificates_file = /etc/ssl/certs/ca-certificates.crt
+ File containing a list of peer trusted certificates (in the PEM format)::
+ [replicator]
+ ssl_trusted_certificates_file = /etc/ssl/certs/ca-certificates.crt
-.. _config/replicator/ssl_certificate_max_depth:
-``ssl_certificate_max_depth``
------------------------------
-Maximum peer certificate depth (must be set even if certificate validation is
-off)::
+ .. config:option:: ssl_certificate_max_depth
- [replicator]
- ssl_certificate_max_depth = 3
+ Maximum peer certificate depth (must be set even if certificate validation
+ is off)::
+ [replicator]
+ ssl_certificate_max_depth = 3
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/config/services.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/services.rst b/share/doc/src/config/services.rst
index 23d4841..9e06e03 100644
--- a/share/doc/src/config/services.rst
+++ b/share/doc/src/config/services.rst
@@ -16,160 +16,135 @@
CouchDB Internal Services
=========================
-.. _config/daemons:
-``[daemons]`` :: CouchDB Daemonized Mini Apps
-=============================================
+.. _config/daemons:
-.. todo:: Add more detailed apps description and guide how to add custom ones.
+CouchDB Daemonized Mini Apps
+============================
-.. _config/daemons/auth_cache:
+.. config:section:: daemons :: CouchDB Daemonized Mini Apps
-``auth_cache``
---------------
-This daemon provides authentication caching to avoid repeated opening and
-closing of the `_users` database for each request requiring authentication::
+ .. config:option:: auth_cache
- [daemons]
- auth_cache={couch_auth_cache, start_link, []}
+ This daemon provides authentication caching to avoid repeated opening and
+ closing of the `_users` database for each request requiring authentication::
+ [daemons]
+ auth_cache={couch_auth_cache, start_link, []}
-.. _config/daemons/compaction_daemon:
-``compaction_daemon``
----------------------
-:ref:`Automatic compaction <config/compactions>` daemon::
+ .. config:option:: compaction_daemon
- [daemons]
- compaction_daemon={couch_compaction_daemon, start_link, []}
+ :ref:`Automatic compaction <config/compactions>` daemon::
+ [daemons]
+ compaction_daemon={couch_compaction_daemon, start_link, []}
-.. _config/daemons/external_manager:
-``external_manager``
---------------------
-`External` processes manager::
+ .. config:option:: external_manager
- [daemons]
- external_manager={couch_external_manager, start_link, []}
+ `External` processes manager::
+ [daemons]
+ external_manager={couch_external_manager, start_link, []}
-.. _config/daemons/httpd:
-``httpd``
----------
+ .. config:option:: httpd
-HTTP server daemon::
+ HTTP server daemon::
- [daemons]
- httpd={couch_httpd, start_link, []}
+ [daemons]
+ httpd={couch_httpd, start_link, []}
-.. _config/daemons/httpsd:
-``httpsd``
-----------
+ .. config:option:: httpsd
-Provides :ref:`SSL support <config/ssl>`. The default ssl port CouchDB listens
-on is 6984::
+ Provides :ref:`SSL support <config/ssl>`. The default ssl port CouchDB
+ listens on is `6984`::
- [daemons]
- httpsd = {couch_httpd, start_link, [https]}
+ [daemons]
+ httpsd = {couch_httpd, start_link, [https]}
-.. _config/daemons/index_server:
-``index_server``
-----------------
+ .. config:option:: index_server
-The `couch_index` application is responsible for managing all of the
-different types of indexers. This manages the process handling for
-keeping track of the index state as well as managing the updater and
-compactor handling::
+ The `couch_index` application is responsible for managing all of the
+ different types of indexers. This manages the process handling for
+ keeping track of the index state as well as managing the updater and
+ compactor handling::
- [daemons]
- index_server={couch_index_server, start_link, []}
+ [daemons]
+ index_server={couch_index_server, start_link, []}
-.. _config/daemons/os_daemons:
-``os_daemons``
---------------
+ .. config:option:: os_daemons
-:ref:`OS Daemons <config/os_daemons>` manager::
+ :ref:`OS Daemons <config/os_daemons>` manager::
- [daemons]
- os_daemons={couch_os_daemons, start_link, []}
+ [daemons]
+ os_daemons={couch_os_daemons, start_link, []}
-.. _config/daemons/query_servers:
-``query_servers``
------------------
+ .. config:option:: query_servers
-:ref:`Query servers <config/query_servers>` manager::
+ :ref:`Query servers <config/query_servers>` manager::
- [daemons]
- query_servers={couch_query_servers, start_link, []}
+ [daemons]
+ query_servers={couch_query_servers, start_link, []}
-.. _config/daemons/replicator_manager:
-``replicator_manager``
-----------------------
+ .. config:option:: replicator_manager
-Replications manager::
+ Replications manager::
- [daemons]
- replicator_manager={couch_replicator_manager, start_link, []}
+ [daemons]
+ replicator_manager={couch_replicator_manager, start_link, []}
-.. _config/daemons/aggregator:
-``stats_aggregator``
---------------------
+ .. config:option:: stats_aggregator
-Runtime statistics aggregator::
+ Runtime statistics aggregator::
- [daemons]
- stats_aggregator={couch_stats_aggregator, start, []}
+ [daemons]
+ stats_aggregator={couch_stats_aggregator, start, []}
-.. _config/daemons/stats_collector:
-``stats_collector``
--------------------
+ .. config:option:: stats_collector
-Runtime statistics collector::
+ Runtime statistics collector::
- [daemons]
- stats_collector={couch_stats_collector, start, []}
+ [daemons]
+ stats_collector={couch_stats_collector, start, []}
-.. _config/daemons/uuids:
-``uuids``
----------
+ .. config:option:: uuids
-:ref:`UUIDs <config/uuids>` generator daemon::
+ :ref:`UUIDs <config/uuids>` generator daemon::
- [daemons]
- uuids={couch_uuids, start, []}
+ [daemons]
+ uuids={couch_uuids, start, []}
-.. _config/daemons/vhosts:
-``vhosts``
-----------
+ .. config:option:: vhosts
-:ref:`Virtual hosts <config/vhosts>` manager. Provides dynamic add of vhosts
-without restart, wildcards support and dynamic routing via pattern matching::
+ :ref:`Virtual hosts <config/vhosts>` manager. Provides dynamic add of vhosts
+ without restart, wildcards support and dynamic routing via pattern matching
+ ::
- [daemons]
- vhosts={couch_httpd_vhost, start_link, []}
+ [daemons]
+ vhosts={couch_httpd_vhost, start_link, []}
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/cve/2012-5641.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/cve/2012-5641.rst b/share/doc/src/cve/2012-5641.rst
index 7400b2f..04a0af9 100644
--- a/share/doc/src/cve/2012-5641.rst
+++ b/share/doc/src/cve/2012-5641.rst
@@ -54,8 +54,8 @@ Work-Around
Users may simply exclude any file-based web serving components directly
within their configuration file, typically in `local.ini`. On a default
CouchDB installation, this requires amending the
-:ref:`config/httpd_global_handlers/favicon.ico` and
-:ref:`config/httpd_global_handlers/_utils` lines within
+:config:option:`httpd_global_handlers/favicon.ico` and
+:config::`config/httpd_global_handlers/_utils` lines within
``[httpd_global_handlers]``::
[httpd_global_handlers]
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/externals.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/externals.rst b/share/doc/src/externals.rst
index 9068e75..b6d3bea 100644
--- a/share/doc/src/externals.rst
+++ b/share/doc/src/externals.rst
@@ -103,7 +103,8 @@ one instance of it is alive. If you have something where you want multiple
processes, you need to either tell CouchDB about each one, or have a main
process that forks off the required sub-processes.
-To configure an :ref:`OS daemon <config/os_daemons>`, add this to your local.ini::
+To configure an :config:section:`OS daemon <os_daemons>`, add this to your
+`local.ini`::
[os_daemons]
my_daemon = /path/to/command -with args
@@ -114,8 +115,9 @@ Configuration API
As an added benefit, because stdio is now free, I implemented a simple API
that OS daemons can use to read the configuration of their CouchDB host. This
way you can have them store their configuration inside CouchDB's config system
-if you desire. Or they can peek at things like the :ref:`bind_address
-<config/httpd/bind_address>` and port that CouchDB is using.
+if you desire. Or they can peek at things like the
+:config:option:`httpd/bind_address` and :config:option:`httpd/port` that CouchDB
+is using.
A request for a config section looks like this::
@@ -149,13 +151,13 @@ Dynamic Daemons
+++++++++++++++
The OS daemons react in real time to changes to the configuration system. If
-you set or delete keys in the :ref:`os_daemons <config/os_daemons>` section,
+you set or delete keys in the :config:section:`os_daemons` section,
the corresponding daemons will be started or killed as appropriate.
Neat. But So What?
------------------
-It was suggested that a good first demo would be a `Node.js`_ handler. So, I
+It was suggested that a good first demo would be a `Node.js`_ handler. So, I
present to you a "Hello, World" Node.js handler. Also, remember that this
currently relies on code in my fork on `GitHub`_.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/intro/security.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro/security.rst b/share/doc/src/intro/security.rst
index 1c25159..76d5cb2 100644
--- a/share/doc/src/intro/security.rst
+++ b/share/doc/src/intro/security.rst
@@ -137,13 +137,13 @@ any changes back to the `.ini` files.
The `.ini` files can also be edited by hand when CouchDB is not running.
Instead of creating the admin user as we showed previously, you could have
stopped CouchDB, opened your `local.ini`, added ``anna = secret`` to the
-:ref:`[admins] section <config/admins>`, and restarted CouchDB. Upon reading
-the new line from local.ini, CouchDB would run the hashing algorithm and write
-back the hash to `local.ini`, replacing the plain-text password. To make sure
-CouchDB only hashes plain-text passwords and not an existing hash a second time,
-it prefixes the hash with ``-hashed-``, to distinguish between plain-text
-passwords and hashed passwords. This means your plain-text password can't start
-with the characters ``-hashed-``, but that's pretty unlikely to begin with.
+:config:section:`admins`, and restarted CouchDB. Upon reading the new line from
+`local.ini`, CouchDB would run the hashing algorithm and write back the hash to
+`local.ini`, replacing the plain-text password. To make sure CouchDB only hashes
+plain-text passwords and not an existing hash a second time, it prefixes
+the hash with ``-hashed-``, to distinguish between plain-text passwords and
+hashed passwords. This means your plain-text password can't start with the
+characters ``-hashed-``, but that's pretty unlikely to begin with.
.. note::
@@ -485,8 +485,8 @@ Users Public Information
Sometimes users *wants* to share some information with the World. For instance,
their contact email to let other users get in touch with him. To solve this
problem, but still keep sensitive and private information secured there is
-special :ref:`configuration <config>` option :ref:`public_fields
-<config/couch_httpd_auth/public_fields>`. In this options you may define comma
+special :ref:`configuration <config>` option :config:option:`public_fields
+<couch_httpd_auth/public_fields>`. In this options you may define comma
separated list of users document fields that will be publicity available.
Normally, if you request any user's document and you're not administrator or
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/maintenance/compaction.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/maintenance/compaction.rst b/share/doc/src/maintenance/compaction.rst
index 3e3ddfc..dd99ec2 100644
--- a/share/doc/src/maintenance/compaction.rst
+++ b/share/doc/src/maintenance/compaction.rst
@@ -187,7 +187,7 @@ automatic compaction, so that compaction of databases and views is automatically
triggered based on various criteria. Automatic compaction is configured in
CouchDB's :ref:`configuration files <config/intro>`.
-The :ref:`compaction daemon <config/daemons/compaction_daemon>` is responsible
-for triggering the compaction. It is automatically started, but disabled by
-default. The criteria for triggering the compactions is configured in the
-:ref:`compactions <config/compactions>` section.
+The :config:option:`daemons/compaction_daemon` is responsible for triggering
+the compaction. It is automatically started, but disabled by default.
+The criteria for triggering the compactions is configured in the
+:config:section:`compactions` section.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/maintenance/performance.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/maintenance/performance.rst b/share/doc/src/maintenance/performance.rst
index 9495cb1..b4f9d59 100644
--- a/share/doc/src/maintenance/performance.rst
+++ b/share/doc/src/maintenance/performance.rst
@@ -78,7 +78,7 @@ CouchDB Configuration Options
delayed_commits
^^^^^^^^^^^^^^^
-The :ref:`delayed commits <config/couchdb/delayed_commits>` allows it to
+The :config:option:`delayed commits <couchdb/delayed_commits>` allows 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
@@ -89,7 +89,7 @@ max_dbs_open
^^^^^^^^^^^^
In your :ref:`configuration <config>` (local.ini or similar) familiarize
-yourself with the :ref:`max_dbs_open <config/couchdb/max_dbs_open>`:
+yourself with the :config:option:`couchdb/max_dbs_open`:
.. code-block:: ini
@@ -174,8 +174,8 @@ sent to the TCP socket, like the reply to a document write request (or reading
a very small document), will not be sent immediately to the network - TCP will
buffer it for a while hoping that it will be asked to send more data through
the same socket and then send all the data at once for increased performance.
-This TCP buffering behaviour can be disabled via :ref:`socket_options
-<config/httpd/socket_options>`:
+This TCP buffering behaviour can be disabled via
+:config:option:`httpd/socket_options`:
.. code-block:: ini
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/query-server/protocol.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/query-server/protocol.rst b/share/doc/src/query-server/protocol.rst
index b7d8718..c34a35c 100644
--- a/share/doc/src/query-server/protocol.rst
+++ b/share/doc/src/query-server/protocol.rst
@@ -964,4 +964,4 @@ CouchDB responds nothing, but writes received message into log file::
[Sun, 13 Feb 2009 23:31:30 GMT] [info] [<0.72.0>] Query Server Log Message: some message
-These messages are only logged at :ref:`info level <config/log/level>`.
+These messages are only logged at :config:option:`info level <log/level>`.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/whatsnew/0.11.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/whatsnew/0.11.rst b/share/doc/src/whatsnew/0.11.rst
index 4e184c6..e4b5a76 100644
--- a/share/doc/src/whatsnew/0.11.rst
+++ b/share/doc/src/whatsnew/0.11.rst
@@ -95,8 +95,8 @@ WWW-Authenticate
The default configuration has been changed to avoid causing basic-auth popups
which result from sending the WWW-Authenticate header. To enable basic-auth
-popups, uncomment the :ref:`WWW-Authenticate <config/httpd/WWW-Authenticate>`
-line in `local.ini`.
+popups, uncomment the :config:option:`httpd/WWW-Authenticate` line in
+`local.ini`.
Query server line protocol
^^^^^^^^^^^^^^^^^^^^^^^^^^
[3/3] git commit: updated refs/heads/master to 6f31ffd
Posted by kx...@apache.org.
Add configuration domain.
:config:section:`httpd` to point on specific section.
:config:option:`httpd/port` to point on specific option.
You have to use section-option pair for that due to clash of option
names (ssl and replicator for example).
As bonus provides complete configuration reference by section names.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/6f31ffd9
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/6f31ffd9
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/6f31ffd9
Branch: refs/heads/master
Commit: 6f31ffd97c443e3d7712eaaa7b06353600f4eb95
Parents: b144050
Author: Alexander Shorin <kx...@apache.org>
Authored: Tue Oct 1 13:38:45 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Tue Oct 1 13:38:45 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 2 +
share/doc/ext/configdomain.py | 127 +++++
share/doc/src/api/database/bulk-api.rst | 2 +-
share/doc/src/api/database/changes.rst | 2 +-
share/doc/src/api/database/common.rst | 2 +-
share/doc/src/api/ddoc/common.rst | 2 +-
share/doc/src/api/document/attachments.rst | 14 +-
share/doc/src/api/document/common.rst | 10 +-
share/doc/src/api/server/authn.rst | 21 +-
share/doc/src/api/server/common.rst | 4 +-
share/doc/src/conf.py | 3 +-
share/doc/src/config/auth.rst | 469 +++++++--------
share/doc/src/config/compaction.rst | 199 ++++---
share/doc/src/config/couchdb.rst | 253 ++++-----
share/doc/src/config/externals.rst | 190 +++----
share/doc/src/config/http-handlers.rst | 310 +++++-----
share/doc/src/config/http.rst | 725 +++++++++++-------------
share/doc/src/config/intro.rst | 20 +-
share/doc/src/config/logging.rst | 94 +--
share/doc/src/config/misc.rst | 364 ++++++------
share/doc/src/config/query-servers.rst | 187 +++---
share/doc/src/config/replicator.rst | 172 +++---
share/doc/src/config/services.rst | 151 ++---
share/doc/src/cve/2012-5641.rst | 4 +-
share/doc/src/externals.rst | 12 +-
share/doc/src/intro/security.rst | 18 +-
share/doc/src/maintenance/compaction.rst | 8 +-
share/doc/src/maintenance/performance.rst | 8 +-
share/doc/src/query-server/protocol.rst | 2 +-
share/doc/src/whatsnew/0.11.rst | 4 +-
share/doc/src/whatsnew/1.4.rst | 2 +-
31 files changed, 1624 insertions(+), 1757 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index ef98bde..fab82a6 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -262,6 +262,7 @@ html_files = \
html/whatsnew/1.5.html \
html/whatsnew/index.html \
html/about.html \
+ html/config-ref.html \
html/contents.html \
html/externals.html \
html/json-structure.html \
@@ -422,6 +423,7 @@ src_files_html = \
../templates/utilities.html
sphinx_extensions = \
+ ../ext/configdomain.py \
../ext/github.py \
../ext/httpdomain.py \
../ext/http-api-descr.json
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/ext/configdomain.py
----------------------------------------------------------------------
diff --git a/share/doc/ext/configdomain.py b/share/doc/ext/configdomain.py
new file mode 100644
index 0000000..a02938b
--- /dev/null
+++ b/share/doc/ext/configdomain.py
@@ -0,0 +1,127 @@
+## 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.
+
+from sphinx import addnodes
+from sphinx.roles import XRefRole
+from sphinx.domains import Domain, ObjType, Index
+from sphinx.directives import ObjectDescription
+from sphinx.util.nodes import make_refnode
+
+
+class ConfigObject(ObjectDescription):
+
+ def handle_signature(self, sig, signode):
+ if '::' in sig:
+ name, descr = map(lambda i: i.strip(), sig.split('::'))
+ else:
+ name, descr = sig.strip(), ''
+
+ signode['name'] = name
+ signode['descr'] = descr
+
+ domain, objtype = self.name.split(':')
+ if objtype == 'section':
+ self.env.temp_data['section'] = signode['name']
+ name = '[%s]' % signode['name']
+
+ signode += addnodes.desc_name(name, name)
+
+ return signode['name']
+
+ def needs_arglist(self):
+ return False
+
+ def add_target_and_index(self, name, sig, signode):
+ section = self.env.temp_data['section']
+ domain, objtype = self.name.split(':')
+ data = self.env.domaindata[domain][objtype]
+ if objtype == 'section':
+ data[name] = (self.env.docname, signode['descr'])
+ signode['ids'].append(signode['name'])
+ elif objtype == 'option':
+ idx = '%s/%s' % (section, signode['name'])
+ data[idx] = (self.env.docname, signode['descr'])
+ signode['ids'].append(idx)
+ else:
+ assert 'unknown object type %r' % objtype
+
+
+class ConfigIndex(Index):
+
+ name = 'ref'
+ localname = 'Configuration Reference'
+ shortname = 'Config Reference'
+
+ def generate(self, docnames=None):
+ content = dict(
+ (name, [(name, 1, info[0], name, '', '', info[1])])
+ for name, info in self.domain.data['section'].items()
+ )
+
+ options = self.domain.data['option']
+ for idx, info in sorted(options.items()):
+ path, descr = info
+ section, name = idx.split('/', 1)
+ content[section].append((
+ name, 2, path,
+ '%s/%s' % (section, name),
+ '', '', descr
+ ))
+
+ return (sorted(content.items()), False)
+
+
+class ConfigDomain(Domain):
+
+ name = 'config'
+ label = 'CONFIG'
+
+ object_types = {
+ 'section': ObjType('section', 'section', 'obj'),
+ 'option': ObjType('option', 'option', 'obj'),
+ }
+
+ directives = {
+ 'section': ConfigObject,
+ 'option': ConfigObject,
+ }
+
+ roles = {
+ 'section': XRefRole(),
+ 'option': XRefRole(),
+ }
+
+ initial_data = {
+ 'section': {},
+ 'option': {}
+ }
+
+ indices = [ConfigIndex]
+
+ def resolve_xref(self, env, fromdocname, builder, typ, target,
+ node, contnode):
+ if typ == 'section':
+ info = self.data[typ][target]
+ title = '[%s]' % target
+ elif typ == 'option':
+ assert '/' in target, 'option without section: %r' % target
+ section, option = target.split('/', 1)
+ info = self.data[typ][target]
+ title = option
+ else:
+ assert 'unknown role %r for target %r' % (typ, target)
+ return make_refnode(builder, fromdocname, info[0], target, contnode,
+ title)
+
+
+def setup(app):
+ app.add_domain(ConfigDomain)
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/api/database/bulk-api.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/bulk-api.rst b/share/doc/src/api/database/bulk-api.rst
index 87233df..1c88fbf 100644
--- a/share/doc/src/api/database/bulk-api.rst
+++ b/share/doc/src/api/database/bulk-api.rst
@@ -210,7 +210,7 @@
- :mimetype:`text/plain`
:<header Content-Type: :mimetype:`application/json`
:<header X-Couch-Full-Commit: Overrides server's
- :ref:`commit policy <config/couchdb/delayed_commits>`. Possible values
+ :config:option:`commit policy <couchdb/delayed_commits>`. Possible values
are: ``false`` and ``true``. *Optional*.
:<json boolean all_or_nothing: Sets the database commit mode to use
`all-or-nothing` semantics. Default is ``false``. *Optional*.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/api/database/changes.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/changes.rst b/share/doc/src/api/database/changes.rst
index f2ad9b7..db6af63 100644
--- a/share/doc/src/api/database/changes.rst
+++ b/share/doc/src/api/database/changes.rst
@@ -70,7 +70,7 @@
before the response is sent, even if there are no results. Only applicable
for :ref:`longpoll <changes/longpoll>` or :ref:`continuous
<changes/continuous>` feeds. Default value is specified by
- :ref:`changes_timeout <config/httpd/changes_timeout>` configuration option.
+ :config:option:`httpd/changes_timeout` configuration option.
Note that ``60000`` value is also the default maximum timeout to prevent
undetected dead connections.
:query string view: Allows to use view functions as filters. Documents
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/api/database/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/common.rst b/share/doc/src/api/database/common.rst
index c374625..4d4d24c 100644
--- a/share/doc/src/api/database/common.rst
+++ b/share/doc/src/api/database/common.rst
@@ -268,7 +268,7 @@
- :mimetype:`text/plain`
:<header Content-Type: :mimetype:`application/json`
:<header X-Couch-Full-Commit: Overrides server's
- :ref:`commit policy <config/couchdb/delayed_commits>`. Possible values
+ :config:option:`commit policy <couchdb/delayed_commits>`. Possible values
are: ``false`` and ``true``. *Optional*.
:query string batch: Stores document in :ref:`batch mode
<api/doc/batch-writes>` Possible values: ``ok``. *Optional*
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/api/ddoc/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/common.rst b/share/doc/src/api/ddoc/common.rst
index 16cfffc..af37e61 100644
--- a/share/doc/src/api/ddoc/common.rst
+++ b/share/doc/src/api/ddoc/common.rst
@@ -46,7 +46,7 @@
Currently it is the next:
* **language** (*string*): Defines :ref:`Query Server <query-server>`
- :ref:`key <config/query_servers>` to process design document functions
+ :config:section:`key <query_servers>` to process design document functions
* **options** (*object*): View's default options
* **filters** (*object*): :ref:`Filter functions <filterfun>` definition
* **lists** (*object*): :ref:`List functions <listfun>` definition
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/api/document/attachments.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/document/attachments.rst b/share/doc/src/api/document/attachments.rst
index c26b561..8514993 100644
--- a/share/doc/src/api/document/attachments.rst
+++ b/share/doc/src/api/document/attachments.rst
@@ -34,8 +34,8 @@
:>header Accept-Ranges: :ref:`Range request aware <api/doc/attachment/range>`.
Used for attachments with :mimetype:`application/octet-stream` content type
:>header Content-Encoding: Used compression codec. Available if attachment's
- ``content_type`` is in :ref:`list of compressiable types
- <config/attachments/compressible_types>`
+ ``content_type`` is in :config:option:`list of compressiable types
+ <attachments/compressible_types>`
:>header Content-Length: Attachment size. If compression codec was used,
this value is about compressed size, not actual
:>header Content-MD5: Base64 encoded MD5 binary digest
@@ -87,8 +87,8 @@
:>header Accept-Ranges: :ref:`Range request aware <api/doc/attachment/range>`.
Used for attachments with :mimetype:`application/octet-stream`
:>header Content-Encoding: Used compression codec. Available if attachment's
- ``content_type`` is in :ref:`list of compressiable types
- <config/attachments/compressible_types>`
+ ``content_type`` is in :config:option:`list of compressiable types
+ <attachments/compressible_types>`
:>header Content-Length: Attachment size. If compression codec is used,
this value is about compressed size, not actual
:>header Content-MD5: Base64 encoded MD5 binary digest
@@ -127,8 +127,8 @@
:>header Accept-Ranges: :ref:`Range request aware <api/doc/attachment/range>`.
Used for attachments with :mimetype:`application/octet-stream`
:>header Content-Encoding: Used compression codec. Available if attachment's
- ``content_type`` is in :ref:`list of compressiable types
- <config/attachments/compressible_types>`
+ ``content_type`` is in :config:option:`list of compressiable types
+ <attachments/compressible_types>`
:>header Content-Length: Attachment size. If compression codec is used,
this value is about compressed size, not actual
:>header Content-MD5: Base64 encoded MD5 binary digest
@@ -197,7 +197,7 @@
- :mimetype:`text/plain`
:<header If-Match: Document revision. Alternative to `rev` query parameter
:<header X-Couch-Full-Commit: Overrides server's
- :ref:`commit policy <config/couchdb/delayed_commits>`. Possible values
+ :config:option:`commit policy <couchdb/delayed_commits>`. Possible values
are: ``false`` and ``true``. *Optional*
:query string rev: Document revision. *Required*
:query string batch: Store changes in :ref:`batch mode
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/api/document/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/document/common.rst b/share/doc/src/api/document/common.rst
index 6687ebc..49ffe42 100644
--- a/share/doc/src/api/document/common.rst
+++ b/share/doc/src/api/document/common.rst
@@ -177,7 +177,7 @@
:<header Content-Type: :mimetype:`application/json`
:<header If-Match: Document's revision. Alternative to `rev` query parameter
:<header X-Couch-Full-Commit: Overrides server's
- :ref:`commit policy <config/couchdb/delayed_commits>`. Possible values
+ :config:option:`commit policy <couchdb/delayed_commits>`. Possible values
are: ``false`` and ``true``. *Optional*
:query string batch: Stores document in :ref:`batch mode
<api/doc/batch-writes>` Possible values: ``ok``. *Optional*
@@ -253,7 +253,7 @@
- :mimetype:`text/plain`
:<header If-Match: Document's revision. Alternative to `rev` query parameter
:<header X-Couch-Full-Commit: Overrides server's
- :ref:`commit policy <config/couchdb/delayed_commits>`. Possible values
+ :config:option:`commit policy <couchdb/delayed_commits>`. Possible values
are: ``false`` and ``true``. *Optional*
:query string rev: Actual document's revision
:query string batch: Stores document in :ref:`batch mode
@@ -325,7 +325,7 @@
:<header If-Match: Source document's revision. Alternative to `rev` query
parameter
:<header X-Couch-Full-Commit: Overrides server's
- :ref:`commit policy <config/couchdb/delayed_commits>`. Possible values
+ :config:option:`commit policy <couchdb/delayed_commits>`. Possible values
are: ``false`` and ``true``. *Optional*
:query string rev: Revision to copy from. *Optional*
:query string batch: Stores document in :ref:`batch mode
@@ -397,8 +397,8 @@ information objects with next structure:
Base64-encoded hash digest
- **encoded_length** (*number*): Compressed attachment size in bytes
Available when query parameter ``att_encoding_info=true`` was specified and
- ``content_type`` is in :ref:`list of compressiable types
- <config/attachments/compressible_types>`
+ ``content_type`` is in :config:option:`list of compressiable types
+ <attachments/compressible_types>`
- **encoding** (*string*): Compression codec. Available when query parameter
``att_encoding_info=true`` was specified
- **length** (*number*): Real attachment size in bytes. Not available if attachment
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/api/server/authn.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/server/authn.rst b/share/doc/src/api/server/authn.rst
index ce08277..a3ac3ea 100644
--- a/share/doc/src/api/server/authn.rst
+++ b/share/doc/src/api/server/authn.rst
@@ -75,13 +75,13 @@ For cookie authentication (:rfc:`2109`) CouchDB generates a token that the
client can use for the next few requests to CouchDB. Tokens are valid until
a timeout. When CouchDB sees a valid token in a subsequent request, it will
authenticate user by this token without requesting the password again. By
-default, cookies are valid for 10 minutes, but it's :ref:`adjustable
-<config/couch_httpd_auth/timeout>`. Also it's possible to make cookies
-:ref:`persistent <config/couch_httpd_auth/allow_persistent_cookies>`
+default, cookies are valid for 10 minutes, but it's :config:option:`adjustable
+<couch_httpd_auth/timeout>`. Also it's possible to make cookies
+:config:option:`persistent <couch_httpd_auth/allow_persistent_cookies>`
To obtain the first token and thus authenticate a user for the first time, the
-`username` and `password` must be sent to the
-:ref:`_session API <api/auth/session>`.
+`username` and `password` must be sent to the :ref:`_session API
+<api/auth/session>`.
.. _api/auth/session:
@@ -271,8 +271,7 @@ Proxy Authentication
.. note::
To use this authentication method make sure that the
``{couch_httpd_auth, proxy_authentication_handler}`` value in added to
- the list of the active
- :ref:`authentication handlers <config/httpd/authentication_handlers>`:
+ the list of the active :config:option:`httpd/authentication_handlers`:
.. code-block:: ini
@@ -288,13 +287,13 @@ This authentication method allows creation of a :ref:`userctx_object` for
remotely authenticated user. By default, the client just need to pass specific
headers to CouchDB with related request:
-- :ref:`X-Auth-CouchDB-UserName <config/couch_httpd_auth/x_auth_username>`:
+- :config:option:`X-Auth-CouchDB-UserName <couch_httpd_auth/x_auth_username>`:
username;
-- :ref:`X-Auth-CouchDB-Roles <config/couch_httpd_auth/x_auth_roles>`:
+- :config:option:`X-Auth-CouchDB-Roles <couch_httpd_auth/x_auth_roles>`:
list of user roles separated by a comma (``,``);
-- :ref:`X-Auth-CouchDB-Token <config/couch_httpd_auth/x_auth_token>`:
+- :config:option:`X-Auth-CouchDB-Token <couch_httpd_auth/x_auth_token>`:
authentication token. Optional, but strongly recommended to
- :ref:`force token be required <config/couch_httpd_auth/proxy_use_secret>`
+ :config:option:`force token be required <couch_httpd_auth/proxy_use_secret>`
to prevent requests from untrusted sources.
**Request**:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/api/server/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/server/common.rst b/share/doc/src/api/server/common.rst
index fda74f5..2c14fee 100644
--- a/share/doc/src/api/server/common.rst
+++ b/share/doc/src/api/server/common.rst
@@ -956,8 +956,8 @@ structure is as follows:
]
}
-The UUID type is determined by the :ref:`UUID algorithm <config/uuids/algorithm>`
-setting in the CouchDB configuration.
+The UUID type is determined by the :config:option:`UUID algorithm
+<uuids/algorithm>` setting in the CouchDB configuration.
The UUID type may be changed at any time through the
:ref:`Configuration API <api/config/section/key>`. For example, the UUID type
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/conf.py
----------------------------------------------------------------------
diff --git a/share/doc/src/conf.py b/share/doc/src/conf.py
index 805f87d..b3f8325 100644
--- a/share/doc/src/conf.py
+++ b/share/doc/src/conf.py
@@ -17,7 +17,8 @@ import sys
sys.path.insert(0, os.path.abspath('../ext'))
-extensions = ["sphinx.ext.todo", "sphinx.ext.extlinks", 'github', 'httpdomain']
+extensions = ["sphinx.ext.todo", "sphinx.ext.extlinks", 'github',
+ 'httpdomain', 'configdomain']
_info = {}
_regex = re.compile('m4_define\(\[(.+)\],\s+\[(.+)\]\)')
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/config/auth.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/auth.rst b/share/doc/src/config/auth.rst
index 85d0dbb..4127288 100644
--- a/share/doc/src/config/auth.rst
+++ b/share/doc/src/config/auth.rst
@@ -10,8 +10,9 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-.. highlight:: ini
+.. default-domain:: config
+.. highlight:: ini
================================
Authentication and Authorization
@@ -19,383 +20,341 @@ Authentication and Authorization
.. _config/admins:
-``[admins]`` :: Server Administrators
-=====================================
+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::
+.. config:section:: admins :: Server Administrators
- [admins]
- ;admin = mysecretpassword
- admin = -hashed-6d3c30241ba0aaa4e16c6ea99224f915687ed8cd,7f4a3e05e0cbc6f48a0035e3508eef90
- architect = -pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000
+ 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::
-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:
+ [admins]
+ ;admin = mysecretpassword
+ admin = -hashed-6d3c30241ba0aaa4e16c6ea99224f915687ed8cd,7f4a3e05e0cbc6f48a0035e3508eef90
+ architect = -pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000
-.. code-block:: http
+ 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:
- GET /_config/admins HTTP/1.1
- Accept: application/json
- Host: localhost:5984
+ .. code-block:: http
-.. code-block:: http
+ 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 (Erlang/OTP)
+ .. code-block:: http
-.. code-block:: json
+ 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)
- {
- "admin": "-hashed-6d3c30241ba0aaa4e16c6ea99224f915687ed8cd,7f4a3e05e0cbc6f48a0035e3508eef90",
- "architect": "-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
- }
+ .. code-block:: json
-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.
+ {
+ "admin": "-hashed-6d3c30241ba0aaa4e16c6ea99224f915687ed8cd,7f4a3e05e0cbc6f48a0035e3508eef90",
+ "architect": "-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
+ }
-.. code-block:: http
+ 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.
- PUT /_config/admins/architect?raw=true HTTP/1.1
- Accept: application/json
- Content-Type: application/json
- Content-Length: 89
- Host: localhost:5984
+ .. code-block:: http
- "-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
+ PUT /_config/admins/architect?raw=true HTTP/1.1
+ Accept: application/json
+ Content-Type: application/json
+ Content-Length: 89
+ Host: localhost:5984
-.. code-block:: http
+ "-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
- 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)
+ .. code-block:: http
- "-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
+ 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)
-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>`_.
+ "-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
-.. versionchanged:: 1.4 `PBKDF2` server-side hashed salted password support
- added, now as a synchronous call for the ``_config/admins`` API.
+ 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:
-``[couch_httpd_auth]`` :: Authentication Configuration
-======================================================
-
-.. _config/couch_httpd_auth/allow_persistent_cookies:
+Authentication Configuration
+============================
-``allow_persistent_cookies`` :: Persistent cookies
---------------------------------------------------
+.. config:section:: couch_httpd_auth :: Authentication Configuration
-Makes cookies persistent if ``true``.
-::
+ .. config:option:: allow_persistent_cookies :: Persistent cookies
- [couch_httpd_auth]
- allow_persistent_cookies = false
+ Makes cookies persistent if ``true``.
+ ::
-.. _config/couch_httpd_auth/auth_cache_size:
+ [couch_httpd_auth]
+ allow_persistent_cookies = false
-``auth_cache_size`` :: Authentication cache
--------------------------------------------
-Number of :ref:`userctx_object` to cache in memory, to reduce disk lookups.
+ .. 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
+ ::
+ [couch_httpd_auth]
+ auth_cache_size = 50
-.. _config/couch_httpd_auth/authentication_db:
-``authentication_db`` :: Users database
----------------------------------------
+ .. config:option:: authentication_db :: Users database
-Specifies the name of the system database for storing CouchDB users.
+ Specifies the name of the system database for storing CouchDB users.
-::
+ ::
- [couch_httpd_auth]
- authentication_db = _users
+ [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.
+ .. 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/couch_httpd_auth/authentication_redirect:
+ .. config:option:: authentication_redirect :: Default redirect for authentication requests
-``authentication_redirect`` :: Default redirect for authentication requests
----------------------------------------------------------------------------
+ Specifies the location for redirection on successful authentication if a
+ ``text/html`` response is accepted by the client (via an ``Accept`` header).
-Specifies the location for redirection on successful authentication if a
-``text/html`` response is accepted by the client (via an ``Accept`` header).
+ ::
-::
+ [couch_httpd_auth]
+ authentication_redirect = /_utils/session.html
- [couch_httpd_auth]
- authentication_redirect = /_utils/session.html
+ .. config:option:: iterations :: PBKDF2 iterations count
-.. _config/couch_httpd_auth/iterations:
+ .. versionadded:: 1.3
-``iterations`` :: 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.3
+ ::
-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]
+ iterations = 10000
-::
- [couch_httpd_auth]
- iterations = 10000
+ .. 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`.
-.. _config/couch_httpd_auth/proxy_use_secret:
+ ::
-``proxy_use_secret`` :: Force proxy auth use secret token
----------------------------------------------------------
+ [couch_httpd_auth]
+ proxy_use_secret = false
-When this option is set to ``true``, the
-:ref:`secret <config/couch_httpd_auth/secret>` option is required for
-:ref:`api/auth/proxy`.
-::
+ .. 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/couch_httpd_auth/public_fields:
+ ::
-``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
-:ref:`authentication_db <config/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
-::
- [couch_httpd_auth]
- public_fields = first_name, last_name, contacts, url
+ .. config:option:: require_valid_user :: Force user authentication
-.. note::
- Using the ``public_fields`` whitelist for user document properties requires
- setting the :ref:`users_db_public <config/couch_httpd_auth/users_db_public>`
- option to ``true`` (the latter option has no other purpose)::
+ When this option is set to ``true``, no requests are allowed from anonymous
+ users. Everyone must be authenticated.
- [couch_httpd_auth]
- users_db_public = true
+ ::
-.. _config/couch_httpd_auth/require_valid_user:
+ [couch_httpd_auth]
+ require_valid_user = false
-``require_valid_user`` :: Force user authentication
----------------------------------------------------
-When this option is set to ``true``, no requests are allowed from anonymous
-users. Everyone must be authenticated.
+ .. config:option:: secret :: Proxy Auth secret token
-::
+ The secret token used for :ref:`api/auth/proxy` method.
- [couch_httpd_auth]
- require_valid_user = false
+ ::
+ [couch_httpd_auth]
+ secret = 92de07df7e7a3fe14808cef90a7cc0d91
-.. _config/couch_httpd_auth/secret:
-``secret`` :: Proxy Auth secret token
--------------------------------------
+ .. config:option:: timeout :: Session timeout
-The secret token used for :ref:`api/auth/proxy` method.
+ Number of seconds since the last request before sessions will be expired.
-::
+ ::
- [couch_httpd_auth]
- secret = 92de07df7e7a3fe14808cef90a7cc0d91
+ [couch_httpd_auth]
+ timeout = 600
-.. _config/couch_httpd_auth/timeout:
+ .. config:option:: users_db_public :: Publish user documents
-``timeout`` :: Session timeout
-------------------------------
+ .. versionadded:: 1.4
-Number of seconds since the last request before sessions will be expired.
+ 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]
- timeout = 600
+ [couch_httpd_auth]
+ users_db_public = false
+ .. config:option:: x_auth_roles :: Proxy Auth roles header
-.. _config/couch_httpd_auth/users_db_public:
+ 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`.
-``users_db_public`` :: Publish user documents
----------------------------------------------
+ ::
-.. versionadded:: 1.4
+ [couch_httpd_auth]
+ x_auth_roles = X-Auth-CouchDB-Roles
-Allow all users to view user documents. By default, only admins may browse
-all users documents, while users may browse only their own document.
-::
+ .. config:option:: x_auth_token :: Proxy Auth token header
- [couch_httpd_auth]
- users_db_public = false
+ 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`.
+ ::
-.. _config/couch_httpd_auth/x_auth_roles:
+ [couch_httpd_auth]
+ x_auth_roles = X-Auth-CouchDB-Token
-``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:: 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_roles = X-Auth-CouchDB-Roles
+ ::
+ [couch_httpd_auth]
+ x_auth_username = X-Auth-CouchDB-UserName
-.. _config/couch_httpd_auth/x_auth_token:
-``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 :ref:`secret key <config/couch_httpd_auth/secret>` and
-:ref:`username <config/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
-:ref:`proxy_use_secret <config/couch_httpd_auth/proxy_use_secret>`
-option is not ``true``. Used for :ref:`api/auth/proxy`.
+.. _config/couch_httpd_oauth:
-::
+HTTP OAuth Configuration
+========================
- [couch_httpd_auth]
- x_auth_roles = X-Auth-CouchDB-Token
+.. config:section:: couch_httpd_oauth :: HTTP OAuth Configuration
+ .. versionadded:: 1.2
-.. _config/couch_httpd_auth/x_auth_username:
+ .. config:option:: use_users_db
-``x_auth_username`` :: Proxy Auth username header
--------------------------------------------------
+ CouchDB is able to store OAuth credentials within user documents instead of
+ config file by using this option::
-The HTTP header name (``X-Auth-CouchDB-UserName`` by default) containing the
-username. Used for :ref:`api/auth/proxy`.
+ [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.
- [couch_httpd_auth]
- x_auth_username = X-Auth-CouchDB-UserName
+ .. 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:
-``[oauth]`` :: OAuth Configuration
-==================================
+OAuth Configuration
+===================
-.. _config/oauth/oauth_consumer_secrets:
-.. _config/oauth/oauth_token_secrets:
-.. _config/oauth/oauth_token_users:
+.. config:section:: oauth_* :: OAuth Configuration
-Store credentials within config
--------------------------------
+ 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:
-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:
-1. The Consumer secret:
+ ::
-::
+ [oauth_consumer_secrets]
+ consumer1 = sekr1t
- [oauth_consumer_secrets]
- consumer1 = sekr1t
+ 2. Token secrets:
-2. Token secrets:
+ ::
-::
+ [oauth_token_secrets]
+ token1 = tokensekr1t
- [oauth_token_secrets]
- token1 = tokensekr1t
+ 3. A mapping from tokens to users:
-3. A mapping from tokens to users:
-
-::
-
- [oauth_token_users]
- token1 = couchdb_username
-
-
-.. _config/couch_httpd_oauth:
-.. _config/couch_httpd_oauth/use_users_db:
-
-Store OAuth credentials within auth database
---------------------------------------------
-
-.. versionadded:: 1.2
-
-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
-:ref:`authentication database <config/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"
- }
- }
- }
+ ::
+ [oauth_token_users]
+ token1 = couchdb_username
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/config/compaction.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/compaction.rst b/share/doc/src/config/compaction.rst
index 0393d8c..5e1e10d 100644
--- a/share/doc/src/config/compaction.rst
+++ b/share/doc/src/config/compaction.rst
@@ -10,172 +10,165 @@
.. License for the specific language governing permissions and limitations under
.. the License.
+.. default-domain:: config
+
.. highlight:: ini
========================
Compaction Configuration
========================
-.. _config/database_compaction:
-
-``[database_compaction]`` :: Database Compaction Options
-========================================================
-
-.. _config/database_compaction/doc_buffer_size:
+.. _conifg/database_compaction:
-``doc_buffer_size`` :: Documents buffer size
---------------------------------------------
+Database Compaction Options
+===========================
-Specifies the copy buffer's maximum size in bytes::
+.. config:section:: database_compaction :: Database Compaction Options
- [database_compaction]
- doc_buffer_size = 524288
+ .. config:option:: doc_buffer_size :: Documents buffer size
+ Specifies the copy buffer's maximum size in bytes::
-.. _config/database_compaction/checkpoint_after:
+ [database_compaction]
+ doc_buffer_size = 524288
-``checkpoint_after`` :: Checkpoint trigger
-------------------------------------------
-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:
-``[compactions]`` :: Compaction Daemon Rules
-============================================
+Compaction Daemon Rules
+=======================
-Automatic compaction rules definition.
-The :ref:`compaction daemon <config/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::
+.. config:section:: compactions :: Compaction Daemon Rules
- [compactions]
- database_name = [ {ParamName, ParamValue}, {ParamName, ParamValue}, ... ]
- _default = [ {ParamName, ParamValue}, {ParamName, ParamValue}, ... ]
+ Automatic compaction rules definition. 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}, ... ]
-For example::
- [compactions]
- _default = [{db_fragmentation, "70%"}, {view_fragmentation, "60%"}, {from, "23:00"}, {to, "04:00"}]
+ For example::
-Possible parameters:
+ [compactions]
+ _default = [{db_fragmentation, "70%"}, {view_fragmentation, "60%"}, {from, "23:00"}, {to, "04:00"}]
-- ``db_fragmentation``: If the ratio of legacy data, including metadata, to
- current data in the database 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::
+ Possible parameters:
- (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 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 :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 groups)
- 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 groups)
+ 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 it's 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 it's 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:
-``[compaction_daemon]`` :: Configuration of Compaction Daemon
-=============================================================
+.. _config/compaction_daemon:
-.. _config/compaction_daemon/check_interval:
+Configuration of Compaction Daemon
+==================================
-``check_interval``
-------------------
+.. config:section:: compaction_daemon :: Configuration of Compaction Daemon
-The delay, in seconds, between each check for which database and view indexes
-need to be compacted::
+ .. config:option:: check_interval
- [compaction_daemon]
- check_interval = 300
+ The delay, in seconds, between each check for which database and view
+ indexes need to be compacted::
+ [compaction_daemon]
+ check_interval = 300
-.. _config/compaction_daemon/min_file_size:
-``min_file_size``
------------------
+ .. config:option:: min_file_size
-If a database or view index file is smaller then this value (in bytes),
-compaction will not happen. Very small files always have a very high
-fragmentation therefore it's not worth to compact them::
+ If a database or view index file is smaller then this value (in bytes),
+ compaction will not happen. Very small files always have a very high
+ fragmentation therefore it's not worth to compact them::
- [compaction_daemon]
- min_file_size = 131072
+ [compaction_daemon]
+ min_file_size = 131072
.. _config/view_compaction:
-``[view_compaction]`` :: Views Compaction Options
-=================================================
+Views Compaction Options
+========================
-.. _config/view_compaction/keyvalue_buffer_size:
+.. config:section:: view_compaction :: Views Compaction Options
-``keyvalue_buffer_size`` :: Key-Values buffer size
---------------------------------------------------
-Specifies maximum copy buffer size in bytes used during compaction::
+ .. config:option:: keyvalue_buffer_size :: Key-Values buffer size
- [view_compaction]
- keyvalue_buffer_size = 2097152
+ Specifies maximum copy buffer size in bytes used during compaction::
+ [view_compaction]
+ keyvalue_buffer_size = 2097152
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6f31ffd9/share/doc/src/config/couchdb.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/couchdb.rst b/share/doc/src/config/couchdb.rst
index d42e5b8..6f3c022 100644
--- a/share/doc/src/config/couchdb.rst
+++ b/share/doc/src/config/couchdb.rst
@@ -10,6 +10,8 @@
.. License for the specific language governing permissions and limitations under
.. the License.
+.. default-domain:: config
+
.. highlight:: ini
==================
@@ -18,212 +20,181 @@ Base Configuration
.. _config/couchdb:
-``[couchdb]`` :: Base CouchDB Options
-=====================================
-
-.. _config/couchdb/attachment_stream_buffer_size:
-
-``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/couchdb/database_dir:
-
-``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
+Base CouchDB Options
+====================
+.. config:section:: couchdb :: Base CouchDB Options
-.. _config/couchdb/delayed_commits:
-``delayed_commits`` :: Delayed commits
---------------------------------------
+ .. config:option:: attachment_stream_buffer_size :: Attachment streaming buffer
-When this config value as ``false`` the CouchDB provides guaranty of fsync call
-before return ``HTTP 201 Created`` 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::
+ 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]
- delayed_commits = false
+ ::
-.. warning::
+ [couchdb]
+ attachment_stream_buffer_size = 4096
- 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:: database_dir :: Databases location directory
-.. _config/couchdb/file_compression:
+ 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).
-``file_compression`` :: Compression method for documents
------------------------------------------------------------
+ ::
-.. versionchanged:: 1.2 Added `Google Snappy`_ compression algorithm.
+ [couchdb]
+ database_dir = /var/lib/couchdb
-Method used to compress everything that is appended to database and view index
-files, except for attachments (see the :ref:`[attachments] <config/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)
+ .. 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]
- file_compression = snappy
+ [couchdb]
+ delayed_commits = false
-.. _Google Snappy: http://code.google.com/p/snappy/
+ .. 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/couchdb/fsync_options:
-``fsync_options`` :: Fsync options
-----------------------------------
+ .. config:option:: file_compression :: Compression method for documents
-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.
+ .. 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:
- [couchdb]
- fsync_options = [before_header, after_header, on_file_open]
+ * ``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)
+ ::
-.. _config/couchdb/max_dbs_open:
+ [couchdb]
+ file_compression = snappy
-``max_dbs_open`` :: Limit of simultaneously opened databases
-------------------------------------------------------------
+ .. _Google Snappy: http://code.google.com/p/snappy/
-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.
-::
+ .. config:option:: fsync_options :: Fsync options
- [couchdb]
- max_dbs_open = 100
+ 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/couchdb/max_document_size:
+ [couchdb]
+ fsync_options = [before_header, after_header, on_file_open]
-``max_document_size`` :: Maximum document size
-----------------------------------------------
-.. versionchanged:: 1.3 This option now actually works.
+ .. config:option:: max_dbs_open :: Limit of simultaneously opened databases
-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.
+ 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_document_size = 4294967296 ; 4 GB
+ [couchdb]
+ max_dbs_open = 100
-.. _config/couchdb/os_process_timeout:
+ .. config:option:: max_document_size :: Maximum document size
-``os_process_timeout`` :: External processes time limit
--------------------------------------------------------
+ .. versionchanged:: 1.3 This option now actually works.
-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.
+ 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]
- os_process_timeout = 5000 ; 5 sec
+ [couchdb]
+ max_document_size = 4294967296 ; 4 GB
-.. _config/couchdb/uri_file:
+ .. config:option:: os_process_timeout :: External processes time limit
-``uri_file`` :: Discovery CouchDB help file
--------------------------------------------
+ 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.
-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]
+ os_process_timeout = 5000 ; 5 sec
- [couchdb]
- uri_file = /var/run/couchdb/couchdb.uri
-.. _URI: http://en.wikipedia.org/wiki/URI
+ .. 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).
-.. _config/couchdb/util_driver_dir:
+ ::
-``util_driver_dir`` :: CouchDB binary utility drivers
------------------------------------------------------
+ [couchdb]
+ uri_file = /var/run/couchdb/couchdb.uri
-Specifies location of binary drivers (`icu`, `ejson`, etc.). This location and
-its contents should be readable for the user that runs the CouchDB service.
+ .. _URI: http://en.wikipedia.org/wiki/URI
-::
- [couchdb]
- util_driver_dir = /usr/lib/couchdb/erlang/lib/couch-1.5.0/priv/lib
+ .. config:option:: util_driver_dir :: CouchDB binary utility drivers
+ 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/couchdb/uuid:
+ ::
-``uuid`` :: CouchDB server UUID
--------------------------------
+ [couchdb]
+ util_driver_dir = /usr/lib/couchdb/erlang/lib/couch-1.5.0/priv/lib
-.. versionadded:: 1.3
-Unique identifier for this CouchDB server instance.
+ .. config:option:: uuid :: CouchDB server UUID
-::
+ .. versionadded:: 1.3
- [couchdb]
- uuid = 0a959b9b8227188afc2ac26ccdf345a6
+ Unique identifier for this CouchDB server instance.
+ ::
-.. _config/couchdb/view_index_dir:
+ [couchdb]
+ uuid = 0a959b9b8227188afc2ac26ccdf345a6
-``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).
+ .. 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/blob/6f31ffd9/share/doc/src/config/externals.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/externals.rst b/share/doc/src/config/externals.rst
index d4a8eab..c05fe05 100644
--- a/share/doc/src/config/externals.rst
+++ b/share/doc/src/config/externals.rst
@@ -10,6 +10,8 @@
.. License for the specific language governing permissions and limitations under
.. the License.
+.. default-domain:: config
+
.. highlight:: ini
==================
@@ -18,162 +20,160 @@ External Processes
.. _config/os_daemons:
-``[os_daemons]`` :: 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
-:ref:`adjustable <config/os_daemon_settings>`.
+.. config:section:: os_daemons :: OS Daemons
-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
-`CouchDB Externals API`_.
+ 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.
-.. _CouchDB Externals API: http://davispj.com/2010/09/26/new-couchdb-externals-api.html
+ 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:
-``[os_daemon_settings]`` :: OS Daemons settings
-===============================================
-
-.. _config/os_daemons_settings/max_retries:
+OS Daemons settings
+===================
-``max_retries`` :: Maximum restart retries
-------------------------------------------
+.. config:section:: os_daemon_settings :: OS Daemons settings
-Specifies maximum attempts to run :ref:`os_daemon <config/os_daemons>` before
-mark them halted::
- [os_daemon_settings]
- max_retries = 3
+ .. config:option:: max_retries :: Maximum restart retries
+ Specifies maximum attempts to run :section:`os_daemons` before
+ mark them halted::
-.. _config/os_daemons_settings/retry_time:
+ [os_daemon_settings]
+ max_retries = 3
-``retry_time`` :: Delay between restart attempts
-------------------------------------------------
-Delay in seconds between :ref:`os_daemon <config/os_daemons>` restarts::
+ .. config:option:: retry_time :: Delay between restart attempts
- [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:
-``[update_notification]`` :: Update notifications
-=================================================
+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`::
+.. config:section:: update_notification :: Update notifications
- [update_notification]
- ;unique notifier name=/full/path/to/exe -with "cmd line arg"
- index_updater = ruby /usr/local/bin/index_updater.rb
+ 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:
+ The update notification messages are depend upon of event type:
-- **Database created**:
+ - **Database created**:
- .. code-block:: javascript
+ .. code-block:: javascript
- {"type":"created","db":"dbname"}
+ {"type":"created","db":"dbname"}
-- **Database updated**: this event raises when any document gets updated for
- specified database:
+ - **Database updated**: this event raises when any document gets updated for
+ specified database:
- .. code-block:: javascript
+ .. code-block:: javascript
- {"type":"updated","db":"dbname"}
+ {"type":"updated","db":"dbname"}
-- **Design document updated**: for design document updates there is special
- event raised in additional to regular db update one:
+ - **Design document updated**: for design document updates there is special
+ event raised in additional to regular db update one:
- .. code-block:: javascript
+ .. code-block:: javascript
- {"type":"ddoc_updated","db":"dbname","id":"_design/ddoc_name"}
+ {"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/blob/6f31ffd9/share/doc/src/config/http-handlers.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/http-handlers.rst b/share/doc/src/config/http-handlers.rst
index 7da653d..e4a1f41 100644
--- a/share/doc/src/config/http-handlers.rst
+++ b/share/doc/src/config/http-handlers.rst
@@ -18,324 +18,274 @@ HTTP Resource Handlers
.. _config/httpd_global_handlers:
-``[httpd_global_handlers]`` :: Global HTTP Handlers
-===================================================
+Global HTTP Handlers
+====================
-These HTTP resources are provided for CouchDB server root level.
+.. config:section:: httpd_global_handlers :: Global HTTP Handlers
-.. _config/httpd_global_handlers/root:
+ These HTTP resources are provided for CouchDB server root level.
-:ref:`/ <api/server/root>`
---------------------------
+ .. 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/httpd_global_handlers/favicon.ico:
-:ref:`favicon.ico <api/server/favicon>`
----------------------------------------
+ .. config:option:: favicon.ico
-The favicon handler looks for `favicon.ico` file within specified directory::
+ The favicon handler looks for `favicon.ico` file within specified directory::
- [httpd_global_handlers]
- favicon.ico = {couch_httpd_misc_handlers, handle_favicon_req, "/usr/share/couchdb/www"}
+ [httpd_global_handlers]
+ favicon.ico = {couch_httpd_misc_handlers, handle_favicon_req, "/usr/share/couchdb/www"}
-.. _config/httpd_global_handlers/_active_tasks:
-:ref:`_active_tasks <api/server/active_tasks>`
-----------------------------------------------
+ .. config:option:: _active_tasks
-::
+ ::
- [httpd_global_handlers]
- _active_tasks = {couch_httpd_misc_handlers, handle_task_status_req}
+ [httpd_global_handlers]
+ _active_tasks = {couch_httpd_misc_handlers, handle_task_status_req}
-.. _config/httpd_global_handlers/_all_dbs:
-:ref:`_all_dbs <api/server/all_dbs>`
-------------------------------------
+ .. config:option:: _all_dbs
-Provides a list of all server's databases::
+ Provides a list of all server's databases::
- [httpd_global_handlers]
- _all_dbs = {couch_httpd_misc_handlers, handle_all_dbs_req}
+ [httpd_global_handlers]
+ _all_dbs = {couch_httpd_misc_handlers, handle_all_dbs_req}
-.. note::
+ .. 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.
+ 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 s`ame also is true for other resource handlers.
+ The same also is true for other resource handlers.
-.. _config/httpd_global_handlers/_config:
-:ref:`_config <api/config>`
----------------------------
+ .. config:option:: _config
-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 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::
- [httpd_global_handlers]
- _config = {couch_httpd_misc_handlers, handle_config_req}
+ [httpd_global_handlers]
+ _config = {couch_httpd_misc_handlers, handle_config_req}
-.. _config/httpd_global_handlers/_log:
-:ref:`_log <api/server/log>`
-----------------------------
+ .. config:option:: _log
-::
+ ::
- [httpd_global_handlers]
- _log = {couch_httpd_misc_handlers, handle_log_req}
+ [httpd_global_handlers]
+ _log = {couch_httpd_misc_handlers, handle_log_req}
-.. _config/httpd_global_handlers/_oauth:
-``_oauth``
-----------
+ .. config:option:: _oauth
-::
+ ::
- [httpd_global_handlers]
- _oauth = {couch_httpd_oauth, handle_oauth_req}
+ [httpd_global_handlers]
+ _oauth = {couch_httpd_oauth, handle_oauth_req}
-.. _config/httpd_global_handlers/_replicate:
-:ref:`_replicate <api/server/replicate>`
-----------------------------------------
+ .. config:option:: _replicate
-Provides an API to run :ref:`temporary replications <api/server/replicate>`::
+ Provides an API to run :ref:`temporary replications <api/server/replicate>`::
- [httpd_global_handlers]
- _replicate = {couch_replicator_httpd, handle_req}
+ [httpd_global_handlers]
+ _replicate = {couch_replicator_httpd, handle_req}
-.. _config/httpd_global_handlers/_restart:
-:ref:`_restart <api/server/restart>`
-------------------------------------
+ .. config:option:: _restart
-::
+ ::
- [httpd_global_handlers]
- _restart = {couch_httpd_misc_handlers, handle_restart_req}
+ [httpd_global_handlers]
+ _restart = {couch_httpd_misc_handlers, handle_restart_req}
-.. _config/httpd_global_handlers/_session:
-``_session``
-------------
+ .. config:option:: _session
-Provides a resource with information about the current user's session::
+ Provides a resource with information about the current user's session::
- [httpd_global_handlers]
- _session = {couch_httpd_auth, handle_session_req}
+ [httpd_global_handlers]
+ _session = {couch_httpd_auth, handle_session_req}
-.. _config/httpd_global_handlers/_stats:
+ .. config:option:: _stats
-:ref:`_stats <api/server/stats>`
---------------------------------
+ ::
-::
+ [httpd_global_handlers]
+ _stats = {couch_httpd_stats_handlers, handle_stats_req}
- [httpd_global_handlers]
- _stats = {couch_httpd_stats_handlers, handle_stats_req}
+ .. config:option:: _utils
-.. _config/httpd_global_handlers/_utils:
+ The :ref:`_utils <api/server/utils>` handler serves `Futon`'s web administration
+ page::
-:ref:`_utils <api/server/utils>`
---------------------------------
+ [httpd_global_handlers]
+ _utils = {couch_httpd_misc_handlers, handle_utils_dir_req, "/usr/share/couchdb/www"}
-The :ref:`_utils <api/server/utils>` handler serves `Futon`'s web administration
-page::
+ In similar way, you may setup custom handler to let CouchDB serve any static
+ files.
- [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::
-.. _config/httpd_global_handlers/_uuids:
+ [httpd_global_handlers]
+ _uuids = {couch_httpd_misc_handlers, handle_uuids_req}
-:ref:`_uuids <api/server/uuids>`
---------------------------------
+ This is useful when your client environment isn't capable of providing truly
+ random IDs (web browsers e.g.).
-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.).
.. _config/httpd_db_handlers:
-``[httpd_db_handlers]`` :: Database HTTP Handlers
-=================================================
+Database HTTP Handlers
+======================
+
+.. config:section:: httpd_db_handlers :: Database HTTP Handlers
-These HTTP resources are available on every CouchDB database.
+ These HTTP resources are available on every CouchDB database.
-.. _config/httpd_db_handlers/_all_docs:
-:ref:`_all_docs <api/db/all_docs>`
-----------------------------------
+ .. config:option:: _all_docs
-::
+ ::
- [httpd_db_handlers]
- _all_docs = {couch_mrview_http, handle_all_docs_req}
+ [httpd_db_handlers]
+ _all_docs = {couch_mrview_http, handle_all_docs_req}
-.. _config/httpd_db_handlers/_changes:
-:ref:`_changes <changes>`
--------------------------
+ .. config:option:: _changes
-::
+ ::
- [httpd_db_handlers]
- _changes = {couch_httpd_db, handle_changes_req}
+ [httpd_db_handlers]
+ _changes = {couch_httpd_db, handle_changes_req}
-.. _config/httpd_db_handlers/_compact:
-:ref:`_compact <api/db/compact>`
---------------------------------
+ .. config:option:: _compact
-::
+ ::
- [httpd_db_handlers]
- _compact = {couch_httpd_db, handle_compact_req}
+ [httpd_db_handlers]
+ _compact = {couch_httpd_db, handle_compact_req}
-.. _config/httpd_db_handlers/_design:
-:ref:`_design <api/ddoc>`
--------------------------
+ .. config:option:: _design
-::
+ ::
- [httpd_db_handlers]
- _design = {couch_httpd_db, handle_design_req}
+ [httpd_db_handlers]
+ _design = {couch_httpd_db, handle_design_req}
-.. _config/httpd_db_handlers/_temp_view:
-:ref:`_temp_view <api/db/temp_view>`
-------------------------------------
+ .. config:option:: _temp_view
-::
+ ::
- [httpd_db_handlers]
- _temp_view = {couch_mrview_http, handle_temp_view_req}
+ [httpd_db_handlers]
+ _temp_view = {couch_mrview_http, handle_temp_view_req}
-.. _config/httpd_db_handlers/_view_cleanup:
-:ref:`_view_cleanup <api/db/view_cleanup>`
-------------------------------------------
+ .. 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:
-``[httpd_design_handlers]`` :: Design Documents HTTP Handlers
-=============================================================
+Design Documents HTTP Handlers
+==============================
-These HTTP resources are provided for design documents.
+.. config:section:: httpd_design_handlers :: Design Documents HTTP Handlers
-.. _config/httpd_design_handlers/_compact:
+These HTTP resources are provided for design documents.
-:ref:`_compact <api/db/compact/ddoc>`
--------------------------------------
-::
+ .. config:option:: _compact
- [httpd_design_handlers]
- _compact = {couch_mrview_http, handle_compact_req}
+ ::
+ [httpd_design_handlers]
+ _compact = {couch_mrview_http, handle_compact_req}
-.. _config/httpd_design_handlers/_info:
-:ref:`_info <api/ddoc/info>`
-----------------------------
-::
+ .. config:option:: _info
- [httpd_design_handlers]
- _info = {couch_mrview_http, handle_info_req}
+ ::
+ [httpd_design_handlers]
+ _info = {couch_mrview_http, handle_info_req}
-.. _config/httpd_design_handlers/_list:
-:ref:`_list <api/ddoc/list>`
-----------------------------
-::
+ .. config:option:: _list
- [httpd_design_handlers]
- _list = {couch_mrview_show, handle_view_list_req}
+ ::
+ [httpd_design_handlers]
+ _list = {couch_mrview_show, handle_view_list_req}
-.. _config/httpd_design_handlers/_rewrite:
-:ref:`_rewrite <api/ddoc/rewrite>`
-----------------------------------
-::
+ .. config:option:: _rewrite
- [httpd_design_handlers]
- _rewrite = {couch_httpd_rewrite, handle_rewrite_req}
+ ::
+ [httpd_design_handlers]
+ _rewrite = {couch_httpd_rewrite, handle_rewrite_req}
-.. _config/httpd_design_handlers/_show:
-:ref:`_show <api/ddoc/show>`
-----------------------------
-::
+ .. config:option:: _show
- [httpd_design_handlers]
- _show = {couch_mrview_show, handle_doc_show_req}
+ ::
+ [httpd_design_handlers]
+ _show = {couch_mrview_show, handle_doc_show_req}
-.. _config/httpd_design_handlers/_update:
-:ref:`_update <api/ddoc/update>`
---------------------------------
-::
+ .. config:option:: _update
- [httpd_design_handlers]
- _update = {couch_mrview_show, handle_doc_update_req}
+ ::
+ [httpd_design_handlers]
+ _update = {couch_mrview_show, handle_doc_update_req}
-.. _config/httpd_design_handlers/_view:
-:ref:`_view <api/ddoc/view>`
-----------------------------
-::
+ .. config:option:: _view
- [httpd_design_handlers]
- _view = {couch_mrview_http, handle_view_req}
+ ::
+ [httpd_design_handlers]
+ _view = {couch_mrview_http, handle_view_req}