Return-Path: X-Original-To: apmail-couchdb-commits-archive@www.apache.org Delivered-To: apmail-couchdb-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id E5D5617EB1 for ; Thu, 16 Oct 2014 09:09:14 +0000 (UTC) Received: (qmail 40843 invoked by uid 500); 16 Oct 2014 09:09:14 -0000 Delivered-To: apmail-couchdb-commits-archive@couchdb.apache.org Received: (qmail 40706 invoked by uid 500); 16 Oct 2014 09:09:14 -0000 Mailing-List: contact commits-help@couchdb.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@couchdb.apache.org Delivered-To: mailing list commits@couchdb.apache.org Received: (qmail 40050 invoked by uid 99); 16 Oct 2014 09:09:14 -0000 Received: from tyr.zones.apache.org (HELO tyr.zones.apache.org) (140.211.11.114) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 16 Oct 2014 09:09:14 +0000 Received: by tyr.zones.apache.org (Postfix, from userid 65534) id DC53A98FBBC; Thu, 16 Oct 2014 09:09:13 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit From: kxepal@apache.org To: commits@couchdb.apache.org Date: Thu, 16 Oct 2014 09:09:22 -0000 Message-Id: <49cc6a45dd0f4b2986985755af8eb908@git.apache.org> In-Reply-To: References: X-Mailer: ASF-Git Admin Mailer Subject: [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 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 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 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. - - :
`_ 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 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 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 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 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 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 - ` 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 -` setting in the CouchDB configuration. - -The UUID type may be changed at any time through the -:ref:`Configuration API `. 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 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 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 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 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 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) `_. - - .. 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 `. - 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 ` 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 `. - - - ``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 `. - - 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.