Skip to content

Latest commit

 

History

History
172 lines (125 loc) · 6.63 KB

create-users.md

File metadata and controls

172 lines (125 loc) · 6.63 KB
Raw
title summary toc
Create & Manage Users
A secure CockroachDB cluster uses TLS for encrypted inter-node and client-node communication and requires CA, node, and client certificates and keys.
false

To create and manage your cluster's users (which lets you control SQL-level privileges), use the cockroach user command with appropriate flags.

When creating users, it's also important to note:

Subcommands

Subcommand Usage
get Retrieve a table containing a user and their hashed password
ls List all users
rm Remove a user
set Create or update a user

Synopsis

# Create a user:
$ cockroach user set <username> <flags>

# List all users:
$ cockroach user ls <flags>

# Display a specific user:
$ cockroach user get <username> <flags>

# View help:
$ cockroach user --help
$ cockroach user get --help
$ cockroach user ls --help
$ cockroach user rm --help
$ cockroach user set --help

Flags

The cert command and subcommands support the following flags, as well as logging flags.

Flag Description
--ca-cert The path to the CA certificate. This flag is required when creating a user for a secure cluster.

Env Variable: COCKROACH_CA_CERT
--cert The path to the client certificate. This flag is required if the user does not have a password.

Env Variable: COCKROACH_CERT
-d, --database The name of the database to connect to.

Env Variable: COCKROACH_DATABASE
--host Database server host to connect to.

Env Variable: COCKROACH_HOST
--insecure Set this only if the cluster is insecure and running on multiple machines.

If the cluster is insecure and local, leave this out. If the cluster is secure, leave this out and set the --ca-cert, --cert, and --key flags.

Env Variable: COCKROACH_INSECURE
--key Path to the client key protecting the client certificate. This flag is required if the user does not have a password.

Env Variable: COCKROACH_KEY
--password The password for the user.

If not passed in on a secure cluster, CockroachDB will prompt you to enter and confirm the user's password.

If you want to provide the password through standard input, use '-'
(i.e. --password=-).

Find more detail about how CockroachDB handles passwords.

Env Variable: COCKROACH_PASSWORD
-p, --port Connect to the cluster on the specified port.

Env Variable: COCKROACH_PORT
Default: 26257
--pretty Format tables using ASCII. When not specified, table rows are printed as tab-separated values (TSV).

Default: true
--url Connect to the cluster on the provided URL, e.g., postgresql://myuser@localhost:26257/mydb. If left blank, the connection flags are used (host, port, user, database, insecure, certs).

Env Variable: COCKROACH_URL
-u, --user The username you want to actively engage with.

Env Variable: COCKROACH_USER
Default: root

User Authentication

On secure clusters, users must authenticate their access to the cluster's databases and tables. CockroachDB offers two types of authentication, which you can choose between on a per-user basis based on the password you enter through cockroach user set:

  • Client certificate and key only: Use a blank/NULL password.
  • Password or client certificate and key: Enter a password string.

{{site.data.alerts.callout_info}}Users on insecure clusters are created with blank/NULL passwords unless you include the --password flag. If at any point in the future you convert an insecure cluster to a secure cluster, you can easily add passwords to existing users.{{site.data.alerts.end}}

Examples

Create a User

Insecure Cluster

$ cockroach user set jpointsman

After creating users, you must grant them privileges to databases.

Secure Cluster

$ cockroach user set \
jpointsman \
--ca-cert=certs/ca.cert --cert=certs/root.cert --key=certs/root.key

After issuing this command, you must enter a value for the password, which determines the authentication methods available to the user.

{{site.data.alerts.callout_success}}If you want allow password authentication for the user, you can simply include the --password flag to bypass entering it at the command prompt.{{site.data.alerts.end}}

After creating users, you must grant them privileges to databases.

Provide Password via Standard Input

echo "PNtPaS2" | cockroach user set jpointsman --password=-

Start a SQL Shell as a Specific User

Insecure Clusters

$ cockroach sql --user=jpointsman

Secure Clusters with Passwords

$ cockroach sql --user=jpointsman --ca-cert=certs/ca.cert

After issuing this command, you must enter the password for jpointsman twice.

Secure Clusters with Client Certificates

$ cockroach sql --user=jpointsman --ca-cert=certs/ca.cert --cert=jpointsman.cert --key=jpointsman.key

Update a User's Password

$ cockroach user set \
jpointsman \
--password=5akHb95 \
--ca-cert=certs/ca.cert --cert=certs/root.cert --key=certs/root.key

List All Users

$ cockroach user ls
+------------+
|  username  |
+------------+
| jpointsman |
+------------+

Find a Specific User

$ cockroach user get jpointsman
+------------+--------------------------------------------------------------+
|  username  |                        hashedPassword                        |
+------------+--------------------------------------------------------------+
| jpointsman | $2a$108tm5lYjES9RSXSKtQFLhNO.e/ysTXCBIRe7XeTgBrR6ubXfp6dDczS |
+------------+--------------------------------------------------------------+

Remove a User

$ cockroach user rm jpointsman

See Also