trove-specs/specs/mitaka/couchdb-database-user-functions.rst

CouchDB Database & User Functions

Even though CouchDB has been added as an experimental datastore in Trove, the functionality yet has some gaps to be filled. The motivation behind this spec is to implement some of those missing user and database functions for the CouchDB datastore in Trove.

Launchpad Blueprint: https://blueprints.launchpad.net/trove/+spec/couchdb-database-user-functions

Problem Description

Currently, a CouchDB instance can be created using Trove but the functionality is very limited. No user or database actions can be performed via the Trove CLI. While, it is possible to perform such operations by accessing the CouchDB administration interface called Futon¹, it is not within the scope of Trove. Therefore for ease of use and consistency, it is best that these database and user functionalities for CouchDB be implemented as part of Trove.

Proposed Change

Implementation of the basic user and database functions will be performed for the CouchDB datastore in Trove using an HTTP-based REST API which CouchDB uses to communicate with the server. Curl commands will be sent over HTTP requests to the CouchDB server which will then execute actions.

The new operations that will be supported are as follows:

• create/delete/show user
• list users
• grant/revoke/show access
• root enable/show
• create/delete database
• list databases

A CouchDBAdmin class will be created in service.py which will have these methods in it and the functions in manager.py will be updated to call these new methods. Each method will use the core CouchDB API to make appropriate HTTP requests for that functionality on the server.

As of now an API extension for CouchDB does not exist so a new API extension will be created to implement datastore specifics while moderating user/ database operations. The validation in effect in the CouchDB specific models will correspond to CouchDB datastore requirements.

CouchDB Security

On a fresh CouchDB instance, the server allows any request to be made by anyone - it's an Admin Party² . To enable the user functionalities, the guest agent's CouchDB server will be made secure by creating a Trove user 'os_admin' by default. When a guest is first started, the os_admin user will be created and will be connected to the server using a password generated by the guest. This will be done using the following command-curl -X PUT http://localhost:5984/_config/admins/os_admin -d '"password"'

The username and generated password will be stored in a file in the home ~ directory on the instance (stream_codecs.JsonCodec will be used to handle it). All other users that are created are non-admin users so this preventing anybody from accidentally creating an admin user³ . The only admin user that can be created is 'root' using the trove root-enable command by creating a user on the couchDB server with admin privileges.

Configuration

None

Database

None

Public API

The user will be able to run the implemented functions for CouchDB datastore via CLI.

Public API Security

None

Python API

None

CLI (python-troveclient)

The following Trove command line commands will be functional for CouchDB:

• trove user-create
• trove user-delete
• trove user-grant-access
• trove user-list
• trove user-revoke-access
• trove user-show
• trove user-show-access
• trove root-enable
• trove root-show
• trove database-create
• trove database-delete
• trove database-list

Internal API

None

Guest Agent

The CouchDB guest agent will be modified to support additional database and user functionality. In particular the following files will have added components:

trove/guestagent/datastore/experimental/couchdb/manager.py
trove/guestagent/datastore/experimental/couchdb/service.py
trove/guestagent/datastore/experimental/couchdb/system.py

Several new guest agent functions will be implemented using the CouchDB API. Below are sample API calls and associated details for each guest agent method.

create_user

Create non-admin user with name username and password password

curl -X PUT http://os_admin:password@localhost:5984/_users/org.couchdb
.user:username \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"name": "username", "password": "password", "roles": [], "type":
"user"}'

list_users

List all the users from the system database _users and all the databases from the system database _all_dbs. Then cross reference to list users and the databases that they have access to.

curl -s http://os_admin:password@localhost:5984/_users/_all_docs

curl -X http://os_admin:password@localhost:5984/_all_dbs

curl -X http://os_admin:password@localhost:5984/databasename/_security

delete_user

Deletes user username from the system database _users corresponding to rev number 1-3cd11775d7e3ba15a9f8c553cb3d47bd. The rev number for the document to be obtained using the second command listed below.

curl -X DELETE http://os_admin:password@localhost:5984/_users/org. couchdb.user:username?rev=1-3cd11775d7e3ba15a9f8c553cb3d47bd

curl -s http://os_admin:password@localhost:5984/_users/_all_docs

get_user

Shows the complete information associated with a specific user - username, databases user has access to and permissions(admin/member).

curl -X http://os_admin:password@localhost:5984/_all_dbs

curl -X http://os_admin:password@localhost:5984/databasename/_security

enable_root

Create user "root" and grant the role "admin"

curl -X PUT http://os_admin:password@localhost:5984/_config/admins/
root -d '"password"'

is_root_enabled

Checks if user root exists in the system database _config and has admin privileges

curl -s http://os_admin:password@localhost:5984/_config/_admins

delete_root

Deletes the root user from the CouchDB instance.

curl -X DELETE http://
os_admin:password@localhost:5984/_config/admins/root

grant_access

Modify the role of user username for database databasename to include username as a listed admin

curl -X PUT http://os_admin:password@localhost:5984
/databasename/_security \
> -d '{"admins":{"names":[], "roles":[]}, "members":{"names”:[
“username”],”roles":[]}}'

revoke_access

Similar to the implementation of grant access, modify the role of user username for database databasename to remove username` as a listed member

curl -X PUT http://os_admin:password@localhost:5984
/databasename/_security \
> -d '{"admins":{"names":[], "roles":[]}, "members":{"names”:[],
”roles":[]}}'

list_access

Lists all the databases from the system database _all_dbs. Then cross reference to list all the databases that the specified user has has access to.

curl -X http://os_admin:password@localhost:5984/_all_dbs

curl -X http://os_admin:password@localhost:5984/databasename/_security

create_database

Creates a database with name database_name

curl -X PUT http://os_admin:password@localhost:5984/database_name

The database name must consist of one or more of the following characters and the name must begin with a lowercase letter⁴ .

• Lowercase characters (a-z)
• Digits (0-9)
• Any of the characters _, $, (, ), +, -, and /.

delete_database

Deletes the database with name database_name

curl -X DELETE http://os_admin:password@localhost:5984/database_name

list_databases

Lists all the databases from the system database _all_dbs

curl -X GET http://os_admin:password@localhost:5984/_all_dbs

Alternatives

None

Dashboard Impact (UX)

The dashboard will need to be updated for the users and databases tabs to be enabled for the CouchDB datastore. No new features will need to be added to the dashboard.

Implementation

Assignee(s)

Primary assignee:

imandhan (launchpad id) Ishita Mandhan <imandha@us.ibm.com>

Milestones

Mitaka

Work Items

Implementation of the functionality of user and database functions for CouchDB. Involves working on the manager, service and system files primarily. Tests will be written as required - both unit tests and int tests. The work will be split into 5 parts-

1. Enable authentication on server
2. Create/delete/get/list user
3. Enable/check root
4. grant/revoke/list access
5. create/delete/list database

Upgrade Implications

None

Dependencies

None

Testing

Unit tests and integration tests will be added as necessary to test new code added.

Documentation Impact

The CouchDB Trove documentation will need to be updated to indicate that user and database functions have been implemented.

References

Appendix

None

---

1. CouchDB Futon: http://docs.couchdb.org/en/1.6.1/intro/futon.html↩︎

2. CouchDB Security: http://docs.couchdb.org/en/1.6.1/intro/security.html↩︎

3. CouchDB Authentication: http://docs.couchdb.org/en/1.6.1/config/auth.html↩︎

4. CouchDB Database Name Restrictions: http://couchdb-13.readthedocs.org/en/latest/api/database/↩︎