Arc Time-Series Database 26.09.3 on AWS User Guide

Overview

This guide covers launching and using the Arc Time-Series Database 26.09.3 on Ubuntu 24.04 AMI from cloudimg on Amazon EC2. It is one version of the cloudimg Search, OLAP and Time-Series database listing on AWS Marketplace; you pick it as the software version when you subscribe and launch.

Arc, from Basekick Labs, is an open source (AGPL-3.0) time-series and analytical database. It ingests metrics, events and logs over the InfluxDB line protocol and MessagePack, stores them as Apache Parquet files it compacts automatically, and answers standard SQL through an embedded DuckDB engine, all from one Go binary with an HTTP API.

The cloudimg image adds:

• Authentication on, no default token. Arc's own bearer-token authentication is enabled. First boot generates an admin token on your instance (48 hex characters) and writes it to a root-only file; none is baked into the image and no two instances share one. Arc refuses to start without it.
• No token in the logs. Upstream Arc prints a newly created admin token to its log on its very first start. This image seeds the token privately at first boot (Arc's output discarded, loopback only) and then starts Arc normally, so the token never reaches the journal or Arc's logs.
• HTTPS from the first boot. Arc serves its API on port 8000 with TLS only, using a certificate generated on your instance. Plain HTTP is refused. Nothing else listens on the network except SSH.
• DuckDB sandboxed. SQL cannot read files outside Arc's own data directories or fetch from the network (enable_external_access off, no extensions installed at runtime).
• Metadata access blocked for Arc and its first-boot service, and the AMI requires IMDSv2.
• Fails closed. A guard checks the token database, the certificate, the configuration's ownership and modes before every start and refuses to start Arc if anything is missing or loosened.
• Built from source with current security fixes. Arc 26.09.3 is compiled from its signed-off release tag with the latest Go 1.26 toolchain and in-range dependency security updates, and checked with govulncheck (no reachable known vulnerabilities at build time).
• Fully patched Ubuntu 24.04 LTS at build time, with unattended security upgrades switched on.

What is on the image: Arc 26.09.3 (/usr/local/bin/arc, DuckDB 1.5.5 built in), its configuration in /etc/arc, Ubuntu 24.04 LTS, curl, jq, cloud-init and the AWS Systems Manager agent. There is no web interface; you use Arc through its HTTP API and tools such as Telegraf, Grafana and the Arc client libraries.

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

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 8000 (Arc's HTTPS API) from the applications and people that write to or query Arc, and TCP 22 (SSH) from your own networks only. The listing's default security group opens 8000 to everyone; narrow it to your own networks.

Arc is configured for m5.large (2 vCPUs, 8 GiB): DuckDB may use 3 GB of memory and 2 threads. Data is stored as Parquet files on the root volume under /var/lib/arc/data, so give the root volume the space your data needs (you can grow it later, see Step 9).

Step 1: Launch the instance

In the AWS Marketplace listing choose Continue to Subscribe, then Continue to Configuration, pick Arc Time-Series Database 26.09.3 on Ubuntu 24.04 as the software version and your Region, then Launch through EC2. Choose m5.large or larger, your key pair and a security group as above.

With the AWS CLI (replace the values in angle brackets):

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/sda1,Ebs={VolumeSize=100,VolumeType=gp3}' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=arc}]'

You do not need --metadata-options: the AMI already makes IMDSv2 required. The root file system grows to fill the volume on first boot.

Step 2: Connect to your instance

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

Step 3: Check the service

First boot takes under a minute. Then Arc and its first-boot service are active:

systemctl is-active arc arc-tsdb-firstboot

active
active

Arc (8000) and SSH (22) are the only listeners on the network:

sudo ss -tlnH | awk '{print $4}' | sort -u

0.0.0.0:22
0.0.0.0:8000
127.0.0.53%lo:53
127.0.0.54:53
[::]:22

The two port 53 entries are the system DNS resolver.

Step 4: Get your URL and admin token

sudo grep -v '^ARC_ADMIN_TOKEN=' /root/arc-tsdb-credentials.txt

The file holds the URL Arc is served at, the host, the fingerprint of this instance's certificate and, on the line left out above, the admin token:

# Arc Time-Series Database 26.09.3 (cloudimg) on this instance. Every query, write and admin request needs the token:
#   Authorization: Bearer <ARC_ADMIN_TOKEN>
# The token is unique to this instance. Create more (and narrower) tokens with the API, then keep this one safe.
# The certificate is self-signed for this instance: compare its SHA-256 fingerprint with ARC_TLS_SHA256, or pass
# --cacert /etc/arc/tls/arc.crt on this instance.
ARC_URL=https://<public-ip>:8000
ARC_HOST=<public-ip>
ARC_TLS_SHA256=<sha256-fingerprint>
GUIDE=https://www.cloudimg.co.uk/guides/arc-time-series-database-26-09-3-on-ubuntu-24-04-aws/

Read the token with sudo cat /root/arc-tsdb-credentials.txt and keep it in your secrets manager. The URL and a reminder are printed when you log in over SSH.

Step 5: Write data and query it with SQL

Arc takes the InfluxDB line protocol on /api/v1/write/line-protocol (the database is named in the x-arc-database header) and SQL on /api/v1/query. Measurements are tables named <database>.<measurement>. In this example the token is written into a header file readable only by you, so it never appears on a command line. The certificate directory is readable only by root and Arc, so the first line copies the (public) certificate to your home directory for curl to trust:

sudo cat /etc/arc/tls/arc.crt > ~/arc.crt
HDR="$(mktemp)"; chmod 600 "$HDR"
sudo sed -n 's/^ARC_ADMIN_TOKEN=\(.*\)$/Authorization: Bearer \1/p' /root/arc-tsdb-credentials.txt > "$HDR"
arc() { curl -s --cacert ~/arc.crt -H "@$HDR" "$@"; }
NOW="$(date +%s)"
printf 'cpu,host=web1 usage=12.5 %s000000000\ncpu,host=web1 usage=17.5 %s000000000\ncpu,host=web2 usage=40 %s000000000\n' \
  "$((NOW - 120))" "$((NOW - 60))" "$NOW" |
  arc -o /dev/null -w '%{http_code}\n' -H 'x-arc-database: demo' --data-binary @- https://localhost:8000/api/v1/write/line-protocol
arc -o /dev/null -w '%{http_code}\n' -X POST https://localhost:8000/api/v1/write/line-protocol/flush
arc -H 'Content-Type: application/json' -d '{"sql":"SELECT host, count(*) AS points, avg(usage) AS avg_usage FROM demo.cpu GROUP BY host ORDER BY host"}' \
  https://localhost:8000/api/v1/query | jq -c '.data'
rm -f "$HDR"

204
200
[["web1",2,15],["web2",1,40]]

Arc buffers writes for up to a second before it writes Parquet; the flush call (admin only) writes them at once. The files are under /var/lib/arc/data/demo/cpu/, readable by any tool that reads Parquet.

From another machine, use https://<ARC_HOST>:8000 with the header Authorization: Bearer <token>, and copy ~/arc.crt from the instance to trust the certificate (--cacert for curl), or install your own certificate (Step 8). Telegraf's InfluxDB output, Grafana's Arc data source and the Arc client libraries all take the URL and a token.

Step 6: Check the security controls

Only /health, /ready, /ready/write, /api/v1/auth/verify and Arc's aggregate /metrics counters answer without a token. Everything else, including SQL and writes, is refused without a valid token (401), and plain HTTP gets no answer at all:

for t in "" "Authorization: Bearer 0000000000000000000000000000000000000000000000000"; do
  curl -s -o /dev/null -w '%{http_code}\n' --cacert ~/arc.crt ${t:+-H "$t"} \
    -H 'Content-Type: application/json' -d '{"sql":"SELECT 1"}' https://localhost:8000/api/v1/query
done
curl -s --cacert ~/arc.crt https://localhost:8000/health | jq -r .status
curl -s -o /dev/null http://127.0.0.1:8000/health || echo "plain HTTP refused (curl exit $?)"

401
401
ok
plain HTTP refused (curl exit 52)

Arc and first boot cannot reach the instance metadata service:

for u in arc arc-tsdb-firstboot; do
  printf '%s: ' "$u"; systemctl show -p IPAddressDeny --value "$u" | tr ' ' '\n' | grep -E '^169\.254\.' | paste -sd' '
done

arc: 169.254.169.254/32
arc-tsdb-firstboot: 169.254.169.254/32

The full self test the image build runs is available too:

sudo arc-selftest

ARC_SELFTEST_OK

Step 7: Tokens for your applications

Keep the admin token for administration and give each application its own token with only the permissions it needs. Tokens are managed with Arc's API (/api/v1/auth/tokens, admin token required), for example a write-only token for Telegraf:

curl -s --cacert ~/arc.crt -H "@$HDR" -H 'Content-Type: application/json' \
  -d '{"name":"telegraf","permissions":["write"]}' https://localhost:8000/api/v1/auth/tokens

The response shows the new token once; store it in your secrets manager. Arc stores only a hash of each token. To replace the admin token, create a new admin token, update ARC_ADMIN_TOKEN in /root/arc-tsdb-credentials.txt, then delete the old token through the same API.

Step 8: Your own DNS name and certificate

The certificate generated on first boot names the instance's addresses, localhost and its public DNS name. To use a certificate from your own CA or from Let's Encrypt, replace /etc/arc/tls/arc.crt and /etc/arc/tls/arc.key (owner root, group arc, key mode 0640, directory mode 0750) and restart Arc:

sudo systemctl restart arc

Clients then trust it without --cacert.

Step 9: Storage, retention and backups

• Disk space: Parquet files live on the root volume under /var/lib/arc/data. Grow the EBS volume in the EC2 console; the file system can be extended online (sudo growpart /dev/nvme0n1 1 && sudo resize2fs /dev/nvme0n1p1).
• Retention: Arc deletes old data per database with retention policies (/api/v1/retention); compaction merges small Parquet files hourly and daily.
• Backups: Arc's backup API (/api/v1/backup) writes to /var/lib/arc/backups; copy those to Amazon S3, or take EBS snapshots of the volume.
• Amazon S3 storage: Arc can keep Parquet in S3 ([storage] backend = "s3" in /etc/arc/arc.toml). Instance metadata is blocked for Arc, so it cannot use the instance role: give it an access key for an IAM user limited to that bucket in the configuration, then restart Arc.

Step 10: Server components

Logs: sudo journalctl -u arc.

Step 11: Security recommendations

• Allow port 22 in the security group from your own networks only, and open 8000 only to the applications and people that need Arc.
• Give each application its own token with the narrowest permissions, and keep the admin token for administration.
• Use your own DNS name and a certificate your clients trust (Step 8).
• Keep the operating system patched; unattended security upgrades are on, and sudo apt-get update && sudo apt-get upgrade applies everything else.

Support and licensing

Arc 26.09.3 is open source software under the GNU Affero General Public License v3.0 from https://github.com/Basekick-Labs/arc. Its LICENSE, the list of the Go modules compiled into it and the notices of DuckDB and the other components it includes are in /usr/share/doc/arc/. The binary is built from the unmodified 26.09.3 source with the dependency updates recorded there. The image's price covers the cloudimg packaging, hardening and per-instance setup described above; there is no Arc licence fee.

• Email: support@cloudimg.co.uk
• Website: https://www.cloudimg.co.uk
• Support: 24/7, with a 24 hour response SLA

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.