Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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
       networking  solution  compared  to  the traditional if_bridge/epair/tap
       setup, offering a clearer and shorter list of virtual devices, and per-
       formance	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).	 Addi-
       tional  tools  assist  with  jail  interface  management,   configuring
       vm-bhyve, naming	vm-bhyve sockets, displaying basic statistics, and de-
       termining 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 defini-
	      tions 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) de-
	      vices and	basic usage statistics.

       bridge bridge interface
	      Create a bridge and an associated	rc.conf	entry.	If the	inter-
	      face  exists, bridge will	be associated with it.	Otherwise, in-
	      terface 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)  configura-
	      tion, e.g., /vm/.config/system.conf.

       vmname Name  ng_socket(4)  devices associated with bhyve	instances run-
	      ning 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 re-
       boot.

       ngbuddy_enable
	      Set to YES to enable the service.

       ngbuddy_(BRIDGE)_if
	      Link a new ng_bridge(4) device named BRIDGE to the indicated in-
	      terface, 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  ng-
	      buddy_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 indi-
	      cated.  The command's output will	receive	the seed through stan-
	      dard input (see ngbuddy_set_mac) and must	return enough hexadec-
	      imal 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 dia-
	      gram 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 as-
       sociated	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	ifcon-
       fig_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.

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)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ngbuddy&manpath=FreeBSD+14.3-RELEASE+and+Ports>

home | help