NAME

sakaki —

NetBSD-powered home router

HARDWARE

The sakaki box is a PC Engines apu1 with 2 gigabytes of RAM and 3 Realtek gigabit Ethernet interfaces.

It runs Coreboot with SeaBIOS and NetBSD. The coreboot build is:

Build 9/8/2014 (beta, reduced spew
  level)

This was flashed due to issues with miniPCIe with earlier builds.

Currently it boots from a SD card, and the mSATA SSD slot is now unpopulated - we are unsure if the drive was bad or the controller was bad. There are two miniPCIe slots, which could be filled with pci(4) cards for ieee80211(4) or LTE, but are currently unpopulated. There is also "SATA proper", which is unpopulated because we don't have a big enough case to fit a drive. There is GPIO, but we need a newer OS release for that.

The case is dented due to a fat cat sleeping on it. You can infer from this that the hardware gets warm - it does, about 60C idle. Do not unscrew the motherboard, you will need to reapply some fragile heat pads.

ROLES

sakaki is currently performing the following functions:

PPPoE (via pppoe(4))
DNSCrypt (via dnscrypt-proxy(8))
DHCP (via dhcpd(8))
IPv6 Prefix Delegation (via dhcpcd(8))
IPv6 Router Advertisement (via rtadvd(8))
Firewall (via npf(7))
NTP (via chrony(8))
HTTP network statistics (via darkstat(8))
SSH (via sshd(8))

NETBSD BASICS

The default shell is sh(1). Edit your shell configuration by editing $HOME/.profile and $HOME/.shrc. sh(1) has two editing modes, vi and emacs, and supports tab completion for filenames. It does not support tab completion for command names, but ksh(1) does. There is also csh(1), if you are weird. You can change your default shell with chsh(1). Please do not install bash. If you write scripts, please use sh(1), so everyone can understand them. And keep it basic.

Services are configured by editing /etc/rc.conf, see rc.conf(5). They are started/stopped/restarted with the service(8) command . A static shell script /etc/rc.local can also contain local services, but we should avoid this and use real rc.subr(8) init scripts where we're able. As well as cron(8), you can add entries to the scripts /etc/daily.local (etc.) to run periodic tasks. The admin writing this text prefers this to cron(8) in most situations.

Kernel settings are changed with sysctl(8), and read on boot from /etc/sysctl.conf, see sysctl.conf(5). The main ones we change are the ones that enable packet forwarding and raise the secmodel_securelevel(9).

By default, syslogd(8) writes to /var/log/messages. To check kernel messages, run dmesg(8).

Many configuration examples for core OS things (including the firewall) can be found in /usr/share/examples.

AVAILABLE SOFTWARE

For editing text, vi(1) is included with NetBSD by default. I have also installed nano(1).

If you would like to learn how to use BSD vi(1), try:

less
  /usr/share/doc/usd/vi/vitut.txt

If you want to download files from HTTPS, try being a pro BSD user and using ftp(1) for it. Please note that tar(1) can handle most formats known to man.

For system monitoring, to be a pro extreme super BSD user, try top(1), netstat(1), fstat(1), sysstat(1). top(1) is often more accurate than htop on NetBSD, and less disappointing than the versions of top common on Linux. Many network stack statistics can also be learned from ‘sysctl -a | less’.

In case of emergency, ktrace(1) is the typical system call trace utility. strace is also available from packages, but is less useful.

tmux(1) is included with NetBSD by default, as well as file(1). Also, tetris(6).

PACKAGE MANAGEMENT

On this box, pkgin(1) is used for package management. It is similar to things like apt from Linux. There are many other ways to use pkgsrc, but we are keeping things basic here. Stick to quarterly releases.

By default, pkgsrc installs software to /usr/pkg. If you're more familar with Linux, this is like /usr, but only for third-party software. If you're more familiar with (Free|Open)BSD, this is like /usr/local. On NetBSD, /usr/local is for anything that is not part of the core OS, and has not been installed from the packaging system.

Configuration for third-party software is contained in /usr/pkg/etc. The packaging system cannot touch this directory except to install example files from /usr/pkg/share/examples.

Other relevant commands are pkg_admin(1) and pkg_info(1).

You can check if there are any vulnerable packages with:

pkg_admin audit

List the contents of a package:

pkg_info -L chrony

Identify a mysterious file:

pkg_info -F
  /usr/pkg/bin/msgfmt

The root account should also recieve email about vulnerable packages. NetBSD uses mail(1) as a notification system.

NETWORK CONFIGURATION

The following files are used:

/etc/ifconfig.re0: The Ethernet port closest to the serial port. This is the router's gateway to the world. See re(4) and ifconfig.if(5).
/etc/ifconfig.re1: Another ethernet port, for LAN.
/etc/ifconfig.re2: Another ethernet port, for LAN.
/etc/ifconfig.bridge0: A bridge(4) used to bring all of the LAN interfaces together.
/etc/ifconfig.tap0: A virtual Ethernet interface used as a bridge(4) endpoint. Note that bridges cannot be assigned addresses on NetBSD, but this device can be. If we update to NetBSD 10 or newer, this will need to be replaced with vether0. The DHCP server listens on this interface, and the firewall assigns rules based on it. See tap(4).
/etc/ifconfig.pppoe0: A virtual interface used to encapsulate PPPoE packets to talk to bad residential ISPs. See pppoe(4).
/etc/npf.conf: The ruleset for the npf(7) firewall, see npf.conf(5). It can be reloaded with ‘service npf reload’.
/etc/dhcpd.conf: Configuration for the DHCP server, see dhcpd.conf(5).
/etc/dhcpcd.conf: Configuration for IPv6 prefix delegation, see dhcpcd.conf(5).
/etc/hostapd.conf: Configuration for acting as a WiFi access point, see hostapd.conf(5). This is not currently in use, but is kept for posterity.
/etc/ppp/ip-up: This is used by ifwatchd(8) and is an ordinary sh(1) script that runs when a PPPoE link is obtained. It is used to assign a route to the outside world.
/etc/ppp/ip-down: This deletes the route created by /etc/ppp/ip-up.

SOFTWARE CONFIGURATION

/usr/pkg/etc/dnscrypt_proxy.toml: For DNSCrypt. Not documented in a man page (boos, throws fruit).
/usr/pkg/etc/chrony.conf: For NTP. Documented in chrony.conf(5).

UPDATING SOFTWARE

You can update NetBSD remotely by using sysupgrade(8), available in pkgsrc. Alternatively, connect a serial console and insert a USB drive with a new installer image.

Please note that using the following NetBSD bootloader option is essential to get serial output in the installer image:

consdev com0,115200

You can update the packages using pkgin(1). You may need to change /usr/pkg/etc/pkgin/repositories.conf to point at a newer repository occasionally.

New coreboot firmware can be flashed with flashrom(8), available in pkgsrc. Please be very careful when doing this.

UPDATING THIS DOCUMENT

If you're unfamiliar with how to write man pages, please refer to mdoc(7). Preview it with ‘

man
  ./sakaki.7

’. Verify it is correct with ‘mandoc -T lint ./sakaki.7’.