Apache IoTDB on AWS User Guide

Overview

This image runs Apache IoTDB, the high-performance, lightweight open source time-series database purpose-built for IoT and industrial sensor data. IoTDB delivers fast columnar storage with high compression, a familiar SQL-like query language, rich aggregation and downsampling, and connectors for the wider data ecosystem. The image is delivered as a ready-to-use appliance: the single-node standalone deployment (one ConfigNode plus one DataNode) is installed and iotdb.service is enabled and starts on boot, so the moment an engineer connects over SSH the database is already accepting writes.

This is a headless time-series database service. There is no web interface. IoTDB is a JVM application, and this image bundles a dedicated Eclipse Temurin JRE 17 so no system Java is required. The DataNode client RPC port (6667, used by the CLI and the native session SDKs) and the internal ConfigNode and DataNode coordination ports are bound to loopback only, so the database engine is never exposed to the network. The IoTDB REST API V2 is enabled on port 18080; the instance security group opens port 22 only, so the REST port is reachable over 127.0.0.1 on the instance but never from the network until you open it yourself.

On the first boot of your instance a one-shot service generates a fresh root password, unique to that instance, and rotates the built-in default away. The password is written to a root-only file. No shared or default credentials ship in the image.

The entire time-series database, every ConfigNode and DataNode data, write-ahead-log, consensus and system directory, lives on a dedicated, independently resizable EBS data volume mounted at /var/lib/iotdb, so your sensor data sits on durable storage rather than the operating system disk.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Apache IoTDB. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.medium or larger; the single-node deployment runs two JVMs (the ConfigNode and the DataNode), so 4 GiB of memory is the practical minimum. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation runs once after the instance state becomes Running and the status checks pass: it waits for the database to come up, generates the per-instance root password and rotates the default, then writes the credentials file. The JVM start plus this rotation takes a minute or two on first boot.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Apache IoTDB Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens port 22 from your management network.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.medium \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=apache-iotdb}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

ssh -i <key-name>.pem ubuntu@<public-ip>

A welcome banner prints the most useful commands. Retrieve the per-instance root password that first boot generated:

sudo cat /root/apache-iotdb-credentials.txt

That file contains the iotdb.root.password value for this instance and ready-to-paste examples for the SQL CLI and the REST API. The commands in the following steps read the password straight from this file, so you can run them as written.

Step 4: Verify the Service

Apache IoTDB runs as a system service that is enabled and started on boot. Confirm the service is active:

systemctl is-active iotdb

That prints active. For the full unit status, including the main process and the two JVMs (ConfigNode and DataNode), use:

systemctl status iotdb --no-pager

The database binds the client RPC port and the REST port; confirm they are listening on the instance:

ss -tlnp | grep -E '6667|18080'

Confirm the bundled JRE that runs the database:

/usr/lib/jvm/temurin-17-jre-amd64/bin/java -version

Step 5: Use the SQL Command-Line Client

IoTDB ships a SQL command-line client under /opt/iotdb/sbin/start-cli.sh. It connects to the DataNode RPC on 127.0.0.1:6667 as user root. The following commands read the per-instance password from the credentials file, create a couple of timeseries, write data points and query them back. First create the schema:

PASS=$(sudo grep '^iotdb.root.password=' /root/apache-iotdb-credentials.txt | cut -d= -f2-)
sudo -u iotdb /opt/iotdb/sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw "$PASS" \
  -e "CREATE TIMESERIES root.factory.line1.temperature WITH DATATYPE=FLOAT,ENCODING=GORILLA;"

Insert a couple of readings, then query them back ordered by time:

PASS=$(sudo grep '^iotdb.root.password=' /root/apache-iotdb-credentials.txt | cut -d= -f2-)
sudo -u iotdb /opt/iotdb/sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw "$PASS" \
  -e "INSERT INTO root.factory.line1(time,temperature) VALUES(now(),73.4);"
sudo -u iotdb /opt/iotdb/sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw "$PASS" \
  -e "SELECT temperature FROM root.factory.line1 ORDER BY time DESC LIMIT 5;"

You can also run the client interactively to explore the database: sudo -u iotdb /opt/iotdb/sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw '<password>', then type SQL statements such as SHOW DATABASES;, SHOW TIMESERIES;, SHOW DEVICES; and aggregation queries like SELECT count(temperature) FROM root.factory.line1;. Type quit; to exit.

Step 6: The REST API

IoTDB also exposes a REST API V2 on port 18080, enabled on this image. The /ping endpoint is an unauthenticated liveness probe that returns HTTP 200 with a success body while the service is up:

curl -s http://127.0.0.1:18080/ping

Data endpoints require HTTP Basic authentication with user root and the per-instance password. The following command reads the password, builds the Basic auth header and runs a query through POST /rest/v2/query:

PASS=$(sudo grep '^iotdb.root.password=' /root/apache-iotdb-credentials.txt | cut -d= -f2-)
curl -s -X POST http://127.0.0.1:18080/rest/v2/query \
  -H "Authorization: Basic $(printf 'root:%s' "$PASS" | base64 -w0)" \
  -H 'Content-Type: application/json' \
  -d '{"sql":"select temperature from root.factory.line1 order by time desc limit 5"}'

The response is a JSON document with the expression names, data types, timestamps and values. To ingest data over REST, post to POST /rest/v2/insertTablet with the same Basic auth header. The REST port binds on the instance but is not reachable from the network because the security group opens port 22 only; to expose it, open the port in the instance security group yourself and front it with your own TLS termination.

Step 7: The Data Volume

The entire time-series database lives on a dedicated EBS volume mounted at /var/lib/iotdb. Every ConfigNode and DataNode data, write-ahead-log, consensus and system directory sits here, off the operating system disk, so you can resize or snapshot the database independently. Confirm the mount with:

df -h /var/lib/iotdb

IoTDB stores sensor data in its purpose-built columnar TsFile format with high compression, so long-retention time series stay compact on disk. To grow the volume, expand the EBS volume in the AWS console, then grow the filesystem on the instance with sudo resize2fs on the underlying device. Snapshot the volume for point-in-time backups of the database.

Step 8: Connect Applications

Point your applications at the instance to write and read time series at scale. The native session SDKs (Java, Python, C++, Go and others) connect to the DataNode RPC on port 6667 and are the highest-throughput path for ingestion; the REST API on 18080 suits lightweight HTTP clients. Both authenticate as root with the per-instance password, and you can create additional users and grant fine-grained privileges with CREATE USER and GRANT from the SQL CLI. Because the RPC and REST ports bind to loopback and the instance respectively and the security group opens only port 22, decide your own exposure: open the relevant port in the security group for trusted clients, or keep access on the instance and tunnel over SSH.

Support

This image is published and supported by cloudimg. Support covers deployment, schema and timeseries modelling, ingestion through the REST API and the session SDKs, IoTDB SQL queries, aggregation and downsampling, retention and storage tuning, user and privilege management, and upgrade planning. Contact cloudimg through the support channel listed on the AWS Marketplace listing.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.