Y2
Databases AWS

YugabyteDB 2025.2.8.0 on AWS User Guide

| Product: YugabyteDB 2025.2.8.0 on Ubuntu 24.04 on AWS

Overview

This guide covers launching and using YugabyteDB 2025.2.8.0 on Ubuntu 24.04 from cloudimg on Amazon EC2. It is one version of cloudimg's distributed and embedded SQL databases listing on AWS Marketplace; you pick it as the software version when you subscribe and launch. The other databases in the listing are described on the listing's guide hub.

YugabyteDB is an open source distributed SQL database. It stores data in DocDB, a replicated, sharded document store, and puts two APIs on top of it: YSQL, which is PostgreSQL compatible (it reuses the PostgreSQL 15 query layer, so psql, PostgreSQL drivers and most PostgreSQL SQL work unchanged), and YCQL, which is compatible with Apache Cassandra's query language. Tables are split into tablets automatically; on a multi-node cluster the tablets are replicated and spread across nodes so the database keeps serving through node failures. This image runs a single-node cluster, which is the right start for development, testing and small production workloads, and the base you grow from.

The version is 2025.2.8.0 from the v2025.2 LTS (long-term support) series, released 23 October 2026 and maintained by Yugabyte until December 2027. cloudimg chose it over the newer v2026.1 STS series because the latest STS build does not yet carry the upstream PostgreSQL 15.19 security fixes that this LTS build includes.

What the cloudimg image adds:

  • No default login, passwords unique to your instance. Upstream YugabyteDB starts with authentication off and with the superusers yugabyte/yugabyte (YSQL) and cassandra/cassandra (YCQL). Here password authentication is on for both APIs, and the image ships no database at all: first boot creates the cluster inside a private network namespace that nothing else on the instance can reach, changes both superuser passwords to 32 character values generated on your instance, proves the upstream defaults are refused, and only then lets the database services start. The passwords are written to the root only file /root/yugabytedb-credentials.txt, never to a command line, a log or the journal.
  • Everything on localhost. Every YugabyteDB port listens on 127.0.0.1 only: YSQL (5433), YCQL (9042), the internal RPC ports (7100, 9100) and the web consoles (7000, 9000, 13000, 12000). From the network, only SSH is reachable; you connect through an SSH tunnel (Step 8), or open YSQL or YCQL to your own network when you choose to (Step 9).
  • TLS everywhere, with a certificate authority of your own. First boot creates a certificate authority and a server certificate unique to your instance. Client connections (YSQL and YCQL) and the traffic between YugabyteDB's own servers are encrypted with it, and unencrypted connections are refused. YSQL accepts only TLS connections with SCRAM-SHA-256 passwords.
  • No call home. YugabyteDB's diagnostics reporting (callhome) is switched off on both servers; the build proves that the database makes no outbound connection.
  • Hardened services. yb-master and yb-tserver run as the unprivileged yugabyte user with no capabilities, a read-only view of the system and no access to /root. They and the first boot service are blocked from the instance metadata service (YSQL can connect to addresses a SQL user names, for example with postgres_fdw or dblink), and the AMI requires IMDSv2. SSH accepts keys only, and fwupd's automatic firmware-metadata refresh is switched off (EC2 has no firmware it can update).
  • Your data on its own disk. The cluster's data, write-ahead logs and server logs (/var/lib/yugabyte) are on a separate 20 GiB EBS volume you can grow or snapshot on its own.
  • Fully patched Ubuntu 24.04 LTS at build time, with unattended security upgrades switched on. YugabyteDB is the vendor's Apache-2.0 release tarball, its checksum verified at build time.

What is on the image: YugabyteDB 2025.2.8.0 in /opt/yugabyte (yb-master, yb-tserver, the ysqlsh and ycqlsh shells, yb-admin, ysql_dump), the helpers yb-ysqlsh, yb-ycqlsh and yb-ysql-dump that sign you in, Ubuntu 24.04 LTS, cloud-init and the AWS Systems Manager agent. The yugabyte database is empty, ready for your tables.

Default user: ubuntu · Architecture: x86_64 · Recommended instance type: m5.large

What this image leaves out, and why

cloudimg removed five parts of the vendor tarball. None is needed to run the database:

Left out Why
YB Controller (share/ybc-*.tar.gz, the YBC backup daemon) It is licensed under the PolyForm Free Trial licence, which does not allow redistribution; the rest of the tarball is Apache-2.0. Backups on this image use yb-admin snapshots and ysql_dump (Step 12), not YBC.
yugabyted and yugabyted-ui The image runs yb-master and yb-tserver directly as systemd services (YugabyteDB's manual deployment model), so the yugabyted launcher and its web UI are not used. yugabyted-ui is built with Go 1.26.6 and govulncheck reports 13 reachable Go standard library advisories in it that are fixed in later Go releases. The master and tablet server consoles (Step 8) remain.
pg_parquet (the YSQL extension) It is built in Rust and cargo-audit reports 22 advisories in the libraries it bundles (among them rustls 0.21, rustls-webpki 0.101, h2, quick-xml and lz4_flex), with no fixed build yet.
redis-cli It is the client from Redis 4.0.1 with hiredis 0.13.3, which have known client-side advisories; YugabyteDB's Redis-compatible API (YEDIS) is off on this image.
python/ai (an example RAG agent) It is not installed or started by anything, and its requirements pin packages with known advisories (fastapi 0.104.1, python-multipart 0.0.6, python-jose 3.3.0).

What this is not

This is a single-node cluster (replication factor 1): it does not replicate data to other machines, so protect it with volume snapshots and backups (Step 12). Growing to a multi-node, fault-tolerant cluster means adding instances, binding the RPC ports to the private network and raising the replication factor; see YugabyteDB's manual deployment documentation. YugabyteDB Anywhere (Yugabyte's commercial cluster manager) is not part of this image.

Prerequisites

  • An AWS account subscribed to the listing, an EC2 key pair and a VPC subnet with a route to the internet (or a private route you use for management).
  • A security group that allows TCP 22 (SSH) from your admin network. YugabyteDB listens on the loopback address only, so no database port needs to be open; you reach it through an SSH tunnel (Step 8).

Step 1: Launch the instance

In the AWS Marketplace listing choose Continue to Subscribe, then Continue to Configuration, pick YugabyteDB 2025.2.8.0 on Ubuntu 24.04 as the software version and your Region, then Launch through EC2. Choose m5.large or larger (YugabyteDB needs at least 8 GiB of memory; give it more for larger working sets), your key pair and a security group as above. The AMI brings two volumes: the root volume and a 20 GiB data volume (/dev/sdf) for /var/lib/yugabyte. Make the data volume as large as your data needs at launch.

With the AWS CLI (replace the values in angle brackets; this example grows the data volume to 100 GiB):

aws ec2 run-instances --region <region> --image-id <ami-id-from-the-listing> \
  --instance-type m5.large --key-name <your-key-pair> \
  --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --block-device-mappings 'DeviceName=/dev/sdf,Ebs={VolumeSize=100,VolumeType=gp3}' \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=yugabytedb}]'

If you make the data volume larger at launch, grow the file system once after first boot with sudo resize2fs "$(findmnt -no SOURCE /var/lib/yugabyte)". First boot takes about a minute once the instance is running.

Step 2: Connect to your instance

Version SSH user
YugabyteDB 2025.2.8.0 on Ubuntu 24.04 ubuntu 
ssh -i <your-key.pem> ubuntu@<public-ip>

Step 3: Check the services

The first boot service, the master and the tablet server should all be active:

systemctl is-active yugabytedb-firstboot.service yb-master.service yb-tserver.service

active
active
active

Every YugabyteDB port listens on the loopback address; from the network, only SSH is reachable:

sudo ss -Htln

LISTEN 0      128        127.0.0.1:12000 0.0.0.0:*
LISTEN 0      4096   127.0.0.53%lo:53    0.0.0.0:*
LISTEN 0      128        127.0.0.1:7000  0.0.0.0:*
LISTEN 0      128        127.0.0.1:7100  0.0.0.0:*
LISTEN 0      4096         0.0.0.0:22    0.0.0.0:*
LISTEN 0      4096      127.0.0.54:53    0.0.0.0:*
LISTEN 0      644        127.0.0.1:5433  0.0.0.0:*
LISTEN 0      128        127.0.0.1:9042  0.0.0.0:*
LISTEN 0      128        127.0.0.1:9000  0.0.0.0:*
LISTEN 0      128        127.0.0.1:9100  0.0.0.0:*
LISTEN 0      128        127.0.0.1:13000 0.0.0.0:*
LISTEN 0      4096            [::]:22       [::]:*

5433 is YSQL, 9042 is YCQL, 7100 and 9100 are the master's and tablet server's RPC ports, 7000 and 9000 their web consoles, and 13000 and 12000 the YSQL and YCQL metrics consoles. The port 53 lines are Ubuntu's local DNS resolver, also loopback only. yb-admin (which connects over TLS with the instance's certificates) shows the master as the cluster's leader:

sudo -u yugabyte /opt/yugabyte/bin/yb-admin --master_addresses 127.0.0.1:7100 --certs_dir_name /etc/yugabyte/tls list_all_masters

Master UUID                         RPC Host/Port           State       Role    Broadcast Host/Port 
31f106e98b66484285455adf751ee3e9    127.0.0.1:7100          ALIVE       LEADER  127.0.0.1:7100

Step 4: Get your connection details

Your connection details are in /root/yugabytedb-credentials.txt:

sudo grep -E '^YUGABYTEDB_(VERSION|YSQL_HOST|YSQL_PORT|YSQL_USER|YSQL_DATABASE|YCQL_PORT|YCQL_USER|TLS_CA)=' /root/yugabytedb-credentials.txt

YUGABYTEDB_VERSION=2025.2.8.0-b60
YUGABYTEDB_YSQL_HOST=127.0.0.1
YUGABYTEDB_YSQL_PORT=5433
YUGABYTEDB_YSQL_USER=yugabyte
YUGABYTEDB_YSQL_DATABASE=yugabyte
YUGABYTEDB_YCQL_PORT=9042
YUGABYTEDB_YCQL_USER=cassandra
YUGABYTEDB_TLS_CA=/etc/yugabyte/tls/ca.crt

Show a password itself when you need it (for a client on your own computer):

sudo grep -E '^YUGABYTEDB_(YSQL|YCQL)_PASSWORD=' /root/yugabytedb-credentials.txt

yugabyte is the YSQL superuser and cassandra the YCQL superuser. YUGABYTEDB_TLS_CA_SHA256 in the same file is the SHA-256 fingerprint of this instance's certificate authority; clients trust the database by its certificate /etc/yugabyte/tls/ca.crt.

Step 5: Use YSQL (PostgreSQL compatible)

yb-ysqlsh runs ysqlsh (YugabyteDB's psql) as yugabyte against 127.0.0.1:5433, verifying the server's certificate, with the password handed over in a temporary root-only file:

sudo yb-ysqlsh -c 'SELECT version();'
sudo yb-ysqlsh -c 'SELECT ssl, version, cipher FROM pg_stat_ssl WHERE pid = pg_backend_pid();'

                                                                                          version
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 PostgreSQL 15.12-YB-2025.2.8.0-b0 on x86_64-pc-linux-gnu, compiled by clang version 19.1.0 (https://github.com/yugabyte/llvm-project.git a2a6b655e14e7fa1fcf1011a6cb29cb8575249c0), 64-bit
(1 row)

 ssl | version |         cipher
-----+---------+------------------------
 t   | TLSv1.3 | TLS_AES_256_GCM_SHA384
(1 row)

Create a table split into three tablets, load rows and run an aggregation with a window function:

sudo yb-ysqlsh -c "CREATE TABLE IF NOT EXISTS orders (id bigint PRIMARY KEY, region text NOT NULL, amount numeric(10,2) NOT NULL) SPLIT INTO 3 TABLETS;"
sudo yb-ysqlsh -c "INSERT INTO orders SELECT g, (ARRAY['EMEA','APAC','AMER'])[1 + g % 3], round((g * 7.31)::numeric % 500, 2) FROM generate_series(1, 3000) AS g ON CONFLICT (id) DO NOTHING;"
sudo yb-ysqlsh -c "SELECT region, count(*) AS orders, sum(amount) AS revenue, rank() OVER (ORDER BY sum(amount) DESC) AS rank FROM orders GROUP BY region ORDER BY rank;"
sudo yb-ysqlsh -c "SELECT num_tablets, num_hash_key_columns FROM yb_table_properties('orders'::regclass);"

CREATE TABLE
INSERT 0 3000
 region | orders |  revenue  | rank
--------+--------+-----------+------
 APAC   |   1000 | 250345.00 |    1
 AMER   |   1000 | 248655.00 |    2
 EMEA   |   1000 | 247465.00 |    3
(3 rows)

 num_tablets | num_hash_key_columns
-------------+----------------------
           3 |                    1
(1 row)

Run sudo yb-ysqlsh with no options for an interactive session (\q quits). For applications, create a dedicated role rather than using yugabyte, for example CREATE ROLE app LOGIN PASSWORD '<password>'; followed by the GRANT statements your application needs.

Step 6: Use YCQL (Cassandra compatible)

yb-ycqlsh runs ycqlsh as cassandra against 127.0.0.1:9042 over verified TLS, with the password handed over in a temporary root-only file:

sudo yb-ycqlsh -e "CREATE KEYSPACE IF NOT EXISTS shop; CREATE TABLE IF NOT EXISTS shop.carts (user_id int, item text, qty int, PRIMARY KEY ((user_id), item)); INSERT INTO shop.carts (user_id, item, qty) VALUES (1, 'keyboard', 1); INSERT INTO shop.carts (user_id, item, qty) VALUES (1, 'mouse', 2);"
sudo yb-ycqlsh -e "SELECT * FROM shop.carts WHERE user_id = 1;"

 user_id | item     | qty
---------+----------+-----
       1 | keyboard |   1
       1 |    mouse |   2

(2 rows)

For applications, create a dedicated role: CREATE ROLE app WITH PASSWORD = '<password>' AND LOGIN = true; and GRANT it the keyspaces it needs.

Step 7: Remove the examples

sudo yb-ysqlsh -c "DROP TABLE IF EXISTS orders;"
sudo yb-ycqlsh -e "DROP TABLE IF EXISTS shop.carts; DROP KEYSPACE IF EXISTS shop;"

DROP TABLE

Step 8: Connect from your own computer through an SSH tunnel

Every port listens on 127.0.0.1. Forward the ones you need over SSH from your computer:

ssh -i <your-key.pem> -N -L 5433:127.0.0.1:5433 -L 9042:127.0.0.1:9042 -L 7000:127.0.0.1:7000 -L 9000:127.0.0.1:9000 ubuntu@<public-ip>

Copy the instance's certificate authority to your computer once (scp -i <your-key.pem> ubuntu@<public-ip>:/etc/yugabyte/tls/ca.crt yugabytedb-ca.crt), then connect with any PostgreSQL client or driver, or with cqlsh/ycqlsh and the Cassandra drivers:

psql "host=127.0.0.1 port=5433 user=yugabyte dbname=yugabyte sslmode=verify-full sslrootcert=yugabytedb-ca.crt"
SSL_CERTFILE=yugabytedb-ca.crt ycqlsh --ssl -u cassandra 127.0.0.1 9042

Enter the passwords from Step 4 when prompted. The certificate names 127.0.0.1, localhost and the instance's private and public addresses, so sslmode=verify-full works through the tunnel.

The web consoles are YugabyteDB's master console at http://127.0.0.1:7000/ (cluster overview, tablet servers, tables and tablets) and the tablet server console at http://127.0.0.1:9000/. The web consoles (ports 7000, 9000, 12000 and 13000) have no login of their own, so anyone with a shell on the instance can read them. That is why they listen on localhost only: open them through the SSH tunnel above, never expose ports 7000, 9000, 12000 or 13000 to a network, and give shell access to the instance only to people you would trust with the database.

The YugabyteDB master console home page on 127.0.0.1:7000: universe overview with replication factor 1, one tablet server, two user tables, the load balancer enabled and balanced, YugabyteDB version 2025.2.8.0 RELEASE, and the single master at 127.0.0.1:7000 as RAFT LEADER (Encryption Status refers to encryption at rest of the DocDB files, which is not configured; EBS volume encryption is chosen at launch)

The Tablet Servers page lists the instance's tablet server 127.0.0.1:9000 as ALIVE, with its tablet peers and leaders:

The master console Tablet Servers page: Universe Summary with 1 live tablet server and 0 dead, the tablet server 127.0.0.1:9000 ALIVE with 4 user and 8 system tablet peers, all leaders, and the cluster load balanced across cloud1, datacenter1, rack1

The Tables page shows each YSQL and YCQL table with its on-disk size, here the orders table from Step 5 (database yugabyte) and the carts table from Step 6 (keyspace shop):

The master console Tables page: user tables orders in the yugabyte database (YSQL) and carts in the shop keyspace (YCQL), both Running, with their WAL and SST sizes, followed by the system tables

Step 9: Optional: open YSQL or YCQL to your own network

If applications in your VPC must connect without SSH, bind the client ports to all interfaces. TLS and password authentication stay enforced: YSQL accepts only TLS connections with SCRAM passwords and refuses plaintext, and YCQL refuses unencrypted connections. Edit /etc/yugabyte/tserver.conf:

sudo sed -i 's#^--pgsql_proxy_bind_address=127.0.0.1:5433$#--pgsql_proxy_bind_address=0.0.0.0:5433#' /etc/yugabyte/tserver.conf
sudo sed -i 's#^--cql_proxy_bind_address=127.0.0.1:9042$#--cql_proxy_bind_address=0.0.0.0:9042#' /etc/yugabyte/tserver.conf
sudo systemctl restart yb-tserver.service

Then allow TCP 5433 (and 9042 for YCQL) in the instance's security group from your own network only (never 0.0.0.0/0):

aws ec2 authorize-security-group-ingress --group-id <your-security-group> \
  --protocol tcp --port 5433 --cidr <your-cidr>

Clients connect to the private (or public) IP with the certificate authority from Step 8, for example psql "host=<private-ip> port=5433 user=yugabyte dbname=yugabyte sslmode=verify-full sslrootcert=yugabytedb-ca.crt". A public IP that is not an Elastic IP changes when the instance is stopped and started, and the certificate names only the addresses the instance had at first boot; use sslmode=verify-ca if you connect by a name the certificate does not carry. Keep the RPC ports (7100, 9100) and the consoles on localhost unless you are building a multi-node cluster. To close access again, put the two lines back to 127.0.0.1, restart yb-tserver and remove the security group rule.

Step 10: Security checks

YugabyteDB and its first boot service cannot reach the instance metadata service:

systemctl show -p IPAddressDeny yb-master.service yb-tserver.service yugabytedb-firstboot.service

IPAddressDeny=169.254.169.254/32 168.63.129.16/32 fd00:ec2::254/128

IPAddressDeny=169.254.169.254/32 168.63.129.16/32 fd00:ec2::254/128

IPAddressDeny=169.254.169.254/32 168.63.129.16/32 fd00:ec2::254/128

The tablet server's effective settings: authentication on for both APIs, TLS between clients and servers and between the servers, unencrypted connections refused, call home off, and the client ports on localhost:

curl -s 'http://127.0.0.1:9000/varz?raw=1' | grep -E '^--(callhome_enabled|ysql_enable_auth|use_cassandra_authentication|use_client_to_server_encryption|use_node_to_node_encryption|allow_insecure_connections|pgsql_proxy_bind_address|cql_proxy_bind_address)='

--allow_insecure_connections=false
--callhome_enabled=false
--cql_proxy_bind_address=127.0.0.1:9042
--pgsql_proxy_bind_address=127.0.0.1:5433
--use_cassandra_authentication=true
--use_client_to_server_encryption=true
--use_node_to_node_encryption=true
--ysql_enable_auth=true

YugabyteDB runs unprivileged:

ps -o user:9=,comm= -u yugabyte | sort | uniq -c
sudo grep -E '^(CapEff|NoNewPrivs)' /proc/$(systemctl show -p MainPID --value yb-tserver.service)/status

      5 yugabyte  postgres
      1 yugabyte  yb-master
      1 yugabyte  yb-tserver
CapEff: 0000000000000000
NoNewPrivs: 1

The image's own round trip: the per-instance passwords work over verified TLS and an analytic query returns exact results, while yugabyte/yugabyte, cassandra/cassandra, the password-less postgres role, blank, common and random passwords and plaintext connections are refused; it also checks that every port is loopback only:

sudo /usr/local/sbin/yugabytedb-roundtrip.sh | tail -1

OK-yugabytedb-roundtrip

Step 11: Change the passwords

For YSQL, \password sends the new password to the server already hashed. Sign in, set it, then update the credentials file so yb-ysqlsh keeps working:

sudo yb-ysqlsh
yugabyte=# \password yugabyte
yugabyte=# \q
sudo sed -i 's/^YUGABYTEDB_YSQL_PASSWORD=.*/YUGABYTEDB_YSQL_PASSWORD=<new-password>/' /root/yugabytedb-credentials.txt

For YCQL, sign in with sudo yb-ycqlsh, run ALTER ROLE cassandra WITH PASSWORD = '<new-password>'; and update YUGABYTEDB_YCQL_PASSWORD the same way.

Step 12: Backup, updates and maintenance

  • Back up with EBS snapshots of the data volume (consistent when you stop yb-tserver and yb-master first), with a logical YSQL dump, or with YugabyteDB's own distributed snapshots. This image does not include the YB Controller backup daemon (see "What this image leaves out"); yb-admin and ysql_dump are the backup tools. A schema and data dump of the yugabyte database to a root only file: sudo yb-ysql-dump > /root/yugabyte-$(date +%F).sql. A distributed snapshot, kept on the data volume:
sudo -u yugabyte /opt/yugabyte/bin/yb-admin --master_addresses 127.0.0.1:7100 --certs_dir_name /etc/yugabyte/tls create_database_snapshot ysql.yugabyte
sudo -u yugabyte /opt/yugabyte/bin/yb-admin --master_addresses 127.0.0.1:7100 --certs_dir_name /etc/yugabyte/tls list_snapshots
  • Memory: YugabyteDB sizes its caches from the instance's memory at start (--use_memory_defaults_optimized_for_ysql); choose a larger instance type for larger working sets and restart both services after resizing.
  • Logs: sudo journalctl -u yb-tserver.service -n 50, and the server logs in /var/lib/yugabyte/logs/master and /var/lib/yugabyte/logs/tserver.
  • Configuration: the servers read their flags from /etc/yugabyte/master.conf and /etc/yugabyte/tserver.conf; restart the service after a change. Keep --callhome_enabled=false, --allow_insecure_connections=false and the authentication flags as they are.
  • Certificates: the certificate authority's key /etc/yugabyte/tls/ca.key stays on the instance (root only) so you can sign certificates for more nodes; the servers use node.127.0.0.1.crt and node.127.0.0.1.key.
  • Updates: Ubuntu security updates install automatically. YugabyteDB is installed from the vendor's tarball in /opt/yugabyte; upgrade it deliberately by following YugabyteDB's manual upgrade procedure after taking a snapshot of the data volume, and keep to the v2025.2 LTS series for long-term support.

Support and licensing

YugabyteDB is open source software under the Apache License 2.0; the build on this image is the vendor's unmodified Apache-2.0 release with the five parts listed above removed (/usr/share/cloudimg/yugabytedb/LICENSE-NOTE.txt). cloudimg provides 24/7 technical support for this image by email and live chat: support@cloudimg.co.uk. YugabyteDB is a trademark of YugabyteDB, Inc.; PostgreSQL and Apache Cassandra are trademarks of their owners; cloudimg is not affiliated with or endorsed by any of them.