Fix superfluous asteriks in multiplication

Now using fetch to remotely fetch the distribution packages for post 9.0 dists.
Using fetch allows to specify protocols other than file:// and ftp://, with ftp:// being the default.
http servers are not yet queried for the distributions provided.

LICENSE

@@ -0,0 +1,5 @@
+"THE BEER-WARE LICENSE" (Revision 42):
+<erdgeist@erdgeist.org> and the ezjail-community are authors of these files.
+As long as you retain this notice you can do whatever you want with this stuff.
+If we meet some day, and you think this stuff is worth it, you can buy us a
+beer in return. - Dirk Engling for the ezjail-community

Makefile

@@ -3,17 +3,20 @@
 # want / as your install location, DO set PREFIX before invoking this Makefile
 
 PREFIX?=/usr/local
+DST=	${DESTDIR}${PREFIX}
 
 all:
 
 install:
-	mkdir -p ${PREFIX}/etc/ezjail/ ${PREFIX}/man/man1/ ${PREFIX}/man/man5/ ${PREFIX}/etc/rc.d/ ${PREFIX}/bin/ ${PREFIX}/share/examples/ezjail
+	mkdir -p ${DST}/etc/ezjail/ ${DST}/man/man5/ ${DST}/man/man7 ${DST}/man/man8 ${DST}/etc/rc.d/ ${DST}/bin/ ${DST}/share/examples/ezjail ${DST}/share/zsh/site-functions
-	cp -p ezjail.conf.sample ${PREFIX}/etc/
+	cp -R examples/example ${DST}/share/examples/ezjail/
-	cp -R -p examples/default ${PREFIX}/share/examples/ezjail/
+	cp -R examples/nullmailer-example ${DST}/share/examples/ezjail/
-	sed s:EZJAIL_PREFIX:${PREFIX}: ezjail.sh > ${PREFIX}/etc/rc.d/ezjail.sh
+	cp -R share/zsh/site-functions/ ${DST}/share/zsh/site-functions/
-	sed s:EZJAIL_PREFIX:${PREFIX}: ezjail-admin > ${PREFIX}/bin/ezjail-admin
+	sed s:EZJAIL_PREFIX:${PREFIX}: ezjail.conf.sample > ${DST}/etc/ezjail.conf.sample
-	sed s:EZJAIL_PREFIX:${PREFIX}: man1/ezjail-admin.1 > ${PREFIX}/man/man1/ezjail-admin.1
+	sed s:EZJAIL_PREFIX:${PREFIX}: ezjail.sh > ${DST}/etc/rc.d/ezjail
-	sed s:EZJAIL_PREFIX:${PREFIX}: man5/ezjail.conf.5 > ${PREFIX}/man/man5/ezjail.conf.5
+	sed s:EZJAIL_PREFIX:${PREFIX}: ezjail-admin > ${DST}/bin/ezjail-admin
-	sed s:EZJAIL_PREFIX:${PREFIX}: man5/ezjail.5 > ${PREFIX}/man/man5/ezjail.5
+	sed s:EZJAIL_PREFIX:${PREFIX}: man8/ezjail-admin.8 > ${DST}/man/man8/ezjail-admin.8
-	chmod 755 ${PREFIX}/etc/rc.d/ezjail.sh ${PREFIX}/bin/ezjail-admin
+	sed s:EZJAIL_PREFIX:${PREFIX}: man5/ezjail.conf.5 > ${DST}/man/man5/ezjail.conf.5
-	chown -R root:wheel ${PREFIX}/man/man1/ezjail-admin.1 ${PREFIX}/man/man5/ezjail.conf.5 ${PREFIX}/man/man5/ezjail.5 ${PREFIX}/share/examples/ezjail/
+	sed s:EZJAIL_PREFIX:${PREFIX}: man7/ezjail.7 > ${DST}/man/man7/ezjail.7
+	chmod 755 ${DST}/etc/rc.d/ezjail ${DST}/bin/ezjail-admin
+	chmod 0440 ${DST}/share/examples/ezjail/example/usr/local/etc/sudoers

examples/example/etc/make.conf

@@ -1,3 +1,4 @@
 WRKDIRPREFIX=		/var/ports
 DISTDIR=		/var/ports/distfiles
 PACKAGES=		/var/ports/packages
+INDEXDIR=		/var/ports

examples/example/etc/periodic.conf

@@ -1,5 +1,8 @@
+daily_output="/var/log/daily.log"
+weekly_output="/var/log/weekly.log"
+monthly_output="/var/log/monthly.log"
+daily_status_security_output="/var/log/daily_status_security.log"
 daily_status_network_enable="NO"
 daily_status_security_ipfwlimit_enable="NO"
 daily_status_security_ipfwdenied_enable="NO"
 weekly_whatis_enable="NO"       # our jails are read-only /usr
-

examples/example/etc/rc.conf

@@ -16,6 +16,7 @@ syslogd_flags="-ss"
 sendmail_enable="NO"
 sendmail_submit_enable="NO"
 sendmail_outbound_enable="NO"
+sendmail_msp_queue_enable="NO"
 
 # Bring up sshd, it takes some time and uses some entropy on first startup
 # sshd_enable="YES"

examples/example/etc/rc.d/ezjail.flavour.example

@@ -1,15 +1,21 @@
 #!/bin/sh
 #
 # BEFORE: DAEMON
+# PROVIDE: ezjail.example.config
 #
 # ezjail flavour example
 
-# Hide
+. /etc/rc.subr
-#######
-#
-# Prevent this script from being called over and over if something fails.
 
-rm -f /etc/rc.d/ezjail-config.sh /ezjail.flavour
+name=ezjail.flavour.example
+start_cmd=flavour_setup
+
+flavour_setup() {
+
+# Remove traces of ourself
+# N.B.: Do NOT rm $0, it points to /etc/rc
+##########################
+  rm -f "/etc/rc.d/ezjail.flavour.example"
 
 # Groups
 #########
@@ -22,7 +28,7 @@ rm -f /etc/rc.d/ezjail-config.sh /ezjail.flavour
 # Users
 ########
 #
-# You might want to add some users. The password is to be provided in the 
+# You might want to add some users. The password is to be provided in the
 # encrypted form as found in /etc/master.passwd.
 # The example password here is "admin"
 # Refer to crypt(3) and pw(8) for more information
@@ -48,13 +54,13 @@ rm -f /etc/rc.d/ezjail-config.sh /ezjail.flavour
 # Install all packages previously put to /pkg
 # Remove package files afterwards
 
-[ -d /pkg ] && PACKAGESITE=file:// pkg_add -r /pkg/*
+[ -d /pkg ] && cd /pkg && pkg_add /pkg/*
 rm -rf /pkg
 
 # Postinstall
 ##############
 #
-# Your own stuff here, for example set login shells that were only 
+# Your own stuff here, for example set login shells that were only
 # installed just before.
 
 # Please note, that for all network related stuff like ports,
@@ -63,3 +69,7 @@ rm -rf /pkg
 # chpass -s /usr/local/bin/bash admin
 # pkg_add -r pico
 # cd /usr/ports/sysutils/screen && make install
+
+}
+
+run_rc_command "$1"

examples/nullmailer-example/etc/mail/mailer.conf

@@ -0,0 +1,4 @@
+# replace sendmail with nullmailer
+sendmail	/usr/local/libexec/nullmailer/sendmail
+send-mail	/usr/local/libexec/nullmailer/sendmail
+mailq		/usr/local/libexec/nullmailer/mailq

examples/nullmailer-example/etc/rc.conf

@@ -0,0 +1,26 @@
+# Pretuned by German Engineers
+
+# No network interfaces in jails
+network_interfaces=""
+
+# Prevent rpc
+rpcbind_enable="NO"
+
+# Prevent loads of jails doing their cron jobs at the same time
+cron_flags="$cron_flags -J 15"
+
+# Prevent syslog to open sockets
+syslogd_flags="-ss"
+
+# Prevent sendmail to try to connect to localhost
+sendmail_enable="NO"
+sendmail_submit_enable="NO"
+sendmail_outbound_enable="NO"
+sendmail_msp_queue_enable="NO"
+
+# Bring up sshd, it takes some time and uses some entropy on first startup
+# sshd_enable="YES"
+
+# Enable nullmailer for external mail delivery
+nullmailer_enable="YES"
+

examples/nullmailer-example/ezjail.flavour

@@ -0,0 +1,10 @@
+#!/bin/sh
+#
+# BEFORE: DAEMON
+#
+# ezjail flavour example
+
+# install nullmailer port
+cd /usr/ports/mail/nullmailer
+yes | make install
+hostname > /usr/local/etc/nullmailer/me

examples/nullmailer-example/usr/local/etc/nullmailer/remotes

@@ -0,0 +1,2 @@
+# example smtp route
+# 127.0.0.1 smtp

ezjail-clone.sh

@@ -0,0 +1,56 @@
+#!/bin/sh
+
+ezjail_dirlist="bin boot lib libexec rescue sbin usr/bin usr/include usr/lib usr/libdata usr/libexec usr/sbin usr/src usr/share usr/lib32 usr/ports"
+
+ezjail_name=`uname -n`
+ezjail_safename=`echo -n "${ezjail_name}" | tr -c '[:alnum:]' _`
+ezjail_archive_tag="${ezjail_safename}-`date +%Y%m%d%H%M.%S`"
+ezjail_archive="${ezjail_archive_tag}.tar.gz"
+ezjail_archive_opt="-f `pwd -P`/${ezjail_archive}"
+
+# Create soft links needed in all ezjails
+mkdir -p /tmp/ezjail_fakeroot/usr /tmp/ezjail_fakeroot/basejail
+for dir in ${ezjail_dirlist}; do
+  ln -s /basejail/${dir} /tmp/ezjail_fakeroot/${dir}
+done
+
+# Construct regex that excludes directories from newjail
+# Also excludes the directories themself, they will be added as softlinks
+repl=""
+for dir in ${ezjail_dirlist}; do
+  repl="${repl} -s:^./${dir}/.*::p -s:^./${dir}$::p"
+done
+
+# Do not want to archive the archive itself
+repl="${repl} -s:.*/${ezjail_archive}$::p"
+
+# Must not archive content of /dev and /proc
+repl="${repl} -s:^./dev/.*::p -s:^./proc/.*::p"
+
+# Map the softlinks found in our fake root into the jails root
+# exclude fakeroot's /usr
+repl="${repl} -s:^./tmp/ezjail_fakeroot/usr$::p -s:^./tmp/ezjail_fakeroot/:ezjail/:p"
+
+# Finally re-locate all files under ezjail/ so that the restore command find them
+repl="${repl} -s:^\.:ezjail:p"
+
+cd /
+pax -wt -x cpio ${ezjail_archive_opt} ${repl} .
+ezjail_paxresult=$?
+
+rm -rf /tmp/ezjail_fakeroot/
+
+# Debug: unset LANG LC_CTYPE
+# Debug: find -dE / ! -regex "/(dev|proc|${ezjail_dirlist})/.*" -a ! -regex "/(${ezjail_dirlist})" -a ! -path /tmp/ezjail_fakeroot/usr -a ! -name "${ezjail_archive}" \
+
+if [ ${ezjail_paxresult} -eq 0 ]; then
+  echo Your system has been archived to ${ezjail_archive}
+  echo On the destination ezjail installation use the following command to
+  echo import it as an ezjail:
+  echo   ezjail-admin create -a ./${ezjail_archive} HOSTNAME IP
+  echo Of course you can use many other switches to ezjail-admin create on
+  echo the target system as well.
+else
+  echo Your system could not be archived, try the following command to find
+  echo out why:
+fi

ezjail.conf.sample

@@ -6,7 +6,7 @@
 
 # Location of jail root directories
 #
-# Note: If you have spread your jails to multiple locations, use softlinks 
+# Note: If you have spread your jails to multiple locations, use softlinks
 # to collect them in this directory
 # ezjail_jaildir=/usr/jails
 
@@ -19,20 +19,25 @@
 # Location of your copy of FreeBSD's source tree
 # ezjail_sourcetree=/usr/src
 
-# In case you want to provide a copy of ports tree in base jail, set this to
-# a cvsroot near you
-# ezjail_portscvsroot=:pserver:anoncvs@anoncvs.at.FreeBSD.org:/home/ncvs
-
 # This is where the install sub command defaults to fetch its packages from
 # ezjail_ftphost=ftp.freebsd.org
 
+# This is the command that is being executed by the console subcommand
+# ezjail_default_execute="/usr/bin/login -f root"
+
+# This is the flavour used by default when setting up a new jail
+# ezjail_default_flavour=""
+
+# This is the default location where ezjail archives its jails to
+# ezjail_archivedir="${ezjail_jaildir}/ezjail_archives"
+
 # base jail will provide a soft link from /usr/bin/perl to /usr/local/bin/perl
 # to accomodate all scripts using '#!/usr/bin/perl'...
 # ezjail_uglyperlhack="YES"
 
 # Default options for newly created jails
 #
-# Note: Be VERY careful about disabling ezjail_mount_enable. Mounting 
+# Note: Be VERY careful about disabling ezjail_mount_enable. Mounting
 # basejail via nullfs depends on this. You will have to find other
 # ways to provide your jail with essential system files
 # ezjail_mount_enable="YES"
@@ -40,3 +45,27 @@
 # ezjail_devfs_ruleset="devfsrules_jail"
 # ezjail_procfs_enable="YES"
 # ezjail_fdescfs_enable="YES"
+
+# ZFS options
+
+# Setting this to YES will start to manage the basejail and newjail in ZFS
+# ezjail_use_zfs="YES"
+
+# Setting this to YES will manage ALL new jails in their own zfs
+# ezjail_use_zfs_for_jails="YES"
+
+# The name of the ZFS ezjail should create jails on, it will be mounted at the ezjail_jaildir
+# ezjail_jailzfs="tank/ezjail"
+
+# ADVANCED, be very careful!
+# ezjail_zfs_properties="-o compression=lzjb -o atime=off"
+# ezjail_zfs_jail_properties="-o dedup=on"
+
+# For auto snapshots this is the default policy to keep old snapshots. In each window there
+# will be guaranteed to be one or two snapshots only
+# If this variable is not set, no snapshots will be removed by ezjail-admin snapshot
+
+# Example policy for a database jail with rollbackable snapshots starting with four snapshots
+# in the last hour and up to an annual snapshot for 1000 years. Beware of the load caused by
+# destroying snapshots.
+# ezjail_default_retention_policy="4x15m 3x1h 2x2h 4h 12h 6x1d 7x1w 11x4w 1000x1y"

ezjail.sh

@@ -20,7 +20,7 @@ ezjail_prefix=EZJAIL_PREFIX
 . /etc/rc.subr
 
 name=ezjail
-rcvar=`set_rcvar`
+rcvar=${name}_enable
 extra_commands="startcrypto stopcrypto"
 load_rc_config ${name}
 
@@ -35,28 +35,38 @@ stopcrypto_cmd="do_cmd stopcrypto _"
 do_cmd()
 {
   action=$1; message=$2; shift 2;
-  unset ezjail_list ezjail_pass ezjail_mds
+  unset ezjail_list ezjail_pass ezjail_mds ezjail_stop
+  ezjail_cfgs=${ezjail_prefix}/etc/ezjail/
   ezjail_fromrc="YES"
 
+  case "${action}" in *stop) ezjail_stop="YES";; esac
+
   # If a jail list is given on command line, process it
   # If not, fetch it from our config directory
-  if [ -n "$*" ]; then
+  if [ "$*" ]; then
     ezjail_list=`echo -n $* | tr -c '[:alnum:] ' '_'` 
-    ezjail_fromrc="NO"
+    unset ezjail_fromrc
   else
-    [ -d ${ezjail_prefix}/etc/ezjail/ ] && cd ${ezjail_prefix}/etc/ezjail/ && ezjail_list=`ls | xargs rcorder`
+    [ "${ezjail_stop}" ] && reverse_command="tail -r" || reverse_command="cat"
+    [ -d "${ezjail_cfgs}" ] && cd "${ezjail_cfgs}" && ezjail_list=`ls | xargs rcorder | ${reverse_command}`
     echo -n "${message##_}"
   fi
 
   for ezjail in ${ezjail_list}; do
-    # If jail is temporary disabled (dot in name), skip it
+    unset ezjail_config ezjail_norun
-    [ "${ezjail%.*}" != "${ezjail}" ] && continue
+
+    [ -e "${ezjail_cfgs}/${ezjail}"       ] && ezjail_config="${ezjail_cfgs}/${ezjail}"
+    [ -e "${ezjail_cfgs}/${ezjail}.norun" ] && ezjail_config="${ezjail_cfgs}/${ezjail}.norun" && ezjail_norun="YES"
 
     # Check for jails config
-    [ ! -r ${ezjail_prefix}/etc/ezjail/${ezjail} ] && echo " Warning: Jail ${ezjail} not found." && continue
+    [ ! -f "${ezjail_config}" ] && echo " Warning: Jail ${ezjail} not found." && continue
+
+    # If jail is temporary disabled (dot in name), skip it for starts
+    [ "${ezjail_stop}" ] && ezjail="${ezjail%%.*}"
+    [ "${ezjail%.*}" != "${ezjail}" -o "${ezjail_norun}" ] && echo -n " skipping ${ezjail}" && continue
 
     # Read config file
-    . ${ezjail_prefix}/etc/ezjail/${ezjail}
+    . ${ezjail_config}
 
     eval ezjail_rootdir=\"\$jail_${ezjail}_rootdir\"
     eval ezjail_image=\"\$jail_${ezjail}_image\"
@@ -65,16 +75,25 @@ do_cmd()
     eval ezjail_attachblocking=\"\$jail_${ezjail}_attachblocking\"
     eval ezjail_forceblocking=\"\$jail_${ezjail}_forceblocking\"
 
-    [ "${ezjail_attachblocking}" = "YES" -o "${ezjail_forceblocking}" = "YES" ] && ezjail_blocking="YES" || unset ezjail_blocking
+    # Fix backward compatibility issue
+    eval ezjail_exec_start=\"\$jail_${ezjail}_exec_start\"
+    eval ezjail_exec=\"\$jail_${ezjail}_exec\"
+    eval jail_${ezjail}_exec_start=\"\${ezjail_exec_start:-${ezjail_exec}}\"
+    eval unset jail_${ezjail}_exec
+
+    # Do we still have a root to run in?
+    [ ! -d "${ezjail_rootdir}" ] && echo " Warning: root directory ${ezjail_rootdir} of ${ezjail} does not exist." && continue
+
+    [ "${ezjail_attachblocking}" -o "${ezjail_forceblocking}" ] && ezjail_blocking="YES" || unset ezjail_blocking
 
     # Cannot auto mount blocking jails without interrupting boot process
-    [ "${ezjail_fromrc}" = "YES" -a "${action}" = "start" -a "${ezjail_blocking}" = "YES" ] && continue
+    [ "${ezjail_fromrc}" -a "${action}" = "start" -a "${ezjail_blocking}" ] && echo -n " ...skipping blocking jail ${ezjail}" && continue
 
-    # Explicitely do only run blocking crypto jails when *crypto is requested
+    # Explicitly do only run blocking crypto jails when *crypto is requested
-    [ "${action%crypto}" != "${action}" -a -z "${ezjail_blocking}" ] && continue
+    [ "${action%crypto}" = "${action}" -o "${ezjail_blocking}" ] || continue
 
     # Try to attach (crypto) devices
-    if [ -n "${ezjail_image}" ]; then
+    if [ "${ezjail_image}" ]; then
       attach_detach_pre || continue
     fi
 
@@ -84,21 +103,51 @@ do_cmd()
   # Pass control to jail script which does the actual work
   [ "${ezjail_pass}" ] && sh /etc/rc.d/jail one${action%crypto} ${ezjail_pass}
 
+  # Configure settings that need to be done after the jail has been started
+  if [ "${action%crypto}" = "start" -o "${action}" = "restart" ]; then
+    for ezjail in ${ezjail_pass}; do
+      ezjail_safename=`echo -n "${ezjail}" | tr -c '[:alnum:]' _`
+      # Get the JID of the jail
+      [ -f "/var/run/jail_${ezjail_safename}.id" ] && ezjail_id=`cat /var/run/jail_${ezjail_safename}.id` || return
+
+      eval ezjail_zfs_datasets=\"\$jail_${ezjail_safename}_zfs_datasets\"
+      eval ezjail_cpuset=\"\$jail_${ezjail_safename}_cpuset\"
+      eval ezjail_post_start_script=\"\$jail_${ezjail_safename}_post_start_script\"
+
+      # Attach ZFS-datasets to the jail
+      for zfs in ${ezjail_zfs_datasets}; do
+        /sbin/zfs jail ${ezjail_id} ${zfs} || echo -n "Error: ${zfs} could not be configured"
+      done
+
+      # Configure processor sets for the jail via cpuset(1)
+      [ -z "${ezjail_cpuset}" ] || /usr/bin/cpuset -l ${ezjail_cpuset} -j ${ezjail_id} || echo -n "Error: The defined cpuset is malformed"
+
+      # Run post start script
+      [ -z "${ezjail_post_start_script}" ] || "${ezjail_post_start_script}" ${ezjail_id} "${ezjail}" || echo -n "Error: Post Start Script failed"
+    done
+  fi
+
   # Can only detach after unmounting (from fstab.JAILNAME in /etc/rc.d/jail)
   attach_detach_post
 }
 
 attach_detach_pre ()
 {
-  if [ "${action%crypto}" = "start" ]; then
+  case "${action%crypto}" in
+  start|restart)
     # If jail is running, do not mount devices, this is the same check as
     # /etc/rc.d/jail does
-    [ -e /var/run/jail_${ezjail}.id ] && return 1
+    [ -e "/var/run/jail_${ezjail}.id" ] && return 0
 
     if [ -L "${ezjail_rootdir}.device" ]; then
       # Fetch destination of soft link
       ezjail_device=`stat -f "%Y" ${ezjail_rootdir}.device`
-      [ -e "${ezjail_device}" ] && echo "Jail image file ${ezjail} already attached as ${ezjail_device}. 'ezjail-admin config -i detach' it first." && return 1
+
+      mount -p -v | grep -E "^${ezjail_rootdir}.device.${ezjail_rootdir}" && echo "Warning: Skipping jail. Jail image file ${ezjail} already attached as ${ezjail_device}. 'ezjail-admin config -i detach' it first." && return 1
+      mount -p -v | grep -E "^${ezjail_device}.${ezjail_rootdir}" && echo "Warning: Skipping jail. Jail image file ${ezjail} already attached as ${ezjail_device}. 'ezjail-admin config -i detach' it first." && return 1
+
+      # Remove stale device link
+      rm -f "${ezjail_rootdir}.device"
     fi
 
     # Create a memory disc from jail image
@@ -109,42 +158,43 @@ attach_detach_pre ()
     case ${ezjail_imagetype} in
     crypto|bde)
       echo "Attaching bde device for image jail ${ezjail}..."
-      echo gbde attach /dev/${ezjail_device} ${ezjail_attachparams} | /bin/sh 
+      echo gbde attach "/dev/${ezjail_device}" ${ezjail_attachparams} | /bin/sh 
       if [ $? -ne 0 ]; then
-        mdconfig -d -u ${ezjail_device} > /dev/null
+        mdconfig -d -u "${ezjail_device}" > /dev/null
         echo "Error: Attaching bde device failed."; return 1
       fi
       # Device to mount is not md anymore
-      ezjail_device=${ezjail_device}.bde
+      ezjail_device="${ezjail_device}.bde"
       ;;
     eli)
       echo "Attaching eli device for image jail ${ezjail}..."
-      echo geli attach ${ezjail_attachparams} /dev/${ezjail_device} | /bin/sh
+      echo geli attach ${ezjail_attachparams} "/dev/${ezjail_device}" | /bin/sh
       if [ $? -ne 0 ]; then
-        mdconfig -d -u ${ezjail_device} > /dev/null
+        mdconfig -d -u "${ezjail_device}" > /dev/null
         echo "Error: Attaching eli device failed."; return 1
       fi
       # Device to mount is not md anymore
-      ezjail_device=${ezjail_device}.eli
+      ezjail_device="${ezjail_device}.eli"
       ;;
     esac
 
     # Clean image
-    fsck_ufs -F -p /dev/${ezjail_device}
+    fsck -t ufs -p -B "/dev/${ezjail_device}"
 
     # relink image device
-    rm -f ${ezjail_rootdir}.device
+    rm -f "${ezjail_rootdir}.device"
-    ln -s /dev/${ezjail_device} ${ezjail_rootdir}.device
+    ln -s "/dev/${ezjail_device}" "${ezjail_rootdir}.device"
-  else
+  ;;
+  stop)
     # If jail is not running, do not unmount devices, this is the same check
     # as /etc/rc.d/jail does
-    [ -e /var/run/jail_${ezjail}.id ] || return 1
+    [ -e "/var/run/jail_${ezjail}.id" ] || return 1
 
     # If soft link to device is not set, we cannot unmount
-    [ -e ${ezjail_rootdir}.device ] || return
+    [ -e "${ezjail_rootdir}.device" ] || return
 
     # Fetch destination of soft link
-    ezjail_device=`stat -f "%Y" ${ezjail_rootdir}.device`
+    ezjail_device=`stat -f "%Y" "${ezjail_rootdir}.device"`
 
     # Add this device to the list of devices to be unmounted
     case ${ezjail_imagetype} in
@@ -154,16 +204,17 @@ attach_detach_pre ()
     esac
 
     # Remove soft link (which acts as a lock)
-    rm -f ${ezjail_rootdir}.device
+    rm -f "${ezjail_rootdir}.device"
-  fi
+  ;;
+  esac
 }
 
 attach_detach_post () {
   # In case of a stop, unmount image devices after stopping jails
   for md in ${ezjail_mds}; do
-    [ -e ${md}.bde ] && gbde detach ${md}
+    [ -e "${md}.bde" ] && gbde detach "${md}"
-    [ -e ${md}.eli ] && geli detach ${md}
+    [ -e "${md}.eli" ] && geli detach "${md}"
-    mdconfig -d -u ${md#/dev/}
+    mdconfig -d -u "${md#/dev/}"
   done
 }
 

man1/ezjail-admin.1

@@ -1,236 +0,0 @@
-.TH ezjail\-admin 1
-.SH NAME
-ezjail-admin \- Administrate ezjail
-.SH SYNOPSIS
-.T
-.B ezjail-admin create
-[-f flavour] [-r jailroot] [-s imagesize] [-ibx] [-c bde|eli] [-C attachargs]
-.I hostname jailip
-
-.T
-.B ezjail-admin delete
-[-w]
-.I hostname
-
-.T
-.B ezjail-admin list
-
-.T
-.B ezjail-admin config
-[-r run|norun] [-i attach|detach]
-.I jailname
-
-.T
-.B ezjail-admin install
-[-mps] [-h host] [-r release]
-
-.T
-.B ezjail-admin update
-[-s sourcetree] [-i] [-pP]
-.SH DESCRIPTION
-The
-.B ezjail-admin
-tool is used to manage jails inside the ezjail scope. It is not used 
-to start or stop ezjails jails. Refer to ezjail(5) for more details. 
-.SH ezjail-admin create
-copies the template jail to the root of a new jail, whose name and IP
-address are provided as mandatory parameters.
-
-If no jail root is specified via the -r option, it is derived from
-the jails name. In this case or, if a jail root is given and does not
-start with a '/', it is interpreted relative to ezjails root dir
-(default:
-.I /usr/jails
-). If a specified jail root lies outside ezjail root dir, a soft link
-is created inside this root dir pointing to the newly created jails
-location.
-
-The -i and the -c option both require a size passed via the -s option
-and create a file based jail image, gbde or geli encrypted for the -c 
-case. The image file is named as the jail root suffixed with
-.I .img
-.
-
-The -x (jail exists) option indicates, that an ezjail already exists
-at the jail root.
-.B In this case nothing is copied. ezjail only updates its config.
-This is useful in situations where you just want to alter some of a
-jail properties and called ezjail-admin delete without the -w option
-before. However, sanity checks are being performed.
-
-The script creates an entry in its config and a
-.I /etc/fstab.hostname
-file allowing the jail to be brought up after next reboot (or) via
-the EZJAIL_PREFIX/etc/rc.d/ezjail.sh script.
-
-The newly created jail can perform some initializiation actions, if the
--f
-.I flavour
-option is given, where
-.I flavour
-is a directory tree under ezjails root dir (default:
-.I /usr/jails/flavours
-). See section
-.B FLAVOURS
-below for more details.
-
-Options for newly created jails are read from
-.B ezjail.conf,
-refer to ezjail.conf(5) for more information.
-.SH ezjail-admin delete
-removes a jail from ezjails config and the corresponding
-.I /etc/fstab.hostname
-file, thus preventing the jail from being brought
-up on next reboot.
-
-If the -w (wipe) option is given, the directory pointed to by the jail
-root entry is removed as well as the soft link in ezjails root dir.
-.SH ezjail-admin list
-lists all jails inside ezjails scope. They are sorted by the order they 
-start up, as defined by rcorder. The list format is straight forward.
-
-A status flag consisting of 2 or 3 letters, the first meaning
-.B (D)irectory
-based,
-.B (I)mage
-based,
-.B (B)de
-crypto image based,
-.B (E)li
-crypto image based. The second one meaning
-.B (R)unning
-,
-.B (A)ttached
-but not running,
-.B (S)topped
-. An optional
-.B (N)orun
-stands for disabled jails (see
-.I ezjail-admin config
-).
-
-Rest of the row is follow by jails jid (if available), its IP, hostname 
-and root directory.
-.SH ezjail-admin config
-manages existing specific ezjails.
-
-You can prevent an ezjail from being run at system start by the -r norun
-option and reenable it by -r run.
-
-You can attach image jails for administrative purposes by the -i attach
-option and detach them with -i detach. It is not possible to run or delete
-an attached jail.
-.SH ezjail-admin install
-fetches everything needed to setup a base jail from an FTP server and 
-installs it.
-
-Default location for ezjails base jail is
-.I /usr/jails
-, so be sure you have enough space there (a FreeBSD base without man 
-pages, sources and ports is around 120MB).
-
-The -m and -s option will fetch and install man pages (ca. 10MB) and
-sources packages (ca. 450MB) respectively. The -p option invokes the
-portsnap utility to fetch and extract a FreeBSD ports tree (ca. 475MB).
-
-Default OS version is, whatever uname -r returns. If this does not match
-"*-RELEASE", you will be prompted for a better guess. (Normally
-ftp-servers do not provide release candidates or CURRENT builds). You can
-use the -r option to specify a release from command line.
-
-Default host to fetch packages from is ftp.freebsd.org, you may want to
-change this via the -h option or in ezjail.conf(5).
-
-If the specified location begins with file://, your local copy of the
-release is used. That way you can do some modifications to install.sh
-scripts before executing them.
-
-You can later update your world from CVS or update ports by
-.U ezjail-admin update
-or rerun this subcommand with another OS version.
-.SH ezjail-admin update
-creates or update ezjails basejail. Depending on the parameters
-given it will install a FreeBSD system from a source tree whose location
-is either provided in the
-.B ezjail.conf
-config file or via the -s option.
-
-If the -p or -P options are given, the base jail also is given a copy of
-FreeBSDs ports tree, which is in turn linked into all newly created
-ezjails. The portsnap utility is invoked to do the actual work.
-
-If the -P option is given,
-.B only the ports tree will be updated,
-this can be done, while jails are running.
-
-If the -i (install only) option is given,
-.B ezjail-admin update
-only performes a
-.I make installworld,
-otherwise
-.I make world
-is invoked.
-
-.SH NOTES
-.B ezjail-admin update
-uses a temporary directory to install its world to, thus leaving intact
-all installed libraries, if a base jail already exists.
-
-When using the
-.B ezjail-admin update
-option, be careful to use the same FreeBSD source tree used to build the 
-host systems world, or at least its kernel. Combining a make world in the 
-host system with
-.B ezjail-admin update
-is considered a good idea.
-
-When a ports tree exists in base jail, a make.conf containing reasonable
-values for having ports in jails is created in the template jail.
-.SH FLAVOURS
-.B ezjail-admin
-provides an easy way to create many jails with similar or identical
-properties.
-
-A sample flavour config directory resides under
-.I EZJAIL_PREFIX/share/examples/ezjail/default/.
-Some typical Jail initialization actions are demonstrated and you are
-encouraged to use it as a template for your flavours.
-
-If a flavour is selected on jail creation, the flavour root is being
-copied to the new Jails root, mostly containing an
-.I /ezjail.flavour .
-If the Jail starts up for the first time this script is run.
-
-In its default form it will create some groups and users, change the
-ownership of some files and installs all packages residing under /pkg.
-
-It allows you to add some post install actions.
-.SH EXAMPLES
-ezjail-admin update -p
-.br
-ezjail-admin create -f httpd -r /jails/web12 web12.test.org 10.0.1.12
-.br
-EZJAIL_PREFIX/etc/rc.d/ezjail.sh start web12.test.org
-.br
-EZJAIL_PREFIX/etc/rc.d/ezjail.sh stop ns.test.org
-.br
-ezjail-admin delete ns.test.org
-.br
-ezjail-admin create -x -r /jails/ns ns.test.org 10.0.2.1
-.SH BUGS
-Due to the way ezjail handles jail config files it is not possible to
-create multiple jails if their names are identical when piped through
-.B tr -C [:alnum:] _
-
-Sure to be others.
-.SH FILES
-.T4
-EZJAIL_PREFIX/etc/ezjail.conf
-.br
-EZJAIL_PREFIX/etc/rc.d/ezjail.sh
-.br
-EZJAIL_PREFIX/share/examples/ezjail/
-.SH "SEE ALSO"
-ezjail(5), ezjail.conf(5), jail(8), devfs(5), fdescfs(5), procfs(5), pw(8)
-.SH AUTHOR
-Dirk Engling <erdgeist@erdgeist.org>

man5/ezjail.5

@@ -1,60 +0,0 @@
-.TH ezjail 5
-.SH NAME
-ezjail \- A simple jail setup framework
-.SH SYNOPSIS
-EZJAIL_PREFIX/etc/rc.d/ezjail.sh
-.SH DESCRIPTION
-The ezjail framework provides a simple way to create many virtual FreeBSD 
-servers by using FreeBSD's jail system. It requires little administration 
-effort and aims for minimum system resource usage.
-
-If you are not familiar with the FreeBSD jail concept, please refer to 
-jail(8) before continuing.
-.SH OVERVIEW
-One
-.I base jail
-is filled with most userland binaries and libraries and then mounted 
-read only into a number of stripped down jails via
-.B mount_nullfs(8)
-- thus saving lots of inodes and memory resources.
-.SH INVOCATION
-The ezjail script
-.B EZJAIL_PREFIX/etc/rc.d/ezjail.sh
-takes parameters
-.I start, startcrypto, restart
-and
-.I stop.
-It may be passed an additional list of jails. If no jail name is 
-specified (usually when the script is being called by rc.local at boot 
-and shutdown time), all jails in ezjails scope, except crypto image
-jails (or jails marked as blocking), are being started/stopped. To
-start all crytpo image jails (or those depending on them), use the
-.I startcrypto
-parameter.
-
-The script examines its config, attaches and mounts images, sets
-variables for each jail in the jail_list before passing its command on
-to the
-.B /etc/rc.d/jail
-script.
-.SH NOTES
-.B ezjail.sh
-enforces the execution of
-.B /etc/rc.d/jail,
-by prepending
-.I "one"
-to the start, restart and stop commands so it is
-.B NOT NECESSARY
-to set
-.I jail_enable
-in the
-.B /etc/rc.conf
-config file.
-.SH FILES
-EZJAIL_PREFIX/etc/ezjail.conf
-.br
-EZJAIL_PREFIX/etc/rc.d/ezjail.sh
-.SH "SEE ALSO"
-ezjail-admin(1), ezjail.conf(5), jail(8), mount_nullfs(8)
-.SH AUTHOR
-Dirk Engling <erdgeist@erdgeist.org>

man5/ezjail.conf.5

@@ -1,111 +1,229 @@
-.TH ezjail.conf 5
+.Dd December 5, 2013
-.SH NAME
+.Dt EZJAIL.CONF 5 USD
-ezjail.conf \- configuration file for ezjail script
+.Os FreeBSD
-.SH DESCRIPTION
+.Sh NAME
+.Pa ezjail.conf
+.Nd configuration file for ezjail script
+.Sh DESCRIPTION
 The file
-.B ezjail.conf
+.Pa ezjail.conf
-contains settings that control the operation of the ezjail rc script. It is 
+contains settings that control the operation of the ezjail
-also read by the
+.Xr rc 8
-.B ezjail-admin
+script. It is also read by the
-utility to figure out where it should perform its actions.
+.Cm ezjail-admin
-.SH PATH OPTIONS
+utility to figure out where it should perform its actions. Its path is
-.TP
+set at installation time to
-.B ezjail_jaildir (str)
+.Pa EZJAIL_PREFIX/etc/ezjail.conf ,
-Location of jail root directories
+with an example file installed at
+.Pa EZJAIL_PREFIX/etc/ezjail.conf.sample .
+.Pp
+This file is really a shell script that is sourced by the
+.Cm ezjail-admin
+command at run-time.
+.Dq (str)
+denotes a string; it should be enclosed in quotes if it contains space.
+.Dq (bool)
+notes a boolean, whose possible values are
+.Dq YES
+and
+.Dq NO .
+.Sh PATH OPTIONS
+.Bl -tag -width option
+.It ezjail_jaildir (str)
+Location of jail root directories.
 .br
-.I default: /usr/jails
+Default:
-.TP
+.Em /usr/jails .
-.B ezjail_jailtemplate (str)
+.It ezjail_jailtemplate (str)
 Location of template jail used to create a new jail
 .br
-.I default: /usr/jails/newjail
+Default:
-.TP
+.Em ${ezjail_jaildir}/newjail .
-.B ezjail_jailbase (str)
+.It ezjail_jailbase (str)
 Location of base jail, the one that is mounted to all jails
 .br
-.I default: /usr/jails/basejail
+Default:
-.TP
+.Em ${ezjail_jaildir}/basejail .
-.B ezjail_sourcetree (str)
+.It ezjail_sourcetree (str)
 Location of your copy of FreeBSD's source tree (refer to the
-.B ezjail-admin(1)
+.Xr ezjail-admin 8
-utility for more information)
+utility for more information).
 .br
-.I default: /usr/src
+Default:
-.TP
+.Em /usr/src .
-.B ezjail_portscvsroot (str)
+.It ezjail_flavours_dir (str)
-Cvs root to use when checking out or updating the ports tree in base jail
+Location of the flavours, where each directory is a different flavour.
 .br
-.I default: :pserver:anoncvs@anoncvs.at.FreeBSD.org:/home/ncvs
+Default:
-.TP
+.Em ${ezjail_jaildir}/flavours .
-.B ezjail_ftphost (str)
+.It ezjail_ftphost (str)
-This is where the install sub command defaults to fetch its packages from
+This is where the install subcommand defaults to fetch its packages from.
 .br
-.I default: ftp.freebsd.org
+Default:
-.TP
+.Em ftp.freebsd.org .
-.B ezjail_uglyperlhack (bool)
+.It ezjail_archivedir (str)
-Set to YES, if ezjail should provide a soft link from /usr/bin/perl to /usr/local/bin/perl in base jail.
+This is the default archive location for the
+.Cm ezjail-admin archive
+command.
 .br
-.I default: YES
+Default:
-.SH JAIL CREATION OPTIONS
+.Em ${ezjail_jaildir}/ezjail_archives .
+.El
+.Sh JAIL ADMIN OPTIONS
+.Bl -tag -width option
+.It ezjail_default_execute (str)
+This is the default command executed in a jail by
+.Cm ezjail-admin console .
+.br
+Default:
+.Em /usr/bin/login -f root .
+.It ezjail_exec_start (str)
+The command to execute in a jail when starting it.
+.br
+Default:
+.Em /bin/sh /etc/rc .
+.El
+.Sh JAIL CREATION OPTIONS
 Default options for newly created jails. Used by the
-.B ezjail-admin(1)
+.Xr ezjail-admin 1
-utility. Be careful about disabling ezjail_mount_enable. (Refer to
+utility. Be careful about disabling
-.B ezjail-admin(1)
+.Em ezjail_mount_enable .
-for more information).
+.Bl -tag -width option
-.TP
+.It ezjail_mount_enable (bool)
-.B ezjail_mount_enable (bool)
+Controls whether
-Controls, whether /etc/fstab.hostname should be executed at jail startup 
+.Pa /etc/fstab. Ar hostname
-time.
+should be executed at jail startup time.
 .br
-.I default: "YES"
+Default:
-.TP
+.Em YES .
-.B ezjail_devfs_enable (bool)
+.It ezjail_devfs_enable (bool)
-Controls, whether newly created jails will be given a working
+Controls whether newly created jails are given a working
-.I /dev
+.Pa /dev
 directory. (Refer to
-.B devfs(5)
+.Xr devfs 5
 and
-.B jail(8)
+.Xr jail 8
 for more information).
 .br
-.I default: "YES"
+Default:
-.TP
+.Em YES .
-.B ezjail_devfs_ruleset (str)
+.It ezjail_devfs_ruleset (str)
-Specifies, which devfs ruleset should apply for newly created jails. 
+Specifies which devfs ruleset should apply for newly created jails.
 (Refer to
-.B devfs(5)
+.Xr devfs 5
 and
-.N jail(8)
+.Xr jail 8
 for more information).
 .br
-.I default: "devfsrules_jail"
+Default:
-.TP
+.Em devfsrules_jail .
-.B ezjail_procfs_enable (bool)
+.It ezjail_procfs_enable (bool)
-Controls, whether newly created jails will be given a working
+Controls whether newly created jails are given a working
-.I /proc
+.Pa /proc
 directory. (Refer to
-.B procfs(5)
+.Xr procfs 5
 and
-.B jail(8)
+.Xr jail (8)
 for more information).
 .br
-.I default: "YES"
+Default:
-.TP
+.Em YES .
-.B ezjail_fdescfs_enable (bool)
+.It ezjail_fdescfs_enable (bool)
-Controls, whether newly created jails will be given a working
+Controls whether newly created jails are given a working
-.I /dev/fd/
+.Pa /dev/fd/
 directory. (Refer to
-.B fdescfs(5)
+.Xr fdescfs (5)
 and
-.B jail(8)
+.Xr jail (8)
 for more information).
 .br
-.I default: "YES"
+Default:
-.SH FILES
+.Em YES .
+.It ezjail_uglyperlhack (bool)
+Set to YES, if ezjail should provide a soft link from
+.Pa /usr/bin/perl
+to
+.Pa /usr/local/bin/perl
+in base jail.
+.br
+Default:
+.Em YES .
+.It ezjail_default_flavour (str)
+Controls which flavours should be used for newly created jails if none
+are given on the command line.
+.br
+Default:
+.Em none .
+.It ezjail_imagetype (one of simple, bde, eli, zfs)
+Type of jail to create when creating a jail with the
+.Fl i
+flag without specifying the type explicitly.
+.br
+Default:
+.Em simple
+.El
+.Sh ZFS OPTIONS
+.Bl -tag -width option
+.It ezjail_use_zfs (bool)
+Set to YES, if ezjail should manage basejail and newjail in a separate
+ZFS-datasets.
+.br
+Default:
+.Em NO .
+.It ezjail_use_zfs_for_jails (bool)
+Set to YES, if ezjail should manage all new jails in their own
+ZFS-datasets. To override that on the command line, use
+.Cm ezjail-admin create -c simple
+for image based jails or
+.Cm ezjail-admin create -c ''
+for non-image jails. 
+.br
+Default:
+.Em NO .
+.It ezjail_jailzfs (str)
+The name of the parent ZFS-dataset which ezjail will use to create
+jails on. It will be mounted in
+.Em ezjail_jaildir .
+Setting this will automatically enable ezjail managing jails in separate
+ZFS-datasets.
+.br
+Default:
+.Em none .
+.It ezjail_zfs_properties (str)
+Default properties ZFS will use for creating datasets. See
+.Xr zfs 1m
+for details. ADVANCED, be very careful!
+.br
+Default:
+.Em none .
+.It ezjail_default_retention_policy (str)
+Policy for the
+.Cm ezjail-admin snapshot
+subcommand to keep older snapshots. See
+.Xr ezjail-admin 1
+for details.
+.br
+Default:
+.Em none .
+.El
+.Sh FILES
 EZJAIL_PREFIX/etc/ezjail.conf
 .br
 EZJAIL_PREFIX/etc/rc.d/ezjail.sh
-.SH "SEE ALSO"
+.Sh SEE ALSO
-ezjail-admin(1), ezjail(5), jail(8), devfs(5), fdescfs(5), procfs(5)
+.Xr ezjail-admin 1 ,
-.SH AUTHOR
+.Xr ezjail 5 ,
-Dirk Engling <erdgeist@erdgeist.org>
+.Xr jail 8 ,
+.Xr devfs 5 ,
+.Xr fdescfs 5 ,
+.Xr procfs 5 .
+.Sh AUTHOR
+Dirk Engling
+.Aq erdgeist@erdgeist.org .
+.Pp
+The man page is based on a draft by
+.An JoeB
+.Aq joeb1@a1poweruser.com
+and was rewritten by
+.An Frederic Perrin
+.Aq frederic.perrin@resel.fr .

man7/ezjail.7

@@ -0,0 +1,708 @@
+.Dd December 5, 2013
+.Dt EZJAIL 7 USD
+.Os
+.Sh NAME
+.Cm ezjail
+.Nd Jail administration framework.
+.Sh SYNOPSIS
+.Nm ezjail-admin Ar command arguments...
+.Sh OVERVIEW
+The ezjail commands provide a simple way to create multiple jails
+using FreeBSD's jail system. It simplifies jail administration effort
+and minimizes jail system resource usage.
+.Pp
+If you are not familiar with the FreeBSD jail concept, please refer to
+.Xr jail 8
+before continuing. For additional design information, see the ezjail
+site at
+.Li http://erdgeist.org/arts/software/ezjail .
+.Sh DESCRIPTION
+The ezjail system enables the system administrator to create multiple
+OS-level virtualization containers called jails. Services like web
+servers, mail servers, FTP servers, are typically under frequent attack
+from the public Internet and are exposed to possible compromise. The
+typical usage of jails is to run a single service in each jail and if
+that service becomes compromised the rest of the jails and the host
+system are protected from also being compromised.
+.Pp
+The major shortcoming of jails is that each jail has its own copy of
+the world. This eats disk space, inodes, and more importantly,
+prevents the sharing of binaries images between jails, thus increasing
+the memory pressure on the host system. In addition, this causes a
+major administration headache when comes the time to update the host
+system, as each jail needs to be updated independently.
+.Pp
+Ezjail addresses these problems by creating a single basejail (a read-only
+.Xr nullfs 4
+mounted directory) populated with the same binaries as the host
+system which is then shared across all the other service jails created
+by ezjail. Is is possible to update the base jail (and thus all the jails) in
+a single ezjail command.
+.Pp
+Typical usage of jails include separation of services, creating test
+environments, consolidation of different services on a single physical
+host, and more.
+.Sh EZJAIL SYSTEM
+The administrative interface to the ezjail system is the
+.Xr ezjail-admin 8
+command. It is used to install the ezjail environment, create new
+jails, archive, restore, delete and update jails, open a jail console,
+and list the status of all the jails. See below for example usage, and
+refer to its man page for complete usage details.
+.Pp
+Ezjail reads its configuration from its
+.Xr ezjail.conf 5 .
+Normally it will not be necessary to edit this file, as some sane defaults
+are provided. A sample configuration is installed as
+.Pa EZJAIL_PREFIX/etc/ezjail.conf.sample .
+.Pp
+A script is also installed as
+.Pa ezjail
+in the rc.d system to allow jails under ezjails control to be started at boot
+time, given ezjail is enabled by setting the
+.Xr rc.conf 5
+variable
+.Dq Li $ezjail_enable
+to
+.Dq Li YES .
+.Sh WHAT'S IN A JAIL
+.Ss The life of an ezjail installation
+The base jail is first created by running
+.Nm Cm update
+or
+.Nm Cm install .
+Example usage of this command is section
+.Sx EXAMPLES .
+This will create the base jail, setup a template jail used to
+setting up new jails, install an example flavour (see below) and
+configure miscellaneous things.
+.Pp
+This step is necessary before using the ezjail system. In particular,
+it is not possible to create new jails without initializing the base
+jail in advance.
+.Pp
+Once the base jail has been created, new jails may be created with
+.Nm Cm create .
+A new jail is defined by its name and can have one or multiple IP
+addresses. Creating a new jail involves copying the template jail to the
+new location, configuring
+.Xr nullfs 4
+mounts for giving access to the base jail, and little more. A jail
+that has just be created occupies about 2MB of disk space ; when
+running, only a handful of daemons (cron, syslog, sendmail mainly) use
+memory.
+.Pp
+After their creation, jails may be archived to a
+.Xr pax 1
+archive, restored, and eventually deleted.
+.Pp
+When a new version of FreeBSD is released, or when an errata is
+published, only the base jail need to be updated. Both source upgrades
+and binary upgrades (using
+.Xr freebsd-update 8 )
+are supported. The
+.Xr ports 7
+collection may also be updated by ezjail, but individual ports need to
+be upgraded individually by the administrator.
+.Ss Anatomy of a Jail
+In the ezjail system, a jail is defined by a root directory and a
+couple of configuration values, mainly a name and IP addresses. The
+root directory of the jail contains only the jail-specific files:
+configuration files, data files, and ports installed by the
+administrator. The base system is shared amongst all jails, using a
+.Xr nullfs 4
+mount. This saves space and inodes (especially when the ports
+collection in made available to the jails), and also memory, as the
+kernel is now able to share copies of running programs between the
+jails.
+.Pp
+Unless the variable
+.Dq Li $ezjail_jaildir
+has been set by the administrator, the root directory of the jail is
+kept in
+.Pa /usr/jails ,
+which therefore needs to reside on a partition big enough.
+.Pp
+There are also file-based jails, in which the storage space for the
+jail is kept in a file mounted with
+.Xr mdconfig 8 .
+There are two advantages to image jails. The amount of disk space
+allocated to the jail is limited, while normal jails have no bound on
+the amount of disk space they use. On the other hand, the space
+dedicated to the jail is no longer available to the host, even if the
+jail doesn't use all its allocated space.
+.Pp
+Image jails may also be encrypted using
+.Xr bde 4
+or
+.Xr geli 8 ,
+depending on the options given at creation time.
+.Ss Using ZFS
+To give more precise control over the resources consumed by a jail,
+ezjail allows putting each jail in its own
+.Xr zfs 8
+filesystem. See
+.Sx Jail Creation Examples
+for details.
+.Pp
+Also, ezjail can be configured to install its basejail and the accompanying
+template for all new jails into its own filesystem. Set the
+.Dq Li $ezjail_use_zfs
+variable in your
+.Pa ezjail.conf
+to
+.Dq YES
+before running
+.Nm Cm update
+or
+.Nm Cm install .
+.Pp
+To use any zfs feature in ezjail, you first need to configure the destination
+ZFS filesystem using the
+.Dq Li $ezjail_jailzfs
+variable.
+.Pp
+You can use ZFS jails without installing the basejail into its own ZFS
+filesystem and vice versa. In order to create ZFS jails by default, set the
+.Dq Li $ezjail_use_zfs_for_jails
+variable to
+.Dq YES .
+.Ss Per-Jail options
+As we saw earlier, a jail is described by a file in
+.Pa EZJAIL_PREFIX/etc/ezjail/ .
+This file has the same name as the jail it configures. It is a set of
+variables interpreted by
+.Xr sh 1 ,
+much like
+.Xr rc.conf 5
+is. This file is created at the same time as the jail, and usually
+doesn't require tweaking from the administrator.
+.Pp
+In addition to the variables described below, any variable used by the
+init script
+.Pa /etc/rc.d/jail
+may be added manually by the administrator. The following variables
+are handled by ezjail, replacing JAILNAME with the actual name of the jail:
+.Bl -tag -width indent
+.It jail_JAILNAME_hostname
+The hostname of the jail. Defaults to the name of the jail, unless
+special characters needed to be stripped.
+.It jail_JAILNAME_ip
+The IP addresses the jail is allowed to use.
+.Pp
+Since FreeBSD 7.2,
+several IP addresses may be given, separated by commas.
+.Pp
+Since FreeBSD 9.0
+each IP address can be prefixed by an interface name followed by the pipe
+symbol. It will then automatically be configured on that interface when the
+jail is started and removed from the interface when the jail stops. (You
+will probably have to escape the pipe symbol, though.)
+.It jail_JAILNAME_rootdir
+The directory holding the jail files (the directory used as a mount
+point for file-based jails). Defaults to the jail name inside
+.Dq Li $ezjail_jaildir .
+.It jail_JAILNAME_exec_start
+The command to run inside the jail when starting it. Defaults to
+.Dq Li $ezjail_exec_start
+or
+.Dq Li /bin/sh /etc/rc .
+.It jail_JAILNAME_exec_stop
+The command to run inside the jail when stopping it. Defaults to the
+empty string, which means
+.Dq Li /bin/sh /etc/rc.shutdown .
+.It jail_JAILNAME_mount_enable
+A boolean
+.Dq ( YES
+or
+.Dq NO ) ,
+that specifies whether the filesystems in
+.Pa /etc/fstab. Ar JAILNAME
+are carried out. Set by ezjail to
+.Dq Li YES ,
+set to
+.Dq Li NO
+at your own risk.
+.It jail_JAILNAME_devfs_enable
+A boolean specifying whether to mount a
+.Pa /dev
+filesystem inside the jail. Defaults to
+.Dq Li $ezjail_devfs_enable ,
+or
+.Dq Li YES .
+.It jail_JAILNAME_devfs_ruleset
+The ruleset to apply when mounting a
+.Pa /dev
+filesystem inside a jail. Defaults to
+.Dq Li $ezjail_devfs_ruleset ,
+or
+.Dq Li devfsrules_jail .
+.It ezjail_JAILNAME_procfs
+A boolean specifying whether to mount a
+.Pa /proc
+filesystem inside the jail. Defaults to
+.Dq Li $ezjail_procfs_enable ,
+or
+.Dq Li YES .
+.It ezjail_JAILNAME_fdescfs
+A boolean specifying whether to mount a
+.Pa /dev/fs
+filesystem inside the jail. Defaults to
+.Dq Li $ezjail_fdescfs_enable ,
+or
+.Dq Li YES .
+.It ezjail_JAILNAME_image
+The path to the image file backing the jail, if the jail is
+file-based; or the empty string.
+.It ezjail_JAILNAME_imagetype
+The type of the image, if the jail is file-based; the empty string
+otherwise.
+.It ezjail_JAILNAME_attachparams
+The parameters to pass to the tool used to decrypt file-based,
+encrypted jails. Initialized from the
+.Fl C
+option when creating such a jail, or the empty string.
+.It ezjail_JAILNAME_attachblocking
+.Dq Li YES
+if the jail requires interaction with the administrator when starting
+(typically, encrypted jails that needs a password to be decrypted).
+.It ezjail_JAILNAME_forceblocking
+If
+.Dq Li YES ,
+start the jail even when it is marked as blocking.
+.It ezjail_JAILNAME_zfs_datasets
+For ZFS jails, additional ZFS datasets to attach to the jail when
+starting it. Taken from the
+.Fl z
+option when configuring a jail; the empty string otherwise.
+.It ezjail_JAILNAME_cpuset
+The processor set to place the jail in when starting it (see
+.Xr cpuset 1 ) .
+Taken from the
+.Fl c
+option when configuring a jail; the empty string otherwise.
+.It ezjail_JAILNAME_fib
+The network view to give to the jail (see
+.Xr setfib 1 )
+when starting it. Taken from the
+.Fl f
+option when configuring the jail; the empty string otherwise.
+.It ezjail_JAILNAME_parameters
+The parameter set to be configured to the jail (see
+.Xr jail 8 )
+when starting it. You need to configure this by hand.
+.It ezjail_JAILNAME_post_start_script
+The path to a script that will be executed after the jail
+successfully was created. The script receives two parameters,
+the jid and the jail name.  You need to configure this by hand.
+.El
+.Pp
+In addition to these
+.Xr sh 1 Ns No -style
+variables, the administrator may add comment lines starting with
+.Dq PROVIDE: ,
+.Dq REQUIRE:
+and
+.Dq BEFORE: .
+These comments are used by
+.Xr rcorder 8
+to determine the order in which the jails are started. The default is
+to keep
+.Dq REQUIRE
+and
+.Dq BEFORE
+empty, meaning the jails are started in no particular order.
+.Ss Flavours
+When a jail is created, it is not configured; in particular you likely
+want to edit files such as
+.Pa /etc/resolv.conf , /etc/localtime
+and others. You may also want to create some system users, maybe
+enable
+.Xr sshd 8 .
+Ezjail solves this problem by using the concept of
+.Dq flavours .
+When a flavour is selected at jail creation time, the flavour
+directory tree is merged into the new jail's directory tree. In
+addition, the jail is configured so that on its first boot, the file
+.Pa ezjail.flavour
+is executed.
+.Pp
+As part of the install sub-command, the flavour base directory
+was created as
+.Pa /usr/jails/flavours
+and populated with an single flavour named
+.Cm example .
+This flavour contains 3 files customized for running in a
+jail
+.Pa ( etc/make.conf , etc/periodic.conf , etc/rc.conf ) .
+The example
+.Pa ezjail.flavour
+also show how to create users, and introduce the convention of placing
+packages in
+.Pa /pkg
+that are installed when the jail is first brought up. You are
+encouraged to copy the example flavour to create your own flavour.
+Typical flavour usages include setting up jails with site-specific
+configuration, creating classes of jails for development or testing
+(such as a webdev flavour that would install Apache with your
+favourite web development framework), pre-creating local users, and so
+on.
+.Ss Updating the Base Jail
+We already mentioned how easy it is to update jails, since only one
+copy needs to be updated. Ezjail only handles updating the base
+system; updating the ports is left to the administrator (but see
+.Dq Li ports-mgmt/jailaudit
+for a way to get notified of ports in need of an update). Updates are
+handled with the
+.Nm Cm update
+command. It is possible to update the base jail from source or from
+binary packages. If a base jail already exists, the
+.Cm update
+command installs the world in a temporary directory before moving it
+to the basejail, thus leaving intact all installed libraries. After
+making sure all software running in the jails is linked with the new
+libraries, you may want to remove the old library versions. It is
+often a good idea to update the jails when a new kernel is installed
+in the host, using the same sources.
+.Ss Starting Jails
+Like all
+.Xr rc 8
+scripts, the ezjail script
+.Pa EZJAIL_PREFIX/etc/rc.d/ezjail
+accepts parameters
+.Cm start , restart No and Cm stop, No running, restarting and stopping
+all (non-blocking) jails under ezjail's control by default. When passed an
+additional list of jails, only these jails are acted upon.
+.Pp
+The order in which jails are started is determined by the
+.Xr rcorder 8
+tool, using cues from the jail configurations in ezjails
+.Pa EZJAIL_PREFIX/etc/ezjail
+control directory.
+.Pp
+The script examines its config, attaches and mounts images, and sets
+variables for each jail in the list before passing its command on
+to the
+.Pa /etc/rc.d/jail
+script.
+.Pp
+To interactively start all crypto image jails (or those depending on
+them), that were not automatically started during booting, use the
+.Cm startcrypto
+parameter.
+.Pp
+Note that jails configured to be in the
+.Em norun
+state (using
+.Nm Cm config Fl r Ar norun Ar jailname )
+are never started by the ezjail rc script.
+.Pp
+As a convenient shortcut, the
+.Nm
+command invokes the rc.d script and passes the corresponding parameters,
+if they look like valid parameters.
+.Pp
+Even if ezjail is not enabled in the
+.Xr rc.conf 5 ,
+rc.d/ezjail can be used to start and stop jails by prepending
+.Cm force No or Cm one No to the Cm start, restart No or Cm stop No parameter.
+Refer to
+.Xr rc 8
+for details.
+.Ss Snapshots and retention policies
+Jails residing in their own zfs and their corresponding zfs data sets can be
+automatically snapshot by the
+.Cm ezjail-admin snapshot
+subcommand. Taking snapshots of all jails before a major update is considered
+best practise. However, when taking snapshots regularly, the amount of disc
+space used can be considerable.
+.Pp
+Therefore ezjail allows you to set retention policies that describe how many
+of your snapshots you want to keep for one or all jails or a particular zfs. See
+the description of the snapshot command in
+.Xr ezjail-admin 5
+for details.
+.Pp
+A retention policy consists of one or multiple windows for which ezjail guarantees
+to keep at least one and at most two snapshots. A simple example:
+.D1 $ezjail_default_retention_policy="1d 2w 1y"
+will ensure ONE snapshot for the last day, for the last two weeks before that day and
+then for one snapshot in the year before the two-week window. Valid multipliers are
+(m)inutes, (h)ours, (d)ays, (w)eeks and (y)ears.
+.Pp
+Windows can be repeated by prepending them with a number and the letter x:
+.D1 $ezjail_test_com_retention_policy="24x1h 6x1d 3x1w 11x4w KEEP"
+will set the retention policy for jail test.com to keep hourly snapshots for one
+day, then daily snapshots for the rest of the week, weekly snapshots for the rest of
+the month, monthly snapshots for the rest of the year.
+.Pp
+The magic keyword KEEP at the end of the list will make ezjail not delete snapshots
+older than the oldest window. It is your responsibility to keep the list in an order
+that makes keeping snapshots possible, i.e. not placing one-hour-windows after
+one-year-windows.
+.Ss Remarks & Tips
+Jails can be either accessed from the network, for instance by using
+.Xr ssh 1 ,
+or from the host system by using the
+.Cm console
+command, which gives you an interactive shell inside the jail. It is
+also possible to edit the files of a running jail, and the
+modifications will appear immediately inside the jail environment.
+When dealing image-based, the
+.Cm config -i attach
+command allows one to access the disk of a file-based jail without starting it.
+.Pp
+Raw sockets are disallowed by default for all jails. This is not a ezjail
+restriction, but a design default of the jail command. This means the
+.Xr ping 8
+command will get
+.Dq Operation not permitted.
+error when used from inside of a jail. There are
+.Xr sysctl 3
+knobs for allowing a jail to access raw sockets, see the
+.Xr jail 8
+man page for details.
+.Pp
+Once your jail has network access, then all your normal application
+install functions are available, right from the jails console. In
+particular, if the ports collection was installed, it can be used as
+if from the host system. A modified
+.Pa make.conf
+file is installed by the example flavour, that enable the ports
+collection to work even with a read-only
+.Pa /usr/ports .
+.Pp
+It is possible to change the IP address of a jail by editing its
+configuration file in
+.Pa EZJAIL_PREFIX/etc/ezjail
+and restarting the jail.
+.Pp
+The jails use the same network stack as the host system. In
+particular, that means that if a firewall is needed, it must be
+configured in the host system.
+.Pp
+The ezjail system (and the jails it controls) depends on the
+.Dq Li $ezjail_enable
+variable being set to
+.Dq Li YES
+in
+.Pa rc.conf .
+It is possible to set this variable to
+.Dq Li NO
+if the administrator wants to temporarily disable ezjail, or if she doesn't
+want the jails to be automatically started on boot.
+.Pp
+The ezjail system may be reset to a pristine state by removing all its
+files, that is:
+.Bl -item -compact
+.It
+.Pa /usr/jails/
+.It
+.Pa EZJAIL_PREFIX/etc/ezjail/
+.It
+.Pa EZJAIL_PREFIX/etc/ezjail.conf
+.It
+.Pa /etc/fstab.* No (but check the list of files this matches)
+.El
+.Sh EXAMPLES
+The examples below are only that, examples. The reader is encouraged
+to read the
+.Xr ezjail-admin 8
+man page for definitive documentation of all the options.
+.Ss Initial Binary Installation
+The ezjail system may be bootstrapped either from binary packages, or
+by building from source. The
+.Cm install
+command allow to bootstrap from binary packages, while the
+.Cm update
+deals with installations (and updates) from source.
+.Bl -tag -width indent
+.It Nm Cm install No (without any options)
+Fetch and install binaries for populating the base jail from the
+FreeBSD FTP server. If the host is not running a -RELEASE version, you
+will be asked for the release to install. Neither the man pages nor
+the source nor the ports tree are installed. Note that the FreeBSD FTP
+server is sometimes so busy the download times out. Use the
+.Fl h Ar host
+option to specify a less loaded server, or the
+.Dq Li $ezjail_ftphost
+option in
+.Xr ezjail.conf 8 .
+.It Nm Cm install Fl ms
+Same behavior as above, except that man pages and sources are installed in the
+base jail.
+.It Nm Cm install Fl p
+Same as the first example, but use
+.Xr portsnap 8
+to fetch and extract a full FreeBSD ports tree from
+.Li portsnap.FreeBSD.org
+into the base jail. This is necessary if you plan to install ports at later
+time into service jails.
+.It Nm Cm install Fl P No (note uppercase P)
+Only fetch the current version of the ports tree, adding it to the base jail.
+This allow to either add the ports tree after the initial installation or update the ports tree in the base jail.
+.It Install from a disk image
+Mount and use a downloaded
+.Pa disc1.iso
+CDRom image file.
+.Bd -literal -offset indent
+mdconfig -a -f /usr/8.0-RELEASE-i386-disc1.iso md0
+mount -v -t cd9660 /dev/md0 /mnt
+cd /mnt/8.0-RELEASE
+ezjail-admin install -h file:// -sm
+.Ed
+.Pp
+When the installation finishes, use the following to release the
+.Pa disc1.iso
+.Pa md0
+file.
+.Bd -literal -offset indent
+cd /usr
+umount /mnt
+mdconfig -d -u md0
+.Ed
+.It Install from a local directory
+To fetch the RELEASE base files manually, create a
+.Pa .netrc
+file in your home directory and populate it with this.
+.Bd -literal -offset indent
+machine ftp2.jp.FreeBSD.org
+login anonymous
+password FBSD@home.com
+macdef init
+prompt off
+cd /pub/FreeBSD/releases/i386/8.0-RELEASE
+epsv4 off
+$ getdir base kernels manpages src
+quit
+macdef getdir
+! mkdir $i
+mreget $i/*
+.Ed
+.Pp
+Then issue this command on the command line. If the FTP download
+times out re-issue the FTP command again to resume where it left off.
+.Bd -literal -offset indent
+mkdir /usr/8.0-RELEASE
+cd /usr/8.0-RELEASE
+ftp -v ftp2.jp.FreeBSD.org
+ezjail-admin install -h file:// -sm
+.Ed
+.Pp
+Use this option to target the 8.0-RELEASE files you FTP'ed as the source of
+the running binaries used to populate the base jail. In addition the man
+pages and sources will be installed into the base jail.
+.El
+.Ss From Source Installation and Update
+The
+.Cm update
+is used to both install or update from source the base jail, and for
+updating the base jail from binary packages.
+.Bl -tag -width indent
+.It Nm Cm update Fl b
+Build and install a world from source. The sources are taken from
+.Pa /usr/src
+(but see the
+.Fl s
+flag). This can be used both for creating the initial base jail, and
+for updating it after the host has been upgraded.
+.It Nm Cm update Fl u
+Update the base jail to the next release using
+.Xr freebsd-update 8
+(i.e. using binary packages). This may be used only to update an
+existing installation.
+.It Nm Cm update Fl U s Ar 8.0-RELEASE
+Upgrade the base jail to the host system's release using
+.Xr freebsd-update 8 . This may be used only to upgrade an
+existing installation. Tell freebsd-update which OS version to expect
+in the basejail via the
+.Fl s No option.
+.Pp
+Note: Check
+.Xr uname 1
+and especially the
+.Pa UNAME_r
+environment variable to upgrade to different versions.
+.El
+.Ss Jail Creation Examples
+.Bl -tag -width indent
+.It Nm Cm create Ar www.example.com 10.0.10.1
+Create a new jail. The jail files will reside in directory
+.Pa www_example_com
+in
+.Pa /usr/jails ,
+unless the variable
+.Dq Li $ezjail_jaildir
+has been set to some other value. The jail will only be allowed to use
+the given IP address. A warning will be displayed if this IP address
+is not already configured in the host, or if some network daemon is
+already listening on this address. The name of the jail which will
+appear in the
+.Cm list
+command or which will need to be given to the
+.Cm console
+command is
+.Ar www.example.com .
+.It Nm Cm create Fl f Ar example Fl r Ar webserver www.example.com 10.0.10.2,2001:db8:1:9243::80
+Create a new jail, placing it in directory
+.Pa webserver
+instead of deriving the directory name of the jail from its host name.
+The jail will be created with the flavour
+.Ar example .
+This jail will be given two IP addresses; this is possible only since
+FreeBSD 7.2.
+.It Nm Cm create Fl i Fl s Ar 600M sandbox2 10.0.10.4
+This creates a new file-based jail having a file size of 600 megabytes
+in
+.Pa /usr/jails/sandbox2.img .
+An empty directory,
+.Pa /usr/jails/sandbox2 ,
+will be created, and used as a mount point when starting the jail.
+.It Nm Cm create Fl c Cm bde Fl s Ar 600M sandbox3 10.0.10.5
+This creates a new file based image jail, with
+.Xr gbde 4
+encryption. During the gbde creation process you are asked to enter a
+passphrase that is used as the prime seed value of the encryption process.
+Remember this passphrase, you will be asked for the passphrase every time
+you want to start this jail. As they require administrator interaction,
+jails backed by an encrypted file are not automatically started when the
+system boots.
+.It Nm Cm create Fl c Ar zfs Fl s Ar 1G sandbox4 em1\[rs]|10.0.10.6
+This creates a new zfs filesystem based jail with a default quota of 1
+gigabyte using lzjb compression. It uses the parent ZFS filesystem configured
+in the
+.Dq Li $ezjail_jailzfs
+variable to create the filesystem in. The jail command will add the ip
+address 10.0.10.6 as an alias on the device em1 before starting the jail.
+.El
+.Sh FILES
+.Pa EZJAIL_PREFIX/bin/ezjail-admin
+.br
+.Pa EZJAIL_PREFIX/etc/rc.d/ezjail
+.br
+.Pa EZJAIL_PREFIX/etc/ezjail.conf
+.br
+.Pa EZJAIL_PREFIX/share/examples/ezjail/
+.br
+.Pa EZJAIL_PREFIX/etc/ezjail/*
+.br
+.Pa /usr/etc/fstab.*
+.Sh SEE ALSO
+.Xr ezjail-admin 8 ,
+.Xr ezjail.conf 5 ,
+.Xr jail 8 ,
+.Xr nullfs 4 ,
+.Xr zfs 8 .
+.Pp
+Interesting additional tools include:
+.Dq Li ports-mgmt/jailaudit .
+.Sh AUTHOR
+.An Dirk Engling
+.Aq erdgeist@erdgeist.org .
+.Pp
+The man page is based on a draft by
+.An JoeB
+.Aq joeb1@a1poweruser.com
+and was rewritten by
+.An Frederic Perrin
+.Aq frederic.perrin@resel.fr .

man8/ezjail-admin.8

@@ -0,0 +1,658 @@
+.Dd December 5, 2013
+.Dt EZJAIL-ADMIN 8 USD
+.Os FreeBSD
+.Sh NAME
+.Nm ezjail-admin
+.Nd Administrate ezjail environment
+.Sh SYNOPSIS
+.Nm Cm install
+.Op Fl mMpPsS
+.Op Fl h Ar host
+.Op Fl r Ar release
+.Nm
+.Cm create
+.Op Fl bx
+.Op Fl f Ar flavour
+.Op Fl r Ar jailroot
+.Op Fl a Ar archive
+.Op Fl c Ar jailtype Fl s Ar imagesize Op Fl C Ar attachargs
+.Op Fl z Ar parentzfs
+.Bk -words
+.Ar jailname ipaddress Ns Op Ar ,ipaddress2,...
+.Ek
+.Nm
+.Cm console
+.Op Fl f
+.Op Fl e Ar command
+.Ar jailname
+.Nm
+.Cm list
+.Nm
+.Cm start | stop | restart | startcrypto | stopcrypto Ar jailname...
+.Nm
+.Cm config
+.Op Fl r Ar run | norun | test
+.Op Fl n Ar newname
+.Op Fl i Ar attach | detach | fsck
+.Op Fl z Ar newdataset
+.Op Fl c Ar newcpuset
+.Op Fl f Ar newfib
+.Ar jailname
+.Nm
+.Cm delete
+.Op Fl wf
+.Ar jailname
+.Nm
+.Cm archive
+.Op Fl Af
+.Op Fl a Ar archive
+.Op Fl d Ar archivedir
+.Ar jailname...
+.Nm
+.Cm restore
+.Op Fl f
+.Op Fl d Ar archivedir
+.Ar archive | jailname...
+.Nm
+.Cm snapshot
+.Ar [jailname...]
+.Nm
+.Cm update
+.Op Fl s Ar sourcetree | sourceosversion
+.Op Fl p
+.Fl b | Fl i | Fl P | Fl u | Fl U
+.Sh DESCRIPTION
+The
+.Nm
+utility is used to manage the ezjail environment and all the jails inside the
+ezjail scope. This man page describes the invocation of
+.Nm .
+Refer to
+.Xr ezjail 7
+in order to get an introduction to the usage of ezjail, as well as
+usage examples.
+.Pp
+The description of some options ends with
+.Sq Variable: Dq Li $ezjail_abcd .
+This means that the default value of the option may be overridden by setting
+this variable in
+.Xr ezjail.conf 5 .
+.Ss Nm Cm install
+This function sub-command is normally run once in the life of the ezjail
+environment. It allocates the directory structure used by ezjail and populates
+the base jail using the minimal distribution set from a FreeBSD FTP server.
+.Pp
+The default location for ezjail's basejail is in
+.Pa /usr/jails ,
+so be sure you have enough space there (a FreeBSD base release without man
+pages, sources and ports is around 120MB). This location may be modified in
+.Xr ezjail.conf 5 .
+.Pp
+See also
+.Nm
+.Cm update
+to install the base jail from source, as well as a method to update
+the base jail using
+.Xr freebsd-update 8 .
+.Pp
+The following options are available:
+.Bl -tag -width indent
+.It Fl m
+Fetch and install man pages (ca. 10MB).
+.It Fl M
+Fetch and install man pages, without (re)installing the base jail. May be used
+to add the man pages to the base jail after the initial installation.
+.It Fl s
+Fetch and install sources (ca. 450MB).
+.It Fl S
+Fetch and install sources, without (re)installing the base jail.
+.It Fl p
+Invoke the
+.Xr portsnap 8
+utility to fetch and extract a FreeBSD ports tree from
+.Li portsnap.FreeBSD.org
+(ca. 475MB). When a ports tree is added to the base jail, a modified
+.Pa make.conf
+containing reasonable values to function in the jailed environment is added to
+the new jail template so all jails created from the new jail template will
+have a working ports environment. See the appendix
+.%B Using Portsnap
+in the
+.%B FreeBSD Handbook
+for details or
+.Xr portsnap 8 .
+.It Fl P
+Fetch and extract a ports tree, without (re)installing the base jail.
+.It Fl h Ar host
+Set the remote host to fetch FreeBSD distribution sets from. If absent the
+default host
+.Li ftp.FreeBSD.org
+is used. Variable:
+.Dq Li $ezjail_ftphost .
+.Pp
+It is possible to install from the
+.Li disc1
+CD-ROM, or an extracted -RELEASE directory, by specifying the
+.Ar host
+argument as
+.Pa file://path/to/source .
+.It Fl r Ar release
+Install this release of FreeBSD in the base jail, instead of the version
+returned by
+.Dq Li uname -r
+on the host system. Note that the FreeBSD FTP servers usually provide only
+-RELEASE versions, not -STABLE nor -CURRENT versions; you will be prompted for
+confirmation when trying to install a non -RELEASE version. If you want to
+install a -CURRENT version, you may have to compile from source the base jail;
+see the
+.Nm Cm update
+sub-command for this.
+.El
+.Ss Nm Cm create
+Create a new jail inside ezjail's scope. It either copies the new jail
+directory tree template or an ezjail archive directory tree to new jail root
+directory,
+.Pa /usr/jails/ Ns Ar jailname
+by default. Jailname and IP address are mandatory parameters.
+.Pp
+When a new jail is created, a corresponding new
+.Pa /etc/fstab. Ns Ar jailname
+file is also created, with a
+.Xr nullfs 5
+mount giving access to the base jail from the new jail.
+.Pp
+The following operands are mandatory:
+.Bl -tag -width indent
+.It Ar jailname
+The name of the jail. It is customary to use the network name of the jail,
+such as
+.Dq Li jail1.example.com
+(or maybe simply
+.Dq Li jail1 ) ,
+but really any name may be used.
+.Pp
+It is an error to have several jails of the same name, note that due to
+ezjail's internal jailname sanitation,
+.Dq Li sand-box.com
+and
+.Dq Li sand_box_com
+are considered identical. Some names such as
+.Dq Li basejail
+and
+.Dq Li flavours
+are reserved for ezjails internal administrative purposes.
+.It Ar ipaddress Ns Op Ar ,ipaddress2,...
+The IP address or addresses of the jail. Since FreeBSD 7.2, it is possible to
+assign several several IPv4 or IPv6 addresses to a jail, by separating them
+with commas. Previous versions of FreeBSD allowed only a single IPv4 address
+per jail.
+.Pp
+From FreeBSD 9.0 the ipaddresses may be prefixed with an interface name, followed
+by the pipe symbol. It will then automatically be configured as an alias on that
+interface when the jail starts. Else
+.Nm
+will display a warning if the requested address is not found on any interface,
+and the jail will probably not start.
+.Pp
+It is common to bind jails to loopback addresses, so they provide services
+visible to other jails only.
+.El
+.Pp
+The following options are available:
+.Bl -tag -width indent
+.It Fl r Ar jailroot
+Use this name as the directory name of the new jail. Without this option, it
+is derived from the jail's name. If this option is given and does not start
+with a '/', it is interpreted as relative to ezjail's root directory
+.Pa (/usr/jails
+by default). If a specified jailroot path lies outside the ezjail root
+directory, a soft link is created inside
+.Pa /usr/jails/
+pointing to the location of the newly created jail.
+.It Fl a Ar archive
+Restore a jail from an archive created with
+.Nm Cm archive .
+The archive files are kept in
+.Pa /usr/jails/ezjail_archives
+by default. Use
+.Pa -
+to restore an archive from the standard input.
+.Pp
+You will probably need to tidy up things inside an ezjail if you migrate it
+between different ezjail environments. This may include (but is not limited
+to) reinstalling ports or packages for different CPUs or library versions. You
+may also need to copy some libraries from the source host's base jail.
+.Pp
+See also
+.Nm Cm restore ,
+if you only want to revert to an old jail's state from an archive on the same
+release version.
+.It Fl x
+This flag indicates that a jail root directory for that jail already exists.
+In this case, ezjail will only import the jail to its control directory. Sanity
+checks are performed.
+.It Fl f Ar flavour
+Install the requested
+.Ar flavour
+in the new jail. Refer to
+.Xr ezjail 7
+for more details on flavours.
+.Pp
+This option may not be used with the
+.Fl a
+option.
+.It Fl c Cm simple | bde | eli | zfs
+Create an image jail of the given type.
+.Pp
+.Cm simple, bde No and Cm eli
+image jails are file backed memory discs attached as
+.Xr md 4
+devices, so the jail can never grow beyond its allocated size and can
+even be mounted read only. The jail will be stored in a file named
+.Ar jailname Ns Pa .img ,
+unless
+.Fl r Ar jailroot
+is given, in which case the jail is stored in
+.Ar jailroot Ns Pa .img .
+.Pp
+Both
+.Cm bde No and Cm eli
+jails use the
+.Xr geom 4
+framework to encrypt all data written to the image file using
+.Xr gbde 4
+(for
+.Cm bde )
+or
+.Xr geli 8
+(for
+.Cm eli ) .
+.Pp
+Unless you pass some options to the encryption geom commands using the
+.Fl C
+parameter, you will be prompted for a passphrase to protect the crypto
+image. Note that, since starting normal encrypted image jails requires user
+interaction to enter the passphrase, they will
+.Cm NOT automatically be started at boot time. No Use
+.Cm ezjail-admin startcrypto No to manually start all crypto image jails.
+.Pp
+A
+.Cm zfs
+jail is backed with a
+.Xr zfs 8
+filesystem, whose initial quota is given with the
+.Fl s
+option. The filesystem by default
+(see the
+.Fl z
+option) is created in the
+.Dq Li $ezjail_jailzfs
+parent filesystem and compressed using the lzjb method, as set in
+the
+.Dq Li ezjail_zfs_jail_properies
+variable, both values configured in
+.Xr ezjail.conf 5 .
+.Pp
+In each case, the
+.Fl s
+flag is mandatory when creating a file backed jail (i.e. any image that is
+not zfs backed). An empty directory (without the
+.Pa .img
+suffix in the case of file-based jails) will be created and used as a mount
+point when running the jail.
+.It Fl z Ar parentzfs
+Normally zfs jails are created in a child of the same zfs, ezjail keeps its
+working directories in, as configured in the
+.Dq Li ezjail_jailzfs
+variable set in
+.Xr ezjail.conf 5 .
+Use this option to override this default.
+.Pp
+This option implies
+.Fl c Ar zfs .
+.It Fl s Ar imagesize
+Allocate this size to the jail. Without an unit, the size is in bytes. The
+valid suffix values are b/B for blocks (i. e. 512 bytes), k/K for kilobytes,
+m/M for megabytes, and g/G for gigabytes. As a reference point, a newly
+created jail requires 2 MB.
+.Pp
+It is not possible to increase the size of file-based jails after their
+creation, short of creating a new image jail with a larger size.
+.It Fl C Ar imageopt
+Pass this argument to
+.Xr gbde 8
+or
+.Xr geli 8
+when initialising crypto image jails. The
+.Fl P No and Fl K
+(and
+.Fl L
+for
+.Xr gbde 4 )
+options will be translated and passed to the respective attach command when
+starting the jail. You will have to escape parameters with single ticks to
+protect them from shell expansion.
+.It Fl i
+Synonym of
+.Fl c Cm simple .
+.It Fl b
+Tell ezjail that starting this jail would block unattended reboots. This may
+happen when certain services need private SSL keys that require the user to
+interactively enter a passphrase. The jail is then not automatically started
+at boot time.
+.El
+.Ss Nm Cm console
+Attach your console to the selected jail. You are logged in as root by
+default.
+.Pp
+The following options are available:
+.Bl -tag -width indent
+.It Fl f
+Start the jail if it is not running yet.
+.It Fl e Ar command
+Use
+.Ar command
+instead of the default
+.Dq /usr/bin/login -f root .
+login command. A one time change to use a different user can be
+accomplished by using
+.Fl e Qq Li /usr/bin/login -f user .
+Variable:
+.Dq Li $ezjail_default_execute .
+.El
+.Ss Nm Cm list
+List all jails inside ezjail's scope. They are sorted by the order they start
+up, as defined by
+.Xr rcorder 1 .
+.Pp
+The first column is the status flag consisting of 2 or 3 letters. The first
+letter is the type of jail:
+.Bl -tag -width 4n -offset indent -compact
+.It Sy D
+Directory tree based jail.
+.It Sy I
+File-based jail.
+.It Sy E
+Geli encrypted file-based jail.
+.It Sy B
+Bde encrypted file-based jail.
+.It Sy Z
+ZFS filesystem-based jail.
+.El
+.Pp
+The second letter is the status of the jail:
+.Bl -tag -width 4n -offset indent -compact
+.It Sy R
+The jail is running.
+.It Sy A
+The image of the jail is mounted, but the jail is not running.
+.It Sy S
+The jail is stopped.
+.El
+.Pp
+If present, the third letter,
+.Sy N ,
+means that the jail is not automatically started.
+.Pp
+The following columns are the JID (when it is running), the IP addresses, the name and the full path directory name of the jail.
+.Ss Nm Cm start | restart | stop | startcrypto | stopcrypto Op Ar jailname ...
+This is a shortcut to the
+.Xr rc 8
+.Cm ezjail
+script. Refer to
+.Xr ezjail 7
+section
+.Pa Starting jails
+for details.
+.Pp
+Note that, if ezjail is not enabled in
+.Xr rc.conf 5
+with
+.Dq Li ezjail_enable= Ns Qq Li YES ,
+nothing happens.
+.Pp
+Since starting crypto image jails requires interaction with the administrator, they are not run at
+boot time. Use
+.Cm startcrypto No to run them all at once.
+.Ss Nm Cm config Ar jailname
+Manage parameters of specific ezjails. For running jails, most of the
+configuration changes described below will not be applied until the next time
+the jail is restarted.
+.Pp
+The following options are available:
+.Bl -tag -width indent
+.It Fl r Cm run | norun | test
+Set the jail to be automatically started or not on boot.
+.sp
+Note that the test parameter can be used to check if an ezjail exists, in this case the script will return with an exit code of zero and the runnable state on standard out. A non-zero exit code will be returned if the jail does not exist.
+.It Fl n Ar newname
+Rename the jail. Unless a custom root directory was given with the
+.Fl r
+flag when creating the jail, the root directory will be renamed as well. A
+running jail may not be renamed.
+.It Fl i Cm attach | detach | fsck
+Only valid for stopped image jails. Attaching a jail means making the content
+of the root of the jail accessible from the host. No other sub-commands will
+function on an jail while its image is attached. With
+.Cm fsck ,
+the image jail is attached,
+.Xr fsck 8
+is run, then the image jail is detached. You can only fsck image based jails.
+.It Fl z Ar newdataset
+Set the given ZFS dataset to be mounted inside the jail file system
+when it is started.
+.It Fl f Ar newfib
+Change the FIB of the jail (see
+.Xr setfib 2 ) .
+.It Fl c Ar newcpuset
+Change the CPU affinity set of the jail (see
+.Xr cpuset 2 ) .
+.El
+.Ss Nm Cm delete Ar jailname
+Delete a jail. By default, this command only deletes ezjail's control file for
+the selected jail as well as
+.Pa /etc/fstab. Ns Ar jailname .
+The
+.Pa /usr/jails/ Ns Ar jailname
+directory is not deleted.
+.Bl -tag -width indent
+.It Fl f
+Stop the jail before deleting it.
+.It Fl w
+Delete the directory or the file backing the jail.
+.El
+.Ss Nm Cm archive Op jailname
+Create a backup of one or all jails. The jail's root directory tree is backed
+up as a
+.Xr pax 1
+archive. By default, the jail needs to be stopped.
+.Bl -tag -width indent
+.It Fl A
+Archive all jails. You must neither specify an archivename nor a jailname in
+this case.
+.It Fl a Ar archivename
+Use this name for the archive file. If absent, the archive file name is
+derived from the jail name, with the current date and time appended to the
+archive's file name. Use
+.Pa -
+to write to stdout.
+.It Fl d Ar directory
+Save the archive in this directory. If this option is not given and
+.Dq Li $ezjail_archivedir
+is not set, the archive is saved in the default directory.
+Variable:
+.Dq Li $ezjail_archivedir .
+.It Fl f
+Archive the jail even when it is running.
+.El
+.Pp
+Use
+.Nm Cm restore
+or
+.Nm Cm create Fl a Ar archive
+to restore an archive.
+.Ss Nm Cm restore
+Create new ezjails from archived versions. It tries to collect all
+information necessary to do that without user interaction from the
+user.
+.Pp
+The following operand is mandatory:
+.Bl -tag -width indent
+.It Ar archive | jailname
+Restore this jail. If only the jail name is given,
+.Nm
+will use the most recent archive file matching the name you specified.
+To restore an older version, specify the complete archive file name
+(file name with the date and time of the archive appended to it).
+.El
+.Pp
+The following options are available:
+.Bl -tag -width indent
+.It Fl d Ar archivedir
+Search the archive file in this directory. If this option is not given, the
+archive is searched in
+.Dq Li $ezjail_archivedir .
+.It Fl f
+Restore the archive even if running on a host different from
+where it was archived. Be default,
+.Nm
+will refuse to restore an archive if the archived host system's hostname,
+its FreeBSD version or CPU architecture do not match the current host.
+.El
+.Ss Nm Cm snapshot [jailname...]
+Takes zfs snapshots of some or all (zfs) ezjails and their zfs datasets and
+optionally destroys older snapshots according to a configured retention
+policy.
+.Pp
+The zfs snapshots will be named @ez-autosnap- with the date appended in format
+“%Y%m%d%H%M”. List all auto snapshots with
+.Dq Li /sbin/zfs list -H -t snapshot | grep @ez-autosnap- .
+.Pp
+You can set (and override in that order) the retention policy globally in your
+.Dq Li $ezjail_default_retention_policy
+.Xr ezjail.conf 5
+variable, set them per jail in its config file with their
+.Dq Li $ezjail_retention_policy
+variable or set a User property with the name
+.Dq Li ezjail:autosnap_retention
+on the respective file systems.
+.Pp
+The policy is described by a pattern of space separated
+.Dq Li repeat x window
+entries with the algorithm guaranteeing at least one and at most two snapshots
+in each of the windows, if mathematically possible. See
+.Xr ezjail 7
+for details.
+.Ss Nm Cm update
+Updates ezjail's basejail, or in the
+.Fl b
+or
+.Fl i
+case, install a FreeBSD world from source to be used as basejail.
+.Pp
+Exactly one of the following operand must be specified:
+.Bl -tag -width indent
+.It Fl b
+Build a world from source and install it as the (updated) basejail.
+.Dq make buildworld ; make installworld
+by default using the sources located at
+.Pa /usr/src
+(but see the
+.Fl s
+option).
+.Pp
+As the old basejail is not deleted, but merely overwritten, this usually
+leaves all jails in a state where they still find older versions of libraries
+they were linked against.
+.It Fl i
+As above but only perform a
+.Dq make installworld ,
+assuming the world has already been built. That is highly likely since it is
+recommended to update the basejail along with the host system.
+.It Fl u
+Use
+.Xr freebsd-update 8
+to update the basejail. Note that as
+.Xr freebsd-update 8
+uses
+.Dq Li uname -r
+to determine the currently running system, the base jail and the host
+need to be updated at the same time, without rebooting on the new
+kernel in the meantime.
+.It Fl U
+Use
+.Xr freebsd-update 8
+to upgrade the basejail to the hosts operating system version, or a version
+you may pass freebsd-update's call to
+.Dq uname -r
+via the
+.Pa UNAME_r
+environment variable. Since there currently is no way of inferring the
+osversion currently installed in the basejail, you need to remember the
+original osversion and pass it to this script using the
+.Fl s
+option.
+.It Fl P
+Install only the ports tree, assuming the basejail has already been
+created. This can be done while jails are running. The
+.Xr portsnap 8
+utility is invoked to do the actual work.
+.El
+.Pp
+The following options are available:
+.Bl -tag -width indent
+.It Fl p
+Give the new basejail a copy of FreeBSD's ports tree. The
+.Xr portsnap 8
+utility is invoked to do the actual work.
+.It Fl s Ar sourcedir | sourceosversion
+In the
+.Fl b No and Fl i No case: Use the sources in
+.Ar sourcedir
+instead of
+.Pa /usr/src .
+Variable:
+.Dq Li $ezjail_sourcetree .
+.Pp
+In the
+.Fl U No case: Pass this release tag to
+.Xr freebsd-update 8
+as the source OS version of the basejail.
+.El
+.Pp
+See the
+.Cm install
+sub command to install the basejail from binary packages.
+.Pp
+If the basejail is managed in its own ZFS filesystem, a snapshot of that
+filesystem is taken first.
+.Sh FILES
+.Pa EZJAIL_PREFIX/bin/ezjail-admin
+.br
+.Pa EZJAIL_PREFIX/etc/rc.d/ezjail
+.br
+.Pa EZJAIL_PREFIX/etc/ezjail.conf
+.br
+.Pa EZJAIL_PREFIX/share/examples/ezjail/
+.br
+.Pa EZJAIL_PREFIX/etc/ezjail/*
+.br
+.Pa /usr/etc/fstab.*
+.Sh SEE ALSO
+.Xr ezjail 7 ,
+.Xr ezjail.conf 8 ,
+.Xr jail 8 ,
+.Xr devfs 5 ,
+.Xr fdescfs 5 ,
+.Xr procfs 5 ,
+.Xr portsnap 8 .
+.Sh AUTHOR
+.An Dirk Engling
+.Aq erdgeist@erdgeist.org .
+.Pp
+The man page is based on a draft by
+.An JoeB
+.Aq joeb1@a1poweruser.com
+and was rewritten by
+.An Frederic Perrin
+.Aq frederic.perrin@resel.fr .

share/zsh/site-functions/_ezjail-admin

@@ -0,0 +1,194 @@
+#compdef ezjail-admin
+
+# zsh completion for ezjail -- http://erdgeist.org/arts/software/ezjail/
+# This file is under the Beerware license, like ezjail itself
+
+# Heavily based on http://zsh.sf.net/Guide/zshguide06.html#l177
+
+# Frédéric Perrin, April 2011.
+
+_ezjail () {
+    local cmd
+    if (( CURRENT > 2)); then
+    cmd=${words[2]}
+    # Set the context for the subcommand.
+    curcontext="${curcontext%:*:*}:ezjail-$cmd"
+    # Narrow the range of words we are looking at to exclude `ezjail-admin'
+    (( CURRENT-- ))
+    shift words
+    # Run the completion for the subcommand
+    (( $+functions[_ezjail_cmd_$cmd] )) && _ezjail_cmd_$cmd
+
+    else
+    _values : \
+        "archive[create a backup of one or several jails]" \
+        "config[manage specific jails]" \
+        "console[attach your console to a running jail]" \
+        "create[installs a new jail inside ezjail\'s scope]" \
+        "cryptostart[start the encrypted jails]" \
+        "delete[removes a jail from ezjail\'s config]" \
+        "install[create the basejail from binary packages]" \
+        "list[list all jails]" \
+        "restart[restart a running jail]" \
+        "restore[create new ezjails from archived versions]" \
+        "start[start a jail]" \
+        "stop[stop a running jail]" \
+        "update[create or update the basejail from source]"
+    fi   
+}
+
+_ezjail_cmd_archive () {
+    _arguments -s : \
+    "-d[destination directory]:destination dir:_files -/" \
+    "-a[archive name]:archive name:" \
+    "-f[archive the jail even if it is running]" \
+    - archiveall \
+        "-A[archive all jails]" \
+    - somejails \
+        "*:jail:_ezjail_mostly_stopped_jails"
+}
+
+_ezjail_cmd_config () {
+    _arguments -s : \
+    "-r[run the jail on host boot]:run:(run norun)" \
+    "-n[new jail name]:new name:" \
+    "-c[jail cpuset]:cpu list:" \
+    "-z[ZFS dataset to attach]:zfs dataset:" \
+    "-f[jail FIB number]:fib number:" \
+    "-i[operate on image]:imageaction:(attach detach fsck)" \
+    "*:jailname:_ezjail_jails"
+}
+
+_ezjail_cmd_console () {
+    _arguments -s : \
+    "-e[execute command in jail]:execute:" \
+    "-f[start the jail if it isn't running]" \
+    "*:jailname:_ezjail_mostly_running_jails"   
+}
+
+_ezjail_cmd_create () {
+    _arguments -s : \
+    "-f[flavour for the new jail]:flavour:_ezjail_flavours" \
+    "-x[jail exists, only update the config]" \
+    "-r[name of the root dir]:dir:" \
+    "-a[restore from archive]:archive:_files" \
+    "-A[restore config from archive]:configarchive:_files" \
+    "-c[image type]:imagetype:(bde eli zfs)" \
+    "-C[image parameters]:imageparams:" \
+    "-b[jail start will be synchronous]" \
+    "-i[file-based jail]" \
+    "-s[size of the jail]:jailsize:" \
+    ":jail name:" \
+    ":comma-separated IP addresses:"
+}
+
+_ezjail_cmd_cryptostart () {
+    _ezjail_stopped_jails
+}
+
+_ezjail_cmd_delete () {
+    _arguments -s : \
+    "-w[wipe the jail root]" \
+    "-f[proceed even if the jail is running]" \
+    "*:jail:_ezjail_mostly_stopped_jails"
+}
+
+_ezjail_cmd_install () {
+    _arguments : \
+    - newjail \
+        "-r[FreeBSD release]:release:(8.0-RELEASE 8-STABLE 9-STABLE)" \
+        "-h[host for fetching packages]:remote host:" \
+        "-m[include man pages]" \
+        "-s[include the /usr/src tree]" \
+        "-p[include the ports tree]" \
+    - pimpjail \
+        "-M[install man pages over an existing basejail]" \
+        "-S[install the /usr/src tree over an existing basejail]" \
+        "-P[install the ports tree over an existing basejail]" \
+}
+
+_ezjail_cmd_list () {}
+
+_ezjail_cmd_restart () {
+    _ezjail_running_jails
+}
+
+_ezjail_cmd_restore () {
+    _arguments -s : \
+    "-f[restore over an existing jail]" \
+    "-d[archive directory]:archivedir:_files -/" \
+    "*::_files" \
+    "*::_ezjail_jails"
+}
+
+_ezjail_cmd_start () {
+    _ezjail_stopped_jails
+}
+
+_ezjail_cmd_stop () {
+    _ezjail_running_jails
+}
+
+_ezjail_cmd_update () {
+    _arguments -s : \
+    "-p[also update the ports tree]" \
+    "-s[source tree]:source tree:_files -/" \
+    "-P[update only the ports tree]" \
+    "-b[perform a make buildworld]" \
+    "-i[perform only a make installworld]" \
+    "-u[use freebsd-update to update]" \
+    "-U[use freebsd-update to upgrade]"
+}
+
+_ezjail_flavours () {
+    local flavourdir
+    local etcjailconf="/usr/local/etc/ezjail.conf"
+    flavourdir=$( . $etcjailconf ; ezjail_flavours_dir=${ezjail_flavours_dir:-${ezjail_jaildir}/flavours}; echo $ezjail_flavours_dir )
+    _files -W $flavourdir
+}
+
+_ezjail_list_jails () {
+    local jailcfgs="/usr/local/etc/ezjail"
+    local state=$1
+    local ret=1
+    local j
+    # Those names have already been passed through "tr -c '[alnum]' _" by ezjail
+    for j in $jailcfgs/*(:t) ; do
+    case $state in
+    running) [[ -f /var/run/jail_${j}.id ]] && compadd $j && ret=0 ;;
+    stopped) [[ -f /var/run/jail_${j}.id ]] || compadd $j && ret=0 ;;
+    *)       compadd $j && ret=0 ;;
+    esac
+    done
+    return $ret
+}
+
+_ezjail_jails () {
+    _ezjail_list_jails all
+}
+
+_ezjail_running_jails () {
+    _ezjail_list_jails running
+}
+
+_ezjail_stopped_jails () {
+    _ezjail_list_jails stopped
+}
+
+# Some commands (console...) should be run with running jails,
+# unless -f is given, in which case we can operate on all jails
+_ezjail_mostly_running_jails () {
+    local wanted_jails=_ezjail_running_jails
+    (( ${words[(I)-*f]} )) && wanted_jails=_ezjail_jails
+    $wanted_jails
+}
+
+_ezjail_mostly_stopped_jails () {
+    local wanted_jails=_ezjail_stopped_jails
+    (( ${words[(I)-*f]} )) && wanted_jails=_ezjail_jails
+    $wanted_jails
+}
+
+_ezjail "$@"
+
+# -*- mode: shell-script -*-