3 # Copyright (c) 2016 Devin Teske
6 # Redistribution and use in source and binary forms, with or without
7 # modification, are permitted provided that the following conditions
9 # 1. Redistributions of source code must retain the above copyright
10 # notice, this list of conditions and the following disclaimer.
11 # 2. Redistributions in binary form must reproduce the above copyright
12 # notice, this list of conditions and the following disclaimer in the
13 # documentation and/or other materials provided with the distribution.
15 # THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16 # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 # ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19 # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 # OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 # HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 # LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29 ############################################################ IDENT(1)
31 # $Title: if_bridge(4) management script for vnet jails $
33 ############################################################ INFORMATION
35 # Use this tool with jail.conf(5) (or rc.conf(5) ``legacy'' configuration) to
36 # manage `vnet' interfaces for jails. Designed to automate the creation of vnet
37 # interface(s) during jail `prestart' and destroy said interface(s) during jail
40 # In jail.conf(5) format:
42 # ### BEGIN EXCERPT ###
45 # host.hostname = "xxx.yyy";
49 # # NB: Below 2-lines required
50 # # NB: The number of eNb_xxx interfaces should match the number of
51 # # arguments given to `jib addm xxx' in exec.prestart value.
54 # vnet.interface = "e0b_xxx e1b_xxx ...";
57 # exec.system_user = "root";
58 # exec.jail_user = "root";
61 # # NB: Below 2-lines required
62 # # NB: The number of arguments after `jib addm xxx' should match
63 # # the number of eNb_xxx arguments in vnet.interface value.
65 # exec.prestart += "jib addm xxx em0 em1 ...";
66 # exec.poststop += "jib destroy xxx";
69 # exec.start += "/bin/sh /etc/rc";
70 # exec.stop = "/bin/sh /etc/rc.shutdown";
71 # exec.consolelog = "/var/log/jail_xxx_console.log";
74 # # Optional (default off)
76 # #allow.set_hostname = 1;
78 # #devfs_ruleset = "11"; # rule to unhide bpf for DHCP
83 # In rc.conf(5) ``legacy'' format (used when /etc/jail.conf does not exist):
85 # ### BEGIN EXCERPT ###
91 # # Global presets for all jails
93 # jail_devfs_enable="YES" # mount devfs
96 # # Global options (default off)
98 # #jail_mount_enable="YES" # mount /etc/fstab.{name}
99 # #jail_set_hostname_allow="YES" # Allow hostname to change
100 # #jail_sysvipc_allow="YES" # Allow SysV Interprocess Comm.
103 # jail_xxx_hostname="xxx.shxd.cx" # hostname
104 # jail_xxx_rootdir="/vm/xxx" # root directory
105 # jail_xxx_vnet_interfaces="e0b_xxx e1bxxx ..." # vnet interface(s)
106 # jail_xxx_exec_prestart0="jib addm xxx em0 em1 ..." # bridge interface(s)
107 # jail_xxx_exec_poststop0="jib destroy xxx" # destroy interface(s)
108 # #jail_xxx_mount_enable="YES" # mount /etc/fstab.xxx
109 # #jail_xxx_devfs_ruleset="11" # rule to unhide bpf for DHCP
111 # ### END EXCERPT ###
113 # Note that the legacy rc.conf(5) format is converted to
114 # /var/run/jail.{name}.conf by /etc/rc.d/jail if jail.conf(5) is missing.
116 # ASIDE: dhclient(8) inside a vnet jail...
118 # To allow dhclient(8) to work inside a vnet jail, make sure the following
119 # appears in /etc/devfs.rules (which should be created if it doesn't exist):
121 # [devfsrules_jail=11]
122 # add include $devfsrules_hide_all
123 # add include $devfsrules_unhide_basic
124 # add include $devfsrules_unhide_login
125 # add path 'bpf*' unhide
127 # And set ether devfs.ruleset="11" (jail.conf(5)) or
128 # jail_{name}_devfs_ruleset="11" (rc.conf(5)).
130 # NB: While this tool can't create every type of desirable topology, it should
131 # handle most setups, minus some which considered exotic or purpose-built.
133 ############################################################ GLOBALS
135 pgm="${0##*/}" # Program basename
143 ############################################################ FUNCTIONS
147 local action usage descr
149 echo "Usage: $pgm action [arguments]"
157 eval usage=\"\$jib_${action}_usage\"
158 [ "$usage" ] || continue
159 eval descr=\"\$jib_${action}_descr\"
160 printf "\t%s\n\t\t%s\n" "$usage" "$descr"
167 local usage descr action="$1"
168 eval usage=\"\$jib_${action}_usage\"
169 echo "Usage: $pgm $usage" >&2
170 eval descr=\"\$jib_${action}_descr\"
171 printf "\t%s\n" "$descr"
177 local OPTIND=1 OPTARG __flag
178 local __mac_num= __make_pair=
179 while getopts 2n: __flag; do
182 n) __mac_num=${OPTARG%%[^0-9]*} ;;
185 shift $(( $OPTIND - 1 ))
187 if [ ! "$__mac_num" ]; then
188 eval __mac_num=\${_${iface}_num:--1}
189 __mac_num=$(( $__mac_num + 1 ))
190 eval _${iface}_num=\$__mac_num
193 local __iface="$1" __name="$2" __var_to_set="$3" __var_to_set_b="$4"
194 local __iface_devid __new_devid __num __new_devid_b
196 # Calculate MAC address derived from given iface.
198 # The formula I'm using is ``NP:SS:SS:II:II:II'' where:
199 # + N denotes 4 bits used as a counter to support branching
200 # each parent interface up to 15 times under the same jail
201 # name (see S below).
202 # + P denotes the special nibble whose value, if one of
203 # 2, 6, A, or E (but usually 2) denotes a privately
204 # administered MAC address (while remaining routable).
205 # + S denotes 16 bits, the sum(1) value of the jail name.
206 # + I denotes bits that are inherited from parent interface.
208 # The S bits are a CRC-16 checksum of NAME, allowing the jail
209 # to change link numbers in ng_bridge(4) without affecting the
210 # MAC address. Meanwhile, if...
211 # + the jail NAME changes (e.g., it was duplicated and given
212 # a new name with no other changes)
213 # + the underlying network interface changes
214 # + the jail is moved to another host
215 # the MAC address will be recalculated to a new, similarly
216 # unique value preventing conflict.
218 __iface_devid=$( ifconfig $__iface ether | awk '/ether/,$0=$2' )
220 __new_devid=${__iface_devid#??:??:??} # => :II:II:II
222 __num=$( set -- `echo -n "$__name" | sum` && echo $1 )
223 __new_devid=$( printf :%02x:%02x \
224 $(( $__num >> 8 & 255 )) $(( $__num & 255 )) )$__new_devid
225 # => P:SS:SS:II:II:II
226 case "$__iface_devid" in
227 ?2:*) __new_devid=a$__new_devid __new_devid_b=e$__new_devid ;;
228 ?[Ee]:*) __new_devid=2$__new_devid __new_devid_b=6$__new_devid ;;
229 *) __new_devid=2$__new_devid __new_devid_b=e$__new_devid
231 # => NP:SS:SS:II:II:II
232 __new_devid=$( printf %x $(( $__mac_num & 15 )) )$__new_devid
233 __new_devid_b=$( printf %x $(( $__mac_num & 15 )) )$__new_devid_b
236 # Return derivative MAC address(es)
238 if [ "$__make_pair" ]; then
239 if [ "$__var_to_set" -a "$__var_to_set_b" ]; then
240 eval $__var_to_set=\$__new_devid
241 eval $__var_to_set_b=\$__new_devid_b
243 echo $__new_devid $__new_devid_b
246 if [ "$__var_to_set" ]; then
247 eval $__var_to_set=\$__new_devid
254 mustberoot_to_continue()
256 if [ "$( id -u )" -ne 0 ]; then
257 echo "Must run as root!" >&2
262 jib_addm_usage="addm [-b BRIDGE_NAME] NAME [!]iface0 [[!]iface1 ...]"
263 jib_addm_descr="Creates e0b_NAME [e1b_NAME ...]"
266 local OPTIND=1 OPTARG flag bridge=bridge
267 while getopts b: flag; do
269 b) bridge="${OPTARG:-bridge}" ;;
270 *) action_usage addm # NOTREACHED
273 shift $(( $OPTIND - 1 ))
276 [ "${name:-x}" = "${name#*[!0-9a-zA-Z_]}" -a $# -gt 1 ] ||
277 action_usage addm # NOTREACHED
280 mustberoot_to_continue
282 local iface eiface_devid_a eiface_devid_b
283 local new no_derive num quad i=0
288 !*) iface=${iface#!} no_derive=1 ;;
291 # Make sure the interface doesn't exist already
292 if ifconfig "e${i}a_$name" > /dev/null 2>&1; then
297 # Bring the interface up
298 ifconfig $iface up || return
300 # Make sure the interface has been bridged
301 if ! ifconfig "$iface$bridge" > /dev/null 2>&1; then
302 new=$( ifconfig bridge create ) || return
303 ifconfig $new addm $iface || return
304 ifconfig $new name "$iface$bridge" || return
305 ifconfig "$iface$bridge" up || return
308 # Create a new interface to the bridge
309 new=$( ifconfig epair create ) || return
310 ifconfig "$iface$bridge" addm $new || return
312 # Rename the new interface
313 ifconfig $new name "e${i}a_$name" || return
314 ifconfig ${new%a}b name "e${i}b_$name" || return
315 ifconfig "e${i}a_$name" up || return
316 ifconfig "e${i}b_$name" up || return
319 # Set the MAC address of the new interface using a sensible
320 # algorithm to prevent conflicts on the network.
322 eiface_devid_a= eiface_devid_b=
323 [ "$no_derive" ] || derive_mac -2 $iface "$name" \
324 eiface_devid_a eiface_devid_b
325 if [ "$eiface_devid_a" -a "$eiface_devid_b" ]; then
326 ifconfig "e${i}a_$name" ether $eiface_devid_a
327 ifconfig "e${i}b_$name" ether $eiface_devid_b
334 jib_show_usage="show"
335 jib_show_descr="List possible NAME values for \`show NAME'"
336 jib_show1_usage="show NAME"
337 jib_show1_descr="Lists e0b_NAME [e1b_NAME ...]"
338 jib_show2_usage="show [NAME]"
341 local OPTIND=1 OPTARG flag
342 while getopts "" flag; do
344 *) action_usage show2 # NOTREACHED
347 shift $(( $OPTIND - 1 ))
348 if [ $# -eq 0 ]; then
352 sub(/:.*/, "", iface)
356 for (n = split($0, group); n > 1; n--) {
357 if (group[n] != "bridge") continue
362 xargs -rn1 ifconfig |
363 awk '$1 == "member:" &&
364 sub(/^e[[:digit:]]+a_/, "", $2), $0 = $2' |
368 ifconfig | awk -v name="$1" '
369 match($0, /^e[[:digit:]]+a_/) && sub(/:.*/, "") &&
370 substr($1, RSTART + RLENGTH) == name
374 jib_destroy_usage="destroy NAME"
375 jib_destroy_descr="Destroy e0b_NAME [e1b_NAME ...]"
378 local OPTIND=1 OPTARG flag
379 while getopts "" flag; do
381 *) action_usage destroy # NOTREACHED
384 shift $(( $OPTIND -1 ))
386 [ "${name:-x}" = "${name#*[!0-9a-zA-Z_]}" -a $# -eq 1 ] ||
387 action_usage destroy # NOTREACHED
388 mustberoot_to_continue
389 jib_show "$name" | xargs -rn1 -I eiface ifconfig eiface destroy
392 ############################################################ MAIN
395 # Command-line arguments
398 [ "$action" ] || usage # NOTREACHED
401 # Validate action argument
403 if [ "$BASH_VERSION" ]; then
404 type="$( type -t "jib_$action" )" || usage # NOTREACHED
406 type="$( type "jib_$action" 2> /dev/null )" || usage # NOTREACHED
411 eval "jib_$action" \"\$@\"
413 *) usage # NOTREACHED
416 ################################################################################
418 ################################################################################