User Tools

Site Tools


Turris MOX: network boot

This article will guide you through setting up your Turris MOX as an AP attached to another Turris router.

Necessary software

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 DevicesNetboot to control them easilly.

Pairing MOX with Omnia

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 in Foris. You might need to refresh your browser. Once you see a pairing request, verify that the serial matches and accept the pairing request. Once done, MOX will boot up and save the pairing information. From then on, it will always try to boot from the network and from 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 Under the hood part. 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 WebUI, you can also use netboot-manager script on your Omnia. The most important operation is pairing your MOX. When MOX starts booting, it sends pairing request, you can list the state of pairing by issuing netboot-manager list command and you can accept any of the Incoming requests by typing netboot-manager accept $serial.

Cancel pairing

To use MOX in standalone mode or to pair it with a different router, simply use factory reset.

Under the hood

MOX automatically uses the first SSID and password from your WiFi configuration. You can customize quite some options regarding network booted image.

To have Netboot integrated in Foris web interface, you need to have your Foris switched to mqtt bus. This should happen automatically when you install the corresponding software, but you can do it also manually (if coming from medkit or you got stuck with old config because of some other reason).

uci set foris-ws.main.bus=mqtt
uci set foris-controller.main.bus=mqtt
uci commit
/etc/init.d/foris-controller restart
/etc/init.d/foris-ws restart
/etc/init.d/lighttpd restart

Overlay

You can inject additional files to your MOX by putting them into /srv/turris-netboot/rootfs/overlay directory in either common subdirectory (this will get included on every MOX) or in subdirectory named after serial number of the MOX (those files will be included only on specific MOX).

Setup scripts

You can also customize the behavior of the resulting system by deploying custom scripts that are run when system boots up. There are few scripts that can be used and all of them resides in /srv/turris-netboot/rootfs directory.

setup.sh

You can use this script to replace our setup script that configures SSID and password and set's up the network. Only when you really know what you are doing.

postsetup.sh

This one gets run on every MOX after network setup is done and can be used to deploy some some custom services.

postsetup-$SERIAL.sh

Script that gets run after network setup but only on MOX with specific serial number.

Advance configuration

There is also configuration file /etc/config/netboot on your Omnia that can be used to customize mainly the WiFi settings.

# Defaults to be overriden 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 MOX and 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 your Omnia
  • @@KEY@@ means key of your first configured WiFi on your Omnia
  • @@COUNTRY@@ means country you have set for your WiFi on your Omnia
  • auto24 means random channel on 2.4GHz WiFi
  • auto5 means 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 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 MOX and Omnia
config device 02df_9141
        option channel 'auto24'

But if you have one Pocket WiFi that you want to run on 5GHz, you can override the defaults for that specific serial number in following way

# AP-WiFi specific overrides - format serial_WiFi
config device 0000000000000007_168c_003c
        option channel 'auto5'