Setup¶

This chapter walks through the basic setup of your router running RouterKit OS.

Access your router¶

Open a serial console in PVE by double clicking on the VM in the list on the lefthand side. Press enter, if you do not see anything. Since we're using xterm.js here, you'll be able to copy and paste. If Ctrl+C/V won't work, try using the context menu (right click).

You should either see the router booting up or a login prompt.

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

   RKOS 0.3 / Linux 6.18.59-0-lts / x86_64

localhost login:     

If this is your first time accessing the router, just log in as root without a password.

Installing RouterKit OS¶

This step is pretty easy. Just run rkos-install using the appropriate arguments:

rkos-install /media/cdrom /dev/sda

The installer asks, if you want to configure EFI boot entries. You can accept that.

Now is a good time to reboot the router to test your new installation. Just type reboot. After your router is back up, log in with root again.

Configuring RouterKit OS¶

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

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

Hostname¶

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

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

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 and Network Time Protocol¶

Just press enter to use the default values (UTC 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.

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: 
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

SSH server¶

You might want to access your router via SSH. To do so, install openssh by pressing enter.

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 ]

Installing base packages¶

The basic setup of RouterKit OS is now done. Next, you can 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-pod1-bg1:~# apk add nano
(1/1) Installing nano (9.3-r0)
Executing busybox-1.37.0-r31.trigger
OK: 75.4 MiB in 138 packages

You 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

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 keep in 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.3 / Linux 6.18.59-0-lts / x86_64

rtr-pod1-bg1 login: