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

# cockroach init

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

This page explains the `cockroach init` <InternalLink path="cockroach-commands">command</InternalLink>, 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 <InternalLink path="manual-deployment">Manual Deployment</InternalLink> tutorials.

<Note>
  When starting a single-node cluster with <InternalLink path="cockroach-start-single-node">`cockroach start-single-node`</InternalLink>, you do not need to use the `cockroach init` command.
</Note>

## 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 <InternalLink path="cockroach-start#networking">`--join`</InternalLink> when starting the cluster. Otherwise, the command will not initialize the cluster correctly.
</Note>

### Client connection

| Flag                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--url`                               | A <InternalLink path="connection-parameters#connect-using-a-url">connection URL</InternalLink> to use instead of the other arguments. To convert a connection URL to the syntax that works with your client driver, run <InternalLink path="connection-parameters#convert-a-url-for-different-drivers">`cockroach convert-url`</InternalLink>.<br /><br />**Env Variable:** `COCKROACH_URL`<br />**Default:** no URL                                                                                                                                                                                                                                                                                                                                                                                 |
| `--host`                              | The server host and port number to connect to. This can be the address of any node in the cluster. <br /><br />**Env Variable:** `COCKROACH_HOST`<br />**Default:** `localhost:26257`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `--port`<br /><br />`-p`              | The server port to connect to. Note: The port number can also be specified via `--host`. <br /><br />**Env Variable:** `COCKROACH_PORT`<br />**Default:** `26257`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `--user`<br /><br />`-u`              | The <InternalLink path="create-user">SQL user</InternalLink> that will own the client session.<br /><br />**Env Variable:** `COCKROACH_USER`<br />**Default:** `root`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `--insecure`                          | Use an insecure connection.<br /><br />**Env Variable:** `COCKROACH_INSECURE`<br />**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 <InternalLink path="cockroach-cert">certificate directory</InternalLink> containing the CA and client certificates and client key.<br /><br />**Env Variable:** `COCKROACH_CERTS_DIR`<br />**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 <InternalLink path="cockroach-start#general">`cockroach start`</InternalLink>.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `--disable-cluster-name-verification` | Disables the cluster name check for this command. This flag must be paired with `--cluster-name`. For more information, see <InternalLink path="cockroach-start#general">`cockroach start`</InternalLink>.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

See <InternalLink path="connection-parameters">Client Connection Parameters</InternalLink> for details.

### Logging

By default, this command logs messages to `stderr`. This includes events with `WARNING` <InternalLink path="logging#logging-levels-severities">severity</InternalLink> and higher.

If you need to troubleshoot this command's behavior, you can <InternalLink path="configure-logs">customize its logging behavior</InternalLink>.

## Examples

Usage of `cockroach init` assumes that nodes have already been started with <InternalLink path="cockroach-start">`cockroach start`</InternalLink> and are waiting to be initialized as a new cluster. For a more detailed tutorial, see one of the <InternalLink path="manual-deployment">Manual Deployment</InternalLink> tutorials.

### Initialize a Cluster on a Node's Machine

1. SSH to the machine where the node has been started. This must be a node that was listed with <InternalLink path="cockroach-start#networking">`--join`</InternalLink> 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 <InternalLink path="cockroach-start#standard-output">standard output</InternalLink>, such as the CockroachDB version, the URL for the DB Console, and the SQL URL for clients.

4. SSH to the machine where the node has been started. This must be a node that was listed with <InternalLink path="cockroach-start#networking">`--join`</InternalLink> when starting the cluster.

5. 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 <InternalLink path="cockroach-start#standard-output">standard output</InternalLink>, such as the CockroachDB version, the URL for the DB Console, and the SQL URL for clients.

### Initialize a cluster from another machine

1. <InternalLink path="install-cockroachdb">Install the `cockroach` binary</InternalLink> 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 <InternalLink path="cockroach-start#networking">`--join`</InternalLink> 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 <InternalLink path="cockroach-start#standard-output">standard output</InternalLink>, such as the CockroachDB version, the URL for the DB Console, and the SQL URL for clients.

4. <InternalLink path="install-cockroachdb">Install the `cockroach` binary</InternalLink> on a machine separate from the node.

5. 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 <InternalLink path="cockroach-start#networking">`--join`</InternalLink> 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 <InternalLink path="cockroach-start#standard-output">standard output</InternalLink>, such as the CockroachDB version, the URL for the DB Console, and the SQL URL for clients.

## See also

* <InternalLink path="manual-deployment">Manual Deployment</InternalLink>
* <InternalLink path="kubernetes-overview">Orchestrated Deployment</InternalLink>
* <InternalLink path="start-a-local-cluster">Local Deployment</InternalLink>
* <InternalLink path="cockroach-start">`cockroach start`</InternalLink>
* <InternalLink path="cockroach-commands">`cockroach` Commands Overview</InternalLink>