You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by wo...@apache.org on 2020/01/29 18:21:48 UTC
[couchdb-documentation] branch 3.0.0-relnotes-2 created (now
a2a8bd5)
This is an automated email from the ASF dual-hosted git repository.
wohali pushed a change to branch 3.0.0-relnotes-2
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git.
at a2a8bd5 Fully remove mention of admin party everywhere
This branch includes the following new commits:
new a2a8bd5 Fully remove mention of admin party everywhere
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[couchdb-documentation] 01/01: Fully remove mention of admin party
everywhere
Posted by wo...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
wohali pushed a commit to branch 3.0.0-relnotes-2
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git
commit a2a8bd5d514d8b4a3dc708eb427799362832107b
Author: Joan Touzet <wo...@atypical.net>
AuthorDate: Wed Jan 29 13:21:33 2020 -0500
Fully remove mention of admin party everywhere
---
src/best-practices/reverse-proxies.rst | 14 +++-
src/config/auth.rst | 22 ++---
src/config/http.rst | 3 +-
src/intro/api.rst | 51 +++++++-----
src/intro/curl.rst | 42 ++++++----
src/intro/index.rst | 2 +-
src/intro/security.rst | 146 ++++++++++++++++-----------------
src/intro/tour.rst | 64 +++++++++------
templates/layout.html | 2 +-
9 files changed, 187 insertions(+), 159 deletions(-)
diff --git a/src/best-practices/reverse-proxies.rst b/src/best-practices/reverse-proxies.rst
index 0553ab1..13bcd7b 100644
--- a/src/best-practices/reverse-proxies.rst
+++ b/src/best-practices/reverse-proxies.rst
@@ -145,7 +145,11 @@ CouchDB in the ``/couchdb`` subdirectory:
}
This setup leans entirely on nginx performing authorization, and forwarding
-requests to CouchDB with no authentication (with CouchDB in Admin Party mode).
+requests to CouchDB with no authentication (with CouchDB in Admin Party mode),
+which isn't sufficient in CouchDB 3.0 anymore as Admin Party has been removed.
+You'd need to at the very least hard-code user credentials into this version
+with headers.
+
For a better solution, see :ref:`api/auth/proxy`.
SSL with nginx
@@ -291,8 +295,12 @@ advisable. One solution is to define Caddy-process environment variables e.g.
``COUCH_PW=couchdb_password`` and using placeholders in the ``Caddyfile``
instead, e.g. ``{$COUCH_PW}``.
-This setup leans entirely on Caddy performing authorization, and forwarding
-requests to CouchDB with no authentication (with CouchDB in Admin Party mode).
+This setup leans entirely on nginx performing authorization, and forwarding
+requests to CouchDB with no authentication (with CouchDB in Admin Party mode),
+which isn't sufficient in CouchDB 3.0 anymore as Admin Party has been removed.
+You'd need to at the very least hard-code user credentials into this version
+with headers.
+
For a better solution, see :ref:`api/auth/proxy`.
SSL/TLS with Caddy
diff --git a/src/config/auth.rst b/src/config/auth.rst
index d4dad85..2097b9a 100644
--- a/src/config/auth.rst
+++ b/src/config/auth.rst
@@ -25,16 +25,18 @@ Server Administrators
.. config:section:: admins :: Server Administrators
- A default CouchDB install provides admin-level access to all connecting
- users. This configuration is known as `Admin Party`, and is not recommended
- for in-production usage. You can crash the party simply by creating the
- first admin account. CouchDB server administrators and passwords are not
- stored in the ``_users`` database, but in the last ``[admins]`` section
- that CouchDB finds when loading its ini files. See :config:intro for
- details on config file order and behaviour. This file (which could be
- something like ``etc/local.ini`` or ``etc/local.d/10-admins.ini`` on a
- Debian/Ubuntu system installed from packages) should be appropriately
- secured and readable only by system administrators::
+.. versionchanged:: 3.0.0
+
+ CouchDB requires an admin account to start. If an admin account has not
+ been created, CouchDB will print an error message and terminate.
+
+ CouchDB server administrators and passwords are not stored in the
+ ``_users`` database, but in the last ``[admins]`` section that CouchDB
+ finds when loading its ini files. See :config:intro for details on config
+ file order and behaviour. This file (which could be something like
+ ``etc/local.ini`` or ``etc/local.d/10-admins.ini`` on a Debian/Ubuntu
+ system installed from packages) should be appropriately secured and
+ readable only by system administrators::
[admins]
;admin = mysecretpassword
diff --git a/src/config/http.rst b/src/config/http.rst
index fd94757..dd7079d 100644
--- a/src/config/http.rst
+++ b/src/config/http.rst
@@ -90,8 +90,7 @@ HTTP Server Options
- ``{chttpd_auth, cookie_authentication_handler}``: used for Cookie auth;
- ``{chttpd_auth, proxy_authentication_handler}``: used for Proxy auth;
- ``{chttpd_auth, default_authentication_handler}``: used for Basic auth;
- - ``{couch_httpd_auth, null_authentication_handler}``: disables auth.
- Everlasting `Admin Party`!
+ - ``{couch_httpd_auth, null_authentication_handler}``: disables auth, breaks CouchDB.
.. config:section:: httpd :: HTTP Server Options
diff --git a/src/intro/api.rst b/src/intro/api.rst
index 04aaa76..fda4458 100644
--- a/src/intro/api.rst
+++ b/src/intro/api.rst
@@ -55,11 +55,20 @@ CouchDB replies, all excited to get going:
.. code-block:: javascript
{
- "couchdb": "Welcome",
- "version": "2.0.0",
- "vendor": {
- "name": "The Apache Software Foundation"
- }
+ "couchdb": "Welcome",
+ "version": "3.0.0",
+ "git_sha": "83bdcf693",
+ "uuid": "56f16e7c93ff4a2dc20eb6acc7000b71",
+ "features": [
+ "access-ready",
+ "partitioned",
+ "pluggable-storage-engines",
+ "reshard",
+ "scheduler"
+ ],
+ "vendor": {
+ "name": "The Apache Software Foundation"
+ }
}
You get back a JSON string, that, if parsed into a native object or data
@@ -89,7 +98,7 @@ and we creatively give our database the name albums. Note that we're now
using the ``-X`` option again to tell curl to send a :method:`PUT` request
instead of the default :method:`GET` request::
- curl -X PUT http://127.0.0.1:5984/albums
+ curl -X PUT http://admin:password@127.0.0.1:5984/albums
CouchDB replies:
@@ -101,7 +110,7 @@ That's it. You created a database and CouchDB told you that all went well.
What happens if you try to create a database that already exists? Let's try
to create that database again::
- curl -X PUT http://127.0.0.1:5984/albums
+ curl -X PUT http://admin:password@127.0.0.1:5984/albums
CouchDB replies:
@@ -117,7 +126,7 @@ Let's create another database, this time with curl's ``-v`` (for "verbose")
option. The verbose option tells curl to show us not only the essentials --
the HTTP response body -- but all the underlying request and response details::
- curl -vX PUT http://127.0.0.1:5984/albums-backup
+ curl -vX PUT http://admin:password@127.0.0.1:5984/albums-backup
curl elaborates::
@@ -293,7 +302,7 @@ that are important for the particular request.
Creating databases is all fine, but how do we get rid of one? Easy -- just
change the HTTP method::
- > curl -vX DELETE http://127.0.0.1:5984/albums-backup
+ > curl -vX DELETE http://admin:password@127.0.0.1:5984/albums-backup
This deletes a CouchDB database. The request will remove the file that the
database contents are stored in. There is no *"Are you sure?"* safety net or
@@ -328,7 +337,7 @@ later time or on a different computer; secondly, CouchDB replication lets you
share documents with others and using UUIDs ensures that it all works.
But more on that later; let's make some documents::
- curl -X PUT http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af -d '{"title":"There is Nothing Left to Lose","artist":"Foo Fighters"}'
+ curl -X PUT http://admin:password@127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af -d '{"title":"There is Nothing Left to Lose","artist":"Foo Fighters"}'
CouchDB replies:
@@ -366,7 +375,7 @@ values.
To double-check that CouchDB isn't lying about having saved your document (it
usually doesn't), try to retrieve it by sending a GET request::
- curl -X GET http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af
+ curl -X GET http://admin:password@127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af
We hope you see a pattern here. Everything in CouchDB has an address, a URI,
and you use the different HTTP methods to operate on these URIs.
@@ -404,7 +413,7 @@ are likely to overwrite data you didn't know existed. Or simplified: whoever
saves a change to a document first, wins. Let's see what happens if we don't
provide a ``_rev`` field (which is equivalent to providing a outdated value)::
- curl -X PUT http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af \
+ curl -X PUT http://admin:password@127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af \
-d '{"title":"There is Nothing Left to Lose","artist":"Foo Fighters","year":"1997"}'
CouchDB replies:
@@ -416,7 +425,7 @@ CouchDB replies:
If you see this, add the latest revision number of your document to the JSON
structure::
- curl -X PUT http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af \
+ curl -X PUT http://admin:password@127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af \
-d '{"_rev":"1-2902191555","title":"There is Nothing Left to Lose","artist":"Foo Fighters","year":"1997"}'
Now you see why it was handy that CouchDB returned that ``_rev`` when we made
@@ -481,7 +490,7 @@ We'll add some more of our favorite music albums. Get a fresh UUID from the
``/_uuids`` resource. If you don't remember how that works, you can look it up
a few pages back. ::
- curl -vX PUT http://127.0.0.1:5984/albums/70b50bfa0a4b3aed1f8aff9e92dc16a0 \
+ curl -vX PUT http://admin:password@127.0.0.1:5984/albums/70b50bfa0a4b3aed1f8aff9e92dc16a0 \
-d '{"title":"Blackened Sky","artist":"Biffy Clyro","year":2002}'
.. note::
@@ -527,7 +536,7 @@ the album artwork to the ``6e1295ed6c29495e54cc05947f18c8af`` document
(*"There is Nothing Left to Lose"*), and let's also say the artwork is in a file
`artwork.jpg` in the current directory::
- curl -vX PUT http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af/artwork.jpg?rev=2-2739352689 \
+ curl -vX PUT http://admin:password@127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af/artwork.jpg?rev=2-2739352689 \
--data-binary @artwork.jpg -H "Content-Type:image/jpg"
.. note::
@@ -546,7 +555,7 @@ http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af/artwork.jpg
If you request the document again, you'll see a new member::
- curl http://127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af
+ curl http://admin:password@127.0.0.1:5984/albums/6e1295ed6c29495e54cc05947f18c8af
CouchDB replies:
@@ -600,11 +609,11 @@ create a target database for you, and will return a replication failure if
the target doesn't exist (likewise for the source, but that mistake isn't as
easy to make)::
- curl -X PUT http://127.0.0.1:5984/albums-replica
+ curl -X PUT http://admin:password@127.0.0.1:5984/albums-replica
Now we can use the database `albums-replica` as a replication target::
- curl -vX POST http://127.0.0.1:5984/_replicate \
+ 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"}' \
-H "Content-Type: application/json"
@@ -667,7 +676,7 @@ 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://127.0.0.1:5984/_replicate \
+ 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"}' \
-H "Content-Type:application/json"
@@ -686,14 +695,14 @@ 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://127.0.0.1:5984/_replicate \
+ 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"}' \
-H "Content-Type:application/json"
Finally, you can run remote replication, which is mostly useful for management
operations::
- curl -vX POST http://127.0.0.1:5984/_replicate \
+ 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"
diff --git a/src/intro/curl.rst b/src/intro/curl.rst
index 1228186..fb3c2c6 100644
--- a/src/intro/curl.rst
+++ b/src/intro/curl.rst
@@ -16,18 +16,17 @@
cURL: Your Command Line Friend
==============================
-The ``curl`` utility is a command line tool available on Unix, Linux,
-Mac OS X and Windows and many other platforms. ``curl`` provides easy
-access to the HTTP protocol (among others) directly from the
-command-line and is therefore an ideal way of interacting with CouchDB
-over the HTTP REST API.
+The ``curl`` utility is a command line tool available on Unix, Linux, Mac OS X
+and Windows and many other platforms. ``curl`` provides easy access to the HTTP
+protocol (among others) directly from the command-line and is therefore an
+ideal way of interacting with CouchDB over the HTTP REST API.
-For simple ``GET`` requests you can supply the URL of the request. For
-example, to get the database information:
+For simple ``GET`` requests you can supply the URL of the request. For example,
+to get the database information:
.. code-block:: bash
- shell> curl http://127.0.0.1:5984
+ shell> curl http://admin:password@127.0.0.1:5984
This returns the database information (formatted in the output below for
clarity):
@@ -35,11 +34,20 @@ clarity):
.. code-block:: json
{
- "couchdb": "Welcome",
- "version": "2.0.0",
- "vendor": {
- "name": "The Apache Software Foundation"
- }
+ "couchdb": "Welcome",
+ "version": "3.0.0",
+ "git_sha": "83bdcf693",
+ "uuid": "56f16e7c93ff4a2dc20eb6acc7000b71",
+ "features": [
+ "access-ready",
+ "partitioned",
+ "pluggable-storage-engines",
+ "reshard",
+ "scheduler"
+ ],
+ "vendor": {
+ "name": "The Apache Software Foundation"
+ }
}
.. note::
@@ -75,7 +83,7 @@ URL you send using a PUT request:
.. code-block:: bash
- shell> curl -X PUT http://127.0.0.1:5984/demo
+ shell> curl -X PUT http://user:pass@127.0.0.1:5984/demo
{"ok":true}
But to obtain the database information you use a ``GET`` request (with
@@ -83,7 +91,7 @@ the return information formatted for clarity):
.. code-block:: bash
- shell> curl -X GET http://127.0.0.1:5984/demo
+ shell> curl -X GET http://user:pass@127.0.0.1:5984/demo
{
"compact_running" : false,
"doc_count" : 0,
@@ -113,7 +121,7 @@ submit a simple document to the ``demo`` database:
.. code-block:: bash
shell> curl -H 'Content-Type: application/json' \
- -X POST http://127.0.0.1:5984/demo \
+ -X POST http://user:pass@127.0.0.1:5984/demo \
-d '{"company": "Example, Inc."}'
{"ok":true,"id":"8843faaf0b831d364278331bc3001bd8",
"rev":"1-33b9fbce46930280dab37d672bbc8bb9"}
@@ -126,7 +134,7 @@ that was returned:
.. code-block:: bash
- shell> curl -X GET http://127.0.0.1:5984/demo/8843faaf0b831d364278331bc3001bd8
+ shell> curl -X GET http://user:pass@127.0.0.1:5984/demo/8843faaf0b831d364278331bc3001bd8
{"_id":"8843faaf0b831d364278331bc3001bd8",
"_rev":"1-33b9fbce46930280dab37d672bbc8bb9",
"company":"Example, Inc."}
diff --git a/src/intro/index.rst b/src/intro/index.rst
index 39e7116..a01fb1e 100644
--- a/src/intro/index.rst
+++ b/src/intro/index.rst
@@ -47,6 +47,6 @@ teach how to use CouchDB.
why
consistency
curl
+ security
tour
api
- security
diff --git a/src/intro/security.rst b/src/intro/security.rst
index ec30b0e..152b053 100644
--- a/src/intro/security.rst
+++ b/src/intro/security.rst
@@ -16,43 +16,16 @@
Security
========
-In this document, we'll look at the basic security mechanisms in CouchDB: the
-`Admin Party`, `Basic Authentication`, `Cookie Authentication`; how CouchDB
+In this document, we'll look at the basic security mechanisms in CouchDB:
+`Basic Authentication` and `Cookie Authentication`. This is how CouchDB
handles users and protects their credentials.
Authentication
==============
-.. _intro/security/admin_party:
-
-The Admin Party
----------------
-
-When you start out fresh, CouchDB allows any request to be made by anyone.
-Create a database? No problem, here you go. Delete some documents? Same deal.
-CouchDB calls this the `Admin Party`. Everybody has privileges to do anything.
-Neat.
-
-While it is incredibly easy to get started with CouchDB that way,
-it should be obvious that putting a default installation into the wild is
-adventurous. Any rogue client could come along and delete a database.
-
-A note of relief: by default, CouchDB will listen only on your loopback
-network interface (``127.0.0.1`` or ``localhost``) and thus only you will be
-able to make requests to CouchDB, nobody else. But when you start to open up
-your CouchDB to the public (that is, by telling it to bind to your machine's
-public IP address), you will want to think about restricting access so that
-the next bad guy doesn't ruin your admin party.
-
-In our previous discussions, we dropped some keywords about how things
-without the `Admin Party` work. First, there's *admin* itself, which implies
-some sort of super user. Then there are *privileges*. Let's explore these terms
-a little more.
-
CouchDB has the idea of an *admin user* (e.g. an administrator, a super user,
or root) that is allowed to do anything to a CouchDB installation. By default,
-everybody is an admin. If you don't like that, you can create specific admin
-users with a username and password as their credentials.
+one admin user **must** be created for CouchDB to start up successfully.
CouchDB also defines a set of requests that only admin users are allowed to
do. If you have defined one or more specific admin users, CouchDB will ask for
@@ -77,32 +50,52 @@ identification for certain requests:
- Updating the active configuration
(:put:`PUT /_node/{node-name}/_config/section/key </_config/{section}/{key}>`)
-Creating New Admin User
-^^^^^^^^^^^^^^^^^^^^^^^
+Creating a New Admin User
+^^^^^^^^^^^^^^^^^^^^^^^^^
-Let's do another walk through the API using `curl` to see how CouchDB behaves
-when you add admin users. ::
+If your installation process did not set up an admin user, you will have to add
+one to the configuration file by hand and restart CouchDB first. For the purposes of
+this example, we'll create a default ``admin`` user with the password ``password``.
- > HOST="http://127.0.0.1:5984"
- > NODENAME="_local"
- > curl -X PUT $HOST/database
- {"ok":true}
+.. warning::
+ Don't just type in the following without thinking! Pick a good name for your
+ administrator user that isn't easily guessable, and pick a secure password.
+
+To the end of your ``etc/local.ini`` file, after the ``[admins]`` line, add the text
+``admin = password``, so it looks like this:
+
+.. code-block:: ini
-When starting out fresh, we can add a database. Nothing unexpected. Now let's
-create an admin user. We'll call her ``anna``, and her password is ``secret``.
-Note the double quotes in the following code; they are needed to denote a string
-value for the :ref:`configuration API <api/config>`::
+ [admins]
+ admin = password
+(Don't worry about the password being in plain text; we'll come back to this.)
+
+Now, restart CouchDB using the method appropriate for your operating system.
+You should now be able to access CouchDB using your new administrator account::
+
+ > curl http://admin:password@127.0.0.1:5984/_up
+ {"status":"ok","seeds":{}}
+
+Great!
+
+Let's create an admin user through the HTTP API. We'll call her ``anna``, and
+her password is ``secret``. Note the double quotes in the following code; they
+are needed to denote a string value for the :ref:`configuration API
+<api/config>`::
+
+ > HOST="http://admin:password@127.0.0.1:5984"
+ > NODENAME="_local"
> curl -X PUT $HOST/_node/$NODENAME/_config/admins/anna -d '"secret"'
""
-As per the :ref:`_config <api/config>` API's behavior, we're getting
-the previous value for the config item we just wrote. Since our admin user
-didn't exist, we get an empty string.
+As per the :ref:`_config <api/config>` API's behavior, we're getting the previous value
+for the config item we just wrote. Since our admin user didn't exist, we get an empty
+string.
-Please note that ``_local`` serves as an alias for the local node name, so
-for all configuration URLs, ``NODENAME`` may be set to ``_local``, to interact
-with the local node’s configuration.
+Please note that ``_local`` serves as an alias for the local node name, so for all
+configuration URLs, ``NODENAME`` may be set to ``_local``, to interact with the local
+node’s configuration.
.. seealso::
:ref:`Node Management <cluster/nodes>`
@@ -111,17 +104,20 @@ Hashing Passwords
^^^^^^^^^^^^^^^^^
Seeing the plain-text password is scary, isn't it? No worries, CouchDB doesn't
-show the plain-text password anywhere. It gets hashed right away. The hash
-is that big, ugly, long string that starts out with ``-hashed-``.
-How does that work?
+show the plain-text password anywhere. It gets hashed right away. Go ahead and
+look at your ``local.ini`` file now. You'll see that CouchDB has rewritten the
+plain text passwords so they are hashed:
-#. Creates a new 128-bit UUID. This is our *salt*.
-#. Creates a sha1 hash of the concatenation of the bytes of the plain-text
- password and the salt ``(sha1(password + salt))``.
-#. Prefixes the result with ``-hashed-`` and appends ``,salt``.
+.. code-block:: ini
+
+ [admins]
+ admin = -pbkdf2-71c01cb429088ac1a1e95f3482202622dc1e53fe,226701bece4ae0fc9a373a5e02bf5d07,10
+ anna = -pbkdf2-2d86831c82b440b8887169bd2eebb356821d621b,5e11b9a9228414ab92541beeeacbf125,10
+
+The hash is that big, ugly, long string that starts out with ``-pbkdf2-``.
To compare a plain-text password during authentication with the stored hash,
-the same procedure is run and the resulting hash is compared to the stored
+the hashing algorithm is run and the resulting hash is compared to the stored
hash. The probability of two identical hashes for different passwords is too
insignificant to mention (c.f. `Bruce Schneier`_). Should the stored hash fall
into the hands of an attacker, it is, by current standards, way too inconvenient
@@ -130,38 +126,34 @@ the hash.
.. _Bruce Schneier: http://en.wikipedia.org/wiki/Bruce_Schneier
-But what's with the ``-hashed-`` prefix? When CouchDB starts up, it reads a set
-of `.ini` files with config settings. It loads these settings into an internal
-data store (not a database). The config API lets you read the current
-configuration as well as change it and create new entries. CouchDB is writing
-any changes back to the `.ini` files.
+When CouchDB starts up, it reads a set of ``.ini`` files with config settings. It
+loads these settings into an internal data store (not a database). The config
+API lets you read the current configuration as well as change it and create new
+entries. CouchDB is writing any changes back to the ``.ini`` files.
-The `.ini` files can also be edited by hand when CouchDB is not running.
+The ``.ini`` files can also be edited by hand when CouchDB is not running.
Instead of creating the admin user as we showed previously, you could have
-stopped CouchDB, opened your `local.ini`, added ``anna = secret`` to the
+stopped CouchDB, opened your ``local.ini``, added ``anna = secret`` to the
:config:section:`admins`, and restarted CouchDB. Upon reading the new line from
-`local.ini`, CouchDB would run the hashing algorithm and write back the hash to
-`local.ini`, replacing the plain-text password. To make sure CouchDB only hashes
-plain-text passwords and not an existing hash a second time, it prefixes
-the hash with ``-hashed-``, to distinguish between plain-text passwords and
-hashed passwords. This means your plain-text password can't start with the
-characters ``-hashed-``, but that's pretty unlikely to begin with.
+``local.ini``, CouchDB would run the hashing algorithm and write back the hash
+to ``local.ini``, replacing the plain-text password - just as it did for our
+original ``admin`` user. To make sure CouchDB only hashes plain-text passwords
+and not an existing hash a second time, it prefixes the hash with ``-pbkdf2-``,
+to distinguish between plain-text passwords and `PBKDF2`_ hashed passwords. This
+means your plain-text password can't start with the characters ``-pbkdf2-``,
+but that's pretty unlikely to begin with.
-.. note::
- Since :ref:`1.3.0 release <release/1.3.0>` CouchDB uses ``-pbkdf2-`` prefix
- by default to sign about using `PBKDF2`_ hashing algorithm instead of
- `SHA1`.
-
- .. _PBKDF2: http://en.wikipedia.org/wiki/PBKDF2
+.. _PBKDF2: http://en.wikipedia.org/wiki/PBKDF2
.. _intro/security/basicauth:
Basic Authentication
--------------------
-Now that we have defined an admin, CouchDB will not allow us to create new
-databases unless we give the correct admin user credentials. Let's verify::
+CouchDB will not allow us to create new databases unless we give the correct admin user
+credentials. Let's verify::
+ > HOST="http://127.0.0.1:5984"
> curl -X PUT $HOST/somedatabase
{"error":"unauthorized","reason":"You are not a server admin."}
diff --git a/src/intro/tour.rst b/src/intro/tour.rst
index fe6e967..a7197ba 100644
--- a/src/intro/tour.rst
+++ b/src/intro/tour.rst
@@ -40,16 +40,20 @@ The reply should look something like:
.. code-block:: javascript
{
- "couchdb": "Welcome",
- "version": "2.2.0",
- "git_sha":"2a16ec4",
- "features": [
- "pluggable-storage-engines",
- "scheduler"
- ],
- "vendor": {
- "name": "The Apache Software Foundation"
- }
+ "couchdb": "Welcome",
+ "version": "3.0.0",
+ "git_sha": "83bdcf693",
+ "uuid": "56f16e7c93ff4a2dc20eb6acc7000b71",
+ "features": [
+ "access-ready",
+ "partitioned",
+ "pluggable-storage-engines",
+ "reshard",
+ "scheduler"
+ ],
+ "vendor": {
+ "name": "The Apache Software Foundation"
+ }
}
Not all that spectacular. CouchDB is saying "hello" with the running version
@@ -57,21 +61,25 @@ number.
Next, we can get a list of databases::
- curl -X GET http://127.0.0.1:5984/_all_dbs
+ curl -X GET http://admin:password@127.0.0.1:5984/_all_dbs
-All we added to the previous request is the _all_dbs string.
+All we added to the previous request is the _all_dbs string, and our admin user
+name and password (set when installing CouchDB).
The response should look like::
- ["_global_changes","_replicator","_users"]
+ ["_replicator","_users"]
.. note::
In case this returns an empty Array for you, it means you haven't finished
installation correctly. Please refer to :ref:`setup` for further
information on this.
-Oh, that's right, we didn't create any databases yet! All we see is an empty
-list.
+ For the purposes of this example, we'll not be showing the system databases
+ past this point. In *your* installation, any time you ``GET /_all_dbs``,
+ you should see the system databases in the list, too.
+
+Oh, that's right, we didn't create any user databases yet!
.. note::
The curl command issues GET requests by default. You can issue POST requests
@@ -87,7 +95,7 @@ list.
Let's create a database::
- curl -X PUT http://127.0.0.1:5984/baseball
+ curl -X PUT http://admin:password@127.0.0.1:5984/baseball
CouchDB will reply with::
@@ -95,7 +103,7 @@ CouchDB will reply with::
Retrieving the list of databases again shows some useful results this time::
- curl -X GET http://127.0.0.1:5984/_all_dbs
+ curl -X GET http://admin:password@127.0.0.1:5984/_all_dbs
::
@@ -115,7 +123,7 @@ Retrieving the list of databases again shows some useful results this time::
Let's create another database::
- curl -X PUT http://127.0.0.1:5984/baseball
+ curl -X PUT http://admin:password@127.0.0.1:5984/baseball
CouchDB will reply with::
@@ -125,7 +133,7 @@ CouchDB will reply with::
We already have a database with that name, so CouchDB will respond with an
error. Let's try again with a different database name::
- curl -X PUT http://127.0.0.1:5984/plankton
+ curl -X PUT http://admin:password@127.0.0.1:5984/plankton
CouchDB will reply with::
@@ -133,7 +141,7 @@ CouchDB will reply with::
Retrieving the list of databases yet again shows some useful results::
- curl -X GET http://127.0.0.1:5984/_all_dbs
+ curl -X GET http://admin:password@127.0.0.1:5984/_all_dbs
CouchDB will respond with::
@@ -141,7 +149,7 @@ CouchDB will respond with::
To round things off, let's delete the second database::
- curl -X DELETE http://127.0.0.1:5984/plankton
+ curl -X DELETE http://admin:password@127.0.0.1:5984/plankton
CouchDB will reply with::
@@ -149,7 +157,7 @@ CouchDB will reply with::
The list of databases is now the same as it was before::
- curl -X GET http://127.0.0.1:5984/_all_dbs
+ curl -X GET http://admin:password@127.0.0.1:5984/_all_dbs
CouchDB will respond with::
@@ -178,11 +186,13 @@ To load Fauxton in your browser, visit::
http://127.0.0.1:5984/_utils/
-In later documents, we'll focus on using CouchDB from
-server-side languages such as Ruby and Python. As such, this document is a great
-opportunity to showcase an example of natively serving up a dynamic web
-application using nothing more than CouchDB's integrated web server, something
-you may wish to do with your own applications.
+and log in when prompted with your admin password.
+
+In later documents, we'll focus on using CouchDB from server-side languages
+such as Ruby and Python. As such, this document is a great opportunity to
+showcase an example of natively serving up a dynamic web application using
+nothing more than CouchDB's integrated web server, something you may wish to do
+with your own applications.
The first thing we should do with a fresh installation of CouchDB is run the
test suite to verify that everything is working properly. This assures us
diff --git a/templates/layout.html b/templates/layout.html
index 706e50f..3840a61 100644
--- a/templates/layout.html
+++ b/templates/layout.html
@@ -32,7 +32,7 @@ specific language governing permissions and limitations under the License.
<ul>
<li><a href="https://couchdb.apache.org/"{% if not local %} onclick="_gaq.push(['_link', 'https://couchdb.apache.org/']); return false;"{% endif %}>CouchDB Homepage</a></li>
<li><a href="https://couchdb.apache.org/#mailing-list"{% if not local %} onclick="_gaq.push(['_link', 'https://couchdb.apache.org/#mailing-list']); return false;"{% endif %}>Mailing Lists</a></li>
-<li><a href="http://webchat.freenode.net/?channels=couchdb">IRC</a></li>
+<li><a href="https://couchdb.apache.org/#chat">Realtime Chat</a></li>
<li><a href="https://github.com/apache/couchdb/issues">Issue Tracker</a></li>
<li><a href="{{ pathto('download') }}">Download Docs</a></li>
</ul>