From ab8cb5cb3ebed2599695c84e4e65bdf45b38a20e Mon Sep 17 00:00:00 2001 From: Troy McConaghy Date: Fri, 31 Aug 2018 13:13:28 +0200 Subject: [PATCH] Document the three supported MongoDB auth methods --- .../production-nodes/node-requirements.md | 13 -------- .../source/server-reference/configuration.md | 30 +++++++++++++++++-- 2 files changed, 28 insertions(+), 15 deletions(-) diff --git a/docs/server/source/production-nodes/node-requirements.md b/docs/server/source/production-nodes/node-requirements.md index 1a2a883e..a9daaaf9 100644 --- a/docs/server/source/production-nodes/node-requirements.md +++ b/docs/server/source/production-nodes/node-requirements.md @@ -14,19 +14,6 @@ BigchainDB Server requires Python 3.5+ and Python 3.5+ [will run on any modern O _Don't use macOS_ (formerly OS X, formerly Mac OS X), because it's not a server-grade operating system. Also, BigchaindB Server uses the Python multiprocessing package and [some functionality in the multiprocessing package doesn't work on Mac OS X](https://docs.python.org/3.6/library/multiprocessing.html#multiprocessing.Queue.qsize). -## Using Hosted MongoDB - -If you are using already existing MongoDB deployment or hosted MongoDB service (e.g. MongoDB Atlas) you should create a new database (e.g. `bigchain`) and create a user with `readWrite` access. You can perform above steps through MongoDB shell as follows: - -Login to your MongoDB deployment as Admin and run following commands - -``` -use -db.createUser({user: "", pwd: "", roles: [{role: "readWrite", db: ""}]}) -``` - -Now configure the details of your database and newly created user in your BigchainDB configs before starting BigchainDB - ## General Considerations BigchainDB Server runs many concurrent processes, so more RAM and more CPU cores is better. diff --git a/docs/server/source/server-reference/configuration.md b/docs/server/source/server-reference/configuration.md index 9dd892b5..663d99eb 100644 --- a/docs/server/source/server-reference/configuration.md +++ b/docs/server/source/server-reference/configuration.md @@ -40,8 +40,34 @@ The settings with names of the form `database.*` are for the backend database * `database.connection_timeout` is the maximum number of milliseconds that BigchainDB will wait before giving up on one attempt to connect to the backend database. * `database.max_tries` is the maximum number of times that BigchainDB will try to establish a connection with the backend database. If 0, then it will try forever. * `database.replicaset` is the name of the MongoDB replica set. The default value is `null` because in BighainDB 2.0+, each BigchainDB node has its own independent MongoDB database and no replica set is necessary. -* `database.login` and `database.password` are the login and password used to authenticate to the backend database, specified in plaintext. -* `database.ssl` determines if BigchainDB connects to MongoDB over TLS/SSL or not. It can be set to `true` or `false`. + +There are three ways for BigchainDB Server to authenticate itself with MongoDB (or a specific MongoDB database): no authentication, username/password, and x.509 certificate authentication. + +**No Authentication** + +If you use all the default BigchainDB configuration settings, then no authentication will be used. + +**Username/Password Authentication** + +To use username/password authentication, a MongoDB instance must already be running somewhere (maybe in another machine), it must already have a database for use by BigchainDB (usually named `bigchain`, which is the default `database.name`), and that database must already have a "readWrite" user with associated username and password. To create such a user, login to your MongoDB instance as Admin and run the following commands: + +```text +use +db.createUser({user: "", pwd: "", roles: [{role: "readWrite", db: ""}]}) +``` + +* `database.login` is the user's username. +* `database.password` is the user's password, given in plaintext. +* `database.ssl` must be `false` (the default value). +* `database.ca_cert`, `database.certfile`, `database.keyfile`, `database.crlfile`, and `database.keyfile_passphrase` are not used so they can have their default values. + +**x.509 Certificate Authentication** + +To use x.509 certificate authentication, a MongoDB instance must be running somewhere (maybe in another machine), it must already have a database for use by BigchainDB (usually named `bigchain`, which is the default `database.name`), and that database must be set up to use x.509 authentication. See the MongoDB docs about how to do that. + +* `database.login` is the user's username. +* `database.password` isn't used so the default value (`null`) is fine. +* `database.ssl` must be `true`. * `database.ca_cert`, `database.certfile`, `database.keyfile` and `database.crlfile` are the paths to the CA, signed certificate, private key and certificate revocation list files respectively. * `database.keyfile_passphrase` is the private key decryption passphrase, specified in plaintext.