CLI Command Reference

The appliance CLI is the native ct binary at /usr/local/bin/ct. Use it for appliance operations and for managing the companion CLI tools pack.

sudo ct <command> [options]

Native CLI availability

Use ct for all documented appliance operations. The companion tools pack is managed through ct cli ...; if ct cli is unavailable, run ct version and confirm that the appliance release includes the tools bridge before troubleshooting it.

Quick Reference

Command	Description
update [version] [options]	Upgrade to specified version (default: latest)
rollback	Restore the previous compose configuration (not database data)
doctor	Active appliance preflight health and sanity diagnostics
`telemetry [status	enable
logs [service]	Stream or tail appliance service container logs (-f, --tail)
backup test <url>	Test remote SFTP/FTP backup destination connectivity and permissions
appliance export [path]	Full appliance archive export (.cta) with encrypted secrets vault
appliance import <archive>	Full disaster recovery restore from archive (.cta) with TimescaleDB hooks
appliance inspect <archive>	Inspect archive metadata, row estimates, and secrets keys
backup run / export	Create database backup or full appliance archive
backup schedule	Manage automated recurring backup schedule (.cta) with systemd timers
cucm check-ports <ip>	Verify TCP/UDP reachability for essential CUCM ports (8443, 2748, 6970, 514)
license status	Inspect organization license tier, active phone quota, and expiration
db active-queries	Display real-time running non-idle PostgreSQL queries
db backup	Create a database backup
db restore [file]	Restore from a database backup
db maintenance vacuum <tbl> [--full]	Vacuum one table (--full reclaims disk; locks the table)
db maintenance compact	Docker cleanup + whole-database VACUUM FULL (locks every table)
db data purge <tbl|group> <days> [--yes]	Purge old rows from a table or retention group
db data purge truncate-debug --yes	TRUNCATE all debug/mirror/webhook log tables (unbounded)
db inspect size / db inspect tables	Read-only size and table-size inspection
migrate status	Check migration progress
migrate run	Execute pending migrations
docker prune	Remove unused Docker resources
certs <command>	Manage enterprise SSL/TLS certs, CSRs, CA trust store, or reset
reset	Factory reset (deletes all data)
users list	List users with IDs, emails, roles, and last-login times
users reset-password <email> <new-password>	Reset an administrator password without sending email
selfupdate	Update the native CLI itself
completion [shell]	Generate shell tab completion script (bash, zsh, fish)
syslog port [port]	Show or change the external UDP/TCP syslog receiver port
postgres profile [small|medium|large|show]	Set the DB connection/pool sizing tier, or show detected host RAM/vCPUs and the applied/recommended profile (see PostgreSQL Connection Profile)
postgres upgrade <version> [--dry-run]	Major PostgreSQL version upgrade with preflight validation, automated volume backup, and crash recovery (see PostgreSQL Major Version Upgrade)
postgres rollback [--yes]	Roll back PostgreSQL major version to previous isolated volume (see PostgreSQL Rollback Plan)
offline <command>	On-appliance air-gapped apply/list (see Offline / Air-Gapped Bundles)

Native CLI tools bridge

The Go CLI can install and run a companion TypeScript tools pack without changing which binary owns the ct command. The bridge is implemented but remains an opt-in companion surface: the Go CLI stays on PATH and remains the customer default.

Check the tools pack

Use status before changing anything. A missing tools pack is reported as not installed and the status command returns successfully so it can be used in diagnostic scripts. A present binary with a probe mismatch returns exit code 1.

sudo ct cli status

The output includes the managed path, last update time, engine, probe token, and tools version. The normal managed layout is:

/usr/local/bin/ct                 # Go customer CLI
<install>/.ct/tools/ct-ts         # companion tools binary
<install>/.ct/tools/state.json    # last successful install
<install>/.ct/tools-pin.json      # optional pinned tools version

For a new appliance, the expected diagnostic output is:

cli-tools path:  <install>/.ct/tools/ct-ts
cli-tools:       not installed
Install with:    ct cli update

After a successful install, status includes the engine, probe, and version:

cli-tools path:  <install>/.ct/tools/ct-ts
cli-tools last:  <UTC timestamp>
cli-tools engine: typescript
cli-tools probe:  calltelemetry-ts-cli-v1
cli-tools version:<installed-version>

Install or refresh the tools pack

# Install or refresh the companion tools
sudo ct cli update

# Preview the target without downloading or changing files
sudo ct cli update --check

# Install a specific companion version
sudo ct cli update --version 0.12.20

# Install and persist a version pin for later updates
sudo ct cli update --version 0.12.20 --pin

# Ignore an existing pin and use the floating latest version
sudo ct cli update --latest

--check and --dry-run are equivalent. --latest and --version are mutually exclusive. An explicit ct cli update fails if the installer, checksum, or post-install probe fails; do not treat a failed probe as a usable tools installation.

Run companion commands

Use run for a one-shot command and preserve the command's exit code:

sudo ct cli run -- network status
sudo ct cli run -- version

The command after -- is required. Use the interactive shell when the installed tools build provides it:

sudo ct cli shell

If the shell is unavailable or behaves differently on an older tools build, use ct cli run -- <command> [args...] instead.

Tools refresh during ct update

An appliance update runs the Go self-update first, then refreshes the companion tools pack. In production and UAT, a tools install, checksum, or probe failure hard-fails the overall update so the appliance does not continue with a broken CLI toolchain.

The following are lab/test escape hatches only:

Variable	Effect
CT_CLI_TOOLS_REQUIRE=0	Continue with a warning when the tools refresh fails
CT_CLI_TOOLS_REQUIRE=1	Explicitly require a successful tools refresh
CT_SKIP_CLI_TOOLS_UPDATE=1	Skip the tools refresh entirely
CT_CLI_TOOLS_PATH	Override the managed companion binary path
CT_TS_CLI_BASE_URL	Override the dual-publish tools feed
CT_INSTALL_CT_PATH	Use a local install-ct.sh during refresh

Do not use the warn-only or skip variables on a customer production appliance unless Call Telemetry support explicitly directs it. Do not manually edit a .ct/tools-require marker; the current CLI defaults to hard-fail and treats that marker as informational.

Troubleshooting the tools bridge

Symptom	Recovery
ct: command not found	Repair or reinstall the native appliance CLI through the appliance installer. Then run ct version and ct cli status.
ct cli status reports not installed	Run sudo ct cli update, then repeat sudo ct cli status. A missing tools pack is not itself a status failure.
ct cli update cannot download the tools	Check outbound HTTPS and the release feed configured for the appliance, then retry sudo ct cli update.
Checksum, installer, or post-install probe fails	Stop and do not run the tools binary. Verify the release/architecture feed and retry sudo ct cli update; include the exact error in the support ticket. Do not bypass checksum or probe validation.
Permission or path mismatch	Run with the same sudo boundary used for the appliance install. Confirm the resolved install directory and CT_CLI_INSTALL_DIR; use CT_CLI_TOOLS_PATH only in a lab or when support directs it.
ct cli shell is unavailable	Some shipped tools builds do not include the full interactive shell. Use sudo ct cli run -- <command> [args...], for example sudo ct cli run -- network status.
ct update stops after a tools error	This is the production/UAT hard-fail guard. Fix the installer/feed/probe issue, run sudo ct cli update, and retry the appliance update. Do not claim the appliance update completed.

If a status probe is present but does not match the expected native probe token, leave the tools pack disabled and contact support. A probe mismatch indicates a wrong or incompatible binary, not a cosmetic warning.

Collect support evidence

Include the following output when opening a CLI support request:

sudo ct version
sudo ct cli status

Also include the exact command that failed, its exit code, the appliance release, CPU architecture, and whether the failure occurred during ct update or an explicit ct cli update. Redact passwords, access tokens, private keys, and credentials embedded in URLs before sharing logs or terminal output.

Upgrade & Rollback

Update to Latest Version

sudo ct update

Update to Specific Version

sudo ct update 0.8.4-rc172

Update Options

Option	Description
--ignore-os-check	Continue past only the operating-system compatibility failure. This is a temporary upgrade workaround, not a long-term fix.
--force-upgrade	Skip validation checks (RAM, disk, Docker version)
--no-cleanup	Keep old images for troubleshooting

Examples:

# Temporarily continue an upgrade after an OS compatibility failure
sudo ct update 0.8.6.26 --ignore-os-check

# Force upgrade bypassing checks
sudo ct update --force-upgrade

# Upgrade without cleanup
sudo ct update --no-cleanup

# Combine options
sudo ct update 0.8.4 --no-cleanup

System Requirements

The update command validates these requirements before proceeding:

• Operating system: AlmaLinux or RHEL
• RAM: Minimum 7GB (8GB for v0.8.4+)
• Disk: Minimum 10% free space
• Docker: Version 26 or higher

Unsupported operating systems

If the preflight reports an unsupported operating system, use --ignore-os-check only as a temporary workaround for the current upgrade. The OS check still runs and its original failure remains visible; every other preflight check still gates the upgrade. Plan to migrate the appliance to AlmaLinux or RHEL for long-term supported upgrades. See Migrating from CentOS Stream to AlmaLinux.

You can also apply the narrow workaround while running the standalone preflight:

sudo ct update preflight 0.8.6.26 --ignore-os-check

Rollback

Restore the previous docker-compose configuration from the most recent pre-upgrade snapshot. This changes the application configuration only; restore database contents separately with ct db restore.

sudo ct rollback

Snapshots are automatically created before each upgrade in /home/calltelemetry/backups/.

Update the native CLI

The native CLI can be updated independently:

sudo ct selfupdate

User Management

Reset an Administrator Password

From the Call Telemetry installation directory, list the users to locate the account and confirm its exact email address:

sudo ct users list

The table includes each user's ID, email, primary role, complete role list, and last login.

Reset the selected account by email address:

sudo ct users reset-password 'admin@example.com' 'new-password'

The command requires exactly one email address and one new password, changes the password immediately, and does not send an email. Quote passwords that contain spaces or shell characters.

Syslog Receiver

Syslog remains an optional profile. Changing its port does not enable the receiver. The appliance defaults to external UDP and TCP port 514; use a different port, such as 5514, when the network or an existing service requires it.

# Show the configured receiver port
sudo ct syslog port

# Set the external UDP and TCP receiver port
sudo ct syslog port 5514

The setting is saved in the appliance .env as SYSLOG_PORT. If syslog is already enabled, the command recreates only ct-syslog-ingest so the new mapping applies immediately. The service continues to listen on port 514 inside Docker.

Enable the optional profile separately when needed:

sudo ct syslog enable

The interactive TUI exposes the same setting under Tools → Syslog.

Database Operations

The ct db surface is organized into three semantic groups. Every legacy command (ct db backup, ct db compact, …) keeps working unchanged as a flat alias; the grouped form is preferred and carries risk hints in ct help.

Database Maintenance (service-changing)

# Vacuum a single table (plain: safe, online)
sudo ct db maintenance vacuum cube_event_logs

# Vacuum with disk reclaim — locks the table for the duration
sudo ct db maintenance vacuum cube_event_logs --full

# Refresh planner statistics
sudo ct db maintenance analyze

# Docker cleanup + whole-database VACUUM FULL
sudo ct db maintenance compact

VACUUM FULL locks

vacuum --full takes an exclusive lock on the target table and prompts for confirmation on a terminal. compact runs VACUUM FULL on every table and takes an exclusive lock on the whole database — run it in a maintenance window. Both print per-table row counts and support CT_DB_VACUUM_LOCK_TIMEOUT / CT_DB_COMPACT_LOCK_TIMEOUT lock budgets.

Database Data (backups and retention)

# Backup / restore
sudo ct db data backup
sudo ct db data restore /home/calltelemetry/backups/<file>.sql

# Timestamp purge (batched DELETE; supports retention groups)
sudo ct db data purge cdr_records 90 --yes

# List optimized and truncate groups
sudo ct db data purge-groups

Database Inspection (read-only)

sudo ct db inspect size        # database size
sudo ct db inspect tables      # per-table row counts and disk usage
sudo ct db inspect list        # available backups
sudo ct db inspect report      # comprehensive storage + database report

Backup

Create a timestamped SQL dump of the database:

sudo ct db backup

Automatic Backup Retention

Only the 5 most recent backups are retained. Download critical backups before they are automatically purged.

Backups are stored in /home/calltelemetry/backups/ with format: calltelemetry_prod_YYYYMMDD_HHMMSS.sql.

Restore

Restore database from a backup file:

sudo ct db restore /home/calltelemetry/backups/calltelemetry_prod_20250119_143022.sql

Flat aliases

Every command above also accepts the legacy flat form — sudo ct db backup, sudo ct db restore, sudo ct db compact, sudo ct db vacuum <tbl>, sudo ct db purge <tbl|group> <days>, sudo ct db size, sudo ct db tables — with identical behavior. The grouped forms add semantic clarity and risk hints; run sudo ct db or sudo ct help to see the full grouped layout.

Migration Status

Monitor migration progress:

# Check current status
sudo ct migrate status

# Watch continuously
sudo ct migrate watch

ct migrate watch continues polling until interrupted. Press Ctrl+C to stop watching without changing migration state.

SQL Migration Status

View last 10 applied migrations directly from database:

sudo ct migrate history

Run Migrations

Execute all pending migrations:

sudo ct migrate run

Rollback Migrations

Rollback a specified number of migrations:

# Rollback last migration
sudo ct migrate rollback 1

# Rollback last 3 migrations
sudo ct migrate rollback 3

Long-Running Migrations & Live SQL Watch

Database migrations during version upgrades run with unlimited query and session timeouts (idle_in_transaction_session_timeout = 0) to prevent operations from aborting prematurely on large tables or index rebuilds.

If migrations take 3 minutes or longer during ct update or manual migration runs, the CLI automatically engages an active SQL monitor:

• Active SQL Activity: Displays queries currently executing in PostgreSQL, with query parameters automatically masked for privacy.
• Container CPU %: Shows real-time CPU utilization of the database container to verify that migrations are actively making progress.

PostgreSQL Connection Profile

ct postgres profile sets a t-shirt-sized connection and pool sizing tier — PG_MAX_CONNECTIONS and the per-repo DB_*_POOL_SIZE env keys. It does not choose memory settings. Show the current tier, detected host sizing, and a recommendation:

sudo ct postgres profile show

show prints detected host RAM and vCPU count, the currently applied profile, a recommended profile based on that RAM, the current connection/pool values, and — if the applied profile no longer matches the detected host RAM — a warning naming the exact command to fix it.

Apply a tier:

sudo ct postgres profile small   # ~8GB hosts
sudo ct postgres profile medium  # ~12GB hosts
sudo ct postgres profile large   # ~16GB hosts

Applying a profile restarts the db container to pick up the new values.

Profile name vs. memory settings

The profile name selects connection/pool sizing only. PostgreSQL memory settings (shared_buffers, work_mem, and the DB container's memory limit) are derived from detected host RAM alone, independent of which profile name is applied — there is no per-profile memory table. Every ct postgres profile <tier> run re-derives those memory settings from the host RAM present at that moment, alongside the connection/pool values for the chosen tier.

ct postgres profile manages the main, migration, call-control, background, discovery, Oban, CDR-ingest, and SFTPD connection pools. The backend also defines several lower-traffic pools that this command does not touch and that keep their independent fixed defaults regardless of applied profile: analytical-rollup (DB_ANALYTICAL_ROLLUP_POOL_SIZE, default 2), CUBE telemetry (DB_CUBE_TELEMETRY_POOL_SIZE, default 2), maintenance DDL (DB_MAINTENANCE_DDL_POOL_SIZE, default 2), reporting (DB_REPORTING_POOL_SIZE, default 2), auth (DB_AUTH_POOL_SIZE, default 2), post-call (DB_POST_CALL_POOL_SIZE, default 2), and XCC rollup (DB_XCC_ROLLUP_POOL_SIZE, default 2). Set any of these directly in .env if a specific workload needs a larger pool.

Resizing after a RAM increase

ct update, ct restart, and offline apply establish memory settings on an appliance that has never been tuned. On one that already has them, those commands deliberately do not change memory as a side effect of a version bump — instead, if the tuned memory no longer matches detected host RAM, they print an advisory naming the exact ct postgres profile <tier> command to run. Applying a profile is the explicit, auditable step that re-derives memory. To resize a running appliance after adding RAM in the hypervisor:

1. Grow the VM's RAM allocation (and reboot the guest OS if the hypervisor requires it for the new RAM to be visible to the appliance).
2. Run sudo ct postgres profile <tier> for the tier that matches the new RAM total — for example sudo ct postgres profile medium after growing an 8GB appliance to 12GB.
3. The command re-derives shared_buffers/work_mem/the DB memory limit from the newly detected RAM, applies the tier's connection/pool sizing, and restarts the db container.

Confirm the result with sudo ct postgres profile show — the detected RAM, applied profile, and recommendation should now agree, with no warning.

PostgreSQL Major Version Upgrade

The ct postgres upgrade command automates major PostgreSQL version upgrades (e.g. PostgreSQL 14 → 15) natively without requiring any manual file editing or docker commands.

Also available via aliases ct appliance upgrade-postgres <version> and ct db upgrade <version>.

Phase 1: Preflight Sizing & Extension Validation

Always run with --dry-run first to verify compatibility while services continue running:

# Verify target image, installed TimescaleDB extensions, and disk headroom without stopping services
sudo ct postgres upgrade 15 --dry-run

The preflight check:

1. Verifies that the target image is officially supported and reachable (14, 15, 16, 17, 18).
2. Checks that the host filesystem has sufficient free disk headroom (≥ 2.5x database size).
3. Connects to the database and verifies TimescaleDB extension catalog status.

Phase 2: Fully Automated Execution

When preflight checks pass, execute the upgrade:

# Automated upgrade (creates backup, isolates old volume, applies override, boots PG 15, restores data)
sudo ct postgres upgrade 15

# Accelerated upgrade skipping voluminous diagnostic/debug logs
sudo ct postgres upgrade 15 --skip-logs --yes

Flag	Description
--dry-run	Validates target image, installed TimescaleDB extensions, and disk headroom without taking down services
--skip-logs, --no-logs	Excludes debug event tables and user activity logs from the upgrade backup to accelerate completion
--yes, -y	Confirms execution without interactive countdown prompt

The automated execution pipeline:

1. Downloads the official version override (e.g. postgres-15.yaml) into docker-compose.override.yml, saving the previous override to postgres-override.v<oldVer>-<ts>.bak.
2. Creates a pre-upgrade compressed backup into /var/backups/.
3. Quiesces active services (docker compose down).
4. Isolates the previous data volume into postgres-data.v<oldVer>-<ts>.bak.
5. Starts the new PostgreSQL engine and executes timescaledb_pre_restore().
6. Restores the database with multi-core parallelism and re-enables background workers (timescaledb_post_restore()).
7. Resumes all services and verifies pg_isready health.

PostgreSQL Rollback Plan

If any unexpected application behavior occurs after upgrading, CallTelemetry provides an automated, zero-touch rollback command:

# Interactive rollback (discovers latest volume backup and prompts for confirmation)
sudo ct postgres rollback

# Non-interactive rollback (for automation or instant recovery)
sudo ct postgres rollback --yes

Also available via aliases ct appliance rollback-postgres and ct db rollback.

The rollback engine:

1. Automatically discovers the newest preserved backup volume (postgres-data.v<oldVer>-<ts>.bak).
2. Quiesces all running services (docker compose down).
3. Preserves the aborted volume to postgres-data.v<curVer>-aborted-<ts>.bak so no data is destroyed.
4. Swaps the previous data volume back into postgres-data.
5. Reverts docker-compose.override.yml byte-for-byte from postgres-override.v<oldVer>-<ts>.bak.
6. Restarts all services (docker compose up -d) and verifies database connectivity.

Cross-Server Migrations

For moving to a new virtual machine or deploying a fresh OVA, use the Appliance Archive Workflow (ct appliance export → ct appliance import). See Appliance Backup & Disaster Recovery.

Appliance Archives & Disaster Recovery (ct appliance & ct backup)

CallTelemetry Appliance Archives (.cta) provide complete, self-contained disaster recovery bundles. While standard database dumps (ct db backup) only capture SQL tables, an appliance archive captures everything needed to reconstruct an appliance on a fresh host or migrate between virtual machines:

1. Full Database Dump (calltelemetry_prod.dump): Custom binary format export covering all PostgreSQL relational schemas, tables, and TimescaleDB hypertables.
2. Encrypted Secrets Vault (secrets.env.enc): Protects CLOAK_KEY, database passwords, web session credentials, and integration secrets using PBKDF2-SHA256 (64,000 iterations, 16-byte cryptographically secure salt) and AES-256-GCM authenticated encryption.
3. Appliance Manifest (manifest.json): Source version, git commit, table catalog estimates, and SHA-256 integrity checksums for every component.
4. Media Store (media.tar.gz): Optional audio prompts, announcements, greetings, and custom ringtones.

Environment file parity

Appliance operations automatically maintain parity between the primary Docker Compose environment file (/home/calltelemetry/.env) and /etc/calltelemetry/.env. Decrypted secrets are safely synchronized across both locations during restoration.

Non-Blocking Row Estimation (Zero Table Locks)

To prevent locking or degrading performance on high-throughput production appliances (such as systems with 80M+ CDR rows), ct appliance export and ct appliance inspect query PostgreSQL's internal catalog statistics (pg_class.reltuples and pg_total_relation_size).

• Instantaneous metadata: Catalog statistics return in ~10ms with zero row scanning.
• No COUNT(*) locking: Never issues sequential table scans or read locks on active production tables.

Table Progress & Diagnostic Session Logging

Both export and import operations provide real-time table-by-table progress reporting and comprehensive session diagnostic logging:

• Multi-step progress bars: Structured series tracking each operational phase (pre-restore catalog preparation, schema extraction, table data streaming, TimescaleDB worker restart).
• Session log file: Every operation writes raw tool output to /var/calltelemetry/db_dumps/appliance-export-<timestamp>.log or /var/calltelemetry/db_dumps/appliance-restore-<timestamp>.log.
• Actionable failure diagnostics: If an export or restore fails (e.g. disk exhaustion or network timeout), the CLI immediately presents the exact file path and the command to view it:

  cat /var/calltelemetry/db_dumps/appliance-restore-2026-09-04-123456.log

  Followed by recommended next steps like running sudo ct doctor.

Export Appliance Archive (ct appliance export)

Full Disaster Recovery Guide

For detailed step-by-step procedures, architecture deep dives, and remote storage automation, see the dedicated Appliance Backup & Disaster Recovery guide.

Create a compressed .cta disaster recovery archive. By default, the export packages the full PostgreSQL database (including TimescaleDB hypertables), an AES-256-GCM encrypted secrets vault, enterprise TLS certificates (./certs/), configuration files (seaweedfs-s3.json, Caddyfile), audio media assets (./media/), and SeaweedFS object storage:

# Interactive export (packages database, secrets, certs, configs, media, and storage)
sudo ct appliance export

# Export to a custom destination file with inline passphrase
sudo ct appliance export /backups/calltelemetry-appliance-2026-09-04.cta --passphrase="MyVaultPassphrase123"

# Read passphrase from a secured file (useful for cron jobs and automation)
sudo ct appliance export /backups/appliance.cta --passphrase-file /root/.vault_passphrase

# Skip voluminous debug events and user activity logs while preserving all call records and schemas
sudo ct appliance export --skip-logs

# Configuration-only export: skip all call records, CURRI events, CDRs, Teams call data, and debug logs
sudo ct appliance export --skip-data

# Skip media files for a lightweight archive
sudo ct appliance export --skip-media

# Skip SeaweedFS storage volume
sudo ct appliance export --skip-storage

# Export and upload directly to remote SFTP or FTP storage
sudo ct appliance export --upload sftp://backup_user:secret@192.168.10.50/backups/ --clean-local

# Dry-run: inspect estimated tables, sizes, and row counts without dumping
sudo ct appliance export --dry-run

Flag	Description
--passphrase <str>	Passphrase to encrypt the secrets vault (AES-256-GCM)
--passphrase-file <path>	Read encryption passphrase from a local file
--skip-logs, --no-logs	Exclude diagnostic debug tables, webhooks, and user activity logs (retains call records)
--skip-data, --config-only	Exclude all call records, CURRI events, CDRs, and Teams data (creates config-only archive)
--skip-media, --no-media	Omit /home/calltelemetry/media directory (included by default)
--skip-storage, --no-storage	Omit SeaweedFS S3 storage volume (included by default)
--upload <url>	Upload completed archive to remote SFTP or FTP storage (sftp://... or ftp://...)
--clean-local	Remove the local .cta archive file after successful remote upload
--dry-run	Query catalog row estimates and report archive plan without creating files

Alias

sudo ct backup run and sudo ct backup export function as direct aliases for ct appliance export.

Inspect Archive (ct appliance inspect)

Examine an archive's manifest, source version, estimated table row counts, certificates, configs, and secret keys without restoring:

sudo ct appliance inspect /backups/calltelemetry-appliance-2026-09-04.cta

Example output:

=== CallTelemetry Appliance Archive Inspection ===
Archive:           calltelemetry-appliance-2026-09-04.cta
Created At:        Thu, 04 Sep 2026 12:00:00 UTC
Appliance Version: 0.8.7
Format Version:    1.0

Component Summary:
  - Database:      database/calltelemetry_prod.dump (4.12 GB, ~84.1M estimated records)
    Format:        pg_dump_custom (multi-core parallel restore compatible)
    SHA-256:       e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
    Key Tables (from pg_class catalog):
      cdrcalls                 ~84,120,400 rows
      cmr_records              ~12,450,200 rows
      cube_event_logs          ~3,200,100 rows
      curri_events             ~850,000 rows
      orgs                     ~12 rows
      users                    ~45 rows
  - Secrets Vault: secrets/secrets.env.enc (AES-256-GCM, PBKDF2-SHA256)
    Keys Secured:  CLOAK_KEY, POSTGRES_PASSWORD, SECRET_KEY_BASE, GUARDIAN_SECRET_KEY
  - Certificates:  certs/certs.tar.gz (3 files, 14 KB)
  - Config Files:  configs/configs.tar.gz (seaweedfs-s3.json, Caddyfile, 4 KB)
  - Media Assets:  media/media.tar.gz (48 files, 142 MB)
  - S3 Storage:    storage/seaweedfs-data.tar.gz (1.8 GB)

✓ Archive structure and manifest verified successfully.

Alias

sudo ct backup inspect <archive> functions as a direct alias for ct appliance inspect.

Restore Appliance Archive (ct appliance import)

Perform a full appliance restore from a .cta archive. This will restore the database, reconfigure TimescaleDB hypertables, decrypt and adopt credentials, restore enterprise certificates, configs, media assets, SeaweedFS storage, and restart all services.

# Interactive restore (prompts for passphrase and confirmation)
sudo ct appliance import /backups/calltelemetry-appliance-2026-09-04.cta

# Automated non-interactive restore
sudo ct appliance import /backups/calltelemetry-appliance-2026-09-04.cta --passphrase="MyVaultPassphrase123" --yes

# Restore directly from remote SFTP or FTP storage
sudo ct appliance import sftp://backup_user:secret@192.168.10.50/backups/calltelemetry-appliance-2026-09-04.cta --yes

Flag	Description
--passphrase <str>	Passphrase to decrypt the secrets vault (AES-256-GCM)
--passphrase-file <path>	Read decryption passphrase from a local file
--yes, -y	Skip interactive confirmation prompt
--force	Bypass version compatibility check

Automated 7-Step Restoration Sequence

1. Unpacking & Manifest Verification: Validates archive integrity against embedded SHA-256 checksums across all components (database, secrets, certs, configs, media, storage).
2. Pre-flight Decryption: Verifies the encryption passphrase and decrypts secrets vault before taking down any running services. If the passphrase is wrong, no changes occur.
3. Service Quiescing: Safely stops worker containers (web, nats, jtapi-sidecar, ct-media, seaweedfs).
4. TimescaleDB Pre-Restore Hook: Terminates active PostgreSQL connections and executes timescaledb_pre_restore() to disable background hypertable workers.
5. Database Restoration: Executes pg_restore -v with live table progress reporting and writes full diagnostics to the session log.
6. Asset Restoration & Credential Adoption: Restores configuration files (seaweedfs-s3.json, Caddyfile), enterprise TLS certificates (./certs/), audio media (./media/), and SeaweedFS object storage volume. Re-enables TimescaleDB background workers (timescaledb_post_restore()) and writes decrypted secrets (CLOAK_KEY, passwords) to /home/calltelemetry/.env and /etc/calltelemetry/.env.
7. Service Startup & Health Validation: Launches services with docker compose up -d and validates database readiness with pg_isready.

Alias

sudo ct backup import <archive> and sudo ct backup restore <archive> function as direct aliases for ct appliance import.

Automated Recurring Backups (ct backup schedule)

Manage automated recurring .cta disaster recovery archives using native Linux systemd timers:

# View active schedule, timer status, and next scheduled backup
sudo ct backup schedule

# Enable daily backup at 02:00 UTC with 7-day retention
sudo ct backup schedule enable daily --time 02:00 --target /var/backups/ --retention 7

# Enable weekly backup to remote SFTP with log filtering and local staging cleanup
sudo ct backup schedule enable weekly --day sun --time 03:00 \
  --target sftp://backupuser@storage.corp.lan/backups/ \
  --retention 4 \
  --skip-logs \
  --clean-local

# Test scheduled backup immediately on demand
sudo ct backup schedule run

# View scheduled backup execution history and journal logs
sudo ct backup schedule log

# Disable automated backups
sudo ct backup schedule disable

Alias

sudo ct appliance schedule-backup functions as a direct alias for ct backup schedule.

System Maintenance

Compact

Comprehensive cleanup including Docker system prune and PostgreSQL VACUUM FULL. Prefer the grouped form sudo ct db maintenance compact; sudo ct db compact remains a working alias:

sudo ct db maintenance compact

This command:

• Removes stopped containers
• Removes unused networks and volumes
• Removes dangling images
• Runs PostgreSQL VACUUM FULL on all tables

When to Compact

Run this monthly or when disk space is low, in a maintenance window. The operation takes an exclusive lock on the whole database and may take several minutes on large tables.

Purge

Remove unused Docker resources only (lighter than compact):

sudo ct docker prune

Removes:

• Stopped containers
• Unused networks
• Unused volumes
• Dangling images (retains images from last 24 hours)

Reset

Factory reset - stops services and deletes all data:

sudo ct reset

Data Loss Warning

This command permanently deletes:

• SFTP data
• PostgreSQL database
• All backups

The application restarts in factory state. This cannot be undone.

Enterprise SSL/TLS Certificates

Manage appliance TLS certificates for the web admin portal, Caddy reverse proxy, and enterprise CA trust store.

View Certificate Status

Inspect active certificates, validity windows, issuer, and Subject Alternative Names:

sudo ct certs status

Generate Certificate Signing Request (CSR)

Generate a private key and CSR to submit to your enterprise Certificate Authority (Microsoft CA, Active Directory CS, etc.):

sudo ct certs csr --cn appliance.corp.local --san appliance.corp.local,appliance,10.0.1.5

The CSR and generated private key are saved in /home/calltelemetry/certs/.

Import Enterprise Certificate

Validate and install an enterprise-signed certificate with its private key and optional intermediate chain:

sudo ct certs import \
  --cert /home/calltelemetry/certs/appliance.crt \
  --key /home/calltelemetry/certs/appliance.key \
  --chain /home/calltelemetry/certs/chain.crt

The CLI verifies that:

1. The certificate and private key match.
2. The certificate is currently valid (not expired or not yet valid).
3. The certificate chain resolves cleanly.

Upon validation, certificates are atomically deployed and the web proxy is reloaded without dropping active calls.

Add Internal CA to Trust Store

Install your organization's root or intermediate CA into the appliance operating system trust store so outbound TLS connections (such as CUCM AXL, Tomcat, or LDAPS) succeed without certificate verification errors:

sudo ct certs trust add /home/calltelemetry/certs/Enterprise-Root-CA.pem

Reset Certificates

Delete existing certificates and regenerate fresh self-signed SSL certificates for appliance portals:

sudo ct certs reset

Automation

Use --yes for non-interactive automation. Without it, an interactive terminal prompts for confirmation.

For UI-based CSR generation and browser upload workflows, see SSL Certificates for Call Telemetry Appliance.

Database Troubleshooting

Table Sizes

View row counts and disk usage:

# All tables
sudo ct db inspect tables

# Specific table filter
sudo ct db inspect tables cdr_records

Purge Old Records

Timestamp-batched DELETE of rows older than the given days (requires an inserted_at/timestamp column; optimized paths exist for known tables):

# Delete CDR records older than 90 days
sudo ct db purge cdr_records 90 --yes

# Purge by retention group (lists groups with: ct db purge-groups)
sudo ct db purge cube 7 --yes
sudo ct db purge-ct-events 7 --yes

Truncate Groups (wholesale, unbounded)

Debug/diagnostic log tables have no retention requirement. Truncate groups run a wholesale TRUNCATE ... CASCADE and are dramatically faster than batched DELETEs on large tables. They are unbounded — no days argument — and require --yes:

# All debug/mirror/webhook tables (CURRI debugs, XCC mirror, cube + CDR
# webhooks, workflow webhook requests, cube recovery failures)
sudo ct db data purge truncate-debug --yes

# CUBE/XCC + CURRI event logs and disconnect metrics (keeps CDRs)
sudo ct db purge truncate-telemetry --yes

The run prints a per-table row count before truncating and skips tables that do not exist. Non-interactive runs refuse without --yes and print the exact re-run command. truncate-debug removes no CDRs, call records, or events.

Unbounded operation

TRUNCATE removes all rows in the group's tables immediately — there is no retention window and no undo. Prefer db data purge <table> <days> --yes whenever a retention period applies.

Destructive operation

Review the target table and retention period carefully before proceeding. The --yes flag is required for scripted deletion.

Offline / Air-Gapped Bundles

Build bundles on an internet-connected workstation with Call Telemetry Appliance Manager (macOS / Windows), or using the ct offline download command.

On the appliance, use offline apply / offline list after you stage or transfer a bundle.

For the full end-to-end workflow (download Manager → build → transfer → apply), see the Air-Gapped Appliance Upgrade guide.

Version requirement

Applying ISO or chunked bundles requires appliance CLI 0.8.7 or later. SFTP/FTP remote apply is supported natively in CLI 0.8.7+.

On-appliance Offline Commands

Command	Description
offline apply <bundle|dir|url>	Apply a bundle from a local archive, directory, mounted ISO, or remote SFTP/FTP server
offline list	List images in the current docker-compose.yml and which are downloaded
offline download [version]	Build an offline bundle on an internet-connected workstation, with optional SFTP/FTP upload

Apply a Bundle

Run on the air-gapped appliance. offline apply performs the same full upgrade as the online update — no manual .env editing required.

1. Remote SFTP or FTP Storage

Deploy updates directly from a central network file share without pre-staging files on the appliance disk:

# Direct SFTP pull (credentials in URL or prompted interactively)
sudo ct offline apply sftp://backup.corp.local/bundles/calltelemetry-offline-0.8.7.tar.gz

# SFTP with SSH private key authentication and retaining downloaded file
sudo ct offline apply sftp://files.corp.local/builds/calltelemetry-offline-0.8.7.iso \
  --user deploy --key /home/calltelemetry/.ssh/id_ed25519 --keep-download

# Internal FTP repository
sudo ct offline apply ftp://anonymous@ftp.corp.local/pub/calltelemetry-offline-0.8.7.tar.gz

2. Mounted ISO (Recommended for Appliance Manager)

sudo mkdir -p /mnt/cdrom
sudo mount -o loop calltelemetry-offline.iso /mnt/cdrom
sudo ct offline apply /mnt/cdrom

3. Local Folder / Extracted Directory

Apply directly from an uncompressed or extracted release directory:

sudo ct offline apply /home/calltelemetry/calltelemetry-build

4. Chunked ISO Parts

# Point to the first chunk; all sibling parts in the directory will be reassembled automatically
sudo ct offline apply calltelemetry-offline.iso.part-000

apply Options Reference

Flag	Description
--backup-db	Force a pre-upgrade database snapshot before applying changes
--no-backup-db	Skip the pre-upgrade snapshot (default prompts on an interactive terminal)
-u, --user <username>	Username for remote SFTP/FTP authentication
-p, --password <secret>	Password for remote SFTP/FTP authentication (prompted securely if omitted)
-i, --key <identity_file>	Path to SSH private key for remote SFTP authentication
--keep-download	Retain downloaded archive in /home/calltelemetry/ after remote apply (default cleans up)

Automatic Verification & Rollback

offline apply verifies SHA-256 checksums before loading images. A pre-upgrade configuration snapshot is created before replacing active configs. To revert configuration, use sudo ct rollback (the snapshot timestamp is printed on failure). Restore database contents separately with sudo ct db restore <file>.

Download and Upload Bundles (offline download)

On an internet-connected workstation, ct offline download can build release bundles and optionally upload them directly to internal SFTP/FTP storage:

# Build a standard tar.gz bundle for a specific version
ct offline download 0.8.7-rc1

# Build and immediately upload to central SFTP file share, cleaning up local files
ct offline download 0.8.7-rc1 \
  --upload sftp://deploy@files.corp.local/bundles/ \
  --clean-local

# Build as a single ISO with specific compose profiles
ct offline download 0.8.7-rc1 --format iso --profiles jtapi,syslog

# Split into 2GB chunks for FAT32 or file size restrictions
ct offline download 0.8.7-rc1 --chunk-size 2G

Configuration

Logging Level

Modify the logging level in docker-compose.yml and restart services:

sudo ct logging debug

Available levels:

• debug - Verbose logging for troubleshooting
• info - Normal operational logging (default)
• warning - Warnings and errors only
• error - Errors only

Advanced Operations

Build Appliance

Download and execute appliance initialization script:

sudo ct build-appliance

Prepare Cluster Node

Configure node for Kubernetes deployment:

sudo ct prep-cluster-node

This command:

• Disables firewall and SELinux
• Installs kubectl, helm, and K9s
• Installs Git

Diagnostics & Observability

Appliance Health Check (ct doctor)

Run active preflight sanity and health diagnostics across all appliance subsystems:

sudo ct doctor

ct doctor tests:

• Database pool connectivity: Ping database connection pool with latency metrics.
• Disk space: Verify free space across root and data partitions.
• NTP time synchronization: Verify clock drift against reference time sources.
• TLS certificate expiration: Alert on certificates nearing expiration within 30 days.
• System memory & CPU load: Check host memory saturation and container limits.

Service Container Logs (ct logs)

Stream or tail logs from appliance Docker compose services without manually running docker logs:

# Tail the primary web application logs
sudo ct logs web

# Follow logs in real-time
sudo ct logs web -f

# Tail the last 200 lines of JTAPI sidecar logs
sudo ct logs jtapi --tail 200

# View Caddy reverse proxy or NATS messaging logs
sudo ct logs caddy
sudo ct logs nats

Appliance Telemetry & Crash Reporting (ct telemetry)

Appliance telemetry helps Call Telemetry detect release migration issues, crash loops, and platform errors automatically to deliver faster fixes. Telemetry is opt-in and covers both the host CLI and appliance backend services.

Telemetry never transmits customer call data, CDRs, phone numbers, or passwords.

# Check current telemetry posture
ct telemetry status

# Enable appliance telemetry
sudo ct telemetry enable

# Disable appliance telemetry
sudo ct telemetry disable

When enabled, telemetry reports:

• CLI command execution outcomes and exit codes
• Database migration duration and failure diagnostics
• High-level system errors and unhandled exceptions

Storage & Cisco UC Connectivity

Test Remote Backup Storage (ct backup test)

Verify network reachability, credentials, and write permissions for remote SFTP or FTP backup destinations before initiating backups or automated jobs:

# Test remote SFTP storage with inline credentials
sudo ct backup test sftp://backup_user:secretPass@192.168.10.50/backups/

# Test SFTP with interactive password masking
sudo ct backup test sftp://backup_user@192.168.10.50/backups/

# Test FTP destination
sudo ct backup test ftp://backup_user:secretPass@192.168.10.50/backups/

backup test connects to the remote host, uploads a unique temporary probe file (.ct-backup-probe-<uuid>), verifies the file size and read access, and deletes the probe file, confirming full read/write/delete permissions.

Check Cisco UC Reachability (ct cucm check-ports)

Perform rapid TCP and UDP socket reachability checks against a Cisco Unified Communications Manager (CUCM) node:

sudo ct cucm check-ports 192.168.125.10

Validates critical Cisco UC communication ports:

• 8443 (TCP): AXL / Tomcat Administrative Web API
• 2748 (TCP): CTI Manager / JTAPI Provider port
• 6970 (TCP): TFTP over HTTP configuration service
• 514 (UDP/TCP): CDR / Syslog message export

Output presents clear [PASS], [WARN], or [FAIL] status along with measured socket latency.

License & Query Inspection

License Status & Quota (ct license status)

Inspect the appliance license tier, active phone quota usage, and expiration details:

sudo ct license status

Displays:

• Organization: Licensed organization name.
• Tier: Community, Enterprise, or Premium.
• Phone Quota: Active registered phones vs. licensed capacity.
• Expiration: Expiration timestamp and remaining days.

Active Database Queries (ct db active-queries)

Inspect currently executing non-idle queries from PostgreSQL's pg_stat_activity:

sudo ct db active-queries

Displays backend PID, client IP address, query state, elapsed execution duration, and query text. Designed for non-blocking read-only execution with zero locks on large tables.

Shell Autocompletion

Generate shell completion scripts or auto-install completion for the interactive shell:

# Generate completion script for your current shell
sudo ct completion bash
sudo ct completion zsh
sudo ct completion fish

# Load completions into current Bash session
source <(sudo ct completion bash)

# Load completions into current Zsh session
source <(sudo ct completion zsh)

Common Workflows

Upgrading with Safety Checks

# 1. Create backup before upgrade
sudo ct db backup

# 2. Run upgrade
sudo ct update

# 3. Monitor migration progress
sudo ct migrate watch

# 4. If issues occur, rollback
sudo ct rollback

Troubleshooting Disk Space

# 1. Check table sizes (read-only)
sudo ct db inspect tables

# 2. Purge old records
sudo ct db purge cdr_records 90 --yes

# 3. Truncate debug/webhook log tables wholesale (fast, unbounded)
sudo ct db purge truncate-debug --yes

# 4. Reclaim disk (locks every table — maintenance window)
sudo ct db maintenance compact

Investigating Migration Failures

# 1. Check migration status
sudo ct migrate status

# 2. View recent migrations from database
sudo ct migrate history

# 3. Check application logs
sudo docker logs calltelemetry-web -f

# 4. Manually run migrations if needed
sudo ct migrate run

Full Appliance Disaster Recovery & Host Migration

Migrate an entire appliance to a new VM or restore after a disaster:

# 1. On source appliance: export complete archive (DB, certs, configs, media, storage, encrypted secrets)
sudo ct appliance export /backups/appliance-full.cta

# 2. Transfer archive to target appliance host (via scp, sftp, or mounted volume)
scp /backups/appliance-full.cta admin@new-appliance:/tmp/

# 3. On target appliance: inspect payload, table row estimates, and version
sudo ct appliance inspect /tmp/appliance-full.cta

# 4. Restore everything (quiesces services, restores DB, re-enables TimescaleDB, syncs .env)
sudo ct appliance import /tmp/appliance-full.cta --yes

# 5. Verify appliance health and connectivity
sudo ct doctor
sudo ct logs web --tail 50

See Also

• Upgrading Guide - Step-by-step upgrade procedures
• Air-Gapped Appliance Upgrade - Offline bundle workflow
• Kubernetes Deployment Guide - K8s deployment and updates