COCKROACH-START(1)

NAME

cockroach-start - start a node in a multi-node cluster

SYNOPSIS

cockroach start [flags]

DESCRIPTION

Start a CockroachDB node, which will export data from one or more storage devices, specified via --store flags.

Specify the --join flag to point to another node or nodes that are part of the same cluster. The other nodes do not need to be started yet, and if the address of the other nodes to be added are not yet known it is legal for the first node to join itself.

To initialize the cluster, use 'cockroach init'.

OPTIONS

--accept-proxy-protocol-headers[=false]

Allows CockroachDB to parse proxy protocol headers. Proxy protocol is used by
 some proxies to retain the original client IP information after the proxy has
 rewritten the source IP address of forwarded packets.

When using this flag, ensure all traffic to CockroachDB flows through a proxy
 which adds proxy protocol headers, to prevent spoofing of client IP address
 information.

--advertise-addr=:

The address/hostname and port to advertise to other CockroachDB nodes for
 intra-cluster communication. It must resolve and be routable from other nodes
 in the cluster.

If left unspecified, it defaults to the setting of --listen-addr. If the flag
 is provided but either the address part or the port part is left unspecified,
 that particular part defaults to the same part in --listen-addr.

An IPv6 address can also be specified with the notation [...], for example
 [::1]:26257 or [fe80::f6f2:::]:26257.

The port number should be the same as in --listen-addr unless port forwarding
 is set up on an intermediate firewall/router.

--advertise-http-addr=:

The HTTP address/hostname and port to advertise to nodes in the cluster for
 reporting the DB Console address and proxying of HTTP connections. It must
 resolve and be routable from other nodes in the cluster for proxying to work
 in DB Console.

If left unspecified, it defaults to the host setting of --advertise-addr
 and the port of --http-addr, which is 8080 by default. If advertise-addr is
 left unspecified, it defaults to the setting of http-addr. If the flag is
 unspecified as well as fallbacks, it defaults to the hostname as reported by
 the OS.

An IPv6 address can also be specified with the notation [...], for example
 [::1]:26257 or [fe80::f6f2:::]:26257.

The port number should be the same as in --http-addr unless port forwarding is
 set up on an intermediate firewall/router.

--advertise-sql-addr=:

The SQL address/hostname and port to advertise to CLI admin utilities and via
 SQL introspection for the purpose of SQL address discovery. It must resolve
 and be routable from clients.

If left unspecified, it defaults to the setting of --sql-addr. If the flag
 is provided but either the address part or the port part is left unspecified,
 that particular part defaults to the same part in --sql-addr.

An IPv6 address can also be specified with the notation [...], for example
 [::1]:26257 or [fe80::f6f2:::]:26257.

The port number should be the same as in --sql-addr unless port forwarding is
 set up on an intermediate firewall/router.

--attrs=""

An ordered, colon-separated list of node attributes. Attributes are arbitrary
 strings specifying machine capabilities. Machine capabilities might include
 specialized hardware or number of cores (e.g. "gpu", "x16c"). For example:

--attrs=x16c:gpu

--background[=false]

Start the server in the background. This is similar to appending "&" to the
 command line, but when the server is started with --background, control is not
 returned to the shell until the server is ready to accept requests.

--cache=256 MiB

Total size in bytes for caches, shared evenly if there are multiple storage
 devices. Size suffixes are supported (e.g. 1GB and 1GiB). If left unspecified,
 defaults to 128MiB. A percentage of physical memory can also be specified
 (e.g. .25).

--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
 such as "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. It is permissible for the string to contain colons.

--certs-dir="/home/builder/.cockroach-certs"

Path to the directory containing SSL certificates and keys.

--clock-device=""

Override HLC to use PTP hardware clock user space API when querying for
 current time. The value corresponds to the clock device to be used. This is
 currently only tested and supported on Linux.

--clock-device=/dev/ptp0

--cluster-name=

Sets a name to verify the identity of a remote node or cluster. The value must
 match between this node and the remote node(s) specified via --join.

This can be used as an additional verification when either the node or
 cluster, or both, have not yet been initialized and do not yet know their
 cluster ID.

To introduce a cluster name into an already-initialized cluster, pair this
 flag with --disable-cluster-name-verification.

--disable-cluster-name-verification[=false]

Tell the server to ignore cluster name mismatches. This is meant for use when
 opting an existing cluster into starting to use cluster name verification, or
 when changing the cluster name.

The cluster should be restarted once with --cluster-name and
 --disable-cluster-name-verification combined, and once all nodes have been
 updated to know the new cluster name, the cluster can be restarted again with
 this flag removed.

--disable-max-offset-check[=false]

Normally, a node will self-terminate if it finds that its clock offset with
 the rest of the cluster exceeds --max-offset. This flag disables this check.
 The operator is responsible for ensuring that real clock skew never exceeds
 max-offset, to avoid read inconsistencies and other correctness anomalies.

--enterprise-encryption=

Specify encryption options for one of the stores on a node. If multiple
 stores exist, the flag must be specified for each store.

A valid enterprise license is required to use this functionality.

Key files should be generated by "cockroach gen encryption-key".

Valid fields:

    •   path (required): must match the path of one of the stores, or the special
                           value "*" to match all stores

    •   key (required): path to the current key file, or "plain"

    •   old-key (required): path to the previous key file, or "plain"

    •   rotation-period : amount of time after which data keys should be rotated

example:
   --enterprise-encryption=path=cockroach-data,key=/keys/aes-128.key,old-key=plain

--experimental-dns-srv[=false]

When enabled, the node will first attempt to fetch SRV records from DNS
 for every name specified with --join. If a valid SRV record is found, that
 information is used instead of regular DNS A/AAAA lookups. This feature is
 experimental and may be removed or modified in a later version.

--experimental-secondary-cache=n/a

Enables the use of a secondary cache to store objects from shared storage (see
 --experimental-shared-storage) inside local paths for each store. A size must
 be specified with this flag, which will be the maximum size for the secondary
 cache on each store on this node:

--experimental-secondary-cache=20GiB

The size can be given in various ways:

--experimental-secondary-cache=10000000000 -> 10000000000 bytes
   --experimental-secondary-cache=20GB -> 20000000000 bytes
   --experimental-secondary-cache=20GiB -> 21474836480 bytes
   --experimental-secondary-cache=20% -> 20% of available space
   --experimental-secondary-cache=0.2 -> 20% of available space
   --experimental-secondary-cache=.2 -> 20% of available space

--experimental-shared-storage=""

Shared storage URL (with a cloud scheme, eg. s3://, gcs://) to use for
 all stores on this cockroach node. Cockroach can take advantage of this
 storage for faster replication from node to node, as well as to grow beyond
 locally-available disk space. The format of this URL is the same as that
 specified for bulk operations, for more on that see:
 https://www.cockroachlabs.com/docs/v26.1/use-cloud-storage-for-bulk-operations
 This is an experimental option, and must be specified on every start of this
 node starting from the very first call to start. Passing this flag on an
 existing initialized node is not supported.

--external-io-dir=""

The local file path under which remotely-initiated operations that can specify
 node-local I/O paths, such as BACKUP, RESTORE or IMPORT, can access files.
 Following symlinks is allowed, meaning that other paths can be added by
 symlinking to them from within this path.

Note: operations in a distributed cluster can run across many nodes, so
 reading or writing to any given node's local file system in a distributed
 cluster is not usually useful unless that filesystem is actually backed by
 something like NFS.

If left empty, defaults to the "extern" subdirectory of the first store
 directory.

The value "disabled" will disable all local file I/O.

--external-io-disable-http[=false]

Disable use of HTTP when accessing external data.

--external-io-disable-implicit-credentials[=false]

Disable use of implicit credentials when accessing external data. Instead,
 require the user to always specify access keys.

--external-io-disabled[=false]

Disable use of "external" IO, such as to S3, GCS, or the file system
 (nodelocal), or anything other than userfile.

--external-io-enable-non-admin-implicit-access[=false]

Allow non-admin users to specify arbitrary network addressses
 (e.g. https:// URIs or custom endpoints in s3:// URIs) and implicit
 credentials (machine account/role providers) when running operations
 like IMPORT/EXPORT/BACKUP/etc. Note: that --external-io-disable-http or
 --external-io-disable-implicit-credentials still apply, this only removes the
 admin-user requirement.

--go-gc-percent=0

Garbage collection target percentage set on the Go runtime (which is also
 configurable via the GOGC environment variable, but --go-gc-percent has higher
 precedence if both are set). A garbage collection is triggered when the ratio
 of freshly allocated data to live data remaining after the previous collection
 reaches this percentage. If left unspecified, defaults to 300%. If set to a
 negative value, disables the target percentage garbage collection heuristic,
 leaving only the soft memory limit heuristic to trigger garbage collection.

-h, --help[=false]
    help for start

--http-addr=:8080

The hostname or IP address to bind to for HTTP requests. If left unspecified,
 the address part defaults to the setting of --listen-addr. The port number
 defaults to 8080. An IPv6 address can also be specified with the notation
 [...], for example [::1]:8080 or [fe80::f6f2:::]:8080.

--insecure[=false]

Start a node with all security controls disabled. There is no encryption, no
 authentication and internal security checks are also disabled. This makes any
 client able to take over the entire cluster.

This flag is only intended for non-production testing.

Beware that using this flag on a public network without --listen-addr is
 likely to cause the entire host server to become compromised.

To simply accept non-TLS connections for SQL clients while keeping the
 cluster secure, consider using --accept-sql-without-tls instead. Also see:
 https://go.crdb.dev/issue-v/53404/v26.1

-j, --join=""

The addresses for connecting a node to a cluster.

When starting a multi-node cluster for the first time, set this flag to the
 addresses of 3-5 of the initial nodes. Then run the cockroach init command
 against one of the nodes to complete cluster startup.

When starting a singe-node cluster, leave this flag out. This will cause
 the node to initialize a new single-node cluster without needing to run the
 cockroach init command.

When adding a node to an existing cluster, set this flag to 3-5 of the nodes
 already in the cluster; it's easiest to use the same list of addresses that
 was used to start the initial nodes.

This flag can be specified separately for each address:

--join=localhost:1234 --join=localhost:2345

Or can be specified as a comma separated list in single flag, or both forms
 can be used together, for example:

--join=localhost:1234,localhost:2345 --join=localhost:3456

--listen-addr=:26257

The address/hostname and port to listen on for intra-cluster communication,
 for example --listen-addr=myhost:26257 or --listen-addr=:26257 (listen on all
 interfaces).

If the address part is left unspecified, it defaults to the "all interfaces"
 address (0.0.0.0 IPv4 / [::] IPv6). If the port part is left unspecified, it
 defaults to 26257.

An IPv6 address can also be specified with the notation [...], for example
 [::1]:26257 or [fe80::f6f2:::]:26257.

If --advertise-addr is left unspecified, the node will also announce
 this address for use by other nodes. It is strongly recommended to use
 --advertise-addr in cloud and container deployments or any setup where NAT is
 present between cluster nodes.

Unless --sql-addr is also specified, this address is also used to accept SQL
 client connections. Using --listen-addr to specify the SQL address without
 --sql-addr is a deprecated feature.

--listening-url-file=""

After the CockroachDB node has started up successfully, it will write its
 connection URL to the specified file.

--locality=

An ordered, comma-separated list of key-value pairs that describe the
 topography of the machine. Topography often includes cloud provider regions
 and availability zones, but can also refer to on-prem concepts like datacenter
 or rack. Data is automatically replicated to maximize diversities of each
 tier. The order of tiers is used to determine the priority of the diversity,
 so the more inclusive localities like region should come before less inclusive
 localities like availability zone. The tiers and order must be the same on all
 nodes. Including more tiers is better than including fewer. For example:

--locality=cloud=gce,region=us-west1,zone=us-west-1b
   --locality=cloud=aws,region=us-east,zone=us-east-2

This flag is incompatible with --locality-file.

--locality-advertise-addr=

List of ports to advertise to other CockroachDB nodes for intra-cluster
 communication for some locality. This should be specified as a comma separated
 list of locality@address. Addresses can also include ports. For example:

"region=us-west@127.0.0.1,zone=us-west-1b@127.0.0.1"
   "region=us-west@127.0.0.1:26257,zone=us-west-1b@127.0.0.1:26258"

--locality-file=""

File name to read locality data from. Using this flag has the same effect as
 providing the file's contents directly via the --locality flag. Any leading or
 trailing whitespace characters, as defined by Unicode, will be automatically
 trimmed.

This flag is incompatible with --locality.

--max-disk-temp-storage=

Maximum storage capacity available to store temporary disk-based data for SQL
 queries that exceed the memory budget (e.g. join, sorts, etc are sometimes
 able to spill intermediate results to disk). Accepts numbers interpreted as
 bytes, size suffixes (e.g. 32GB and 32GiB) or a percentage of disk size (e.g.
 10%). If left unspecified, defaults to 32GiB.

The location of the temporary files is within the first store dir (see
 --store). If expressed as a percentage, --max-disk-temp-storage is interpreted
 relative to the size of the storage device on which the first store is placed.
 The temp space usage is never counted towards any store usage (although it
 does share the device with the first store) so, when configuring this, make
 sure that the size of this temp storage plus the size of the first store don't
 exceed the capacity of the storage device.

If the first store is an in-memory one (i.e. type=mem), then this temporary
 "disk" data is also kept in-memory. A percentage value is interpreted as a
 percentage of the available internal memory. If not specified, the default
 shifts to 100MiB when the first store is in-memory.

--max-go-memory=0 B

Soft memory limit set on the Go runtime (which is also configurable via the
 GOMEMLIMIT environment variable, but --max-go-memory has higher precedence
 if both are set). Notably, the pebble cache (as configured by --cache) is not
 under control of the Go runtime and should not be considered when determining
 this soft memory limit. Accepts numbers interpreted as bytes, size suffixes
 (e.g. 1GB and 1GiB) or a percentage of physical memory (e.g. .25). If left
 unspecified, defaults to 2.25x of --max-sql-memory (subject to max-go-memory
 + 1.15x --cache not exceeding 90% of available RAM). Set to 0 to disable the
 soft memory limit (not recommended).

--max-offset=500ms

Maximum clock offset for the cluster. If real clock skew exceeds this
 value, consistency guarantees can no longer be upheld, possibly resulting
 in stale reads and other anomalies. This value affects the frequency of
 uncertainty-based read restarts and write latencies for global tables.

If a node detects that its clock offset from other nodes is too large, it will
 self-terminate to protect consistency guarantees. This check can be disabled
 via --disable-max-offset-check.

This value should be the same on all nodes in the cluster. It is allowed to
 differ such that the max-offset value can be changed via a rolling restart of
 the cluster, in which case the real clock skew between nodes must be below the
 smallest max-offset value of any node.

--max-sql-memory=16 GiB

Maximum memory capacity available to store temporary data for SQL clients,
 including prepared queries and intermediate data rows during query execution.
 Accepts numbers interpreted as bytes, size suffixes (e.g. 1GB and 1GiB) or a
 percentage of physical memory (e.g. .25). If left unspecified, defaults to 25%
 of physical memory.

--max-tsdb-memory=641 MiB

Maximum memory capacity available to store temporary data for use by the
 time-series database to display metrics in the DB Console. Accepts numbers
 interpreted as bytes, size suffixes (e.g. 1GB and 1GiB) or a percentage of
 physical memory (e.g. 0.01). If left unspecified, defaults to 1% of physical
 memory or 64MiB whichever is greater. It maybe necessary to manually increase
 this value on a cluster with hundreds of nodes where individual nodes have
 very limited memory available. This can constrain the ability of the DB
 Console to process time-series queries used to render metrics for the entire
 cluster. This capacity constraint does not affect SQL query execution.

--node-cert-distinguished-name=""

A string of comma separated list of distinguished-name
 = mappings in accordance with RFC4514 for
 the node user. This strictly needs to match the DN subject in the client
 certificate provided for node user if this flag is set.

--pid-file=""

After the CockroachDB node has started up successfully, it will write its
 process ID to the specified file.

--root-cert-distinguished-name=""

A string of comma separated list of distinguished-name
 = mappings in accordance with RFC4514 for
 the root user. This strictly needs to match the DN subject in the client
 certificate provided for root user if this flag is set.

--socket-dir=""

Accept client connections using a Unix domain socket created in the specified
 directory. Note: for compatibility with PostgreSQL clients and drivers, the
 generated socket name has the form "/path/to/.s.PGSQL.NNNN", where NNNN is the
 port number configured via --listen-addr. PostgreSQL clients only take a port
 number and directory as input and construct the socket name programmatically.
 To use, for example:

    psql -h /path/to -p NNNN ...

Environment variable: COCKROACH_SOCKET_DIR

--spatial-libs="/usr/local/lib/cockroach"

The location where all libraries for spatial operations is located.

--sql-addr=:

The hostname or IP address to bind to for SQL clients, for example
 --sql-addr=myhost:26257 or --sql-addr=:26257 (listen on all interfaces).

If specified but the address part is omitted, the address part defaults to the
 address part of --listen-addr. If specified but the port number is omitted,
 the port number defaults to 26257.

To actually use separate bindings, it is recommended to specify both flags and
 use a different port number via --listen-addr, for example --sql-addr=:26257
 --listen-addr=:26258. Ensure that --join is set accordingly on other nodes. It
 is also possible to use the same port number but separate host addresses.

An IPv6 address can also be specified with the notation [...], for example
 [::1]:26257 or [fe80::f6f2:::]:26257.

If --sql-addr is left unspecified, the address specified by --listen-addr will
 be used for both RPC and SQL connections. This default behavior is deprecated;
 we recommend always setting --sql-addr.

--storage-engine=""

Deprecated: only present for backward compatibility.

-s, --store=

The file path to a storage device. This flag must be specified separately for
 each storage device, for example:

--store=/mnt/ssd01 --store=/mnt/ssd02 --store=/mnt/hda1

For each store, the "attrs" and "size" fields can be used to specify device
 attributes and a maximum store size (see below). When one or both of these
 fields are set, the "path" field label must be used for the path to the
 storage device, for example:

--store=path=/mnt/ssd01,attrs=ssd,size=20GiB

In most cases, node-level attributes are preferable to store-level attributes.
 However, the "attrs" field can be used to match capabilities for storage
 of individual databases or tables. For example, an OLTP database would
 probably want to allocate space for its tables only on solid state devices,
 whereas append-only time series might prefer cheaper spinning drives. Typical
 attributes include whether the store is flash (ssd), spinny disk (hdd),
 or in-memory (mem), as well as speeds and other specs. Attributes can be
 arbitrary strings separated by colons, for example:

--store=path=/mnt/hda1,attrs=hdd:7200rpm

The store size in the "size" field is not a guaranteed maximum but is
 used when calculating free space for rebalancing purposes. The size can be
 specified either in a bytes-based unit or as a percentage of hard drive space,
 for example:

--store=path=/mnt/ssd01,size=10000000000 -> 10000000000 bytes
   --store=path=/mnt/ssd01,size=20GB -> 20000000000 bytes
   --store=path=/mnt/ssd01,size=20GiB -> 21474836480 bytes
   --store=path=/mnt/ssd01,size=0.02TiB -> 21474836480 bytes
   --store=path=/mnt/ssd01,size=20% -> 20% of available space
   --store=path=/mnt/ssd01,size=0.2 -> 20% of available space
   --store=path=/mnt/ssd01,size=.2 -> 20% of available space

For an in-memory store, the "type" and "size" fields are required, and the
 "path" field is forbidden. The "type" field must be set to "mem", and the
 "size" field must be set to the true maximum bytes or percentage of available
 memory that the store may consume, for example:

--store=type=mem,size=20GiB
   --store=type=mem,size=90%

Optionally, to configure admission control enforcement to prevent disk
 bandwidth saturation, the "provisioned-rate" field can be specified with the
 "disk-name" and an optional "bandwidth". The bandwidth is used to override
 the value of the cluster setting, kvadmission.store.provisioned_bandwidth. For
 example:

--store=provisioned-rate=disk-name=nvme1n1
   --store=provisioned-rate=disk-name=sdb:bandwidth=250MiB/s

Commas are forbidden in all values, since they are used to separate fields.
 Also, if you use equal signs in the file path to a store, you must use the
 "path" field label. (default is 'cockroach-data' in current directory except
 for mt commands which use 'cockroach-data-tenant-X' for tenant 'X')

--temp-dir=""

The parent directory path where a temporary subdirectory will be created to
 be used for temporary files. This path must exist or the node will not start.
  The encryption from one of the stores is used with the temporary directory
 (specifically, the first store that is on-disk and encrypted). The temporary
 subdirectory is used primarily as working memory for distributed computations
 and CSV importing. For example, the following will generate an arbitrary,
 temporary subdirectory "/mnt/ssd01/temp/cockroach-temp":

--temp-dir=/mnt/ssd01/temp

If this flag is unspecified, the temporary subdirectory will be located under
 the root of one of the stores (with preference for on-disk, encrypted stores).

--tls-cipher-suites=[]

A string of comma separated list of cipher suites to be used for all incoming
 TLS connections to the node. For TLS 1.2, this should strictly be a subset of
 suites defined in security/tls_ciphersuites.go as RecommendedCipherSuites or
 OldCipherSuites. For TLS 1.3, this should be configured to a subset of ciphers
 in crypto/tls/cipher_suites.go, e.g. TLS_AES_256_GCM_SHA384.

--unencrypted-localhost-http[=false]

When specified, restricts HTTP connections to localhost-only and disables
 TLS for the HTTP interface. The hostname part of --http-addr, if specified,
 is then ignored. This flag is intended for use to facilitate local testing
 without requiring certificate setups in web browsers.

--wal-failover=""

Configures the use and behavior of WAL failover. WAL failover enables
 automatic failover to another directory if a WAL write does not complete
 within the configured threshold. Defaults to "disabled". Possible values
 depend on the number of stores a node is configured to use. If a node has
 multiple stores, the value "among-stores" enables automatic failover to
 another store's data directory. CockroachDB will automatically assign each
 store a secondary to serve as its WAL failover destination. For example:

--wal-failover=among-stores

If a node has a single store, the value "path=" enables automatic
 failover to the provided path. After this setting is used, changing the
 configuration to a new path or disabling requires providing the previous path
 as ",prev_path=". For example:

     --wal-failover=path=/mnt/data2
     --wal-failover=path=/mnt/data3,prev_path=/mnt/data2
     --wal-failover=disabled,prev_path=/mnt/data3

See the storage.wal_failover.unhealthy_op_threshold cluster setting.
 Environment variable: COCKROACH_WAL_FAILOVER

OPTIONS INHERITED FROM PARENT COMMANDS

--enterprise-require-fips-ready[=false]
    abort if FIPS readiness checks fail

--log=

Logging configuration, expressed using YAML syntax. For example, you can
 change the default logging directory with: --log='file-defaults: {dir: ...}'.
 See the documentation for more options and details. To preview how the log
 configuration is applied, or preview the default configuration, you can use
 the 'cockroach debug check-log-config' sub-command.

--log-config-file=

File name to read the logging configuration from. This has the same effect as
 passing the content of the file via the --log flag.

--log-config-vars=[]

Environment variables that will be expanded if present in the body of the
 logging configuration.

--log-dir=

--log-dir=XXX is an alias for --log='file-defaults: {dir: XXX}'.

--logtostderr[=UNKNOWN]

--logtostderr=XXX is an alias for --log='sinks: {stderr: {filter: XXX}}'. If
 no value is specified, the default value for the command is inferred: INFO for
 server commands, WARNING for client commands.

--redactable-logs=false

--redactable-logs=XXX is an alias for --log='file-defaults: {redactable:
 XXX}}'.

--vmodule=
    comma-separated list of pattern=N settings for file-filtered logging (significantly hurts performance)

EXAMPLE

      cockroach start --insecure --store=attrs=ssd,path=/mnt/ssd1 --join=host:port,[host:port]

SEE ALSO

cockroach(1)

HISTORY

13-May-2026 Auto generated by spf13/cobra