Apache IoTDB on Ubuntu 24.04 on Azure User Guide

Overview

Apache IoTDB (Internet of Things Database) is a high-performance time-series database purpose-built for IoT and IIoT workloads - devices, sensors and industrial telemetry collected at massive scale - with a SQL-like query language. The cloudimg image installs Apache IoTDB 2.0.8 (the official apache-iotdb-2.0.8-all-bin distribution) on a Temurin 17 JRE, runs it in standalone mode as a dedicated iotdb system user, stores all data directories on a dedicated Azure data disk, and rotates a unique root password into the image on first boot. Backed by 24/7 cloudimg support.

What is included:

• Apache IoTDB 2.0.8 in standalone mode (one ConfigNode + one DataNode)
• A Temurin 17 JRE (the runtime IoTDB 2.x requires)
• A unique per-VM root password generated on first boot (the default root/root is never shipped)
• All data directories (data, WAL, system, consensus) on a dedicated 30 GiB Azure data disk at /var/lib/iotdb
• Loopback-only native client/SQL port 6667 with password authentication (not exposed publicly)
• A REST service on 127.0.0.1:18080 with a /ping health endpoint
• 24/7 cloudimg support

This is a database product: IoTDB's native client/SQL port 6667 listens on 127.0.0.1 only and is not opened to the internet. Connect locally on the VM, over an SSH tunnel, or open 6667 on your own Network Security Group after re-binding (see Step 9).

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet + subnet in the target region. Standard_B2ms (2 vCPU / 8 GiB RAM) is a good starting point. NSG inbound: allow 22/tcp from your management network. No inbound application ports are needed by default because IoTDB is reached locally or over the SSH tunnel.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Apache IoTDB by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) only. Then Review + create -> Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name iotdb \
  --image <marketplace-image-urn> \
  --size Standard_B2ms \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm Apache IoTDB is installed and running

systemctl is-active iotdb.service iotdb-firstboot.service
ss -tln | grep -E ':6667 |:18080 '

You should see both services active and the native client port 6667 bound to loopback alongside the REST port 18080:

active
active
LISTEN 0      50     [::ffff:127.0.0.1]:6667             *:*
LISTEN 0      50                      *:18080            *:*

Step 5 - Retrieve your per-VM root password

Each VM generates its own unique IoTDB root password on first boot and writes it to a root-only credentials file (the default root/root is never shipped):

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

The file contains iotdb.root.password, the CLI connection string, the REST health-check command and the port-6667 instructions. Store the password in your secrets manager. In the commands below, <IOTDB_ROOT_PASSWORD> stands for the value of iotdb.root.password.

Step 6 - Connect with the IoTDB SQL CLI

The IoTDB CLI authenticates with the root user and the per-VM password. Run a non-interactive query with -e, or omit -e to drop into the interactive IoTDB> shell:

/opt/iotdb/sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw <IOTDB_ROOT_PASSWORD> -e 'SHOW DATABASES'

A wrong password is rejected, so the database is never open without the credential.

Step 7 - Create a time-series and insert data

IoTDB models data as a tree of root.<database>.<device>.<measurement> time-series. Create a database, create a typed time-series, insert a few timestamped points and read them back:

/opt/iotdb/sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw <IOTDB_ROOT_PASSWORD> -e "
CREATE DATABASE root.factory;
CREATE TIMESERIES root.factory.line1.temperature WITH DATATYPE=FLOAT,ENCODING=RLE;
INSERT INTO root.factory.line1(timestamp,temperature) VALUES(1,21.7);
INSERT INTO root.factory.line1(timestamp,temperature) VALUES(2,22.4);
INSERT INTO root.factory.line1(timestamp,temperature) VALUES(3,23.9);
SELECT temperature FROM root.factory.line1;
SELECT avg(temperature) FROM root.factory.line1;
"

The SELECT returns the three points keyed by timestamp, and the aggregate query returns their average - proving the time-series database works end to end.

Step 8 - Use the REST API and confirm persistence

IoTDB also exposes a REST service on 127.0.0.1:18080. The /ping endpoint is a Basic-auth health check, and /rest/v2/query runs SQL over HTTP:

curl -u root:<IOTDB_ROOT_PASSWORD> http://127.0.0.1:18080/ping
curl -u root:<IOTDB_ROOT_PASSWORD> -H 'Content-Type: application/json' \
  -X POST http://127.0.0.1:18080/rest/v2/query \
  -d '{"sql":"SHOW DATABASES"}'

All IoTDB data, WAL and system directories live on the dedicated Azure data disk, so the time-series persist across reboots and the volume is independently resizable:

findmnt /var/lib/iotdb

Step 9 - Remote access and opening port 6667

By default the native client/SQL port 6667 binds to 127.0.0.1 only and is not reachable from outside the VM. You have two options for remote access:

Option A - SSH tunnel (no NSG change): from your workstation, forward the port and run the CLI against 127.0.0.1:

ssh -L 6667:127.0.0.1:6667 azureuser@<vm-public-ip>

Option B - bind publicly and open the NSG: set dn_rpc_address=0.0.0.0 in /opt/iotdb/conf/iotdb-system.properties, restart IoTDB, and add an inbound rule for TCP 6667 on this VM's Network Security Group, restricted to your trusted networks:

az network nsg rule create \
  --resource-group <your-rg> --nsg-name <your-nsg> \
  --name allow-iotdb-6667 --priority 1100 \
  --access Allow --protocol Tcp --direction Inbound \
  --destination-port-ranges 6667 --source-address-prefixes <your-cidr>

Do not expose 6667 to the public internet without network controls. Always keep the per-VM root password and consider TLS termination in front of IoTDB for production.

Support

This image is maintained by cloudimg with 24/7 support. Apache, Apache IoTDB and the Apache IoTDB logo are trademarks of the Apache Software Foundation. For deployment help or questions, contact support@cloudimg.co.uk.