FreeBSD Manual Pages
ngbuddy(8) System Manager's Manual ngbuddy(8) 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 network- ing solution compared to the traditional if_bridge/epair/tap setup, offer- ing 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 de- fault 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 ad- dress and add a NAT service to allow your guests to have access to the net- work. 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 in- terface 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 sub- commands will use sysrc(8) to configure rc.conf with the following vari- ables 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 inter- face, 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 ad- dress 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_pre- fix="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 indi- cated. The command's output will receive the seed through standard input (see ngbuddy_set_mac) and must return enough hexadecimal char- acters 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/bell- hyve/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 associ- ated 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_DE- FAULT=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 exam- ple script and additional examples by Klara Systems. SEE ALSO jail(8), netgraph(4), ng_bridge(4), ngctl(8), ng_eiface(4), ng_socket(4), vm(8) HISTORY Netgraph Buddy was originally developed as an internal tool for Bell Tower Integration's private cloud in August 2022. AUTHORS Daniel J. Bell. July 8, 2024 ngbuddy(8)
NAME | SYNOPSIS | DESCRIPTION | QUICK START EXAMPLE | SUBCOMMANDS | RC.CONF VARIABLES | FILES | EXAMPLES | NOTES | SEE ALSO | HISTORY | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ngbuddy&manpath=FreeBSD+15.1-RELEASE+and+Ports.quarterly>