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
|
||||
|
||||
Reference in New Issue
Block a user