Skip to content

Commit

Permalink
Documentation: Add adm:pass to replication endpoint URL (#4457)
Browse files Browse the repository at this point in the history 
When using replication, we need to specify a username and password
(`adm:pass` / `admin:password`) for the replication endpoint URL,
otherwise a 401 unauthorized error will be thrown.

Co-authored-by: jiahuili <Jiahui.Li@ibm.com>
  • Loading branch information
@jiahuili430
jiahuili430 and jiahuili committed Mar 6, 2023
1 parent 5aed161 commit 0db9154
Show file tree
Hide file tree
Showing 4 changed files with 65 additions and 60 deletions.
4 changes: 2 additions & 2 deletions src/docs/src/api/server/common.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -764,8 +764,8 @@
Host: localhost:5984
{
"source": "http://127.0.0.1:5984/db_a",
"target": "http://127.0.0.1:5984/db_b"
"source": "http://adm:pass@127.0.0.1:5984/db_a",
"target": "http://adm:pass@127.0.0.1:5984/db_b"
}
**Response**
Expand Down
43 changes: 24 additions & 19 deletions src/docs/src/intro/api.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -613,8 +613,8 @@ easy to make)::

Now we can use the database `albums-replica` as a replication target::

curl -vX POST http://admin:password@127.0.0.1:5984/_replicate \
-d '{"source":"http://127.0.0.1:5984/albums","target":"http://127.0.0.1:5984/albums-replica"}' \
curl -X POST http://adm:pass@127.0.0.1:5984/_replicate \
-d '{"source":"http://adm:pass@127.0.0.1:5984/albums","target":"http://adm:pass@127.0.0.1:5984/albums-replica"}' \
-H "Content-Type: application/json"

.. note::
Expand All @@ -632,22 +632,27 @@ easily):
.. code-block:: javascript
{
"ok": true,
"session_id": "30bb4ac013ca69369c0f32be78864d6e",
"source_last_seq": "2-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYExlzgQLsBiaphqYpSZjKcRqRxwIkGRqA1H8Uk4wszJIskg0wdWUBAFHwJD4",
"replication_id_version": 4,
"history": [
{
"session_id": "30bb4ac013ca69369c0f32be78864d6e",
"start_time": "Sun, 05 Mar 2023 20:30:26 GMT",
"end_time": "Sun, 05 Mar 2023 20:30:29 GMT",
"start_last_seq": 0,
"end_last_seq": "2-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYExlzgQLsBiaphqYpSZjKcRqRxwIkGRqA1H8Uk4wszJIskg0wdWUBAFHwJD4",
"recorded_seq": "2-g1AAAACTeJzLYWBgYMpgTmHgz8tPSTV0MDQy1zMAQsMckEQiQ1L9____szKYExlzgQLsBiaphqYpSZjKcRqRxwIkGRqA1H8Uk4wszJIskg0wdWUBAFHwJD4",
"missing_checked": 2,
"missing_found": 2,
"docs_read": 2,
"end_last_seq": 5,
"missing_checked": 2,
"docs_written": 2,
"doc_write_failures": 0,
"end_time": "Sat, 11 Jul 2009 17:36:21 GMT",
"start_time": "Sat, 11 Jul 2009 17:36:20 GMT"
"bulk_get_docs": 2,
"bulk_get_attempts": 2
}
],
"source_last_seq": 5,
"session_id": "924e75e914392343de89c99d29d06671",
"ok": true
]
}
CouchDB maintains a *session history* of replications. The response for a
Expand All @@ -660,8 +665,8 @@ replication replicates the database only as it was at the point in time
when replication was started. So, any additions, modifications,
or deletions subsequent to the start of replication will not be replicated.

We'll punt on the details again -- the ``"ok": true`` at the end tells us all
went well. If you now have a look at the albums-replica database,
We'll punt on the details again -- the ``"ok": true`` at the beginning tells
us all went well. If you now have a look at the albums-replica database,
you should see all the documents that you created in the albums database.
Neat, eh?

Expand All @@ -676,8 +681,8 @@ and target members of our replication request are actually links (like in
HTML) and so far we've seen links relative to the server we're working on
(hence local). You can also specify a remote database as the target::

curl -vX POST http://admin:password@127.0.0.1:5984/_replicate \
-d '{"source":"http://127.0.0.1:5984/albums","target":"http://example.org:5984/albums-replica"}' \
curl -X POST http://adm:pass@127.0.0.1:5984/_replicate \
-d '{"source":"http://adm:pass@127.0.0.1:5984/albums","target":"http://user:password@example.org:5984/albums-replica"}' \
-H "Content-Type:application/json"

Using a *local source* and a *remote target* database is called *push
Expand All @@ -695,16 +700,16 @@ You can also use a *remote source* and a *local target* to do a *pull
replication*. This is great for getting the latest changes from a server that
is used by others::

curl -vX POST http://admin:password@127.0.0.1:5984/_replicate \
-d '{"source":"http://example.org:5984/albums-replica","target":"http://127.0.0.1:5984/albums"}' \
curl -X POST http://adm:pass@127.0.0.1:5984/_replicate \
-d '{"source":"http://user:password@example.org:5984/albums-replica","target":"http://adm:pass@127.0.0.1:5984/albums"}' \
-H "Content-Type:application/json"

Finally, you can run remote replication, which is mostly useful for management
operations::

curl -vX POST http://admin:password@127.0.0.1:5984/_replicate \
-d '{"source":"http://example.org:5984/albums","target":"http://example.org:5984/albums-replica"}' \
-H"Content-Type: application/json"
curl -X POST http://adm:pass@127.0.0.1:5984/_replicate \
-d '{"source":"http://user:password@example.org:5984/albums","target":"http://user:password@example.org:5984/albums-replica"}' \
-H "Content-Type: application/json"

.. note::
**CouchDB and REST**
Expand Down
8 changes: 4 additions & 4 deletions src/docs/src/replication/conflicts.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -270,7 +270,7 @@ Here's how to use it to find all conflicts in a database:

.. code-block:: bash
$ curl -X POST http://127.0.0.1/dbname/_find \
$ curl -X POST http://adm:pass@127.0.0.1:5984/dbname/_find \
-d '{"selector": {"_conflicts": { "$exists": true}}, "conflicts": true}' \
-Hcontent-type:application/json
Expand All @@ -289,7 +289,7 @@ index to speed the query:

.. code-block:: bash
$ curl -X POST http://127.0.0.1/dbname/_index \
$ curl -X POST http://adm:pass@127.0.0.1:5984/dbname/_index \
-d '{"index":{"fields": ["_conflicts"]}}' \
-Hcontent-type:application/json
Expand All @@ -307,7 +307,7 @@ to determine for each document whether it is in a conflicting state:

.. code-block:: bash
$ curl 'http://127.0.0.1:5984/conflict_test/_all_docs?include_docs=true&conflicts=true'
$ curl 'http://adm:pass@127.0.0.1:5984/conflict_test/_all_docs?include_docs=true&conflicts=true'
.. code-block:: javascript
Expand All @@ -330,7 +330,7 @@ to determine for each document whether it is in a conflicting state:
.. code-block:: bash
$ curl 'http://127.0.0.1:5984/conflict_test/test?conflicts=true'
$ curl 'http://adm:pass@127.0.0.1:5984/conflict_test/test?conflicts=true'
.. code-block:: javascript
Expand Down
70 changes: 35 additions & 35 deletions src/docs/src/replication/replicator.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,17 +56,17 @@ Let's say you POST the following document into ``_replicator``:
{
"_id": "my_rep",
"source": "http://myserver.com/foo",
"source": "http://user:password@myserver.com/foo",
"target": {
"url": "http://localhost:5984/bar",
"auth": {
"basic": {
"username": "user",
"username": "adm",
"password": "pass"
}
}
},
"create_target": true,
"create_target": true,
"continuous": true
}
Expand Down Expand Up @@ -181,17 +181,17 @@ For example, POST-ing this document
{
"_id": "my_rep_crashing",
"source": "http://myserver.com/missing",
"source": "http://user:password@myserver.com/missing",
"target": {
"url": "http://localhost:5984/bar",
"auth": {
"basic": {
"username": "user",
"username": "adm",
"password": "pass"
}
}
},
"create_target": true,
"create_target": true,
"continuous": true
}
Expand Down Expand Up @@ -252,16 +252,16 @@ normal.
Documents describing the same replication
=========================================

Lets suppose 2 documents are added to the ``_replicator`` database in
Let's suppose 2 documents are added to the ``_replicator`` database in
the following order:

.. code-block:: javascript
{
"_id": "my_rep",
"source": "http://myserver.com/foo",
"target": "http://user:pass@localhost:5984/bar",
"create_target": true,
"source": "http://user:password@myserver.com/foo",
"target": "http://adm:pass@localhost:5984/bar",
"create_target": true,
"continuous": true
}
Expand All @@ -271,9 +271,9 @@ and
{
"_id": "my_rep_dup",
"source": "http://myserver.com/foo",
"target": "http://user:pass@localhost:5984/bar",
"create_target": true,
"source": "http://user:password@myserver.com/foo",
"target": "http://adm:pass@localhost:5984/bar",
"create_target": true,
"continuous": true
}
Expand Down Expand Up @@ -517,56 +517,56 @@ which represent pull replications from servers A and B:
{
"_id": "rep_from_A",
"source": "http://aserver.com:5984/foo",
"source": "http://user:password@aserver.com:5984/foo",
"target": {
"url": "http://localhost:5984/foo_a",
"auth": {
"basic": {
"username": "user",
"username": "adm",
"password": "pass"
}
}
},
"continuous": true
"continuous": true
}
.. code-block:: javascript
{
"_id": "rep_from_B",
"source": "http://bserver.com:5984/foo",
"source": "http://user:password@bserver.com:5984/foo",
"target": {
"url": "http://localhost:5984/foo_b",
"auth": {
"basic": {
"username": "user",
"username": "adm",
"password": "pass"
}
}
},
"continuous": true
"continuous": true
}
Now without stopping and restarting CouchDB, add another replicator
database. For example ``another/_replicator``:

.. code-block:: bash
$ curl -X PUT http://user:pass@localhost:5984/another%2F_replicator/
$ curl -X PUT http://adm:pass@localhost:5984/another%2F_replicator/
{"ok":true}
.. note::
A / character in a database name, when used in a URL, should be escaped.
A ``/`` (%2F) character in a database name, when used in a URL, should be escaped.

Then add a replication document to the new replicator database:

.. code-block:: javascript
{
"_id": "rep_from_X",
"source": "http://xserver.com:5984/foo",
"target": "http://user:pass@localhost:5984/foo_x",
"continuous": true
"source": "http://user:password@xserver.com:5984/foo",
"target": "http://adm:pass@localhost:5984/foo_x",
"continuous": true
}
From now on, there are three replications active in the system: two
Expand All @@ -576,7 +576,7 @@ Then remove the additional replicator database:

.. code-block:: bash
$ curl -X DELETE http://user:pass@localhost:5984/another%2F_replicator/
$ curl -X DELETE http://adm:pass@localhost:5984/another%2F_replicator/
{"ok":true}
After this operation, replication pulling from server X will be stopped
Expand Down Expand Up @@ -633,18 +633,18 @@ following pull replication documents in it:
{
"_id": "rep_from_A",
"source": "http://aserver.com:5984/foo",
"target": "http://user:pass@localhost:5984/foo_a",
"continuous": true
"source": "http://user:password@aserver.com:5984/foo",
"target": "http://adm:pass@localhost:5984/foo_a",
"continuous": true
}
.. code-block:: javascript
{
"_id": "rep_from_B",
"source": "http://bserver.com:5984/foo",
"target": "http://user:pass@localhost:5984/foo_b",
"continuous": true
"source": "http://user:password@bserver.com:5984/foo",
"target": "http://adm:pass@localhost:5984/foo_b",
"continuous": true
}
Now you would like to have the same pull replications going on in server
Expand Down Expand Up @@ -697,9 +697,9 @@ Example delegated replication document:
{
"_id": "my_rep",
"source": "http://bserver.com:5984/foo",
"target": "http://user:pass@localhost:5984/bar",
"continuous": true,
"source": "http://user:password@bserver.com:5984/foo",
"target": "http://adm:pass@localhost:5984/bar",
"continuous": true,
"user_ctx": {
"name": "joe",
"roles": ["erlanger", "researcher"]
Expand Down Expand Up @@ -770,7 +770,7 @@ There are multiple ways to specify usernames and passwords for replication endpo
.. code-block:: javascript
{
"target": "http://user:pass@localhost:5984/bar"
"target": "http://adm:pass@localhost:5984/bar"
...
}
Expand Down

0 comments on commit 0db9154

Please sign in to comment.