Install a site connector (Airgate Edge)
A site connector (Airgate Edge) is a small service at a site that relays the site’s network traffic to Airgate. Use it when the site’s switches and access points cannot reach Airgate directly (private addresses behind NAT, no RadSec support), when Airgate must send Change of Authorization to them, or when you check Active Directory passwords with PEAP-MSCHAPv2. At the end of this guide the connector shows Online under Network › Sites and the site’s devices authenticate through it.
What a connector relays
Section titled “What a connector relays” Site LAN Airgate (Cloud or appliance) ┌───────────────────────────┐ outbound ┌───────────────────────────┐ │ switches / APs │ only │ │ │ RADIUS UDP 1812/1813 ─┐ │ │ │ │ TACACS+ TCP 49 ───────┤ │ RadSec │ RADIUS / EAP │ │ DHCP helper UDP 67 ───┤ │ TCP 2083 ──►│ │ │ CoA UDP 3799 ◄────────┤ │ │ │ │ Airgate Edge HTTPS 443 ►│ console API, tunnels, │ │ domain controllers ◄──┘ │ │ CoA and ntlm_auth jobs │ └───────────────────────────┘ └───────────────────────────┘| Traffic | What the connector does |
|---|---|
| RADIUS (UDP 1812 authentication, 1813 accounting) | Receives it from the site’s devices and forwards it to Airgate over RadSec (TLS on TCP 2083, with its own client certificate) or, when TCP 2083 is blocked, through an HTTPS tunnel. Each request carries the original device address, so policies, the Sign-in log and device groups see the real switch or access point |
| CoA and Disconnect (UDP 3799) | Long-polls Airgate for Change of Authorization jobs, sends them to the device and returns the answer |
| TACACS+ (TCP 49) | Tunnels device-administration sessions to Airgate’s TACACS+ service over HTTPS |
| DHCP (UDP 67) | As an extra DHCP helper address it reads DHCP fingerprints for device profiling. It never answers DHCP |
| Active Directory password checks | When joined to the domain, it runs ntlm_auth for PEAP-MSCHAPv2 and MS-CHAP sign-ins of Active Directory users, because Active Directory never gives out password hashes |
| Offline MAC authentication | It remembers Airgate’s MAB accepts and answers known devices itself when Airgate cannot be reached |
The connector only opens outbound connections. You need no inbound firewall rule at the site.
Before you begin
Section titled “Before you begin”- The policy:write permission (for example Network Administrator or Tenant Administrator).
- A host on the site LAN that the site’s devices can reach, with a static IP address. Either:
- the Airgate Edge appliance
airgate-edge-<version>.ovafor VMware ESXi or vCenter 6.7 or later: 2 vCPU, 2 GB RAM, 16 GB disk (thin); or - a Linux host of your own with systemd, the
nac-edgeprogram and itsnac-edge.serviceunit.
- the Airgate Edge appliance
- Outbound from that host:
- TCP 443 to the Airgate console address;
- TCP 2083 to Airgate for RadSec (recommended). Without it, RADIUS goes through the HTTPS tunnel.
- The console’s name must resolve from the site. The enrollment checks the console’s HTTPS certificate for that name.
- The connector must trust the console’s HTTPS certificate. A certificate from a public CA works as is. If your appliance’s console certificate is issued by its own root, either install a public certificate (Console access and certificates) or, on your own Linux host, give the root to
nac-edge enroll --api-ca <file.pem>. - For Active Directory password checks: DNS servers that find the domain controllers, the domain’s realm and NetBIOS name, and an account allowed to join computers to the domain.
Step 1: Create the site in the console
Section titled “Step 1: Create the site in the console”-
Go to Network › Sites and select Add site.
-
Enter a Name, for example
Branch-12, unique in the tenant. Optionally add Sites (locations served) and a Description. -
Under RADIUS transport to the cloud, choose:
Option Behaviour Auto (recommended) RadSec (TLS, TCP 2083) when the connector holds a certificate, otherwise the HTTPS tunnel RadSec Same as Auto, but the connector logs a warning while it has no RadSec certificate HTTPS tunnel Always relay RADIUS over HTTPS. For sites that cannot reach TCP 2083 -
Under Services, leave Enabled on, and turn DHCP fingerprinting and TACACS+ tunnel on or off.
-
Under Enrollment, leave Issue a one-time enrollment token now on and choose how long it is valid (1 hour to 30 days).
-
Save. The Install window shows the enrollment token (
et_…) and the commands.
Step 2a: Deploy the Airgate Edge appliance
Section titled “Step 2a: Deploy the Airgate Edge appliance”Skip to Step 2b if you use your own Linux host.
-
Deploy
airgate-edge-<version>.ovawith Deploy OVF Template, as for the Airgate appliance. Map its network adapter to the site LAN. -
Power it on and open the VM console. The setup wizard asks:
Question What to enter Network: dhcp or static, IP address, gateway, DNS As for the Airgate appliance; staticis recommendedHost name For example edge-branch12oredge-branch12.contoso.comNTP servers Optional; Active Directory needs the right time Airgate console address For example https://nac.contoso.com; empty to enroll laterIP address of the console Only when site DNS cannot resolve the console’s name; the wizard then adds a hosts entry Enrollment token The et_…token; empty to enroll laterJoin Active Directory for AD password checks (PEAP-MSCHAPv2)? yto join now: AD realm (for exampleCORP.CONTOSO.COM), NetBIOS domain (for exampleCORP), join account and its passwordAppliance login password for user airgate At least 12 characters; for the VM console and SSH
When enrollment succeeds, the connector starts at once.
Step 2b: Install on your own Linux host
Section titled “Step 2b: Install on your own Linux host”On a Linux host with systemd, as root:
install -m 0755 nac-edge /usr/local/bin/nac-edgeuseradd --system --home /etc/nac-edge --shell /usr/sbin/nologin nac-edgeinstall -d -o nac-edge -g nac-edge -m 0700 /etc/nac-edgesudo -u nac-edge nac-edge enroll --url https://nac.contoso.com --token et_… --config /etc/nac-edge/edge.jsoninstall -m 0644 nac-edge.service /etc/systemd/system/ && systemctl enable --now nac-edgenac-edge statusThe Install window in the console builds the same nac-edge enroll command for you, with these options:
| Option | Meaning |
|---|---|
Tunnel only (--no-certificate) |
Enroll without a RadSec certificate. RADIUS always uses the HTTPS tunnel and never upgrades to RadSec |
| Pass token via environment | Read the token from NAC_EDGE_TOKEN instead of the command line |
Hostname override (--hostname) |
The name the connector reports (default: the system host name) |
Other nac-edge enroll flags: --api-ca <file.pem> (extra CA certificates to trust for the console), and --radius-auth, --radius-acct, --dhcp, --tacacs to change a listener address ("" turns it off; defaults :1812, :1813, :67, :49).
Enrollment writes /etc/nac-edge/edge.json, the API token, and in certificate mode the RadSec key, certificate and CA, all readable only by the nac-edge user. The systemd unit runs the connector as that unprivileged user with only the capabilities to bind ports below 1024 and to capture packets.
To run the connector in a container with Active Directory support, the deployment includes a nac-edge image with Samba winbind: it enrolls from NAC_URL and NAC_EDGE_TOKEN, joins the domain from AD_REALM, AD_NETBIOS_DOMAIN, AD_JOIN_USER and AD_JOIN_PASSWORD, and must use host networking to receive the site’s traffic.
Step 3: Assign network devices to the connector
Section titled “Step 3: Assign network devices to the connector”- In Network › Switches and APs, open each device at the site and set its Site connector (or use the connector’s NADs tab).
- Enter the device’s IP address or subnet and its RADIUS shared secret as usual. The connector matches incoming packets by source address against the devices assigned to it.
A connector serves only the enabled devices assigned to it, and only devices of its own tenant.
Step 4: Point the devices at the connector
Section titled “Step 4: Point the devices at the connector”On each switch, access point or controller at the site, use the connector’s LAN address:
| Setting on the device | Value |
|---|---|
| RADIUS authentication and accounting server | Connector address, UDP 1812 / 1813, the device’s shared secret |
| Dynamic authorization (CoA) client | Connector address, the same shared secret |
| TACACS+ server | Connector address, TCP 49, the device’s TACACS+ secret |
DHCP helper (ip helper-address) |
Connector address, in addition to the real DHCP server |
Step 5: Join Active Directory (optional)
Section titled “Step 5: Join Active Directory (optional)”To check Active Directory passwords for PEAP-MSCHAPv2 and MS-CHAP, the connector must be joined to the domain:
- Edge appliance: answer
yto Join Active Directory insudo airgate-edge-setup. - Your own host: install Samba winbind and
ntlm_auth, join the domain, and make surewbinfo -tsucceeds.
The connector checks every minute that the join works (wbinfo -t) and that ntlm_auth is installed, and reports ad_joined and the domain to Airgate. When Airgate needs to check an Active Directory password, it sends the check to an online, domain-joined connector of the tenant: first the one the request came through, otherwise the most recently seen. The challenge and response are deleted as soon as the check ends.
See Active Directory with PEAP-MSCHAPv2.
Offline MAC authentication
Section titled “Offline MAC authentication”The connector remembers each MAB accept that Airgate sends (per device, MAC address and SSID) and drops the entry when Airgate rejects the device. When Airgate cannot be reached, it answers known MAB devices from that cache with a Session-Timeout of 1800 seconds, so they check again soon after the link returns. A known device never waits more than 3 seconds for Airgate. Unknown devices and 802.1X sign-ins get no answer during an outage.
The cache is kept for 24 hours by default (offline_cache in edge.json, a duration such as 24h, or "off"). It is stored next to the configuration, readable only by the connector, because it can hold guest pre-shared keys.
Verify
Section titled “Verify”- Network › Sites shows the connector as Online within a minute (it sends a heartbeat every 30 seconds), with its version, host name and transport.
- On the connector:
sudo nac-edge statusshows the configuration, the RadSec certificate (subject, serial, expiry) and the cached cloud configuration. - Connect a device at the site. The sign-in appears in Monitor › Sign-in log with the site’s switch or access point as the network device.
- For CoA, select Reauthenticate on a session in Monitor › Connected now; the connector’s jobs show the result.
Replace or re-enroll a connector
Section titled “Replace or re-enroll a connector”To replace the host, open the connector and issue a new enrollment token, then enroll the new host with it. The old credentials keep working until the new token is redeemed. Then the old RadSec certificate is revoked and TACACS+ tunnels opened with the old credentials are closed.
Revoke credentials drops a connector’s credentials at once. Disable refuses its API calls, RadSec connections, relayed RADIUS, CoA and TACACS+ immediately. Delete revokes its certificate, deletes pending CoA jobs and detaches its devices.
The connector renews its RadSec certificate by itself when Airgate asks it to.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause | Fix |
|---|---|---|
| Enrollment fails with a certificate error | The connector does not trust the console’s HTTPS certificate, or the name does not match | Use a public certificate on the console, or --api-ca with the issuing root; make sure the console address matches the certificate name |
| Enrollment fails: token invalid | Token expired, already used, or replaced by a newer one | Issue a new token on the connector |
| Connector stays Offline | No outbound HTTPS to the console, or the service is stopped | sudo journalctl -u nac-edge -f; check the firewall and DNS |
| Status shows HTTPS tunnel instead of RadSec | TCP 2083 blocked, transport set to HTTPS tunnel, or enrolled with --no-certificate |
Open TCP 2083, set Auto, re-enroll without --no-certificate |
| Requests from a switch are ignored | The switch is not assigned to this connector, is disabled, or its address does not match | Assign it in Network › Switches and APs with the address the connector sees |
| A wrong shared secret is reported | The switch’s secret differs from the one in Airgate | Monitor › Alerts and events shows the device; fix the secret on either side |
| PEAP-MSCHAPv2 for Active Directory users is rejected | No online domain-joined connector | sudo net ads testjoin and wbinfo -t on the connector; join again |
| Packet capture on the connector stays running then fails | The connector lacks the packet-capture capability, or is an old version | Update the connector and install the current nac-edge.service unit, then systemctl daemon-reload && systemctl restart nac-edge |