share/examples/jails/jib

   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: if_bridge(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 eNb_xxx interfaces should match the number of
  51 #       #     arguments given to `jib addm xxx' in exec.prestart value.
  52 #       #
  53 #       vnet;
  54 #       vnet.interface = e0b_xxx, e1b_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 `jib addm xxx' should match
  63 #       #     the number of eNb_xxx arguments in vnet.interface value.
  64 #       #
  65 #       exec.prestart += "jib addm xxx em0 em1 ...";
  66 #       exec.poststop += "jib destroy xxx";
  67 #
  68 #       # Standard recipe
  69 #       exec.start += "/bin/sh /etc/rc";
  70 #       exec.stop = "/bin/sh /etc/rc.shutdown jail";
  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="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
 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
 135 pgm="${0##*/}" # Program basename
 136
 137 #
 138 # Global exit status
 139 #
 140 SUCCESS=0
 141 FAILURE=1
 142
 143 ############################################################ FUNCTIONS
 144
 145 usage()
 146 {
 147         local action usage descr
 148         exec >&2
 149         echo "Usage: $pgm action [arguments]"
 150         echo "Actions:"
 151         for action in \
 152                 addm            \
 153                 show            \
 154                 show1           \
 155                 destroy         \
 156         ; do
 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"
 161         done
 162         exit $FAILURE
 163 }
 164
 165 action_usage()
 166 {
 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"
 172         exit $FAILURE
 173 }
 174
 175 derive_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
 254 mustberoot_to_continue()
 255 {
 256         if [ "$( id -u )" -ne 0 ]; then
 257                 echo "Must run as root!" >&2
 258                 exit $FAILURE
 259         fi
 260 }
 261
 262 jib_addm_usage="addm [-b BRIDGE_NAME] NAME [!]iface0 [[!]iface1 ...]"
 263 jib_addm_descr="Creates e0b_NAME [e1b_NAME ...]"
 264 jib_addm()
 265 {
 266         local OPTIND=1 OPTARG flag bridge=bridge
 267         while getopts b: flag; do
 268                 case "$flag" in
 269                 b) bridge="${OPTARG:-bridge}" ;;
 270                 *) action_usage addm # NOTREACHED
 271                 esac
 272         done
 273         shift $(( $OPTIND - 1 ))
 274
 275         local name="$1"
 276         [ "${name:-x}" = "${name#*[!0-9a-zA-Z_]}" -a $# -gt 1 ] ||
 277                 action_usage addm # NOTREACHED
 278         shift 1 # name
 279
 280         mustberoot_to_continue
 281
 282         local iface eiface_devid_a eiface_devid_b
 283         local new no_derive num quad i=0
 284         for iface in $*; do
 285
 286                 no_derive=
 287                 case "$iface" in
 288                 !*) iface=${iface#!} no_derive=1 ;;
 289                 esac
 290
 291                 # Make sure the interface doesn't exist already
 292                 if ifconfig "e${i}a_$name" > /dev/null 2>&1; then
 293                         i=$(( $i + 1 ))
 294                         continue
 295                 fi
 296
 297                 # Bring the interface up
 298                 ifconfig $iface up || return
 299
 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
 306                 fi
 307
 308                 # Create a new interface to the bridge
 309                 new=$( ifconfig epair create ) || return
 310                 ifconfig "$iface$bridge" addm $new || return
 311
 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
 317
 318                 #
 319                 # Set the MAC address of the new interface using a sensible
 320                 # algorithm to prevent conflicts on the network.
 321                 #
 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
 328                 fi > /dev/null 2>&1
 329
 330                 i=$(( $i + 1 ))
 331         done # for iface
 332 }
 333
 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]"
 339 jib_show()
 340 {
 341         local OPTIND=1 OPTARG flag
 342         while getopts "" flag; do
 343                 case "$flag" in
 344                 *) action_usage show2 # NOTREACHED
 345                 esac
 346         done
 347         shift $(( $OPTIND - 1 ))
 348         if [ $# -eq 0 ]; then
 349                 ifconfig | awk '
 350                         /^[^:[:space:]]+:/ {
 351                                 iface = $1
 352                                 sub(/:.*/, "", iface)
 353                                 next
 354                         }
 355                         $1 == "groups:" {
 356                                 for (n = split($0, group); n > 1; n--) {
 357                                         if (group[n] != "bridge") continue
 358                                         print iface
 359                                         next
 360                                 }
 361                         }' |
 362                         xargs -rn1 ifconfig |
 363                         awk '$1 == "member:" &&
 364                                 sub(/^e[[:digit:]]+a_/, "", $2), $0 = $2' |
 365                         sort -u
 366                 return
 367         fi
 368         ifconfig | awk -v name="$1" '
 369                 match($0, /^e[[:digit:]]+a_/) && sub(/:.*/, "") &&
 370                         substr($1, RSTART + RLENGTH) == name
 371         ' | sort
 372 }
 373
 374 jib_destroy_usage="destroy NAME"
 375 jib_destroy_descr="Destroy e0b_NAME [e1b_NAME ...]"
 376 jib_destroy()
 377 {
 378         local OPTIND=1 OPTARG flag
 379         while getopts "" flag; do
 380                 case "$flag" in
 381                 *) action_usage destroy # NOTREACHED
 382                 esac
 383         done
 384         shift $(( $OPTIND -1 ))
 385         local name="$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
 390 }
 391
 392 ############################################################ MAIN
 393
 394 #
 395 # Command-line arguments
 396 #
 397 action="$1"
 398 [ "$action" ] || usage # NOTREACHED
 399
 400 #
 401 # Validate action argument
 402 #
 403 if [ "$BASH_VERSION" ]; then
 404         type="$( type -t "jib_$action" )" || usage # NOTREACHED
 405 else
 406         type="$( type "jib_$action" 2> /dev/null )" || usage # NOTREACHED
 407 fi
 408 case "$type" in
 409 *function)
 410         shift 1 # action
 411         eval "jib_$action" \"\$@\"
 412         ;;
 413 *) usage # NOTREACHED
 414 esac
 415
 416 ################################################################################
 417 # END
 418 ################################################################################