Page MenuHomeFreeBSD
Files F174178487

D59474.diff
No OneTemporary
Actions

D59474.diff
View Options

diff --git a/ObsoleteFiles.inc b/ObsoleteFiles.inc
--- a/ObsoleteFiles.inc
+++ b/ObsoleteFiles.inc
@@ -51,6 +51,10 @@
# xargs -n1 | sort | uniq -d;
# done
+# 20260906: Move jib and jng from share/examples/jails to usr.sbin
+OLD_FILES+=usr/share/examples/jails/jib
+OLD_FILES+=usr/share/examples/jails/jng
+
# 20260813: lib9p.so becomes a private library
OLD_LIBS+=usr/lib/lib9p.so.1
diff --git a/share/examples/Makefile b/share/examples/Makefile
--- a/share/examples/Makefile
+++ b/share/examples/Makefile
@@ -107,8 +107,6 @@
README \
VIMAGE \
jail.xxx.conf \
- jib \
- jng \
rc.conf.jails \
rcjail.xxx.conf
diff --git a/share/examples/jails/README b/share/examples/jails/README
--- a/share/examples/jails/README
+++ b/share/examples/jails/README
@@ -17,9 +17,10 @@
# Load ng_ether at once without rebooting:
$ kldload ng_ether
+See jib(8) and jng(8). Both are installed to /usr/sbin.
+
Sample 1: jail.conf(5)
- $ cp jib jng /usr/sbin/
$ cat jail.xxx.conf >> /etc/jail.conf
$ vi /etc/jail.conf
# NB: Customize root directory and bridge interface
@@ -30,7 +31,6 @@
Sample 2: rc.conf(5)
- $ cp jib jng /usr/sbin/
$ cp rc.conf.jails /etc/
$ vi /etc/rc.conf.jails
# NB: Customize root directory and bridge interface
@@ -40,7 +40,6 @@
Sample 3: Per-jail jail.conf(5)
- $ cp jib jng /usr/sbin/
$ cp jail.xxx.conf /etc/
$ vi /etc/jail.xxx.conf
# NB: Customize root directory and bridge interface
@@ -51,7 +50,6 @@
Sample 4: Per-jail rc.conf(5)
- $ cp jib jng /usr/sbin/
$ cp rcjail.xxx.conf /etc/
$ vi /etc/rcjail.xxx.conf
# NB: Customize root directory and bridge interface
diff --git a/share/man/man4/epair.4 b/share/man/man4/epair.4
--- a/share/man/man4/epair.4
+++ b/share/man/man4/epair.4
@@ -25,7 +25,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd August 16, 2026
+.Dd September 6, 2026
.Dt EPAIR 4
.Os
.Sh NAME
@@ -87,16 +87,40 @@
that is only guaranteed to be unique within one network stack.
The tunable
.Va net.link.epair.ether_gen_addr Ns
-=1 will generate a stable MAC address with
+=1 will generate a stable MAC address in the
.Fx
-OUI using
+Foundation OUI
+.Dq 58:9c:fc
+using
.Xr ether_gen_addr 9 .
-This tunable defaults to 1 in
-.Fx 15.0 and might be removed in
+This tunable defaults to 0 on
+.Fx 14
+and to 1 in
+.Fx 15.0
+and later; it might be removed in
.Fx 16.0 .
-To change the default addresses one may use the SIOCSIFADDR
-.Xr ioctl 2 or
-.Xr ifconfig 8 utility.
+On
+.Fx 14
+set
+.Dl sysctl net.link.epair.ether_gen_addr=1
+to get the Foundation OUI instead of a random locally administered address.
+.Pp
+To change the default addresses one may use
+.Xr ifconfig 8
+.Cm ether .
+That moves the clone-time address to
+.Cm hwaddr
+and places the new address on the wire.
+.Xr jib 8
+does this by default so a multi-node cluster can derive unique addresses
+from the parent NIC.
+Prefixing an interface with
+.Ql \&!
+in
+.Xr jib 8
+skips that override so the
+.Xr ether_gen_addr 9
+address remains on the wire.
.Pp
The basic intent is to provide connectivity between two virtual
network stack instances.
@@ -161,7 +185,9 @@
.Xr vlan 4 ,
.Xr loader.conf 5 ,
.Xr rc.conf 5 ,
-.Xr ifconfig 8
+.Xr ifconfig 8 ,
+.Xr jib 8 ,
+.Xr ether_gen_addr 9
.Sh HISTORY
The
.Nm
diff --git a/tools/build/mk/OptionalObsoleteFiles.inc b/tools/build/mk/OptionalObsoleteFiles.inc
--- a/tools/build/mk/OptionalObsoleteFiles.inc
+++ b/tools/build/mk/OptionalObsoleteFiles.inc
@@ -1791,8 +1791,6 @@
OLD_FILES+=usr/share/examples/jails/README
OLD_FILES+=usr/share/examples/jails/VIMAGE
OLD_FILES+=usr/share/examples/jails/jail.xxx.conf
-OLD_FILES+=usr/share/examples/jails/jib
-OLD_FILES+=usr/share/examples/jails/jng
OLD_FILES+=usr/share/examples/jails/rc.conf.jails
OLD_FILES+=usr/share/examples/jails/rcjail.xxx.conf
OLD_FILES+=usr/share/examples/kld/Makefile
@@ -2711,11 +2709,15 @@
OLD_FILES+=etc/rc.d/jail
OLD_FILES+=usr/sbin/jail
OLD_FILES+=usr/sbin/jexec
+OLD_FILES+=usr/sbin/jib
OLD_FILES+=usr/sbin/jls
+OLD_FILES+=usr/sbin/jng
OLD_FILES+=usr/share/man/man5/jail.conf.5.gz
OLD_FILES+=usr/share/man/man8/jail.8.gz
OLD_FILES+=usr/share/man/man8/jexec.8.gz
+OLD_FILES+=usr/share/man/man8/jib.8.gz
OLD_FILES+=usr/share/man/man8/jls.8.gz
+OLD_FILES+=usr/share/man/man8/jng.8.gz
.endif
.if ${MK_KDUMP} == no
diff --git a/usr.sbin/Makefile b/usr.sbin/Makefile
--- a/usr.sbin/Makefile
+++ b/usr.sbin/Makefile
@@ -160,7 +160,9 @@
SUBDIR.${MK_ISCSI}+= iscsid
SUBDIR.${MK_JAIL}+= jail
SUBDIR.${MK_JAIL}+= jexec
+SUBDIR.${MK_JAIL}+= jib
SUBDIR.${MK_JAIL}+= jls
+SUBDIR.${MK_JAIL}+= jng
# XXX MK_SYSCONS
SUBDIR.${MK_LEGACY_CONSOLE}+= kbdcontrol
SUBDIR.${MK_LEGACY_CONSOLE}+= kbdmap
diff --git a/usr.sbin/jail/jail.8 b/usr.sbin/jail/jail.8
--- a/usr.sbin/jail/jail.8
+++ b/usr.sbin/jail/jail.8
@@ -26,7 +26,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd August 13, 2026
+.Dd September 6, 2026
.Dt JAIL 8
.Os
.Sh NAME
@@ -1596,7 +1596,9 @@
.Xr ifconfig 8 ,
.Xr inetd 8 ,
.Xr jexec 8 ,
+.Xr jib 8 ,
.Xr jls 8 ,
+.Xr jng 8 ,
.Xr mount 8 ,
.Xr mountd 8 ,
.Xr nfsd 8 ,
diff --git a/usr.sbin/jail/jail.conf.5 b/usr.sbin/jail/jail.conf.5
--- a/usr.sbin/jail/jail.conf.5
+++ b/usr.sbin/jail/jail.conf.5
@@ -25,7 +25,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd September 21, 2024
+.Dd September 6, 2026
.Dt JAIL.CONF 5
.Os
.Sh NAME
@@ -245,7 +245,9 @@
.Xr rc.conf 5 ,
.Xr jail 8 ,
.Xr jexec 8 ,
+.Xr jib 8 ,
.Xr jls 8 ,
+.Xr jng 8 ,
.Xr zfs-jail 8
.Pp
The
diff --git a/usr.sbin/jib/Makefile b/usr.sbin/jib/Makefile
new file mode 100644
--- /dev/null
+++ b/usr.sbin/jib/Makefile
@@ -0,0 +1,6 @@
+PACKAGE= jail
+
+SCRIPTS= jib
+MAN= jib.8
+
+.include <bsd.prog.mk>
diff --git a/share/examples/jails/jib b/usr.sbin/jib/jib
rename from share/examples/jails/jib
rename to usr.sbin/jib/jib
--- a/share/examples/jails/jib
+++ b/usr.sbin/jib/jib
@@ -205,7 +205,7 @@
#
# The formula I'm using is ``NP:SS:SS:II:II:II'' where:
# + N denotes 4 bits used as a counter to support branching
- # each parent interface up to 15 times under the same jail
+ # each parent interface up to 16 times under the same jail
# name (see S below).
# + P denotes the special nibble whose value, if one of
# 2, 6, A, or E (but usually 2) denotes a privately
@@ -342,7 +342,7 @@
jib_show_usage="show"
jib_show_descr="List possible NAME values for \`show NAME'"
jib_show1_usage="show NAME"
-jib_show1_descr="Lists e0b_NAME [e1b_NAME ...]"
+jib_show1_descr="Lists e0a_NAME [e1a_NAME ...]"
jib_show2_usage="show [NAME]"
jib_show()
{
diff --git a/usr.sbin/jib/jib.8 b/usr.sbin/jib/jib.8
new file mode 100644
--- /dev/null
+++ b/usr.sbin/jib/jib.8
@@ -0,0 +1,319 @@
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.\" Copyright (c) 2016-2026 Devin Teske
+.\"
+.Dd September 6, 2026
+.Dt JIB 8
+.Os
+.Sh NAME
+.Nm jib
+.Nd "if_bridge(4) and epair(4) management for vnet jails"
+.Sh SYNOPSIS
+.Nm
+.Op Fl hv
+.Ar action
+.Op Ar arguments
+.Nm
+.Cm addm
+.Op Fl b Ar bridge_name
+.Ar name
+.Oo Li \&! Oc Ns Ar iface ...
+.Nm
+.Cm show
+.Op Ar name
+.Nm
+.Cm destroy
+.Ar name
+.Sh DESCRIPTION
+The
+.Nm
+utility creates and destroys
+.Xr epair 4
+interfaces attached to
+.Xr if_bridge 4
+for
+.Xr jail 8
+instances that use
+.Va vnet .
+It is intended to run from
+.Va exec.prestart
+and
+.Va exec.poststop
+in
+.Xr jail.conf 5
+.Po
+or the equivalent
+.Xr rc.conf 5
+.Dq legacy
+jail variables
+.Pc .
+.Pp
+For each parent interface given to
+.Cm addm ,
+.Nm
+brings the parent up, creates a bridge by appending the suffix
+.Ql Li bridge
+to the parent name
+.Pq for example Li em0bridge
+if one does not already exist, creates an
+.Xr epair 4
+pair, adds the host side to the bridge, and renames the ends
+.Li e Ns Ar N Ns Li a_ Ns Ar name
+.Pq host
+and
+.Li e Ns Ar N Ns Li b_ Ns Ar name
+.Pq jail .
+The jail configuration should list the
+.Li b
+side in
+.Va vnet.interface
+.Pq Xr jail.conf 5
+or
+.Va jail_ Ns Ar name Ns Va _vnet_interface
+.Pq Xr rc.conf 5 .
+.Pp
+.Nm
+cannot express every topology.
+It covers the common bridged-vnet case.
+.Sh OPTIONS
+.Bl -tag -width indent
+.It Fl h
+Print usage statement and exit.
+.It Fl v
+Print version information and exit.
+.El
+.Sh ACTIONS
+.Bl -tag -width indent
+.It Xo
+.Cm addm
+.Op Fl b Ar bridge_name
+.Ar name
+.Oo Li \&! Oc Ns Ar iface ...
+.Xc
+Create
+.Li e0b_ Ns Ar name ,
+.Li e1b_ Ns Ar name ,
+\&... for each parent interface.
+Must be run as root.
+.Pp
+.Bl -tag -width indent -compact
+.It Fl b Ar bridge_name
+Suffix used to name the bridge
+.Pq default Ql Cm bridge ,
+so parent
+.Li em0
+yields
+.Li em0bridge .
+.It Li \&! Ns Ar iface
+Do not run the multi-node MAC derivation described under
+.Sx MAC ADDRESSES .
+The kernel-generated
+.Xr ether_gen_addr 9
+address stays on the wire instead of moving to
+.Cm hwaddr .
+.El
+.It Cm show
+List jail
+.Ar name
+values that currently have
+.Nm
+interfaces.
+.It Cm show Ar name
+List
+.Li e Ns Ar N Ns Li a_ Ns Ar name
+interfaces for
+.Ar name .
+.It Cm destroy Ar name
+Destroy the
+.Xr epair 4
+interfaces created for
+.Ar name .
+Must be run as root.
+.El
+.Sh MAC ADDRESSES
+By default,
+.Nm
+sets a derived link-level address on both ends of each
+.Xr epair 4
+so that the same jail name can be started on more than one host without
+producing a duplicate MAC on a shared L2 segment.
+.Pp
+The derived address has the form
+.Li NP:SS:SS:II:II:II :
+.Bl -tag -width indent
+.It N
+A 4-bit branch counter, allowing the same parent interface to be presented
+up to 16 times under one jail name.
+.It P
+The locally administered unicast nibble
+.Pq typically 2, 6, A, or E .
+.It S
+16 bits from
+.Xr sum 1
+of the jail
+.Ar name ,
+so renaming the jail
+.Pq or moving it
+yields a new address, while changing
+only the epair instance number does not.
+.It I
+The last three octets inherited from the parent interface.
+.El
+.Pp
+Keeping the
+.Fx
+Foundation OUI
+.Pq Dq 58:9c:fc
+on the wire is supported with
+.Ql \&!
+but is not the default.
+A fixed vendor OUI consumes the bits
+.Nm
+uses for the branch counter and parent inheritance.
+Without inheritance, two hosts that start a jail of the same name derive
+the same address and a switch will see a flap.
+Unlike
+.Xr bhyve 8
+orchestrators,
+.Nm
+is stateless and does not keep a MAC database.
+.Pp
+Prefix
+.Ar iface
+with
+.Ql \&!
+to skip derivation.
+The address assigned at
+.Xr epair 4
+clone time remains the on-wire address.
+With
+.Va net.link.epair.ether_gen_addr Ns =1
+that is a stable address in the Foundation OUI from
+.Xr ether_gen_addr 9 ;
+see
+.Xr epair 4 .
+On
+.Fx 14
+that tunable defaults to 0
+.Pq a random locally administered address
+and must be set to 1 for the Foundation OUI.
+.Fx 15.0
+and later default to 1.
+.Pp
+When derivation
+.Em does
+run,
+.Xr ifconfig 8 Cm ether
+moves the clone-time address to
+.Cm hwaddr
+and places the derived address on the wire.
+.Sh EXAMPLES
+A typical
+.Xr jail.conf 5
+stanza:
+.Bd -literal -offset indent
+xxx {
+ host.hostname = "xxx.yyy";
+ path = "/vm/xxx";
+
+ vnet;
+ vnet.interface = e0b_xxx, e1b_xxx;
+
+ exec.clean;
+ exec.system_user = "root";
+ exec.jail_user = "root";
+
+ exec.prestart += "jib addm xxx em0 em1";
+ exec.poststop += "jib destroy xxx";
+
+ exec.start += "/bin/sh /etc/rc";
+ exec.stop = "/bin/sh /etc/rc.shutdown jail";
+ exec.consolelog = "/var/log/jail_xxx_console.log";
+ mount.devfs;
+}
+.Ed
+.Pp
+The number of
+.Li e Ns Ar N Ns Li b_ Ns Ar name
+values in
+.Va vnet.interface
+must match the number of parent interfaces given to
+.Cm addm .
+In
+.Xr rc.conf 5
+.Dq legacy
+form
+.Po
+used when
+.Pa /etc/jail.conf
+does not exist; converted to
+.Pa /var/run/jail. Ns Ar name Ns Pa .conf
+by
+.Pa /etc/rc.d/jail
+.Pc ,
+that list is
+.Va jail_ Ns Ar name Ns Va _vnet_interface .
+See
+.Pa /usr/share/examples/jails/
+for samples.
+.Pp
+To leave the Foundation OUI on the wire:
+.Bd -literal -offset indent
+exec.prestart += "jib addm xxx !em0";
+.Ed
+.Ss DHCP inside the jail
+To allow
+.Xr dhclient 8
+to work inside a vnet jail, create
+.Pa /etc/devfs.rules
+if needed:
+.Bd -literal -offset indent
+[devfsrules_jail=11]
+add include $devfsrules_hide_all
+add include $devfsrules_unhide_basic
+add include $devfsrules_unhide_login
+add path 'bpf*' unhide
+.Ed
+.Pp
+and set
+.Va devfs_ruleset Ns = Ns Ql 11
+in
+.Xr jail.conf 5 ,
+or
+.Va jail_ Ns Ar name Ns Va _devfs_ruleset Ns = Ns Ql 11
+in
+.Xr rc.conf 5 .
+.Sh FILES
+.Bl -tag -width "/usr/share/examples/jails/" -compact
+.It Pa /usr/share/examples/jails/
+Sample
+.Xr jail.conf 5
+and
+.Xr rc.conf 5
+stanzas.
+.El
+.Sh SEE ALSO
+.Xr sum 1 ,
+.Xr epair 4 ,
+.Xr if_bridge 4 ,
+.Xr jail.conf 5 ,
+.Xr rc.conf 5 ,
+.Xr dhclient 8 ,
+.Xr ifconfig 8 ,
+.Xr jail 8 ,
+.Xr jng 8 ,
+.Xr ether_gen_addr 9
+.Sh HISTORY
+The
+.Nm
+utility first appeared in
+.Fx 11.0
+as
+.Pa /usr/share/examples/jails/jib
+and was moved to
+.Pa /usr/sbin
+in
+.Fx 16.0 .
+.Sh AUTHORS
+.An Devin Teske Aq Mt dteske@FreeBSD.org
diff --git a/usr.sbin/jng/Makefile b/usr.sbin/jng/Makefile
new file mode 100644
--- /dev/null
+++ b/usr.sbin/jng/Makefile
@@ -0,0 +1,6 @@
+PACKAGE= jail
+
+SCRIPTS= jng
+MAN= jng.8
+
+.include <bsd.prog.mk>
diff --git a/share/examples/jails/jng b/usr.sbin/jng/jng
rename from share/examples/jails/jng
rename to usr.sbin/jng/jng
--- a/share/examples/jails/jng
+++ b/usr.sbin/jng/jng
@@ -262,7 +262,7 @@
#
# The formula used is ``NP:SS:SS:II:II:II'' where:
# + N denotes 4 bits used as a counter to support branching
- # each parent interface up to 15 times under the same jail
+ # each parent interface up to 16 times under the same jail
# name (see S below).
# + P denotes the special nibble whose value, if one of
# 2, 6, A, or E (but usually 2) denotes a privately
diff --git a/usr.sbin/jng/jng.8 b/usr.sbin/jng/jng.8
new file mode 100644
--- /dev/null
+++ b/usr.sbin/jng/jng.8
@@ -0,0 +1,491 @@
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.\" Copyright (c) 2016-2026 Devin Teske
+.\"
+.Dd September 7, 2026
+.Dt JNG 8
+.Os
+.Sh NAME
+.Nm jng
+.Nd "netgraph(4) management for vnet jails"
+.Sh SYNOPSIS
+.Nm
+.Op Fl hv
+.Ar action
+.Op Ar arguments
+.Nm
+.Cm bridge
+.Op Fl b Ar bridge_name
+.Ar name
+.Oo Li \&! Ns | Ns Li = Oc Ns Ar iface ...
+.Nm
+.Cm pin
+.Brq Fl a | Ar name ...
+.Nm
+.Cm graph
+.Op Fl f
+.Op Fl T Ar type
+.Op Fl o Ar output
+.Nm
+.Cm show
+.Op Ar name ...
+.Nm
+.Cm shutdown
+.Ar name ...
+.Nm
+.Cm stats
+.Op Fl j
+.Brq Fl a | Ar name ...
+.Sh DESCRIPTION
+The
+.Nm
+utility creates and destroys
+.Xr ng_eiface 4
+interfaces attached to
+.Xr ng_bridge 4
+for
+.Xr jail 8
+instances that use
+.Va vnet .
+It is intended to run from
+.Va exec.prestart
+and
+.Va exec.poststop
+in
+.Xr jail.conf 5
+.Po
+or the equivalent
+.Xr rc.conf 5
+.Dq legacy
+jail variables
+.Pc .
+.Pp
+Unlike
+.Xr jib 8 ,
+which uses
+.Xr if_bridge 4
+and
+.Xr epair 4 ,
+.Nm
+uses netgraph as the virtual networking fabric.
+The
+.Xr ng_ether 4
+module must be loaded
+.Pq it is not loaded on demand .
+.Xr ng_bridge 4
+and
+.Xr ng_eiface 4
+load with it as needed.
+.Bd -literal -offset indent
+sysrc kld_list+=ng_ether
+kldload ng_ether
+.Ed
+.Pp
+For each parent interface given to
+.Cm bridge ,
+.Nm
+brings the parent up, attaches an
+.Xr ng_bridge 4
+on the
+.Xr ng_ether 4
+.Li lower
+hook as
+.Li uplink
+if one does not already exist, creates an
+.Xr ng_eiface 4 ,
+and renames it
+.Li ng Ns Ar N Ns Li _ Ns Ar name .
+The jail configuration should list that name in
+.Va vnet.interface
+.Pq Xr jail.conf 5
+or
+.Va jail_ Ns Ar name Ns Va _vnet_interface
+.Pq Xr rc.conf 5 .
+.Pp
+Return each interface to the host in
+.Va exec.prestop
+with
+.Xr ifconfig 8
+.Cm -vnet
+so the kernel does not move it during jail removal
+.Pq a BPF race
+and destroy it in
+.Va exec.poststop
+with
+.Cm shutdown .
+.Pp
+Uplink on
+.Xr ng_ether 4
+.Li lower
+keeps the WAN MAC table small:
+.Xr ng_bridge 4
+does not learn on uplink hooks.
+The first connected hook being uplink also selects restrictive unknown-unicast:
+frames for an unknown destination go only to uplink, not to jail links.
+Inbound unicast to a jail therefore requires that jail's MAC to live in the
+forwarding database
+.Pq FDB
+on the jail's link.
+.Nm
+pins each eiface MAC with
+.Xr ngctl 8
+.Cm movehost
+and sets
+.Va maxStaleness
+so
+.Li host->staleness
+cannot age it out.
+.Cm pin
+replants after an accidental move.
+.Pp
+.Nm
+cannot express every topology.
+It covers the common bridged-vnet case.
+.Sh OPTIONS
+.Bl -tag -width indent
+.It Fl h
+Print usage statement and exit.
+.It Fl v
+Print version information and exit.
+.El
+.Sh ACTIONS
+All actions must be run as root.
+.Bl -tag -width indent
+.It Xo
+.Cm bridge
+.Op Fl b Ar bridge_name
+.Ar name
+.Oo Li \&! Ns | Ns Li = Oc Ns Ar iface ...
+.Xc
+Create
+.Li ng0_ Ns Ar name ,
+.Li ng1_ Ns Ar name ,
+\&... for each parent interface.
+.Pp
+.Bl -tag -width indent -compact
+.It Fl b Ar bridge_name
+Suffix for a secondary
+.Xr ng_bridge 4
+on that parent, so
+.Li em0
+with
+.Ql Fl b Ar private
+yields
+.Li em0private .
+Eifaces attach there instead of to the default
+.Li em0bridge
+on the parent's
+.Li lower
+hook.
+That node has its own
+.Xr ng_bridge 4
+configuration, independent of the WAN bridge.
+.It Li \&! Ns Ar iface
+Do not run the multi-node MAC derivation described under
+.Sx MAC ADDRESSES .
+The kernel-generated
+.Xr ether_gen_addr 9
+address stays on the wire instead of moving to
+.Cm hwaddr .
+.It Li = Ns Ar iface
+Set the eiface MAC to a copy of the parent interface's on-wire address.
+.El
+.It Xo
+.Cm pin
+.Brq Fl a | Ar name ...
+.Xc
+Pin eiface MACs into the
+.Xr ng_bridge 4
+FDB.
+.Ql Fl a
+pins every running jail that has
+.Nm
+interfaces.
+.It Xo
+.Cm graph
+.Op Fl f
+.Op Fl T Ar type
+.Op Fl o Ar output
+.Xc
+Write a netgraph diagram via
+.Xr ngctl 8
+.Cm dot
+and the Graphviz
+.Xr dot 1
+utility.
+The default output file is
+.Pa jng.svg .
+.Ql Fl f
+overwrites an existing file.
+.It Cm show
+List jail
+.Ar name
+values that currently have
+.Nm
+interfaces.
+.It Cm show Ar name ...
+List
+.Li ng Ns Ar N Ns Li _ Ns Ar name
+interfaces for each
+.Ar name .
+.It Cm shutdown Ar name ...
+Shut down the
+.Xr ng_eiface 4
+nodes created for each
+.Ar name .
+.It Xo
+.Cm stats
+.Op Fl j
+.Brq Fl a | Ar name ...
+.Xc
+Show
+.Xr ng_bridge 4
+link statistics.
+A parent interface reports
+.Li lower
+and
+.Li upper
+on its default bridge.
+A jail name reports each eiface's link.
+.Ql Fl a
+covers every bridged
+.Xr ng_ether 4
+device and every
+.Nm
+jail name.
+.Ql Fl j
+prints JSON.
+.El
+.Sh MAC ADDRESSES
+By default,
+.Nm
+sets a derived link-level address on each
+.Xr ng_eiface 4
+so that the same jail name can be started on more than one host without
+producing a duplicate MAC on a shared L2 segment.
+.Pp
+The derived address has the form
+.Li NP:SS:SS:II:II:II :
+.Bl -tag -width indent
+.It N
+A 4-bit branch counter, allowing the same parent interface to be presented
+up to 16 times under one jail name.
+.It P
+The locally administered unicast nibble
+.Pq typically 2, 6, A, or E .
+.It S
+16 bits from
+.Xr sum 1
+of the jail
+.Ar name ,
+so renaming the jail
+.Pq or moving it
+yields a new address, while changing
+only the eiface instance number does not.
+.It I
+The last three octets inherited from the parent interface.
+.El
+.Pp
+Keeping the
+.Fx
+Foundation OUI
+.Pq Dq 58:9c:fc
+on the wire is supported with
+.Ql \&!
+but is not the default.
+A fixed vendor OUI consumes the bits
+.Nm
+uses for the branch counter and parent inheritance.
+Without inheritance, two hosts that start a jail of the same name derive
+the same address and a switch will see a flap.
+Unlike
+.Xr bhyve 8
+orchestrators,
+.Nm
+is stateless and does not keep a MAC database.
+.Pp
+Prefix
+.Ar iface
+with
+.Ql \&!
+to skip derivation.
+The address assigned when the
+.Xr ng_eiface 4
+is created remains the on-wire address: a stable address in the Foundation
+OUI from
+.Xr ether_gen_addr 9 .
+.Xr ng_eiface 4
+always uses
+.Xr ether_gen_addr 9
+.Pq there is no epair-style sysctl .
+When derivation
+.Em does
+run,
+.Xr ifconfig 8 Cm ether
+moves the create-time address to
+.Cm hwaddr
+and places the derived address on the wire.
+.Pp
+Prefix
+.Ar iface
+with
+.Ql =
+to copy the parent interface's MAC onto the eiface instead.
+.Sh EXAMPLES
+A typical
+.Xr jail.conf 5
+stanza:
+.Bd -literal -offset indent
+xxx {
+ host.hostname = "xxx.yyy";
+ path = "/vm/$name";
+
+ vnet;
+ vnet.interface = ng0_$name, ng1_$name;
+
+ exec.clean;
+ exec.system_user = "root";
+ exec.jail_user = "root";
+
+ exec.prestart += "jng bridge $name em0 em1";
+ exec.prestop += "ifconfig ng0_$name -vnet $name";
+ exec.prestop += "ifconfig ng1_$name -vnet $name";
+ exec.poststop += "jng shutdown $name";
+
+ exec.start += "/bin/sh /etc/rc";
+ exec.stop = "/bin/sh /etc/rc.shutdown jail";
+ exec.consolelog = "/var/log/jail_${name}_console.log";
+ mount.devfs;
+}
+.Ed
+.Pp
+The number of
+.Li ng Ns Ar N Ns Li _ Ns Ar name
+values in
+.Va vnet.interface
+must match the number of parent interfaces given to
+.Cm bridge ,
+and each must be returned to the host in
+.Va exec.prestop .
+In
+.Xr rc.conf 5
+.Dq legacy
+form
+.Po
+used when
+.Pa /etc/jail.conf
+does not exist; converted to
+.Pa /var/run/jail. Ns Ar name Ns Pa .conf
+by
+.Pa /etc/rc.d/jail
+.Pc ,
+that list is
+.Va jail_ Ns Ar name Ns Va _vnet_interface .
+See
+.Pa /usr/share/examples/jails/
+for samples.
+.Pp
+To leave the Foundation OUI on the wire:
+.Bd -literal -offset indent
+exec.prestart += "jng bridge $name !em0";
+.Ed
+.Pp
+To attach eifaces to a secondary
+.Xr ng_bridge 4
+that can be configured apart from the WAN node, define the
+.Cm setconfig
+fields once in
+.Xr jail.conf 5
+and reuse them:
+.Bd -literal -offset indent
+$dL = "debugLevel";
+$lT = "loopTimeout";
+$mS = "maxStaleness";
+$mSA = "minStableAge";
+$debug_cfg = "$dL=2 $lT=60 $mS=900 $mSA=1";
+.Pp
+exec.prestart += "jng bridge -b debug $name em0";
+exec.prestart += "ngctl msg em0debug: setconfig '{ $debug_cfg }'";
+.Ed
+.Pp
+Each jail that uses that suffix on the same parent shares
+.Li em0debug .
+.Xr ngctl 8
+.Cm setconfig
+is per node: the last jail to start or restart wins.
+Expanding one variable from every such stanza keeps the values from drifting.
+The
+.Va exec.prestart
+string is double-quoted so
+.Li $debug_cfg
+expands; single quotes around the
+.Cm setconfig
+argument keep it one word for the shell.
+.Cm setconfig
+replaces the whole node config; fields not named default to 0.
+The values above are
+.Xr ng_bridge 4
+defaults except
+.Ql Va debugLevel Ns = Ns 2
+.Pq log detected loops .
+This does not change
+.Li em0bridge .
+.Ss DHCP inside the jail
+To allow
+.Xr dhclient 8
+to work inside a vnet jail, create
+.Pa /etc/devfs.rules
+if needed:
+.Bd -literal -offset indent
+[devfsrules_jail=11]
+add include $devfsrules_hide_all
+add include $devfsrules_unhide_basic
+add include $devfsrules_unhide_login
+add path 'bpf*' unhide
+.Ed
+.Pp
+and set
+.Va devfs_ruleset Ns = Ns Ql 11
+in
+.Xr jail.conf 5 ,
+or
+.Va jail_ Ns Ar name Ns Va _devfs_ruleset Ns = Ns Ql 11
+in
+.Xr rc.conf 5 .
+.Sh FILES
+.Bl -tag -width "/usr/share/examples/jails/" -compact
+.It Pa /usr/share/examples/jails/
+Sample
+.Xr jail.conf 5
+and
+.Xr rc.conf 5
+stanzas.
+.El
+.Sh SEE ALSO
+.Xr sum 1 ,
+.Xr netgraph 4 ,
+.Xr ng_bridge 4 ,
+.Xr ng_eiface 4 ,
+.Xr ng_ether 4 ,
+.Xr jail.conf 5 ,
+.Xr rc.conf 5 ,
+.Xr dhclient 8 ,
+.Xr ifconfig 8 ,
+.Xr jail 8 ,
+.Xr jib 8 ,
+.Xr ngctl 8 ,
+.Xr ether_gen_addr 9
+.Sh HISTORY
+The
+.Nm
+utility first appeared in
+.Fx 11.0
+as
+.Pa /usr/share/examples/jails/jng
+and was moved to
+.Pa /usr/sbin
+in
+.Fx 16.0 .
+.Sh AUTHORS
+.An Devin Teske Aq Mt dteske@FreeBSD.org

File Metadata

Mime Type
text/plain
Expires
Fri, Oct 2, 4:25 AM (22 h, 37 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
40029133
Default Alt Text
D59474.diff (23 KB)

Event Timeline