Docs / Start here

Network, NAT and firewall

This chapter covers the server's own network settings: a fixed address and how to change it safely, what to set when the server sits behind a router (NAT), the ports the phone system uses, the firewall on the Server › Network page, port forwards on the router, DNS records, and the built-in connectivity test.

The examples use a server at 10.0.0.20 on the office network 10.0.0.0/24 (gateway 10.0.0.1), behind a router whose public address is 203.0.113.10, with the name pbx.example.com.

A fixed address

Phones are provisioned to the server's address and register to it, and the router forwards ports to it. The address must therefore never change. Give the server either a static address or a DHCP reservation on your DHCP server. The first-boot setup asks for this (see Installing the server); you can change it later in the console or on the server's screen.

Phones and carriers reach the phone engine over IPv4. The console and portal also answer on IPv6 if the server has an IPv6 address.

Changing the address in the console

Changing the address can cut you off from the server, so the console undoes the change by itself unless you confirm it within 5 minutes.

1. Open Server › Network (system administrators only). The Interfaces card shows each network card, its state and speed, its addresses (marked "(DHCP)" when they came from DHCP) and its traffic, with the gateway and DNS servers above.
2. Press Change address.
3. In Change the address, fill in:
   • Interface: the network card;
   • IPv4: Automatic (DHCP) or Static. For static, the IPv4 address with its prefix length, for example 10.0.0.20/24 (several are separated by commas), and the Gateway, which must be inside that network;
   • IPv6: Automatic, Static (with IPv6 address and IPv6 gateway) or Off;
   • DNS servers: up to three, needed with a static address;
   • Search domains, optional;
   • MTU: leave it empty unless your network needs it (576 to 9216).
4. Press Apply. The server checks the configuration first and refuses one that the network service would not accept.
5. Two seconds later the new configuration is live. If the address changed, this page loses its connection: open the console at the new address, for example https://10.0.0.21/admin, and go to Server › Network.
6. A card says that a network change is waiting, with a countdown. Press Keep.

If you do not press Keep within 5 minutes, the previous configuration comes back by itself, so a wrong address cannot lock you out. Undo now brings it back at once. The server keeps copies of the last ten configurations it replaced.

When the address changes, phones that were set up with the old address need to be pointed at the new one (see Desk phones), and the router's port forwards and your DNS records must follow.

On the server's screen

If the console cannot be reached, sign in on the server's screen as onyxadmin (or run sudo onyx-console over SSH) and choose Network and firewall. It has the same tools: Show the current configuration, Change the address (DHCP or static, IPv4/IPv6, DNS), Test connectivity, Firewall and Change the host name.

Behind a router (NAT)

Most servers sit on a private network behind a router. Phones in the office reach the server at 10.0.0.20, but phones at home and carriers on the internet reach it at the router's public address, 203.0.113.10, through port forwards.

SIP messages carry addresses: each side tells the other where to send the call audio. If the server tells an outside phone or carrier to send audio to 10.0.0.20, that audio never arrives, and the call connects with one-way audio or none. So the server must know its public address and announce it to everyone outside the office network.

Two settings do this. Both are on Server settings, in the Calls and network group:

With a public address set, the engine announces it in calls with phones and carriers outside the local networks, for the SIP messages and for the call audio, on UDP, TCP and TLS. Phones inside the local networks get the server's own address, as before.

To set them:

1. Open Server settings.
2. In Public address, type 203.0.113.10 and press Save (or Enter).
3. Check Local networks. It must include every network your office phones are on, including networks behind a VPN or another site router that reach the server without NAT. If you change it, list them all, for example 10.0.0.0/8, 172.16.0.0/12.

The first-boot setup sets Public address for you when you answer Yes to the NAT question. With the command line: onyx setting set engine.external_address 203.0.113.10.

Notes:

• A fixed public IP address is the dependable choice. A DNS name is accepted, for example for a line whose address changes now and then.
• An empty field is saved as an empty value. For Public address that turns NAT off, as intended. For Local networks it means "no local networks"; to go back to the default instead, run onyx setting unset engine.local_nets.
• Local networks also decides, unless you set something else, which networks may fetch desk phone settings and which phones plug-and-play answers (see Desk phones).
• Changes reach the engine within a second. Some network changes restart the engine; it waits until no calls are up.
• STUN server (engine.stun_server, host or host:port) lets the engine learn its public address from a STUN server. Setting Public address yourself is simpler and does not depend on an outside service.

Phones at home, behind their own router, need no special settings. The engine answers each phone at the address and port its packets came from, and sends call audio back the way it came. Phone keepalive (seconds) (default 60) checks registered phones regularly, which also keeps their home router's NAT mapping open.

The connectivity test below tells you whether the server is behind NAT and what its public address is.

Ports

The SIP, SIP over TLS and audio ports are settings on Server settings: SIP port (engine.sip_port), SIP TLS port (engine.sip_tls_port), Audio ports from (engine.rtp_start) and Audio ports to (engine.rtp_end). The defaults suit almost every network. If you change them, change the firewall and the router's forwards to match; the firewall card's warnings and Reset to phone system ports always use the ports the engine really has.

Every call uses audio ports from the range, so keep it wide. For the cluster ports, see High availability.

The firewall

The server has a firewall (ufw). Manage it on the Firewall card at the bottom of Server › Network, or under Network and firewall on the server's screen.

The card shows whether the firewall is On ("only the ports below accept connections") or Off ("every port that has a service listening is reachable"), and the rules.

• Turn on / Turn off switches the firewall. Turning it on always opens SSH (22) and HTTPS (443) first if no rule does, so you cannot lock yourself out of the console.
• Reset to phone system ports replaces all rules (it asks Replace all rules? first) with the phone system's set: incoming connections are refused except SSH, HTTP and HTTPS, SIP over UDP and TCP, SIP over TLS, the audio range and plug-and-play. Outgoing connections are allowed.
• Close next to a rule removes it. Closing SSH or HTTPS for everyone asks Close it? You may lock yourself out first.
• To open a port, fill in Port (a number, or a range like 10000:20000), Protocol (TCP or UDP) and From (any, or an address or network such as 203.0.113.0/24), and press Open port.

Above the rules, the card warns about anything the phone system needs that the firewall blocks: SSH or the console unreachable, a closed SIP port ("phones and trunks using it cannot register or call"), audio ports that are not all open ("calls connect without audio or with one-way audio"), and a closed plug-and-play port. These are warnings, not errors: closing SIP for everyone is a valid choice when only known carriers and sites may reach it. In that case open the SIP port for their addresses only, with From.

The firewall that the first-boot setup turns on opens the plug-and-play port 5062 too. On a server set up with version 0.1.0 it does not, and the card warns about it: press Reset to phone system ports, or open 5062 UDP, if you want new phones on the office network to find the server by themselves. DHCP option 66 and typing the address into the phone work either way.

Addresses that keep failing to sign in (phones, softphones or the console) are blocked by Onyx Voice's intrusion prevention, separately from these rules. The card shows how many are blocked and links to the Security page. See Security.

Port forwards on the router

When phones or carriers reach the server from the internet, forward these ports on the router to the server's office address (10.0.0.20), with the same port number outside and inside:

Do not forward 22, 5062, 5432, 8444 or 8446.

Then set Public address to the router's public address (see Behind a router (NAT)).

Tips:

• If only your carrier needs to reach the server, limit the SIP forward to the carrier's addresses on the router, or keep it open on the router and limit it with From on the server's firewall. Your carrier's documentation lists its addresses; the trunk templates show them too (see Trunks (carriers)).
• Many routers have a "SIP ALG" or SIP helper that rewrites SIP messages passing through. It often causes one-way audio and failed registrations with a phone system that handles NAT itself; turn it off.
• Remote desk phones also need permission to fetch their settings from outside the office (the setting Phones may fetch settings from; see Desk phones).

DNS records

Phones, softphones and browsers reach the server by its name, for example pbx.example.com. Create an A record for it:

• Only office phones: in your office DNS, pbx.example.com points to 10.0.0.20.
• Phones outside too: in public DNS, pbx.example.com points to 203.0.113.10. If office phones should use the office address, also create the record in your office DNS server with 10.0.0.20 (split DNS). Many routers cannot send traffic from the office back in through their own public address, so office phones that resolve the public address may fail.
• Let's Encrypt: the public record must point to the public address, with port 80 forwarded. Every extra name on the certificate needs its own record (see Names and certificates).

The name is the Server name setting (engine.hostname), set by the first-boot setup.

The connectivity test

The test checks the server's way out to the internet and finds its public address.

1. Open Server › Network (or Server › Logs & diagnostics).
2. In Connectivity test, press Run the test. It takes up to half a minute.

On the server's screen the same test is under Network and firewall › Test connectivity.

The test looks outward. It does not show whether phones and carriers can reach the server from the internet: test that with a phone outside the office, for example a softphone on a mobile phone without Wi-Fi. If it registers but calls have one-way audio, check Public address, the audio port forward and the router's SIP ALG (see Troubleshooting).