Ubiquiti EdgeOS/UniFi Configuration Guide

This is an original planning guide. It is not a vendor manual, an official standard, or legal advice. Example addresses use documentation ranges. Review every command before you paste it.

Where Ubiquiti EdgeOS and UniFi sits

EdgeOS is a set-and-commit CLI related in spirit to a router CLI, used on EdgeRouter. UniFi is a controller model: the device takes a configuration from a controller, and a local CLI edit can be overwritten or unsupported. This pillar covers both names because the plan groups them, and the operational rule is to know which one you are holding. If there is a controller, the controller is the source of truth. If it is EdgeOS, commit and save are the source of truth.

Do not push a UniFi VLAN from the EdgeOS CLI chapter, and do not expect a controller to notice an EdgeOS commit. Write the product name in the ticket before you write the VLAN id.

Use a lab or the first closet, not the core, for the first week you touch Ubiquiti EdgeOS and UniFi. The change window still needs a ticket, a test host, and the rollback above. Automation comes after you can do the boring change by hand and get back. The automation guide is that sequence. This page is the dialect.

Management belongs on a prefix you named, over SSH or the platform's equivalent, from a jump host. The hardening guide is the standard. This page does not open Telnet, does not permit the world, and does not put a password in the clear for you to copy. If a generator shows a placeholder password, replace it before the device is reachable.

A lab change, one step at a time

Step 1 on Ubiquiti EdgeOS and UniFi is about the hostname. The lab text is: hostname edge-01 EdgeOS is a set-and-commit CLI related in spirit to a router CLI, used on EdgeRouter. UniFi is a controller model: the device takes a configuration from a controller, and a local CLI edit can be overwritten or unsupported. This pillar covers both names because the plan groups them, and the operational rule is to know which one you are holding. If there is a controller, the controller is the source of truth. If it is EdgeOS, commit and save are the source of truth. This is a starter for a switching platform with its own save and interface names. It uses documentation addresses where an address appears, and it uses the token prompt-for-this wherever a secret would go. Replace that token. Do not save a secret from a guide. After the step, check: The prompted hostname matches the ticket.. If the check fails, stop. The way back is: the previous configuration you stored off-box, or the platform's rollback if you practised it. Do not type the next step on top of a failed one. Ubiquiti EdgeOS and UniFi only keeps a change the way its own save model describes: the platform save you practised, not a command borrowed from a neighbour. A neighbouring vendor's save command is not this one. The generators linked from this page draft the same kind of starter in the browser. They do not log in. Read their banner, then read this step, then decide. A line that looks familiar from Cisco IOS is not a reason to paste it into Ubiquiti EdgeOS and UniFi.

Step 2 on Ubiquiti EdgeOS and UniFi is about management. The lab text is: A management address in 192.0.2.10/24 on the platform's management interface, not on a user VLAN. Keep management off the user broadcast domain. This is a starter for a switching platform with its own save and interface names. It uses documentation addresses where an address appears, and it uses the token prompt-for-this wherever a secret would go. Replace that token. Do not save a secret from a guide. After the step, check: Ping the management gateway from a jump host, not from a user port.. If the check fails, stop. The way back is: the previous configuration you stored off-box, or the platform's rollback if you practised it. Do not type the next step on top of a failed one. Ubiquiti EdgeOS and UniFi only keeps a change the way its own save model describes: the platform save you practised, not a command borrowed from a neighbour. A neighbouring vendor's save command is not this one. The generators linked from this page draft the same kind of starter in the browser. They do not log in. Read their banner, then read this step, then decide. A line that looks familiar from Cisco IOS is not a reason to paste it into Ubiquiti EdgeOS and UniFi.

Step 3 on Ubiquiti EdgeOS and UniFi is about SSH only. The lab text is: Enable SSH and do not enable Telnet. Do not push a UniFi VLAN from the EdgeOS CLI chapter, and do not expect a controller to notice an EdgeOS commit. Write the product name in the ticket before you write the VLAN id. This is a starter for a switching platform with its own save and interface names. It uses documentation addresses where an address appears, and it uses the token prompt-for-this wherever a secret would go. Replace that token. Do not save a secret from a guide. After the step, check: Telnet is refused.. If the check fails, stop. The way back is: the previous configuration you stored off-box, or the platform's rollback if you practised it. Do not type the next step on top of a failed one. Ubiquiti EdgeOS and UniFi only keeps a change the way its own save model describes: the platform save you practised, not a command borrowed from a neighbour. A neighbouring vendor's save command is not this one. The generators linked from this page draft the same kind of starter in the browser. They do not log in. Read their banner, then read this step, then decide. A line that looks familiar from Cisco IOS is not a reason to paste it into Ubiquiti EdgeOS and UniFi.

Step 4 on Ubiquiti EdgeOS and UniFi is about one VLAN. The lab text is: Create VLAN 20 named Users before you assign it. The VLAN id is not an IP address. This is a starter for a switching platform with its own save and interface names. It uses documentation addresses where an address appears, and it uses the token prompt-for-this wherever a secret would go. Replace that token. Do not save a secret from a guide. After the step, check: The VLAN exists in the table.. If the check fails, stop. The way back is: the previous configuration you stored off-box, or the platform's rollback if you practised it. Do not type the next step on top of a failed one. Ubiquiti EdgeOS and UniFi only keeps a change the way its own save model describes: the platform save you practised, not a command borrowed from a neighbour. A neighbouring vendor's save command is not this one. The generators linked from this page draft the same kind of starter in the browser. They do not log in. Read their banner, then read this step, then decide. A line that looks familiar from Cisco IOS is not a reason to paste it into Ubiquiti EdgeOS and UniFi.

Step 5 on Ubiquiti EdgeOS and UniFi is about one access port. The lab text is: Put eth1 in VLAN 20 as an access port, with edge or portfast only if it faces a host. The uplink is not an access port and does not get portfast. This is a starter for a switching platform with its own save and interface names. It uses documentation addresses where an address appears, and it uses the token prompt-for-this wherever a secret would go. Replace that token. Do not save a secret from a guide. After the step, check: A test host lands in VLAN 20.. If the check fails, stop. The way back is: the previous configuration you stored off-box, or the platform's rollback if you practised it. Do not type the next step on top of a failed one. Ubiquiti EdgeOS and UniFi only keeps a change the way its own save model describes: the platform save you practised, not a command borrowed from a neighbour. A neighbouring vendor's save command is not this one. The generators linked from this page draft the same kind of starter in the browser. They do not log in. Read their banner, then read this step, then decide. A line that looks familiar from Cisco IOS is not a reason to paste it into Ubiquiti EdgeOS and UniFi.

Step 6 on Ubiquiti EdgeOS and UniFi is about one route. The lab text is: A static route for 203.0.113.0/24 via 192.0.2.1 is a lab route. Remove it before production. Documentation prefixes must not be advertised. This is a starter for a switching platform with its own save and interface names. It uses documentation addresses where an address appears, and it uses the token prompt-for-this wherever a secret would go. Replace that token. Do not save a secret from a guide. After the step, check: The route is present in the lab and absent in production.. If the check fails, stop. The way back is: the previous configuration you stored off-box, or the platform's rollback if you practised it. Do not type the next step on top of a failed one. Ubiquiti EdgeOS and UniFi only keeps a change the way its own save model describes: the platform save you practised, not a command borrowed from a neighbour. A neighbouring vendor's save command is not this one. The generators linked from this page draft the same kind of starter in the browser. They do not log in. Read their banner, then read this step, then decide. A line that looks familiar from Cisco IOS is not a reason to paste it into Ubiquiti EdgeOS and UniFi.

Step 7 on Ubiquiti EdgeOS and UniFi is about the save. The lab text is: Use this platform's save, written on the card. A Cisco write memory typed into the wrong CLI is not a save. This is a starter for a switching platform with its own save and interface names. It uses documentation addresses where an address appears, and it uses the token prompt-for-this wherever a secret would go. Replace that token. Do not save a secret from a guide. After the step, check: After a lab reload the hostname remains.. If the check fails, stop. The way back is: the previous configuration you stored off-box, or the platform's rollback if you practised it. Do not type the next step on top of a failed one. Ubiquiti EdgeOS and UniFi only keeps a change the way its own save model describes: the platform save you practised, not a command borrowed from a neighbour. A neighbouring vendor's save command is not this one. The generators linked from this page draft the same kind of starter in the browser. They do not log in. Read their banner, then read this step, then decide. A line that looks familiar from Cisco IOS is not a reason to paste it into Ubiquiti EdgeOS and UniFi.

# Ubiquiti EdgeOS and UniFi lab shape. Review every line. Replace secrets.
# Interface example: eth1
# VLAN 20 Users, management 192.0.2.10/24, lab route 203.0.113.0/24 via 192.0.2.1
# Remove the lab route before production.

After the lab is boring

When the lab hostname, the management address, one user VLAN, and one route or one policy all behave, write the rollback and the save command on a card next to the console. The on-call will not reread this pillar at 2 a.m. They will read the card. If the card disagrees with this page, fix the card after you confirm which one matches the software version you run. Versions drift. A command that worked on the previous train may be refused or may mean something narrower.

Back up the configuration once you have saved it the platform's way. Keep that backup off the device. A device you can rebuild from a backup is a device you can harden without fear. A device whose only configuration is the running memory is a device people are afraid to secure, so they leave extra services on. The hardening pass comes after the backup exists, not before.

Compare the generator's draft to this lab before you point the generator at a real site. The draft should be smaller than your wish list. A VLAN, a management restriction, and a route are enough for a first production use. A draft that also turns on every feature the form offered is a draft to trim. The diff is the change. The vendor guide is not a reason to apply every example in one window.

Document the software version, the save command, and the out-of-band path in the same inventory line as the hostname. Migrations fail when that line is missing. The migration guide assumes you can still reach the box when the new path is wrong. Ubiquiti EdgeOS and UniFi does not suspend that rule.

Ubiquiti EdgeOS and UniFi checks before the first production save

Confirm this before you call the change done: The lab is not the production core. prompt-for-this was replaced and the secret is not in the ticket. Management is limited to a named prefix. The save command on the card matches Ubiquiti EdgeOS and UniFi, not a different vendor. A backup exists off the device before you harden it. The test host is in the VLAN you built, and a host outside it was not accidentally included. The rollback was used once in the lab. The generator draft was trimmed to the ticket. No route or policy permits the world as a convenience. Documentation prefixes are gone before production cutover. The software version is written next to the hostname. Out-of-band access was tested. A second person read the allowed VLAN or the policy aloud. And telnet and any wide web management stay off. If one of those fails, stop.

Tools for this guide

These tools run in the browser on this site. They do not log into your machines.

Guides in this cluster

These supporting pages belong to this pillar.