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 2014/10/16 11:09:22 UTC
[10/14] Documentation was moved to couchdb-documentation repository
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/api/server/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/server/common.rst b/share/doc/src/api/server/common.rst
deleted file mode 100644
index 6327dc0..0000000
--- a/share/doc/src/api/server/common.rst
+++ /dev/null
@@ -1,1016 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-
-.. _api/server/root:
-
-``/``
-=====
-
-.. http:get:: /
- :synopsis: Returns the welcome message and version information
-
- Accessing the root of a CouchDB instance returns meta information about
- the instance. The response is a JSON structure containing information
- about the server, including a welcome message and the version of the
- server.
-
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :code 200: Request completed successfully
-
- **Request**:
-
- .. code-block:: http
-
- GET / HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 179
- Content-Type: application/json
- Date: Sat, 10 Aug 2013 06:33:33 GMT
- Server: CouchDB (Erlang/OTP)
-
- {
- "couchdb": "Welcome",
- "uuid": "85fb71bf700c17267fef77535820e371",
- "vendor": {
- "name": "The Apache Software Foundation",
- "version": "1.3.1"
- },
- "version": "1.3.1"
- }
-
-
-.. _api/server/active_tasks:
-
-``/_active_tasks``
-==================
-
-.. http:get:: /_active_tasks
- :synopsis: Obtains a list of the tasks running in the server
-
- List of running tasks, including the task type, name, status
- and process ID. The result is a JSON array of the currently running tasks,
- with each task being described with a single object. Depending on operation
- type set of response object fields might be different.
-
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>json number changes_done: Processed changes
- :>json string database: Source database
- :>json string pid: Process ID
- :>json number progress: Current percentage progress
- :>json number started_on: Task start time as unix timestamp
- :>json string status: Task status message
- :>json string task: Task name
- :>json number total_changes: Total changes to process
- :>json string type: Operation Type
- :>json number updated_on: Unix timestamp of last operation update
- :code 200: Request completed successfully
- :code 401: CouchDB Server Administrator privileges required
-
- **Request**:
-
- .. code-block:: http
-
- GET /_active_tasks HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 1690
- Content-Type: application/json
- Date: Sat, 10 Aug 2013 06:37:31 GMT
- Server: CouchDB (Erlang/OTP)
-
- [
- {
- "changes_done": 64438,
- "database": "mailbox",
- "pid": "<0.12986.1>",
- "progress": 84,
- "started_on": 1376116576,
- "total_changes": 76215,
- "type": "database_compaction",
- "updated_on": 1376116619
- },
- {
- "changes_done": 14443,
- "database": "mailbox",
- "design_document": "c9753817b3ba7c674d92361f24f59b9f",
- "pid": "<0.10461.3>",
- "progress": 18,
- "started_on": 1376116621,
- "total_changes": 76215,
- "type": "indexer",
- "updated_on": 1376116650
- },
- {
- "changes_done": 5454,
- "database": "mailbox",
- "design_document": "_design/meta",
- "pid": "<0.6838.4>",
- "progress": 7,
- "started_on": 1376116632,
- "total_changes": 76215,
- "type": "indexer",
- "updated_on": 1376116651
- },
- {
- "checkpointed_source_seq": 68585,
- "continuous": false,
- "doc_id": null,
- "doc_write_failures": 0,
- "docs_read": 4524,
- "docs_written": 4524,
- "missing_revisions_found": 4524,
- "pid": "<0.1538.5>",
- "progress": 44,
- "replication_id": "9bc1727d74d49d9e157e260bb8bbd1d5",
- "revisions_checked": 4524,
- "source": "mailbox",
- "source_seq": 154419,
- "started_on": 1376116644,
- "target": "http://mailsrv:5984/mailbox",
- "type": "replication",
- "updated_on": 1376116651
- }
- ]
-
-
-.. _api/server/all_dbs:
-
-``/_all_dbs``
-=============
-
-.. http:get:: /_all_dbs
- :synopsis: Returns a list of all the databases
-
- Returns a list of all the databases in the CouchDB instance.
-
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :code 200: Request completed successfully
-
- **Request**:
-
- .. code-block:: http
-
- GET /_all_dbs HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 52
- Content-Type: application/json
- Date: Sat, 10 Aug 2013 06:57:48 GMT
- Server: CouchDB (Erlang/OTP)
-
- [
- "_users",
- "contacts",
- "docs",
- "invoices",
- "locations"
- ]
-
-
-.. _api/server/db_updates:
-
-``/_db_updates``
-================
-
-.. versionadded:: 1.4
-
-.. http:get:: /_db_updates
- :synopsis: Return the server changes of databases
-
- Returns a list of all database events in the CouchDB instance.
-
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :query string feed: - **longpoll**: Closes the connection after the first event.
- - **continuous**: Send a line of JSON per event. Keeps the socket open
- until ``timeout``.
- - **eventsource**: Like, ``continuous``, but sends the events in
- `EventSource <http://dev.w3.org/html5/eventsource/>`_ format.
- :query number timeout: Number of seconds until CouchDB closes the connection.
- Default is ``60``.
- :query boolean heartbeat: Whether CouchDB will send a newline character
- (``\n``) on ``timeout``. Default is ``true``.
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>header Transfer-Encoding: ``chunked``
- :>json string db_name: Database name
- :>json boolean ok: Event operation status
- :>json string type: A database event is one of ``created``, ``updated``,
- ``deleted``
- :code 200: Request completed successfully
- :code 401: CouchDB Server Administrator privileges required
-
- **Request**:
-
- .. code-block:: http
-
- GET /_db_updates HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Type: application/json
- Date: Sat, 10 Aug 2013 07:02:41 GMT
- Server: CouchDB (Erlang/OTP)
- Transfer-Encoding: chunked
-
- {
- "db_name": "mailbox",
- "ok": true,
- "type": "created"
- }
-
-
-.. _api/server/log:
-
-``/_log``
-=========
-
-.. http:get:: /_log
- :synopsis: Returns the server log file
-
- Gets the CouchDB log, equivalent to accessing the local log file of the
- corresponding CouchDB instance.
-
- :<header Accept: - :mimetype:`text/plain`
- :query number bytes: Bytes to be returned. Default is ``1000``.
- :query number offset: Offset in bytes where the log tail should be started.
- Default is ``0``.
- :>header Content-Type: :mimetype:`text/plain; charset=utf-8`
- :>header Transfer-Encoding: ``chunked``
- :code 200: Request completed successfully
- :code 401: CouchDB Server Administrator privileges required
-
- **Request**:
-
- .. code-block:: http
-
- GET /_log HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- **Response**:
-
- .. code-block:: text
-
- [Wed, 27 Oct 2010 10:49:42 GMT] [info] [<0.23338.2>] 192.168.0.2 - - 'PUT' /authdb 401
- [Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.23428.2>] 192.168.0.116 - - 'GET' /recipes/FishStew 200
- [Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.23428.2>] 192.168.0.116 - - 'GET' /_session 200
- [Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.24199.2>] 192.168.0.116 - - 'GET' / 200
- [Wed, 27 Oct 2010 13:03:38 GMT] [info] [<0.24207.2>] 192.168.0.116 - - 'GET' /_log?offset=5 200
-
-If you want to pick out specific parts of the log information you can
-use the ``bytes`` argument, which specifies the number of bytes to be
-returned, and ``offset``, which specifies where the reading of the log
-should start, counted back from the end. For example, if you use the
-following request:
-
-.. code-block:: http
-
- GET /_log?bytes=500&offset=2000
-
-Reading of the log will start at 2000 bytes from the end of the log, and
-500 bytes will be shown.
-
-**How bytes/offset works?**
-
-CouchDB reads specified amount of ``bytes`` from the end of log file,
-jumping to ``offset`` bytes towards the beginning of the file first:
-
-.. code-block:: text
-
- Log File FilePos
- ----------
- | | 10
- | | 20
- | | 30
- | | 40
- | | 50
- | | 60
- | | 70 -- Bytes = 20 --
- | | 80 | Chunk
- | | 90 -- Offset = 10 --
- |__________| 100
-
-
-
-.. _api/server/replicate:
-
-``/_replicate``
-===============
-
-.. http:post:: /_replicate
- :synopsis: Starts or cancels the replication
-
- Request, configure, or stop, a replication operation.
-
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :<header Content-Type: :mimetype:`application/json`
- :<json boolean cancel: Cancels the replication
- :<json boolean continuous: Configure the replication to be continuous
- :<json boolean create_target: Creates the target database.
- Required administrator's privileges on target server.
- :<json array doc_ids: Array of document IDs to be synchronized
- :<json string proxy: Address of a proxy server through which replication
- should occur (protocol can be "http" or "socks5")
- :<json string source: Source database name or URL
- :<json string target: Target database name or URL
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>json array history: Replication history (see below)
- :>json boolean ok: Replication status
- :>json number replication_id_version: Replication protocol version
- :>json string session_id: Unique session ID
- :>json number source_last_seq: Last sequence number read from source database
- :code 200: Replication request successfully completed
- :code 202: Continuous replication request has been accepted
- :code 400: Invalid JSON data
- :code 401: CouchDB Server Administrator privileges required
- :code 404: Either the source or target DB is not found or attempt to
- cancel unknown replication task
- :code 500: JSON specification was invalid
-
- The specification of the replication request is controlled through the
- JSON content of the request. The JSON should be an object with the
- fields defining the source, target and other options.
-
- The `Replication history` is an array of objects with following structure:
-
- :json number doc_write_failures: Number of document write failures
- :json number docs_read: Number of documents read
- :json number docs_written: Number of documents written to target
- :json number end_last_seq: Last sequence number in changes stream
- :json string end_time: Date/Time replication operation completed in
- :rfc:`2822` format
- :json number missing_checked: Number of missing documents checked
- :json number missing_found: Number of missing documents found
- :json number recorded_seq: Last recorded sequence number
- :json string session_id: Session ID for this replication operation
- :json number start_last_seq: First sequence number in changes stream
- :json string start_time: Date/Time replication operation started in
- :rfc:`2822` format
-
- **Request**
-
- .. code-block:: http
-
- POST /_replicate HTTP/1.1
- Accept: application/json
- Content-Length: 36
- Content-Type: application/json
- Host: localhost:5984
-
- {
- "source": "db_a",
- "target": "db_b"
- }
-
- **Response**
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 692
- Content-Type: application/json
- Date: Sun, 11 Aug 2013 20:38:50 GMT
- Server: CouchDB (Erlang/OTP)
-
- {
- "history": [
- {
- "doc_write_failures": 0,
- "docs_read": 10,
- "docs_written": 10,
- "end_last_seq": 28,
- "end_time": "Sun, 11 Aug 2013 20:38:50 GMT",
- "missing_checked": 10,
- "missing_found": 10,
- "recorded_seq": 28,
- "session_id": "142a35854a08e205c47174d91b1f9628",
- "start_last_seq": 1,
- "start_time": "Sun, 11 Aug 2013 20:38:50 GMT"
- },
- {
- "doc_write_failures": 0,
- "docs_read": 1,
- "docs_written": 1,
- "end_last_seq": 1,
- "end_time": "Sat, 10 Aug 2013 15:41:54 GMT",
- "missing_checked": 1,
- "missing_found": 1,
- "recorded_seq": 1,
- "session_id": "6314f35c51de3ac408af79d6ee0c1a09",
- "start_last_seq": 0,
- "start_time": "Sat, 10 Aug 2013 15:41:54 GMT"
- }
- ],
- "ok": true,
- "replication_id_version": 3,
- "session_id": "142a35854a08e205c47174d91b1f9628",
- "source_last_seq": 28
- }
-
-
-Replication Operation
----------------------
-
-The aim of the replication is that at the end of the process, all active
-documents on the source database are also in the destination database
-and all documents that were deleted in the source databases are also
-deleted (if they exist) on the destination database.
-
-Replication can be described as either push or pull replication:
-
-- *Pull replication* is where the ``source`` is the remote CouchDB
- instance, and the ``target`` is the local database.
-
- Pull replication is the most useful solution to use if your source
- database has a permanent IP address, and your destination (local)
- database may have a dynamically assigned IP address (for example,
- through DHCP). This is particularly important if you are replicating
- to a mobile or other device from a central server.
-
-- *Push replication* is where the ``source`` is a local database, and
- ``target`` is a remote database.
-
-Specifying the Source and Target Database
------------------------------------------
-
-You must use the URL specification of the CouchDB database if you want
-to perform replication in either of the following two situations:
-
-- Replication with a remote database (i.e. another instance of CouchDB
- on the same host, or a different host)
-
-- Replication with a database that requires authentication
-
-For example, to request replication between a database local to the
-CouchDB instance to which you send the request, and a remote database
-you might use the following request:
-
-.. code-block:: http
-
- POST http://couchdb:5984/_replicate
- Content-Type: application/json
- Accept: application/json
-
- {
- "source" : "recipes",
- "target" : "http://coucdb-remote:5984/recipes",
- }
-
-
-In all cases, the requested databases in the ``source`` and ``target``
-specification must exist. If they do not, an error will be returned
-within the JSON object:
-
-.. code-block:: javascript
-
- {
- "error" : "db_not_found"
- "reason" : "could not open http://couchdb-remote:5984/ol1ka/",
- }
-
-You can create the target database (providing your user credentials
-allow it) by adding the ``create_target`` field to the request object:
-
-.. code-block:: http
-
- POST http://couchdb:5984/_replicate
- Content-Type: application/json
- Accept: application/json
-
- {
- "create_target" : true
- "source" : "recipes",
- "target" : "http://couchdb-remote:5984/recipes",
- }
-
-The ``create_target`` field is not destructive. If the database already
-exists, the replication proceeds as normal.
-
-Single Replication
-------------------
-
-You can request replication of a database so that the two databases can
-be synchronized. By default, the replication process occurs one time and
-synchronizes the two databases together. For example, you can request a
-single synchronization between two databases by supplying the ``source``
-and ``target`` fields within the request JSON content.
-
-.. code-block:: http
-
- POST http://couchdb:5984/_replicate
- Accept: application/json
- Content-Type: application/json
-
- {
- "source" : "recipes",
- "target" : "recipes-snapshot",
- }
-
-In the above example, the databases ``recipes`` and ``recipes-snapshot``
-will be synchronized. These databases are local to the CouchDB instance
-where the request was made. The response will be a JSON structure
-containing the success (or failure) of the synchronization process, and
-statistics about the process:
-
-.. code-block:: javascript
-
- {
- "ok" : true,
- "history" : [
- {
- "docs_read" : 1000,
- "session_id" : "52c2370f5027043d286daca4de247db0",
- "recorded_seq" : 1000,
- "end_last_seq" : 1000,
- "doc_write_failures" : 0,
- "start_time" : "Thu, 28 Oct 2010 10:24:13 GMT",
- "start_last_seq" : 0,
- "end_time" : "Thu, 28 Oct 2010 10:24:14 GMT",
- "missing_checked" : 0,
- "docs_written" : 1000,
- "missing_found" : 1000
- }
- ],
- "session_id" : "52c2370f5027043d286daca4de247db0",
- "source_last_seq" : 1000
- }
-
-Continuous Replication
-----------------------
-
-Synchronization of a database with the previously noted methods happens
-only once, at the time the replicate request is made. To have the target
-database permanently replicated from the source, you must set the
-``continuous`` field of the JSON object within the request to true.
-
-With continuous replication changes in the source database are
-replicated to the target database in perpetuity until you specifically
-request that replication ceases.
-
-.. code-block:: http
-
- POST http://couchdb:5984/_replicate
- Accept: application/json
- Content-Type: application/json
-
- {
- "continuous" : true
- "source" : "recipes",
- "target" : "http://couchdb-remote:5984/recipes",
- }
-
-Changes will be replicated between the two databases as long as a
-network connection is available between the two instances.
-
-.. note::
- Two keep two databases synchronized with each other, you need to set
- replication in both directions; that is, you must replicate from
- ``source`` to ``target``, and separately from ``target`` to
- ``source``.
-
-Canceling Continuous Replication
---------------------------------
-
-You can cancel continuous replication by adding the ``cancel`` field to
-the JSON request object and setting the value to true. Note that the
-structure of the request must be identical to the original for the
-cancellation request to be honoured. For example, if you requested
-continuous replication, the cancellation request must also contain the
-``continuous`` field.
-
-For example, the replication request:
-
-.. code-block:: http
-
- POST http://couchdb:5984/_replicate
- Content-Type: application/json
- Accept: application/json
-
- {
- "source" : "recipes",
- "target" : "http://couchdb-remote:5984/recipes",
- "create_target" : true,
- "continuous" : true
- }
-
-Must be canceled using the request:
-
-.. code-block:: http
-
- POST http://couchdb:5984/_replicate
- Accept: application/json
- Content-Type: application/json
-
- {
- "cancel" : true,
- "continuous" : true
- "create_target" : true,
- "source" : "recipes",
- "target" : "http://couchdb-remote:5984/recipes",
- }
-
-Requesting cancellation of a replication that does not exist results in
-a 404 error.
-
-
-.. _api/server/restart:
-
-``/_restart``
-=============
-
-.. http:post:: /_restart
- :synopsis: Restarts the server
-
- Restarts the CouchDB instance. You must be authenticated as a user with
- administration privileges for this to work.
-
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :<header Content-Type: :mimetype:`application/json`
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :code 202: Server goes to restart (there is no guarantee that it will be
- alive after)
- :code 401: CouchDB Server Administrator privileges required
- :code 415: Bad request`s :header:`Content-Type`
-
- **Request**:
-
- .. code-block:: http
-
- POST /_restart HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 202 Accepted
- Cache-Control: must-revalidate
- Content-Length: 12
- Content-Type: application/json
- Date: Sat, 10 Aug 2013 11:33:50 GMT
- Server: CouchDB (Erlang/OTP)
-
- {
- "ok": true
- }
-
-
-.. _api/server/stats:
-
-``/_stats``
-===========
-
-.. http:get:: /_stats
- :synopsis: Returns server statistics
-
- The ``_stats`` resource returns a JSON object containing the statistics
- for the running server. The object is structured with top-level sections
- collating the statistics for a range of entries, with each individual
- statistic being easily identified, and the content of each statistic is
- self-describing
-
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :code 200: Request completed successfully
-
- **Request**:
-
- .. code-block:: http
-
- GET /_stats/couchdb/request_time HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 187
- Content-Type: application/json
- Date: Sat, 10 Aug 2013 11:41:11 GMT
- Server: CouchDB (Erlang/OTP)
-
- {
- "couchdb": {
- "request_time": {
- "current": 21.0,
- "description": "length of a request inside CouchDB without MochiWeb",
- "max": 19.0,
- "mean": 7.0,
- "min": 1.0,
- "stddev": 10.392,
- "sum": 21.0
- }
- }
- }
-
-
-The fields provide the current, minimum and maximum, and a collection of
-statistical means and quantities. The quantity in each case is not
-defined, but the descriptions below provide
-
-The statistics are divided into the following top-level sections:
-
-``couchdb``
------------
-
-Describes statistics specific to the internals of CouchDB
-
-+-------------------------+-------------------------------------------------------+----------------+
-| Statistic ID | Description | Unit |
-+=========================+=======================================================+================+
-| ``auth_cache_hits`` | Number of authentication cache hits | number |
-+-------------------------+-------------------------------------------------------+----------------+
-| ``auth_cache_misses`` | Number of authentication cache misses | number |
-+-------------------------+-------------------------------------------------------+----------------+
-| ``database_reads`` | Number of times a document was read from a database | number |
-+-------------------------+-------------------------------------------------------+----------------+
-| ``database_writes`` | Number of times a database was changed | number |
-+-------------------------+-------------------------------------------------------+----------------+
-| ``open_databases`` | Number of open databases | number |
-+-------------------------+-------------------------------------------------------+----------------+
-| ``open_os_files`` | Number of file descriptors CouchDB has open | number |
-+-------------------------+-------------------------------------------------------+----------------+
-| ``request_time`` | Length of a request inside CouchDB without MochiWeb | milliseconds |
-+-------------------------+-------------------------------------------------------+----------------+
-
-``httpd_request_methods``
--------------------------
-
-+----------------+----------------------------------+----------+
-| Statistic ID | Description | Unit |
-+================+==================================+==========+
-| ``COPY`` | Number of HTTP COPY requests | number |
-+----------------+----------------------------------+----------+
-| ``DELETE`` | Number of HTTP DELETE requests | number |
-+----------------+----------------------------------+----------+
-| ``GET`` | Number of HTTP GET requests | number |
-+----------------+----------------------------------+----------+
-| ``HEAD`` | Number of HTTP HEAD requests | number |
-+----------------+----------------------------------+----------+
-| ``POST`` | Number of HTTP POST requests | number |
-+----------------+----------------------------------+----------+
-| ``PUT`` | Number of HTTP PUT requests | number |
-+----------------+----------------------------------+----------+
-
-``httpd_status_codes``
-----------------------
-
-+----------------+------------------------------------------------------+----------+
-| Statistic ID | Description | Unit |
-+================+======================================================+==========+
-| ``200`` | Number of HTTP 200 OK responses | number |
-+----------------+------------------------------------------------------+----------+
-| ``201`` | Number of HTTP 201 Created responses | number |
-+----------------+------------------------------------------------------+----------+
-| ``202`` | Number of HTTP 202 Accepted responses | number |
-+----------------+------------------------------------------------------+----------+
-| ``301`` | Number of HTTP 301 Moved Permanently responses | number |
-+----------------+------------------------------------------------------+----------+
-| ``304`` | Number of HTTP 304 Not Modified responses | number |
-+----------------+------------------------------------------------------+----------+
-| ``400`` | Number of HTTP 400 Bad Request responses | number |
-+----------------+------------------------------------------------------+----------+
-| ``401`` | Number of HTTP 401 Unauthorized responses | number |
-+----------------+------------------------------------------------------+----------+
-| ``403`` | Number of HTTP 403 Forbidden responses | number |
-+----------------+------------------------------------------------------+----------+
-| ``404`` | Number of HTTP 404 Not Found responses | number |
-+----------------+------------------------------------------------------+----------+
-| ``405`` | Number of HTTP 405 Method Not Allowed responses | number |
-+----------------+------------------------------------------------------+----------+
-| ``409`` | Number of HTTP 409 Conflict responses | number |
-+----------------+------------------------------------------------------+----------+
-| ``412`` | Number of HTTP 412 Precondition Failed responses | number |
-+----------------+------------------------------------------------------+----------+
-| ``500`` | Number of HTTP 500 Internal Server Error responses | number |
-+----------------+------------------------------------------------------+----------+
-
-``httpd``
----------
-
-+----------------------------------+----------------------------------------------+----------+
-| Statistic ID | Description | Unit |
-+==================================+==============================================+==========+
-| ``bulk_requests`` | Number of bulk requests | number |
-+----------------------------------+----------------------------------------------+----------+
-| ``clients_requesting_changes`` | Number of clients for continuous _changes | number |
-+----------------------------------+----------------------------------------------+----------+
-| ``requests`` | Number of HTTP requests | number |
-+----------------------------------+----------------------------------------------+----------+
-| ``temporary_view_reads`` | Number of temporary view reads | number |
-+----------------------------------+----------------------------------------------+----------+
-| ``view_reads`` | Number of view reads | number |
-+----------------------------------+----------------------------------------------+----------+
-
-You can also access individual statistics by quoting the statistics
-sections and statistic ID as part of the URL path. For example, to get
-the ``request_time`` statistics, you can use:
-
-.. code-block:: http
-
- GET /_stats/couchdb/request_time
-
-This returns an entire statistics object, as with the full request, but
-containing only the request individual statistic. Hence, the returned
-structure is as follows:
-
-.. code-block:: javascript
-
- {
- "couchdb" : {
- "request_time" : {
- "stddev" : 7454.305,
- "min" : 1,
- "max" : 34185,
- "current" : 34697.803,
- "mean" : 1652.276,
- "sum" : 34697.803,
- "description" : "length of a request inside CouchDB without MochiWeb"
- }
- }
- }
-
-
-.. _api/server/utils:
-
-``/_utils``
-===========
-
-.. http:get:: /_utils
- :synopsis: Redirects to /_utils/
-
- Accesses the built-in Futon administration interface for CouchDB.
-
- :>header Location: New URI location
- :code 301: Redirects to :get:`/_utils/`
-
-.. http:get:: /_utils/
- :synopsis: CouchDB administration interface (Futon)
-
- :>header Content-Type: :mimetype:`text/html`
- :>header Last-Modified: Static files modification timestamp
- :code 200: Request completed successfully
-
-
-.. _api/server/uuids:
-
-``/_uuids``
-===========
-
-.. versionchanged:: 1.5.1
-
-.. http:get:: /_uuids
- :synopsis: Generates a list of UUIDs from the server
-
- Requests one or more Universally Unique Identifiers (UUIDs) from the
- CouchDB instance. The response is a JSON object providing a list of
- UUIDs.
-
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :query number count: Number of UUIDs to return. Default is ``1``.
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>header ETag: Response hash
- :code 200: Request completed successfully
- :code 403: Requested more UUIDs than is :config:option:`allowed
- <uuids/max_count>` to retrieve
-
- **Request**:
-
- .. code-block:: http
-
- GET /_uuids?count=10 HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Content-Length: 362
- Content-Type: application/json
- Date: Sat, 10 Aug 2013 11:46:25 GMT
- ETag: "DGRWWQFLUDWN5MRKSLKQ425XV"
- Expires: Fri, 01 Jan 1990 00:00:00 GMT
- Pragma: no-cache
- Server: CouchDB (Erlang/OTP)
-
- {
- "uuids": [
- "75480ca477454894678e22eec6002413",
- "75480ca477454894678e22eec600250b",
- "75480ca477454894678e22eec6002c41",
- "75480ca477454894678e22eec6003b90",
- "75480ca477454894678e22eec6003fca",
- "75480ca477454894678e22eec6004bef",
- "75480ca477454894678e22eec600528f",
- "75480ca477454894678e22eec6005e0b",
- "75480ca477454894678e22eec6006158",
- "75480ca477454894678e22eec6006161"
- ]
- }
-
-The UUID type is determined by the :config:option:`UUID algorithm
-<uuids/algorithm>` setting in the CouchDB configuration.
-
-The UUID type may be changed at any time through the
-:ref:`Configuration API <api/config/section/key>`. For example, the UUID type
-could be changed to ``random`` by sending this HTTP request:
-
-.. code-block:: http
-
- PUT http://couchdb:5984/_config/uuids/algorithm
- Content-Type: application/json
- Accept: */*
-
- "random"
-
-You can verify the change by obtaining a list of UUIDs:
-
-.. code-block:: javascript
-
- {
- "uuids" : [
- "031aad7b469956cf2826fcb2a9260492",
- "6ec875e15e6b385120938df18ee8e496",
- "cff9e881516483911aa2f0e98949092d",
- "b89d37509d39dd712546f9510d4a9271",
- "2e0dbf7f6c4ad716f21938a016e4e59f"
- ]
- }
-
-
-.. _api/server/favicon:
-
-``/favicon.ico``
-================
-
-.. http:get:: /favicon.ico
- :synopsis: Returns the site icon
-
- Binary content for the `favicon.ico` site icon.
-
- :>header Content-Type: :mimetype:`image/x-icon`
- :code 200: Request completed successfully
- :code 404: The requested content could not be found
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/api/server/configuration.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/server/configuration.rst b/share/doc/src/api/server/configuration.rst
deleted file mode 100644
index 5f53002..0000000
--- a/share/doc/src/api/server/configuration.rst
+++ /dev/null
@@ -1,336 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-.. _api/config:
-
-=============
-Configuration
-=============
-
-The CouchDB Server Configuration API provide an interface to query and update
-the various configuration values within a running CouchDB instance.
-
-``/_config``
-============
-
-.. http:get:: /_config
- :synopsis: Obtains a list of the entire server configuration
-
- Returns the entire CouchDB server configuration as a JSON structure. The
- structure is organized by different configuration sections, with
- individual values.
-
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :code 200: Request completed successfully
- :code 401: CouchDB Server Administrator privileges required
-
- **Request**
-
- .. code-block:: http
-
- GET /_config HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 4148
- Content-Type: application/json
- Date: Sat, 10 Aug 2013 12:01:42 GMT
- Server: CouchDB (Erlang/OTP)
-
- {
- "attachments": {
- "compressible_types": "text/*, application/javascript, application/json, application/xml",
- "compression_level": "8"
- },
- "couch_httpd_auth": {
- "auth_cache_size": "50",
- "authentication_db": "_users",
- "authentication_redirect": "/_utils/session.html",
- "require_valid_user": "false",
- "timeout": "600"
- },
- "couchdb": {
- "database_dir": "/var/lib/couchdb",
- "delayed_commits": "true",
- "max_attachment_chunk_size": "4294967296",
- "max_dbs_open": "100",
- "max_document_size": "4294967296",
- "os_process_timeout": "5000",
- "uri_file": "/var/lib/couchdb/couch.uri",
- "util_driver_dir": "/usr/lib64/couchdb/erlang/lib/couch-1.5.0/priv/lib",
- "view_index_dir": "/var/lib/couchdb"
- },
- "daemons": {
- "auth_cache": "{couch_auth_cache, start_link, []}",
- "db_update_notifier": "{couch_db_update_notifier_sup, start_link, []}",
- "external_manager": "{couch_external_manager, start_link, []}",
- "httpd": "{couch_httpd, start_link, []}",
- "query_servers": "{couch_query_servers, start_link, []}",
- "stats_aggregator": "{couch_stats_aggregator, start, []}",
- "stats_collector": "{couch_stats_collector, start, []}",
- "uuids": "{couch_uuids, start, []}",
- "view_manager": "{couch_view, start_link, []}"
- },
- "httpd": {
- "allow_jsonp": "false",
- "authentication_handlers": "{couch_httpd_oauth, oauth_authentication_handler}, {couch_httpd_auth, cookie_authentication_handler}, {couch_httpd_auth, default_authentication_handler}",
- "bind_address": "192.168.0.2",
- "default_handler": "{couch_httpd_db, handle_request}",
- "max_connections": "2048",
- "port": "5984",
- "secure_rewrites": "true",
- "vhost_global_handlers": "_utils, _uuids, _session, _oauth, _users"
- },
- "httpd_db_handlers": {
- "_changes": "{couch_httpd_db, handle_changes_req}",
- "_compact": "{couch_httpd_db, handle_compact_req}",
- "_design": "{couch_httpd_db, handle_design_req}",
- "_temp_view": "{couch_httpd_view, handle_temp_view_req}",
- "_view_cleanup": "{couch_httpd_db, handle_view_cleanup_req}"
- },
- "httpd_design_handlers": {
- "_info": "{couch_httpd_db, handle_design_info_req}",
- "_list": "{couch_httpd_show, handle_view_list_req}",
- "_rewrite": "{couch_httpd_rewrite, handle_rewrite_req}",
- "_show": "{couch_httpd_show, handle_doc_show_req}",
- "_update": "{couch_httpd_show, handle_doc_update_req}",
- "_view": "{couch_httpd_view, handle_view_req}"
- },
- "httpd_global_handlers": {
- "/": "{couch_httpd_misc_handlers, handle_welcome_req, <<\"Welcome\">>}",
- "_active_tasks": "{couch_httpd_misc_handlers, handle_task_status_req}",
- "_all_dbs": "{couch_httpd_misc_handlers, handle_all_dbs_req}",
- "_config": "{couch_httpd_misc_handlers, handle_config_req}",
- "_log": "{couch_httpd_misc_handlers, handle_log_req}",
- "_oauth": "{couch_httpd_oauth, handle_oauth_req}",
- "_replicate": "{couch_httpd_misc_handlers, handle_replicate_req}",
- "_restart": "{couch_httpd_misc_handlers, handle_restart_req}",
- "_session": "{couch_httpd_auth, handle_session_req}",
- "_stats": "{couch_httpd_stats_handlers, handle_stats_req}",
- "_utils": "{couch_httpd_misc_handlers, handle_utils_dir_req, \"/usr/share/couchdb/www\"}",
- "_uuids": "{couch_httpd_misc_handlers, handle_uuids_req}",
- "favicon.ico": "{couch_httpd_misc_handlers, handle_favicon_req, \"/usr/share/couchdb/www\"}"
- },
- "log": {
- "file": "/var/log/couchdb/couch.log",
- "include_sasl": "true",
- "level": "info"
- },
- "query_server_config": {
- "reduce_limit": "true"
- },
- "query_servers": {
- "javascript": "/usr/bin/couchjs /usr/share/couchdb/server/main.js"
- },
- "replicator": {
- "max_http_pipeline_size": "10",
- "max_http_sessions": "10"
- },
- "stats": {
- "rate": "1000",
- "samples": "[0, 60, 300, 900]"
- },
- "uuids": {
- "algorithm": "utc_random"
- }
- }
-
-
-.. _api/config/section:
-
-``/_config/section``
-====================
-
-.. http:get:: /_config/{section}
- :synopsis: Returns all the configuration values for the specified section
-
- Gets the configuration structure for a single section.
-
- :param section: Configuration section name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :code 200: Request completed successfully
- :code 401: CouchDB Server Administrator privileges required
-
- **Request**:
-
- .. code-block:: http
-
- GET /_config/httpd HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 444
- Content-Type: application/json
- Date: Sat, 10 Aug 2013 12:10:40 GMT
- Server: CouchDB (Erlang/OTP)
-
- {
- "allow_jsonp": "false",
- "authentication_handlers": "{couch_httpd_oauth, oauth_authentication_handler}, {couch_httpd_auth, cookie_authentication_handler}, {couch_httpd_auth, default_authentication_handler}",
- "bind_address": "127.0.0.1",
- "default_handler": "{couch_httpd_db, handle_request}",
- "enable_cors": "false",
- "log_max_chunk_size": "1000000",
- "port": "5984",
- "secure_rewrites": "true",
- "vhost_global_handlers": "_utils, _uuids, _session, _oauth, _users"
- }
-
-
-.. _api/config/section/key:
-
-``/_config/section/key``
-========================
-
-.. http:get:: /_config/{section}/{key}
- :synopsis: Returns a specific section/configuration value
-
- Gets a single configuration value from within a specific configuration
- section.
-
- :param section: Configuration section name
- :param key: Configuration option name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :code 200: Request completed successfully
- :code 401: CouchDB Server Administrator privileges required
-
- **Request**:
-
- .. code-block:: http
-
- GET /_config/log/level HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 8
- Content-Type: application/json
- Date: Sat, 10 Aug 2013 12:12:59 GMT
- Server: CouchDB (Erlang/OTP)
-
- "debug"
-
-
- .. note::
- The returned value will be the JSON of the value, which may be a
- string or numeric value, or an array or object. Some client
- environments may not parse simple strings or numeric values as valid JSON.
-
-
-.. http:put:: /_config/{section}/{key}
- :synopsis: Sets the specified configuration value
-
- Updates a configuration value. The new value should be supplied in the
- request body in the corresponding JSON format. If you are setting a string
- value, you must supply a valid JSON string. In response CouchDB sends old
- value for target section key.
-
- :param section: Configuration section name
- :param key: Configuration option name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :<header Content-Type: :mimetype:`application/json`
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :code 200: Request completed successfully
- :code 400: Invalid JSON request body
- :code 401: CouchDB Server Administrator privileges required
- :code 500: Error setting configuration
-
- **Request**:
-
- .. code-block:: http
-
- PUT /_config/log/level HTTP/1.1
- Accept: application/json
- Content-Length: 7
- Content-Type: application/json
- Host: localhost:5984
-
- "info"
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 8
- Content-Type: application/json
- Date: Sat, 10 Aug 2013 12:12:59 GMT
- Server: CouchDB (Erlang/OTP)
-
- "debug"
-
-
-.. http:delete:: /_config/{section}/{key}
- :synopsis: Removes the current setting
-
- Deletes a configuration value. The returned JSON will be the value of
- the configuration parameter before it was deleted.
-
- :param section: Configuration section name
- :param key: Configuration option name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :code 200: Request completed successfully
- :code 401: CouchDB Server Administrator privileges required
- :code 404: Specified configuration option not found
-
- **Request**:
-
- .. code-block:: http
-
- DELETE /_config/log/level HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 7
- Content-Type: application/json
- Date: Sat, 10 Aug 2013 12:29:03 GMT
- Server: CouchDB (Erlang/OTP)
-
- "info"
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/api/server/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/server/index.rst b/share/doc/src/api/server/index.rst
deleted file mode 100644
index c2e8d9a..0000000
--- a/share/doc/src/api/server/index.rst
+++ /dev/null
@@ -1,28 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-
-.. _api/server:
-
-======
-Server
-======
-
-The CouchDB server interface provides the basic interface to a
-CouchDB server for obtaining CouchDB information and getting and setting
-configuration information.
-
-.. toctree::
-
- common
- authn
- configuration
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/conf.py
----------------------------------------------------------------------
diff --git a/share/doc/src/conf.py b/share/doc/src/conf.py
deleted file mode 100644
index 03c5dd6..0000000
--- a/share/doc/src/conf.py
+++ /dev/null
@@ -1,161 +0,0 @@
-## Licensed under the Apache License, Version 2.0 (the "License"); you may not
-## use this file except in compliance with the License. You may obtain a copy of
-## the License at
-##
-## http://www.apache.org/licenses/LICENSE-2.0
-##
-## Unless required by applicable law or agreed to in writing, software
-## distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-## WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-## License for the specific language governing permissions and limitations under
-## the License.
-
-import datetime
-import os
-import re
-import sys
-
-sys.path.insert(0, os.path.abspath('../ext'))
-
-extensions = ["sphinx.ext.todo", "sphinx.ext.extlinks", 'github',
- 'httpdomain', 'configdomain']
-
-_info = {}
-_regex = re.compile('m4_define\(\[(.+)\],\s+\[(.+)\]\)')
-_acinclude_m4 = '../../../acinclude.m4'
-_acinclude_m4_in = '../../../acinclude.m4.in'
-if os.path.exists(_acinclude_m4):
- _source = _acinclude_m4
-elif os.path.exists(_acinclude_m4_in):
- _source = _acinclude_m4_in
-else:
- _source = None
-if _source is not None:
- _info = dict(_regex.findall(open(_source).read()))
-else:
- raise ValueError('''Project information source wasn't found. We're assume
-that it's located within "acinclude.m4" file at the root of the project, but
-looks like there is no such file there.''')
-
-source_suffix = ".rst"
-
-nitpicky = True
-
-version = '.'.join([
- _info['LOCAL_VERSION_MAJOR'],
- _info['LOCAL_VERSION_MINOR']
-])
-
-release = '.'.join([
- _info['LOCAL_VERSION_MAJOR'],
- _info['LOCAL_VERSION_MINOR'],
- _info['LOCAL_VERSION_REVISION']
-])
-
-if _info.get('LOCAL_VERSION_RELEASE') == '.%revision%':
- release += '-dev'
-elif _info.get('LOCAL_VERSION_RELEASE'):
- # jenkins hack, the release name is too long or uses
- # characters that cause pain down the road. Example:
- # 1.6.0+build.jenkins-ERLANG_VERSION=R14B04,label=Mac-OS-10-8-2-832-76-g2996574
- # which breaks the LaTeX PDF build. Let’s strip this
- # down to the git hash at the end.
- if 'jenkins' in _info['LOCAL_VERSION_RELEASE']:
- release += _info['LOCAL_VERSION_RELEASE'][-9:]
- else: # regular case
- release += _info['LOCAL_VERSION_STAGE'] + _info['LOCAL_VERSION_RELEASE']
-
-
-project = _info['LOCAL_PACKAGE_NAME']
-
-copyright = '%d, %s' % (
- datetime.datetime.now().year,
- _info['LOCAL_PACKAGE_AUTHOR_NAME']
-)
-
-highlight_language = "json"
-
-primary_domain = "http"
-
-pygments_style = "sphinx"
-
-html_theme = "couchdb"
-
-html_theme_path = ['../templates']
-
-templates_path = ["../templates"]
-
-html_static_path = ["../static"]
-
-html_title = ' '.join([
- project,
- version,
- 'Documentation'
-])
-
-html_style = "rtd.css"
-
-html_logo = "../images/logo.png"
-
-html_favicon = "../images/favicon.ico"
-
-html_use_index = False
-
-html_additional_pages = {
- 'download': 'pages/download.html',
- 'index': 'pages/index.html'
-}
-
-html_context = {
- "ga_code": "UA-658988-6"
-}
-
-html_sidebars = {
- "**": [
- "searchbox.html",
- "localtoc.html",
- "relations.html",
- "utilities.html",
- "help.html",
- "tracking.html",
- ]
-}
-
-text_newlines = "native"
-
-latex_documents = [(
- "contents",
- "CouchDB.tex",
- project,
- "",
- "manual",
- True
-)]
-
-latex_elements = {
- "papersize": "a4paper"
-}
-
-texinfo_documents = [(
- "contents",
- "CouchDB",
- project,
- "",
- "CouchDB",
- "The Apache CouchDB database",
- "Databases",
- True
-)]
-
-extlinks = {
- 'issue': ('%s-%%s' % _info['LOCAL_BUG_URI'], 'COUCHDB-'),
- 'commit': ('https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=commit;h=%s', '#')
-}
-
-github_project = 'apache/couchdb'
-
-html_context['git_branch'] = github_branch = 'master'
-
-github_docs_path = 'share/doc/src'
-
-del _info, _regex, _acinclude_m4, _acinclude_m4_in, _source
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/config/auth.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/auth.rst b/share/doc/src/config/auth.rst
deleted file mode 100644
index 8311140..0000000
--- a/share/doc/src/config/auth.rst
+++ /dev/null
@@ -1,384 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-.. default-domain:: config
-
-.. highlight:: ini
-
-================================
-Authentication and Authorization
-================================
-
-.. _config/admins:
-
-Server Administrators
-=====================
-
-.. config:section:: admins :: Server Administrators
-
- A default CouchDB install provides admin-level access to all connecting users.
- This configuration is known as `Admin Party`, and is not recommended for
- in-production usage. You can crash the party simply by creating the first
- admin account. CouchDB server administrators and passwords are not stored
- in the ``_users`` database, but in the ``local.ini`` file, which should be
- appropriately secured and readable only by system administrators::
-
- [admins]
- ;admin = mysecretpassword
- admin = -hashed-6d3c30241ba0aaa4e16c6ea99224f915687ed8cd,7f4a3e05e0cbc6f48a0035e3508eef90
- architect = -pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000
-
- Administrators can be added directly to the ``[admins]`` section, and when
- CouchDB is restarted, the passwords will be salted and encrypted. You may
- also use the HTTP interface to create administrator accounts; this way,
- you don't need to restart CouchDB, and there's no need to temporarily store
- or transmit passwords in plaintext. The HTTP ``_config/admins`` endpoint
- supports querying, deleting or creating new admin accounts:
-
- .. code-block:: http
-
- GET /_config/admins HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 196
- Content-Type: application/json
- Date: Fri, 30 Nov 2012 11:37:18 GMT
- Server: CouchDB (Erlang/OTP)
-
- .. code-block:: json
-
- {
- "admin": "-hashed-6d3c30241ba0aaa4e16c6ea99224f915687ed8cd,7f4a3e05e0cbc6f48a0035e3508eef90",
- "architect": "-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
- }
-
- If you already have a salted, encrypted password string (for example,
- from an old ``local.ini`` file, or from a different CouchDB server), then
- you can store the "raw" encrypted string, without having CouchDB doubly
- encrypt it.
-
- .. code-block:: http
-
- PUT /_config/admins/architect?raw=true HTTP/1.1
- Accept: application/json
- Content-Type: application/json
- Content-Length: 89
- Host: localhost:5984
-
- "-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 89
- Content-Type: application/json
- Date: Fri, 30 Nov 2012 11:39:18 GMT
- Server: CouchDB (Erlang/OTP)
-
- "-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
-
- Further details are available in `security`, including configuring the
- work factor for ``PBKDF2``, and the algorithm itself at
- `PBKDF2 (RFC-2898) <http://tools.ietf.org/html/rfc2898>`_.
-
- .. versionchanged:: 1.4 `PBKDF2` server-side hashed salted password support
- added, now as a synchronous call for the ``_config/admins`` API.
-
-
-.. _config/couch_httpd_auth:
-
-Authentication Configuration
-============================
-
-.. config:section:: couch_httpd_auth :: Authentication Configuration
-
-
- .. config:option:: allow_persistent_cookies :: Persistent cookies
-
- Makes cookies persistent if ``true``.
-
- ::
-
- [couch_httpd_auth]
- allow_persistent_cookies = false
-
-
- .. config:option:: auth_cache_size :: Authentication cache
-
- Number of :ref:`userctx_object` to cache in memory, to reduce disk lookups.
-
- ::
-
- [couch_httpd_auth]
- auth_cache_size = 50
-
-
- .. config:option:: authentication_db :: Users database
-
- Specifies the name of the system database for storing CouchDB users.
-
- ::
-
- [couch_httpd_auth]
- authentication_db = _users
-
- .. warning::
- If you change the database name, do not forget to remove or clean
- up the old database, since it will no longer be protected by CouchDB.
-
-
- .. config:option:: authentication_redirect :: Default redirect for authentication requests
-
- Specifies the location for redirection on successful authentication if a
- ``text/html`` response is accepted by the client (via an ``Accept`` header).
-
- ::
-
- [couch_httpd_auth]
- authentication_redirect = /_utils/session.html
-
-
- .. config:option:: iterations :: PBKDF2 iterations count
-
- .. versionadded:: 1.3
-
- The number of iterations for password hashing by the PBKDF2 algorithm.
- A higher number provides better hash durability, but comes at a cost in
- performance for each request that requires authentication.
-
- ::
-
- [couch_httpd_auth]
- iterations = 10000
-
- .. config:option:: min_iterations :: Minimum PBKDF2 iterations count
-
- .. versionadded:: 1.6
-
- The minimum number of iterations allowed for passwords hashed by
- the PBKDF2 algorithm. Any user with fewer iterations is forbidden.
-
- ::
-
- [couch_httpd_auth]
- min_iterations = 100
-
- .. config:option:: max_iterations :: Maximum PBKDF2 iterations count
-
- .. versionadded:: 1.6
-
- The maximum number of iterations allowed for passwords hashed by
- the PBKDF2 algorithm. Any user with greater iterations is forbidden.
-
- ::
-
- [couch_httpd_auth]
- max_iterations = 100000
-
-
- .. config:option:: proxy_use_secret :: Force proxy auth use secret token
-
- When this option is set to ``true``, the :option:`couch_httpd_auth/secret`
- option is required for :ref:`api/auth/proxy`.
-
- ::
-
- [couch_httpd_auth]
- proxy_use_secret = false
-
-
- .. config:option:: public_fields :: User documents public fields
-
- .. versionadded:: 1.4
-
- A comma-separated list of field names in user documents (in
- :option:`couch_httpd_auth/authentication_db`) that can
- be read by any user. If unset or not specified, authenticated users can only
- retrieve their own document.
-
- ::
-
- [couch_httpd_auth]
- public_fields = first_name, last_name, contacts, url
-
- .. note::
- Using the ``public_fields`` whitelist for user document properties
- requires setting the :option:`couch_httpd_auth/users_db_public`
- option to ``true`` (the latter option has no other purpose)::
-
- [couch_httpd_auth]
- users_db_public = true
-
-
- .. config:option:: require_valid_user :: Force user authentication
-
- When this option is set to ``true``, no requests are allowed from anonymous
- users. Everyone must be authenticated.
-
- ::
-
- [couch_httpd_auth]
- require_valid_user = false
-
-
- .. config:option:: secret :: Proxy Auth secret token
-
- The secret token used for :ref:`api/auth/proxy` method.
-
- ::
-
- [couch_httpd_auth]
- secret = 92de07df7e7a3fe14808cef90a7cc0d91
-
-
- .. config:option:: timeout :: Session timeout
-
- Number of seconds since the last request before sessions will be expired.
-
- ::
-
- [couch_httpd_auth]
- timeout = 600
-
-
- .. config:option:: users_db_public :: Publish user documents
-
- .. versionadded:: 1.4
-
- Allow all users to view user documents. By default, only admins may browse
- all users documents, while users may browse only their own document.
-
- ::
-
- [couch_httpd_auth]
- users_db_public = false
-
-
- .. config:option:: x_auth_roles :: Proxy Auth roles header
-
- The HTTP header name (``X-Auth-CouchDB-Roles`` by default) that contains the
- list of a user's roles, separated by a comma. Used for
- :ref:`api/auth/proxy`.
-
- ::
-
- [couch_httpd_auth]
- x_auth_roles = X-Auth-CouchDB-Roles
-
-
- .. config:option:: x_auth_token :: Proxy Auth token header
-
- The HTTP header name (``X-Auth-CouchDB-Token`` by default) containing the
- token used to authenticate the authorization. This token is an `HMAC-SHA1`
- created from the :option:`couch_httpd_auth/secret` and
- :option:`couch_httpd_auth/x_auth_username`. The secret key should be
- the same on the client and the CouchDB node. This token is optional if
- the value of the :option:`couch_httpd_auth/proxy_use_secret` option is not
- ``true``. Used for :ref:`api/auth/proxy`.
-
- ::
-
- [couch_httpd_auth]
- x_auth_roles = X-Auth-CouchDB-Token
-
-
- .. config:option:: x_auth_username :: Proxy Auth username header
-
- The HTTP header name (``X-Auth-CouchDB-UserName`` by default) containing the
- username. Used for :ref:`api/auth/proxy`.
-
- ::
-
- [couch_httpd_auth]
- x_auth_username = X-Auth-CouchDB-UserName
-
-
-.. _config/couch_httpd_oauth:
-
-HTTP OAuth Configuration
-========================
-
-.. config:section:: couch_httpd_oauth :: HTTP OAuth Configuration
-
- .. versionadded:: 1.2
-
- .. config:option:: use_users_db
-
- CouchDB is able to store OAuth credentials within user documents instead of
- config file by using this option::
-
- [couch_httpd_oauth]
- use_users_db = true
-
- If set to ``true``, OAuth token and consumer secrets will be looked up in the
- :option:`authentication database <couch_httpd_auth/authentication_db>`.
- These secrets are stored in a top level field named ``"oauth"`` in user
- documents, as below.
-
- .. code-block:: javascript
-
- {
- "_id": "org.couchdb.user:joe",
- "type": "user",
- "name": "joe",
- "password_sha": "fe95df1ca59a9b567bdca5cbaf8412abd6e06121",
- "salt": "4e170ffeb6f34daecfd814dfb4001a73"
- "roles": ["foo", "bar"],
- "oauth": {
- "consumer_keys": {
- "consumerKey1": "key1Secret",
- "consumerKey2": "key2Secret"
- },
- "tokens": {
- "token1": "token1Secret",
- "token2": "token2Secret"
- }
- }
- }
-
-
-.. _config/oauth:
-
-OAuth Configuration
-===================
-
-.. config:section:: oauth_* :: OAuth Configuration
-
- To let users be authenticated by :ref:`api/auth/oauth` (:rfc:`5849`), three
- special sections must be set up in the :ref:`configuration <config>` file:
-
- 1. The Consumer secret:
-
- ::
-
- [oauth_consumer_secrets]
- consumer1 = sekr1t
-
- 2. Token secrets:
-
- ::
-
- [oauth_token_secrets]
- token1 = tokensekr1t
-
- 3. A mapping from tokens to users:
-
- ::
-
- [oauth_token_users]
- token1 = couchdb_username
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/config/compaction.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/compaction.rst b/share/doc/src/config/compaction.rst
deleted file mode 100644
index 39311a0..0000000
--- a/share/doc/src/config/compaction.rst
+++ /dev/null
@@ -1,174 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License")you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-.. default-domain:: config
-
-.. highlight:: ini
-
-========================
-Compaction Configuration
-========================
-
-.. _conifg/database_compaction:
-
-Database Compaction Options
-===========================
-
-.. config:section:: database_compaction :: Database Compaction Options
-
- .. config:option:: doc_buffer_size :: Documents buffer size
-
- Specifies the copy buffer's maximum size in bytes::
-
- [database_compaction]
- doc_buffer_size = 524288
-
-
- .. config:option:: checkpoint_after :: Checkpoint trigger
-
- Triggers a checkpoint after the specified amount of bytes were successfully
- copied to the compacted database::
-
- [database_compaction]
- checkpoint_after = 5242880
-
-
-.. _config/compactions:
-
-Compaction Daemon Rules
-=======================
-
-.. config:section:: compactions :: Compaction Daemon Rules
-
- A list of rules to determine when to run automatic compaction. The
- :option:`daemons/compaction_daemon` compacts databases and their respective
- view groups when all the condition parameters are satisfied. Configuration
- can be per-database or global, and it has the following format::
-
- [compactions]
- database_name = [ {ParamName, ParamValue}, {ParamName, ParamValue}, ... ]
- _default = [ {ParamName, ParamValue}, {ParamName, ParamValue}, ... ]
-
-
- For example::
-
- [compactions]
- _default = [{db_fragmentation, "70%"}, {view_fragmentation, "60%"}, {from, "23:00"}, {to, "04:00"}]
-
- - ``db_fragmentation``: If the ratio of legacy data, including metadata, to
- current data in the database file size is equal to or greater than this
- value, this condition is satisfied. The percentage is expressed as an
- integer percentage. This value is computed as::
-
- (file_size - data_size) / file_size * 100
-
- The data_size and file_size values can be obtained when
- querying :http:get:`/{db}`.
-
- - ``view_fragmentation``: If the ratio of legacy data, including metadata, to
- current data in a view index file size is equal to or greater then this
- value, this database compaction condition is satisfied. The percentage is
- expressed as an integer percentage. This value is computed as::
-
- (file_size - data_size) / file_size * 100
-
- The data_size and file_size values can be obtained when querying a
- :ref:`view group's information URI <api/ddoc/info>`.
-
- - ``from`` and ``to``: The period for which a database (and its view group)
- compaction is allowed. The value for these parameters must obey the format::
-
- HH:MM - HH:MM (HH in [0..23], MM in [0..59])
-
- - ``strict_window``: If a compaction is still running after the end of the
- allowed period, it will be canceled if this parameter is set to `true`.
- It defaults to `false` and is meaningful only if the *period* parameter is
- also specified.
-
- - ``parallel_view_compaction``: If set to `true`, the database and its views
- are compacted in parallel. This is only useful on certain setups, like
- for example when the database and view index directories point to different
- disks. It defaults to `false`.
-
- Before a compaction is triggered, an estimation of how much free disk space is
- needed is computed. This estimation corresponds to two times the data size of
- the database or view index. When there's not enough free disk space to compact
- a particular database or view index, a warning message is logged.
-
- Examples:
-
- #. ``[{db_fragmentation, "70%"}, {view_fragmentation, "60%"}]``
-
- The `foo` database is compacted if its fragmentation is 70% or more.
- Any view index of this database is compacted only if its fragmentation
- is 60% or more.
-
- #. ``[{db_fragmentation, "70%"}, {view_fragmentation, "60%"}, {from, "00:00"}, {to, "04:00"}]``
-
- Similar to the preceding example but a compaction (database or view index)
- is only triggered if the current time is between midnight and 4 AM.
-
- #. ``[{db_fragmentation, "70%"}, {view_fragmentation, "60%"}, {from, "00:00"}, {to, "04:00"}, {strict_window, true}]``
-
- Similar to the preceding example - a compaction (database or view index)
- is only triggered if the current time is between midnight and 4 AM. If at
- 4 AM the database or one of its views is still compacting, the compaction
- process will be canceled.
-
- #. ``[{db_fragmentation, "70%"}, {view_fragmentation, "60%"}, {from, "00:00"}, {to, "04:00"}, {strict_window, true}, {parallel_view_compaction, true}]``
-
- Similar to the preceding example, but a database and its views can be
- compacted in parallel.
-
-
-.. _config/compaction_daemon:
-
-Configuration of Compaction Daemon
-==================================
-
-.. config:section:: compaction_daemon :: Configuration of Compaction Daemon
-
- .. config:option:: check_interval
-
- The delay, in seconds, between each check for which database and view
- indexes need to be compacted::
-
- [compaction_daemon]
- check_interval = 300
-
-
- .. config:option:: min_file_size
-
- If a database or view index file is smaller than this value (in bytes),
- compaction will not happen. Very small files always have high fragmentation,
- so compacting them is inefficient.
-
- ::
-
- [compaction_daemon]
- min_file_size = 131072
-
-
-.. _config/view_compaction:
-
-Views Compaction Options
-========================
-
-.. config:section:: view_compaction :: Views Compaction Options
-
-
- .. config:option:: keyvalue_buffer_size :: Key-Values buffer size
-
- Specifies maximum copy buffer size in bytes used during compaction::
-
- [view_compaction]
- keyvalue_buffer_size = 2097152
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/config/couchdb.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/couchdb.rst b/share/doc/src/config/couchdb.rst
deleted file mode 100644
index 6f3c022..0000000
--- a/share/doc/src/config/couchdb.rst
+++ /dev/null
@@ -1,200 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-.. default-domain:: config
-
-.. highlight:: ini
-
-==================
-Base Configuration
-==================
-
-.. _config/couchdb:
-
-Base CouchDB Options
-====================
-
-.. config:section:: couchdb :: Base CouchDB Options
-
-
- .. config:option:: attachment_stream_buffer_size :: Attachment streaming buffer
-
- Higher values may result in better read performance due to fewer read
- operations and/or more OS page cache hits. However, they can also increase
- overall response time for writes when there are many attachment write
- requests in parallel.
-
- ::
-
- [couchdb]
- attachment_stream_buffer_size = 4096
-
-
- .. config:option:: database_dir :: Databases location directory
-
- Specifies location of CouchDB database files (``*.couch`` named).
- This location should be writable and readable for the user the CouchDB
- service runs as (``couchdb`` by default).
-
- ::
-
- [couchdb]
- database_dir = /var/lib/couchdb
-
-
- .. config:option:: delayed_commits :: Delayed commits
-
- When this config value as ``false`` the CouchDB provides guaranty of `fsync`
- call before return :http:statuscode:`201` response on each document saving.
- Setting this config value as ``true`` may raise some overall performance
- with cost of losing durability - it's strongly not recommended to do such
- in production::
-
- [couchdb]
- delayed_commits = false
-
- .. warning::
-
- Delayed commits are a feature of CouchDB that allows it to achieve better
- write performance for some workloads while sacrificing a small amount of
- durability. The setting causes CouchDB to wait up to a full second before
- committing new data after an update. If the server crashes before
- the header is written then any writes since the last commit are lost.
-
-
- .. config:option:: file_compression :: Compression method for documents
-
- .. versionchanged:: 1.2 Added `Google Snappy`_ compression algorithm.
-
- Method used to compress everything that is appended to database and
- view index files, except for attachments (see the :section:`attachments`
- section). Available methods are:
-
- * ``none``: no compression
- * ``snappy``: use Google Snappy, a very fast compressor/decompressor
- * ``deflate_N``: use zlib's deflate; ``N`` is the compression level which
- ranges from ``1`` (fastest, lowest compression ratio) to ``9`` (slowest,
- highest compression ratio)
-
- ::
-
- [couchdb]
- file_compression = snappy
-
- .. _Google Snappy: http://code.google.com/p/snappy/
-
-
- .. config:option:: fsync_options :: Fsync options
-
- Specifies when to make `fsync` calls. `fsync` makes sure that
- the contents of any file system buffers kept by the operating system are
- flushed to disk. There is generally no need to modify this parameter.
-
- ::
-
- [couchdb]
- fsync_options = [before_header, after_header, on_file_open]
-
-
- .. config:option:: max_dbs_open :: Limit of simultaneously opened databases
-
- This option places an upper bound on the number of databases that can be
- open at once. CouchDB reference counts database accesses internally and will
- close idle databases as needed. Sometimes it is necessary to keep more than
- the default open at once, such as in deployments where many databases will
- be replicating continuously.
-
- ::
-
- [couchdb]
- max_dbs_open = 100
-
-
- .. config:option:: max_document_size :: Maximum document size
-
- .. versionchanged:: 1.3 This option now actually works.
-
- Defines a maximum size for JSON documents, in bytes. This limit does not
- apply to attachments, since they are transferred as a stream of chunks.
- If you set this to a small value, you might be unable to modify
- configuration options, database security and other larger documents until
- a larger value is restored by editing the configuration file.
-
- ::
-
- [couchdb]
- max_document_size = 4294967296 ; 4 GB
-
-
- .. config:option:: os_process_timeout :: External processes time limit
-
- If an external process, such as a query server or external process, runs for
- this amount of microseconds without returning any results, it will be
- terminated. Keeping this value smaller ensures you get expedient errors, but
- you may want to tweak it for your specific needs.
-
- ::
-
- [couchdb]
- os_process_timeout = 5000 ; 5 sec
-
-
- .. config:option:: uri_file :: Discovery CouchDB help file
-
- This file contains the full `URI`_ that can be used to access this
- instance of CouchDB. It is used to help discover the port CouchDB is running
- on (if it was set to ``0`` (e.g. automatically assigned any free one).
- This file should be writable and readable for the user that runs the CouchDB
- service (``couchdb`` by default).
-
- ::
-
- [couchdb]
- uri_file = /var/run/couchdb/couchdb.uri
-
- .. _URI: http://en.wikipedia.org/wiki/URI
-
-
- .. config:option:: util_driver_dir :: CouchDB binary utility drivers
-
- Specifies location of binary drivers (`icu`, `ejson`, etc.). This location
- and its contents should be readable for the user that runs the CouchDB
- service.
-
- ::
-
- [couchdb]
- util_driver_dir = /usr/lib/couchdb/erlang/lib/couch-1.5.0/priv/lib
-
-
- .. config:option:: uuid :: CouchDB server UUID
-
- .. versionadded:: 1.3
-
- Unique identifier for this CouchDB server instance.
-
- ::
-
- [couchdb]
- uuid = 0a959b9b8227188afc2ac26ccdf345a6
-
-
- .. config:option:: view_index_dir :: View indexes location directory
-
- Specifies location of CouchDB view index files. This location should be
- writable and readable for the user that runs the CouchDB service
- (``couchdb`` by default).
-
- ::
-
- [couchdb]
- view_index_dir = /var/lib/couchdb
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/config/externals.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/externals.rst b/share/doc/src/config/externals.rst
deleted file mode 100644
index c05fe05..0000000
--- a/share/doc/src/config/externals.rst
+++ /dev/null
@@ -1,179 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-.. default-domain:: config
-
-.. highlight:: ini
-
-==================
-External Processes
-==================
-
-.. _config/os_daemons:
-
-OS Daemons
-==========
-
-.. config:section:: os_daemons :: OS Daemons
-
- This is a simple feature that allows users to configure CouchDB so that it
- maintains a given OS level process alive. If the process dies for any reason,
- CouchDB will restart it. If the process restarts too often, then CouchDB will
- mark it has halted and not attempt to restart it. The default max restart rate
- is ``3`` times in the last ``5`` seconds. These parameters are
- :section:`adjustable <os_daemon_settings>`.
-
- Commands that are started in this manner will have access to a simple
- API over stdio to request configuration parameters or to add log
- statements to CouchDB's logs.
-
- To configure an OS process as a CouchDB os_daemon, create a section
- in your `local.ini` like such::
-
- [os_daemons]
- daemon_name = /path/to/command -with args
-
- This will make CouchDB bring up the command and attempt to keep it
- alive. To request a configuration parameter, an `os_daemon` can write
- a simple JSON message to stdout like such::
-
- ["get", "os_daemons"]\n
-
- which would return::
-
- {"daemon_name": "/path/to/command -with args"}\n
-
- Or::
-
- ["get", "os_daemons", "daemon_name"]\n
-
- which would return::
-
- "/path/to/command -with args"\n
-
- There's no restriction on what configuration variables are visible.
- There's also no method for altering the configuration.
-
- If you would like your OS daemon to be restarted in the event that
- the configuration changes, you can send the following messages::
-
- ["register", $(SECTION)]\n
-
- When anything in that section changes, your OS process will be
- rebooted so it can pick up the new configuration settings. If you
- want to listen for changes on a specific key, you can send something
- like::
-
- ["register", $(SECTION), $(KEY)]\n
-
- In this case, CouchDB will only restart your daemon if that exact
- section/key pair changes, instead of anything in that entire section.
-
- Logging commands look like::
-
- ["log", $(JSON_MESSAGE)]\n
-
- Where ``$(JSON_MESSAGE)`` is arbitrary JSON data. These messages are
- logged at the 'info' level. If you want to log at a different level
- you can pass messages like such::
-
- ["log", $(JSON_MESSAGE), {"level": $(LEVEL)}]\n
-
- Where ``$(LEVEL)`` is one of "debug", "info", or "error".
-
- When implementing a daemon process to be managed by CouchDB you
- should remember to use a method like checking the parent process
- id or if stdin has been closed. These flags can tell you if
- your daemon process has been orphaned so you can exit cleanly.
-
- There is no interactivity between CouchDB and the running process, but
- you can use the OS Daemons service to create new HTTP servers and
- responders and then use the new proxy service to redirect requests and
- output to the CouchDB managed service. For more information on proxying,
- see :ref:`http-proxying`. For further background on the OS Daemon service,
- see :ref:`externals`.
-
-
-.. _config/os_daemon_settings:
-
-OS Daemons settings
-===================
-
-.. config:section:: os_daemon_settings :: OS Daemons settings
-
-
- .. config:option:: max_retries :: Maximum restart retries
-
- Specifies maximum attempts to run :section:`os_daemons` before
- mark them halted::
-
- [os_daemon_settings]
- max_retries = 3
-
-
- .. config:option:: retry_time :: Delay between restart attempts
-
- Delay in seconds between :section:`os_daemons` restarts::
-
- [os_daemon_settings]
- retry_time = 5
-
-
-.. _update-notifications:
-.. _config/update_notification:
-
-Update notifications
-====================
-
-.. config:section:: update_notification :: Update notifications
-
- CouchDB is able to spawn OS processes to notify them about recent databases
- updates. The notifications are in form of JSON messages sent as a line of
- text, terminated by ``CR`` (``\n``) character, to the OS processes through
- `stdout`::
-
- [update_notification]
- ;unique notifier name=/full/path/to/exe -with "cmd line arg"
- index_updater = ruby /usr/local/bin/index_updater.rb
-
- The update notification messages are depend upon of event type:
-
- - **Database created**:
-
- .. code-block:: javascript
-
- {"type":"created","db":"dbname"}
-
-
- - **Database updated**: this event raises when any document gets updated for
- specified database:
-
- .. code-block:: javascript
-
- {"type":"updated","db":"dbname"}
-
-
- - **Design document updated**: for design document updates there is special
- event raised in additional to regular db update one:
-
- .. code-block:: javascript
-
- {"type":"ddoc_updated","db":"dbname","id":"_design/ddoc_name"}
-
-
- - **Database deleted**:
-
- .. code-block:: javascript
-
- {"type":"deleted","db":"dbname"}
-
- .. note:: New line (``\n``) trailing character was removed from examples.