oam/knowledge base/turris os.md

Turris OS

Linux distribution based on top of OpenWrt. Check the website for more information.

Table of contents

1. TL;DR
2. LED diodes settings
   1. Automatic overnight dimming
3. Local DNS resolution
4. Static DHCP leases and hostnames
5. Containers
   1. Git server
   2. Pi-hole
6. Hardening ideas
7. The SFP+ caged module
   1. Use the SFP module as a LAN port
8. Further readings
9. Sources

TL;DR

# Show settings.
uci show
uci show 'dhcp'

# Show what interface is the WAN.
uci show network.wan.device | cut -d "'" -f 2

# Configure a static IP address lease.
uci add dhcp host
uci set dhcp.@host[-1].name='hostname'
uci set dhcp.@host[-1].mac='11:22:33:44:55:66'
uci set dhcp.@host[-1].ip='192.168.1.2'

# Show changes to the settings.
uci changes
uci changes 'dhcp'

# Commit changes.
uci commit
uci commit 'dhcp'

# Reload the configuration.
# Necessary to reflect changes to the settings.
reload_config
luci-reload

# Get LEDs intensity.
rainbow brightness -q

# Set LEDs intensity.
# 0 to 8 normally, 0 to 255 using '-p'.
rainbow brightness '5'
rainbow brightness -p '100'

# Manage services.
/etc/init.d/sshd restart

# Gracefully reboot the device.
reboot

# Gracefully shutdown the device.
poweroff

# Create LXC containers.
lxc-create --name 'ubuntu-focal' --template 'download' -- --dist 'Ubuntu' --release 'Focal' --arch 'armv7l' --server 'repo.turris.cz/lxc'
lxc-create … -t 'download' -- --dist 'debian' --release 'bullseye' --arch 'armhf' --server 'images.linuxcontainers.org'

# List snapshots.
schnapps list

# Create snapshots.
schnapps create 'description'
schnapps create -t 'pre' 'description'

# Change snapshots' information.
schnapps modify '4' -t 'time' -d 'new description'

# Rollback to a snapshot.
schnapps rollback '2'

# Delete snapshots by number.
schnapps delete '3'

# Delete snapshots by type.
schnapps delete -t 'post'

LED diodes settings

A permanent change of color can be set in the UCI configuration file /etc/config/rainbow.

The rainbow utility allows one to change the color and set the status of each diode individually. The setting are disable (off), enable (on) or auto; auto leaves the control of the diodes to the hardware, like blinking during data transfer and so on.

rainbow's brightness subcommand uses numbers from 0 to 8, or from 0 to 255 if using the -p switch for higher precision.

Automatic overnight dimming

Should you want to see the state of individual devices during day but not to be dazzled by the diodes in the night, you can automatically adjust the intensity of LEDs using a cronjob.

Create a text file in the /etc/cron.d directory:

# File /etc/cron.d/rainbow_night.
# Set the light intensity to the second lowest degree every day at 11 PM and set
# it back to maximum every day at 7 AM.
MAILTO=""   # avoid automatic logging of the output
0  23  *  *  *  root   rainbow brightness 1
0   7  *  *  *  root   rainbow brightness 5

Local DNS resolution

Turris OS can answer DNS queries for local devices.

Requires the Network Settings > DNS > Enable DHCP clients in DNS option to be enabled.

Static DHCP leases and hostnames

When assigning static DHCP leases LuCI only requires the IP and MAC addresses, while reForis will also:

• require a unique hostname for each entry
• set the lease time to infinite

Setting a hostname in an entry will make Turris OS resolve the IP address only with that given hostname (and not the name the host presents itself with).
Not setting a hostname in an entry will make Turris OS resolve the IP address with the name the host presents itself with.

CLI procedure:

uci add dhcp host
uci set dhcp.@host[-1].name='paracelsus'
uci set dhcp.@host[-1].mac='11:22:33:44:55:66'
uci set dhcp.@host[-1].ip='192.168.1.200'
uci commit 'dhcp'
reload_config
luci-reload

Containers

Some packages are not available in opkg's repository, but containers can be used to provide them.

This requires the lxc package to be installed.

Suggested the use of an expansion disk.

The usual steps are the following, and should be executed in Turris OS:

1. Create a container for the service:

   # Default source is 'repo.turris.cz/lxc'.
   lxc-create --name 'test' --template 'download'
   lxc-create -n 'pi-hole' -t 'download' -- --dist 'debian' --release 'bullseye' --arch 'armhf' --server 'images.linuxcontainers.org'
   

2. Assign it a static IP address:

   uci add dhcp host
   uci set dhcp.@host[-1].name='pi-hole'
   uci set dhcp.@host[-1].mac="$(grep 'hwaddr' '/srv/lxc/pi-hole/config' | sed 's/.*= //')"
   uci set dhcp.@host[-1].ip='192.168.111.2'
   uci commit 'dhcp'
   reload_config
   luci-reload
   

3. Start the container:

   lxc-start --name 'pi-hole'
   
   # Check it's running correctly.
   lxc-info --name 'pi-hole'
   

4. Execute a shell into it:

   lxc-attach --name 'pi-hole'
   

5. Set up the container.

   See examples of specific instructions in the subsections below.

6. Check all is working as expected.

7. If you changed the hostname inside the container, restart it for good measure.

8. Start the container at boot if required:

   vim '/etc/config/lxc-auto'
   

   config container
       option name pi-hole
       option timeout 60
   

Git server

This procedure assumes you are using a LXC container based upon Debian Bullseye.

Follow the usual procedure above and, as the set up the container step, install and configure git from +inside* the container:

# Set the correct hostname, if different from what is expected.
hostnamectl set-hostname 'git'

# Install `git`, the SSH server and `unattended-upgrades`.
DEBIAN_FRONTEND='noninteractive' apt-get install --assume-yes 'git' 'openssh-server' 'unattended-upgrades'

# (Optionally) configure the SSH server.
vim '/etc/ssh/sshd_config'
systemctl restart 'ssh.service'

# Create the git user.
adduser 'git'

# Set up passwordless authentication.
mkdir '/home/git/.ssh' && sudo chmod '700' '/home/git/.ssh'
touch '/home/git/.ssh/authorized_keys' && sudo chmod '600' '/home/git/.ssh/authorized_keys'
echo 'ssh-…' >> '/home/git/.ssh/authorized_keys'

# (Optionally) create the repositories' root directory.
mkdir '/home/git/repositories'

# Make sure the 'git' user has the correct permissions on the folders.
chown -R 'git' '/home/git'

# (Optionally) lock down the git user.
# This will *prevent* clients to set their SSH key using `ssh-copy-id`.
chsh 'git' -s "$(which 'git-shell')"

# All done!
exit

Pi-hole

This procedure assumes you are using a LXC container based upon Debian Bullseye.

See Installing pi-hole on Turris Omnia, Install Pi-hole and Pi-Hole on Turris Omnia for details.

Choose one of Pi-hole's supported operating systems, then follow the usual procedure above and, as the set up the container step, install and configure pi-hole from +inside* the container:

# Set the correct hostname, if different from what is expected.
hostnamectl set-hostname 'pi-hole'

# Install pi-hole.
DEBIAN_FRONTEND='noninteractive' apt-get install --assume-yes 'ca-certificates' 'curl'
curl -sSL 'https://install.pi-hole.net' | bash

# Follow the guided procedure.

# Change the Web interface password, if needed.
/etc/.pihole/pihole -a -p

# Update pi-hole as a whole, if needed.
/etc/.pihole/pihole -up

After this, finish the procedure above. Then, in Turris OS:

# Distribute pi-hole as the primary DNS.
# Keep the router as secondary.
uci set dhcp.lan.dhcp_option='6,192.168.111.2,192.168.111.1'

# The dns server address in the IPv6 RA should be the container's ULA address
# since the global routable IPv6 address tend to change daily.
uci add_list dhcp.lan.dns="$(lxc-info --name pi-hole | grep -E 'IP.* f[cd]' | sed 's/IP: *//')"

# Apply the new configuration.
uci commit 'dhcp' && reload_config && luci-reload
/etc/init.d/odhcpd restart
/etc/init.d/dnsmasq restart

Hardening ideas

• SSH:
  • Change the SSH port from the default 22 value.
  • Restrict login to specific IP addresses.

The SFP+ caged module

List of supported SFP modules.

The physical WAN port and the SFP module cage are wired to a single controller; when a SFP module is inserted, the physical WAN port will be disabled, and the virtual WAN interface will automatically be switched to the SFP module.

When the OS is installed, it will probably miss the SFP kernel modules.
Check the module is recognized by the system like so:

1. Insert the module in the cage.

2. Check the module has been recognized automatically:

   dmesg | grep 'sfp'
   

3. If the grep returned results:

   [   7.823007] sfp sfp: Host maximum power 3.0W
   [   8.167128] sfp sfp: Turris  RTSFP-10G  rev A  sn 1234567890  dc 123456
   

   the SFP module is recognized and probably started working already right away.
   If, instead, no result has been returned:

   1. Make sure the SFP kernel modules are installed:

      opkg install 'kmod-spf'
      

   2. Reboot (for safety).

   3. Check the module has been recognized (see point 2 in this list).

Use the SFP module as a LAN port

To use the SFP module as a LAN port, assign any other physical switch port to the virtual WAN interface to use that as the WAN connection and the SFP module in the LAN.

In the Foris web interface:

1. Go to Network Settings > Interfaces.
2. Select the WAN interface.
3. In the dropdown Network menu, change WAN to LAN.
4. Select the LAN4 interface.
5. In the dropdown Network menu, change LAN to WAN.
6. Hit Save.

In the LuCI web interface:

1. Go to Network > Interfaces.
2. In the Interfaces tab, edit the WAN interface and assign the lan4 port to it.
3. In the Devices tab, edit the br-lan bridge device to include the port used by the SFP module (on mine, it was eth2).
4. Hit Save & Apply.

Using the CLI (yet to be tested):

uci set network.wan.device='lan4'
uci del_list network.br_lan.ports='lan4'
uci add_list network.br_lan.ports='eth2'
uci commit 'network'
reload_config
luci-reload

Further readings

• Website
• Turris' official documentation
• Turris' wiki
• How to control LED diodes
• Factory reset on Turris Omnia
• Supported SFP modules
• opkg
• uci
• Home NAS

Sources

All the references in the further readings section, plus the following:

• Install Pi-hole
• Pi-Hole on Turris Omnia
• Installing pi-hole on Turris Omnia