diff --git a/README.md b/README.md index b9c0919..46943ee 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,103 @@ 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.) +## 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. + +## 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}/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. + ## How to setup (Easy dual-stack example With Git) Executing this sequence of sample commands will setup a basic Dual-stack router diff --git a/docs/add_canned_isp.md b/docs/add_canned_isp.md index d598270..76428c1 100644 --- a/docs/add_canned_isp.md +++ b/docs/add_canned_isp.md @@ -31,6 +31,12 @@ user-defined ISP hints. ISPs are always configured as `dhcp` for IPv4. For custom static provisioning, other methods of provisioning these interfaces can be used. +## Example +``` +# Connect to Verizon FIOS over `abc0`, and name the connection `main_isp`. +add_canned_isp abc0 main_isp verizon_fios +``` + ## See Also - [`add_net`](add_net.md) diff --git a/docs/add_net.md b/docs/add_net.md index 2112ab3..a74fbdc 100644 --- a/docs/add_net.md +++ b/docs/add_net.md @@ -48,12 +48,12 @@ kept as `0`, as those digits are reserved for future improvements. While this limits the system to 100 vlans, it provides 1:1 visual alignment between IPv4, IPv6, and VLAN ID. Each can be visually compared to the others.) -|VLAN|IPv4 (3rd octet)|IPv6 suffix (hex)|Example IPv4 |Example IPv6 | -|---:|---------------:|----------------:|--------------:|-----------------------:| -| 7| 7 | 7 |192.168.7.0/24 |2001:db8:abcd:ef07:::/64| -| 101|11 | 11 |192.168.11.0/24|2001:db8:abcd:ef11:::/64| -| 205|25 | 25 |192.168.25.0/24|2001:db8:abcd:ef25:::/64| -| 900|90 | 90 |192.168.90.0/24|2001:db8:abcd:ef25:::/64| +|VLAN|IPv4 (3rd octet)|IPv6 suffix (hex)|Example IPv4 |Example IPv6 | +|---:|---------------:|----------------:|--------------:|----------------------:| +| 7| 7 | 7 |192.168.7.0/24 |2001:db8:abcd:ef07::/64| +| 101|11 | 11 |192.168.11.0/24|2001:db8:abcd:ef11::/64| +| 205|25 | 25 |192.168.25.0/24|2001:db8:abcd:ef25::/64| +| 900|90 | 90 |192.168.90.0/24|2001:db8:abcd:ef25::/64| ## Options diff --git a/docs/add_v6_net.md b/docs/add_v6_net.md index 86a80df..337dbee 100644 --- a/docs/add_v6_net.md +++ b/docs/add_v6_net.md @@ -44,12 +44,12 @@ kept as `0`, as those digits are reserved for future improvements. While this limits the system to 100 vlans, it provides 1:1 visual alignment between IPv6 and VLAN ID. Each can be visually compared to the other.) -|VLAN|IPv6 suffix (hex)|Example IPv6 | -|---:|----------------:|-----------------------:| -| 7| 7 |2001:db8:abcd:ef07:::/64| -| 101| 11 |2001:db8:abcd:ef11:::/64| -| 205| 25 |2001:db8:abcd:ef25:::/64| -| 900| 90 |2001:db8:abcd:ef25:::/64| +|VLAN|IPv6 suffix (hex)|Example IPv6 | +|---:|----------------:|----------------------:| +| 7| 7 |2001:db8:abcd:ef07::/64| +| 101| 11 |2001:db8:abcd:ef11::/64| +| 205| 25 |2001:db8:abcd:ef25::/64| +| 900| 90 |2001:db8:abcd:ef25::/64| ## Options diff --git a/docs/variables.md b/docs/variables.md index 34afb8d..8b6f7f8 100644 --- a/docs/variables.md +++ b/docs/variables.md @@ -99,7 +99,7 @@ rc_router_gen_dir="/tmp/rc-router-gen/" This variable defines the lower bound of DHCPv4 pools for auto-generated `/24` networks constructed by [`add_v4_net`](add_v4_net.md) or [`add_net`](add_net.md). These pools can also be specified per-physical-interface (but not vlan) by using -`dhcpdv4_pool_lo_${iface}`. +`dhcpv4_pool_lo_${iface}`. ### Example @@ -117,7 +117,7 @@ dhcpv4_pool_lo_xy0="200" # For networks on `xy0`, start the dynamic pool at 200. This variable defines the upper bound of DHCPv4 pools for auto-generated `/24` networks constructed by [`add_v4_net`](add_v4_net.md) or [`add_net`](add_net.md). These pools can also be specified per-physical-interface (but not vlan) by using -`dhcpdv4_pool_hi_${iface}`. +`dhcpv4_pool_hi_${iface}`. ### Example