Documentation fixes and improvements
This commit is contained in:
@@ -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
|
||||
|
||||
@@ -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)
|
||||
|
||||
+5
-5
@@ -49,11 +49,11 @@ 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|
|
||||
|---:|---------------:|----------------:|--------------:|----------------------:|
|
||||
| 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
|
||||
|
||||
|
||||
+5
-5
@@ -45,11 +45,11 @@ 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|
|
||||
|---:|----------------:|----------------------:|
|
||||
| 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
|
||||
|
||||
|
||||
+2
-2
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user