xref: /freebsd/share/examples/jails/jng (revision 839529caa9c35f92b638dbe074655598e7a6bb6f)
1#!/bin/sh
2#-
3# Copyright (c) 2016 Devin Teske
4# All rights reserved.
5#
6# Redistribution and use in source and binary forms, with or without
7# modification, are permitted provided that the following conditions
8# are met:
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.
14#
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
25# SUCH DAMAGE.
26#
27# $FreeBSD$
28#
29############################################################ IDENT(1)
30#
31# $Title: netgraph(4) management script for vnet jails $
32#
33############################################################ INFORMATION
34#
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
38# `poststop'.
39#
40# In jail.conf(5) format:
41#
42# ### BEGIN EXCERPT ###
43#
44# xxx {
45# 	host.hostname = "xxx.yyy";
46# 	path = "/vm/xxx";
47#
48# 	#
49# 	# NB: Below 2-lines required
50# 	# NB: The number of ngN_xxx interfaces should match the number of
51# 	#     arguments given to `jng bridge xxx' in exec.prestart value.
52# 	#
53# 	vnet;
54# 	vnet.interface = "ng0_xxx ng1_xxx ...";
55#
56# 	exec.clean;
57# 	exec.system_user = "root";
58# 	exec.jail_user = "root";
59#
60# 	#
61# 	# NB: Below 2-lines required
62# 	# NB: The number of arguments after `jng bridge xxx' should match
63# 	#     the number of ngN_xxx arguments in vnet.interface value.
64# 	#
65# 	exec.prestart += "jng bridge xxx em0 em1 ...";
66# 	exec.poststop += "jng shutdown xxx";
67#
68# 	# Standard recipe
69# 	exec.start += "/bin/sh /etc/rc";
70# 	exec.stop = "/bin/sh /etc/rc.shutdown";
71# 	exec.consolelog = "/var/log/jail_xxx_console.log";
72# 	mount.devfs;
73#
74# 	# Optional (default off)
75# 	#allow.mount;
76# 	#allow.set_hostname = 1;
77# 	#allow.sysvipc = 1;
78# 	#devfs_ruleset = "11"; # rule to unhide bpf for DHCP
79# }
80#
81# ### END EXCERPT ###
82#
83# In rc.conf(5) ``legacy'' format (used when /etc/jail.conf does not exist):
84#
85# ### BEGIN EXCERPT ###
86#
87# jail_enable="YES"
88# jail_list="xxx"
89#
90# #
91# # Global presets for all jails
92# #
93# jail_devfs_enable="YES"	# mount devfs
94#
95# #
96# # Global options (default off)
97# #
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.
101#
102# # xxx
103# jail_xxx_hostname="xxx.shxd.cx"		# hostname
104# jail_xxx_rootdir="/vm/xxx"			# root directory
105# jail_xxx_vnet_interfaces="ng0_xxx ng1xxx ..."	# vnet interface(s)
106# jail_xxx_exec_prestart0="jng bridge xxx em0 em1 ..."	# bridge interface(s)
107# jail_xxx_exec_poststop0="jng shutdown 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
110#
111# ### END EXCERPT ###
112#
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.
115#
116# ASIDE: dhclient(8) inside a vnet jail...
117#
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):
120#
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
126#
127# And set ether devfs.ruleset="11" (jail.conf(5)) or
128# jail_{name}_devfs_ruleset="11" (rc.conf(5)).
129#
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.
132#
133############################################################ GLOBALS
134
135pgm="${0##*/}" # Program basename
136
137#
138# Global exit status
139#
140SUCCESS=0
141FAILURE=1
142
143############################################################ FUNCTIONS
144
145usage()
146{
147	local action usage descr
148	exec >&2
149	echo "Usage: $pgm action [arguments]"
150	echo "Actions:"
151	for action in \
152		bridge		\
153		graph		\
154		show		\
155		show1		\
156		shutdown	\
157		stats		\
158	; do
159		eval usage=\"\$jng_${action}_usage\"
160		[ "$usage" ] || continue
161		eval descr=\"\$jng_${action}_descr\"
162		printf "\t%s\n\t\t%s\n" "$usage" "$descr"
163	done
164	exit $FAILURE
165}
166
167action_usage()
168{
169	local usage action="$1"
170	eval usage=\"\$jng_${action}_usage\"
171	echo "Usage: $pgm $usage" >&2
172	exit $FAILURE
173}
174
175derive_mac()
176{
177	local OPTIND=1 OPTARG __flag
178	local __mac_num= __make_pair=
179	while getopts 2n: __flag; do
180		case "$__flag" in
181		2) __make_pair=1 ;;
182		n) __mac_num=${OPTARG%%[^0-9]*} ;;
183		esac
184	done
185	shift $(( $OPTIND - 1 ))
186
187	if [ ! "$__mac_num" ]; then
188		eval __mac_num=\${_${iface}_num:--1}
189		__mac_num=$(( $__mac_num + 1 ))
190		eval _${iface}_num=\$__mac_num
191	fi
192
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
195	#
196	# Calculate MAC address derived from given iface.
197	#
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.
207	#
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.
217	#
218	__iface_devid=$( ifconfig $__iface ether | awk '/ether/,$0=$2' )
219	# ??:??:??:II:II:II
220	__new_devid=${__iface_devid#??:??:??} # => :II:II:II
221	# => :SS:SS: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
230	esac
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
234
235	#
236	# Return derivative MAC address(es)
237	#
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
242		else
243			echo $__new_devid $__new_devid_b
244		fi
245	else
246		if [ "$__var_to_set" ]; then
247			eval $__var_to_set=\$__new_devid
248		else
249			echo $__new_devid
250		fi
251	fi
252}
253
254mustberoot_to_continue()
255{
256	if [ "$( id -u )" -ne 0 ]; then
257		echo "Must run as root!" >&2
258		exit $FAILURE
259	fi
260}
261
262jng_bridge_usage="bridge [-b BRIDGE_NAME] NAME [!|=]iface0 [[!|=]iface1 ...]"
263jng_bridge_descr="Create ng0_NAME [ng1_NAME ...]"
264jng_bridge()
265{
266	local OPTIND=1 OPTARG flag bridge=bridge
267	while getopts b: flag; do
268		case "$flag" in
269		b) bridge="$OPTARG"
270		   [ "$bridge" ] || action_usage bridge ;; # NOTREACHED
271		*) action_usage bridge # NOTREACHED
272		esac
273	done
274	shift $(( $OPTIND - 1 ))
275
276	local name="$1"
277	[ "${name:-x}" = "${name#*[!0-9a-zA-Z_]}" -a $# -gt 1 ] ||
278		action_usage bridge # NOTREACHED
279	shift 1 # name
280
281	mustberoot_to_continue
282
283	local iface parent eiface eiface_devid
284	local new clone_mac no_derive num quad i=0
285	for iface in $*; do
286
287		clone_mac=
288		no_derive=
289		case "$iface" in
290		=*) iface=${iface#=} clone_mac=1 ;;
291		!*) iface=${iface#!} no_derive=1 ;;
292		esac
293
294		# Make sure the interface doesn't exist already
295		eiface=ng${i}_$name
296		if ngctl msg "$eiface:" getifname > /dev/null 2>&1; then
297			i=$(( $i + 1 ))
298			continue
299		fi
300
301		# Bring the interface up
302		ifconfig $iface up || return
303
304		# Set promiscuous mode and don't overwrite src addr
305		ngctl msg $iface: setpromisc 1 || return
306		ngctl msg $iface: setautosrc 0 || return
307
308		# Make sure the interface has been bridged
309		if ! ngctl info ${iface}bridge: > /dev/null 2>&1; then
310			ngctl mkpeer $iface: bridge lower link0 || return
311			ngctl connect $iface: $iface:lower upper link1 ||
312				return
313			ngctl name $iface:lower ${iface}bridge || return
314		fi
315
316		# Optionally create a secondary bridge
317		if [ "$bridge" != "bridge" ] &&
318		   ! ngctl info "$iface$bridge:" > /dev/null 2>&1
319		then
320			num=2
321			while ngctl msg ${iface}bridge: getstats $num \
322				> /dev/null 2>&1
323			do
324				num=$(( $num + 1 ))
325			done
326			ngctl mkpeer $iface:lower bridge link$num link1 ||
327				return
328			ngctl name ${iface}bridge:link$num "$iface$bridge" ||
329				return
330		fi
331
332		# Create a new interface to the bridge
333		num=2
334		while ngctl msg "$iface$bridge:" getstats $num > /dev/null 2>&1
335		do
336			num=$(( $num + 1 ))
337		done
338		ngctl mkpeer "$iface$bridge:" eiface link$num ether || return
339
340		# Rename the new interface
341		while [ ${#eiface} -gt 15 ]; do # OS limitation
342			eiface=${eiface%?}
343		done
344		new=$( set -- `ngctl show -n "$iface$bridge:link$num"` &&
345			echo $2 ) || return
346		ngctl name "$iface$bridge:link$num" $eiface || return
347		ifconfig $new name $eiface || return
348		ifconfig $eiface up || return
349
350		#
351		# Set the MAC address of the new interface using a sensible
352		# algorithm to prevent conflicts on the network.
353		#
354		eiface_devid=
355		if [ "$clone_mac" ]; then
356			eiface_devid=$( ifconfig $iface ether |
357				awk '/ether/,$0=$2' )
358		elif [ ! "$no_derive" ]; then
359			derive_mac $iface "$name" eiface_devid
360		fi
361		[ "$eiface_devid" ] &&
362			ifconfig $eiface ether $eiface_devid > /dev/null 2>&1
363
364		i=$(( $i + 1 ))
365	done # for iface
366}
367
368jng_graph_usage="graph [-f] [-T type] [-o output]"
369jng_graph_descr="Generate network graph (default output is \`jng.svg')"
370jng_graph()
371{
372	local OPTIND=1 OPTARG flag
373	local output=jng.svg output_type= force=
374	while getopts fo:T: flag; do
375		case "$flag" in
376		f) force=1 ;;
377		o) output="$OPTARG" ;;
378		T) output_type="$OPTARG" ;;
379		*) action_usage graph # NOTREACHED
380		esac
381	done
382	shift $(( $OPTIND - 1 ))
383	[ $# -eq 0 -a "$output" ] || action_usage graph # NOTREACHED
384	mustberoot_to_continue
385	if [ -e "$output" -a ! "$force" ]; then
386		echo "$output: Already exists (use \`-f' to overwrite)" >&2
387		return $FAILURE
388	fi
389	if [ ! "$output_type" ]; then
390		local valid suffix
391		valid=$( dot -Txxx 2>&1 )
392		for suffix in ${valid##*:}; do
393			[ "$output" != "${output%.$suffix}" ] || continue
394			output_type=$suffix
395			break
396		done
397	fi
398	ngctl dot | dot ${output_type:+-T "$output_type"} -o "$output"
399}
400
401jng_show_usage="show"
402jng_show_descr="List possible NAME values for \`show NAME'"
403jng_show1_usage="show NAME"
404jng_show1_descr="Lists ng0_NAME [ng1_NAME ...]"
405jng_show2_usage="show [NAME]"
406jng_show()
407{
408	local OPTIND=1 OPTARG flag
409	while getopts "" flag; do
410		case "$flag" in
411		*) action_usage show2 # NOTREACHED
412		esac
413	done
414	shift $(( $OPTIND - 1 ))
415	mustberoot_to_continue
416	if [ $# -eq 0 ]; then
417		ngctl ls | awk '$4=="bridge",$0=$2' |
418			xargs -rn1 -Ibridge ngctl show bridge: |
419			awk 'sub(/^ng[[:digit:]]+_/, "", $2), $0 = $2' |
420			sort -u
421		return
422	fi
423	ngctl ls | awk -v name="$1" '
424		match($2, /^ng[[:digit:]]+_/) &&
425			substr($2, RSTART + RLENGTH) == name &&
426			$4 == "eiface", $0 = $2
427	' | sort
428}
429
430jng_shutdown_usage="shutdown NAME"
431jng_shutdown_descr="Shutdown ng0_NAME [ng1_NAME ...]"
432jng_shutdown()
433{
434	local OPTIND=1 OPTARG flag
435	while getopts "" flag; do
436		case "$flag" in
437		*) action_usage shutdown # NOTREACHED
438		esac
439	done
440	shift $(( $OPTIND -1 ))
441	local name="$1"
442	[ "${name:-x}" = "${name#*[!0-9a-zA-Z_]}" -a $# -eq 1 ] ||
443		action_usage shutdown # NOTREACHED
444	mustberoot_to_continue
445	jng_show "$name" | xargs -rn1 -I eiface ngctl shutdown eiface:
446}
447
448jng_stats_usage="stats NAME"
449jng_stats_descr="Show ng_bridge link statistics for NAME interfaces"
450jng_stats()
451{
452	local OPTIND=1 OPTARG flag
453	while getopts "" flag; do
454		case "$flag" in
455		*) action_usage stats # NOTREACHED
456		esac
457	done
458	shift $(( $OPTIND -1 ))
459	local name="$1"
460	[ "${name:-x}" = "${name#*[!0-9a-zA-Z_]}" -a $# -eq 1 ] ||
461		action_usage stats # NOTREACHED
462	mustberoot_to_continue
463	for eiface in $( jng_show "$name" ); do
464		echo "$eiface:"
465		ngctl show $eiface: | awk '
466		$3 == "bridge" && $5 ~ /^link/ {
467			bridge = $2
468			link = substr($5, 5)
469			system(sprintf("ngctl msg %s: getstats %u",
470				bridge, link))
471		}' | fmt 2 | awk '
472			/=/ && fl = index($0, "=") {
473				printf "%20s = %s\n",
474					substr($0, 0, fl-1),
475					substr($0, 0, fl+1)
476			}
477		' # END-QUOTE
478	done
479}
480
481############################################################ MAIN
482
483#
484# Command-line arguments
485#
486action="$1"
487[ "$action" ] || usage # NOTREACHED
488
489#
490# Validate action argument
491#
492if [ "$BASH_VERSION" ]; then
493	type="$( type -t "jng_$action" )" || usage # NOTREACHED
494else
495	type="$( type "jng_$action" 2> /dev/null )" || usage # NOTREACHED
496fi
497case "$type" in
498*function)
499	shift 1 # action
500	eval "jng_$action" \"\$@\"
501	;;
502*) usage # NOTREACHED
503esac
504
505################################################################################
506# END
507################################################################################
508