cockroach user command

_data/sidebar_doc.yml

@@ -87,6 +87,9 @@ entries:
                 - title: <code>CREATE TABLE AS</code>
                   url: /create-table-as.html
 
+                - title: <code>CREATE USER</code>
+                  url: /create-user.html
+
                 - title: <code>CREATE VIEW</code>
                   url: /create-view.html
 
@@ -320,6 +323,9 @@ entries:
         - title: Create Security Certificates
           url: /create-security-certificates.html
 
+        - title: Create & Manage Users
+          url: /create-and-manage-users.html
+
         - title: Configure Replication Zones
           url: /configure-replication-zones.html
 

_includes/sql/diagrams/create_user.html

@@ -0,0 +1,30 @@
+<svg width="658" height="68">
+
+         <polygon points="9 17 1 13 1 21"></polygon>
+         <polygon points="17 17 9 13 9 21"></polygon>
+         <rect x="31" y="3" width="70" height="32" rx="10"></rect>
+         <rect x="29" y="1" width="70" height="32" class="terminal" rx="10"></rect>
+         <text class="terminal" x="39" y="21">CREATE</text>
+         <rect x="121" y="3" width="56" height="32" rx="10"></rect>
+         <rect x="119" y="1" width="56" height="32" class="terminal" rx="10"></rect>
+         <text class="terminal" x="129" y="21">USER</text>
+         <a xlink:href="sql-grammar.html#name" xlink:title="name">
+            <rect x="197" y="3" width="54" height="32"></rect>
+            <rect x="195" y="1" width="54" height="32" class="nonterminal"></rect>
+            <text class="nonterminal" x="205" y="21">name</text>
+         </a>
+         <rect x="291" y="35" width="58" height="32" rx="10"></rect>
+         <rect x="289" y="33" width="58" height="32" class="terminal" rx="10"></rect>
+         <text class="terminal" x="299" y="53">WITH</text>
+         <rect x="409" y="35" width="100" height="32" rx="10"></rect>
+         <rect x="407" y="33" width="100" height="32" class="terminal" rx="10"></rect>
+         <text class="terminal" x="417" y="53">PASSWORD</text>
+
+            <rect x="529" y="35" width="82" height="32"></rect>
+            <rect x="527" y="33" width="82" height="32" class="nonterminal"></rect>
+            <text class="nonterminal" x="537" y="53">password</text>
+
+         <path class="line" d="m17 17 h2 m0 0 h10 m70 0 h10 m0 0 h10 m56 0 h10 m0 0 h10 m54 0 h10 m20 0 h10 m0 0 h68 m-98 0 h20 m78 0 h20 m-118 0 q10 0 10 10 m98 0 q0 -10 10 -10 m-108 10 v12 m98 0 v-12 m-98 12 q0 10 10 10 m78 0 q10 0 10 -10 m-88 10 h10 m58 0 h10 m40 -32 h10 m0 0 h212 m-242 0 h20 m222 0 h20 m-262 0 q10 0 10 10 m242 0 q0 -10 10 -10 m-252 10 v12 m242 0 v-12 m-242 12 q0 10 10 10 m222 0 q10 0 10 -10 m-232 10 h10 m100 0 h10 m0 0 h10 m82 0 h10 m23 -32 h-3"></path>
+         <polygon points="649 17 657 13 657 21"></polygon>
+         <polygon points="649 17 641 13 641 21"></polygon>
+      </svg>

back-up-and-restore-data.md

@@ -44,7 +44,7 @@ Flag | Description
 `--port`<br>`-p` | The server port to connect to. <br><br>**Env Variable:** `COCKROACH_PORT`<br>**Default:** `26257`
 `--pretty` | Not valid for the `dump` command. This flag will eventually be removed.
 `--url` | The connection URL. If you use this flag, do not set any other connection flags.<br><br>For insecure connections, the URL format is: <br>`--url=postgresql://<user>@<host>:<port>/<database>?sslmode=disable`<br><br>For secure connections, the URL format is:<br>`--url=postgresql://<user>@<host>:<port>/<database>`<br>with the following parameters in the query string:<br>`sslcert=<path-to-client-crt>`<br>`sslkey=<path-to-client-key>`<br>`sslmode=verify-full`<br>`sslrootcert=<path-to-ca-crt>` <br><br>**Env Variable:** `COCKROACH_URL`
-`--user`<br>`-u` | The user executing the `dump` command. The user must have the `SELECT` privilege on the target table.<br><br>**Default:** `root`
+`--user`<br>`-u` | The [user](create-and-manage-users.html) executing the `dump` command. The user must have the `SELECT` privilege on the target table.<br><br>**Default:** `root`
 
 ## Examples
 

build-a-test-app.md

@@ -21,6 +21,7 @@ Make sure you have already:
 As the `root` user, use the [built-in SQL client](use-the-built-in-sql-client.html) to create a `bank` database and [grant privileges](grant.html) to the `maxroach` user. The privileges will enable the user to execute statements in the next steps.
 
 ~~~ shell
+$ cockroach users set maxroach
 $ cockroach sql -e 'CREATE DATABASE bank'
 $ cockroach sql -e 'GRANT ALL ON DATABASE bank TO maxroach'
 ~~~

cockroach-commands.md

@@ -19,7 +19,7 @@ Command | Usage
 `freeze-cluster` | Freeze the cluster in preparation for an upgrade (docs coming soon).
 [`quit`](stop-a-node.html) | Drain and shutdown a node.
 [`sql`](use-the-built-in-sql-client.html) | Use the built-in SQL client.
-`user` | Get, set, list, and remove users (docs coming soon).
+[`user`](create-and-manage-users.html) | Get, set, list, and remove users.
 [`zone`](configure-replication-zones.html) | Configure the number and location of replicas for specific sets of data.
 [`node`](view-node-details.html) | List node IDs and show their status.
 [`dump`](back-up-and-restore-data.html) | Back up a table by outputting the SQL statements required to recreate the table and all its rows.

create-and-manage-users.md

@@ -0,0 +1,171 @@
+---
+title: Create & Manage Users
+summary: To create and manage your cluster's users (which lets you control SQL-level privileges), use the cockroach user command with appropriate flags.
+toc: false
+---
+
+To create and manage your cluster's users (which lets you control SQL-level [privileges](privileges.html)), use the `cockroach user` [command](cockroach-commands.html) with appropriate flags.
+
+When creating users, it's also important to note:
+
+- After creating users, you must [grant them privileges to databases and tables](grant.html).
+- On secure clusters, users must [authenticate their access to the cluster](#user-authentication).
+
+{{site.data.alerts.callout_info}}You can also create users through the <a href="create-user.html"><code>CREATE USER</code></a> statement.{{site.data.alerts.end}}
+
+<div id="toc"></div>
+
+## 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
+
+~~~ shell
+# 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 `user` command and subcommands support the following flags, as well as [logging flags](cockroach-commands.html#logging-flags). 
+
+Flag | Description
+-----|------------
+`--ca-cert` | The path to the [CA certificate](create-security-certificates.html). This flag is required if the cluster is secure.<br><br>**Env Variable:** `COCKROACH_CA_CERT`
+`--cert` | The path to the [client certificate](create-security-certificates.html) of the user *issuing the command* (not the user you're creating). This flag is required if the cluster is secure. <br><br>**Env Variable:** `COCKROACH_CERT`
+`-d`, `--database` | _Deprecated_: Users are created for the entire cluster. However, you can control a user's privileges per database when [granting them privileges](grant.html#grant-privileges-on-databases). <br/><br/>**Env Variable:** `COCKROACH_DATABASE`
+`--host` | Database server host to connect to.<br/><br/>**Env Variable:** `COCKROACH_HOST`
+`--insecure` | Set this only if the cluster is insecure and running on multiple machines. <br><br>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. <br><br>**Env Variable:** `COCKROACH_INSECURE`
+`--key` | Path to the [client key](create-security-certificates.html) protecting the client certificate of the user *issuing the command* (not the user you're creating). This flag is required if the cluster is secure. <br/><br/>**Env Variable:** `COCKROACH_KEY`
+`--password` | Enable password authentication for the user; you will be prompted to enter the password on the command line.<br/><br/>[Find more detail about how CockroachDB handles passwords](#user-authentication).
+`-p`, `--port` | Connect to the cluster on the specified port.<br/><br/>**Env Variable:** `COCKROACH_PORT` <br/>**Default**: `26257`
+`--pretty` | Format tables using ASCII. When not specified, table rows are printed as tab-separated values (TSV). <br/><br/>**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`). <br/><br/>**Env Variable:** `COCKROACH_URL`
+`-u`, `--user` | _Deprecated_: Only the `root` user can create users, so you cannot pass any other usernames into this flag. <br/><br/>**Env Variable:** `COCKROACH_USER` <br/>**Default**: `root`
+
+## User Authentication
+
+Secure clusters require users to authenticate their access to databases and tables. CockroachDB offers two methods for this:
+
+- [Client certificate and key authentication](#secure-clusters-with-client-certificates), which is available to all users. To ensure the highest level of security, we recommend only using client certificate and key authentication.
+- [Password authentication](#secure-clusters-with-passwords), which is available only to users with passwords. To set a password for a user, include the `--password` flag in the `cockroach user set` command. <br/><br/>You can use this password to authenticate users without supplying their client certificate and key; however, we recommend instead using client certificate and key authentication whenever possible.
+
+{{site.data.alerts.callout_info}}Insecure clusters do not support user authentication, but you can still create passwords for users through the <code>--password</code> flag.{{site.data.alerts.end}}
+
+## Examples
+
+### Create a User
+
+#### Insecure Cluster
+
+~~~ shell
+$ cockroach user set jpointsman
+~~~
+
+After creating users, you must [grant them privileges to databases](grant.html).
+
+#### Secure Cluster
+
+~~~ shell
+$ cockroach user set jpointsman \
+--ca-cert=certs/ca.cert --cert=certs/root.cert --key=certs/root.key --password
+~~~
+
+{{site.data.alerts.callout_success}}If you want to allow password authentication for the user, include the <code>--password</code> flag and then enter and confirm the password at the command prompt.{{site.data.alerts.end}}
+
+After creating users, you must [grant them privileges to databases](grant.html).
+
+### Authenticate as a Specific User
+
+#### Insecure Clusters
+
+~~~ shell
+$ cockroach sql --user=jpointsman
+~~~
+
+#### Secure Clusters with Client Certificates
+
+All users can authenticate their access to a secure cluster using [a client certificate](create-security-certificates.html#create-the-certificate-and-key-for-a-client) issued to their username.
+
+~~~ shell
+$ cockroach sql --user=jpointsman --ca-cert=certs/ca.cert --cert=jpointsman.cert --key=jpointsman.key
+~~~
+
+#### Secure Clusters with Passwords
+
+[Users with passwords](create-and-manage-users.html#secure-cluster) can authenticate their access by entering their password at the command prompt instead of using their client certificate and key.
+
+~~~ shell
+$ cockroach sql --user=jpointsman --ca-cert=certs/ca.cert
+~~~
+
+After issuing this command, you must enter the password for `jpointsman` twice.
+
+### Update a User's Password
+
+~~~ shell
+$ cockroach user set jpointsman \
+--password \
+--ca-cert=certs/ca.cert --cert=certs/root.cert --key=certs/root.key
+~~~
+
+After issuing this command, enter and confirm the user's new password at the command prompt.
+
+### List All Users
+
+~~~ shell
+$ cockroach user ls
+~~~
+~~~
++------------+
+|  username  |
++------------+
+| jpointsman |
++------------+
+~~~
+
+### Find a Specific User
+
+~~~ shell
+$ cockroach user get jpointsman
+~~~
+~~~
++------------+--------------------------------------------------------------+
+|  username  |                        hashedPassword                        |
++------------+--------------------------------------------------------------+
+| jpointsman | $2a$108tm5lYjES9RSXSKtQFLhNO.e/ysTXCBIRe7XeTgBrR6ubXfp6dDczS |
++------------+--------------------------------------------------------------+
+~~~
+
+### Remove a User
+
+~~~ shell
+$ cockroach user rm jpointsman
+~~~
+
+## See Also
+
+- [Create Security Certificates](create-security-certificates.html)
+- [`GRANT`](grant.html)
+- [`SHOW GRANTS`](show-grants.html)
+- [`CREATE USER`](create-user.html)
+- [Other Cockroach Commands](cockroach-commands.html)

create-security-certificates.md

@@ -14,9 +14,9 @@ When using <code>cockroach cert</code> to create node and client certificates, y
 
 Subcommand | Usage 
 -----------|------
-`create-ca` | Create the self-signed CA certificate and key for the entire cluster.
+`create-ca` | Create the self-signed certificate authority (CA), which you'll use to create and authenticate certificates and keys for your entire cluster.
 `create-node` | Create a certificate and key for a specific node in the cluster. You specify all addresses at which the node can be reached and pass appropriate flags.
-`create-client` | Create a certificate and key for a specific user accessing the cluster from a client. You specify the username of the user who will use the certificate and pass appropriate flags.  
+`create-client` | Create a certificate and key for a [specific user](create-and-manage-users.html) accessing the cluster from a client. You specify the username of the user who will use the certificate and pass appropriate flags.
 
 ## Synopsis
 
@@ -41,13 +41,15 @@ $ cockroach cert create-client --help
 
 The `cert` command and subcommands support the following flags, as well as [logging flags](cockroach-commands.html#logging-flags). 
 
+
 Flag | Description
------|------------
+-----|-----------
 `--ca-cert` | The path to the CA certificate. <br><br>This flag is required for all subcommands. When used with `create-ca` in particular, this flag defines where to create the certificate and what to call it; the specified directory must exist. 
-`--ca-key` | The path to the private key protecting the CA certificate. <br><br>This flag is required for all subcommands. When used with `create-ca` in particular, it defines where to create the certificate and what to call it; the specified directory must exist. 
-`--cert` | The path to the node or client certificate. <br><br>This flag is used only with the `create-node` and `create-client` subcommands. It defines where to create the node or client certificate and what to call it; the specified directory must exist.  
+`--ca-key` | The path to the private key protecting the CA certificate. <br><br>This flag is required for all subcommands. When used with `create-ca` in particular, it defines where to create the certificate and what to call it; the specified directory must exist.
+`--cert` | The path to the node or client certificate. <br><br>This flag is used only with the `create-node` and `create-client` subcommands. It defines where to create the node or client certificate and what to call it; the specified directory must exist.
 `--key` | The path to the private key protecting the node or client certificate. <br><br>This flag is used only with the `create-node` and `create-client` subcommands. It defines where to create the node or client key and what to call it; the specified directory must exist.
-`--key-size` | The size of the CA, node, or client key, in bits.<br><br>**Default:** `2048`
+ `--key-size` | The size of the CA, node, or client key, in bits.<br><br>**Default:** `2048`
+
 
 ## Examples