yugabyted Reference - YugabyteDB

yugabyted is a utility for deploying and managing YugabyteDB clusters. It simplifies the process of creating single-node and multi-node clusters, making it ideal for both local development and production deployments.

yugabyted can be used for production deployments. You can also administer yb-tserver and yb-master servers directly for more granular control.

Installation

The yugabyted executable is packaged with YugabyteDB and located in the bin directory of your YugabyteDB installation.

YB Controller for Backup/Restore

To use backup and restore features, install the YB Controller service from the share directory:

cd yugabyte-<version>
mkdir ybc
tar -xvf share/ybc-*.tar.gz -C ybc --strip-components=1

Start yugabyted with backup daemon enabled:

./bin/yugabyted start --backup_daemon=true

YB Controller is not supported on macOS.

Syntax

yugabyted [-h] [command] [flags]

Example

./bin/yugabyted start --advertise_address=10.0.0.1 --base_dir=/data/yb

Online Help

Display general help:

./bin/yugabyted --help

Display help for a specific command:

./bin/yugabyted start --help

Base Directory

By default, yugabyted uses $HOME/var to store data, configurations, and logs. You can change this using the --base_dir flag:

./bin/yugabyted start --base_dir=/home/user/node1

When using a custom base directory, you must specify it with --base_dir in all subsequent commands.

Commands

start

Start a YugabyteDB cluster or add a node to an existing cluster.

Syntax

yugabyted start [flags]

Common Start Flags

--advertise_address

string

IP address or hostname that other nodes use to connect to this node.Default: Auto-detected private IP

--base_dir

string

Base directory for data, configuration, and logs.Default: $HOME/var

--cloud_location

string

Cloud location in cloud.region.zone format for geo-distribution.Example: aws.us-west-2.us-west-2a

--data_dir

string

Directory where data is stored. If not specified, uses <base_dir>/data.

--fault_tolerance

string

Fault tolerance level for the cluster.Valid values: zone, region, cloudDefault: none

--join

string

Address of an existing node to join the cluster. Use for multi-node clusters.Example: --join=10.0.0.1

--listen

string

IP address or hostname to bind to for connections.Default: 127.0.0.1 (use 0.0.0.0 for all interfaces)

--master_flags

string

Comma-separated list of yb-master flags to set.Example: --master_flags="log_cache_size_limit_mb=256,max_log_size=1024"

--tserver_flags

string

Comma-separated list of yb-tserver flags to set.Example: --tserver_flags="memstore_size_mb=512,tablet_enable_ttl_file_filter=true"

--rf

int

Replication factor for the cluster.Default: 1 (single-node), 3 (multi-node)Valid range: 1-7 (odd numbers recommended)

--ui

boolean

Enable the yugabyted UI.Default: true

--backup_daemon

boolean

Start the YB Controller backup daemon.Default: false

--enable_pg_parity_tech_preview

boolean

Enable PostgreSQL parity features (tech preview).Default: false

YSQL Flags

--ysql_port

int

Port for YSQL connections.Default: 5433

--enable_ysql

boolean

Enable YSQL API.Default: true

YCQL Flags

--ycql_port

int

Port for YCQL connections.Default: 9042

--enable_ycql

boolean

Enable YCQL API.Default: false

Security Flags

--secure

boolean

Enable encryption in transit and authentication.Default: false

--cert_dir

string

Directory containing SSL certificates.

--initial_scripts_dir

string

Directory containing SQL scripts to run on first start.

Example: Start a Multi-Node Cluster

# Node 1 (first node)
./bin/yugabyted start \
  --advertise_address=10.0.0.1 \
  --base_dir=/data/node1 \
  --cloud_location=aws.us-west-2.us-west-2a

# Node 2
./bin/yugabyted start \
  --advertise_address=10.0.0.2 \
  --base_dir=/data/node2 \
  --join=10.0.0.1 \
  --cloud_location=aws.us-west-2.us-west-2b

# Node 3
./bin/yugabyted start \
  --advertise_address=10.0.0.3 \
  --base_dir=/data/node3 \
  --join=10.0.0.1 \
  --cloud_location=aws.us-west-2.us-west-2c

status

Display the status of a yugabyted cluster.

Syntax

yugabyted status [flags]

Flags

--base_dir

string

Base directory of the yugabyted node.Default: $HOME/var

Example

./bin/yugabyted status --base_dir=/data/node1

stop

Stop a yugabyted cluster or node.

Syntax

yugabyted stop [flags]

Flags

--base_dir

string

Base directory of the yugabyted node to stop.Default: $HOME/var

Example

./bin/yugabyted stop --base_dir=/data/node1

destroy

Destroy a yugabyted cluster and delete all data.

Syntax

yugabyted destroy [flags]

This command permanently deletes all cluster data. Use with caution.

Flags

--base_dir

string

Base directory of the yugabyted node to destroy.Default: $HOME/var

Example

./bin/yugabyted destroy --base_dir=/data/node1

connect

Connect to the cluster using ysqlsh or ycqlsh.

Syntax

yugabyted connect [ysql|ycql] [flags]

YSQL Flags

--username

string

YSQL username to connect.Default: yugabyte

--password

string

Password for YSQL user.

--database

string

Name of the database to connect to.Default: yugabyte

--base_dir

string

Base directory of the yugabyted node.Default: $HOME/var

Example

# Connect with YSQL
./bin/yugabyted connect ysql

# Connect with YCQL
./bin/yugabyted connect ycql

configure

Configure cluster-level settings.

Syntax

yugabyted configure [flags]

Flags

--data_placement_constraint

string

Data placement constraint for the cluster in cloud.region.zone:num_replicas format.Example: aws.us-west-2.us-west-2a:1,aws.us-west-2.us-west-2b:1,aws.us-west-2.us-west-2c:1

--fault_tolerance

string

Set fault tolerance level.Valid values: zone, region, cloud

--rf

int

Set replication factor.

configure_read_replica

Configure, modify, or delete read replica clusters.

Syntax

yugabyted configure_read_replica [new|modify|delete] [flags]

Create New Read Replica

yugabyted configure_read_replica new \
  --rf=1 \
  --data_placement_constraint=aws.us-east-1.us-east-1a

Modify Read Replica

yugabyted configure_read_replica modify \
  --rf=2 \
  --data_placement_constraint=aws.us-east-1.us-east-1a,aws.us-east-1.us-east-1b

Delete Read Replica

yugabyted configure_read_replica delete

backup

Create a backup of a YugabyteDB database.

Requires YB Controller to be running (--backup_daemon=true).

Syntax

yugabyted backup [flags]

Flags

--namespace

string

required

Database namespace to backup.

--backup_location

string

required

Backup storage location (S3, GCS, Azure, or NFS path).Examples:

S3: s3://bucket-name/path
GCS: gs://bucket-name/path
Azure: https://account.blob.core.windows.net/container/path
NFS: /mnt/backup/path

Example: Backup to AWS S3

yugabyted backup \
  --namespace=yugabyte \
  --backup_location=s3://my-bucket/backups/$(date +%Y%m%d)

restore

Restore a YugabyteDB database from a backup.

Syntax

yugabyted restore [flags]

Flags

--namespace

string

required

Target database namespace for restore.

--backup_location

string

required

Location of the backup to restore from.

Example

yugabyted restore \
  --namespace=yugabyte \
  --backup_location=s3://my-bucket/backups/20260304

version

Display the YugabyteDB version.

Syntax

yugabyted version

collect_logs

Collect logs from the cluster for troubleshooting.

Syntax

yugabyted collect_logs [flags]

Flags

--base_dir

string

Base directory of the yugabyted node.Default: $HOME/var

--stdout

boolean

Output logs to stdout instead of a file.Default: false

demo

Start a demo cluster with sample data.

Syntax

yugabyted demo [command] [flags]

Commands

connect - Connect to the demo cluster
destroy - Destroy the demo cluster

Example

# Start demo
yugabyted demo

# Connect to demo
yugabyted demo connect

# Destroy demo
yugabyted demo destroy

Configuration Best Practices

Production Deployments

Use dedicated directories for data

--base_dir=/data/yugabyte --data_dir=/data/yugabyte/data

Set appropriate replication factor
```
--rf=3  # For high availability
```
Configure cloud location for geo-distribution
```
--cloud_location=aws.us-west-2.us-west-2a
```

Enable security features

--secure --cert_dir=/etc/yugabyte/certs

Tune flags for workload

--tserver_flags="memstore_size_mb=1024,tablet_enable_ttl_file_filter=true"

Multi-Region Setup

# Region 1 - Node 1
yugabyted start \
  --advertise_address=10.0.1.1 \
  --cloud_location=aws.us-west-2.us-west-2a \
  --fault_tolerance=region \
  --rf=3

# Region 2 - Node 2
yugabyted start \
  --advertise_address=10.0.2.1 \
  --cloud_location=aws.us-east-1.us-east-1a \
  --join=10.0.1.1 \
  --fault_tolerance=region \
  --rf=3

# Region 3 - Node 3
yugabyted start \
  --advertise_address=10.0.3.1 \
  --cloud_location=aws.eu-west-1.eu-west-1a \
  --join=10.0.1.1 \
  --fault_tolerance=region \
  --rf=3

Troubleshooting

Check Cluster Status

yugabyted status

Collect Logs

yugabyted collect_logs --base_dir=/data/node1

Common Issues

Port conflicts - Ensure ports 5433 (YSQL), 9042 (YCQL), 7000 (Master UI), 9000 (TServer UI) are available
Network connectivity - Verify firewall rules allow communication between nodes
Disk space - Ensure adequate disk space in base_dir and data_dir
Clock skew - Verify NTP is configured and clocks are synchronized

Configuration

System Tables

​Installation

​YB Controller for Backup/Restore

​Syntax

​Example

​Online Help

​Base Directory

​Commands

​start

​Syntax

​Common Start Flags

​YSQL Flags

​YCQL Flags

​Security Flags

​Example: Start a Multi-Node Cluster

​status

​Syntax

​Flags

​Example

​stop

​Syntax

​Flags

​Example

​destroy

​Syntax

​Flags

​Example

​connect

​Syntax

​YSQL Flags

​Example

​configure

​Syntax

​Flags

​configure_read_replica

​Syntax

​Create New Read Replica

​Modify Read Replica

​Delete Read Replica

​backup

​Syntax

​Flags

​Example: Backup to AWS S3

​restore

​Syntax

​Flags

​Example

​version

​Syntax

​collect_logs

​Syntax

​Flags

​demo

​Syntax

​Commands

​Example

​Configuration Best Practices

​Production Deployments

​Multi-Region Setup

​Troubleshooting

​Check Cluster Status

​Collect Logs

​Common Issues

​See Also

Build docs developers (and LLMs) love

Installation

YB Controller for Backup/Restore

Syntax

Example

Online Help

Base Directory

Commands

start

Syntax

Common Start Flags

YSQL Flags

YCQL Flags

Security Flags

Example: Start a Multi-Node Cluster

status

Syntax

Flags

Example

stop

Syntax

Flags

Example

destroy

Syntax

Flags

Example

connect

Syntax

YSQL Flags

Example

configure

Syntax

Flags

configure_read_replica

Syntax

Create New Read Replica

Modify Read Replica

Delete Read Replica

backup

Syntax

Flags

Example: Backup to AWS S3

restore

Syntax

Flags

Example

version

Syntax

collect_logs

Syntax

Flags

demo

Syntax

Commands

Example

Configuration Best Practices

Production Deployments

Multi-Region Setup

Troubleshooting

Check Cluster Status

Collect Logs

Common Issues

See Also