couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From d..@apache.org
Subject [43/49] import CouchBase docs
Date Fri, 14 Sep 2012 10:17:00 GMT
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>
+    &nbsp;
+  </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] [&lt;0.291.0&gt;] Document `my_rep` triggered replication `c0ebe9256695ff083347cbf95f93e280+create_target`
+[Thu, 17 Feb 2011 19:44:37 GMT] [info] [&lt;0.124.0&gt;] 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] [&lt;0.149.0&gt;] Error starting replication `67c1bb92010e7abe35d7d629635f18b6+create_target` (document `my_rep_2`): {db_not_found,&lt;&lt;"could not open http://myserver:5986/foo/"&gt;&gt;
+</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] [&lt;0.125.0&gt;] 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&gt; <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>
+    &nbsp;
+  </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>


Mime
View raw message