Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
ezjail-admin(1)		    General Commands Manual	       ezjail-admin(1)

       ezjail-admin - Administrate ezjail

       ezjail-admin install [-mMpPsS] [-h host]	[-r release]

       ezjail-admin  create  [-f flavours] [-r jailroot] [-s imagesize]	[-ibx]
       [-c bde|eli|zfs]	[-C attachargs]	[-a archive] hostname jailip

       ezjail-admin console [-f] [-e command] jailname

       ezjail-admin list

       ezjail-admin config [-r run|norun] [-n newname] [-c cpu-list] [-z  zfs-
       dataset]	[-f fib-number]	[-i attach|detach|fsck]	jailname

       ezjail-admin delete [-w]	 hostname

       ezjail-admin archive [-Af] [-a archive] [-d archivedir] [jailname...]

       ezjail-admin restore [-f] [-d archivedir] (archive|jailname)...

       ezjail-admin update [-s sourcetree] [-i]	[-pP]

       The  ezjail-admin  tool	is  used  to manage the	ezjail environment and
       jails inside the	ezjail scope.

       It can also be used to start or stop and	to get a console  in  ezjail's
       jails  by  proxying everything looking like ezjail-admin	start, stop or
       restart to the ezjail rc.d script.

ezjail-admin install
       fetches everything needed to setup an ezjail environment	 from  an  FTP
       server and installs it.

       The  default  location for ezjail's base	jail is	/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).
       Options -M, -P or -S behave like	their lower case  pendants,  but  they
       disable (re)installing your basejail.

       The  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 on the command line.

       The default host	to fetch packages from	is;  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 modify	the scripts	before
       executing them.

       You  can	 later update your world from CVS or update ports with ezjail-
       admin update or rerun this subcommand with another OS version.

ezjail-admin create
       installs	a new jail inside ezjail's scope. It either  copies  the  tem-
       plate  jail  or	an  ezjail archive to the root of that new jail, whose
       name and	IP address are provided	as mandatory parameters.

       A new entry in ezjail's config directory	is  created,  a	 corresponding
       new /etc/fstab.hostname allows the jail to be brought up	by next	reboot
       (or) via	the /usr/local/etc/rc.d/ script.

       If no jail root is specified via	the -r option, it is derived from  the
       jail's  name.  In  this	case  or, if a jail root is given and does not
       start with a '/', it is interpreted relative to ezjail's	root dir  (de-
       fault:  /usr/jails).  If	 a specified jail root lies outside the	ezjail
       root dir, a soft	link is	created	inside this root dir pointing  to  the
       newly created jail's location.

       The  -i	option	requires a size	passed via the -s option and creates a
       file-backed jail	image using md(4).  The	image file is named after  the
       jail root suffixed with .img.

       The  -c	options	 allows	to generate a file-backed jail image encrypted
       via gbde	or geli, it requires a size passed via the -s option.  The im-
       age file	is named after the jail	root suffixed with .img.

       Starting	with ZFS version 13 in FreeBSD,	the -c option allows to	create
       a ZFS-backed jail with an optional ZFS filesystem-quota passed via  the
       -s option. The filesystem is named after	the jailname.

       To  install  an ezjail archive instead of a vanilla copy	of newjail use
       -a with the backup's location. Note that	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 basejail. Also  con-
       sider  using ezjail-admin restore, if you only want to revert to	an old
       jail's state from a backup on the same host.

       The -x option indicates that an ezjail already exists at	the jail root.
       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's
       properties and called ezjail-admin delete without the -w	option before.
       However,	sanity checks are performed.

       Using the -f flavour option you can specify one or multiple space sepa-
       rated  ezjail FLAVOURs to be installed in your ezjail (e.g.  preinstall
       packages, add users, configure rc). flavours points to one or more  di-
       rectory	trees  under ezjail's root dir (default: /usr/jails/flavours).
       If no flavours are passed, the global ezjail_default_flavour  (default:
       "") is used. See	FLAVOURS below for more	details.

       Options for newly created jails are read	from ezjail.conf; refer	to ez-
       jail.conf(5) for	more information.

ezjail-admin console
       Attaches	your console to	a jail by executing a jexec with its jid.

       The command executed in that jail defaults to  /usr/bin/login  -f  root
       but  can	 be  set  with	the  -e	 modifier or by	setting	the ezjail_de-
       fault_execute config variable. A	non-running jail is not	started	by de-
       fault. If you want that,	force it with -f.

ezjail-admin list
       lists  all  jails  inside  ezjail's scope. They are sorted by the order
       they start up, as defined by rcorder. The list format  is  straightfor-

       A  status flag consisting of 2 or 3 letters, the	first meaning (D)irec-
       tory based, (I)mage based, (B)de	crypto image based, (E)li crypto image
       based,  and  the	 second	one meaning (R)unning, (A)ttached but not run-
       ning, (S)topped.	An optional (N)orun stands for disabled	jails (see ez-
       jail-admin config).

       The  rest  of the row is	the jail's jid (if available), its IP address,
       hostname	and root directory.

ezjail-admin config
       manages specific	ezjails.

       You can prevent an ezjail from being run	at system start	 with  the  -r
       norun option and	reenable it with -r run.

       You  can	rename an ezjail by using the -n newname option. If the	speci-
       fied ezjail is an image jail and	the image has its  default  name,  the
       image is	renamed	as well.

       You  can	 configure a cpuset(1) for the jail to use with	the -c option.
       The setting will	be configured and, if the jail is  running,  appliedto
       the  running  jail.  The	specification may include numbers separated by
       '-' for ranges and commas separating individual numbers.

       With the	-z option, one or more zfs-datasets can	be  configured	to  be
       attached	 to  the  jail.	  You  need  to	 configure  the	 sysctl	 secu-
       rity.jail.mount_allowed=1 and security.jail.enforce_statfs=0,  set  the
       jailed  zfs property to on  as well as "add path	zfs unhide" in the de-
       vfs ruleset for the jail.

       You can configure an altered network view (FIB) for the jail  with  the
       -f  option.  For	 setting  up FIBs, see setfib(1). The jail needs to be
       restarted after the option has been applied to take effect.

       You can attach image jails for administrative purposes with the -i  at-
       tach  option, and detach	them with -i detach. It	is not possible	to run
       or delete an attached jail. You can force fscking a jail	image with the
       -i fsck command.

ezjail-admin delete
       removes	 a   jail   from   ezjail's   config   and  the	 corresponding
       /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 ezjail's root dir.

ezjail-admin archive
       creates a backup	of one,	multiple or all	ezjails.

       Unless an archive name is given via -a switch, its file name is derived
       from jailname, date and time. It	is saved to a directory	provided by -d
       switch or the ezjail_archivedir variable	in ezjail.conf,	 and  defaults
       to . .

       Use  -A	with no	further	parameters to archive all jails	or specify one
       or more ezjails as parameters.

       Use ezjail-admin	restore	or ezjail-admin	create -a archive  to  restore
       an archive.

ezjail-admin restore
       creates new ezjails from	archived versions. It tries to collect all in-
       formation necessary to do that without user interaction	from  the  ar-
       chives, thus allowing it	to be run from a script.

       Pass  one  or more archives or jail names. For jail names, ezjail-admin
       will try	to find	the newest backup in its archive directory,  as	 given
       in ezjail.conf(5), which	defaults to . and can be overridden via	-d.

       By  default ezjail-admin	restore	refuses	to restore on a	host different
       from where it was archived. Use -f to force that.

ezjail-admin update
       creates or updates ezjail's environment (aka basejail) from source.  To
       install it from ftp servers, use	ezjail-admin install.

       Depending  on the parameters given, it will install the basejail	from a
       source tree whose location is either provided in	the ezjail.conf	config
       file or via the -s option.

       If  the -p or -P	option is given, the base jail also is given a copy of
       FreeBSDs	ports tree, which is in	turn linked into all newly created ez-
       jails. The portsnap utility is invoked to do the	actual work.

       If the -P option	is given, only the ports tree will be updated, so this
       can be done while jails are running.

       If the -i (install only)	option is given, ezjail-admin update  performs
       a make installworld, otherwise make world is invoked.

       ezjail-admin update uses	a temporary directory to install its world to,
       thus leaving intact all installed libraries, if a base jail already ex-

       When  using  the	ezjail-admin update option, be careful to use the same
       FreeBSD source tree used	to build the host system's world, or at	 least
       its kernel. Combining a make world in the host system with ezjail-admin
       update is considered a good idea.

       When a ports tree exists	in basejail, a make.conf containing reasonable
       values for having ports in jails	is created in the template jail.

       ezjail-admin  provides an easy way to create many jails with similar or
       identical properties.

       A sample	flavour	config directory resides under	/usr/local/share/exam-
       ples/ezjail/example/.  Some  typical  jail  initialization  actions are
       demonstrated, and you are encouraged to use it as a template  for  your

       If  flavours  are selected on jail creation, their root directories are
       copied to the new jail's	 root,	each  containing  an  /ezjail.flavour.
       When  the  jail starts up for the first time, these scripts are run and

       In its default form it will create some groups and  users,  change  the
       ownership of some files and install all packages	residing under /pkg.

       It allows you to	add some post-install actions.

       ezjail-admin update -p
       ezjail-admin create -f httpd -r /jails/web12
       /usr/local/etc/rc.d/ start
       /usr/local/etc/rc.d/ stop
       ezjail-admin delete
       ezjail-admin create -x -r /jails/ns

       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
       tr -C [:alnum:] _

       Sure to be others.


       ezjail(5),  ezjail.conf(5),  jail(8),  devfs(5),	fdescfs(5), procfs(5),
       pw(8), cpuset(1), setfib(1)

       Dirk Engling <>


NAME | SYNOPSIS | DESCRIPTION | ezjail-admin install | ezjail-admin create | ezjail-admin console | ezjail-admin list | ezjail-admin config | ezjail-admin delete | ezjail-admin archive | ezjail-admin restore | ezjail-admin update | NOTES | FLAVOURS | EXAMPLES | BUGS | FILES | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:

home | help