-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
fix examples and doc to allow DHCP jails to work
- Loading branch information
Showing
3 changed files
with
348 additions
and
8 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,327 @@ | ||
| .\" Automatically generated by Pandoc 3.1.13 | ||
| .\" | ||
| .TH "ngbuddy" "8" "July 8, 2024" "" "System Manager\[cq]s Manual" | ||
| .SH NAME | ||
| \f[B]ngbuddy\f[R] \- Simplified netgraph(4) manager for jail(8) and | ||
| bhyve(8) | ||
| .SH SYNOPSIS | ||
| \f[B]service ngbuddy enable\f[R] | ||
| .PD 0 | ||
| .P | ||
| .PD | ||
| \f[B]service ngbuddy start\f[R] | ||
| .PD 0 | ||
| .P | ||
| .PD | ||
| \f[B]service ngbuddy stop\f[R] | ||
| .PD 0 | ||
| .P | ||
| .PD | ||
| \f[B]service ngbuddy restart\f[R] | ||
| .PD 0 | ||
| .P | ||
| .PD | ||
| \f[B]service ngbuddy status\f[R] | ||
| .PP | ||
| \f[B]service ngbuddy bridge\f[R] \f[I]bridge\f[R] \f[I]interface\f[R] | ||
| .PD 0 | ||
| .P | ||
| .PD | ||
| \f[B]service ngbuddy unbridge\f[R] \f[I]bridge\f[R] | ||
| .PP | ||
| \f[B]service ngbuddy jail\f[R] \f[I]interface\f[R] [\f[I]bridge\f[R]] | ||
| .PD 0 | ||
| .P | ||
| .PD | ||
| \f[B]service ngbuddy unjail\f[R] \f[I]interface\f[R] [\f[I]jail\f[R]] | ||
| .PD 0 | ||
| .P | ||
| .PD | ||
| \f[B]service ngbuddy create\f[R] \f[I]interface\f[R] [\f[I]bridge\f[R]] | ||
| .PD 0 | ||
| .P | ||
| .PD | ||
| \f[B]service ngbuddy destroy\f[R] \f[I]interface\f[R] | ||
| .PP | ||
| \f[B]service ngbuddy vmconf\f[R] | ||
| .PD 0 | ||
| .P | ||
| .PD | ||
| \f[B]service ngbuddy vmname\f[R] | ||
| .SH DESCRIPTION | ||
| \f[B]ngbuddy\f[R] (\[lq]Netgraph Buddy\[rq]) is an rc.d script for | ||
| managing netgraph(4) networks in mixed vm and jail environments. | ||
| \f[B]rc.conf\f[R] variables prefixed by \f[B]ngbuddy_\f[R] are used to | ||
| manage \[lq]permanent\[rq] ng_bridge(4) and ng_eiface(4) devices. | ||
| Additional tools assist with configuring vm\-bhyve and naming their | ||
| sockets for statistics and graphing. | ||
| .SH QUICK START EXAMPLE | ||
| The following commands will configure a system for netgraph in a way | ||
| that is suitable for most common setups on systems where no netgraph | ||
| configuration currently exists. | ||
| .TP | ||
| \f[B]service ngbuddy enable\f[R] | ||
| Set \f[B]rc.conf\f[R] variables and create a \f[I]public\f[R] bridge | ||
| interface associated with the host system\[cq]s default route, then | ||
| create a \f[I]private\f[R] bridge linked to a virtual interface named | ||
| \f[B]nghost0\f[R] suitable for a local or NAT interfaces. | ||
| It will append three \f[B]rc.conf\f[R] lines similar to the following, | ||
| which you can modify before starting the service: | ||
| .IP | ||
| .EX | ||
| ngbuddy_enable=\[dq]YES\[dq] | ||
| ngbuddy_public_if=\[dq]em0\[dq] | ||
| ngbuddy_private_if=\[dq]nghost0\[dq] | ||
| .EE | ||
| .TP | ||
| \f[B]service ngbuddy start\f[R] | ||
| This command creates the above interfaces. | ||
| .TP | ||
| \f[B]service ngbuddy vmconf\f[R] | ||
| Add the our \[lq]public\[rq] and \[lq]private\[rq] bridges to the vm(8) | ||
| configuration. | ||
| .PP | ||
| If you\[cq]d like to use host\-only or NAT interface, you must configure | ||
| the newly created \f[B]nghost0\f[R] interface. | ||
| For example, you may want to set up IP addresses, a DNS resolver, and a | ||
| DHCP server. | ||
| .PP | ||
| Once post\-configuration is to your liking, create jails or bhyve | ||
| instances attached to your \f[I]public\f[R] or \f[I]private\f[R] bridges | ||
| as you prefer. | ||
| See the \f[B]jail_skel.conf\f[R] for assistance configuring jails. | ||
| .SH SUBCOMMANDS | ||
| Subcommands are called using \f[B]service ngbuddy | ||
| \f[BI]SUBCOMMAND\f[B]\f[R]. | ||
| Note that all commands rely on ngctl(8) and require root permissions. | ||
| .TP | ||
| \f[B]enable\f[R] | ||
| Create a basic default \f[B]ngbuddy\f[R] configuration and enable the | ||
| service. | ||
| .TP | ||
| \f[B]start\f[R] | ||
| Load the ng_bridge(4) and ng_eiface(4) options configured in | ||
| \f[B]rc.conf\f[R]. | ||
| See \f[I]RC.CONF VARIABLES\f[R] below. | ||
| .TP | ||
| \f[B]stop\f[R] | ||
| Destroy all ng_bridge(4) and ng_eiface(4) devices, regardless of whether | ||
| they were created with \f[B]ngbuddy\f[R] or not. | ||
| .TP | ||
| \f[B]restart\f[R] | ||
| Stop, then start. | ||
| .TP | ||
| \f[B]status\f[R] | ||
| Print a list of ng_bridge(4), ng_eiface(4), and ng_socket(4) devices and | ||
| basic usage statistics. | ||
| .TP | ||
| \f[B]bridge\f[R] \f[I]bridge\f[R] \f[I]interface\f[R] | ||
| Create a bridge and an associated \f[B]rc.conf\f[R] entry. | ||
| If the \f[I]interface\f[R] exists, \f[I]bridge\f[R] will be associated | ||
| with it. | ||
| Otherwise, \f[I]interface\f[R] will be created as a new ng_eiface(4) | ||
| device. | ||
| .TP | ||
| \f[B]unbridge\f[R] \f[I]bridge\f[R] | ||
| Remove the indicated bridge from netgraph and \f[B]rc.conf\f[R]. | ||
| This operation will fail if devices appear to be attached to it. | ||
| .TP | ||
| \f[B]jail\f[R] \f[I]interface\f[R] [\f[I]bridge\f[R]] | ||
| Create a new ng_eiface(4) associated with the indicated | ||
| \f[I]bridge\f[R]. | ||
| If only one ng_bridge(4) is present, \f[I]bridge\f[R] may be omitted. | ||
| .TP | ||
| \f[B]unjail\f[R] \f[I]interface\f[R] [\f[I]jail\f[R]] | ||
| Remove an ng_eiface(4) associated with the indicated \f[I]jail\f[R]. | ||
| If the \f[I]interface\f[R] matches the jail name, \f[I]jail\f[R] may be | ||
| omitted. | ||
| .TP | ||
| \f[B]create\f[R] \f[I]interface\f[R] [\f[I]bridge\f[R]] | ||
| Create a new ng_eiface(4) associated with the indicated \f[I]bridge\f[R] | ||
| and add it to \f[B]rc.conf\f[R] so it will be created on startup. | ||
| If only one ng_bridge(4) is present, \f[I]bridge\f[R] may be omitted. | ||
| .TP | ||
| \f[B]destroy\f[R] \f[I]interface\f[R] | ||
| Remove the indicated ng_eiface(4) and remove it from \f[B]rc.conf\f[R]. | ||
| .TP | ||
| \f[B]vmconf\f[R] | ||
| Add the bridges configured in \f[B]rc.conf\f[R] to the vm(8) | ||
| configuration, e.g., \f[B]/vm/.config/system.conf\f[R]. | ||
| .TP | ||
| \f[B]vmname\f[R] | ||
| Name ng_socket(4) devices associated with bhyve instances running via | ||
| vm(8). | ||
| .SH RC.CONF VARIABLES | ||
| The following variables can be manually configured Some of the above | ||
| subcommands will use sysrc(8) to configure rc.conf with the following | ||
| variables for persistent configuration on service restart or system | ||
| reboot, which can also be edited manually. | ||
| .TP | ||
| \f[I]ngbuddy_enable\f[R] | ||
| Set to \f[I]YES\f[R] to enable the service. | ||
| .TP | ||
| \f[I]ngbuddy_(\f[R]BRIDGE\f[I])_if\f[R] | ||
| Link a new ng_bridge(4) device named \f[I]BRIDGE\f[R] to the indicated | ||
| interface, e.g., \f[I]eth0\f[R]. | ||
| If the interface already exists, link it to the new bridge and disable | ||
| LRO/TSO. | ||
| If the interface does not exist, create it as an ng_eiface(4) device. | ||
| This variable will be set with the \f[B]bridge\f[R] and | ||
| \f[B]unbridge\f[R] subcommands. | ||
| .TP | ||
| \f[I]ngbuddy_(\f[R]BRIDGE\f[I])_list\f[R] | ||
| A space delimited list of additional ng_eiface(4) devices that will be | ||
| attached to \f[I]BRIDGE\f[R] at startup. | ||
| This variable will be set with the \f[B]create\f[R] and | ||
| \f[B]destroy\f[R] subcommands. | ||
| .TP | ||
| \f[I]ngbuddy_set_mac\f[R] | ||
| If set to \f[I]YES\f[R], created ng_eiface hardware addresses will be | ||
| determined only from a hash of the interface name; this ensures each | ||
| interface\[cq]s MAC address is stable between hosts. | ||
| If set to another string, such as a host or domain name, add that seed | ||
| to the MAC address generator. | ||
| The default behavior will used FreeBSD\[cq]s default MAC address | ||
| generator, which is prone to MAC address collisions in large networks. | ||
| .TP | ||
| \f[I]ngbuddy_set_mac_prefix\f[R] | ||
| Override the default MAC address prefix of \f[B]58:9C:FC\f[R] (the OUI | ||
| of the FreeBSD Foundation). | ||
| For example, you can set \f[I]ngbuddy_set_mac_prefix=\[lq]02\[rq]\f[R] | ||
| to minimize the risk of collisions. | ||
| .TP | ||
| \f[I]ngbuddy_set_mac_hash\f[R] | ||
| Override the default hash command of \f[B]sha1\f[R] with the command | ||
| indicated. | ||
| The command\[cq]s output will receive the seed through standard input | ||
| (see \f[I]ngbuddy_set_mac\f[R]) and must return enough hexadecimal | ||
| characters to complete the MAC address. | ||
| .SH FILES | ||
| .TP | ||
| \f[B]/usr/local/etc/rc.d/ngbuddy\f[R] | ||
| The Netgraph Buddy run control script. | ||
| .TP | ||
| \f[B]/usr/local/share/ngbuddy/ngbuddy\-status.awk\f[R] | ||
| Helper for \f[B]service ngbuddy status\f[R] | ||
| .TP | ||
| \f[B]/usr/local/share/ngbuddy/ngbuddy\-mmd.awk\f[R] | ||
| An alternative to \f[B]ngctl dot\f[R] that creates a Mermaid\-JS color | ||
| diagram of netgraph nodes. | ||
| .SH NOTES | ||
| These scripts were developed to assist with new netgraph features in | ||
| \f[B]vm\-bhyve 1.5+\f[R], and were inspired by the | ||
| \f[B]/usr/share/examples/jails/jng\f[R] example script and additional | ||
| examples by Klara Systems. | ||
| .SH EXAMPLES | ||
| \f[B]Example 1: Quickly deploy a VNET jail with netgraph using | ||
| jail.conf.d\f[R] | ||
| .PP | ||
| The following steps will configure a jail attached to the interface | ||
| associated with your default route, likely your LAN, using DHCP. | ||
| See the files in \f[B]examples\f[R] at: | ||
| https://github.com/bellhyve/netgraph\-buddy | ||
| .PP | ||
| First, set up Netgraph Buddy: | ||
| .PD 0 | ||
| .P | ||
| .PD | ||
| \- \f[B]service ngbuddy enable\f[R] | ||
| .PD 0 | ||
| .P | ||
| .PD | ||
| \- \f[B]service ngbuddy start\f[R] | ||
| .PD 0 | ||
| .P | ||
| .PD | ||
| \- Append \f[B]examples/devfs.rules\f[R] to \f[B]/etc/devfs.rules\f[R] | ||
| .PD 0 | ||
| .P | ||
| .PD | ||
| .PP | ||
| Next, create a new jail: | ||
| .PD 0 | ||
| .P | ||
| .PD | ||
| \- Set up a FreeBSD base: \f[B]bsdinstall jail /jail/my_jail\f[R] | ||
| .PD 0 | ||
| .P | ||
| .PD | ||
| \- Enable DHCP in the jail: \f[B]sysrc \-f /jail/my_jail/etc/rc.conf | ||
| ifconfig_DEFAULT=SYNCDHCP\f[R] | ||
| .PD 0 | ||
| .P | ||
| .PD | ||
| .PP | ||
| Configure the jail configuration: | ||
| .PD 0 | ||
| .P | ||
| .PD | ||
| \- Copy \f[B]examples/jail_skel.conf\f[R] to | ||
| \f[B]/etc/jail.conf.d/my_jail.conf\f[R] | ||
| .PD 0 | ||
| .P | ||
| .PD | ||
| \- In \f[B]my_jail.conf\f[R] after the comments, change the word | ||
| \f[B]jail_skel\f[R] to your jail\[cq]s name, \f[B]my_jail\f[R] | ||
| .PD 0 | ||
| .P | ||
| .PD | ||
| \- Run: \f[B]service jail start my_jail\f[R] | ||
| .PD 0 | ||
| .P | ||
| .PD | ||
| .PP | ||
| To create more jails, simply copy \f[B]/jail/my_jail\f[R] and | ||
| \f[B]/etc/jail.conf.d/my_jail.conf\f[R], edit the jail configuration as | ||
| above, and start them. | ||
| .PP | ||
| \f[B]Example 2: An rc.conf example for a slightly more complex | ||
| setup\f[R] | ||
| .IP | ||
| .EX | ||
| ngbuddy_enable=\[dq]YES\[dq] | ||
| ngbuddy_lan_if=\[dq]igb0\[dq] | ||
| ngbuddy_private0_if=\[dq]ng0\[dq] | ||
| ngbuddy_private0_list=\[dq]j1p0 j2p0\[dq] | ||
| ngbuddy_private1_if=\[dq]ng1\[dq] | ||
| ngbuddy_private1_list=\[dq]j1p1 j2p1\[dq] | ||
| ngbuddy_tenant_lan_if=\[dq]igb1\[dq] | ||
| ngbuddy_tenant_wan_if=\[dq]ix1\[dq] | ||
| ngbuddy_wan_if=\[dq]ix0\[dq] | ||
| ngbuddy_set_mac=\[dq]belltower\[dq] | ||
| ngbuddy_set_mac_prefix=\[dq]02\[dq] | ||
| ngbuddy_set_mac_hash=\[dq]sha256\[dq] | ||
| .EE | ||
| .PP | ||
| \f[B]Example 3: Initial status of the above configuration\f[R] | ||
| .IP | ||
| .EX | ||
| lan | ||
| igb0 \f[B](\f[R]upper\f[B])\f[R]: RX 0B, TX 0B | ||
| igb0 \f[B](\f[R]lower\f[B])\f[R]: RX 0B, TX 0B | ||
| private0 | ||
| j2p0: RX 0B, TX 0B | ||
| j1p0: RX 0B, TX 0B | ||
| ng0: RX 0B, TX 0B | ||
| private1 | ||
| j2p1: RX 0B, TX 0B | ||
| j1p1: RX 0B, TX 0B | ||
| ng1: RX 0B, TX 0B | ||
| tenant_lan | ||
| igb1 \f[B](\f[R]upper\f[B])\f[R]: RX 0B, TX 0B | ||
| igb1 \f[B](\f[R]lower\f[B])\f[R]: RX 0B, TX 0B | ||
| tenant_wan | ||
| ix1 \f[B](\f[R]upper\f[B])\f[R]: RX 0B, TX 0B | ||
| ix1 \f[B](\f[R]lower\f[B])\f[R]: RX 0B, TX 0B | ||
| wan | ||
| ix0 \f[B](\f[R]upper\f[B])\f[R]: RX 30.69 KB, TX 46.16 KB | ||
| ix0 \f[B](\f[R]lower\f[B])\f[R]: RX 46.32 KB, TX 30.92 KB | ||
| .EE | ||
| .SH SEE ALSO | ||
| jail(8), netgraph(4), ng_bridge(4), ngctl(8), ng_eiface(4), | ||
| ng_socket(4), vm(8) | ||
| .SH HISTORY | ||
| Netgraph Buddy was originally developed as an internal tool for Bell | ||
| Tower Integration\[cq]s private cloud in August 2022. | ||
| .SH AUTHORS | ||
| Daniel J. Bell. |