You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by ns...@apache.org on 2012/09/29 18:11:18 UTC
[4/19] renamed doc to docs
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/doc/src/api/misc.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/misc.rst b/share/doc/src/api/misc.rst
new file mode 100644
index 0000000..f9562ae
--- /dev/null
+++ b/share/doc/src/api/misc.rst
@@ -0,0 +1,805 @@
+.. 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-misc:
+
+=====================
+Miscellaneous Methods
+=====================
+
+The CouchDB Miscellaneous interface provides the basic interface to a
+CouchDB server for obtaining CouchDB information and getting and setting
+configuration information.
+
+A list of the available methods and URL paths are provided below:
+
++--------+-------------------------+-------------------------------------------+
+| Method | Path | Description |
++========+=========================+===========================================+
+| GET | / | Get the welcome message and version |
+| | | information |
++--------+-------------------------+-------------------------------------------+
+| GET | /_active_tasks | Obtain a list of the tasks running in the|
+| | | server |
++--------+-------------------------+-------------------------------------------+
+| GET | /_all_dbs | Get a list of all the DBs |
++--------+-------------------------+-------------------------------------------+
+| GET | /_log | Return the server log file |
++--------+-------------------------+-------------------------------------------+
+| POST | /_replicate | Set or cancel replication |
++--------+-------------------------+-------------------------------------------+
+| POST | /_restart | Restart the server |
++--------+-------------------------+-------------------------------------------+
+| GET | /_stats | Return server statistics |
++--------+-------------------------+-------------------------------------------+
+| GET | /_utils | CouchDB administration interface (Futon) |
++--------+-------------------------+-------------------------------------------+
+| GET | /_uuids | Get generated UUIDs from the server |
++--------+-------------------------+-------------------------------------------+
+| GET | /favicon.ico | Get the site icon |
++--------+-------------------------+-------------------------------------------+
+
+``GET /``
+=========
+
+* **Method**: ``GET /``
+* **Request**: None
+* **Response**: Welcome message and version
+* **Admin Privileges Required**: no
+* **Return Codes**:
+
+ * **200**:
+ Request completed successfully.
+
+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.
+
+.. code-block:: javascript
+
+ {
+ "couchdb" : "Welcome",
+ "version" : "1.0.1"
+ }
+
+.. _active-tasks:
+
+``GET /_active_tasks``
+======================
+
+* **Method**: ``GET /_active_tasks``
+* **Request**: None
+* **Response**: List of running tasks, including the task type, name, status
+ and process ID
+* **Admin Privileges Required**: yes
+* **Return Codes**:
+
+ * **200**:
+ Request completed successfully.
+
+You can obtain a list of active tasks by using the ``/_active_tasks``
+URL. The result is a JSON array of the currently running tasks, with
+each task being described with a single object. For example:
+
+.. code-block:: javascript
+
+ [
+ {
+ "pid" : "<0.11599.0>",
+ "status" : "Copied 0 of 18369 changes (0%)",
+ "task" : "recipes",
+ "type" : "Database Compaction"
+ }
+ ]
+
+The returned structure includes the following fields for each task:
+
+* **tasks** [array]: Active Task
+
+ * **pid**:Process ID
+ * **status**: Task status message
+ * **task**: Task name
+ * **type**: Operation Type
+
+For operation type, valid values include:
+
+- ``Database Compaction``
+
+- ``Replication``
+
+- ``View Group Compaction``
+
+- ``View Group Indexer``
+
+``GET /_all_dbs``
+=================
+
+* **Method**: ``GET /_all_dbs``
+* **Request**: None
+* **Response**: JSON list of DBs
+* **Admin Privileges Required**: no
+* **Return Codes**:
+
+ * **200**:
+ Request completed successfully.
+
+Returns a list of all the databases in the CouchDB instance. For
+example:
+
+.. code-block:: http
+
+ GET http://couchdb:5984/_all_dbs
+ Accept: application/json
+
+The return is a JSON array:
+
+.. code-block:: javascript
+
+ [
+ "_users",
+ "contacts",
+ "docs",
+ "invoices",
+ "locations"
+ ]
+
+``GET /_log``
+=============
+
+* **Method**: ``GET /_log``
+* **Request**: None
+* **Response**: Log content
+* **Admin Privileges Required**: yes
+* **Query Arguments**:
+
+ * **Argument**: bytes
+
+ * **Description**: Bytes to be returned
+ * **Optional**: yes
+ * **Type**: numeric
+ * **Default**: 1000
+
+ * **Argument**: offset
+
+ * **Description**: Offset in bytes where the log tail should be started
+ * **Optional**: yes
+ * **Type**: numeric
+ * **Default**: 0
+
+* **Return Codes**:
+
+ * **200**:
+ Request completed successfully.
+
+Gets the CouchDB log, equivalent to accessing the local log file of the
+corresponding CouchDB instance.
+
+When you request the log, the response is returned as plain (UTF-8)
+text, with an HTTP ``Content-type`` header as ``text/plain``.
+
+For example, the request:
+
+.. code-block:: http
+
+ GET http://couchdb:5984/_log
+ Accept: */*
+
+The raw text is returned:
+
+.. 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.
+
+.. _replicate:
+
+``POST /_replicate``
+====================
+
+.. todo:: POST /_replicate :: what response is?
+
+* **Method**: ``POST /_replicate``
+* **Request**: Replication specification
+* **Response**: TBD
+* **Admin Privileges Required**: yes
+* **Query Arguments**:
+
+ * **Argument**: bytes
+
+ * **Description**: Bytes to be returned
+ * **Optional**: yes
+ * **Type**: numeric
+ * **Default**: 1000
+
+ * **Argument**: offset
+
+ * **Description**: Offset in bytes where the log tail should be started
+ * **Optional**: yes
+ * **Type**: numeric
+ * **Default**: 0
+
+* **Return Codes**:
+
+ * **200**:
+ Replication request successfully completed
+ * **202**:
+ Continuous replication request has been accepted
+ * **404**:
+ Either the source or target DB is not found
+ * **500**:
+ JSON specification was invalid
+
+Request, configure, or stop, a replication operation.
+
+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 fields of the
+JSON request are shown in the table below:
+
+* **cancel (optional)**: Cancels the replication
+* **continuous (optional)**: Configure the replication to be continuous
+* **create_target (optional)**: Creates the target database
+* **doc_ids (optional)**: Array of document IDs to be synchronized
+* **proxy (optional)**: Address of a proxy server through which replication
+ should occur
+* **source**: Source database name or URL
+* **target**: Target database name or URL
+
+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 ``destination`` 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
+ ``destination`` 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
+ Content-Type: application/json
+ Accept: 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
+ }
+
+The structure defines the replication status, as described in the table
+below:
+
+* **history [array]**: Replication History
+
+ * **doc_write_failures**: Number of document write failures
+ * **docs_read**: Number of documents read
+ * **docs_written**: Number of documents written to target
+ * **end_last_seq**: Last sequence number in changes stream
+ * **end_time**: Date/Time replication operation completed
+ * **missing_checked**: Number of missing documents checked
+ * **missing_found**: Number of missing documents found
+ * **recorded_seq**: Last recorded sequence number
+ * **session_id**: Session ID for this replication operation
+ * **start_last_seq**: First sequence number in changes stream
+ * **start_time**: Date/Time replication operation started
+
+* **ok**: Replication status
+* **session_id**: Unique session ID
+* **source_last_seq**: Last sequence number read from source database
+
+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
+ Content-Type: application/json
+ Accept: 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
+ ``databasea`` to ``databaseb``, and separately from ``databaseb`` to
+ ``databasea``.
+
+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
+ Content-Type: application/json
+ Accept: 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.
+
+``POST /_restart``
+==================
+
+* **Method**: ``POST /_restart``
+* **Request**: None
+* **Response**: JSON status message
+* **Admin Privileges Required**: yes
+* **HTTP Headers**:
+
+ * **Header**: ``Content-Type``
+
+ * **Description**: Request content type
+ * **Optional**: no
+ * **Value**: :mimetype:`application/json`
+
+* **Return Codes**:
+
+ * **200**:
+ Replication request successfully completed
+
+Restarts the CouchDB instance. You must be authenticated as a user with
+administration privileges for this to work.
+
+For example:
+
+.. code-block:: http
+
+ POST http://admin:password@couchdb:5984/_restart
+
+The return value (if the server has not already restarted) is a JSON
+status object indicating that the request has been received:
+
+.. code-block:: javascript
+
+ {
+ "ok" : true,
+ }
+
+If the server has already restarted, the header may be returned, but no
+actual data is contained in the response.
+
+``GET /_stats``
+===============
+
+* **Method**: ``GET /_stats``
+* **Request**: None
+* **Response**: Server statistics
+* **Admin Privileges Required**: no
+* **Return Codes**:
+
+ * **200**:
+ Request completed successfully.
+
+The ``_stats`` method 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. For example, the request time statistics, within the
+``couchdb`` section are structured as follows:
+
+.. code-block:: javascript
+
+ {
+ "couchdb" : {
+ ...
+ "request_time" : {
+ "stddev" : "27.509",
+ "min" : "0.333333333333333",
+ "max" : "152",
+ "current" : "400.976",
+ "mean" : "10.837",
+ "sum" : "400.976",
+ "description" : "length of a request inside CouchDB without MochiWeb"
+ },
+ ...
+ }
+ }
+
+
+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"
+ }
+ }
+ }
+
+
+``GET /_utils``
+===============
+
+* **Method**: ``GET /_utils``
+* **Request**: None
+* **Response**: Administration interface
+* **Admin Privileges Required**: no
+
+Accesses the built-in Futon administration interface for CouchDB.
+
+``GET /_uuids``
+===============
+
+* **Method**: ``GET /_uuids``
+* **Request**: None
+* **Response**: List of UUIDs
+* **Admin Privileges Required**: no
+* **Query Arguments**:
+
+ * **Argument**: count
+
+ * **Description**: Number of UUIDs to return
+ * **Optional**: yes
+ * **Type**: numeric
+
+* **Return Codes**:
+
+ * **200**:
+ Request completed successfully.
+
+Requests one or more Universally Unique Identifiers (UUIDs) from the
+CouchDB instance. The response is a JSON object providing a list of
+UUIDs. For example:
+
+.. code-block:: javascript
+
+ {
+ "uuids" : [
+ "7e4b5a14b22ec1cf8e58b9cdd0000da3"
+ ]
+ }
+
+You can use the ``count`` argument to specify the number of UUIDs to be
+returned. For example:
+
+.. code-block:: http
+
+ GET http://couchdb:5984/_uuids?count=5
+
+Returns:
+
+.. code-block:: javascript
+
+ {
+ "uuids" : [
+ "c9df0cdf4442f993fc5570225b405a80",
+ "c9df0cdf4442f993fc5570225b405bd2",
+ "c9df0cdf4442f993fc5570225b405e42",
+ "c9df0cdf4442f993fc5570225b4061a0",
+ "c9df0cdf4442f993fc5570225b406a20"
+ ]
+ }
+
+The UUID type is determined by the UUID type setting in the CouchDB
+configuration. See :ref:`api-put-config`.
+
+For example, changing the UUID type to ``random``:
+
+.. code-block:: http
+
+ PUT http://couchdb:5984/_config/uuids/algorithm
+ Content-Type: application/json
+ Accept: */*
+
+ "random"
+
+When obtaining a list of UUIDs:
+
+.. code-block:: javascript
+
+ {
+ "uuids" : [
+ "031aad7b469956cf2826fcb2a9260492",
+ "6ec875e15e6b385120938df18ee8e496",
+ "cff9e881516483911aa2f0e98949092d",
+ "b89d37509d39dd712546f9510d4a9271",
+ "2e0dbf7f6c4ad716f21938a016e4e59f"
+ ]
+ }
+
+``GET /favicon.ico``
+====================
+
+* **Method**: ``GET /favicon.ico``
+* **Request**: None
+* **Response**: Binary content for the `favicon.ico` site icon
+* **Admin Privileges Required**: no
+* **Return Codes**:
+
+ * **200**:
+ Request completed successfully.
+ * **404**:
+ The requested content could not be found. The returned content will include
+ further information, as a JSON object, if available.
+
+Returns the site icon. The return ``Content-Type`` header is
+:mimetype:`image/x-icon`, and the content stream is the image data.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/doc/src/api/reference.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/reference.rst b/share/doc/src/api/reference.rst
new file mode 100644
index 0000000..fce650a
--- /dev/null
+++ b/share/doc/src/api/reference.rst
@@ -0,0 +1,28 @@
+.. 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 Reference
+=============
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ configuration
+ authn
+ database
+ documents
+ design
+ misc
+ local
+ dbmaint
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/doc/src/changes.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/changes.rst b/share/doc/src/changes.rst
new file mode 100644
index 0000000..bd50860
--- /dev/null
+++ b/share/doc/src/changes.rst
@@ -0,0 +1,43 @@
+.. 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.
+
+.. _changes:
+
+============
+Changes Feed
+============
+
+The ``_changes`` feed can now be used to watch changes to specific
+document ID's or the list of ``_design`` documents in a database. If the
+``filters`` parameter is set to ``_doc_ids`` a list of doc IDs can be
+passed in the "doc_ids" as a JSON array.
+
+
+Polling
+=======
+
+
+
+Long Polling
+============
+
+
+
+Continuous
+==========
+
+
+
+Filters
+=======
+
+
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/doc/src/commonjs.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/commonjs.rst b/share/doc/src/commonjs.rst
new file mode 100644
index 0000000..81ef310
--- /dev/null
+++ b/share/doc/src/commonjs.rst
@@ -0,0 +1,56 @@
+.. 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.
+
+CommonJS support for map functions
+==================================
+
+CommonJS support allows you to use CommonJS notation inside map and
+reduce functions, but only of libraries that are stored inside the views
+part of the design doc.
+
+So you could continue to access CommonJS code in design\_doc.foo, from
+your list functions etc, but we'd add the ability to require CommonJS
+modules within map and reduce, but only from ``design_doc.views.lib``.
+
+There's no worry here about namespace collisions, as Couch just plucks
+``views.*.map`` and ``views.*.reduce`` out of the design doc. So you
+could have a view called ``lib`` if you wanted, and still have CommonJS
+stored in ``views.lib.sha1`` and ``views.lib.stemmer`` if you wanted.
+
+The implementation is simplified by enforcing that CommonJS modules to
+be used in map functions be stored in views.lib.
+
+A sample design doc (taken from the test suite in Futon) is below:
+
+.. code-block:: javascript
+
+ {
+ "views" : {
+ "lib" : {
+ "baz" : "exports.baz = 'bam';",
+ "foo" : {
+ "zoom" : "exports.zoom = 'yeah';",
+ "boom" : "exports.boom = 'ok';",
+ "foo" : "exports.foo = 'bar';"
+ }
+ },
+ "commonjs" : {
+ "map" : "function(doc) { emit(null, require('views/lib/foo/boom').boom)}"
+ }
+ },
+ "_id" : "_design/test"
+ }
+
+The ``require()`` statement is relative to the design document, but
+anything loaded form outside of ``views/lib`` will fail.
+
+.. _CommonJS: http://commonjs.org/specs
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/doc/src/conf.py
----------------------------------------------------------------------
diff --git a/share/doc/src/conf.py b/share/doc/src/conf.py
new file mode 100644
index 0000000..cffdb29
--- /dev/null
+++ b/share/doc/src/conf.py
@@ -0,0 +1,33 @@
+import sys, os
+
+extensions = ["sphinx.ext.todo"]
+
+source_suffix = ".rst"
+
+master_doc = "index"
+
+nitpicky = True
+
+project = "@@"
+
+copyright = "@@"
+
+version = "@@"
+
+release = "@@"
+
+highlight_language = "json"
+
+pygments_style = "sphinx"
+
+# @@ design CouchDB theme
+
+html_theme = "default"
+
+html_short_title = "@@"
+
+html_logo = "@@"
+
+html_favicon = "@@"
+
+html_use_opensearch = "@@"
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/doc/src/config_reference.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config_reference.rst b/share/doc/src/config_reference.rst
new file mode 100644
index 0000000..b2e78cf
--- /dev/null
+++ b/share/doc/src/config_reference.rst
@@ -0,0 +1,288 @@
+.. 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.
+
+Configuration options reference
+===============================
+
+
+Configuration Groups
+--------------------
+
++----------------------------------+-------------------------------------------+
+| Section | Description |
++==================================+===========================================+
+| attachments | Attachment options |
++----------------------------------+-------------------------------------------+
+| couchdb | CouchDB specific options |
++----------------------------------+-------------------------------------------+
+| couch_httpd_auth | HTTPD Authentication options |
++----------------------------------+-------------------------------------------+
+| daemons | Daemons and background processes |
++----------------------------------+-------------------------------------------+
+| httpd | HTTPD Server options |
++----------------------------------+-------------------------------------------+
+| httpd_db_handlers | Database Operation handlers |
++----------------------------------+-------------------------------------------+
+| httpd_design_handlers | Handlers for design document operations |
++----------------------------------+-------------------------------------------+
+| httpd_global_handlers | Handlers for global operations |
++----------------------------------+-------------------------------------------+
+| log | Logging options |
++----------------------------------+-------------------------------------------+
+| query_servers | Query Server options |
++----------------------------------+-------------------------------------------+
+| query_server_config | Query server options |
++----------------------------------+-------------------------------------------+
+| replicator | Replicator Options |
++----------------------------------+-------------------------------------------+
+| ssl | SSL (Secure Sockets Layer) Options |
++----------------------------------+-------------------------------------------+
+| stats | Statistics options |
++----------------------------------+-------------------------------------------+
+| uuids | UUID generation options |
++----------------------------------+-------------------------------------------+
+
+attachments Configuration Options
+---------------------------------
+
++--------------------------------------+---------------------------------------+
+| Option | Description |
++======================================+=======================================+
+| compressible_types | compressible_types |
++--------------------------------------+---------------------------------------+
+| compression_level | compression_level |
++--------------------------------------+---------------------------------------+
+
+couchdb Configuration Options
+-----------------------------
+
++--------------------------------------+---------------------------------------+
+| Option | Description |
++======================================+=======================================+
+| database_dir | database_dir |
++--------------------------------------+---------------------------------------+
+| delayed_commits | delayed_commits |
++--------------------------------------+---------------------------------------+
+| max_attachment_chunk_size | max_attachment_chunk_size |
++--------------------------------------+---------------------------------------+
+| max_dbs_open | max_dbs_open |
++--------------------------------------+---------------------------------------+
+| max_document_size | max_document_size |
++--------------------------------------+---------------------------------------+
+| os_process_timeout | os_process_timeout |
++--------------------------------------+---------------------------------------+
+| uri_file | uri_file |
++--------------------------------------+---------------------------------------+
+| util_driver_dir | util_driver_dir |
++--------------------------------------+---------------------------------------+
+| view_index_dir | view_index_dir |
++--------------------------------------+---------------------------------------+
+
+daemons Configuration Options
+-----------------------------
+
++--------------------------------------+---------------------------------------+
+| Option | Description |
++======================================+=======================================+
+| auth_cache | auth_cache |
++--------------------------------------+---------------------------------------+
+| db_update_notifier | db_update_notifier |
++--------------------------------------+---------------------------------------+
+| external_manager | external_manager |
++--------------------------------------+---------------------------------------+
+| httpd | httpd |
++--------------------------------------+---------------------------------------+
+| httpsd | Enabled HTTPS service |
++--------------------------------------+---------------------------------------+
+| query_servers | query_servers |
++--------------------------------------+---------------------------------------+
+| stats_aggregator | stats_aggregator |
++--------------------------------------+---------------------------------------+
+| stats_collector | stats_collector |
++--------------------------------------+---------------------------------------+
+| uuids | uuids |
++--------------------------------------+---------------------------------------+
+| view_manager | view_manager |
++--------------------------------------+---------------------------------------+
+
+httpd_db_handlers Configuration Options
+---------------------------------------
+
++--------------------------------------+---------------------------------------+
+| Option | Description |
++======================================+=======================================+
+| _changes | _changes |
++--------------------------------------+---------------------------------------+
+| _compact | _compact |
++--------------------------------------+---------------------------------------+
+| _design | _design |
++--------------------------------------+---------------------------------------+
+| _temp_view | _temp_view |
++--------------------------------------+---------------------------------------+
+| _view_cleanup | _view_cleanup |
++--------------------------------------+---------------------------------------+
+
+couch_httpd_auth Configuration Options
+--------------------------------------
+
++--------------------------------------+---------------------------------------+
+| Option | Description |
++======================================+=======================================+
+| auth_cache_size | auth_cache_size |
++--------------------------------------+---------------------------------------+
+| authentication_db | authentication_db |
++--------------------------------------+---------------------------------------+
+| authentication_redirect | authentication_redirect |
++--------------------------------------+---------------------------------------+
+| require_valid_user | require_valid_user |
++--------------------------------------+---------------------------------------+
+| timeout | timeout |
++--------------------------------------+---------------------------------------+
+
+httpd Configuration Options
+---------------------------
+
++--------------------------------------+---------------------------------------+
+| Option | Description |
++======================================+=======================================+
+| allow_jsonp | allow_jsonp |
++--------------------------------------+---------------------------------------+
+| authentication_handlers | authentication_handlers |
++--------------------------------------+---------------------------------------+
+| bind_address | bind_address |
++--------------------------------------+---------------------------------------+
+| default_handler | default_handler |
++--------------------------------------+---------------------------------------+
+| max_connections | max_connections |
++--------------------------------------+---------------------------------------+
+| nodelay | Enable TCP_NODELAY |
++--------------------------------------+---------------------------------------+
+| port | port |
++--------------------------------------+---------------------------------------+
+| secure_rewrites | secure_rewrites |
++--------------------------------------+---------------------------------------+
+| vhost_global_handlers | vhost_global_handlers |
++--------------------------------------+---------------------------------------+
+
+httpd_design_handlers Configuration Options
+-------------------------------------------
+
++--------------------------------------+---------------------------------------+
+| Option | Description |
++======================================+=======================================+
+| _info | _info |
++--------------------------------------+---------------------------------------+
+| _list | _list |
++--------------------------------------+---------------------------------------+
+| _rewrite | _rewrite |
++--------------------------------------+---------------------------------------+
+| _show | _show |
++--------------------------------------+---------------------------------------+
+| _update | _update |
++--------------------------------------+---------------------------------------+
+| _view | _view |
++--------------------------------------+---------------------------------------+
+
+httpd_global_handlers Configuration Options
+-------------------------------------------
+
++--------------------------------------+---------------------------------------+
+| Option | Description |
++======================================+=======================================+
+| / | / |
++--------------------------------------+---------------------------------------+
+| _active_tasks | _active_tasks |
++--------------------------------------+---------------------------------------+
+| _all_dbs | _all_dbs |
++--------------------------------------+---------------------------------------+
+| _config | _config |
++--------------------------------------+---------------------------------------+
+| _log | _log |
++--------------------------------------+---------------------------------------+
+| _oauth | _oauth |
++--------------------------------------+---------------------------------------+
+| _replicate | _replicate |
++--------------------------------------+---------------------------------------+
+| _restart | _restart |
++--------------------------------------+---------------------------------------+
+| _session | _session |
++--------------------------------------+---------------------------------------+
+| _stats | _stats |
++--------------------------------------+---------------------------------------+
+| _utils | _utils |
++--------------------------------------+---------------------------------------+
+| _uuids | _uuids |
++--------------------------------------+---------------------------------------+
+| favicon.ico | favicon.ico |
++--------------------------------------+---------------------------------------+
+
+log Configuration Options
+-------------------------
+
++--------------------------------------+---------------------------------------+
+| Option | Description |
++======================================+=======================================+
+| file | file |
++--------------------------------------+---------------------------------------+
+| include_sasl | include_sasl |
++--------------------------------------+---------------------------------------+
+| level | level |
++--------------------------------------+---------------------------------------+
+
+query_servers Configuration Options
+-----------------------------------
+
++--------------------------------------+---------------------------------------+
+| Option | Description |
++======================================+=======================================+
+| javascript | javascript |
++--------------------------------------+---------------------------------------+
+
+query_server_config Configuration Options
+-----------------------------------------
+
++--------------------------------------+---------------------------------------+
+| Option | Description |
++======================================+=======================================+
+| reduce_limit | reduce_limit |
++--------------------------------------+---------------------------------------+
+
+replicator Configuration Options
+--------------------------------
+
++--------------------------------------+---------------------------------------+
+| Option | Description |
++======================================+=======================================+
+| max_http_pipeline_size | max_http_pipeline_size |
++--------------------------------------+---------------------------------------+
+| max_http_sessions | max_http_sessions |
++--------------------------------------+---------------------------------------+
+
+stats Configuration Options
+---------------------------
+
++--------------------------------------+---------------------------------------+
+| Option | Description |
++======================================+=======================================+
+| rate | rate |
++--------------------------------------+---------------------------------------+
+| samples | samples |
++--------------------------------------+---------------------------------------+
+
+uuids Configuration Options
+---------------------------
+
++--------------------------------------+---------------------------------------+
+| Option | Description |
++======================================+=======================================+
+| algorithm | algorithm |
++--------------------------------------+---------------------------------------+
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/doc/src/configuring.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/configuring.rst b/share/doc/src/configuring.rst
new file mode 100644
index 0000000..aefee3d
--- /dev/null
+++ b/share/doc/src/configuring.rst
@@ -0,0 +1,95 @@
+.. 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.
+
+.. _configuring:
+
+===================
+Configuring CouchDB
+===================
+
+.. todo:: Configuring CouchDB
+
+CouchDB Configuration Files
+===========================
+
+.. todo:: CouchDB Configuration Files
+
+Configuration File Locations
+============================
+
+CouchDB reads files from the following locations, in the following
+order.
+
+1. ``PREFIX/default.ini``
+
+2. ``PREFIX/default.d/*``
+
+3. ``PREFIX/local.ini``
+
+4. ``PREFIX/local.d/*``
+
+Settings in successive documents override the settings in earlier
+entries. For example, setting the ``bind_address`` parameter in
+``local.ini`` would override any setting in ``default.ini``.
+
+.. warning::
+ The ``default.ini`` file may be overwritten during an upgrade or
+ re-installation, so localised changes should be made to the
+ ``local.ini`` file or files within the ``local.d`` directory.
+
+.. _update-notifications:
+
+Update Notifications
+====================
+
+.. todo:: Update Notifications
+
+
+MochiWeb Server Options
+=======================
+
+Server options for the MochiWeb component of CouchDB can be added to the
+configuration files. Settings should be added to the ``server_options``
+option of the ``[httpd]`` section of ``local.ini``. For example:
+
+.. code-block:: ini
+
+ [httpd]
+ server_options = [{backlog, 128}, {acceptor_pool_size, 16}]
+
+Socket Options Configuration Setting
+====================================
+
+The socket options for the listening socket in CouchDB can now be set
+within the CouchDB configuration file. The setting should be added to
+the ``[httpd]`` section of the file using the option name
+``socket_options``. The specification is as a list of tuples. For
+example:
+
+.. code-block:: ini
+
+ [httpd]
+ socket_options = [{recbuf, 262144}, {sndbuf, 262144}, {nodelay, true}]
+
+The options supported are a subset of full options supported by the
+TCP/IP stack. A list of the supported options are provided in the
+`Erlang inet`_ documentation.
+
+.. _Erlang inet: http://www.erlang.org/doc/man/inet.html#setopts-2
+
+``vhosts`` definitions
+======================
+
+Similar to the rewrites section of a ``_design`` document, the
+``vhosts`` system uses variables in the form of ``:varname`` or wildcards in
+the form of asterisks. The variable results can be output into the
+resulting path as they are in the rewriter.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/doc/src/ddocs.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/ddocs.rst b/share/doc/src/ddocs.rst
new file mode 100644
index 0000000..4dd9466
--- /dev/null
+++ b/share/doc/src/ddocs.rst
@@ -0,0 +1,19 @@
+.. 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.
+
+.. _ddocs:
+
+Design Docs
+===========
+
+To be added: information on writing design docs, including views.
+
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/doc/src/errors.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/errors.rst b/share/doc/src/errors.rst
new file mode 100644
index 0000000..431ff91
--- /dev/null
+++ b/share/doc/src/errors.rst
@@ -0,0 +1,37 @@
+.. 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.
+
+Error Messages
+==============
+
+The errors reported when CouchDB is unable to read a required file have
+been updated so that explicit information about the files and problem
+can now be identified from the error message. The errors report file
+permission access either when reading or writing to configuration and
+database files.
+
+The error is raised both through the log file and the error message
+returned through the API call as a JSON error message. For example, when
+setting configuration values:
+
+.. code-block:: bash
+
+ shell> curl -X PUT http://couchdb:5984/_config/couchdb/delayed_commits \
+ -H 'X-Couch-Persist: true' -d '"false"'
+ {"error":"file_permission_error","reason":"/etc/couchdb/local.ini"}
+
+Errors will always be reported using the ``file_permission_error`` error
+type.
+
+During startup permissions errors on key files are also reported in the
+log with a descriptive error message and file location so that
+permissions can be fixed before restart.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/doc/src/http-proxying.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/http-proxying.rst b/share/doc/src/http-proxying.rst
new file mode 100644
index 0000000..cff2404
--- /dev/null
+++ b/share/doc/src/http-proxying.rst
@@ -0,0 +1,94 @@
+.. 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.
+
+.. _http-proxying:
+
+HTTP Proxying
+=============
+
+The HTTP proxy feature makes it easy to map and redirect different
+content through your CouchDB URL. The proxy works by mapping a pathname
+and passing all content after that prefix through to the configured
+proxy address.
+
+Configuration of the proxy redirect is handled through the
+``[httpd_global_handlers]`` section of the CouchDB configuration file
+(typically ``local.ini``). The format is:
+
+.. code-block:: ini
+
+ [httpd_global_handlers]
+ PREFIX = {couch_httpd_proxy, handle_proxy_req, <<"DESTINATION">>}
+
+
+Where:
+
+- ``PREFIX``
+
+ Is the string that will be matched. The string can be any valid
+ qualifier, although to ensure that existing database names are not
+ overridden by a proxy configuration, you can use an underscore
+ prefix.
+
+- ``DESTINATION``
+
+ The fully-qualified URL to which the request should be sent. The
+ destination must include the ``http`` prefix. The content is used
+ verbatim in the original request, so you can also forward to servers
+ on different ports and to specific paths on the target host.
+
+The proxy process then translates requests of the form:
+
+.. code-block:: text
+
+ http://couchdb:5984/PREFIX/path
+
+To:
+
+.. code-block:: text
+
+ DESTINATION/path
+
+.. note::
+ Everything after ``PREFIX`` including the required forward slash
+ will be appended to the ``DESTINATION``.
+
+The response is then communicated back to the original client.
+
+For example, the following configuration:
+
+.. code-block:: ini
+
+ _google = {couch_httpd_proxy, handle_proxy_req, <<"http://www.google.com">>}
+
+Would forward all requests for ``http://couchdb:5984/_google`` to the
+Google website.
+
+The service can also be used to forward to related CouchDB services,
+such as Lucene:
+
+.. code-block:: ini
+
+ [httpd_global_handlers]
+ _fti = {couch_httpd_proxy, handle_proxy_req, <<"http://127.0.0.1:5985">>}
+
+.. note::
+ The proxy service is basic. If the request is not identified by the
+ ``DESTINATION``, or the remainder of the ``PATH`` specification is
+ incomplete, the original request URL is interpreted as if the
+ ``PREFIX`` component of that URL does not exist.
+
+ For example, requesting ``http://couchdb:5984/_intranet/media`` when
+ ``/media`` on the proxy destination does not exist, will cause the
+ request URL to be interpreted as ``http://couchdb:5984/media``. Care
+ should be taken to ensure that both requested URLs and destination
+ URLs are able to cope.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/doc/src/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/index.rst b/share/doc/src/index.rst
new file mode 100644
index 0000000..48b563e
--- /dev/null
+++ b/share/doc/src/index.rst
@@ -0,0 +1,48 @@
+.. 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.
+
+.. CouchDB documentation master file, created by
+ sphinx-quickstart on Tue Jul 31 20:52:16 2012.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Apache CouchDB Documentation
+============================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ intro
+ api-basics
+ range
+ configuring
+ ssl
+ os-daemons
+ http-proxying
+ config_reference
+ replication
+ ddocs
+ commonjs
+ errors
+ changes
+ release
+ api/reference
+ json-structure
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c9efdb1b/share/doc/src/intro.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro.rst b/share/doc/src/intro.rst
new file mode 100644
index 0000000..b5930d3
--- /dev/null
+++ b/share/doc/src/intro.rst
@@ -0,0 +1,309 @@
+.. 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.
+
+============
+Introduction
+============
+
+There are two interfaces to CouchDB, the built-in Futon web-based
+interface and the CouchDB API accessed through the HTTP REST interface.
+The former is the simplest way to view and monitor your CouchDB
+installation and perform a number of basic database and system
+operations. More information on using the Futon interface can be found
+in :ref:`using-futon`.
+
+The primary way to interact with the CouchDB API is to use a client
+library or other interface that provides access to the underlying
+functionality through your chosen language or platform. However, since
+the API is supported through HTTP REST, you can interact with your
+CouchDB with any solution that supports the HTTP protocol.
+
+There are a number of different tools that talk the HTTP protocol and
+allow you to set and configure the necessary information. One tool for
+this that allows for access from the command-line is ``curl``. See
+:ref:`using-curl`.
+
+.. _using-futon:
+
+Using Futon
+===========
+
+Futon is a native web-based interface built into CouchDB. It provides a
+basic interface to the majority of the functionality, including the
+ability to create, update, delete and view documents and views, provides
+access to the configuration parameters, and an interface for initiating
+replication.
+
+The default view is the Overview page which provides you with a list of
+the databases. The basic structure of the page is consistent regardless
+of the section you are in. The main panel on the left provides the main
+interface to the databases, configuration or replication systems. The
+side panel on the right provides navigation to the main areas of Futon
+interface:
+
+.. figure:: ../images/futon-overview.png
+ :align: center
+ :alt: Futon Overview
+
+ Futon Overview
+
+The main sections are:
+
+- Overview
+
+ The main overview page, which provides a list of the databases and
+ provides the interface for querying the database and creating and
+ updating documents. See :ref:`futon-management`.
+
+- Configuration
+
+ An interface into the configuration of your CouchDB installation. The
+ interface allows you to edit the different configurable parameters.
+ For more details on configuration, see :ref:`configuring`.
+
+- Replicator
+
+ An interface to the replication system, enabling you to initiate
+ replication between local and remote databases. See
+ :ref:`futon-replication`.
+
+- Status
+
+ Displays a list of the running background tasks on the server.
+ Background tasks include view index building, compaction and
+ replication. The Status page is an interface to the
+ :ref:`Active Tasks <active-tasks>` API call.
+
+- Verify Installation
+
+ The Verify Installation allows you to check whether all of the
+ components of your CouchDB installation are correctly installed.
+
+- Test Suite
+
+ The Test Suite section allows you to run the built-in test suite.
+ This executes a number of test routines entirely within your browser
+ to test the API and functionality of your CouchDB installation. If
+ you select this page, you can run the tests by using the Run All
+ button. This will execute all the tests, which may take some time.
+
+.. _futon-management:
+
+Managing Databases and Documents
+--------------------------------
+
+You can manage databases and documents within Futon using the main
+Overview section of the Futon interface.
+
+To create a new database, click the Create Database ELLIPSIS button. You
+will be prompted for the database name, as shown in the figure below.
+
+.. figure:: ../images/futon-createdb.png
+ :align: center
+ :alt: Creating a Database
+
+ Creating a Database
+
+Once you have created the database (or selected an existing one), you
+will be shown a list of the current documents. If you create a new
+document, or select an existing document, you will be presented with the
+edit document display.
+
+Editing documents within Futon requires selecting the document and then
+editing (and setting) the fields for the document individually before
+saving the document back into the database.
+
+For example, the figure below shows the editor for a single document, a
+newly created document with a single ID, the document ``_id`` field.
+
+.. figure:: ../images/futon-editdoc.png
+ :align: center
+ :alt: Editing a Document
+
+ Editing a Document
+
+To add a field to the document:
+
+1. Click Add Field.
+
+2. In the fieldname box, enter the name of the field you want to create.
+ For example, “company”.
+
+3. Click the green tick next to the field name to confirm the field name
+ change.
+
+4. Double-click the corresponding Value cell.
+
+5. Enter a company name, for example “Example”.
+
+6. Click the green tick next to the field value to confirm the field
+ value.
+
+7. The document is still not saved as this point. You must explicitly
+ save the document by clicking the Save Document button at the top of
+ the page. This will save the document, and then display the new
+ document with the saved revision information (the ``_rev`` field).
+
+ .. figure:: ../images/futon-editeddoc.png
+ :align: center
+ :alt: Edited Document
+
+ Edited Document
+
+The same basic interface is used for all editing operations within Futon.
+You *must* remember to save the individual element (fieldname, value)
+using the green tick button, before then saving the document.
+
+.. _futon-replication:
+
+Configuring Replication
+-----------------------
+
+When you click the Replicator option within the Tools menu you are
+presented with the Replicator screen. This allows you to start
+replication between two databases by filling in or select the
+appropriate options within the form provided.
+
+.. figure:: ../images/futon-replform.png
+ :align: center
+ :alt: Replication Form
+
+ Replication Form
+
+To start a replication process, either the select the local database or
+enter a remote database name into the corresponding areas of the form.
+Replication occurs from the database on the left to the database on the
+right.
+
+If you are specifying a remote database name, you must specify the full
+URL of the remote database (including the host, port number and database
+name). If the remote instance requires authentication, you can specify
+the username and password as part of the URL, for example
+``http://username:pass@remotehost:5984/demo``.
+
+To enable continuous replication, click the Continuous checkbox.
+
+To start the replication process, click the Replicate button. The
+replication process should start and will continue in the background. If
+the replication process will take a long time, you can monitor the
+status of the replication using the Status option under the Tools menu.
+
+Once replication has been completed, the page will show the information
+returned when the replication process completes by the API.
+
+The Replicator tool is an interface to the underlying replication API.
+For more information, see :ref:`replicate`. For more information on
+replication, see :ref:`replication`.
+
+.. _using-curl:
+
+Using ``curl``
+==============
+
+The ``curl`` utility is a command line tool available on Unix, Linux,
+Mac OS X and Windows and many other platforms. ``curl`` provides easy
+access to the HTTP protocol (among others) directly from the
+command-line and is therefore an ideal way of interacting with CouchDB
+over the HTTP REST API.
+
+For simple ``GET`` requests you can supply the URL of the request. For
+example, to get the database information:
+
+.. code-block:: bash
+
+ shell> curl http://127.0.0.1:5984
+
+This returns the database information (formatted in the output below for
+clarity):
+
+.. code-block:: json
+
+ {
+ "couchdb" : "Welcome",
+ "version" : "|version|",
+ }
+
+.. note:: For some URLs, especially those that include special characters such
+ as ampersand, exclamation mark, or question mark, you should quote
+ the URL you are specifying on the command line. For example:
+
+ .. code-block:: bash
+
+ shell> curl 'http://couchdb:5984/_uuids?count=5'
+
+You can explicitly set the HTTP command using the ``-X`` command line
+option. For example, when creating a database, you set the name of the
+database in the URL you send using a PUT request:
+
+.. code-block:: bash
+
+ shell> curl -X PUT http://127.0.0.1:5984/demo
+ {"ok":true}
+
+But to obtain the database information you use a ``GET`` request (with
+the return information formatted for clarity):
+
+.. code-block:: bash
+
+ shell> curl -X GET http://127.0.0.1:5984/demo
+ {
+ "compact_running" : false,
+ "doc_count" : 0,
+ "db_name" : "demo",
+ "purge_seq" : 0,
+ "committed_update_seq" : 0,
+ "doc_del_count" : 0,
+ "disk_format_version" : 5,
+ "update_seq" : 0,
+ "instance_start_time" : "1306421773496000",
+ "disk_size" : 79
+ }
+
+For certain operations, you must specify the content type of request,
+which you do by specifying the ``Content-Type`` header using the ``-H``
+command-line option:
+
+.. code-block:: bash
+
+ shell> curl -H 'Content-Type: application/json' http://127.0.0.1:5984/_uuids
+
+You can also submit 'payload' data, that is, data in the body of the
+HTTP request using the ``-d`` option. This is useful if you need to
+submit JSON structures, for example document data, as part of the
+request. For example, to submit a simple document to the ``demo``
+database:
+
+.. code-block:: bash
+
+ shell> curl -H 'Content-Type: application/json' \
+ -X POST http://127.0.0.1:5984/demo \
+ -d '{"company": "Example, Inc."}'
+ {"ok":true,"id":"8843faaf0b831d364278331bc3001bd8",
+ "rev":"1-33b9fbce46930280dab37d672bbc8bb9"}
+
+In the above example, the argument after the ``-d`` option is the JSON
+of the document we want to submit.
+
+The document can be accessed by using the automatically generated
+document ID that was returned:
+
+.. code-block:: bash
+
+ shell> curl -X GET http://127.0.0.1:5984/demo/8843faaf0b831d364278331bc3001bd8
+ {"_id":"8843faaf0b831d364278331bc3001bd8",
+ "_rev":"1-33b9fbce46930280dab37d672bbc8bb9",
+ "company":"Example, Inc."}
+
+The API samples in the :ref:`api-basics` show the HTTP command, URL and any
+payload information that needs to be submitted (and the expected return
+value). All of these examples can be reproduced using ``curl`` with the
+command-line examples shown above.