Initialize a Cluster

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 walk-through of the cluster startup and initialization process, see one of the Manual Deployment tutorials.

{{site.data.alerts.callout_info}} When starting a single-node cluster, you do not need to use the cockroach init command. You can simply run the cockroach start command without the --join flag to start and initialize the single-node cluster. {{site.data.alerts.end}}

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.

Client connection

Flag	Description
`--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`
`--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/`
`--url`	A connection URL to use instead of the other arguments. Env Variable: `COCKROACH_URL` Default: no URL

See Client Connection Parameters for details.

Logging

By default, the init command logs errors to stderr.

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

Examples

These examples assume that nodes have already been started with cockroach start but are waiting to be initialized as a new cluster. For a more detailed walk-through, see one of the Manual Deployment tutorials.

Initialize a Cluster on a Node's Machine

1. SSH to the machine where the node has been started. 2. Make sure the `client.root.crt` and `client.root.key` files for the `root` user are on the machine. 3. 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: {% include copy-clipboard.html %} ~~~ shell $ cockroach init --certs-dir=certs --host=

~~~ At this point, all the nodes complete startup and print helpful details to the [standard output](start-a-node.html#standard-output), such as the CockroachDB version, the URL for the Admin UI, and the SQL URL for clients.

1. SSH to the machine where the node has been started. 2. Run the `cockroach init` command with the `--host` flag set to the address of the current node: {% include copy-clipboard.html %} ~~~ shell $ cockroach init --insecure --host=

Initialize a cluster from another machine

1. [Install the `cockroach` binary](install-cockroachdb.html) on a machine separate from the node. 2. Create a `certs` directory and copy the CA certificate and the client certificate and key for the `root` user into the directory. 3. 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 any node: {% include copy-clipboard.html %} ~~~ shell $ cockroach init --certs-dir=certs --host=

1. [Install the `cockroach` binary](install-cockroachdb.html) on a machine separate from the node. 2. Run the `cockroach init` command with the `--host` flag set to the address of any node: {% include copy-clipboard.html %} ~~~ shell $ cockroach init --insecure --host=