Network boot of Turris MOX
This article will guide you through setting up your Turris MOX as an AP attached to another Turris router.
On the controlling router, you need to install Turris MOX network boot package list from the Updater tab. This will provide everything necessary to boot up your MOX and a new tab in Foris user interface Managed Devices → Netboot to control them easily.
It will also set up everything needed to boot MOXes over the network - enables TFTP in Dnsmasq, downloads the latest image, generate keys and prepare everything.
If you would like to boot Turris MOX from Turris 1.0/1.1,
you will need to have
srv mounted by Storage plugin in Foris
or boot from microSD card.
Pairing MOX with other Turris router
To pair your MOX with controlling router, connect them directly by Ethernet cable and make sure that there is no micro SD card in MOX. Power it on and wait for incoming request to show up in Foris web interface. You might need to refresh your browser. Once you see a pairing request, verify that the serial number matches the one on MOX and accept the pairing request. When it is done, MOX will boot up and save the pairing information. From then on, it will always try to boot from the network and from the specific controlling Turris router.
When it boots up, it will use a random channel but the same SSID and password as the controlling router and bridge the WiFi to the local network. If you want to customize the setup, see the Advance configuration section and Under the hood -> Other customization part of this article. Fully booted up MOX will blink with it’s led in heartbeat pattern (two fast blinks followed by a longer pause).
Make sure you have your region set up correctly on the router you are booting from. It affects what region you are in and thus available channels.
Apart from using Foris UI, you can also use
netboot-manager script on
your controlling router. The most important operation is pairing your MOX. When
MOX starts booting, it sends pairing request, you can list the state of pairing
netboot-manager list command and you can accept any of the
Incoming requests by typing
netboot-manager accept $serial. If
troubleshooting, an interesting command might also be
netboot-manager regen -f
which recreates all generated files and redownloads latest image.
To use MOX in standalone mode or to pair it with a different router, simply use factory reset, which will reset U-boot settings.
MOX automatically uses the first SSID and password from your WiFi configuration. It will also integrate into Foris and thus allow you to get information about the connected routers and change their configuration.
There is also configuration file
/etc/config/netboot on the controlling router that can
be used to customize mainly the WiFi settings.
# Defaults to be overridden later config wifi default option ssid '@@SSID@@' option key '@@KEY@@' # WiFi specific settings # 02df_9141 is MOX SDIO WiFi # 168c_003c is WLE900VX - 5GHz AC PCIe WiFi card in Turris MOX and Turris Omnia config device 168c_003c option channel 'auto5' config device 02df_9141 option channel 'auto24' # AP-WiFi relations config device 0000000000000007 option network 'default' # AP-WiFi specific overrides - format serial_WiFi config device 0000000000000007_168c_003c option channel '40' option ssid '@@SSID@@-5' option key '@@KEY@@-5' option htmode 'VHT40'
Let’s start by explaining some special values
@@SSID@@means SSID of your first configured WiFi on the controlling router
@@KEY@@means key of your first configured WiFi on the controlling router
@@COUNTRY@@means country you have set for your WiFi on the controlling router
auto24means random channel on 2.4GHz WiFi
auto5means random channel on 5GHz WiFi
Now how the configuration file works. You can specify some named networks with some parameters. For example:
config wifi home option ssid 'homenet' option key 'home_sweet_home'
Special name for a defined network is
default. That one is assigned to every
device unless overridden.
You can reference this network later on and specify that for example device
with the serial number
0000000000000007 should use those settings.
# AP-WiFi relations config device 0000000000000007 option network 'home'
By default, we set random 2.4GHz channel on SDIO WiFi in MOX and random 5GHz channel on the PCIe card. That is done via the following part:
# 02df_9141 is MOX SDIO WiFi config device 168c_003c option channel 'auto5' # 168c_003c is WLE900VX - 5GHz AC PCIe WiFi card in Turris MOX and Turris Omnia config device 02df_9141 option channel 'auto24'
But if you have just one WiFi card in Turris MOX and you want to run 5 GHz on it, you can override the defaults for that specific serial number in the following way
# AP-WiFi specific overrides - format serial_WiFi config device 0000000000000007_168c_003c option channel 'auto5'
Under the hood
How it works
Booting and pairing
MOX tries to boot from various sources and the last of them is PXE. Netboot sets up your controlling router to provide PXE configuration for MOX and provides it with kernel and ramdisk.
That ramdisk boots up, generates ssh keys and uses the key provided via kernel boot parameters to send that key over ssh to controlling router. It uses highly restricted account that can do just that - send a little bit of information about itself and try to get something back. Nothing more. Then it waits for pairing to be completed by trying to use it’s key to get access to more advanced API.
On the controlling router, when accepting key you will authorize provided ssh key to access more advanced functions - like download rootfs and configuration. Pairing process will also generate more keys, one aes and one certification authority to be used by Foris.
Once authorized, MOX will download the aes key and save it together with generated and now authorized ssh key to NOR memory. It will also overwrite U-Boot environment to enforce network boot by default. Not generic PXE boot, but booting specific image named after the serial number of the MOX and encrypted by aes key. On next boot, it will try to download only specific kernel and boot it only if it will be encrypted using the saved aes key.
When pairing is done, MOX will setup background job that will check the rootfs and configuration version from the controlling router and reboot the MOX if version changes or controlling router becomes inaccessible.
The last step is downloading rootfs into RAM and running the system from it. It is
a little bit customized by replacing
rc.local with setup script mentioned
You can add files to your MOX by putting them in
/srv/turris-netboot/rootfs/overlay directory in either
subdirectory (this will get included on every MOX) or in a subdirectory named
after serial number of the MOX (those files will be included only on specific
You can also customize the behavior of the resulting system by deploying custom
scripts that are run when the system boots up. There are a few scripts that can be
used and all of them resides in
You can use this script to replace our setup script that configures SSID and password and sets up the network. Only when you really know what you are doing.
This one gets run on every MOX after network setup is done and can be used to deploy some custom services.
The script that gets run after network setup but only on MOX with specific serial number.