Setup¶

This chapter walks through the basic setup of your router running RouterKit OS. RKOS is already installed on the routers, so you can start with the initial configuration right away.

Access your router¶

At first you have to establish a serial connection to your router in order to configure it to enable SSH access.

Depending on your router model, you either have a RJ45 port labeled COM, a mini or a micro USB console port. Use one of these ports to access the serial console of the router. You should now see a new serial device (e.g. /dev/ttyUSB0 on Linux systems or COM3 Windows). The USB console ports of some router models may only become available when the device is powered on, so don't panic if it's missing.

Now plug in the power cable and power on your router. Some routers will automatically power on if power is provided, so check for a status light.

You can now connect to the router using your favorite serial terminal program with the following settings:

Speed	Data bits	Parity	Stop bits	Flow control
115,200	8	None	1	no

rtr-pod0-1:~$ screen /dev/ttyUSB0 115200
[...]

   ____             _            _  ___ _
  |  _ \ ___  _   _| |_ ___ _ __| |/ (_) |_
  | |_) / _ \| | | | __/ _ \ '__| ' /| | __|
  |  _ < (_) | |_| | ||  __/ |  | . \| | |_
  |_| \_\___/ \__,_|\__\___|_|  |_|\_\_|\__|

   RKOS 0.1 / Linux 6.18.15-0-lts / x86_64

localhost login:     

Congratulations if you're seeing the login prompt! If you're seeing nothing or garbage output, then check your cabling and that you're using the correct serial port (settings). Feel free to reach out for help.

You can now log in with root.

Configuring RouterKit OS¶

The basic configuration of an Alpine Linux based system is pretty easy using setup-alpine.

We will walk through all steps of setup-alpine, now. At first, run the command.

Hostname¶

To keep everything consistent, please use the following scheme: rtr-podX-Y. The first router of Pod #1 should be named rtr-pod1-1.

 Hostname
----------
Enter system hostname (fully qualified form, e.g. 'foo.example.org') [localhost] rtr-pod0-1

Interface¶

Now, we will not configure our network, since we will be using IfState later on. Enter done for the first question and just press enter for the following ones.

 Interface
-----------
Available interfaces are: eth0 eth1 eth2 eth3.
Enter '?' for help on bridges, bonding and vlans.
Which one do you want to initialize? (or '?' or 'done') [eth0] done
Do you want to do any manual network configuration? (y/n) [n] 
DNS domain name? (e.g 'bar.com') 
DNS nameserver(s)? 

Root Password¶

Please set the password as specified on the blackboard. As you're typing, you won't get any feedback on the console.

 Root Password
---------------
Changing password for root
New password: 
Retype password: 
passwd: password for root changed by root

Timezone, Proxy and Network Time Protocol¶

Just press enter to use the default values (UTC, none and busybox).

You will see some errors when the router tries to set the time using NTP. This is expected, since we're not connected to the Internet yet.

APK Mirror¶

Type in skip in order to use the local packages repository, only. When setting up a router there is no connectivity yet, so everything needs to be available locally. Explicitly setting skip tells Alpine to only use the preconfigured local path (i.e. /media/sda1/apks) to get packages instead of trying to download them from the internet.

 APK Mirror
------------
wget: bad address 'mirrors.alpinelinux.org'
wget: bad address 'mirrors.alpinelinux.org'
 (f)    Find and use fastest mirror
 (s)    Show mirrorlist
 (r)    Use random mirror
 (e)    Edit /etc/apk/repositories with text editor
 (c)    Community repo enable
 (skip) Skip setting up apk repositories

Enter mirror number or URL: skip

User¶

Setup a user named rkos which will be used for remote login. Please also use the password as specified on the blackboard and accept the default values for all other options.

This user can be used to connect using SSH later on. To gain root privileges, you can use doas -s.

 User
------
Setup a user? (enter a lower-case loginname, or 'no') [no] rkos
Full name for user rkos [rkos] 
Changing password for rkos
New password: 
Bad password: too weak
Retype password: 
passwd: password for rkos changed by root
Enter ssh key or URL for rkos (or 'none') [none] 
(1/1) Installing doas (6.8.2-r8)
Executing busybox-1.37.0-r30.trigger
OK: 10.5 MiB in 29 packages
Which ssh server? ('openssh', 'dropbear' or 'none') [openssh] 
 * service sshd added to runlevel default
 * Caching service dependencies ...
 [ ok ]
ssh-keygen: generating new host keys: RSA ECDSA ED25519 
 * Starting sshd ...
 [ ok ]

Disk & Install¶

We're almost done! Now we specify where the persistent configurations and packages should be stored. If you're seeing something containing sda1 for the default values, just use them. Otherwise, please reach out for help.

 Disk & Install
----------------
No disks available. Try boot media /media/sda1? (y/n) [n] 
Enter where to store configs ('floppy', 'sda1', 'usb' or 'none') [sda1] 
Enter apk cache directory (or '?' or 'none') [/media/sda1/cache] 

Installing base packages¶

You can now install a text editor like nano or vim (not just the busybox versions). Packages can be installed with the apk add … and removed with the apk del … commands.

rtr-pod0-1:~# apk add nano
(1/1) Installing nano (8.7-r0)
Executing busybox-1.37.0-r30.trigger
OK: 72.8 MiB in 130 packages

We should now see the requested packages in /etc/apk/world. There should be other packages like openssh as well, which were installed by setup-alpine.

rtr-pod0-1:~$ cat /etc/apk/world 
alpine-base
busybox-mdev-openrc
doas
nano
openssh
openssl
util-linux

Committing changes¶

As already stated at the beginning, our changes do not automatically persist. This behavior is intentional for building routers as they do not keep any persistant data. Like most networking devices you can just reboot the router, even by calling your grandma turning it off and on again, to restore a working configuration. But you need to mind to commit your changes before rebooting or an unexpected power outage occurs.

Alpine local backup is used to save your changes with the lbu commit command. The lbu status and the lbu diff command can be used to check for pending changes before and after calling lbu commit.

Now it's time to cross your fingers and reboot using the command reboot! After a few moments, you should be greeted by your previously set hostname.

   ____             _            _  ___ _
  |  _ \ ___  _   _| |_ ___ _ __| |/ (_) |_
  | |_) / _ \| | | | __/ _ \ '__| ' /| | __|
  |  _ < (_) | |_| | ||  __/ |  | . \| | |_
  |_| \_\___/ \__,_|\__\___|_|  |_|\_\_|\__|

   RKOS 0.1 / Linux 6.18.15-0-lts / x86_64

rtr-pod0-1 login: