cockroach init

On this page

This page explains the cockroach init command, which you use to perform a one-time initialization of a new multi-node cluster. For a full tutorial of the cluster startup and initialization process, see one of the Manual Deployment tutorials.

Note:

When starting a single-node cluster with cockroach start-single-node, you do not need to use the cockroach init command.

Synopsis

Perform a one-time initialization of a cluster:

$ cockroach init <flags>

View help:

$ cockroach init --help

Flags

The cockroach init command supports the following client connection and logging flags.

Note:

cockroach init must target one of the nodes that was listed with --join when starting the cluster. Otherwise, the command will not initialize the cluster correctly.

Client connection

Flag	Description
`--url`	A connection URL to use instead of the other arguments. To convert a connection URL to the syntax that works with your client driver, run `cockroach convert-url`. Env Variable: `COCKROACH_URL` Default: no URL
`--host`	The server host and port number to connect to. This can be the address of any node in the cluster. Env Variable: `COCKROACH_HOST` Default: `localhost:26257`
`--port` `-p`	The server port to connect to. Note: The port number can also be specified via `--host`. Env Variable: `COCKROACH_PORT` Default: `26257`
`--user` `-u`	The SQL user that will own the client session. Env Variable: `COCKROACH_USER` Default: `root`
`--insecure`	Use an insecure connection. Env Variable: `COCKROACH_INSECURE` Default: `false`
`--cert-principal-map`	A comma-separated list of `<cert-principal>:<db-principal>` mappings. This allows mapping the principal in a cert to a DB principal such as `node` or `root` or any SQL user. This is intended for use in situations where the certificate management system places restrictions on the `Subject.CommonName` or `SubjectAlternateName` fields in the certificate (e.g., disallowing a `CommonName` like `node` or `root`). If multiple mappings are provided for the same `<cert-principal>`, the last one specified in the list takes precedence. A principal not specified in the map is passed through as-is via the identity function. A cert is allowed to authenticate a DB principal if the DB principal name is contained in the mapped `CommonName` or DNS-type `SubjectAlternateName` fields.
`--certs-dir`	The path to the certificate directory containing the CA and client certificates and client key. Env Variable: `COCKROACH_CERTS_DIR` Default: `${HOME}/.cockroach-certs/`
`--cluster-name`	The cluster name to use to verify the cluster's identity. If the cluster has a cluster name, you must include this flag. For more information, see `cockroach start`.
`--disable-cluster-name-verification`	Disables the cluster name check for this command. This flag must be paired with `--cluster-name`. For more information, see `cockroach start`.

See Client Connection Parameters for details.

Logging

By default, this command logs messages to stderr. This includes events with WARNING severity and higher.

If you need to troubleshoot this command's behavior, you can customize its logging behavior.

Examples

Usage of cockroach init assumes that nodes have already been started with cockroach start and are waiting to be initialized as a new cluster. For a more detailed tutorial, see one of the Manual Deployment tutorials.

Initialize a Cluster on a Node's Machine

SSH to the machine where the node has been started. This must be a node that was listed with --join when starting the cluster.
Make sure the client.root.crt and client.root.key files for the root user are on the machine.
Run the cockroach init command with the --certs-dir flag set to the directory containing the ca.crt file and the files for the root user, and with the --host flag set to the address of the current node:
```
$ cockroach init --certs-dir=certs --host=<address of this node>
```
At this point, all the nodes complete startup and print helpful details to the standard output, such as the CockroachDB version, the URL for the DB Console, and the SQL URL for clients.

SSH to the machine where the node has been started. This must be a node that was listed with --join when starting the cluster.
Run the cockroach init command with the --host flag set to the address of the current node:
```
$ cockroach init --insecure --host=<address of this node>
```
At this point, all the nodes complete startup and print helpful details to the standard output, such as the CockroachDB version, the URL for the DB Console, and the SQL URL for clients.

Initialize a cluster from another machine

Install the cockroach binary on a machine separate from the node.
Create a certs directory and copy the CA certificate and the client certificate and key for the root user into the directory.
Run the cockroach init command with the --certs-dir flag set to the directory containing the ca.crt file and the files for the root user, and with the --host flag set to the address of the node. This must be a node that was listed with --join when starting the cluster:
```
$ cockroach init --certs-dir=certs --host=<address of any node on --join list>
```
At this point, all the nodes complete startup and print helpful details to the standard output, such as the CockroachDB version, the URL for the DB Console, and the SQL URL for clients.

Install the cockroach binary on a machine separate from the node.
Run the cockroach init command with the --host flag set to the address of the node. This must be a node that was listed with --join when starting the cluster:
```
$ cockroach init --insecure --host=<address of any node on --join list>
```
At this point, all the nodes complete startup and print helpful details to the standard output, such as the CockroachDB version, the URL for the DB Console, and the SQL URL for clients.

Pricing

Contact us

Sign In