MySQL Configuration

Astervis reads every call from your PBX's MySQL/MariaDB database — the same one FreePBX or Asterisk already writes Call Detail Records (CDRs) to. It takes one consistent snapshot of your call history, then follows the binary log in real time so new calls land in your dashboards within seconds. This page explains how that connection is configured, how to turn on binary logging, and the exact database grants the change-data-capture (CDC) service needs.

The installer sets all of this up for you on a clean install. You only need this page when auto-detection misses something, you're wiring up a non-standard PBX, or you're chasing down an empty call history.

How the connection is detected

During Step 3/4 of the install wizard, the installer probes the usual PBX config files and pulls the CDR database credentials out automatically, so most servers never see a prompt. Detection covers all the supported PBX systems — Sangoma PBX, FreePBX, Issabel, VitalPBX, Elastix, and generic Asterisk.

When detection succeeds, the wizard skips the MySQL prompt entirely. When it can't find credentials — a custom Asterisk build, an unusual config path — it falls back to asking you for four values, pre-filled with sensible defaults:

The manual .env fallback

Everything the installer collects ends up in /opt/astervis/.env (mode 0600). If you need to correct the connection after install, edit that file directly:

MYSQL_HOST=host.docker.internal
MYSQL_PORT=3306
MYSQL_USER=freepbxuser
MYSQL_PASSWORD=your_mysql_password
MYSQL_DB=asteriskcdrdb
MYSQL_USERS_DB=asterisk
MYSQL_TIMEZONE=Asia/Tashkent

The litcdc CDC service reads its own copy of these values (as LITCDC_MYSQL_*) from the same .env. After editing, restart the stack so both the application and the CDC service pick up the change:

sudo astervis-installer restart

Why containers can't use localhost

This is the single most common configuration mistake, so it's worth understanding. Astervis runs in Docker containers. Inside a container, localhost and 127.0.0.1 resolve to the container's own loopback interface — not the host machine. Your MariaDB lives on the host, so a container that dials localhost:3306 connects to nothing and your call history stays empty.

The fix is host.docker.internal, a special DNS name Docker resolves to the host's gateway address. The installer handles this for you: it rewrites any loopback value (localhost, 127.0.0.1, ::1, 0.0.0.0) in MYSQL_HOST to host.docker.internal automatically. A real LAN or remote address is left untouched.

MYSQL_HOST=host.docker.internal

Enabling binary logging

Real-time CDC works by reading MySQL's binary log (binlog) — the same mechanism MySQL replication uses. litcdc needs row-based binlog turned on with full row images. The installer enables this for you (ConfigureMySQLForCDC), but on a locked-down or non-standard server you may need to do it by hand.

First, check whether binlog is already on:

mysql -u root -p -e "SHOW VARIABLES LIKE 'log_bin';"

If the value is OFF, add the configuration block below under [mysqld]. This is the exact block the installer writes — match it so your manual setup behaves identically to a managed install:

[mysqld]
server-id = 1
log_bin = mysql-bin
binlog_format = ROW
binlog_row_image = FULL
expire_logs_days = 3
max_binlog_size = 100M
bind-address = 0.0.0.0

A few notes on why each line matters:

• binlog_format = ROW + binlog_row_image = FULL — litcdc needs the full before/after row data, not statement-level SQL. Anything other than ROW breaks CDC.
• expire_logs_days = 3 — binlogs are rotated after three days so they don't fill the disk. Without an expiry, binlogs grow unbounded.
• bind-address = 0.0.0.0 — lets the Docker bridge network reach MariaDB. The installer also rewrites any existing bind-address = 127.0.0.1 it finds in the MariaDB config tree.

sudo nano /etc/my.cnf

sudo systemctl restart mariadb

mysql -u root -p -e "SHOW VARIABLES LIKE 'log_bin';"

The CDC user grant

litcdc connects as a database user to take its initial snapshot and then stream the binlog. That user needs a specific set of global privileges. The installer grants them automatically; if you're provisioning the user yourself, run:

GRANT RELOAD, LOCK TABLES, SHOW DATABASES, REPLICATION CLIENT, REPLICATION SLAVE
  ON *.* TO 'freepbxuser'@'%';

GRANT SELECT ON asteriskcdrdb.* TO 'freepbxuser'@'%';
GRANT SELECT ON asterisk.* TO 'freepbxuser'@'%';

FLUSH PRIVILEGES;

Why each privilege is required:

• REPLICATION SLAVE and REPLICATION CLIENT — let litcdc read the binlog stream and query its position. These are the core CDC privileges.
• RELOAD and LOCK TABLES — required for the initial snapshot. litcdc runs FLUSH TABLES WITH READ LOCK to capture a consistent point-in-time view of the cdr table before it starts streaming. Without LOCK TABLES, the snapshot fails and you get no call history.
• SHOW DATABASES — litcdc enumerates databases while setting up the snapshot.
• SELECT on the CDR and users databases — to read the rows themselves.

The grant is on '<user>'@'%' (any host) because the connection arrives over the Docker bridge network, not from localhost. The installer also opens TCP 3306 to the Docker subnet (172.16.0.0/12) in the host firewall so containers can reach MariaDB.

The CDR table

Astervis reads the standard Asterisk cdr table — one row per call leg. litcdc takes a consistent snapshot of this table for the historical backfill, then follows new inserts via the binlog. The columns it relies on are the usual Asterisk CDR fields:

You don't create or modify this table — FreePBX/Asterisk already maintains it. Astervis only reads from it.

Testing the connection

The fastest check is to confirm the database is reachable with the credentials from your .env, using 127.0.0.1 from the host (the container's host.docker.internal points to the same place):

mysql -h 127.0.0.1 -P 3306 -u freepbxuser -p asteriskcdrdb -e "SELECT COUNT(*) FROM cdr;"

A row count confirms the user, password, host, and table are all correct. Then check the CDC service is actually streaming:

sudo astervis-installer logs

A healthy astervis-litcdc container logs a completed snapshot followed by a steady realtime stream; the astervis-replication container should show events flowing into TimescaleDB. Once that's running, new calls appear in your dashboards at https://<your-domain-or-IP>:8443 within seconds.

Common errors

Next steps