diff options
| -rw-r--r-- | 2026-05-19-ubnt-setup.txt | 172 |
1 files changed, 172 insertions, 0 deletions
diff --git a/2026-05-19-ubnt-setup.txt b/2026-05-19-ubnt-setup.txt new file mode 100644 index 0000000..0ca5ede --- /dev/null +++ b/2026-05-19-ubnt-setup.txt @@ -0,0 +1,172 @@ +I've used both China Unicom and China Telecom in the past, and both use +the PPPoE protocol to authenticate Internet connections. The first thing +I do after deploying the network is configure the ONT (Optical Network +Terminal) into bridge mode. I want the device to have the single +responsibility of translating rapid pulses of light from the fiber optic +cable into electrical signals, while a dedicated router handles DHCP and +gives me more control over the internal network. + +That brings us to my Ubiquiti EdgeRouter X (ER-X-SFP), a small, +lightweight, power-efficient (5W) Linux box based on the MIPS +architecture. I've installed it inside the structured media enclosure, +and it has been running fairly stably. Overall, I am pretty satisfied +with the device. + +There are two modes in EdgeOS—the operating system running on the +hardware: operational mode and configuration mode. When you SSH into the +system, you are in operational mode by default, which can be identified +by the dollar sign `$`. To switch to configuration mode, use the +`configure` command. Configuration mode can be identified by the hashtag +`#`. To leave configuration mode and return to operational mode, use the +`exit` command. + + user@ubnt:~$ configure + + [edit] + user@ubnt:# + + +Convention +---------- + +The commands shown in this article are prefixed with either operational +mode or configuration mode so that you can easily identify which mode +the command should be executed in. + +Whenever you want to apply changes made to the router, use the `commit` +command. After confirming everything works as expected, you can persist +the changes with the `save` command, which writes the configuration to a +file. + + # commit + # save + +I am currently running firmware version `v2.0.9-hotfix.7`. You can check +your version with: + + $ show version + + +Set up the Internet connection +------------------------------ + +Assuming we already have the credentials on hand, we can configure the +PPPoE connection on the `eth0` interface in configuration mode. Replace +the username and password placeholders with your actual credentials. + + # edit interfaces ethernet eth0 + # set description "Internet (PPPoE)" + # set pppoe 0 user-id <PPPoE Username> + # set pppoe 0 password <PPPoE Password> + +Once the connection is established, we can check the IP addresses +allocated by the ISP. + + $ show interfaces + +The following commands are handy when you want to reconnect to the +Internet manually, especially since some ISPs forcefully terminate +connections every seven days. By reconnecting during your own chosen +hours, you can avoid unexpected interruptions during something critical, +such as debugging a production issue. + + $ disconnect interface pppoe0 + $ connect interface pppoe0 + + +Assign a CIDR block to the LAN +------------------------------ + +You may want to customize your local network using the CIDR block +`192.168.10.0/24`. In this subnet, `192.168.10.0` is the network address +and `192.168.10.255` is the broadcast address, leaving `192.168.10.1` +through `192.168.10.254` as usable host addresses. + +However, not all usable addresses need to be assigned dynamically by +DHCP. In my setup, I reserve `192.168.10.1` for the router itself and +configure the DHCP pool to allocate addresses only from `192.168.10.100` +to `192.168.10.199`. The remaining addresses stay available for manually +assigned devices or future network expansion. Feel free to adjust the +subnet to suit your needs. + + # set service dhcp-server shared-network-name LAN subnet 192.168.10.0/24 default-router 192.168.10.1 + # set service dhcp-server shared-network-name LAN subnet 192.168.10.0/24 dns-server 192.168.10.1 + # set service dhcp-server shared-network-name LAN subnet 192.168.10.0/24 start 192.168.10.100 stop 192.168.10.199 + # set interfaces switch switch0 address 192.168.10.1/24 + +You can always inspect DHCP leases with the following commands: + + $ show dhcp leases + $ show dhcp leases pool LAN + +If you want static DHCP bindings, all you need is the desired IP address +and the device's MAC address. Here, I bind my Raspberry Pi to +`192.168.10.2`. `pi` is simply a descriptive name for the mapping. + + # set service dhcp-server shared-network-name LAN subnet 192.168.10.0/24 static-mapping pi ip-address 192.168.10.2 + # set service dhcp-server shared-network-name LAN subnet 192.168.10.0/24 static-mapping pi mac-address 01:23:45:ab:cd + +One more thing worth mentioning is the `switch-port` setting, which +defines which physical Ethernet ports belong to the `switch0` interface. +Ports assigned to the switch share the same Layer 2 broadcast domain, +meaning devices connected to those ports are part of the same LAN. + +I have another purpose for the `eth1` port, so I removed it from the +switch: + + # delete interfaces switch switch0 switch-port interface eth1 + + +Hardware offloading +------------------- + +The EdgeRouter X includes dedicated hardware acceleration for NAT and +routing, so enabling hardware offloading allows the device to make full +use of its capabilities. + +According to the official documentation, enabling hardware offloading +increases IPv4 routing throughput from roughly 300 Mbps to around 950 +Mbps—more than a 3x improvement. + + # set system offload hwnat enable + # set system offload ipsec enable + + +Disable the Web GUI +------------------- + +I enjoy managing my home network through the terminal, and I rarely use +the Web GUI, so disabling it does not affect my workflow. Once the +router is configured, there is usually little need to change the +settings anyway. It may also reduce memory usage slightly. + + # delete service gui + + +Backup and restore +------------------ + +We have a `save` command for backing up the configuration, but +unfortunately it is broken in my current firmware version. That is not a +big deal since it uses `scp` underneath, and we can simply do it +manually instead. Don't forget to configure SSH keys beforehand. The +backup filename below includes a datetime suffix. + + $ scp /config/config.boot <user>@<host>:/path/to/config.boot.$(date +%Y%m%d%H%M%S) + +To restore from a backup, use the `load` command. Compare the changes +against the current configuration before applying them. Once everything +looks correct, commit and save the configuration permanently. + + # load scp://<user>@<host>:/path/to/config.boot + # compare + + +Useful links +------------ + +Help Center — EdgeRouter +https://help.ui.com/hc/en-us/sections/360008075214-EdgeRouter + +EdgeRouter X Datasheet +https://dl.ubnt.com/datasheets/edgemax/EdgeRouter_X_DS.pdf |