From a2a8bd5d514d8b4a3dc708eb427799362832107b Mon Sep 17 00:00:00 2001 From: Joan Touzet Date: Wed, 29 Jan 2020 13:21:33 -0500 Subject: [PATCH 1/6] 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 0553ab16..13bcd7b0 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 d4dad855..2097b9a4 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 fd947579..dd7079d0 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 04aaa761..fda4458d 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 1228186e..fb3c2c6a 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 39e7116e..a01fb1ed 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 ec30b0ec..152b053c 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 `) -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 `:: + [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 +`:: + + > 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'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'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 ` @@ -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 ` 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 fe6e967b..a7197bac 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 706e50f0..3840a61d 100644 --- a/templates/layout.html +++ b/templates/layout.html @@ -32,7 +32,7 @@

More Help

From 7c45549be0b4436e455b3b40611a1f2b2934f6bb Mon Sep 17 00:00:00 2001 From: Joan Touzet Date: Wed, 29 Jan 2020 18:46:23 +0000 Subject: [PATCH 2/6] Update src/intro/curl.rst Co-Authored-By: Jonathan Hall --- src/intro/curl.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/intro/curl.rst b/src/intro/curl.rst index fb3c2c6a..7b488239 100644 --- a/src/intro/curl.rst +++ b/src/intro/curl.rst @@ -16,7 +16,8 @@ cURL: Your Command Line Friend ============================== -The ``curl`` utility is a command line tool available on Unix, Linux, Mac OS X +The ``curl`` utility is a command line tool available on Unix, Linux, Mac OS X, +Windows, and many other platforms. 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. From 44d6ecc5337ce05483c03481a4577704f04d3811 Mon Sep 17 00:00:00 2001 From: Joan Touzet Date: Wed, 29 Jan 2020 18:46:32 +0000 Subject: [PATCH 3/6] Update src/intro/curl.rst Co-Authored-By: Jonathan Hall --- src/intro/curl.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/intro/curl.rst b/src/intro/curl.rst index 7b488239..db1a2ec9 100644 --- a/src/intro/curl.rst +++ b/src/intro/curl.rst @@ -19,7 +19,7 @@ cURL: Your Command Line Friend The ``curl`` utility is a command line tool available on Unix, Linux, Mac OS X, Windows, and many other platforms. 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 +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, From f3ce58d32dd20d0cf44ecfc6311b1beb7704153a Mon Sep 17 00:00:00 2001 From: Joan Touzet Date: Wed, 29 Jan 2020 18:46:44 +0000 Subject: [PATCH 4/6] Update src/intro/security.rst Co-Authored-By: Jonathan Hall --- src/intro/security.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/intro/security.rst b/src/intro/security.rst index 152b053c..2cdd9abb 100644 --- a/src/intro/security.rst +++ b/src/intro/security.rst @@ -129,7 +129,7 @@ the hash. 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. +entries. CouchDB writes any changes back to the ``.ini`` files. 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 From e745bedf9e7fb2195575a2c0a36774d2cb580e87 Mon Sep 17 00:00:00 2001 From: Joan Touzet Date: Wed, 29 Jan 2020 13:49:49 -0500 Subject: [PATCH 5/6] em dash --- src/intro/security.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/intro/security.rst b/src/intro/security.rst index 2cdd9abb..21c3a7d3 100644 --- a/src/intro/security.rst +++ b/src/intro/security.rst @@ -136,7 +136,7 @@ Instead of creating the admin user as we showed previously, you could have 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 - just as it did for our +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 From c0c7c73ef6627346524a8b8496b440a94021fcd7 Mon Sep 17 00:00:00 2001 From: Joan Touzet Date: Wed, 29 Jan 2020 18:56:18 +0000 Subject: [PATCH 6/6] Update curl.rst --- src/intro/curl.rst | 3 +-- src/intro/security.rst | 4 ++-- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/src/intro/curl.rst b/src/intro/curl.rst index db1a2ec9..195b3aca 100644 --- a/src/intro/curl.rst +++ b/src/intro/curl.rst @@ -17,8 +17,7 @@ cURL: Your Command Line Friend ============================== The ``curl`` utility is a command line tool available on Unix, Linux, Mac OS X, -Windows, and many other platforms. -and Windows and many other platforms. ``curl`` provides easy access to the HTTP +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. diff --git a/src/intro/security.rst b/src/intro/security.rst index 21c3a7d3..4e3833b8 100644 --- a/src/intro/security.rst +++ b/src/intro/security.rst @@ -51,7 +51,7 @@ identification for certain requests: (:put:`PUT /_node/{node-name}/_config/section/key `) Creating a New Admin User -^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------- 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 @@ -492,7 +492,7 @@ needing to be an administrator*. Keep in mind, though, not to publish sensitive information, especially without user's consent! Authorization -============== +============= Now that you have a few users who can log in, you probably want to set up some restrictions on what actions they can perform based on their identity and their