NAME

ngbuddy - Simplified netgraph(4) manager for jail(8) and bhyve(8)

SYNOPSIS

service ngbuddy enable

service ngbuddy start

service ngbuddy stop

service ngbuddy restart

service ngbuddy status

service ngbuddy bridge bridge interface

service ngbuddy unbridge bridge

service ngbuddy jail interface [bridge]

service ngbuddy unjail interface [jail]

service ngbuddy create interface [bridge]

service ngbuddy destroy interface

service ngbuddy vmconf

service ngbuddy vmname

DESCRIPTION

ngbuddy (“Netgraph Buddy”) is an rc.d script for managing netgraph(4) in mixed vm and jail environments. Netgraph provides a more flexible networking solution compared to the traditional if_bridge/epair/tap setup, offering a clearer and shorter list of virtual devices, and performance benefits for some workloads.

rc.conf variables prefixed by ngbuddy_ are used to manage ng_bridge(4) and ng_eiface(4) devices upon service start (and system boot). Additional tools assist with jail interface management, configuring vm-bhyve, naming vm-bhyve sockets, displaying basic statistics, and determining stable MAC addresses to help avoid collisions.

QUICK START EXAMPLE

The following commands will configure a system for netgraph.

service ngbuddy enable: Sets rc.conf variables to enable the ngbuddy service. If no bridge definitions are set, the following default bridge definitions will be added:

public: A bridge interface associated with the host system’s current default route, allowing guests to interact with the existing network.

private: A bridge linked to a new virtual interface named nghost0, suitable for host-only or NAT network with your guests.



    ngbuddy_enable="YES"


    ngbuddy_public_if="em0"


    ngbuddy_private_if="nghost0"

service ngbuddy start: Creates bridges and interfaces defined in rc.conf.
service ngbuddy vmconf: Adds our public and private bridges to the vm(8) configuration, as a substitute for the vm switch ...* commands.

To get the most out of the private bridge, configure nghost0 with an IP address and add a NAT service to allow your guests to have access to the network. See the examples in the ngbuddy repository for demo scripts.

SUBCOMMANDS

Subcommands are called using service ngbuddy SUBCOMMAND. Note that all commands rely on ngctl(8) and require root permissions.

enable: Enable the ngbuddy service. If no bridges are defined, a public and private bridge will be created. See QUICK START EXAMPLE above for details.
start: Load the bridge and eiface options configured in rc.conf. See RC.CONF VARIABLES below for a complete list of options.
stop: Destroy all ng_bridge(4) and ng_eiface(4) devices, even if they were not created with ngbuddy.
restart: Stop, then start.
status: Print a list of ng_bridge(4), ng_eiface(4), and ng_socket(4) devices and basic usage statistics.
bridge bridge interface: Create a bridge and an associated rc.conf entry. If the interface exists, bridge will be associated with it. Otherwise, interface will be created as a new eiface node.
unbridge bridge: Remove the indicated bridge from netgraph and rc.conf.
jail interface [bridge]: Create a new eiface associated with the indicated bridge. If only one ng_bridge(4) is present, bridge may be omitted.
unjail interface [jail]: Shut down the eiface associated with the indicated jail. If the interface matches the jail name, jail may be omitted.
create interface [bridge]: Create a new eiface associated with the indicated bridge and add it to rc.conf so it will be created on startup. If only one bridge is configured, bridge may be omitted.
destroy interface: Shut down the indicated eiface and remove it from rc.conf.
vmconf: Add the bridges configured in rc.conf to the vm(8) configuration, e.g., /vm/.config/system.conf.
vmname: Name ng_socket(4) devices associated with bhyve instances running via vm(8).

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.

ngbuddy_enable: Set to YES to enable the service.
ngbuddy_(BRIDGE)_if: Link a new ng_bridge(4) device named BRIDGE to the indicated interface, e.g., eth0. 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 bridge and unbridge subcommands.
ngbuddy_(BRIDGE)_list: A space delimited list of additional ng_eiface(4) devices that will be attached to BRIDGE at startup. This variables will be set with the create and destroy subcommands.
ngbuddy_set_mac: If set to YES, eiface hardware addresses will be determined from a hash of the interface name, ensuring that the interfaces’ MAC address are stable between hosts. If set to a string besides YES, that string will be added to the MAC address generator’s seed.
ngbuddy_set_mac_prefix: Override the default MAC address prefix of 58:9C:FC (the OUI of the FreeBSD Foundation). For example, you can set ngbuddy_set_mac_prefix=“02” to minimize the risk of collisions. ngbuddy_set_mac must also be enabled to use this feature.
ngbuddy_set_mac_hash: Override the default hash command of sha1 with the command indicated. The command’s output will receive the seed through standard input (see ngbuddy_set_mac) and must return enough hexadecimal characters to complete the MAC address.

FILES

/usr/local/etc/rc.d/ngbuddy: The Netgraph Buddy run control script.
/usr/local/share/ngbuddy/ngbuddy-status.awk: Helper for service ngbuddy status
/usr/local/share/ngbuddy/ngbuddy-mmd.awk: An alternative to ngctl dot that creates a Mermaid-JS color diagram of netgraph nodes.

EXAMPLES

For examples and demo scripts, see examples at: https://github.com/bellhyve/netgraph-buddy

Example 1: Quickly deploy a VNET jail with netgraph using jail.conf.d

The following steps will configure a jail attached to the interface associated with the host’s current default route, likely your LAN, using DHCP.

First, set up Netgraph Buddy:

- service ngbuddy enable

- service ngbuddy start

- Append examples/devfs.rules to /etc/devfs.rules

Next, create a new jail:

- Set up a FreeBSD base: bsdinstall jail /jail/my_jail

- Enable DHCP in the jail: sysrc -f /jail/my_jail/etc/rc.conf ifconfig_DEFAULT=SYNCDHCP

Configure the jail configuration:

- Copy examples/jail_skel.conf to /etc/jail.conf.d/my_jail.conf

- In my_jail.conf after the comments, change the word jail_skel to your jail’s name, my_jail

- Run: service jail start my_jail

To create more jails, you can:

- Copy /jail/my_jail/ to /jail/new_jail1/

- Copy /etc/jail.conf.d/my_jail.conf to new_jail1.conf

- Edit the new configuration as above and change the word my_jail to new_jail1

- Run: service jail start new_jail1

- And repeat as desired.

Example 2: An rc.conf example for a slightly more complex setup

ngbuddy_enable="YES"
ngbuddy_lan_if="igb0"
ngbuddy_private0_if="ng0"
ngbuddy_private0_list="j1p0 j2p0"
ngbuddy_private1_if="ng1"
ngbuddy_private1_list="j1p1 j2p1"
ngbuddy_tenant_lan_if="igb1"
ngbuddy_tenant_wan_if="ix1"
ngbuddy_wan_if="ix0"
ngbuddy_set_mac="belltower"
ngbuddy_set_mac_prefix="02"
ngbuddy_set_mac_hash="sha256"

Example 3: Initial status of the above configuration

lan


  igb0 (upper): RX 0B, TX 0B


  igb0 (lower): 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 (upper): RX 0B, TX 0B


  igb1 (lower): RX 0B, TX 0B
tenant_wan


  ix1 (upper): RX 0B, TX 0B


  ix1 (lower): RX 0B, TX 0B
wan


  ix0 (upper): RX 30.69 KB, TX 46.16 KB


  ix0 (lower): RX 46.32 KB, TX 30.92 KB

NOTES

These scripts were developed to assist with new netgraph features in vm-bhyve 1.5+, and were inspired by the /usr/share/examples/jails/jng example script and additional examples by Klara Systems.

HISTORY

Netgraph Buddy was originally developed as an internal tool for Bell Tower Integration’s private cloud in August 2022.

AUTHORS

Daniel J. Bell.