Skip to main content
yugabyted is a command-line utility for deploying and managing YugabyteDB universes locally on your laptop or on VMs for production deployments.

​
Synopsis

yugabyted [-h] [command] [flags]

​
Description

yugabyted provides a simplified way to manage YugabyteDB clusters without directly managing YB-Master and YB-TServer processes. It handles installation, configuration, and lifecycle management of YugabyteDB nodes. Key features:
  • Single command to start/stop/destroy clusters
  • Built-in configuration for multi-zone/multi-region deployments
  • Integrated backup and restore capabilities
  • Support for xCluster replication
  • Point-in-time recovery (PITR) configuration
  • TLS/SSL certificate generation

​
Installation

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

​
Base Directory

By default, yugabyted uses $HOME/var to store data, configurations, and logs. You can override this with the --base_dir flag: 
yugabyted start --base_dir /home/user/node1
When using a custom base directory, you must specify it for all subsequent commands.

​
Commands

​
start

Start a YugabyteDB node and optionally join an existing cluster. 
yugabyted start [flags]

​
Common Flags

FlagDescription
--advertise_addressIP address to advertise to other nodes
--base_dirBase directory for data, logs, and configuration
--cloud_locationCloud location in format cloud.region.zone
--joinJoin existing cluster at specified address
--listen(Deprecated) Use --advertise_address instead
--master_flagsAdditional flags for yb-master
--tserver_flagsAdditional flags for yb-tserver
--master_webserver_portMaster web server port (default: 7000)
--tserver_webserver_portTServer web server port (default: 9000)
--ysql_portYSQL port (default: 5433)
--ycql_portYCQL port (default: 9042)
--backgroundRun in background mode (default: true)
--uiEnable yugabyted UI (default: true)

​
Security Flags

FlagDescription
--secureEnable TLS/SSL encryption
--insecureStart in insecure mode
--certs_dirDirectory containing TLS certificates
--ysql_enable_authEnable YSQL authentication
--use_cassandra_authenticationEnable YCQL authentication

​
Advanced Flags

FlagDescription
--fault_toleranceFault tolerance level: none, zone, region
--rfReplication factor (default: 3)
--read_replicaStart as read replica node
--backup_daemonEnable backup daemon
--callhomeEnable telemetry (default: true)
--enhance_time_sync_via_clockboundUse clockbound for time synchronization
--initial_scripts_dirDirectory with initialization scripts

​
Examples

# Create a single-node local cluster
yugabyted start

# Join other nodes in the same cluster
yugabyted start --join=host:port

# Create a secure cluster
yugabyted start --secure --certs_dir=/path/to/certs

# Use clockbound for precise time
yugabyted start --enhance_time_sync_via_clockbound

# Start with custom cloud location
yugabyted start --cloud_location=aws.us-west-2.us-west-2a

​
stop

Stop a running YugabyteDB node. 
yugabyted stop [flags]

​
Flags

FlagDescription
--base_dirBase directory of the node to stop

​
Example

yugabyted stop --base_dir /home/user/node1

​
destroy

Destroy a YugabyteDB cluster and remove all data. 
yugabyted destroy [flags]

​
Flags

FlagDescription
--base_dirBase directory of the node to destroy

​
Example

yugabyted destroy --base_dir /home/user/node1

​
status

Print the status of a YugabyteDB cluster. 
yugabyted status [flags]

​
Example Output

$ yugabyted status
+--------------------------------------------------------------------------------------------------+
|                                            yugabyted                                             |
+--------------------------------------------------------------------------------------------------+
| Status              : Running.                                                                   |
| Replication Factor  : 1                                                                          |
| YugabyteDB UI       : http://127.0.0.1:15433                                                     |
| JDBC                : jdbc:postgresql://127.0.0.1:5433/yugabyte?user=yugabyte&password=yugabyte  |
| YSQL                : bin/ysqlsh -h 127.0.0.1                                                    |
| YCQL                : bin/ycqlsh 127.0.0.1 9042 -u cassandra                                     |
| Data Dir            : /home/user/var/data                                                        |
| Log Dir             : /home/user/var/logs                                                        |
+--------------------------------------------------------------------------------------------------+

​
version

Display the YugabyteDB version. 
yugabyted version

​
configure

Configure cluster settings for data placement, encryption, admin operations, and PITR.

​
configure data_placement

Configure multi-zone or multi-region data placement. 
yugabyted configure data_placement --fault_tolerance=<zone|region> [flags]
Flags
FlagDescription
--fault_toleranceFault tolerance level: zone or region
--constraint_valueData placement constraint
--rfReplication factor
--base_dirBase directory
Example
# Configure multi-zone cluster
yugabyted configure data_placement --fault_tolerance=zone

​
configure encrypt_at_rest

Enable or disable encryption at rest. 
yugabyted configure encrypt_at_rest --enable|--disable [flags]
Examples
# Enable encryption at rest
yugabyted configure encrypt_at_rest --enable

# Disable encryption at rest
yugabyted configure encrypt_at_rest --disable

​
configure admin_operation

Execute yb-admin commands on the cluster. 
yugabyted configure admin_operation --command <yb-admin_command> [flags]
Flags
FlagDescription
--commandyb-admin command to execute
--master_addressesComma-separated master addresses
Example
yugabyted configure admin_operation --command "list_all_masters"

​
configure point_in_time_recovery

Configure point-in-time recovery for databases or keyspaces. 
yugabyted configure point_in_time_recovery [flags]
Flags
FlagDescription
--enableEnable PITR
--disableDisable PITR
--databaseYSQL database name
--keyspaceYCQL keyspace name
--retentionRetention period in days
--statusDisplay PITR status
Examples
# Enable PITR for a database with 7-day retention
yugabyted configure point_in_time_recovery --enable --database yugabyte --retention 7

# Check PITR status
yugabyted configure point_in_time_recovery --status

# Disable PITR
yugabyted configure point_in_time_recovery --disable --database yugabyte

​
configure_read_replica

Configure, modify, or delete read replica clusters.

​
configure_read_replica new

Create a new read replica cluster. 
yugabyted configure_read_replica new --rf=<replication_factor> \
  --data_placement_constraint=<placement_policy>

​
configure_read_replica modify

Modify an existing read replica cluster. 
yugabyted configure_read_replica modify --rf=<new_replication_factor> \
  --data_placement_constraint=<new_placement_policy>

​
configure_read_replica delete

Delete a read replica cluster. 
yugabyted configure_read_replica delete

​
backup

Back up a YugabyteDB database to cloud storage or network file system. 
yugabyted backup --database=<name> --cloud_storage_uri=<uri> [flags]

​
Flags

FlagDescription
--databaseYSQL database to backup
--keyspaceYCQL keyspace to backup
--cloud_storage_uriS3, GCS, Azure, or NFS path
--statusCheck backup task status
--base_dirBase directory

​
Examples

# Backup to AWS S3
yugabyted backup --database=northwind --cloud_storage_uri=s3://my-bucket/backups

# Backup to network file storage
yugabyted backup --database=northwind --cloud_storage_uri=/nfs/backups

# Check backup status
yugabyted backup --database=northwind --cloud_storage_uri=s3://my-bucket --status

​
restore

Restore a YugabyteDB database from cloud storage or perform point-in-time recovery. 
yugabyted restore --database=<name> --cloud_storage_uri=<uri> [flags]

​
Flags

FlagDescription
--databaseYSQL database to restore
--keyspaceYCQL keyspace to restore
--cloud_storage_uriS3, GCS, Azure, or NFS path
--recover_to_point_in_timeTimestamp for PITR
--statusCheck restore task status
--base_dirBase directory

​
Examples

# Restore from S3
yugabyted restore --database=northwind --cloud_storage_uri=s3://my-bucket/backups

# Point-in-time recovery
yugabyted restore --recover_to_point_in_time '2024-01-29 9:30:00 PM' --database yugabyte

# Check restore status
yugabyted restore --database=northwind --cloud_storage_uri=s3://my-bucket --status

​
connect

Connect to the YugabyteDB cluster using YSQL or YCQL shell.

​
connect ysql

Connect using ysqlsh. 
yugabyted connect ysql [flags]
Flags
FlagDescription
--usernameYSQL username
--passwordYSQL password
--databaseDatabase name
--base_dirBase directory
Example
yugabyted connect ysql --username yugabyte --database northwind

​
connect ycql

Connect using ycqlsh. 
yugabyted connect ycql [flags]
Flags
FlagDescription
--usernameYCQL username
--passwordYCQL password
--keyspaceKeyspace name
--base_dirBase directory
Example
yugabyted connect ycql --username cassandra --keyspace system

​
demo

Load and interact with preset demo data.

​
demo connect

Connect to a demo database with sample data. 
yugabyted demo connect [flags]

​
demo destroy

Destroy the demo database. 
yugabyted demo destroy [flags]

​
cert

Generate TLS/SSL certificates for secure clusters.

​
cert generate_server_certs

Generate server certificates for cluster nodes. 
yugabyted cert generate_server_certs --hostnames=<comma_separated_hostnames>
Example
yugabyted cert generate_server_certs --hostnames=node1.example.com,node2.example.com,node3.example.com

​
collect_logs

Collect and package logs for troubleshooting. 
yugabyted collect_logs [flags]

​
Flags

FlagDescription
--stdoutOutput logs to stdout (for Docker)
--collect_at_dirDirectory to store logs.tar.gz
--base_dirBase directory

​
Examples

# Collect logs to file
yugabyted collect_logs

# Collect logs in Docker
docker exec <container-id> bin/yugabyted collect_logs --stdout > yugabyted.tar.gz

​
upgrade

Upgrade YugabyteDB nodes to a new version.

​
upgrade ysql_catalog

Upgrade YSQL catalog metadata. 
yugabyted upgrade ysql_catalog [--timeout=<milliseconds>]

​
upgrade finalize_new_version

Finalize the upgrade to the new version. 
yugabyted upgrade finalize_new_version [--timeout=<milliseconds>]

​
upgrade check_version_compatibility

Check version compatibility before upgrading. 
yugabyted upgrade check_version_compatibility [--timeout=<milliseconds>]

​
finalize_upgrade

Finalize the upgrade process for the cluster. 
yugabyted finalize_upgrade [--upgrade_ysql_timeout=<milliseconds>]

​
xcluster

Setup and manage xCluster replication between clusters.

​
xcluster create_checkpoint

Initialize xCluster replication (run on source cluster). 
yugabyted xcluster create_checkpoint --replication_id=<id> --databases=<db_list> [flags]
Flags
FlagDescription
--replication_idUnique replication identifier
--databasesComma-separated database names
--automatic_modeSetup in automatic mode
Example
yugabyted xcluster create_checkpoint --replication_id=rep1 --databases=db1,db2

​
xcluster add_to_checkpoint

Add databases to an existing xCluster checkpoint (run on source). 
yugabyted xcluster add_to_checkpoint --replication_id=<id> --databases=<db_list>

​
xcluster set_up

Setup xCluster replication (run on source cluster). 
yugabyted xcluster set_up --target_address=<ip> --replication_id=<id> --bootstrap_done
Flags
FlagDescription
--target_addressIP of target cluster node
--replication_idReplication ID from checkpoint
--bootstrap_doneIndicate bootstrapping complete

​
xcluster add_to_replication

Add databases to existing replication (run on source). 
yugabyted xcluster add_to_replication --target_address=<ip> \
  --replication_id=<id> --databases=<db_list> --bootstrap_done

​
xcluster status

Display xCluster replication status. 
yugabyted xcluster status [--base_dir=<dir>]

​
xcluster delete_replication

Delete xCluster replication (run on source). 
yugabyted xcluster delete_replication --replication_id=<id>

​
xcluster remove_database_from_replication

Remove databases from replication (run on source). 
yugabyted xcluster remove_database_from_replication --replication_id=<id> --databases=<db_list>

​
Environment Variables

VariableDescription
YB_DISABLE_CALLHOMEDisable telemetry (set to true)
YSQL_PASSWORDDefault YSQL password
YCQL_USERDefault YCQL username
YCQL_PASSWORDDefault YCQL password

​
Exit Status

yugabyted returns 0 on success, non-zero on failure.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us