couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jan Lehnardt <>
Subject Re: Setting up CouchDB 2.0
Date Wed, 24 Sep 2014 13:12:59 GMT

On 24 Sep 2014, at 13:26 , Alexander Shorin <> wrote:

> Hi Jan,
> Looks good, replied inline.
> On Wed, Sep 24, 2014 at 2:35 PM, Jan Lehnardt <> wrote:
>> # Setting up CouchDB 2.0
>> Hey all, since we are getting close to feature completeness, I’d like to bring
up the topic of setting up CouchDB 2.0 solo and as a cluster. Actually, Bob Newson brought
this up on IRC, and we discussed it a bit and I agreed to write up our current thoughts. As
usual, please be generous with your commentary :)
>> Here is what we envision (includes feedback by rnewson, chewbranca and davisp). This
needs to be squared against current implementation (, required
engineering and security considerations.
>> My main motivation is to make sure that CouchDB 2.0 is as simple to use as CouchDB
1.0. Because setting up a cluster is intrinsically more complicated than launching a single
node, this isn’t quite possible, but I believe it is crucial to make this as simple as it
can be made.
>> The current setup procedure (again, at is not terribly
hard, but I think we can do better.
>> ## The Setup Procedure
>> Here is a preliminary outline of how we thing this could go. It is still very high-level,
but should give you the idea. If you see any technical or security roadblocks that could make
this hard to actually build, please holler :)
>> N. End User Action
>>  - what happens behind the scenes
>> 1. User sets up a new CouchDB 2.0 (A), starts it and goes to Faxuton
>>    - `couchdb` prompts for admin user and pass, if none are configured, rejects startup
> I think password MUST be set manually in config file. Otherwise this
> will be nothing different from Admin Party when there is a race
> condition: who opens Fauxton first wins.

`couchdb` is a shell script that runs before Erlang is booted up, so
there is no race condition.

>> 2. Fauxton sees that it has no nodes connected to it yet (/nodes db empty or non
existent), so Fauxton shows a cluster setup screen (that we can go back later as well).
>>    - *handwaving* something about a /_membership endpoint that I don’t know much
about, yet.
>> 2.1. If the user just wants a single node couch, there is a button “Thanks no cluster
setup needed” and we go directly to step 5.
>> 3. User sets up another CouchDB 2.0 (B) and notes its fully qualified domain name
or ip address (fqdn/ip)
>>  - and uses the same admin/pass combo as on node A.
>> 4. User goes back to Fauxton on A and adds a node in the (fictitious at this point)
UI and enters node B’s fqdn/ip
>>  - Fauxton posts this info to e.g. /_setup on A, A then checks if the node fqdn/ip
is reachable, if not, returns an error, if yes, it creates the node doc in /nodes
>>  - The post to /_setup also configures the erlang cookie/shared secret (this requires
code that updates a shared cookie value (could be a UUID, or readable-secure random password)
but results in really nice end-user friendliness). This enables secure Erlang-level communication
that the cluster needs to do its work, without any end-user interaction.
>>  - a security consideration here is that a node is open to receive a shared secret
via HTTP, someone might be able to hijack an in-setup cluster node, requiring an admin/pass
on node-startup and making the /_setup endpoint admin-only should mitigate that.
>> // Repeat steps 3. and 4. until all nodes are added
>> 5. User clicks a “cluster setup done” button and goes back to the regular Fauxton
start page.
>>  - fauxton posts to /_setup with a body that indicates that the setup is complete
and node A creates /_users and /_replicator and whatever else is needed) in the cluster, to
get it into a production-ready state (*waves hands*)
>>  - this could also flip a bit “cluster setup done” in all nodes, not yet sure
what we’d use this for, though, maybe block all non-fauxton/setup traffic until setup is
>> There is some handwaving how the adding-nodes machinery works under the hood, but
I think that can be worked out later.
> Too much magic is applied for /_setup.

It is not well defined yet, yes, but too much magic? Let’s design it and decide then :)

Also what would you do alternatively?

> Is it the only resource which will verify availability of the node to add?

Possibly, what other resources would you want to have to expose this information?

> Can I run setup once again right after it is done?

Unspecified as per now, but I’d imagine you can. All /_setup does is doing in bulk what tells you to do manually today.

> How can I rollback my cluster CouchDB to single node?

Can you do this today? Is this a feature we want?

> And can I run setup again after that?

Again unspecified, see above.

> Can I protect my instance from being included into cluster by some other node?

Yes, e.g. don’t give the other node admin creds. Is this enough? I don’t know. Maybe /_setup
is also disabled after the “the cluster is ready” bit was flipped and you need to disable
that that manually again, to get access to /_setup again.

> Also, UI-less setup also requires and probably it have to be the base
> for Fauxton UI workflow.

As I said in my reply to Dirkjan, that was my intention.

>> ## Requirements
>> This requires at least a new HTTP endpoint /_setup which needs to be defined in a
little more detail. I might give it a stab later.
>> This also requires a start script that knows how to read a username and password
from the command line (for interactive setups) or from a config file or environment vars (for
automated setups).
>> This finally requires a Fauxton addition that makes /_setup accessible to users.
>> I think the engineering effort is small enough to warrant the “expense” of having
a really nice user experience for CouchDB 2.0.
>> ### A note on admin party
>> Admin party has to go. It is the right thing to do to keep a node or a cluster in
a “vulnerable setup state” as short as possible. As outlined above, a node would not even
start with out an admin set up, and creating an admin user can be made super simple, so it
doesn’t inhibit the setup user experience too much (we’ve done the same thing at Hoodie,
and it works really well). This will also give us some more “doing it right” credibility
among the folks who care about these things (c.f. turning off delayed commits).
> Wouldn't it cause "false protection" problem? If user need just a
> database that works for local need without auth headaches forcing him
> to set some password will make him set something trivial like "123",
> "qwerty", "god", "sex", "love" etc. Yay, user has admin now, but does
> such admin protects instance or makes a feel that instance is
> protected? What if we keep Admin Party as an option, but disabled by
> default? For sure, only for single node mode. Too complicated?

This is a good point. As mentioned in my other email, I’m living in forced-admin Couch land
at the moment, and all my personal test setups have the same three letter password. But I
know it’s there and I know it is not secure. The fact that I took a deliberate shortcut
there makes me remember to pick a proper password when setting up a CouchDB for production.
So there is that.

My goal was to make the cluster setup as easy as possible. Whether or not admin party plays
a role is kinda orthogonal to this, but it was worth mentioning, since removing it has been
discussed in the past. I’m happy to ignore the admin party discussion for now in favour
of defining the first run experience for solo and cluster setups.


>> That’s it so far, what do you think? :)
>> Best
>> Jan
>> --
> --
> ,,,^..^,,,

View raw message