You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by kx...@apache.org on 2015/02/20 01:26:47 UTC
[14/26] documentation commit: updated refs/heads/master to 5a81ace
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/71a4fc90/src/config/http.rst
----------------------------------------------------------------------
diff --git a/src/config/http.rst b/src/config/http.rst
index 33adb84..90ce031 100644
--- a/src/config/http.rst
+++ b/src/config/http.rst
@@ -11,7 +11,6 @@
.. the License.
.. default-domain:: config
-
.. highlight:: ini
===================
@@ -25,220 +24,202 @@ HTTP Server Options
.. config:section:: httpd :: HTTP Server Options
- .. config:option:: 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:option:: 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:option:: allow_jsonp :: Enables JSONP support
- .. config:option:: bind_address :: Listen IP address
+ The ``true`` value of this option enables `JSONP`_ support (it's
+ ``false`` by default)::
- Defines the IP address by which CouchDB will be accessible::
+ [httpd]
+ allow_jsonp = false
- [httpd]
- bind_address = 127.0.0.1
+ .. _JSONP: http://www.json-p.org/
- To let CouchDB listen any available IP address, just setup ``0.0.0.0``
- value::
+ .. config:option:: authentication_handlers :: Authentication handlers
- [httpd]
- bind_address = 0.0.0.0
+ 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::
- For IPv6 support you need to set ``::1`` if you want to let CouchDB listen
- local address::
+ [httpd]
+ authentication_handlers = {couch_httpd_oauth, oauth_authentication_handler}, {couch_httpd_auth, cookie_authentication_handler}, {couch_httpd_auth, default_authentication_handler}
- [httpd]
- bind_address = ::1
+ - ``{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`!
- or ``::`` for any available::
+ .. config:option:: bind_address :: Listen IP address
- [httpd]
- bind_address = ::
+ Defines the IP address by which CouchDB will be accessible::
+ [httpd]
+ bind_address = 127.0.0.1
- .. config:option:: changes_timeout :: Changes feed timeout
+ To let CouchDB listen any available IP address, just setup ``0.0.0.0``
+ value::
- Specifies default `timeout` value for :ref:`Changes Feed <changes>` in
- milliseconds (60000 by default)::
+ [httpd]
+ bind_address = 0.0.0.0
- [httpd]
- changes_feed = 60000 ; 60 seconds
+ For IPv6 support you need to set ``::1`` if you want to let CouchDB
+ listen local address::
+ [httpd]
+ bind_address = ::1
- .. config:option:: config_whitelist :: Config options while list
+ or ``::`` for any available::
- 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::
+ [httpd]
+ bind_address = ::
- [httpd]
- config_whitelist = [{httpd,config_whitelist}, {log,level}, {etc,etc}]
+ .. config:option:: changes_timeout :: Changes feed timeout
+ Specifies default `timeout` value for :ref:`Changes Feed <changes>` in
+ milliseconds (60000 by default)::
- .. config:option:: default_handler :: Default request handler
+ [httpd]
+ changes_feed = 60000 ; 60 seconds
- Specifies default HTTP requests handler::
+ .. config:option:: config_whitelist :: Config options while list
- [httpd]
- default_handler = {couch_httpd_db, handle_request}
+ 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::
+ [httpd]
+ config_whitelist = [{httpd,config_whitelist}, {log,level}, {etc,etc}]
- .. config:option:: enable_cors :: Activates CORS
+ .. config:option:: default_handler :: Default request handler
- .. versionadded:: 1.3
+ Specifies default HTTP requests handler::
- Controls :ref:`CORS <config/cors>` feature::
+ [httpd]
+ default_handler = {couch_httpd_db, handle_request}
- [httpd]
- enable_cors = false
+ .. config:option:: enable_cors :: Activates CORS
+ .. versionadded:: 1.3
- .. config:option:: log_max_chunk_size :: Logs chunk size
+ Controls :ref:`CORS <config/cors>` feature::
- Defines maximum chunk size in bytes for :ref:`_log <api/server/log>`
- resource::
+ [httpd]
+ enable_cors = false
- [httpd]
- log_max_chunk_size = 1000000
+ .. config:option:: log_max_chunk_size :: Logs chunk size
+ Defines maximum chunk size in bytes for :ref:`_log <api/server/log>`
+ resource::
- .. config:option:: port :: Listen port
+ [httpd]
+ log_max_chunk_size = 1000000
- Defined the port number to listen::
+ .. config:option:: port :: Listen port
- [httpd]
- port = 5984
+ Defined the port number to listen::
- To let CouchDB handle any free port, set this option to ``0``::
+ [httpd]
+ port = 5984
- [httpd]
- port = 0
+ To let CouchDB handle any free port, set this option to ``0``::
- After that, CouchDB URI could be located within the URI file.
+ [httpd]
+ port = 0
+ After that, CouchDB URI could be located within the URI file.
- .. config:option:: redirect_vhost_handler :: Virtual Hosts custom redirect handler
+ .. config:option:: redirect_vhost_handler :: Virtual Hosts custom redirect handler
- This option customizes the default function that handles requests to
- :section:`virtual hosts <vhosts>`::
+ This option customizes the default function that handles requests to
+ :section:`virtual hosts <vhosts>`::
- [httpd]
- redirect_vhost_handler = {Module, Fun}
+ [httpd]
+ redirect_vhost_handler = {Module, Fun}
- The specified function take 2 arguments: the Mochiweb request object and the
- target path.
+ The specified function take 2 arguments: the Mochiweb request object
+ and the target path.
+ .. config:option:: server_options :: MochiWeb Server Options
- .. config:option:: server_options :: MochiWeb Server Options
+ Server options for the `MochiWeb`_ component of CouchDB can be added to
+ the configuration files::
- Server options for the `MochiWeb`_ component of CouchDB can be added to the
- configuration files::
+ [httpd]
+ server_options = [{backlog, 128}, {acceptor_pool_size, 16}]
- [httpd]
- server_options = [{backlog, 128}, {acceptor_pool_size, 16}]
+ .. _MochiWeb: https://github.com/mochi/mochiweb
- .. _MochiWeb: https://github.com/mochi/mochiweb
+ .. config:option:: secure_rewrites :: Default request handler
+ This option allow to isolate databases via subdomains::
- .. config:option:: secure_rewrites :: Default request handler
+ [httpd]
+ secure_rewrites = true
- This option allow to isolate databases via subdomains::
+ .. config:option:: socket_options :: Socket Options
- [httpd]
- secure_rewrites = true
+ The socket options for the listening socket in CouchDB can be specified
+ as a list of tuples. For example::
+ [httpd]
+ socket_options = [{recbuf, 262144}, {sndbuf, 262144}, {nodelay, true}]
- .. config:option:: socket_options :: Socket Options
+ 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.
- The socket options for the listening socket in CouchDB can be specified as
- a list of tuples. For example::
+ .. _Erlang inet: http://www.erlang.org/doc/man/inet.html#setopts-2
- [httpd]
- socket_options = [{recbuf, 262144}, {sndbuf, 262144}, {nodelay, true}]
+ .. config:option:: vhost_global_handlers :: Virtual hosts global handlers
- 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.
+ List of global handlers that are available for :section:`virtual hosts
+ <vhosts>`::
- .. _Erlang inet: http://www.erlang.org/doc/man/inet.html#setopts-2
+ [httpd]
+ vhost_global_handlers = _utils, _uuids, _session, _oauth, _users
+ .. config:option:: x_forwarded_host :: X-Forwarder-Host
- .. config:option:: vhost_global_handlers :: Virtual hosts global handlers
+ 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::
- List of global handlers that are available for :section:`virtual hosts
- <vhosts>`::
+ [httpd]
+ x_forwarded_host = X-Forwarded-Host
- [httpd]
- vhost_global_handlers = _utils, _uuids, _session, _oauth, _users
+ This header has higher priority above ``Host`` one, if only it exists
+ in the request.
+ .. config:option:: x_forwarded_proto :: X-Forwarder-Proto
- .. config:option:: x_forwarded_host :: X-Forwarder-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::
- 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]
+ x_forwarded_proto = X-Forwarded-Proto
- [httpd]
- x_forwarded_host = X-Forwarded-Host
+ .. config:option:: x_forwarded_ssl :: X-Forwarder-Ssl
- This header has higher priority above ``Host`` one, if only it exists in
- the request.
+ 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_proto :: X-Forwarder-Proto
+ .. config:option:: WWW-Authenticate :: Force basic auth
- `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::
-
- [httpd]
- x_forwarded_proto = X-Forwarded-Proto
-
-
- .. 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::
-
- [httpd]
- x_forwarded_ssl = X-Forwarded-Ssl
-
-
- .. config:option:: WWW-Authenticate :: Force basic auth
-
- Set this option to trigger basic-auth popup on unauthorized requests::
-
- [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:
@@ -247,184 +228,176 @@ Secure Socket Level Options
.. config:section:: ssl :: 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.
-
- 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.
- shell> mkdir /etc/couchdb/cert
- shell> cd /etc/couchdb/cert
- shell> openssl genrsa > privkey.pem
- shell> openssl req -new -x509 -key privkey.pem -out couchdb.pem -days 1095
- shell> chmod 600 privkey.pem couchdb.pem
- shell> chown couchdb privkey.pem couchdb.pem
+ .. code-block:: bash
- 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.
+ shell> mkdir /etc/couchdb/cert
+ shell> cd /etc/couchdb/cert
+ shell> openssl genrsa > privkey.pem
+ shell> openssl req -new -x509 -key privkey.pem -out couchdb.pem -days 1095
+ shell> chmod 600 privkey.pem couchdb.pem
+ shell> chown couchdb privkey.pem couchdb.pem
- At first, :option:`enable the HTTPS daemon <daemons/httpsd>`::
+ 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.
- [daemons]
- httpsd = {couch_httpd, start_link, [https]}
+ At first, :option:`enable the HTTPS daemon <daemons/httpsd>`::
- Next, under ``[ssl]`` section setup newly generated certificates::
+ [daemons]
+ httpsd = {couch_httpd, start_link, [https]}
- [ssl]
- cert_file = /etc/couchdb/cert/couchdb.pem
- key_file = /etc/couchdb/cert/privkey.pem
+ Next, under ``[ssl]`` section setup newly generated certificates::
- For more information please read `certificates HOWTO`_.
+ [ssl]
+ cert_file = /etc/couchdb/cert/couchdb.pem
+ key_file = /etc/couchdb/cert/privkey.pem
- Now start (or restart) CouchDB. You should be able to connect to it
- using HTTPS on port 6984:
+ For more information please read `certificates HOWTO`_.
- .. code-block:: bash
+ Now start (or restart) CouchDB. You should be able to connect to it
+ using HTTPS on port 6984:
- shell> curl https://127.0.0.1:6984/
- curl: (60) SSL certificate problem, verify that the CA cert is OK. Details:
- error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed
- More details here: http://curl.haxx.se/docs/sslcerts.html
+ .. code-block:: bash
- curl performs SSL certificate verification by default, using a "bundle"
- of Certificate Authority (CA) public keys (CA certs). If the default
- bundle file isn't adequate, you can specify an alternate file
- using the --cacert option.
- If this HTTPS server uses a certificate signed by a CA represented in
- the bundle, the certificate verification probably failed due to a
- problem with the certificate (it might be expired, or the name might
- not match the domain name in the URL).
- If you'd like to turn off curl's verification of the certificate, use
- the -k (or --insecure) option.
+ shell> curl https://127.0.0.1:6984/
+ curl: (60) SSL certificate problem, verify that the CA cert is OK. Details:
+ error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed
+ More details here: http://curl.haxx.se/docs/sslcerts.html
- 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:
+ curl performs SSL certificate verification by default, using a "bundle"
+ of Certificate Authority (CA) public keys (CA certs). If the default
+ bundle file isn't adequate, you can specify an alternate file
+ using the --cacert option.
+ If this HTTPS server uses a certificate signed by a CA represented in
+ the bundle, the certificate verification probably failed due to a
+ problem with the certificate (it might be expired, or the name might
+ not match the domain name in the URL).
+ If you'd like to turn off curl's verification of the certificate, use
+ the -k (or --insecure) option.
- .. code-block:: bash
+ 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:
- shell> curl -k https://127.0.0.1:6984/
- {"couchdb":"Welcome","version":"1.5.0"}
+ .. code-block:: bash
- All done.
+ shell> curl -k https://127.0.0.1:6984/
+ {"couchdb":"Welcome","version":"1.5.0"}
- .. _`certificates HOWTO`: http://www.openssl.org/docs/HOWTO/certificates.txt
- .. _OpenSSL: http://www.openssl.org/
+ All done.
+ .. _`certificates HOWTO`: http://www.openssl.org/docs/HOWTO/certificates.txt
+ .. _OpenSSL: http://www.openssl.org/
- .. config:option:: cacert_file :: CA Certificate file
+ .. config:option:: cacert_file :: CA Certificate file
- The path to a file containing PEM encoded CA certificates. The CA
- certificates are used to build the server certificate chain, and for client
- authentication. Also the CAs are used in the list of acceptable client CAs
- passed to the client when a certificate is requested. May be omitted if
- there is no need to verify the client and if there are not any intermediate
- CAs for the server certificate::
+ The path to a file containing PEM encoded CA certificates. The CA
+ certificates are used to build the server certificate chain, and for
+ client authentication. Also the CAs are used in the list of acceptable
+ client CAs passed to the client when a certificate is requested. May be
+ omitted if there is no need to verify the client and if there are not
+ any intermediate CAs for the server certificate::
- [ssl]
- cacert_file = /etc/ssl/certs/ca-certificates.crt
+ [ssl]
+ cacert_file = /etc/ssl/certs/ca-certificates.crt
+ .. config:option:: cert_file :: Certificate file
- .. config:option:: cert_file :: Certificate file
+ Path to a file containing the user's certificate::
- Path to a file containing the user's certificate::
+ [ssl]
+ cert_file = /etc/couchdb/cert/couchdb.pem
- [ssl]
- cert_file = /etc/couchdb/cert/couchdb.pem
+ .. config:option:: key_file :: Certificate key file
+ Path to file containing user's private PEM encoded key::
- .. config:option:: key_file :: Certificate key file
+ [ssl]
+ key_file = /etc/couchdb/cert/privkey.pem
- Path to file containing user's private PEM encoded key::
+ .. config:option:: 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
+ .. config:option:: ssl_certificate_max_depth :: Maximum peer certificate depth
- String containing the user's password. Only used if the private keyfile is
- password protected::
+ Maximum peer certificate depth (must be set even if certificate
+ validation is off)::
- [ssl]
- password = somepassword
+ [ssl]
+ ssl_certificate_max_depth = 1
+ .. config:option:: verify_fun :: SSL verification function
- .. config:option:: ssl_certificate_max_depth :: Maximum peer certificate depth
+ The verification fun (optional) if not specified, the default
+ verification fun will be used::
- Maximum peer certificate depth (must be set even if certificate validation
- is off)::
+ [ssl]
+ verify_fun = {Module, VerifyFun}
- [ssl]
- ssl_certificate_max_depth = 1
+ .. config:option:: verify_ssl_certificates :: Enable certificate verification
+ Set to `true` to validate peer certificates::
- .. config:option:: verify_fun :: SSL verification function
+ [ssl]
+ verify_ssl_certificates = false
- The verification fun (optional) if not specified, the default
- verification fun will be used::
+ .. config:option:: fail_if_no_peer_cert :: Require presence of client certificate if certificate verification is enabled
- [ssl]
- verify_fun = {Module, VerifyFun}
+ Set to `true` to terminate the TLS/SSL handshake with a
+ `handshake_failure` alert message if the client does not send a
+ certificate. Only used if `verify_ssl_certificates` is `true`. If set
+ to `false` it will only fail if the client sends an invalid certificate
+ (an empty certificate is considered valid)::
+ [ssl]
+ fail_if_no_peer_cert = false
- .. config:option:: verify_ssl_certificates :: Enable certificate verification
+ .. config:option:: secure_renegotiate :: Enable secure renegotiation
- Set to `true` to validate peer certificates::
+ Set to `true` to reject renegotiation attempt that does not live up to
+ RFC 5746::
- [ssl]
- verify_ssl_certificates = false
+ [ssl]
+ secure_renegotiate = true
- .. config:option:: fail_if_no_peer_cert :: Require presence of client certificate if certificate verification is enabled
+ .. config:option:: ciphers :: Specify permitted server cipher list
- Set to `true` to terminate the TLS/SSL handshake with a
- `handshake_failure` alert message if the client does not send a
- certificate. Only used if `verify_ssl_certificates` is `true`. If
- set to `false` it will only fail if the client sends an invalid
- certificate (an empty certificate is considered valid)::
+ Set to the cipher suites that should be supported which can be
+ specified in erlang format "{ecdhe_ecdsa,aes_128_cbc,sha256}" or
+ in OpenSSL format "ECDHE-ECDSA-AES128-SHA256". ::
- [ssl]
- fail_if_no_peer_cert = false
+ [ssl]
+ ciphers = ["ECDHE-ECDSA-AES128-SHA256", "ECDHE-ECDSA-AES128-SHA"]
- .. config:option:: secure_renegotiate :: Enable secure renegotiation
+ .. config:option:: tls_versions :: Specify permitted server SSL/TLS protocol versions
- Set to `true` to reject renegotiation attempt that does not live up to RFC 5746::
-
- [ssl]
- secure_renegotiate = true
-
- .. config:option:: ciphers :: Specify permitted server cipher list
-
- Set to the cipher suites that should be supported which can be
- specified in erlang format "{ecdhe_ecdsa,aes_128_cbc,sha256}" or
- in OpenSSL format "ECDHE-ECDSA-AES128-SHA256".
-
- [ssl]
- ciphers = ["ECDHE-ECDSA-AES128-SHA256", "ECDHE-ECDSA-AES128-SHA"]
-
- .. config:option:: tls_versions :: Specify permitted server SSL/TLS
- protocol versions
-
- Set to a list of permitted SSL/TLS protocol versions::
-
- [ssl]
- tls_versions = [tlsv1 | 'tlsv1.1' | 'tlsv1.2']
+ Set to a list of permitted SSL/TLS protocol versions::
+ [ssl]
+ tls_versions = [tlsv1 | 'tlsv1.1' | 'tlsv1.2']
.. _cors:
.. _config/cors:
@@ -434,113 +407,105 @@ Cross-Origin Resource Sharing
.. config:section:: cors :: Cross-Origin Resource Sharing
- .. versionadded:: 1.3 added CORS support, see JIRA :issue:`431`
-
- `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.
-
- 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.
-
- 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.
+ .. versionadded:: 1.3 added CORS support, see JIRA :issue:`431`
- 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.
+ `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.
- 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.
+ 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.
- This section requires :option:`httpd/enable_cors` option have
- ``true`` value::
+ 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.
- [httpd]
- enable_cors = true
+ 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.
+ 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.
- .. config:option:: credentials
+ This section requires :option:`httpd/enable_cors` option have
+ ``true`` value::
- 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.
+ [httpd]
+ enable_cors = true
- ::
+ .. config:option:: 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
+ CouchDB will respond to a credentials-enabled CORS request with an
+ additional header, ``Access-Control-Allow-Credentials=true``.
- .. config:option:: origins
+ .. config:option:: origins
- List of origins separated by a comma, ``*`` means accept all.
- You can’t set ``origins = *`` and ``credentials = true`` option at the same
- time::
+ 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 = *
+ [cors]
+ origins = *
- Access can be restricted by protocol, host and optionally by port. Origins
- must follow the scheme: http://example.com:80::
+ Access can be restricted by protocol, host and optionally by port.
+ Origins must follow the scheme: http://example.com:80::
- [cors]
- origins = http://localhost, https://localhost, http://couch.mydev.name:8080
+ [cors]
+ origins = http://localhost, https://localhost, http://couch.mydev.name:8080
- Note that by default, no origins are accepted. You must define them
- explicitly.
+ Note that by default, no origins are accepted. You must define them
+ explicitly.
+ .. config:option:: headers
- .. config:option:: headers
+ List of accepted headers separated by a comma::
- List of accepted headers separated by a comma::
+ [cors]
+ headers = X-Couch-Id, X-Couch-Rev
- [cors]
- headers = X-Couch-Id, X-Couch-Rev
+ .. config:option:: methods
+ List of accepted methods::
- .. config:option:: methods
+ [cors]
+ methods = GET,POST
- List of accepted methods::
+ .. seealso::
+ Original JIRA `implementation ticket <https://issues.apache.org/jira/browse/COUCHDB-431>`_
- [cors]
- methods = GET,POST
+ Standards and References:
- .. seealso::
+ - 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>`_
- Original JIRA `implementation ticket <https://issues.apache.org/jira/browse/COUCHDB-431>`_
+ Mozilla Developer Network Resources:
- Standards and References:
+ - `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>`_
- - 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/>`_
+ 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/>`_
Per Virtual Host Configuration
------------------------------
@@ -549,16 +514,14 @@ 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
- ; List of origins separated by a comma
- origins = *
- ; List of accepted headers separated by a comma
- headers = X-CouchDB-Header
- ; List of accepted methods
- methods = HEAD, GET
-
-
+ [cors:example.com]
+ credentials = false
+ ; List of origins separated by a comma
+ origins = *
+ ; List of accepted headers separated by a comma
+ headers = X-CouchDB-Header
+ ; List of accepted methods
+ methods = HEAD, GET
.. _config/vhosts:
@@ -567,49 +530,48 @@ Virtual Hosts
.. config:section:: vhosts :: Virtual Hosts
- CouchDB can map requests to different locations based on the ``Host`` header,
- even if they arrive on the same inbound IP address.
-
- 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 same 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.
Rewriting Hosts to a Path
-------------------------
@@ -617,15 +579,14 @@ Rewriting Hosts to a Path
Like in the :ref:`_rewrite <api/ddoc/rewrite>` handler you can match some
variable and use them to create the target path. Some examples::
- [vhosts]
- *.couchdb.local = /*
- :dbname. = /:dbname
- :ddocname.:dbname.example.com = /:dbname/_design/:ddocname/_rewrite
-
+ [vhosts]
+ *.couchdb.local = /*
+ :dbname. = /:dbname
+ :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`.
-You could also change the default function to handle request by changing
-the setting :option:`httpd/redirect_vhost_handler`.
+You could also change the default function to handle request by changing the
+setting :option:`httpd/redirect_vhost_handler`.
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/71a4fc90/src/config/index.rst
----------------------------------------------------------------------
diff --git a/src/config/index.rst b/src/config/index.rst
index a9513c2..6306dc2 100644
--- a/src/config/index.rst
+++ b/src/config/index.rst
@@ -17,18 +17,18 @@ Configuring CouchDB
===================
.. toctree::
- :maxdepth: 2
+ :maxdepth: 2
- intro
- couchdb
- http
- auth
- compaction
- logging
- replicator
- query-servers
- externals
- http-handlers
- services
- misc
- proxying
+ intro
+ couchdb
+ http
+ auth
+ compaction
+ logging
+ replicator
+ query-servers
+ externals
+ http-handlers
+ services
+ misc
+ proxying
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/71a4fc90/src/config/intro.rst
----------------------------------------------------------------------
diff --git a/src/config/intro.rst b/src/config/intro.rst
index 835643a..ba19bd4 100644
--- a/src/config/intro.rst
+++ b/src/config/intro.rst
@@ -11,9 +11,7 @@
.. the License.
.. default-domain:: config
-
.. highlight:: ini
-
.. _config/intro:
=============================
@@ -21,56 +19,51 @@ Introduction Into Configuring
=============================
Configuration files
--------------------
+===================
.. warning::
- The following section covering load order of config files
- applies only to UNIX-ish systems.
- For Windows, only the provided ``default.ini`` and ``local.ini``
- files are relevant. These can of course have content
- appended, which achieves the same type of functionality
- as outlined for UNIX-ish systems below.
+ The following section covering load order of config files applies only to
+ UNIX-ish systems. For Windows, only the provided ``default.ini`` and
+ ``local.ini`` files are relevant. These can of course have content
+ appended, which achieves the same type of functionality as outlined for
+ UNIX-ish systems below.
By default, CouchDB reads configuration files from the following locations,
in the following order:
#. ``LOCALCONFDIR/default.ini``
-
#. ``LOCALCONFDIR/default.d/*.ini``
-
#. ``PLUGINS_DIR/*/priv/default.d/*.ini``
-
#. ``LOCALCONFDIR/local.ini``
-
#. ``LOCALCONFDIR/local.d/*.ini``
The ``LOCALCONFDIR`` points to the directory that contains configuration files
(``/usr/local/etc/couchdb`` by default). This variable may vary from the
-target operation system and may be changed during building from the source code.
-For binary distributions, it mostly points to the installation path
+target operation system and may be changed during building from the source
+code. For binary distributions, it mostly points to the installation path
(e.g. ``C:\Program Files\CouchDB\etc\couchdb`` for Windows).
To see the actual configuration files chain run in shell::
- couchdb -c
+ couchdb -c
This will print out all *actual* configuration files that will form the result
CouchDB configuration::
- /etc/couchdb/default.ini
- /etc/couchdb/default.d/geocouch.ini
- /etc/couchdb/local.ini
- /etc/couchdb/local.d/geocouch.ini
- /etc/couchdb/local.d/vendor.ini
+ /etc/couchdb/default.ini
+ /etc/couchdb/default.d/geocouch.ini
+ /etc/couchdb/local.ini
+ /etc/couchdb/local.d/geocouch.ini
+ /etc/couchdb/local.d/vendor.ini
Settings in successive documents override the settings in earlier entries.
-For example, setting the :option:`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
- re-installation, so localised changes should be made to the
- ``local.ini`` file or files within the ``local.d`` directory.
+ The ``default.ini`` file may be overwritten during an upgrade or
+ re-installation, so localised changes should be made to the ``local.ini``
+ file or files within the ``local.d`` directory.
The configuration files chain may be changed by specifying additional sources
by using next command line options:
@@ -80,24 +73,23 @@ by using next command line options:
Let's add these options and see how the configuration chain changes::
- shell> couchdb -c -a /home/couchdb/custom.ini
- /etc/couchdb/default.ini
- /etc/couchdb/default.d/geocouch.ini
- /etc/couchdb/local.ini
- /etc/couchdb/local.d/geocouch.ini
- /etc/couchdb/local.d/vendor.ini
- /home/couchdb/custom.ini
+ shell> couchdb -c -a /home/couchdb/custom.ini
+ /etc/couchdb/default.ini
+ /etc/couchdb/default.d/geocouch.ini
+ /etc/couchdb/local.ini
+ /etc/couchdb/local.d/geocouch.ini
+ /etc/couchdb/local.d/vendor.ini
+ /home/couchdb/custom.ini
In case when `/home/couchdb/custom.ini` exists it will be added to
the configuration chain.
-
Parameter names and values
---------------------------
+==========================
All parameter names are *case-sensitive*. Every parameter takes a value of one
-of five types: `boolean`, `integer`, `string`, `tuple`_ and `proplist`_. Boolean
-values can be written as ``true`` or ``false``.
+of five types: `boolean`, `integer`, `string`, `tuple`_ and `proplist`_.
+Boolean values can be written as ``true`` or ``false``.
Parameters with value type of `tuple` or `proplist` are following the Erlang
requirement for style and naming.
@@ -105,9 +97,8 @@ requirement for style and naming.
.. _proplist: http://www.erlang.org/doc/man/proplists.html
.. _tuple: http://www.erlang.org/doc/reference_manual/data_types.html#id66049
-
Setting parameters via the configuration file
----------------------------------------------
+=============================================
The common way to set some parameters is to edit the `local.ini` file which is
mostly located in the `etc/couchdb` directory relative your installation path
@@ -115,9 +106,9 @@ root.
For example::
- ; This is a comment
- [section]
- param = value ; inline comments are allowed
+ ; This is a comment
+ [section]
+ param = value ; inline comments are allowed
Each configuration file line may contains `section` definition, `parameter`
specification, empty (space and newline characters only) or `commented` line.
@@ -133,16 +124,15 @@ right one. The leading and following whitespace for ``=`` is an optional to
improve configuration readability.
.. note::
- In case when you'd like to remove some parameter from the `default.ini`
- without modifying that file, you may override in `local.ini`, but
- without any value::
+ In case when you'd like to remove some parameter from the `default.ini`
+ without modifying that file, you may override in `local.ini`, but without
+ any value::
- [httpd_global_handlers]
- _all_dbs =
-
- This could be read as: "remove the `_all_dbs` parameter from
- the `httpd_global_handlers` section if it was ever set before".
+ [httpd_global_handlers]
+ _all_dbs =
+ This could be read as: "remove the `_all_dbs` parameter from the
+ `httpd_global_handlers` section if it was ever set before".
The semicolon (``;``) signs about `commentary` start: everything after this
character is counted as commentary and doesn't process by CouchDB.
@@ -150,25 +140,24 @@ character is counted as commentary and doesn't process by CouchDB.
After editing of configuration file CouchDB server instance should be restarted
to apply these changes.
-
Setting parameters via the HTTP API
------------------------------------
+===================================
Alternatively, configuration parameters could be set via the
:ref:`HTTP API <api/config>`. This API allows to change CouchDB configuration
on-the-fly without requiring a server restart::
- curl -X PUT http://localhost:5984/_config/uuids/algorithm -d '"random"'
+ curl -X PUT http://localhost:5984/_config/uuids/algorithm -d '"random"'
In the response the old parameter's value returns::
- "sequential"
+ "sequential"
You should be careful with changing configuration via the HTTP API since it's
easy to make CouchDB unavailable. For instance, if you'd like to change the
:option:`httpd/bind_address` for a new one::
- curl -X PUT http://localhost:5984/_config/httpd/bind_address -d '"10.10.0.128"'
+ curl -X PUT http://localhost:5984/_config/httpd/bind_address -d '"10.10.0.128"'
However, if you make a typo, or the specified IP address is not available
from your network, CouchDB will be unavailable for you in both cases and
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/71a4fc90/src/config/logging.rst
----------------------------------------------------------------------
diff --git a/src/config/logging.rst b/src/config/logging.rst
index 086749f..7cfd56b 100644
--- a/src/config/logging.rst
+++ b/src/config/logging.rst
@@ -11,7 +11,6 @@
.. the License.
.. default-domain:: config
-
.. highlight:: ini
=======
@@ -25,52 +24,49 @@ Logging options
.. config:section:: log :: Logging options
- CouchDB logging configuration.
-
- .. config:option:: file :: Logging file path
-
- Specifies the location of file for logging output::
-
- [log]
- file = /var/log/couchdb/couch.log
+ CouchDB logging configuration.
- This path should be readable and writable for user that runs CouchDB service
- (`couchdb` by default).
+ .. config:option:: file :: Logging file path
+ Specifies the location of file for logging output::
- .. config:option:: level :: Logging verbose level
+ [log]
+ file = /var/log/couchdb/couch.log
- .. versionchanged:: 1.3: Added ``warning`` level.
+ This path should be readable and writable for user that runs CouchDB
+ service (`couchdb` by default).
- Logging level defines how verbose and detailed logging will be::
+ .. config:option:: level :: Logging verbose level
- [log]
- level = info
+ .. versionchanged:: 1.3: Added ``warning`` level.
- Available levels:
+ Logging level defines how verbose and detailed logging will be::
- - ``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.
+ [log]
+ level = info
+ Available levels:
- .. config:option:: include_sasl
+ - ``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.
- Includes `SASL`_ information in logs::
+ .. config:option:: include_sasl
- [log]
- include_sasl = true
+ Includes `SASL`_ information in logs::
- .. _SASL: http://www.erlang.org/doc/apps/sasl/
+ [log]
+ include_sasl = true
+ .. _SASL: http://www.erlang.org/doc/apps/sasl/
.. _config/log_level_by_module:
@@ -79,16 +75,16 @@ Per module logging
.. config:section:: log_level_by_module :: Per module logging
- .. versionadded:: 1.3
+ .. versionadded:: 1.3
- In this section you can specify :option:`log level <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-documentation/blob/71a4fc90/src/config/misc.rst
----------------------------------------------------------------------
diff --git a/src/config/misc.rst b/src/config/misc.rst
index d5c4fce..6b9f134 100644
--- a/src/config/misc.rst
+++ b/src/config/misc.rst
@@ -11,7 +11,6 @@
.. the License.
.. default-domain:: config
-
.. highlight:: ini
========================
@@ -25,26 +24,23 @@ Configuration of Attachment Storage
.. 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:option:: compression_level
- [attachments]
- compression_level = 8
+ Defines zlib compression level for the attachments from ``1`` (lowest,
+ fastest) to ``9`` (highest, slowest). A value of ``0`` disables
+ compression::
+ [attachments]
+ compression_level = 8
- .. config:option:: compressible_types
+ .. 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
+ 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:
@@ -53,23 +49,20 @@ Statistic Calculation
.. config:section:: stats :: Statistic Calculation
+ .. config:option:: rate
- .. config:option:: rate
-
- Rate of statistics gathering in milliseconds::
-
- [stats]
- rate = 1000
+ Rate of statistics gathering in milliseconds::
+ [stats]
+ rate = 1000
- .. config:option:: samples
+ .. 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]
+ Samples are used to track the mean and standard value deviation within
+ specified intervals (in seconds)::
+ [stats]
+ samples = [0, 60, 300, 900]
.. _config/uuids:
@@ -78,142 +71,137 @@ 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:option:: max_count :: Per-Request UUID Limit
-
- .. versionadded:: 1.5.1
-
- No more than this number of UUIDs will be sent in a single request. If
- more UUIDs are requested, an HTTP error response will be thrown.
-
- ::
-
- [uuid]
- max_count = 1000
-
+ .. 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:option:: max_count :: Per-Request UUID Limit
+
+ .. versionadded:: 1.5.1
+
+ No more than this number of UUIDs will be sent in a single request. If
+ more UUIDs are requested, an HTTP error response will be thrown. ::
+
+ [uuid]
+ max_count = 1000
.. _config/vendor:
@@ -222,16 +210,14 @@ Vendor information
.. config:section:: vendor :: Vendor information
- .. versionadded:: 1.3
-
- CouchDB distributors have the option of customizing CouchDB's welcome
- message. This is returned when requesting ``GET /``.
+ .. versionadded:: 1.3
- ::
+ 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
.. _config/csp:
@@ -240,19 +226,18 @@ Content-Security-Policy
.. config:section:: csp :: Content-Security-Policy
- Experimental support of CSP Headers for ``/_utils`` (Fauxton).
-
- .. config:option:: enable
+ Experimental support of CSP Headers for ``/_utils`` (Fauxton).
- Enable the sending of the Header ``Content-Security-Policy``::
+ .. config:option:: enable
- [csp]
- enable = true
+ Enable the sending of the Header ``Content-Security-Policy``::
+ [csp]
+ enable = true
- .. config:option:: header_value
+ .. config:option:: header_value
- You can change the default value for the Header which is sent::
+ You can change the default value for the Header which is sent::
- [csp]
- header_value = default-src 'self'; img-src *; font-src *;
+ [csp]
+ header_value = default-src 'self'; img-src *; font-src *;
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/71a4fc90/src/config/proxying.rst
----------------------------------------------------------------------
diff --git a/src/config/proxying.rst b/src/config/proxying.rst
index 863311e..1e19bf9 100644
--- a/src/config/proxying.rst
+++ b/src/config/proxying.rst
@@ -11,7 +11,6 @@
.. the License.
.. highlight:: ini
-
.. _config/proxy:
======================
@@ -24,34 +23,31 @@ Proxying Configuration
CouchDB As Proxy
================
-The HTTP proxy feature makes it easy to map and redirect different
-content through your CouchDB URL. The proxy works by mapping a pathname
-and passing all content after that prefix through to the configured
-proxy address.
+The HTTP proxy feature makes it easy to map and redirect different content
+through your CouchDB URL. The proxy works by mapping a pathname and passing all
+content after that prefix through to the configured proxy address.
Configuration of the proxy redirect is handled through the
``[httpd_global_handlers]`` section of the CouchDB configuration file
(typically ``local.ini``). The format is::
- [httpd_global_handlers]
- PREFIX = {couch_httpd_proxy, handle_proxy_req, <<"DESTINATION">>}
-
+ [httpd_global_handlers]
+ PREFIX = {couch_httpd_proxy, handle_proxy_req, <<"DESTINATION">>}
Where:
-- ``PREFIX``
+- ``PREFIX``
- Is the string that will be matched. The string can be any valid
- qualifier, although to ensure that existing database names are not
- overridden by a proxy configuration, you can use an underscore
- prefix.
+ Is the string that will be matched. The string can be any valid qualifier,
+ although to ensure that existing database names are not overridden by a proxy
+ configuration, you can use an underscore prefix.
-- ``DESTINATION``
+- ``DESTINATION``
- The fully-qualified URL to which the request should be sent. The
- destination must include the ``http`` prefix. The content is used
- verbatim in the original request, so you can also forward to servers
- on different ports and to specific paths on the target host.
+ The fully-qualified URL to which the request should be sent. The destination
+ must include the ``http`` prefix. The content is used verbatim in the
+ original request, so you can also forward to servers on different ports and
+ to specific paths on the target host.
The proxy process then translates requests of the form:
@@ -66,15 +62,15 @@ To:
DESTINATION/path
.. note::
- Everything after ``PREFIX`` including the required forward slash
- will be appended to the ``DESTINATION``.
+ Everything after ``PREFIX`` including the required forward slash will be
+ appended to the ``DESTINATION``.
The response is then communicated back to the original client.
For example, the following configuration::
- [httpd_global_handlers]
- _google = {couch_httpd_proxy, handle_proxy_req, <<"http://www.google.com">>}
+ [httpd_global_handlers]
+ _google = {couch_httpd_proxy, handle_proxy_req, <<"http://www.google.com">>}
Would forward all requests for ``http://couchdb:5984/_google`` to the
Google website.
@@ -82,17 +78,17 @@ Google website.
The service can also be used to forward to related CouchDB services,
such as `Lucene`::
- [httpd_global_handlers]
- _fti = {couch_httpd_proxy, handle_proxy_req, <<"http://127.0.0.1:5985">>}
+ [httpd_global_handlers]
+ _fti = {couch_httpd_proxy, handle_proxy_req, <<"http://127.0.0.1:5985">>}
.. note::
- The proxy service is basic. If the request is not identified by the
- ``DESTINATION``, or the remainder of the ``PATH`` specification is
- incomplete, the original request URL is interpreted as if the
- ``PREFIX`` component of that URL does not exist.
-
- For example, requesting ``http://couchdb:5984/_intranet/media`` when
- ``/media`` on the proxy destination does not exist, will cause the
- request URL to be interpreted as ``http://couchdb:5984/media``. Care
- should be taken to ensure that both requested URLs and destination
- URLs are able to cope.
+ The proxy service is basic. If the request is not identified by the
+ ``DESTINATION``, or the remainder of the ``PATH`` specification is
+ incomplete, the original request URL is interpreted as if the
+ ``PREFIX`` component of that URL does not exist.
+
+ For example, requesting ``http://couchdb:5984/_intranet/media`` when
+ ``/media`` on the proxy destination does not exist, will cause the request
+ URL to be interpreted as ``http://couchdb:5984/media``. Care should be
+ taken to ensure that both requested URLs and destination URLs are able to
+ cope.
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/71a4fc90/src/config/query-servers.rst
----------------------------------------------------------------------
diff --git a/src/config/query-servers.rst b/src/config/query-servers.rst
index 88fab82..6eee3e9 100644
--- a/src/config/query-servers.rst
+++ b/src/config/query-servers.rst
@@ -23,50 +23,49 @@ Query Servers Definition
.. config:section:: query_servers :: Query Servers Definition
- .. versionchanged:: 1.2: Added CoffeeScript query server
+ .. versionchanged:: 1.2: Added CoffeeScript query server
- 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.
+ 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.
- The external query server may be defined in configuration file following next
- pattern::
+ The external query server may be defined in configuration file following
+ next pattern::
- [query_servers]
- LANGUAGE = PATH ARGS
+ [query_servers]
+ LANGUAGE = PATH ARGS
- Where:
+ Where:
- - ``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 which query server processes the functions.
+ - ``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 which query server processes the functions.
- Note, that you may setup multiple query servers for the same programming
- language, but you have to name them different (like `python-dev` etc.).
+ Note, that you may setup multiple query servers for the same programming
+ language, but you have to name them different (like `python-dev` etc.).
- - ``PATH``: is a system path to the executable binary program that runs the
- query server.
+ - ``PATH``: is a system path to the executable binary program that runs the
+ query server.
- - ``ARGS``: optionally, you may specify additional command line arguments for
- the executable ``PATH``.
+ - ``ARGS``: optionally, you may specify additional command line arguments
+ for the executable ``PATH``.
- The default query server is written in :ref:`JavaScript <query-server/js>`,
- running via `Mozilla SpiderMonkey`_::
+ 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
+ [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
- .. _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.
-
+ .. 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:
@@ -75,38 +74,36 @@ Query Servers Configuration
.. config:section:: query_server_config :: Query Servers Configuration
+ .. config:option:: commit_freq :: View index commit delay
- .. 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``::
-
- [query_server_config]
- commit_freq = 5
+ 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:: os_process_limit :: Query Server operation timeout
+ .. config:option:: os_process_limit :: Query Server operation timeout
- Amount of time in seconds that the Query Server may process CouchDB command::
+ Amount of time in seconds that the Query Server may process CouchDB
+ command::
- [query_server_config]
- os_process_limit = 10
+ [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.
+ 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:option:: 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
-
- Normally, you don't have to disable (by setting ``false`` value) this option
- since main propose of `reduce` functions is to *reduce* the input.
+ [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.
.. _config/native_query_servers:
@@ -115,47 +112,46 @@ Native Erlang Query Server
.. config:section:: native_query_servers :: Native Erlang Query Server
- .. warning::
-
- Due to security restrictions, the Erlang query server is disabled by
- default.
+ .. warning::
+ 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.