http://git-wip-us.apache.org/repos/asf/couchdb/blob/1055ea0e/share/docs/couchdb-manual-1.1/couchdb-manual.xml ---------------------------------------------------------------------- diff --git a/share/docs/couchdb-manual-1.1/couchdb-manual.xml b/share/docs/couchdb-manual-1.1/couchdb-manual.xml new file mode 100644 index 0000000..3404b92 --- /dev/null +++ b/share/docs/couchdb-manual-1.1/couchdb-manual.xml @@ -0,0 +1,65 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' + 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ +<!ENTITY % every.entities SYSTEM "entities.ent"> +%every.entities; +]> +<book id="couchdb-__meta_version_id__"> + + <title>CouchDB __meta_version__ Manual</title> + + <bookinfo> + + <abstract> + + <para> + This manual documents the CouchDB + __meta_version__ database system, including the installation, + functionality, and CouchDB API. + </para> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="../common/docbuilddate.xml"/> + + </abstract> + + </bookinfo> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="couchdb-introduction.xml"/> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="couchdb-features.xml"/> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="couchdb-replication.xml"/> + +<!-- + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="metadoc-couchdb-changes.xml"/> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="couchdb-dbmaint.xml"/> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="couchdb-views.xml"/> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="couchdb-backuprestore.xml"/> +--> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="couchdb-api-introduction.xml"/> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="metadoc-couchdb-api-db.xml"/> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="metadoc-couchdb-api-dbdoc.xml"/> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="metadoc-couchdb-api-localdb.xml"/> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="metadoc-couchdb-api-design.xml"/> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="metadoc-couchdb-api-misc.xml"/> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="metadoc-couchdb-api-config.xml"/> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="metadoc-couchdb-api-auth.xml"/> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="couchdb-configuration.xml"/> + +<!-- Appendices --> + + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="metadoc-couchdb-api-json.xml"/> + +</book>
http://git-wip-us.apache.org/repos/asf/couchdb/blob/1055ea0e/share/docs/couchdb-manual-1.1/couchdb-replication.xml ---------------------------------------------------------------------- diff --git a/share/docs/couchdb-manual-1.1/couchdb-replication.xml b/share/docs/couchdb-manual-1.1/couchdb-replication.xml new file mode 100644 index 0000000..a62a884 --- /dev/null +++ b/share/docs/couchdb-manual-1.1/couchdb-replication.xml @@ -0,0 +1,554 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' + 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ +<!ENTITY % every.entities SYSTEM "entities.ent"> +%every.entities; +]> +<chapter id="couchdb-single-replication"> + + <title>Replication</title> + + <para> + + </para> + + <section id="couchdb-single-replication-replicatordb"> + + <title>Replicator Database</title> + + <para> + A database where you + <literal>PUT</literal>/<literal>POST</literal> documents to + trigger replications and you <literal>DELETE</literal> to cancel + ongoing replications. These documents have exactly the same + content as the JSON objects we used to <literal>POST</literal> to + <literal>_replicate</literal> (fields <literal>source</literal>, + <literal>target</literal>, <literal>create_target</literal>, + <literal>continuous</literal>, <literal>doc_ids</literal>, + <literal>filter</literal>, <literal>query_params</literal>. + </para> + + <para> + Replication documents can have a user defined + <literal>_id</literal>. Design documents (and + <literal>_local</literal> documents) added to the replicator + database are ignored. + </para> + + <para> + The default name of this database is + <literal>_replicator</literal>. The name can be changed in the + <filename>local.ini</filename> configuration, section + <literal>[replicator]</literal>, parameter <literal>db</literal>. + </para> + + <section id="couchdb-single-replication-replicatordb-basics"> + + <title>Basics</title> + + <para> + Let's say you PUT the following document into _replicator: + </para> + +<programlisting> +{ + "_id": "my_rep", + "source": "http://myserver.com:5984/foo";, + "target": "bar", + "create_target": true +} +</programlisting> + + <para> + In the couch log you'll see 2 entries like these: + </para> + +<programlisting> +[Thu, 17 Feb 2011 19:43:59 GMT] [info] [<0.291.0>] Document `my_rep` triggered replication `c0ebe9256695ff083347cbf95f93e280+create_target` +[Thu, 17 Feb 2011 19:44:37 GMT] [info] [<0.124.0>] Replication `c0ebe9256695ff083347cbf95f93e280+create_target` finished (triggered by document `my_rep`) +</programlisting> + + <para> + As soon as the replication is triggered, the document will be + updated by CouchDB with 3 new fields: + </para> + +<programlisting> +{ + "_id": "my_rep", + "source": "http://myserver.com:5984/foo";, + "target": "bar", + "create_target": true, + "_replication_id": "c0ebe9256695ff083347cbf95f93e280", + "_replication_state": "triggered", + "_replication_state_time": 1297974122 +} +</programlisting> + + <para> + Special fields set by the replicator start with the prefix + <literal>_replication_</literal>. + </para> + + <itemizedlist> + + <listitem> + <para> + <literal>_replication_id</literal> + </para> + + <para> + The ID internally assigned to the replication. This is also + the ID exposed by <literal>/_active_tasks</literal>. + </para> + </listitem> + + <listitem> + <para> + <literal>_replication_state</literal> + </para> + + <para> + The current state of the replication. + </para> + </listitem> + + <listitem> + <para> + <literal>_replication_state_time</literal> + </para> + + <para> + A Unix timestamp (number of seconds since 1 Jan 1970) that + tells us when the current replication state (marked in + <literal>_replication_state</literal>) was set. + </para> + </listitem> + + </itemizedlist> + + <para> + When the replication finishes, it will update the + <literal>_replication_state</literal> field (and + <literal>_replication_state_time</literal>) with the value + <literal>completed</literal>, so the document will look like: + </para> + +<programlisting> +{ + "_id": "my_rep", + "source": "http://myserver.com:5984/foo";, + "target": "bar", + "create_target": true, + "_replication_id": "c0ebe9256695ff083347cbf95f93e280", + "_replication_state": "completed", + "_replication_state_time": 1297974122 +} +</programlisting> + + <para> + When an error happens during replication, the + <literal>_replication_state</literal> field is set to + <literal>error</literal> (and + <literal>_replication_state</literal> gets updated of course). + </para> + + <para> + When you PUT/POST a document to the + <literal>_replicator</literal> database, CouchDB will attempt to + start the replication up to 10 times (configurable under + <literal>[replicator]</literal>, parameter + <literal>max_replication_retry_count</literal>). If it fails on + the first attempt, it waits 5 seconds before doing a second + attempt. If the second attempt fails, it waits 10 seconds before + doing a third attempt. If the third attempt fails, it waits 20 + seconds before doing a fourth attempt (each attempt doubles the + previous wait period). When an attempt fails, the Couch log will + show you something like: + </para> + +<programlisting> +[error] [<0.149.0>] Error starting replication `67c1bb92010e7abe35d7d629635f18b6+create_target` (document `my_rep_2`): {db_not_found,<<"could not open http://myserver:5986/foo/">> +</programlisting> + + <note> + <para> + The <literal>_replication_state</literal> field is only set to + <literal>error</literal> when all the attempts were + unsuccessful. + </para> + </note> + + <para> + There are only 3 possible values for the + <literal>_replication_state</literal> field: + <literal>triggered</literal>, <literal>completed</literal> and + <literal>error</literal>. Continuous replications never get + their state set to <literal>completed</literal>. + </para> + + </section> + + <section id="couchdb-single-replication-replicatordb-docsame"> + + <title>Documents describing the same replication</title> + + <para> + Lets suppose 2 documents are added to the + <literal>_replicator</literal> database in the following order: + </para> + +<programlisting> +{ + "_id": "doc_A", + "source": "http://myserver.com:5984/foo";, + "target": "bar" +} +</programlisting> + + <para> + and + </para> + +<programlisting> +{ + "_id": "doc_B", + "source": "http://myserver.com:5984/foo";, + "target": "bar" +} +</programlisting> + + <para> + Both describe exactly the same replication (only their + <literal>_ids</literal> differ). In this case document + <literal>doc_A</literal> triggers the replication, getting + updated by CouchDB with the fields + <literal>_replication_state</literal>, + <literal>_replication_state_time</literal> and + <literal>_replication_id</literal>, just like it was described + before. Document <literal>doc_B</literal> however, is only + updated with one field, the <literal>_replication_id</literal> + so it will look like this: + </para> + +<programlisting> +{ + "_id": "doc_B", + "source": "http://myserver.com:5984/foo";, + "target": "bar", + "_replication_id": "c0ebe9256695ff083347cbf95f93e280" +} +</programlisting> + + <para> + While document <literal>doc_A</literal> will look like this: + </para> + +<programlisting> +{ + "_id": "doc_A", + "source": "http://myserver.com:5984/foo";, + "target": "bar", + "_replication_id": "c0ebe9256695ff083347cbf95f93e280", + "_replication_state": "triggered", + "_replication_state_time": 1297974122 +} +</programlisting> + + <para> + Note that both document get exactly the same value for the + <literal>_replication_id</literal> field. This way you can + identify which documents refer to the same replication - you can + for example define a view which maps replication IDs to document + IDs. + </para> + + </section> + + <section id="couchdb-single-replication-replicatordb-cancel"> + + <title>Canceling replications</title> + + <para> + To cancel a replication simply <literal>DELETE</literal> the + document which triggered the replication. The Couch log will + show you an entry like the following: + </para> + +<programlisting> +[Thu, 17 Feb 2011 20:16:29 GMT] [info] [<0.125.0>] Stopped replication `c0ebe9256695ff083347cbf95f93e280+continuous+create_target` because replication document `doc_A` was deleted +</programlisting> + + <note> + <para> + You need to <literal>DELETE</literal> the document that + triggered the replication. <literal>DELETE</literal>ing + another document that describes the same replication but did + not trigger it, will not cancel the replication. + </para> + </note> + + </section> + + <section id="couchdb-single-replication-replicatordb-restart"> + + <title>Server restart</title> + + <para> + When CouchDB is restarted, it checks its + <literal>_replicator</literal> database and restarts any + replication that is described by a document that either has its + <literal>_replication_state</literal> field set to + <literal>triggered</literal> or it doesn't have yet the + <literal>_replication_state</literal> field set. + </para> + + <note> + <para> + Continuous replications always have a + <literal>_replication_state</literal> field with the value + <literal>triggered</literal>, therefore they're always + restarted when CouchDB is restarted. + </para> + </note> + + </section> + + <section id="couchdb-single-replication-replicatordb-changing"> + + <title>Changing the Replicator Database</title> + + <para> + Imagine your replicator database (default name is _replicator) + has the two following documents that represent pull replications + from servers A and B: + </para> + +<programlisting> +{ + "_id": "rep_from_A", + "source": "http://aserver.com:5984/foo";, + "target": "foo_a", + "continuous": true, + "_replication_id": "c0ebe9256695ff083347cbf95f93e280", + "_replication_state": "triggered", + "_replication_state_time": 1297971311 +} +{ + "_id": "rep_from_B", + "source": "http://bserver.com:5984/foo";, + "target": "foo_b", + "continuous": true, + "_replication_id": "231bb3cf9d48314eaa8d48a9170570d1", + "_replication_state": "triggered", + "_replication_state_time": 1297974122 +} +</programlisting> + + <para> + Now without stopping and restarting CouchDB, you change the name + of the replicator database to + <literal>another_replicator_db</literal>: + </para> + +<programlisting> +$ curl -X PUT http://localhost:5984/_config/replicator/db -d '"another_replicator_db"' +"_replicator" +</programlisting> + + <para> + As soon as this is done, both pull replications defined before, + are stopped. This is explicitly mentioned in CouchDB's log: + </para> + +<programlisting><![CDATA[ +[Fri, 11 Mar 2011 07:44:20 GMT] [info] [<0.104.0>] Stopping all ongoing replications because the replicator database was deleted or changed +[Fri, 11 Mar 2011 07:44:20 GMT] [info] [<0.127.0>] 127.0.0.1 - - PUT /_config/replicator/db 200 +]]> +</programlisting> + + <para> + Imagine now you add a replication document to the new replicator + database named <literal>another_replicator_db</literal>: + </para> + +<programlisting> +{ + "_id": "rep_from_X", + "source": "http://xserver.com:5984/foo";, + "target": "foo_x", + "continuous": true +} +</programlisting> + + <para> + From now own you have a single replication going on in your + system: a pull replication pulling from server X. Now you change + back the replicator database to the original one + <literal>_replicator</literal>: + </para> + +<programlisting> +$ curl -X PUT http://localhost:5984/_config/replicator/db -d '"_replicator"' +"another_replicator_db" +</programlisting> + + <para> + Immediately after this operation, the replication pulling from + server X will be stopped and the replications defined in the + _replicator database (pulling from servers A and B) will be + resumed. + </para> + + <para> + Changing again the replicator database to + <literal>another_replicator_db</literal> will stop the pull + replications pulling from servers A and B, and resume the pull + replication pulling from server X. + </para> + + </section> + + <section id="couchdb-single-replication-replicatordb-replicating"> + + <title>Replicating the replicator database</title> + + <para> + Imagine you have in server C a replicator database with the two + following pull replication documents in it: + </para> + +<programlisting> +{ + "_id": "rep_from_A", + "source": "http://aserver.com:5984/foo";, + "target": "foo_a", + "continuous": true, + "_replication_id": "c0ebe9256695ff083347cbf95f93e280", + "_replication_state": "triggered", + "_replication_state_time": 1297971311 +} +{ + "_id": "rep_from_B", + "source": "http://bserver.com:5984/foo";, + "target": "foo_b", + "continuous": true, + "_replication_id": "231bb3cf9d48314eaa8d48a9170570d1", + "_replication_state": "triggered", + "_replication_state_time": 1297974122 +} +</programlisting> + + <para> + Now you would like to have the same pull replications going on + in server D, that is, you would like to have server D pull + replicating from servers A and B. You have two options: + </para> + + <itemizedlist> + + <listitem> + <para> + Explicitly add two documents to server's D replicator + database + </para> + </listitem> + + <listitem> + <para> + Replicate server's C replicator database into server's D + replicator database + </para> + </listitem> + + </itemizedlist> + + <para> + Both alternatives accomplish exactly the same goal. + </para> + + </section> + + <section id="couchdb-single-replication-replicatordb-delegations"> + + <title>Delegations</title> + + <para> + Replication documents can have a custom + <literal>user_ctx</literal> property. This property defines the + user context under which a replication runs. For the old way of + triggering replications (POSTing to + <literal>/_replicate/</literal>), this property was not needed + (it didn't exist in fact) - this is because at the moment of + triggering the replication it has information about the + authenticated user. With the replicator database, since it's a + regular database, the information about the authenticated user + is only present at the moment the replication document is + written to the database - the replicator database implementation + is like a _changes feed consumer (with + <literal>?include_docs=true</literal>) that reacts to what was + written to the replicator database - in fact this feature could + be implemented with an external script/program. This + implementation detail implies that for non admin users, a + <literal>user_ctx</literal> property, containing the user's name + and a subset of his/her roles, must be defined in the + replication document. This is ensured by the document update + validation function present in the default design document of + the replicator database. This validation function also ensure + that a non admin user can set a user name property in the + <literal>user_ctx</literal> property that doesn't match his/her + own name (same principle applies for the roles). + </para> + + <para> + For admins, the <literal>user_ctx</literal> property is + optional, and if it's missing it defaults to a user context with + name null and an empty list of roles - this mean design + documents will not be written to local targets. If writing + design documents to local targets is desired, the a user context + with the roles <literal>_admin</literal> must be set explicitly. + </para> + + <para> + Also, for admins the <literal>user_ctx</literal> property can be + used to trigger a replication on behalf of another user. This is + the user context that will be passed to local target database + document validation functions. + </para> + + <note> + <para> + The <literal>user_ctx</literal> property only has effect for + local endpoints. + </para> + </note> + + <para> + Example delegated replication document: + </para> + +<programlisting> +{ + "_id": "my_rep", + "source": "http://bserver.com:5984/foo";, + "target": "bar", + "continuous": true, + "user_ctx": { + "name": "joe", + "roles": ["erlanger", "researcher"] + } +} +</programlisting> + + <para> + As stated before, for admins the user_ctx property is optional, + while for regular (non admin) users it's mandatory. When the + roles property of <literal>user_ctx</literal> is missing, it + defaults to the empty list <literal>[ ]</literal>. + </para> + + </section> + + </section> + +</chapter> http://git-wip-us.apache.org/repos/asf/couchdb/blob/1055ea0e/share/docs/couchdb-manual-1.1/couchdb-single-troubleshooting.xml ---------------------------------------------------------------------- diff --git a/share/docs/couchdb-manual-1.1/couchdb-single-troubleshooting.xml b/share/docs/couchdb-manual-1.1/couchdb-single-troubleshooting.xml new file mode 100644 index 0000000..5d72456 --- /dev/null +++ b/share/docs/couchdb-manual-1.1/couchdb-single-troubleshooting.xml @@ -0,0 +1,35 @@ + <section id="couchdb-single-features-errormessages"> + + <title>Error Messages</title> + + <para> + 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. + </para> + + <para> + 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: + </para> + +<programlisting> +shell> <userinput>curl -H 'X-Couch-Persist: true' -X PUT http://couchdb:5984/_config/couchdb/delayed_commits -d '"false"'</userinput> +{"error":"file_permission_error","reason":"/etc/couchdb/local.ini"} + </programlisting> + + <para> + Errors will always be reported using the + <literal>file_permission_error</literal> error type. + </para> + + <para> + 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. + </para> + + </section> http://git-wip-us.apache.org/repos/asf/couchdb/blob/1055ea0e/share/docs/couchdb-manual-1.1/couchdb-views.xml ---------------------------------------------------------------------- diff --git a/share/docs/couchdb-manual-1.1/couchdb-views.xml b/share/docs/couchdb-manual-1.1/couchdb-views.xml new file mode 100644 index 0000000..2056d29 --- /dev/null +++ b/share/docs/couchdb-manual-1.1/couchdb-views.xml @@ -0,0 +1,15 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' + 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ +<!ENTITY % every.entities SYSTEM "entities.ent"> +%every.entities; +]> +<chapter id="couchdb-single-views"> + + <title>Views</title> + + <para> + + </para> + +</chapter> http://git-wip-us.apache.org/repos/asf/couchdb/blob/1055ea0e/share/docs/couchdb-manual-1.1/images/futon-createdb.png ---------------------------------------------------------------------- diff --git a/share/docs/couchdb-manual-1.1/images/futon-createdb.png b/share/docs/couchdb-manual-1.1/images/futon-createdb.png new file mode 100644 index 0000000..eb152c6 Binary files /dev/null and b/share/docs/couchdb-manual-1.1/images/futon-createdb.png differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/1055ea0e/share/docs/couchdb-manual-1.1/images/futon-editdoc.png ---------------------------------------------------------------------- diff --git a/share/docs/couchdb-manual-1.1/images/futon-editdoc.png b/share/docs/couchdb-manual-1.1/images/futon-editdoc.png new file mode 100644 index 0000000..b3b5a51 Binary files /dev/null and b/share/docs/couchdb-manual-1.1/images/futon-editdoc.png differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/1055ea0e/share/docs/couchdb-manual-1.1/images/futon-editeddoc.png ---------------------------------------------------------------------- diff --git a/share/docs/couchdb-manual-1.1/images/futon-editeddoc.png b/share/docs/couchdb-manual-1.1/images/futon-editeddoc.png new file mode 100644 index 0000000..e44ed18 Binary files /dev/null and b/share/docs/couchdb-manual-1.1/images/futon-editeddoc.png differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/1055ea0e/share/docs/couchdb-manual-1.1/images/futon-overview.png ---------------------------------------------------------------------- diff --git a/share/docs/couchdb-manual-1.1/images/futon-overview.png b/share/docs/couchdb-manual-1.1/images/futon-overview.png new file mode 100644 index 0000000..9ecde97 Binary files /dev/null and b/share/docs/couchdb-manual-1.1/images/futon-overview.png differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/1055ea0e/share/docs/couchdb-manual-1.1/images/futon-replform.png ---------------------------------------------------------------------- diff --git a/share/docs/couchdb-manual-1.1/images/futon-replform.png b/share/docs/couchdb-manual-1.1/images/futon-replform.png new file mode 100644 index 0000000..9fd9a1d Binary files /dev/null and b/share/docs/couchdb-manual-1.1/images/futon-replform.png differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/1055ea0e/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-auth.xml ---------------------------------------------------------------------- diff --git a/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-auth.xml b/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-auth.xml new file mode 100644 index 0000000..3c4762b --- /dev/null +++ b/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-auth.xml @@ -0,0 +1,40 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' + 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ +<!ENTITY % every.entities SYSTEM "entities.ent"> +%every.entities; +]> +<chapter id="couchdb-api-auth"> + + <title>CouchDB API Server Authentication Methods</title> + + <para> + The CouchDB Authentication methods provide an interface for + obtaining session and authorization data. + </para> + + <para> + A list of the available methods and URL paths are provided below: + </para> + + <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> +<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> +<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> +<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> +<table id="table-couchdb-api-auth-summary"><title>Authentication API Calls</title><tgroup cols="3"><colspec colname="method"/><colspec colname="path"/><colspec colname="desc"/><thead><row><entry>Method</entry><entry>Path</entry><entry>Description</entry></row></thead><tbody><row><entry><literal>GET</literal></entry><entry><literal>/_oauth/access_token</literal></entry><entry><link linkend="couchdb-api-auth_access-token_get"> + TBC + </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/_oauth/authorize</literal></entry><entry><link linkend="couchdb-api-auth_authorize_get"> + TBC + </link></entry></row><row><entry><literal>POST</literal></entry><entry><literal>/_oauth/authorize</literal></entry><entry><link linkend="couchdb-api-auth_authorize_post"> + TBC + </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/_oauth/request_token</literal></entry><entry><link linkend="couchdb-api-auth_authorize_get"> + TBC + </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/_session</literal></entry><entry><link linkend="couchdb-api-auth_session_get"> + Returns cookie based login user information + </link></entry></row><row><entry><literal>POST</literal></entry><entry><literal>/_session</literal></entry><entry><link linkend="couchdb-api-auth_session_post"> + Do cookie based user login + </link></entry></row><row><entry><literal>DELETE</literal></entry><entry><literal>/_session</literal></entry><entry><link linkend="couchdb-api-auth_session_delete"> + Logout cookie based user + </link></entry></row></tbody></tgroup></table> + +</chapter> http://git-wip-us.apache.org/repos/asf/couchdb/blob/1055ea0e/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-config.xml ---------------------------------------------------------------------- diff --git a/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-config.xml b/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-config.xml new file mode 100644 index 0000000..d7af033 --- /dev/null +++ b/share/docs/couchdb-manual-1.1/metadoc-couchdb-api-config.xml @@ -0,0 +1,348 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN' + 'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [ +<!ENTITY % every.entities SYSTEM "entities.ent"> +%every.entities; +]> +<chapter id="couchdb-api-config"> + + <title>CouchDB API Server Configuration Methods</title> + + <para> + The CouchDB API Server Configuration Methods provide an interface to + query and update the various configuration values within a running + CouchDB instance. + </para> + + <para> + A list of the available methods and URL paths are provided below: + </para> + + <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> +<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> +<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> +<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> +<table id="table-couchdb-api-config-summary"><title>Configuration API Calls</title><tgroup cols="3"><colspec colname="method"/><colspec colname="path"/><colspec colname="desc"/><thead><row><entry>Method</entry><entry>Path</entry><entry>Description</entry></row></thead><tbody><row><entry><literal>GET</literal></entry><entry><literal>/_config</literal></entry><entry><link linkend="couchdb-api-config_config_get"> + Obtain a list of the entire server configuration + </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/_config/section</literal></entry><entry><link linkend="couchdb-api-config_config-section_get"> + Get all the configuration values for the specified section + </link></entry></row><row><entry><literal>GET</literal></entry><entry><literal>/_config/section/key</literal></entry><entry><link linkend="couchdb-api-config_config-section-key_get"> + Get a specific section/configuration value + </link></entry></row><row><entry><literal>PUT</literal></entry><entry><literal>/_config/section/key</literal></entry><entry><link linkend="couchdb-api-config_config-section-key_put"> + Set the specified configuration value + </link></entry></row><row><entry><literal>DELETE</literal></entry><entry><literal>/_config/section/key</literal></entry><entry><link linkend="couchdb-api-config_config-section-key_delete"> + Delete the current setting + </link></entry></row></tbody></tgroup></table> + + <section id="couchdb-api-config_config_get"> + + <title><literal>GET /_config</literal></title> + + <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> +<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> +<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> +<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> +<informaltable><textobject><phrase>URL API GET /_config</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /_config</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> + None + </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> + Returns a structure configuration name and value pairs, + organized by section + </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> + + <para> + Returns the entire CouchDB server configuration as a JSON + structure. The structure is organized by different configuration + sections, with individual values. + </para> + + <para> + For example, to get the configuration for a server: + </para> + +<programlisting> +GET http://couchdb:5984/_config +Accept: application/json +</programlisting> + + <para> + The response is the JSON structure: + </para> + +<programlisting> +<![CDATA[{ + "query_server_config" : { + "reduce_limit" : "true" + }, + "couchdb" : { + "os_process_timeout" : "5000", + "max_attachment_chunk_size" : "4294967296", + "max_document_size" : "4294967296", + "uri_file" : "/var/lib/couchdb/couch.uri", + "max_dbs_open" : "100", + "view_index_dir" : "/var/lib/couchdb", + "util_driver_dir" : "/usr/lib64/couchdb/erlang/lib/couch-1.0.1/priv/lib", + "database_dir" : "/var/lib/couchdb", + "delayed_commits" : "true" + }, + "attachments" : { + "compressible_types" : "text/*, application/javascript, application/json, application/xml", + "compression_level" : "8" + }, + "uuids" : { + "algorithm" : "utc_random" + }, + "daemons" : { + "view_manager" : "{couch_view, start_link, []}", + "auth_cache" : "{couch_auth_cache, start_link, []}", + "uuids" : "{couch_uuids, start, []}", + "stats_aggregator" : "{couch_stats_aggregator, start, []}", + "query_servers" : "{couch_query_servers, start_link, []}", + "httpd" : "{couch_httpd, start_link, []}", + "stats_collector" : "{couch_stats_collector, start, []}", + "db_update_notifier" : "{couch_db_update_notifier_sup, start_link, []}", + "external_manager" : "{couch_external_manager, start_link, []}" + }, + "stats" : { + "samples" : "[0, 60, 300, 900]", + "rate" : "1000" + }, + "httpd" : { + "vhost_global_handlers" : "_utils, _uuids, _session, _oauth, _users", + "secure_rewrites" : "true", + "authentication_handlers" : "{couch_httpd_oauth, oauth_authentication_handler}, + {couch_httpd_auth, cookie_authentication_handler}, + {couch_httpd_auth, default_authentication_handler}", + "port" : "5984", + "default_handler" : "{couch_httpd_db, handle_request}", + "allow_jsonp" : "false", + "bind_address" : "192.168.0.2", + "max_connections" : "2048" + }, + "query_servers" : { + "javascript" : "/usr/bin/couchjs /usr/share/couchdb/server/main.js" + }, + "couch_httpd_auth" : { + "authentication_db" : "_users", + "require_valid_user" : "false", + "authentication_redirect" : "/_utils/session.html", + "timeout" : "600", + "auth_cache_size" : "50" + }, + "httpd_db_handlers" : { + "_design" : "{couch_httpd_db, handle_design_req}", + "_compact" : "{couch_httpd_db, handle_compact_req}", + "_view_cleanup" : "{couch_httpd_db, handle_view_cleanup_req}", + "_temp_view" : "{couch_httpd_view, handle_temp_view_req}", + "_changes" : "{couch_httpd_db, handle_changes_req}" + }, + "replicator" : { + "max_http_sessions" : "10", + "max_http_pipeline_size" : "10" + }, + "log" : { + "include_sasl" : "true", + "level" : "info", + "file" : "/var/log/couchdb/couch.log" + }, + "httpd_design_handlers" : { + "_update" : "{couch_httpd_show, handle_doc_update_req}", + "_show" : "{couch_httpd_show, handle_doc_show_req}", + "_info" : "{couch_httpd_db, handle_design_info_req}", + "_list" : "{couch_httpd_show, handle_view_list_req}", + "_view" : "{couch_httpd_view, handle_view_req}", + "_rewrite" : "{couch_httpd_rewrite, handle_rewrite_req}" + }, + "httpd_global_handlers" : { + "_replicate" : "{couch_httpd_misc_handlers, handle_replicate_req}", + "/" : "{couch_httpd_misc_handlers, handle_welcome_req, <<\"Welcome\">>}", + "_config" : "{couch_httpd_misc_handlers, handle_config_req}", + "_utils" : "{couch_httpd_misc_handlers, handle_utils_dir_req, \"/usr/share/couchdb/www\"}", + "_active_tasks" : "{couch_httpd_misc_handlers, handle_task_status_req}", + "_session" : "{couch_httpd_auth, handle_session_req}", + "_log" : "{couch_httpd_misc_handlers, handle_log_req}", + "favicon.ico" : "{couch_httpd_misc_handlers, handle_favicon_req, \"/usr/share/couchdb/www\"}", + "_all_dbs" : "{couch_httpd_misc_handlers, handle_all_dbs_req}", + "_oauth" : "{couch_httpd_oauth, handle_oauth_req}", + "_restart" : "{couch_httpd_misc_handlers, handle_restart_req}", + "_uuids" : "{couch_httpd_misc_handlers, handle_uuids_req}", + "_stats" : "{couch_httpd_stats_handlers, handle_stats_req}" + } +}]]> + </programlisting> + + </section> + + <section id="couchdb-api-config_config-section_get"> + + <title><literal>GET /_config/section</literal></title> + + <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> +<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> +<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> +<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> +<informaltable><textobject><phrase>URL API GET /_config/section</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /_config/section</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> + None + </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> + All the configuration values within a specified section + </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> + + <para> + Gets the configuration structure for a single section. For + example, to retrieve the CouchDB configuration section values: + </para> + +<programlisting> +GET http://couchdb:5984/_config/couchdb +Accept: application/json +</programlisting> + + <para> + The returned JSON contains just the configuration values for this + section: + </para> + +<programlisting> +{ + "os_process_timeout" : "5000", + "max_attachment_chunk_size" : "4294967296", + "max_document_size" : "4294967296", + "uri_file" : "/var/lib/couchdb/couch.uri", + "max_dbs_open" : "100", + "view_index_dir" : "/var/lib/couchdb", + "util_driver_dir" : "/usr/lib64/couchdb/erlang/lib/couch-1.0.1/priv/lib", + "database_dir" : "/var/lib/couchdb", + "delayed_commits" : "true" +} +</programlisting> + + </section> + + <section id="couchdb-api-config_config-section-key_get"> + + <title><literal>GET /_config/section/key</literal></title> + + <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> +<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> +<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> +<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> +<informaltable><textobject><phrase>URL API GET /_config/section/key</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>GET /_config/section/key</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> + None + </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> + Value of the specified key/section + </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row></tbody></tgroup></informaltable> + + <para> + Gets a single configuration value from within a specific + configuration section. For example, to obtain the current log + level: + </para> + +<programlisting> +GET http://couchdb:5984/_config/log/level +Accept: application/json +</programlisting> + + <para> + Returns the string of the log level: + </para> + +<programlisting> +"info" +</programlisting> + + <note> + <para> + 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. + </para> + </note> + + </section> + + <section id="couchdb-api-config_config-section-key_put"> + + <title><literal>PUT /_config/section/key</literal></title> + + <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> +<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> +<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> +<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> +<informaltable><textobject><phrase>URL API PUT /_config/section/key</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>PUT /_config/section/key</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> + Value structure + </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> + Previous value + </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>200</entry><entry namest="info" nameend="addinfo"> + Configuration option updated successfully + </entry></row><row><entry>500</entry><entry namest="info" nameend="addinfo"> + Error setting configuration + </entry></row></tbody></tgroup></informaltable> + + <para> + Updates a configuration value. The new value should be supplied in + the request body in the corresponding JSON format. For example, if + you are setting a string value, you must supply a valid JSON + string. + </para> + + <para> + For example, to set the function used to generate UUIDs by the + <literal>GET /_uuids</literal> API call to use the + <literal>utc_random</literal> generator: + </para> + +<programlisting> +PUT http://couchdb:5984/_config/uuids/algorithm +Content-Type: application/json + +"utc_random" +</programlisting> + + <para> + The return value will be empty, with the response code indicating + the success or failure of the configuration setting. + </para> + + </section> + + <section id="couchdb-api-config_config-section-key_delete"> + + <title><literal>DELETE /_config/section/key</literal></title> + + <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/> +<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/> +<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/> +<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/> +<informaltable><textobject><phrase>URL API DELETE /_config/section/key</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal>DELETE /_config/section/key</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo"> + None + </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo"> + Previous value + </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry><emphasis role="bold">Query Arguments</emphasis></entry><entry><emphasis role="bold">Argument</emphasis></entry><entry><literal>rev</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry> + Current revision of the document for validation + </entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry><emphasis role="bold">Type</emphasis></entry><entry>string</entry></row><row><entry><emphasis role="bold">HTTP Headers</emphasis></entry><entry><emphasis role="bold">Header</emphasis></entry><entry><literal>If-Match</literal></entry></row><row><entry></entry><entry><emphasis role="bold">Description</emphasis></entry><entry>Current revision of the document for validation</entry></row><row><entry></entry><entry><emphasis role="bold">Optional</emphasis></entry><entry>yes</entry></row><row><entry></entry><entry></entry><entry></entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>409</entry><entry namest="info" nameend="addinfo"> + Supplied revision is incorrect or missing + </entry></row></tbody></tgroup></informaltable> + + <para> + Deletes a configuration value. The returned JSON will be the value + of the configuration parameter before it was deleted. For example, + to delete the UUID parameter: + </para> + +<programlisting> +DELETE http://couchdb:5984/_config/uuids/algorithm +Content-Type: application/json +</programlisting> + + <para> + The returned value is the last configured UUID function: + </para> + +<programlisting> +"random" +</programlisting> + + </section> + +</chapter>
