Asterisk and FreePBX: phone systems

Asterisk, and FreePBX built on it, is watched three ways, each answering a different question:

The first two need nothing but the sensor and, for ARI, a read-only user on the phone system. The third needs two small changes on the phone system, set out below.

Is it answering: SIP OPTIONS

The probe sends a SIP OPTIONS request and reads the reply. OPTIONS is the keepalive every SIP endpoint answers and none acts on: nothing rings and no call record is left. It is a far better check than a port test, because a phone system whose SIP stack has wedged often still accepts a connection.

Add a SIP OPTIONS sensor to the phone system's device, on UDP 5060 unless it listens elsewhere. Look at what it answers before writing a rule: not every system answers 200, and a 401, 403 or 404 from a healthy one is common. Status code at least 500 for critical is a safe start. The sensor's own Help describes every setting.

Asterisk and FreePBX ban addresses that send them SIP they do not expect. Allow the probe's address in fail2ban, or on FreePBX in Connectivity > Firewall as Trusted, or the probe is banned after a few polls and the sensor reads as down.

Are the trunks and phones registered: ARI

ARI, the Asterisk REST Interface, answers with every PJSIP endpoint and its state: trunks, extensions, gateways. The ASTERISK PJSIP template asks for that list once a minute and turns it into one reading per endpoint, so a trunk that has dropped is an alarm on the phone system that names it.

On plain Asterisk

Turn on Asterisk's web server in /etc/asterisk/http.conf, listening where the probe can reach it:

[general]
enabled = yes
bindaddr = 0.0.0.0
bindport = 8088

Then turn on ARI with a read-only user in /etc/asterisk/ari.conf, with a long random password of your own:

[general]
enabled = yes

[oversight]
type = user
read_only = yes
password = a-long-random-password

Load both with asterisk -rx "module reload http" and asterisk -rx "module reload res_ari.so", or restart Asterisk out of hours.

On FreePBX

FreePBX writes those files itself, so set them in the interface instead. In Settings > Advanced Settings, under Asterisk Builtin mini-HTTP server, enable the mini-HTTP server on port 8088. In Settings > Asterisk REST Interface Users, add a user for Oversight, read only, with a long random password. Apply Config. FreePBX's firewall must let the probe reach port 8088: give the probe's address the Trusted zone, as for SIP.

ARI over plain HTTP carries the password readable, so keep it to the probe on the phone system's own LAN, never across the internet.

In Oversight

1. On the phone system's device, add an HTTP(S) credential with the ARI user's name and password. The template sends it as basic authentication.
2. Add a sensor from the ASTERISK PJSIP template. It asks for http://<device>:8088/ari/endpoints/PJSIP through the uf_asterisk user function.
3. Change its extraction rows to your own endpoints. The template comes with three examples, a SIP trunk and two GSM gateways, as a pattern: each row reads one endpoint by its name in Asterisk, exactly as it appears under Connectivity > Trunks or in pjsip show endpoints.
4. Adjust the rules to match. As shipped, the trunk not online is critical and either gateway not online a warning.

Each endpoint reads 0 offline, 1 online, 2 unknown or 3 not found, so the rule is simply not equal to 1. Two more readings come with every poll: down, how many endpoints are not online, and downlist, their names, for the alarm text.

To watch only some endpoints, such as the trunks and not every desk phone, give the user function the names that must exist, as its arguments: {"expect": ["TELNYX_03301901990", "GSMGateway1"]}. One that has been deleted or renamed then reads 3 rather than disappearing, and down counts only those.

What online means is worth knowing. Asterisk only knows an endpoint is reachable when its AOR checks it, with qualify_frequency set; without that, a trunk with a fixed address reads online for as long as it is configured, whether or not the provider is answering. And a trunk's outbound registration, the phone system logging in to the provider, is not in ARI at all: a SIP OPTIONS sensor against the provider, or the logs below, covers that.

The template keeps the raw response with each reading, which is useful while setting it up and costs extra credits. Turn off Store raw response once the readings are right.

Is it under attack: the logs

A phone system on the internet is attacked all day. Bots try to register as extensions, guess passwords and look for accounts that do not exist, and a busy one sees thousands of attempts an hour. Asterisk records every attempt, but by default only in its own files under /var/log/asterisk, where nobody sees them until something has gone wrong.

Sent to the site's syslog sender, they are counted on each phone system and shown as a count per hour, with an alarm when it climbs. A botnet at the door shows as a spike on the one phone system it is hammering, in time to tighten its fail2ban before an account falls. None of the attempts themselves is sent to Oversight, only how many there were.

Sending the host's syslog

The same as any Linux server: one line in /etc/rsyslog.d/oversight.conf, with the syslog sender's machine at 172.16.128.55, then systemctl restart rsyslog:

*.* action(type="omfwd" target="172.16.128.55" port="514" protocol="udp")

Older guides give the short form, *.* @172.16.128.55:514, which does the same; the longer one is unambiguous on every current rsyslog. Use the port the syslog sender listens on, 514 unless it was set up otherwise. A wrong port fails silently: the phone system sends, and nothing arrives. Some newer installs, Debian 12 among them, come without rsyslog and keep everything in the systemd journal; install it first with apt install rsyslog.

Asterisk writing to syslog

Asterisk's logging is set in logger.conf, whose [logfiles] section lists where each kind of message goes. One more line there sends what matters to syslog:

syslog.local0 => notice,warning,error,security

Leave out verbose and debug. They describe every step of every call, which is what the files in /var/log/asterisk are for, and would swamp the syslog sender for no benefit. Then reload the logger, which drops no calls:

asterisk -rx "logger reload"

On plain Asterisk, add the line to the [logfiles] section of /etc/asterisk/logger.conf, beside the lines already there.

On FreePBX, logger.conf is rewritten on the next Apply Config, so an edit there is lost. Its [logfiles] section takes in logger_logfiles_custom.conf, which FreePBX leaves alone. Put the line there instead:

echo 'syslog.local0 => notice,warning,error,security' >> /etc/asterisk/logger_logfiles_custom.conf
chown asterisk:asterisk /etc/asterisk/logger_logfiles_custom.conf
asterisk -rx "logger reload"

To check it took, asterisk -rx "logger show channels" lists a syslog.local0 channel with those levels beside the log files.

Checking it arrives

Within a minute or two, the phone system's address appears under Sources on the Logs page for the syslog channel, and Asterisk's lines carry the tag asterisk. GEN then adds the count rules for the failed registrations and passwords, from your own phone system's lines rather than a generic pattern, since the wording differs between Asterisk versions and SIP channels. A Log count sensor on the phone system's device turns the count into a trend, with a threshold such as more than 1,000 failures an hour for critical.