rc.router

The FreeBSD Init/RC system could use some extensions for easy configuration of homelab and SOHO routers.

These files provide such a set of extensions. These extensions, while providing a lot of advanced functionality, are not meant for anything other than edge routers. "Core router" functionality (which bridges between transit networks) is not provided for by this configuration mechanism.

rc.router requires FreeBSD-15 or greater. (It might work for some configurations on FreeBSD-14, but I no longer run any routers with it on FreeBSD-14.)

Mascot

Meet "Ricky", the project mascot.

I'm no artist, so I had an AI make this. Ricky is a fun little squid made out of the mess of cables in your home network's core. He wants to make your network better!

Prerequisites

None, in particular. The rc.router/scripts/install-dependencies.sh script will install all necessary dependency packages for FreeBSD. Several of the ${rc_router_dir}/rc.d startup scripts depend upon these. It is expected that this script will be run by the administrator to install those packages.

Directory Layout

${rc_router_dir}/rc.d

This directory contains various startup scripts, including configuration file generation scripts.

${rc_router_dir}/defaults

This directory contains rc.conf defaults which are similar to /etc/defaults/rc.conf. This file should not be edited, as user configurations can instead override these default options.

${rc_router_dir}/hints

This directory contains configuration hints for various common ISPs.

${rc_router_dir}/docs

This directory contains markdown formatted documentation for various rc.conf embeddable configuration commands.

${rc_router_dir}/templates

This directory contains the base templates for some generated file types.

${rc_router_dir}/samples

This directory contains subdirectories with sample configurations for common use cases. Each subdirectory is named for its purpose. The basic configuration is recommended as a good starting point. Users should fill in some small details in a "local.conf" file in those configuration samples. When these samples are used, the entire configuration of the router for that purpose should be complete. On next reboot, it should function according to that use case, with no other settings changes necessary. It is recommended that users copy the sample configurations as a starting point, rather than modify them in place

${rc_router_dir}/harness

This directory contains a testing harness to allow running many of these configuration scripts outside of FreeBSD's init system, for testing and validation. (Use env RC_ROUTER_HARNESS=${path_to_harness_dir} to execute one of the rc.d scripts or rc.test.)

Installation and Usage

The rc.router configuration package is designed to be integrated with FreeBSD system startup for use in SOHO and Home-Lab edge routers. It supports easy configuration for automatic generation of a lot of useful components. Eventually the most basic use cases should be as simple as writing just two or three lines of configuration settings.

The package is meant to integrate with /etc/rc.conf by setting two key variables to help the init system find the package and then by sourcing the package's entry point (${rc_router_dir}/rc.entry). One can disable the entire package merely by commenting out that single line which sources rc.entry, which provides an easy way to diagnose if this package is causing problems.

The ${rc_router_dir} variable is meant to be set to the root directory of this package, and it must be mounted early enough in the boot process. The ${rc_router_conf_dir} can be set to any path which will be mounted and present early enough in the boot process as well. The ${rc_router_conf_dir} can be a git repository where ${rc_router_dir} is a git submodule therein. This is the recommended deployment strategy, as it permits configuration versioning and easy-to-use rollback semantics for local configuration changes.

What it does and how it works

rc.router will setup a number of shell script utility functions for use in processing rc.conf style configuration files. After it does this, it will source ${rc_router_conf_dir}/rc.conf. When it does, the user's preferences for router settings will be processed there.

These utility functions simplify the administration of a FreeBSD edge router and firewall by providing easy to use mechanisms to change groups of related rc.conf variables for those use cases. For example, instead of having to write:

vlans_xy0="2"
dhcpd_ifaces="xy0.2"
dhcp6c_interfaces="xy0.2"
rtadvd_interfaces="xy0.2"
ifconfig_xy0_2="192.168.2.1/24"
ifconfig_xy0_2_ipv6="fd12:3456:7890:2::1/64"
# And manually configure several other related variables and configuration files

one could instead just write:

add_net xy0 2

and all the necessary rc.conf variables will be set by the add_net command and the related DHCP configuration files and router advertisement configuration files will be generated. Scripts such as ${rc_router_dir}/rc.d/generate_internal_dhcpv4 will generate the necessary configuration files from various rc.conf variables and hints. rc.router uses several internal variables (set by its commands) to help drive this process, such that more customized configurations can be co-mingled with its patterns.

Easy setup using the basic sample configuration

Executing this sequence of sample commands will setup a fully-functional SOHO router using this framework. You'll need to fill in the appropriate choices for your ISP and your network interfaces.

$ cd /etc
$ mkdir router-conf
$ cd router-conf
$ git init --object-format=sha256 .
$ git submodule add rc.router https://gitea.nerdland.org/rc.router/rc.router
$ rc.router/scripts/install-dependencies.sh
$ cp rc.router/samples/basic/* .
$ cat << EOF > local.conf
external_card="abc0"
internal_card="xy0"
my_isp="verizon_fios"
EOF
$ git add rc.conf local.conf pf.conf
$ git commit -m "FIRST POST!!!"
$ echo 'rc_router_dir="/etc/router-conf/rc.router"' >> /etc/rc.conf
$ echo 'rc_router_conf_dir="/etc/router-conf"' >> /etc/rc.conf
$ echo ". ${rc_router_dir}/rc.entry" >> /etc/rc.conf
$ reboot # Router is ready

How to setup (Easy dual-stack example With Git)

Executing this sequence of sample commands will setup a basic Dual-stack router for Verizon FIOS. There are a few pre-canned ISP configuration files which help guide what settings are needed for which ISPs. (Mostly this impacts IPv6 settings not IPv4 settings.)

$ cd /etc
$ mkdir router-conf
$ cd router-conf
$ git init --object-format=sha256 .
$ cat << EOF > rc.conf
# Configure a basic external v4 ISP
external_card="em0"

add_canned_isp ${external_card} fios_1 verizon_fios 


# Configure a basic internal v4 network
internal_card="re0"
add_net ${internal_card} 0 main

EOF
$ git add rc.conf
$ git submodule add rc.router https://gitea.nerdland.org/rc.router/rc.router
$ git commit -m "FIRST POST!!!"
$ rc.router/scripts/install-dependencies.sh
$ echo 'rc_router_dir="/etc/router-conf/rc.router"' >> /etc/rc.conf
$ echo 'rc_router_conf_dir="/etc/router-conf"' >> /etc/rc.conf
$ echo ". ${rc_router_dir}/rc.entry" >> /etc/rc.conf

How to setup (Easy v4-only example With Git)

Executing this sequence of sample commands will setup a basic v4 NAT/dhcp router.

$ cd /etc
$ mkdir router-conf
$ cd router-conf
$ git init --object-format=sha256 .
$ cat << EOF > rc.conf
# Configure a basic external v4 ISP
external_card="em0"
add_v4_isp ${external_card} dhcp



# Configure a basic internal v4 network
internal_card="re0"
v4_net="172.26"

add_v4_net ${internal_card} 0 main
EOF
$ git add rc.conf
$ git submodule add rc.router https://gitea.nerdland.org/rc.router/rc.router
$ git commit -m "FIRST POST!!!"
$ rc.router/scripts/install-dependencies.sh
$ echo 'rc_router_dir="/etc/router-conf/rc.router"' >> /etc/rc.conf
$ echo 'rc_router_conf_dir="/etc/router-conf"' >> /etc/rc.conf
$ echo ". ${rc_router_dir}/rc.entry" >> /etc/rc.conf

In this example, em0 will be the uplink card, and will dhcpv4 configure itself. re0 is the primary internal interface card, which will be configured to host DHCP for internal 172.26.0.0/24 addresses, in the basic default pool of 172.26.0.100 thru 172.26.0.200. The router's internal address in this subnet is 172.26.0.1/24. And 8.8.8.8 will be used as the default resolver for everyone within this subnet.

Interoperation with regular FreeBSD init and rc.conf configuration

These scripts are not meant to replace the FreeBSD init script mechanisms. Instead these scripts seek to augment the system. The scripts provide ways to set clusters of related config variables (and to generate other related configuration files) such that hybrid configurations can be made. The various commands, such as add_v4_net result in the setting and updating of various rc.conf variables as-if the user simply wrote the correct configuration settings at that point in the rc.conf file.

As such, these mechanisms are meant to co-exist with manual variable setting and manually maintained configuration files for things such as DHCP. This permits an adoption path other than "big bang cutover". The rc.router commands are careful to update-by-append to certain variables, rather than to assume direct ownership of all variables. Thus, add_net xy0 402 and ifconfig_xy0_43_alias0="192.168.10.4/24" could be safely intermingled. (Right now, the scripts assume ownership over specific related variables for interfaces and vlans that they create.)

IPv6 posture and readiness

rc.router is designed as an IPv6-first package. While IPv4-only networks are still possible with this package, the defaults are tuned for and assume IPv6. Pre-canned router configurations should gracefully (albeit with some timeouts) fail back to v4-only modes, when IPv6 is not available from those ISPs, due to CPE concerns.

IPv6 configuration with rc.router permits DHCPv6 IA_PD with Router Advertisements or static configuration for the ISP side. For the internal side, SLAAC is the only configuration provided. DHCPv6 internally for IA_NA is not implemented. rc.router is not expliticly incompatible with DHCPv6 internal provisioning, but no effort has been made to implement or test it. Given that a large number of consumer devices (Android, in particular) refuse to provision via DHCPv6, SLAAC must be used internally for any deployment to accommodate the widest swathe of client devices.

rc.router installs tayga and users are encouraged to use its map feature in the configuration file to provide IPv4 addresses for IPv6-only hosts, or vice-versa. This is intended to permit incremental migration for IPv4-only homelabs to dual-stack and IPv6-only deployments.

The DHCPv4 configuration generator is capable of emitting Option 108 for IPv6-mostly deployments. .