> ## 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

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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <a id="sql-flag-url" />`--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>.  **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 <InternalLink path="create-user">SQL user</InternalLink> that will own the client session.  **Env Variable:**`COCKROACH_USER` **Default:**`root`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `--insecure`                                              | Use an insecure connection.  **Env Variable:**`COCKROACH_INSECURE` **Default:**`false`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| <a id="flags-cert-principal-map" />`--cert-principal-map` | A comma-separated list of `:` 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 \`\`, 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.  **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 <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

<Tabs>
  <Tab title="Secure">
    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.
  </Tab>

  <Tab title="Insecure">
    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. 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.
  </Tab>
</Tabs>

### Initialize a cluster from another machine

<Tabs>
  <Tab title="Secure">
    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.
  </Tab>

  <Tab title="Insecure">
    1. <InternalLink path="install-cockroachdb">Install the `cockroach` binary</InternalLink> 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 <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.
  </Tab>
</Tabs>

## 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>