Asterisk DHCP Server: installation and guide

Platform and requirements

The Asterisk DHCP Server is one RPM for Red Hat Enterprise Linux 9 or a compatible system - Rocky Linux 9, AlmaLinux 9, Oracle Linux 9 or CentOS Stream 9 (x86_64). Not every RPM-based system is compatible: Fedora and openSUSE are not supported. A dedicated virtual machine is the preferred platform - a DHCP server should be the one thing answering DHCP on its network.

How subnets reach it

Asterisk serves every subnet from its one network interface - no VLAN interfaces on the server:

• The server's own subnet is answered directly: mark that scope local.
• Every other subnet reaches it through a DHCP relay on that subnet's router or switch, pointed at the server's address - on Cisco: ip helper-address 10.0.10.20 on the VLAN interface. The relay tells Asterisk which subnet asked, and Asterisk answers from the matching scope.

interface Vlan20
 ip helper-address 10.0.10.20      # the Asterisk server

Get the package

1. Request the download at activation.shanaei.com/download/asterisk with your name, email, company and phone. You get a personal status link straight away - keep it.
2. Once we approve it, the status link shows the RPM and its SHA-256 checksum, and we email you the link. It works for 14 days.
3. Copy both files to the server, e.g. scp asterisk-dhcp-0.10.5-1.el9.x86_64.rpm* root@dhcp01:/root/.

Install

On the server, as root - bring the system up to date, check the file, install:

dnf -y upgrade
cd /root
sha256sum -c asterisk-dhcp-0.10.5-1.el9.x86_64.rpm.sha256      # must say: OK
dnf -y install ./asterisk-dhcp-0.10.5-1.el9.x86_64.rpm

The package creates its service user, /etc/asterisk-dhcp/, the database in /var/lib/asterisk-dhcp/ and a secret key, and opens the firewall (firewalld service asterisk-dhcp: 67, 547, 443, 80). Then three steps:

ip -br addr                                               # its interface name, e.g. ens192
vi /etc/asterisk-dhcp/asterisk-dhcp.env                   # set ASTERISK_DHCP_INTERFACE=ens192
asterisk-dhcp create-admin --username admin               # asks for the password
systemctl enable --now asterisk-dhcp

Open https://<server>/. The certificate is self-signed at first (install your own in Settings › Web management interface); the browser asks once.

systemctl status asterisk-dhcp-web asterisk-dhcp-daemon --no-pager      # both: active (running)

First sign-in and activation

1. Sign in as the administrator you created.
2. Activate on the Licence page: read the end-user licence agreement, enter your full name and company and accept it - the one-month trial with every feature starts that day. In its last 7 days a banner and a daily reminder ask you to request a licence and to back up the configuration.
3. To buy, request a subscription or perpetual licence on the same page - we confirm it by email and it arrives on its own at the next daily check.

Your first scope

1. Scopes › New scope: the subnet (e.g. 10.0.20.0/24), the address pool to hand out (10.0.20.100 - 10.0.20.199), the gateway and DNS servers, the lease time. Tick local only for the server's own subnet.
2. Add any further DHCP options for that scope (domain name, NTP, option 43 for Cisco Plug and Play or access points …).
3. Set up the relay on the subnet's router (above) and plug in a client: it shows up under Leases within seconds.
4. Fixed addresses for printers, cameras or servers: Reservations - by MAC address.

The pages

Passwords and accounts

Change your own password

Click your name at the bottom of the menu: Change password - the current one, then the new one (at least 8 characters).

Reset someone else's password

An administrator opens Users, edits the user and types a new password.

Lost the administrator password

On the server, as root - replace admin with the user name (version 0.10.5 or later):

asterisk-dhcp reset-password --username admin      # asks for the new password twice

On an older version, create a second administrator instead and set the first one's password under Users: asterisk-dhcp create-admin --username admin2.

An API key for monitoring

asterisk-dhcp create-api-token --name zabbix --allow 10.0.10.0/24      # read-only; printed once

Backups and restore

Licence › Your configuration › Back up now (also linked from the banner near the end of a trial) downloads the whole database - scopes, reservations, leases, settings and users - as one file. It works even when the licence has ended. Settings › Configuration export & import moves scopes and reservations between servers.

To restore a backup:

systemctl stop asterisk-dhcp
cp asterisk-dhcp-dhcp01-20261026-1200.db /var/lib/asterisk-dhcp/asterisk_dhcp.db
chown asterisk-dhcp:asterisk-dhcp /var/lib/asterisk-dhcp/asterisk_dhcp.db
rm -f /var/lib/asterisk-dhcp/asterisk_dhcp.db-wal /var/lib/asterisk-dhcp/asterisk_dhcp.db-shm
systemctl start asterisk-dhcp

Upgrades

sha256sum -c asterisk-dhcp-0.10.6-1.el9.x86_64.rpm.sha256
dnf -y upgrade ./asterisk-dhcp-0.10.6-1.el9.x86_64.rpm

The services restart by themselves; scopes, leases, settings and the licence stay. Download a backup first.

Commands for operators

Troubleshooting

Clients get no address

Watch journalctl -u asterisk-dhcp-daemon -f while a client asks. Nothing arrives: check the relay (ip helper-address) and that the firewall allows 67/udp (firewall-cmd --list-services shows asterisk-dhcp). It arrives but no scope matches: the relay's address must be inside one of your scopes. Also check the Licence page - an ended licence stops DHCP.

The web page doesn't open

systemctl status asterisk-dhcp-web, and the firewall. The address and port are shown under Settings › Web management interface.

Activation or the licence check fails

The server must reach https://activation.shanaei.com: curl -sI https://activation.shanaei.com/. Behind a proxy, set it in Settings › Internet access. "Permission denied" through a proxy on an older version: update to 0.10.4 or later.

Still stuck?

Contact us with the output of journalctl -u asterisk-dhcp-daemon -u asterisk-dhcp-web --since "-1 h".