Preparing for release of ezjail-2.0beta

6 files changed, 75 insertions, 47 deletions

diff --git a/ezjail-admin b/ezjail-admin
index 01369bb..f43c9f6 100755
--- a/ezjail-admin
+++ b/ezjail-admin
@@ -3,6 +3,7 @@
 
 # ugly: this variable is set during port install time
 ezjail_prefix=EZJAIL_PREFIX
+ezjail_admin=`basename -- $0`
 ezjail_etc=${ezjail_prefix}/etc
 ezjail_share=${ezjail_prefix}/share/ezjail
 ezjail_examples=${ezjail_prefix}/share/examples/ezjail
@@ -32,13 +33,13 @@ ezjail_dirlist="bin boot lib libexec rescue sbin usr/bin usr/games usr/include u
 case `uname -p` in amd64) ezjail_dirlist="${ezjail_dirlist} usr/lib32";; esac
 
 # Synopsis messages
-ezjail_usage_ezjailadmin="Usage: `basename -- $0` [config|create|delete|install|list|update] {params}"
-ezjail_usage_create="Usage: `basename -- $0` create [-xbi] [-f flavour] [-r jailroot] [-s size] [-c bde|eli] [-C args] jailname jailip"
-ezjail_usage_delete="Usage: `basename -- $0` delete [-w] jailname"
-ezjail_usage_list="Usage: `basename -- $0` list"
-ezjail_usage_update="Usage: `basename -- $0` update [-s sourcetree] [-i] [-pP]"
-ezjail_usage_install="Usage: `basename -- $0` install [-mps] [-h host] [-r release]"
-ezjail_usage_config="Usage: `basename -- $0` config [-r run|norun] [-i attach|detach] jailname"
+ezjail_usage_ezjailadmin="Usage: ${ezjail_admin} [config|create|delete|install|list|update] {params}"
+ezjail_usage_install="Usage: ${ezjail_admin} install [-mps] [-h host] [-r release]"
+ezjail_usage_create="Usage: ${ezjail_admin} create [-xbi] [-f flavour] [-r jailroot] [-s size] [-c bde|eli] [-C args] jailname jailip"
+ezjail_usage_delete="Usage: ${ezjail_admin} delete [-w] jailname"
+ezjail_usage_update="Usage: ${ezjail_admin} update [-s sourcetree] [-i] [-pP]"
+ezjail_usage_config="Usage: ${ezjail_admin} config [-r run|norun] [-i attach|detach] jailname"
+ezjail_usage_list="Usage: ${ezjail_admin} list"
 
 ################################
 # End of variable initialization
@@ -216,9 +217,9 @@ create)
     ezjail_imagerestbytes=`echo ${_val} % 1048576 | bc`
   fi
 
-  # check, whether ezjail-update has been called. existence of
+  # check, whether ezjail has been set up correctly. existence of
   # ezjail_jailbase is our indicator
-  [ -d ${ezjail_jailbase} ] || exerr "Error: base jail does not exist. Please run 'ezjail-admin update' first."
+  [ -d ${ezjail_jailbase} ] || exerr "Error: base jail does not exist. Please run '${ezjail_admin} install' or '${ezjail_admin} update' first."
 
   # relative paths don't make sense in rc.scripts
   [ "${ezjail_jaildir%%[!/]*}" ] || exerr "Error: Need an absolute path in ezjail_jaildir, it currently is set to: ${ezjail_jaildir}."
@@ -263,17 +264,17 @@ create)
   # All sanity checks that may lead to errors are hopefully passed here
   #
 
-  if [ "${ezjail_imagetype}" ]; then
+  if [ -n "${ezjail_imagetype}" ]; then
     # Strip trailing slashes from jail root, those would confuse image path
     ezjail_image=${ezjail_rootdir%/}; while [ "${ezjail_image}" -a -z "${ezjail_image%%*/}" ]; do ezjail_image=${ezjail_image%/}; done
     [ -z "${ezjail_image}" ] && exerr "Error: Could not determine image file name, something is wrong with the jail root: ${ezjail_rootdir}."
 
     # Location of our image file
-    ezjail_image=${ezjail_image}.img
+    ezjail_image="${ezjail_image}.img"
 
     # Prepare crypto jail so that an attacker cannot guess which blocks
     # have been written
-    case ${ezjail_imagetype} in crypto|bde|eli) ezjail_sourcedevice=/dev/random;; simple) ezjail_sourcedevice=/dev/zero;; esac
+    case ${ezjail_imagetype} in bde|eli) ezjail_sourcedevice=/dev/random;; simple) ezjail_sourcedevice=/dev/zero;; esac
 
     # If NOT exist, create image
     if [ -z "${ezjail_exists}" ]; then
@@ -288,7 +289,7 @@ create)
         ( dd if=${ezjail_sourcedevice} bs=${ezjail_imagerestbytes} count=1 >> "${ezjail_image}" ) || exerr "Error: Could not (or not fully) create the image file. You might want to check (and possibly remove) the file ${ezjail_image}. The image size provided was ${ezjail_imagesize}."
       fi
 
-      # And attach device
+      # Attach device
       ezjail_imagedevice=`mdconfig -a -t vnode -f ${ezjail_image}`
       [ $? = 0 ] || detach_images || exerr "Error: Could not attach image device. (Command failed was 'mdconfig -a -t vnode -f ${ezjail_image}')"
       case "${ezjail_imagetype}" in
@@ -296,7 +297,7 @@ create)
           # parse imageparams, generate attachparams
           ezjail_attachblocking="YES"
           if [ -n "${ezjail_imageparams}" ]; then
-            ezjail_attachparams=`echo $0 _parse_g${ezjail_imagetype}_attach_args_ ${ezjail_imageparams} | /bin/sh `
+            ezjail_attachparams=`echo $0 _parse_g${ezjail_imagetype}_attach_args_ ${ezjail_imageparams} | /bin/sh`
             [ 5 -eq $? ] && exerr "processing of ezjail_imageparams failed"
             [ 3 -eq $? ] && unset ezjail_attachblocking
           fi
@@ -347,24 +348,24 @@ create)
 
   # now, where everything seems to have gone right, create control file in
   # ezjails config dir
-  mkdir -p ${ezjail_jailcfgs}
-  echo "# To specify the start up order of your ezjails, use these lines to" > ${ezjail_config}
-  echo "# create a Jail dependency tree. See rcorder(8) for more details." >> ${ezjail_config}
-  echo -e "#\n# PROVIDE: standard_ezjail\n# REQUIRE: \n# BEFORE: \n#\n" >> ${ezjail_config}
-  echo export jail_${ezjail_safename}_hostname=\"${ezjail_hostname}\" >> ${ezjail_config}
-  echo export jail_${ezjail_safename}_ip=\"${ezjail_ip}\" >> ${ezjail_config}
-  echo export jail_${ezjail_safename}_rootdir=\"${ezjail_rootdir}\" >> ${ezjail_config}
-  echo export jail_${ezjail_safename}_exec=\"/bin/sh /etc/rc\" >> ${ezjail_config}
-  echo export jail_${ezjail_safename}_mount_enable=\"${ezjail_mount_enable}\" >> ${ezjail_config}
-  echo export jail_${ezjail_safename}_devfs_enable=\"${ezjail_devfs_enable}\" >> ${ezjail_config}
-  echo export jail_${ezjail_safename}_devfs_ruleset=\"devfsrules_jail\" >> ${ezjail_config}
-  echo export jail_${ezjail_safename}_procfs_enable=\"${ezjail_procfs_enable}\" >> ${ezjail_config}
-  echo export jail_${ezjail_safename}_fdescfs_enable=\"${ezjail_fdescfs_enable}\" >> ${ezjail_config}
-  echo export jail_${ezjail_safename}_image=\"${ezjail_image}\" >> ${ezjail_config}
-  echo export jail_${ezjail_safename}_imagetype=\"${ezjail_imagetype}\" >> ${ezjail_config}
-  echo export jail_${ezjail_safename}_attachparams=\"${ezjail_attachparams}\" >> ${ezjail_config}
-  echo export jail_${ezjail_safename}_attachblocking=\"${ezjail_attachblocking}\" >> ${ezjail_config}
-  echo export jail_${ezjail_safename}_forceblocking=\"${ezjail_forceblocking}\" >> ${ezjail_config}
+  mkdir -p ${ezjail_jailcfgs} || exerr "Error: can't create ezjails control directory (${ezjail_jailcfgs})."
+  ( echo -e "# To specify the start up order of your ezjails, use these lines to\n# create a Jail dependency tree. See rcorder(8) for more details."
+  echo -e "#\n# PROVIDE: standard_ezjail\n# REQUIRE: \n# BEFORE: \n#\n"
+  echo jail_${ezjail_safename}_hostname=\"${ezjail_hostname}\"
+  echo jail_${ezjail_safename}_ip=\"${ezjail_ip}\"
+  echo jail_${ezjail_safename}_rootdir=\"${ezjail_rootdir}\"
+  echo jail_${ezjail_safename}_exec=\"/bin/sh /etc/rc\"
+  echo jail_${ezjail_safename}_mount_enable=\"${ezjail_mount_enable}\"
+  echo jail_${ezjail_safename}_devfs_enable=\"${ezjail_devfs_enable}\"
+  echo jail_${ezjail_safename}_devfs_ruleset=\"devfsrules_jail\"
+  echo jail_${ezjail_safename}_procfs_enable=\"${ezjail_procfs_enable}\"
+  echo jail_${ezjail_safename}_fdescfs_enable=\"${ezjail_fdescfs_enable}\"
+  echo jail_${ezjail_safename}_image=\"${ezjail_image}\"
+  echo jail_${ezjail_safename}_imagetype=\"${ezjail_imagetype}\"
+  echo jail_${ezjail_safename}_attachparams=\"${ezjail_attachparams}\"
+  echo jail_${ezjail_safename}_attachblocking=\"${ezjail_attachblocking}\"
+  echo jail_${ezjail_safename}_forceblocking=\"${ezjail_forceblocking}\"
+  ) > ${ezjail_config}
 
   # Final steps for flavour installation
   if [ -z "${ezjail_exists}" -a -n "${ezjail_flavour}" ]; then
@@ -400,6 +401,7 @@ create)
   [ $? = 0 ] && echo -e "Warning: Some services already seem to be listening on all IP, (including ${ezjail_ip})\n  This may cause some confusion, here they are:\n${ezjail_listener}"
   IFS=${TIFS}
 
+  [ -n "${ezjail_imagetype}" ] && echo "Note: To administrate your image jail, attach it using the '${ezjail_admin} config -i attach ${ezjail_hostname}' command."
   ;;
 ######################## ezjail-admin DELETE ########################
 delete)
@@ -424,9 +426,9 @@ delete)
   [ -n "${ezjail_id}" ] && exerr "Error: Jail appears to be still running, stop it first."
 
   # if jail is attached, refuse to go any further
-  [ -n "${ezjail_attached}" ] && exerr "Error: Jail image file ${ezjail_image} is attached as ${ezjail_device}. '`basename -- $0` config -i detach' it first."
+  [ -n "${ezjail_attached}" ] && exerr "Error: Jail image file ${ezjail_image} is attached as ${ezjail_device}. '${ezjail_admin} config -i detach' it first."
 
-  # now we know everything we need to let the jail be gone remove entry
+  # now we know everything we need to let the jail be gone. remove entry
   # from ezjail resource structure, delete fstab.JAILNAME
   rm -f ${ezjail_config} /etc/fstab.${ezjail_safename}
 
@@ -479,9 +481,9 @@ setup|update)
   [ $# -eq 0 ] || exerr ${ezjail_usage_update}
 
   if [ "${ezjail_installaction}" = "none" ]; then
-    # check, whether ezjail-update has been called. existence of
+    # check, whether ezjail has been setup correctly. existence of
     # ezjail_jailbase is our indicator
-    [ -d ${ezjail_jailbase} ] || exerr "Error: base jail does not exist. You cannot fill base jails ports tree before creating it. Please run 'ezjail-admin update' first."
+    [ -d ${ezjail_jailbase} ] || exerr "Error: base jail does not exist. You cannot fill base jails ports tree before creating it. Please run '${ezjail_admin} update' or '${ezjail_admin} install' first."
   else
     # Bump the user for some of the most common errors
     [ -d ${ezjail_sourcetree} ] || exerr "Cannot find your copy of the FreeBSD source tree in ${ezjail_sourcetree}."
diff --git a/ezjail.conf.sample b/ezjail.conf.sample
index b14dc17..3dfd336 100755
--- a/ezjail.conf.sample
+++ b/ezjail.conf.sample
@@ -23,6 +23,9 @@
 # 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
+
 # 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"
diff --git a/ezjail.sh b/ezjail.sh
index 23ebfa2..8a2822b 100755
--- a/ezjail.sh
+++ b/ezjail.sh
@@ -119,7 +119,7 @@ attach_detach_pre ()
       ;;
     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
         echo "Error: Attaching eli device failed."; return 1
diff --git a/man1/ezjail-admin.1 b/man1/ezjail-admin.1
index 5994a76..451ab95 100755
--- a/man1/ezjail-admin.1
+++ b/man1/ezjail-admin.1
@@ -16,7 +16,13 @@ ezjail-admin \- Administrate ezjail
 .B ezjail-admin list
 
 .T
-.B ezjail-admin install [-mps] [-h host] [-r release]
+.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
@@ -105,6 +111,15 @@ stands for disabled jails (see
 
 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.
@@ -121,14 +136,16 @@ 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 releas from command line.
+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. 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.
+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 by
+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
diff --git a/man5/ezjail.5 b/man5/ezjail.5
index aaef3f0..49fd0c6 100755
--- a/man5/ezjail.5
+++ b/man5/ezjail.5
@@ -27,13 +27,14 @@ and
 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, are being started/stopped. To start all crytpo image jails, use
-the
+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, sets variables for each jail in the
-jail_list before passing its command on to the
+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
diff --git a/man5/ezjail.conf.5 b/man5/ezjail.conf.5
index 2314ec6..6afede0 100755
--- a/man5/ezjail.conf.5
+++ b/man5/ezjail.conf.5
@@ -37,6 +37,11 @@ Cvs root to use when checking out or updating the ports tree in base jail
 .br
 .I default: :pserver:anoncvs@anoncvs.at.FreeBSD.org:/home/ncvs
 .TP
+.B ezjail_ftphost (str)
+This is where the install sub command defaults to fetch its packages from
+.br
+.I default: ftp.freebsd.org
+.TP
 .B ezjail_uglyperlhack (bool)
 Set to YES, if ezjail should provide a soft link from /usr/bin/perl to /usr/local/bin/perl in base jail.
 .br