# 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.

![img](ricky-small.png)

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`](docs/add_net.md) 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.
.