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:24 UTC
[2/3] Add configuration domain.
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
^^^^^^^^^^^^^^^^^^^^^^^^^^