> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cockroachlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# cockroach init

This page explains the `cockroach init` [command](/docs/stable/cockroach-commands.md), 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](/docs/stable/manual-deployment.md) tutorials.

> [!NOTE]
>
> When starting a single-node cluster with [`cockroach start-single-node`](/docs/stable/cockroach-start-single-node), you do not need to use the `cockroach init` command.

## Synopsis

Perform a one-time initialization of a cluster:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach init <flags>
```

View help:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ cockroach init --help
```

## Flags

The `cockroach init` command supports the following [client connection](#client-connection) and [logging](#logging) flags.

> [!NOTE]
>
> `cockroach init` must target one of the nodes that was listed with [`--join`](/docs/stable/cockroach-start#networking) when starting the cluster. Otherwise, the command will not initialize the cluster correctly.

### Client connection

| Flag | Description |
| - | - |
|  `--url` | A [connection URL](/docs/stable/connection-parameters.md#connect-using-a-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`](/docs/stable/connection-parameters#convert-a-url-for-different-drivers). **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](/docs/stable/create-user.md) 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](/docs/stable/cockroach-cert.md) 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`](/docs/stable/cockroach-start#general). |
| `--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`](/docs/stable/cockroach-start#general). |

See [Client Connection Parameters](/docs/stable/connection-parameters.md) for details.

### Logging

By default, this command logs messages to `stderr`. This includes events with `WARNING` [severity](/docs/stable/logging.md#logging-levels-severities) and higher.

If you need to troubleshoot this command's behavior, you can [customize its logging behavior](/docs/stable/configure-logs.md).

## Examples

Usage of `cockroach init` assumes that nodes have already been started with [`cockroach start`](/docs/stable/cockroach-start#standard-output) and are waiting to be initialized as a new cluster. For a more detailed tutorial, see one of the [Manual Deployment](/docs/stable/manual-deployment.md) tutorials.

### Initialize a cluster on a node's machine

**Secure**

1. SSH to the machine where the node has been started. This must be a node that was listed with [`--join`](/docs/stable/cockroach-start#networking) when starting the cluster.

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:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   $ 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](/docs/stable/cockroach-start.md#standard-output), such as the CockroachDB version, the URL for the DB Console, and the SQL URL for clients.

**Insecure**

1. SSH to the machine where the node has been started. This must be a node that was listed with [`--join`](/docs/stable/cockroach-start#networking) when starting the cluster.

2. Run the `cockroach init` command with the `--host` flag set to the address of the current node:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   $ cockroach init --insecure --host=<address of this node
   ```

   At this point, all the nodes complete startup and print helpful details to the [standard output](/docs/stable/cockroach-start.md#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

**Secure**

1. [Install the `cockroach` binary](/docs/stable/install-cockroachdb) 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 the node. This must be a node that was listed with [`--join`](/docs/stable/cockroach-start#networking) when starting the cluster:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   $ 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](/docs/stable/cockroach-start.md#standard-output), such as the CockroachDB version, the URL for the DB Console, and the SQL URL for clients.

**Insecure**

1. [Install the `cockroach` binary](/docs/stable/install-cockroachdb) on a machine separate from the node.

2. 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`](/docs/stable/cockroach-start#networking) when starting the cluster:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   $ 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](/docs/stable/cockroach-start.md#standard-output), such as the CockroachDB version, the URL for the DB Console, and the SQL URL for clients.

## See also

* [Manual Deployment](/docs/stable/manual-deployment.md)
* [Orchestrated Deployment](/docs/stable/kubernetes-overview.md)
* [Local Deployment](/docs/stable/start-a-local-cluster.md)
* [`cockroach start`](/docs/stable/cockroach-start#standard-output)
* [`cockroach` Commands Overview](/docs/stable/cockroach-commands)