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

FreeBSD Manual Pages

  
 
  

home | help
qjail(8)		     System Manager's Manual			qjail(8)

NAME
     qjail -- Utility for deployment of jail environments

SYNOPSIS
     qjail install [-z zone] [-h ftp host] [-f file location] [-l]
     qjail create  [-z zone] [-n interface] [-a archive] [-f flavor]
		   [-A archive zone] [-c] [-i size] [-d duplicate#]
		   [-4 IPv4...] [-6 IPv6...] jailname
     qjail list    [-z zone] [jailname...]
     qjail start   [-z zone] [jailname...]
     qjail stop    [-z zone] [jailname...]
     qjail restart [-z zone] [jailname...]
     qjail console [-z zone] [-u userid] [-c cmd] jailname
     qjail archive [-z zone] [-A] [-s] [jailname...]
     qjail delete  [-z zone] [-A] [jailname...]
     qjail restore [-z zone] [-s] [jailname...]
     qjail config  [-z zone] [-c newnic] [-n newname] [-b rule#] [-A -d -h]
		   [-B -F -k -K -l -L -m -M -q -Q -r -R -S -t -T]
		   [-V -W -x -X -y -Y]
		   [-f value] [-s value] [-v value] [-w value]
		   [-4 newIPv4...] [-6 newIPv6...] jailname
     qjail update  [-z zone] [-b] [-p] [-P] [-S] [-l on|off]
     qjail logmsg  [text....]
     qjail help    [subcommand]

DESCRIPTION
     The  qjail  utility  uses	the  jail(8) jail.conf method which provides the
     ability  to  enable  the	following   options   on   a   per-jail   basis,
     allow.raw_sockets,      devfs_ruleset,	allow.sysvipc,	   allow.quotas,
     allow.mount.nullfs, allow.mount.zfs, securelevel, exec.fib, vnet.interface,
     and vnet. The vnet option gives a jail its  own  network  stack  using  the
     experimental  vimage  software.  This  qjail version is only functional for
     10.0-RELEASE and newer. The vnet option has only been tested  on  i386  and
     amd64 equipment.

     The qjail utility is used to manage the qjail environment and all the jails
     inside  of qjail's scope. Qjail's administration ease does not evaporate as
     jails deployed grow beyond 5 jails. For the deployment of a large number of
     jails, qjail provides two facilities  designed  to  make  their  management
     easy.  The  First	facility is the group prefix selection ability, which is
     advantageous in managing both small and large jail deployments.  The  group
     prefix  equal  sign  "="  wildcard  when  used  on  the jailname allows for
     management of jails based on common jailname  group  prefixes.  The  second
     facility  is  qjail's  ability to create multiple unique jail environments,
     thus providing another method to group common  jails  together  for  easier
     management.  A  large  deployment	of hundreds of jails is possible if your
     host system resources are adequate and a jail naming convention is used  to
     segregate jails into manageable groups.

     This utility deploys two different jail types. The first type is based on a
     Directory	tree.  This  type  has unlimited disk space growth potential, it
     shares the host's disk space. The jail will never run out	of  space  until
     the  host	does.  The second type is based on a sparse image file. A sparse
     file is one that occupies only the  sum  size  of	its  contents,	not  its
     allocation  size. IE; a sparse file allocated size of 5M, but only having 7
     files, each 1k in size, only occupies 7k of physical disk space. As content
     is added,	additional  physical  disk  space  is  occupied  up  to  the  5M
     allocation  ceiling.  The sparse file is mounted as a memory disk using the
     mdconfig command and populated with the directory tree content of	a  jail.
     This  configuration is called a sparse image jail. Its major benefits is it
     provides a way to put a hard limit on the maximum amount of  disk	space  a
     jail can consume. This provides an addition level of protection to the host
     from  intentional	or  unintentional  run-a-way  processes inside of a jail
     consuming disk space until the host system dies.

     Adding qjail_enable="YES" to the "host's" /etc/rc.conf file, will cause all
     jails to be started when the system is booted.

     Following the command "qjail" is the  function  subcommand.  Each	function
     subcommand  has  its  own	list  of  unique options. Qjail is executed from
     /usr/local/bin/ and is a command interpreter  Bourne  type  (shell)  script
     that has to be run from user root.

qjail install
     Allocates	the directory structure used by qjail and must be populated with
     the same Operating System version as the  host  is  running.  For	security
     purposes its necessary that the qjail directory structure be populated with
     a	pristine  version  of  the operating system. By pristine we mean "clean,
     uncompromised, never been exposed to the public internet", as in  installed
     from an iso image file, or from the original distribution file. By default,
     qjail  downloads the original distribution file that matches the OS version
     running on the host to populate it's directory structure  with  a	pristine
     version.

     In  most  cases  the  production  versions of the operating system is used.
     These are identified by versions labeled as "X.X-RELEASE" and have both iso
     image files and original distribution files available for download from the
     FreeBSD FTP servers.

     The pre-release versions  "X.X-BETAx  and	X.X-RCx"  iso  image  files  and
     original  distribution files are only made available by Release Engineering
     during the process of creating the next production version and are  removed
     after  the new production version is published. If your host is running one
     of these pre-release versions, qjail will use it's distribution file.  It's
     the  user's  responsibity	to  update  the  host  to  the	newly  published
     production version.

     The  Development  "X.X-STABLE,  and  X.X-CURRENT"	branchs  have	snapshot
     versions  of  the	iso image files and original distribution files that are
     recreated weekly. These Development branchs are the bleeding edge	and  may
     cause problems for qjail. If your host is running one of these and you want
     to  run  qjail.  Manually	fetch  distribution  base.txz  file from the FTP
     snapshot directory that matches what the host is running. Use option -f  to
     create  a	clean  qjail  system.  If you compiled your OS from source, most
     likly it's revision number is  out  of  sync  with  the  snapshot	revision
     number.  To  update  the  qjail  system  to  same revision number as what's
     running on the host. Issue 'qjail update -b' command to  clone  the  host's
     running libs to the sharedfs directory tree.

     During  the  "qjail  install"  process the following directory structure is
     allocated with the default path of /usr/jails. This default may be modified
     by following comments in the qjail script around line 43.

     sharedfs contains all of the operating  system's  executable  libraries  as
     read-only	files  and  is mounted as an "nullfs" that is shared between all
     the individual jails.  It's  populated  with  a  pristine	version  of  the
     operating	systems  binaries.  This  design  effectively  secures	all  the
     executable files from  being  updated  or	deleted  and  also  secures  the
     directories  containing the executable files from having new files inserted
     by any process running inside of the jail. The "/usr/src" and  "/usr/ports"
     directories  are  also  included.	The  hosts  "/usr/ports"  filesystem can
     temporarily be made available to the jails by using the "mv"  command  like
     this:							mv    /usr/ports
     /usr/jails/sharedfs/usr	and    returned     doing		      mv
     /usr/jails/sharedfs/usr/ports /usr

     Or use "update" subcommand to populate src and/or ports permanently.

     template contains the operating system configuration files. It is copied to
     form the base filesystem of each jail.

     archive  is  where  the  archive  files  are stored that are created by the
     "qjail archive" command.

     flavors contains the "default" and "ssh-default"  system  flavors	and  any
     user created custom flavors.

     Six  internal administration directories are created and get populated with
     information	   unique	     to 	   each 	   jail.
     /usr/local/etc/qjail.config
     /usr/local/etc/qjail.fstab
     /usr/local/etc/qjail.local
     /usr/local/etc/qjail.global
     /usr/local/etc/qjail.packages
     /usr/local/etc/qjail.vnetctl

     This  command  can be run any time to rebuild the sharedfs and the template
     from scratch while not disturbing the existing jails,  or	your  customized
     flavors.	The   "default	 and   ssh-default"  flavors  are  renamed  with
     "users.saved." prefix before being replaced with fresh versions.

     If rebuilding using a newer major RELEASE, IE: 10.3 to 11.0, then remember,
     all existing jails that have ports or  packages  in  them	will  need  them
     updated to versions compatible with the new major RELEASE version. If going
     from  a subversion to a newer subversion within the same major RELEASE, IE:
     10.0  to  10.1,  then  there  is  no  need   to   update	your   installed
     ports/packages.

     The options are as follows:

     -z      Code this option to create multiple unique qjail environments.  The
	     coded  zone value is appended to /usr/jail as /usr/jail.zone and to
	     /usr/local/etc/fstab.qjail.zone and /usr/local/etc/qjail.local.zone
	     which uniquely segregates the qjail environments. All ".  -  /"  in
	     the  zone name are converted to "_" underscores to standardize zone
	     names. All the other qjail subcommands "MUST" code  the  same  zone
	     value   to  process  against  the	zone  created  here.  If  absent
	     /usr/jails        and	  /usr/local/etc/qjail.fstab	     and
	     /usr/local/etc/qjail.local/ are used.

     -h      Code  the URL of the remote host to fetch the original distribution
	     files  from.  If  this  option   is   absent   the   default   host
	     ftp2.freebsd.org  is  used. You may change the default using the -h
	     ftp7.freebsd.org option. Read this for complete list of FTP servers
	     to 			  choose			   from.
	     www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/mirrors-ftp.html

     -f      Code  the	complete path to the location where any of three RELEASE
	     sources are to target as the source to populate  qjail's  directory
	     structure	from.  That  could  be	the  mounted disc1 cdrom, or the
	     downloaded  disc1.iso  image  file,  or  the  downloaded	original
	     distribution files.

     -l      This  enables  logging  of all qjail commands and error messages to
	     /var/log/qjail.log  file.	Each  log  entry  is  prefixed	with   a
	     date/time	stamp and the user account name of the user entering the
	     commands. An entry is also  made  in  /etc/newsyslog.conf	to  auto
	     rotate the qjail.log file.

qjail install examples
     1.  qjail install (without any options)
	       The RELEASE distribution files used to populate the qjail
	       directory structure will be fetched from an FreeBSD FTP
	       server and be the same RELEASE version as the host. Some
	       times at the publication of a new RELEASE version, the FTP
	       server may become so busy that the download gets timed out
	       or connection is refused because of too many current users.
	       RE-issuing the command will start the FTP download from
	       the beginning again.

     2.  qjail install -h ftp6.freebsd.org -l
	       Same behavior as above, except the FreeBSD ftp server specified
	       in the -h option is used, and the qjail system wide logging
	       is enabled.

     3.  mount_cd9660 /dev/cd0 /mnt
	 qjail install -z env1 -f /mnt/usr/freebsd-dist
	       Use this option to target a mounted disc1 RELEASE cdrom
	       as the source of the original distribution files used to
	       populate the qjail directory structure. Plus a uniquely named
	       qjail zone is created named "env1".

	       After the install completes, execute the following commands
	       to release the disc1 RELEASE cdrom.
		    cd /usr
		    umount  /mnt

qjail create
     Creates  a  new  jail  inside  qjail's  scope.  It has great flexibility in
     creating Directory Tree type jails and sparse file image  type  jails  from
     the  template or from a previously made archive file. This coupled with the
     ability to auto duplicate jails makes a easy and simple task  to  deploy  a
     large  number  of	jails  quickly.  Jailname  and	IP address are mandatory
     parameters.

     During the creation process four administration files are created for  each
     jail.	They	  are	   /usr/local/etc/qjail.fstab/jailname	   file,
     /usr/local/etc/qjail.local/jailname				   file,
     /usr/local/etc/qjail.global/jailname	   file,	 and	     the
     /usr/local/etc/qjail.config/jailname file.

     The options are as follows:

     -z      Code the same zone value used with the "install" subcommand to have
	     this subcommand process against that zone.

     -n      This is  the  "network  interface	name"  servicing  the  jails  IP
	     addresses.  When qjail starts a non-vnet jail it will automatically
	     create an alias for the jails IP address on that "network interface
	     name". When qjail stops the jail, it will automatically remove  the
	     alias.  If  "-n  value"  is  absent, the "route command" is used to
	     identify the default network interface device  name  which  is  the
	     device  connected to the public internet and automatically populate
	     the "-n value".

	     For multiple static  public  routable  IP	addresses,  the  correct
	     "network  interface name" to code is the name of the NIC facing the
	     public internet where these IP  addresses	enter  your  host.   For
	     jails  on	the  hosts  private  LAN, the correct "network interface
	     name" to code is the name of the NIC facing the hosts  private  LAN
	     where  those  IP  addresses  exit	and  enter your host.  For jails
	     assigned IP addresses reserved for private LAN use to  be	able  to
	     access  the  public  internet,  you must configure your firewall to
	     perform NAT on them. See -4 option for more details.

	     Very important CAUTIONARY note: Be aware  of  the	LAN  IP  address
	     range  your  DHCP	server	is  dynamically assigning. Do not assign
	     those IP addresses to jails or your LAN users will  instantly  lose
	     their  network  access  when the jail is started and its alias gets
	     created.

     -a      You can use an archive file as the template to create your new jail
	     from. If just the archived jailname is coded, then the most current
	     archive file matching that jailname will be used as the source. The
	     full archive file name can also be coded.	Its  prefixed  with  the
	     jailname  and  has the date & time the archive was created appended
	     as a suffix. Coding the full archive file name is how you select an
	     archive file other than  the  most  current  one.	This  option  is
	     normally  used  to clone multiple jails with the same status as the
	     archived jail has. If the -a flag is absent, the template is  used.
	     Note:  The  -a  and  -f  options cannot be used together. By design
	     jails created from a archive  file  cannot  be  flavored.	Use  "ls
	     /usr/jails/archive/" to list all archive file names.

	     An  archive  of  a image jail can be used to create a new directory
	     tree jail or a new image jail with a larger sized sparse file image
	     jail. An archive of a directory tree jail can be used to  create  a
	     new  directory  tree jail or a new image jail. The -n interface nic
	     name from the archive file is dropped.

     -A      Using the -A archive zone option you can  select  an  archive  file
	     from a different zone as the template to create your new jail from.
	     The  -A option is only valid when used together with the -a option.
	     Using a combination of  the  -z,  -a  and	-A  options  allows  the
	     selection of archive files from other zones.

	     The  default  jail  environment IE; no -z option coded on the qjail
	     install command is a special case. Manipulation of  the  values  in
	     -z,  -a, and -A covers everything but selecting a jail archive from
	     the default jail environment. A special reserved value named nozone
	     may be coded  in  the  -A	value  to  point  to  the  default  jail
	     environment  archives. Normally the -z value is the zone the create
	     command applies to, the -A value is the  zone  where  the	selected
	     archive  file  is located, and the -a value is the archive jailname
	     or full archive file name in the zone pointed by the -A value.

     -f      Using the flavor option you can apply an qjail flavor to  your  new
	     jailname.	If  the  -f  flavor option is coded, the selected flavor
	     directory tree is merged into the new jail's directory tree. If  no
	     flavor option is coded, the "default" flavor is merged into the new
	     jail's  directory	tree.  Qjail  has no function to delete unwanted
	     flavor  directories.  It's  the  users  responsibility  to   delete
	     unwanted  flavor's  using the host's rm -rf /user/jails/flavor/name
	     command. Note: The -f and -a options cannot be  used  together.  By
	     design jails created from a archive file cannot be flavored.

	     As  part  of  the "install" subcommand, a flavor base directory was
	     created as /usr/jails/flavors and populated with two  flavors,  one
	     named  default  and  the  other  named  ssh-default.  Both of these
	     flavors  contains	3  files  customized  for  running  in	a   jail
	     (make.conf,  periodic.conf,  rc.conf). In addition these customized
	     host  files  /etc/resolv.conf  and  /etc/localtime  are  copied  to
	     default and ssh-default to facilitate jail usage. On inspection you
	     will  see	that  these  files  are  in  their normal directory tree
	     locations. When customizing your own flavors you have  to	manually
	     create  your  own	flavor	directory  tree  populating it with your
	     customized files in their correct paths for merging  into	the  new
	     jail.

	     The  ssh-default flavor contains everything the default flavor has,
	     but in addition it has been customized to enable ssh  support,  and
	     has  a predefined standard user account named qjail with a password
	     of "qjail". Every jail you use this ssh-default flavor on will have
	     this predefined standard user account qjail.  On  first  login  the
	     user  will  be  prompted  to  enter a new password to address basic
	     security concerns. The qjail user belongs to the "wheel"  group  so
	     it has "su" access to "root".

	     When  creating  your own flavor always copy the "default" flavor or
	     the "ssh-default" flavor as your starting base.

     -c      This option will enable ssh and create a user  account  having  the
	     login  ID	and  password of the jailname. To address basic security
	     concerns, on first login the user will be prompted to enter  a  new
	     password. The jailname user account belongs to the "wheel" group so
	     it has "su" access to "root".

	     When the jails created with the -c option are started for the first
	     time,  the changes to configure ssh and create the user account for
	     that jail are applied. Doing a qjail restart jailname  or	a  qjail
	     stop  jailname  followed  by  qjail  start  jailname is required to
	     enable the changes which will be in effect from that point on.

     -i      When coded means create a sparse file image type jail. When  absent
	     an  directory  tree  type	jail  is  created. When the -i option is
	     coded, it must be followed by a size value which is the  allocation
	     ceiling size of the sparse file. Only suffixes m|M for megabytes or
	     g|G  for  gigabytes  are valid entries. The sparse image file has a
	     .img suffix and resides in the jailname directory as a single file.
	     When the image jail  is  stopped  the  jailname.img  file	will  be
	     visible.  Issuing	ls  -lh jailname.img will show you the allocated
	     size, issuing du -h jailname.img will show you the amount of  space
	     used.  If	a  image  jail	should	consume  all  of  its disk space
	     allocation, you  can  increase  it  by  following	this  procedure,
	     archive it, delete it, and create it using the -a option, using the
	     image archive as input with a larger -i value. A -i value of 10m is
	     the bare minimum size for a image jail.

     -d      Enter  a  numeric	number representing the number of times you want
	     this jailname duplicated. A  suffix  number  starting  at	one  and
	     incremented  by  one for each duplication is appended to each newly
	     created jailname. Any number greater than 100 is invalid. A  single
	     IPv4  address  is	required. For each repetition of the duplication
	     cycle the last octal of the IPv4 address increments by 1.

     -4      This is the network address used  to  communicate	with  the  jail.
	     Both  non-vnet  jails  and  vnet jails use it for the same purpose.
	     This is either a public IPv4 address or  a  private  IPv4	address.
	     More  than  a  single  IPv4  address  can	be  assigned  to a jail.
	     Multiple IPv4 addresses have to be a list of IP addresses separated
	     by a comma "," without  spaces  before  or  after. 	 Example
	     10.0.0.2,10.0.0.3,10.0.0.4 			       A  second
	     format is also available "xl0|10.0.02,lo1|127.0.2.1" To the left of
	     the "|" symbol is the network device name that the  ip  address  is
	     assigned to. Note the surrounding "  " they are required.

	     According	to RFC 1918, you can use the following IP address ranges
	     for private IPv4 networks which will  never  be  connected  to  the
	     Internet. This is normally intended for Local Area Networks.
			   #
			   #	   10.0.0.0	   -   10.255.255.255
			   #	   172.16.0.0	   -   172.31.255.255
			   #	   192.168.0.0	   -   192.168.255.255
			   #

	     Static  IP  address  (permanent,  never  changes)	public	Internet
	     routable IP addresses are assigned to  you  by  your  ISP.  If  you
	     purchased	a continuous block of static public internet routable IP
	     addresses, then each jail could be assigned one of those individual
	     IP addresses from that block.

	     Normally cable  providers	and  DSL  providers  assign  dynamic  IP
	     addresses.  The  assigned IP address may change when the lease time
	     expires or you reboot your system.

     -6      This is a IPv6 address that is to be assigned  to	the  jail.  More
	     than a single IPv6 address can be assigned to a jail. Multiple IPv6
	     addresses	have  to  be a list of IP addresses separated by a comma
	     "," without spaces before or after. Both IPv4  and  IPv6  addresses
	     may  be assigned to a jail by coding both the -4 and -6 options. An
	     single IPv4 address is required if the -d option is coded to enable
	     jail duplication.

     jailname
	     Only a single jailname is valid.  The  jailname  can  only  contain
	     alphanumeric,   dash,   and   underscore  characters,  all  numeric
	     jailnames are invalid. To better manage large  jail  deployments  a
	     jail naming convention that groups jails by common function or user
	     groups  is  advised.  The	maximum  jailname size is 50 characters.
	     Jailnames have to be unique across all the  zones.   Just	remember
	     that  you	will  be typing in this jailname or some prefix of it on
	     all the subcommands you use, so try to keep the jailname short  but
	     meaningful.

	     Jails are started, stopped, and restarted in ascending alphabetical
	     order,  "a to z" based on the spelling of the jailname. If you want
	     selected jails to start before other jails prefix	those  jailnames
	     with numbers.

qjail create examples
     1.  qjail create -n rl0 -6 21:470:1f15:1ee7::102 webserver
	       This creates a single new directory tree type jail as
	       /usr/jails/webserver from the template with a IPv6 address.
	       The auto alias function is enabled.

     2.  qjail create -n rl0 -c -f myflavor -4 10.0.10.20 bld21a-floorA-cell01
	       This creates a single new directory tree type jail as
	       /usr/jails/bld21a-floorA-cell01 from the template
	       and copies the myflavor directory tree onto the
	       bld21a-floorA-cell01 directory tree.
	       The auto alias function is enabled and ssh access is enabled.

     3.  qjail create -a cell-a -4 10.0.10.20,10.0.10.30 prison-B
	       This creates a single new directory tree type jail as
	       /usr/jails/prison-B using the archive file named cell-a as
	       the template directory tree for the new jailname.
	       The auto alias default function is enabled.

     4.  qjail create -a cell-a -d 15 -4 10.0.10.20 room
	       This creates a new directory tree type jail using the archive
	       file named cell-a as the template for the new jailname, and
	       then duplicates it 15 times.
	       Creating jailnames room-1 through room-15.
	       At the same time the last octet of the IP address
	       10.0.10.20 is incremented by one.
	       room-1 10.0.10.20  room-2 10.0.10.21  room-15 10.0.10.34
	       The auto alias default function is enabled

     5.  qjail create -n rl0 -d 15 -4 10.0.10.20 room
	       This creates a new directory tree type jail using the
	       template directory tree for the new jailname, and then
	       duplicates it 15 times creating jailnames
	       room-1 through room-15. The auto alias function is enabled
	       At the same time the last octet of the IP address
	       10.0.10.20 is incremented by one.
	       room-1 10.0.10.20  room-2 10.0.10.21  room-15 10.0.10.34

     6.  qjail create -n rl0 -d 15 -c -4 10.0.10.20 room
	       This does the same as the previous one except these jails
	       also has ssh access enabled.

     7.  qjail create -i 100m -4 10.0.10.20 class
	       This creates a single new sparse image type jail using the
	       template directory tree to populate the image with a
	       maximum allocation size of 100 megabytes.
	       The auto alias default function is enabled

     8.  qjail create -d 15 -c -i 100m -4 10.0.10.20 class
	       This does the same as the previous one except this jail
	       also has ssh access enabled, and duplicates it self
	       15 times creating jailnames class-1 through class-15.
	       At the same time the last octet of the IP address
	       10.0.10.20 is incremented by one giving.
	       class-1 10.0.10.21  class-2 10.0.10.22  class-15 10.0.10.34

     9.  qjail create -c -a cell-a -i 1g -4 10.0.10.20 room
	       This creates a new single sparse image type jail with a
	       maximum allocation size of 1 gigabyte, using the archive
	       file named cell-a as the template directory tree for
	       populating the image jail.
	       The auto alias default function is enabled and ssh access
	       is enabled.

     10. qjail create -z env1 -a cell-a -i 1G -4 10.0.10.20 room
	       This does the same as the previous one except this jail is
	       being created in the "env1" zone.

     11. qjail create -z env1 -a cell-a -A env2 -4 10.0.10.20 room
	       This creates a new jail named "room" in zone "env1" using a
	       archive file named "cell-a" which is located in zone "env2".

     12. qjail create -z env1 -a cell-0 -A nozone -4 10.0.10.20 room
	       This creates a new jail named "room" in zone "env1" using a
	       archive file named "cell-0" which is located in the qjail
	       default environment. The "nozone" keyword is used.

qjail list
     Lists  information  about	jails  inside  qjail's	scope. They are shown in
     ascending alphanumerically order, based on the spelling of the jailname.

     The list displays 5 columns of information. Starting from the left,  Column
     (1)								Contains
     status flags consisting of 6 positions.				Position
     one  can be the letter (D) for Directory tree based jail, or the letter (I)
     for a image file based jail.			      Position	two  can
     be  the letter (R) meaning the jail is currently running, or the letter (S)
     meaning the jail is stopped.			  Position three through
     six can contain optional letters depending on if the option is emabled. The
     letter (N) means the jail is in norun status or the letter (M) which  means
     the  jail	is  in manual start only status.  The letter (V) means this is a
     vnet jail, and it's followed by a space and number 0 through  3  indicating
     which  firewall  is  enabled  in  the  vnet  jail.  0-none,  1=ipfw,  2=pf,
     3=ipfilter. See the qjail config subcommand
      -r       -R	-m	 -M	  -v	    -V	      for	 details
     Column  (2)
     Contains the jail's jid number if the jail is  started,  and  N/A	for  not
     available	if  the jail is stoped.
     Column (3) 							      is
     the network interface device name, this is the value entered on the "create
     -n" option, or if a vnet jail the "config -w option. If	     the "create
     -n value" was not used, the "route command" is used to identify the default
     network  interface  device name which is the device connected to the public
     internet	and   then   automatically   populates	 the	  "-n	 value".
     Column  (4)
     is the jails IPv4 and IPv6 address or addresses, entered with the	"create"
     command.							      Column (5)
     is the jails jailname.

     -z      Code the same zone value used with the "install" subcommand to have
	     this  subcommand  process	against  that  zone. When this option is
	     coded an addition heading "Jails in zone xxxx" displays right above
	     the normal heading. "xxxx" is the zone name.

     jailname
	     If absent all the jails are listed. Multiple jailnames separated by
	     a space are allowed on the command.  The  group  prefix  option  is
	     enabled.  xxxx=  will  cause only those jailnames matching the xxxx
	     characters to be selected for processing. The equal sign "=" is the
	     wildcard symbol that signifies all the characters to its  left  are
	     to be used to match on jailname to create a list of jailnames to be
	     processed.

qjail [start | stop | restart] jailname.....
     When  start,  stop, or restart command is issued WITHOUT jailnames, all the
     jails under qjail control are  processed.	When  start,  stop,  or  restart
     command  is  issued  WITH	jailnames, only those jailnames are processed. A
     single line informational message is issued as each jailname  is  processed
     saying Started successfully jailname or Already running jailname or Stopped
     successfully  jailname or Already stopped jailname or Bypassed norun status
     jailname.

     Jails are started, stopped, and restarted in ascending alphabetical  order,
     "a  to z" based on the spelling of the jailname. If you want selected jails
     to start before other jails prefix those jailnames with numbers. All  norun
     status jails are ignored.

     The function subcommands are as follows:

       start  Start all jails at once if jailname is absent.

       stop   Stop all jails at once if jailname is absent.

       restart	Restart all jails at once if jailname is absent.

     The options are as follows:

     -z      Code the same zone value used with the "install" subcommand to have
	     this subcommand process against that zone.

     jailname
	     If absent all the jails are used. Multiple jailnames separated by a
	     space  are  allowed  on  the  command.  The  group prefix option is
	     enabled  for  these  subcommands.	 xxxx=	will  cause  only  those
	     jailnames	matching  the  "xxxx" to be selected for processing. The
	     equal sign "=" is	the  wildcard  symbol  that  signifies	all  the
	     characters  to  its  left	are  to  be used to match on jailname to
	     create a list of jailnames to be processed. Use  the  qjail  "list"
	     subcommand to list all the jails under qjail's scope.

qjail console
     Attaches  your host console to the selected jail. You are logged in as root
     by default. The command line prompt shows the name  of  the  jail	and  the
     path.  Entering  exit  will terminate the console. You can not activate the
     jails console if the jail is not currently running. This  is  intended  for
     administration  use only. Normally used to install ports or packages and do
     other system customization.

     -z      Code the same zone value used with the "install" subcommand to have
	     this subcommand process against that zone.

     -c      This option is for submitting console commands to a  jail.  If  the
	     command  has  arguments  they  need  to be enclosed in quotes. This
	     option can be used with the -U option to  target  other  user  ids.
	     Some examples; -c 'ls -l' or -c "ps ax" or -c ls

     -u      If  this  is absent, the /usr/bin/login -f root command is executed
	     logging you in as root. Coding the -u option with the  user  id  of
	     some  user  account  already  created  in	the  jail will cause the
	     console to be attached to	that  user.  The  "Welcome"  message  is
	     displayed.

     jailname
	     Jailname is a mandatory parameter. Only a single jailname is valid.
	     Use the subcommand list to display list of all jailnames.

qjail archive
     Creates  a  backup of one, or all jails. The specified jails directory tree
     is backed up as a tar file. The jails to be archived are required to be  in
     stopped  mode  before this "archive" command executes. The sharedfs and the
     template can also be archived, but only when specified as the only jailname
     on the "archive" command. The archive file name is derived  from  jailname,
     with  the	date  and  time  of  the  archive appended to the file name. The
     default archive directory	is  /usr/jails/archive.   The  jailnames  to  be
     archived  are  required to be in stopped mode before this "archive" command
     executes.

     There is no  qjail  function  to  delete  archive	files.	It's  the  users
     responsibility  to  delete  unwanted  archives using the host's rm command.
     It's also the user responsibility to keep a log of archive file names  with
     a description of why the archive was created, so the correct archive can be
     restored if desired.

     -z      Code the same zone value used with the "install" subcommand to have
	     this subcommand process against that zone.

     -s      This  option  makes  a  backup of the qjail internal definition and
	     control files to the archive directory as	"system.bkup"  plus  the
	     qjail  executable	scripts  to the archive directory as "pgm.bkup".
	     VIMAGE (virtualized network stack) is a highly experimental feature
	     that may cause the host system  to  freeze  up  and  wipe	out  the
	     contents of any open files. Experience has shown that at times this
	     has  happened  to	the qjail internal definition and control files,
	     and with less frequency to the qjail executable  scripts.	If  your
	     going  to	be  using vnet jails, it's highly recommended you have a
	     current backup.

     -A      When used with no other parameters  all  jails  are  archived.  Any
	     other parameter coded with -A is an syntax error.

     jailname
	     Multiple  jailnames  separated  by  a  space  are	allowed  on this
	     command. The group prefix option is enabled. xxxx= will cause  only
	     those  jailnames  matching  the  xxxx  character to be selected for
	     processing.  The  equal  sign  "="  is  the  wildcard  symbol  that
	     signifies all the characters to its left are to be used to match on
	     jailname  to  create a list of jailnames to be processed.	Jailname
	     is a mandatory parameter. Jails in "norun" status or  "man"  manual
	     start status are also candidates for archiving.

	     If jailname is sharedfs or template it will be archived. A sharedfs
	     containing  only  the  minimum  system install, takes less than one
	     minute elapse time to  complete.  A  sharedfs  containing	portsnap
	     downloaded  ports	tree  may  take  up  to 7 minutes elapse time to
	     complete. Template and all other jails takes less than  15  seconds
	     elapse time to complete. Use the subcommand list to display list of
	     all jailnames.

	     Use qjail restore to restore an archive.

qjail delete
     Totally  removes the jailnames directory /usr/jails/jailname, and its entry
     in       the	 three	      administration	    control	   files
     /usr/local/etc/qjail.fstab/jailname /usr/local/etc/qjail.local/jailname and
     /usr/local/etc/qjail.global/jailname.   The  jailnames  to  be  deleted are
     required to be in stopped mode before this "delete" command executes.

     -z      Code the same zone value used with the "install" subcommand to have
	     this subcommand process against that zone.

     -A      This option will delete all the jails under  qjail's  control.  You
	     are  advised to archive all your jails before doing this. This will
	     also reset the qjail.vnetctl counter to zero.

     jailname
	     Multiple jailnames  separated  by	a  space  are  allowed	on  this
	     command.  The group prefix option is enabled. xxxx= will cause only
	     those jailnames matching the xxxx	character  to  be  selected  for
	     processing.  The  equal  sign  "="  is  the  wildcard  symbol  that
	     signifies all the characters to its left are to be used to match on
	     jailname to create a list of jailnames to be  processed.	Jailname
	     is  a mandatory parameter. Jails in "norun" status are NOT excluded
	     from being deleted.

qjail restore
     Creates new jails from archive files.  The  default  archive  directory  is
     /usr/jails/archive.  If a jail exists with the same jailname as the archive
     being restored, the restore is terminated. You have to delete the	existing
     matching  jailname  before  you  can  restore  it. Archived jails that have
     "norun" status or "manual start" status will be restored  with  "norun"  or
     "man" status intact.

     -z      Code the same zone value used with the "install" subcommand to have
	     this subcommand process against that zone.

     -s      This  option  restores  the backup of the qjail internal definition
	     and control files from the archive  "system.bkup"	directory,  plus
	     the qjail executable scripts from the archive "pgm.bkup" directory.
	     VIMAGE (virtualized network stack) is a highly experimental feature
	     that  may	cause  the  host  system  to  freeze up and wipe out the
	     contents of any open files. Experience has shown that at times this
	     has happened to the qjail internal definition  and  control  files,
	     and  with	less  frequency to the qjail executable scripts. If your
	     going to be using vnet jails, it's highly recommended  you  have  a
	     current backup.

     jailname
	     The  most	current  archive  file	matching  the  jailname  will be
	     restored. To restore an older file you have  to  specify  the  full
	     archive file name with the date and time of the archive appended to
	     it.  Multiple  jailnames  separated  by  a space are allowed on the
	     command. The group prefix option is disabled for  this  subcommand.
	     Jailname  is  a  mandatory  parameter. To view all the full archive
	     file names, use this command ls /usr/jails/archive/.

	     If jailname is sharedfs or template and it's the only  jailname  on
	     the  command,  it	will be restored. A sharedfs containing only the
	     minimum system install, takes less than one minute elapse	time  to
	     complete. A sharedfs with source and full ports tree may take up to
	     7	minutes  elapse  time  to  complete.  The  existing  sharedfs or
	     template will be renamed to previous.sharedfs and previous.template
	     before restoring begins.

qjail config
     Manage parameters of specific jails. The selected jailnames are required to
     be in stopped mode before this command will process the jailname.

     The options are as follows:

     -z      Code the same zone value used with the "install" subcommand to have
	     this subcommand process against that zone.

     -A      This option is valid with all options except -i, -n  and  -d.  When
	     coded,  a	jailname  is  invalid.	This  -A option means to set the
	     selected option on "ALL" the jailnames including those  in  "norun"
	     and "man" status.

     -b      Lower  case  b populates the devfs_ruleset per-jail option with the
	     rule number representing the custom ruleset you added to the host's
	     /etc/devfs.rules file. If this -b	rule#  is  omitted  the  default
	     ruleset number 4 is used and in most cases is sufficient.

	     To  create your custom devfs_ruleset always copy rule number 4 from
	     the   hosts   /etc/defaults/devfs.rules   and   create   a   host's
	     /etc/devfs.rules  file renaming number 4 to a unused number of your
	     choice. Never grant access to raw disk devices inside  of	a  jail,
	     this  may	permit	processes  to exit the jail container and modify
	     files outside of the jail. To enable your new rule  issue	"service
	     devfs  restart"  from  the  hosts console. 	       Type "man
	     devfs" or "man devfs.rules" for information on how to create  devfs
	     rulesets  to  limit access and expose only appropriate device nodes
	     to a jail.

	     Example; If a jail were to run OpenVPN in a jail it requires access
	     to the "tun" device which rule number 4 does not include.	This  is
	     when a customized ruleset would be called for.

	     There  is a customized ruleset number 50 that adds the "bfp" device
	     which allows dhclient(8) and tcpdump(1) and maybe	some  others  to
	     work  inside  both non-vnet jails and vnet jails. It's not added by
	     default but the first time you use  "-b  50"  command  it	will  be
	     created automatically.

     -B      Upper case B disables the devfs_ruleset per-jail option and reverts
	     the jail to the default #4 devfs.rules for jails.

     -c      The  new  network	interface  device  name  you want to replace the
	     selected jailname "NIC" network interface device name with.   Coded
	     -c NIC jailname.

     -d      Display's	  the	 jails	  jail(8)    format    definition   from
	     "/usr/local/etc/qjail.config/jailname" which shows the  values  set
	     for the jail. Coded "-d jailname"

     -f      Set  the  FIB  (routing  table)  to  use when running commands from
	     inside the jail. This is a very advanced function used  under  very
	     special  conditions.  Coded  "-f  numeric	value" to identify which
	     routing table the jail is to use.

	     First you need to increase the number of  host  routing  tables  by
	     compiling	the  kernel  with  "option  ROUTETABLES=3"  or	use  the
	     net.fibs=3 option in /boot/loader.config. The result would be     0
	     =	default host routing table,				     1 =
	     first additional routing  table,				    2  =
	     second  additional  routing table. 			    Then
	     issue host console command;				  setfib
	     1	 route	add  default  "That  jails  default  route  ip	address"
	     Where  1	represents   the   first   additional	routing   table.
	     This route table will remain in effect until the next boot.  Adding
	     that  command to /etc/rc.conf would make it happen on every boot of
	     the host system.

	     Then use -f option with value of 1 to assign that routing table  to
	     the selected jail. See setfib(8) for more details.

     -F      Upper case F disables the setfib per-jail option.

     -h      This  option  will  enable ssh and create a user account having the
	     login ID and password of the jailname. To	address  basic	security
	     concerns,	on  first login the user will be prompted to enter a new
	     password. The jailname user account belongs to the "wheel" group so
	     it has "su" access to "root".

	     When the jails modified with the -h  option  are  started	for  the
	     first  time,  the	changes  to  configure	ssh  and create the user
	     account for that jail are applied. Doing a qjail  restart	jailname
	     or  a  qjail  stop  jailname  followed  by  qjail start jailname is
	     required to enable the changes which will be in  effect  from  that
	     point on.

     -4      The  new  IPv4  addresses you want to replace the selected jailname
	     IPv4 address with. More than a single IPv4 address can be	assigned
	     to  a  jail.  Multiple  IPv4  addresses  have  to be a list of IPv4
	     addresses separated by a comma "," without spaces before or  after.
	     Example  10.0.0.2,10.0.0.3,10.0.0.4		       Coded "-4
	     new-IPv4 jailname"

     -6      The new IPv6 addresses you want to replace  the  selected	jailname
	     IPv6  address with. More than a single IPv6 address can be assigned
	     to a jail. Multiple IPv6 addresses  have  to  be  a  list	of  IPv6
	     addresses	separated by a comma "," without spaces before or after.
	     Coded "-6 new-IPv6 jailname"

     -k      This negates the security of the jail concept and should  never  be
	     used  on a jail accessible from the public Internet. Lower case "k"
	     enables the allow.raw_sockets per-jail option.  Normally  the  ping
	     command  will  get "Operation not permitted" error when issued from
	     inside of a jail. This is a security design  default  of  the  jail
	     environment.  This  security  feature  does not allow users or jail
	     applications to create raw sockets. With raw sockets enabled a jail
	     user could use perl or python  or	some  other  port  utilities  to
	     create  raw  sockets  and	launch attacks on the host or the public
	     network. If the jail has public internet access, an public attacker
	     may compromise the jail and launch  attacks  on  the  host  or  the
	     public  network.  Consideration  of  the  security  risk verses the
	     convenience of using the ping command from inside of the jail is in
	     order. However this restriction may be  nullified	by  coding  this
	     option.  Recommend  using	dig  or  whois commands to verify public
	     access.

	     There are some valid situations for enabling allow.raw_sockets  for
	     an  individual  jail,  such  as  running mysql or php or PostgreSQL
	     which require local Unix sockets to work.

     -K      Upper case K disables the allow.raw_sockets per-jail option.

     -l      Lower case l enables the allow.mount.nullfs per-jail option.   This
	     is  restricted  to nullfs mounts on directories inside of the jail.
	     It has nothing to do with mounting nullfs from the host to the jail
	     filesystem which  is  always  available  to  do.  Any  mount_nullfs
	     commands  issued  from  within  the jail are only in effect for the
	     duration the  jail  is  running.  When  the  jail	is  stopped  the
	     established    nullfs    mount    is   neutralized.	     The
	     exec.prestart or exec.poststart parameters may be used to	automate
	     the issuing of the desired mount_nullfs commands.	   Documented in
	     jail(8).

     -L      Upper case L disables the allow.mount.nullfs per-jail option.

     -m      Means put this jail in "manual start" status.		      If
	     qjail_enable="YES"  is  present  in the "host's" /etc/rc.conf file,
	     then all jails in "man" status will be bypassed when  the	host  is
	     booted or powered up.

     -M      Upper case M disables the "man" per-jail option.

     -n      The  new  jailname  you want to replace the selected jailname with.
	     This changes the jailname and the jails  directory  name  that  the
	     jail  is known by. Coded "-n new-jail-name current-jail-name".  The
	     new jail name can only  have  alphanumeric,  dash,  and  underscore
	     characters and all numeric jail names are invalid.

     -p      Edits  a  text  file  containing  the  names  of  packages you want
	     installed in the jail. Enter one package name per line.

     -P      Upper case P runs a "pkg install" command reading	the  content  of
	     the  text	file  created by the lower case -p option. The host must
	     have public Internet access to download  the  package.  The  target
	     jail must be running.

     -q      Lower case q enables the allow.quotas per-jail option. Quota has to
	     be  compiled into the host's system kernel first for this option to
	     function. "option QUOTA" is the statement you have to add	to  your
	     kernel definition source. Documented in jail(8).

     -Q      Upper case Q disables the allow.quotas per-jail option.

     -r      Means  put this jail in "norun" status.			      If
	     qjail_enable="YES" is present in the  "host's"  /etc/rc.conf  file,
	     then  all	jails in "norun" status will be bypassed when the system
	     is booted and also when the start command is used.

     -R      Upper case R disables the "norun" per-jail option.

     -s      Enables the securelevel per-jail  option.	Documented  in	jail(8).
	     There  are  five  different security levels. Any super-user process
	     can raise the level, but no process can lower it.		     The
	     security levels are:

	      -1    Permanently insecure mode - always run the system in
		    insecure mode. This is the default initial value.

	      0     Insecure mode - immutable and append-only flags may be
		    turned off. All devices may be read or written subject
		    to their permissions.

	      1     Secure mode - the system immutable and system append-only
		    flags may not be turned off; disks for mounted file
		    systems, /dev/mem and /dev/kmem may not be opened for
		    writing.

	      2     Highly secure mode - same as secure mode, plus disks may
		    not be opened for writing (except by mount(2)) whether
		    mounted or not. This level precludes tampering with file
		    systems by un-mounting them, but also inhibits running
		    newfs(8) while the system is in multiuser. In addition,
		    kernel time changes are restricted to less than or equal
		    to one second. Attempts to change the time by more than
		    this will log the message "Time adjustment clamped to
		    +1 second".

	      3     Network secure mode - same as highly secure mode, plus IP
		    packet filter rules (see ipfw(8), ipfirewall(4) and
		    pfctl(8) cannot be changed and dummynet(4) or pf(4)
		    configuration cannot be adjusted.

	     This does not really apply to the qjail jail system because all  of
	     the   system  executables	are  in  an  read  only  nullfs  mounted
	     filesystem which makes it impossible to change file content or  add
	     files  to those directories. This is by far a stronger form of jail
	     security than the securelevel parameter can provide on an	per-jail
	     basis.

     -S      Upper case S disables the securelevel per-jail option.

     -t      Lower case t enables the allow.mount.tmpfs per-jail option. This is
	     restricted to tmpfs mounts on directories inside of the jail.

     -T      Upper case T disables the allow.mount.tmpfs per-jail option.

     -v      Lower   case   v	enables   the  vnet  [vimage]  per-jail  option.
	     WARNING: The vnet/vimage configuration used here  is  designed  for
	     host    systems	running    version    11.0-RELEASE   or   newer.
	     VIMAGE  (virtualized  network  stack)  is	a  highly   experimental
	     feature.  Information given here maybe different in newer RELEASES.
	     Vimage has to be compiled into the host's kernel  before  the  vnet
	     function  will work. "option VIMAGE" is the only statement you have
	     to add to your kernel definition source.

	     The "bridge/epair" method is used to establish network  access  for
	     the  vnet	jail. The /usr/local/etc/qjail.vnetctl file contains the
	     counter whos number is used to assign a unique permanent number  to
	     the  vnet	jail's virtual ethernet epair interfaces. The epair pair
	     are named epair<n>[ab] where <n> is  the  unique  number  generated
	     using  the value in the qjail.vnetctl file. This means the names of
	     the first pair of epair  interfaces  would  be  named  epair1a  and
	     epair1b.  The bridge qjail uses is named bridge10 to greatly reduce
	     the likelyhood of the host administrator creating a bridge with the
	     same name.

	     The -v option requires a value of none, ipfw, pf, or ipf, to select
	     which firewall to run in the vnet jail. The host and the vnet  jail
	     must be running the same firewall type, meaning if the vnet jail is
	     using   ipfw,   then   the   host	 must	also  be  running  ipfw.
	     Note: ipf is short for ipfilter.				     The
	     "config -w and -v" flags can be coded together.

	     "IPFW"  is  currently  the  only  one  that can run on the host and
	     inside the vnet jail at the same time and function correctly.  IPFW
	     dummynet and "in kernel NAT" has not been tested in  a  vnet  jail.
	     The  vnet	jail's	IPFW  logging  records are intermingled with the
	     host's IPFW logging records on  the  host. 		   "IPF"
	     can  run  on  the	host  and inside the vnet jail at the same time,
	     except the ipf rules in the vnet jail are not enforced.	"PF" can
	     run on the host and inside the vnet jail at the same  time,  except
	     the  pf  rules in the vnet jail are not enforced.	 "In conclusion;
	     At the current time [RELEASE-11.0], PF and IPF firewalls in a  vnet
	     jail  do  not work and are useless for controlling access to a vnet
	     jail on a per vnet jail basis."

	     Because of the increased likely hood of host system freezes or page
	     faults, vnet jails are  restricted  to  directory	type  filesystem
	     jails  only. No image jail type are allowed because of the manually
	     effort required to recover them. Experience has shown that at times
	     a vnet system freeze may cause the contents of any open files to be
	     wiped out leaving only  the  file	name.  This  effects  the  qjail
	     internal  definition and control files. It's highly recommended you
	     use the "archive -s" option to create a  current  backup  of  these
	     files. Using the "restore -s" option will restore those files after
	     a vnet system freeze greatly simplifying the recovery process.

     -V      Upper case V disables the vnet [vimage] per-jail option.

     -w      Enables  the  vnet.interface  per-jail  option.  Populate	with the
	     network interface device name of the NIC facing the public internet
	     or facing the LAN server you want vnet [vimage] to exchange traffic
	     with.

     -W      Upper case W disables the vnet.interface per-jail option.

     -x      Lower case x enables  the	allow.mount.zfs  per-jail  option.  This
	     option has mandatory host requirements before it's useful. The host
	     must  have all or some part of it's hard drive space defined to zfs
	     and actively using  it.  See  zfs(8)  for	information  on  how  to
	     configure	the  zfs  filesystem to operate from inside a jail.  The
	     exec.prestart or exec.poststart parameters may be used to	automate
	     the  issuing  of the desired zfs commands. 	      Documented
	     in jail(8).

     -X      Upper case X disables the allow.mount.zfs per-jail option.

     -y      Lower case y enables  the	allow.sysvipc  per-jail  option.   Grant
	     processes	within	the  jail  access  to System V IPC (semaphores).
	     Enabling sysvipc makes the jail considerably less secure in respect
	     to shared memory. This feature should not be used unless absolutely
	     necessary when no other option is available. Documented in ipcs(1).

	     Example: Zabbix (a system	monitoring  tool)  which  is  the  major
	     competitor  of  naigos  would need allow.sysvipc enabled so it will
	     start.

     -Y      Upper case Y disables the allow.sysvipc per-jail option.

     jailname
	     For all options except -d, -i, and -n, multiple jailnames separated
	     by a space are allowed on the command. The group prefix  option  is
	     enabled.  xxxx=  will  cause only those jailnames matching the xxxx
	     characters to be selected for processing. The equal sign "=" is the
	     wildcard symbol that signifies all the characters to its  left  are
	     to be used to match on jailname to create a list of jailnames to be
	     processed. Jailname is a mandatory parameter. Use subcommand "list"
	     to show a list of all jailnames.

qjail update
     Provides the ability to add or update the ports collection on sharedfs, and
     a	method	for  synchronizing  the  host's system binaries and those of the
     sharedfs.

     -z      Code the same zone value used with the "install" subcommand to have
	     this subcommand process against that zone.

     -b      The basic requirement of FreeBSD jails is the jail environment  and
	     the  host	run  the same version of the systems binaries. Since the
	     FreeBSD-update utility only inspects the host system  to  determine
	     the   systems  RELEASE  level  it's  not  applicable  in  a  jailed
	     environment.   Performing	 a   make   buildworld/installworld   on
	     sharedfs's  source  is  such  a waste of effort and resources after
	     having done this already for the host system. This option makes the
	     buildworld/installworld obsolete for the qjail environment.

	     This option deletes all the system binaries from the  sharedfs  and
	     them  copies  the host's system binaries to sharedfs. It's intended
	     to be used after running the FreeBSD-update utility on the host  to
	     apply  security  updates  or  to  upgrade the GENERIC host from one
	     RELEASE to another  newer	RELEASE,  or  after  performing  a  make
	     buildworld/installworld  on  the host updating its system binaries.
	     Basically update the host	and  copy  your  work  to  the	sharedfs
	     getting both environments synchronized.

	     Note:  When  going from one subversion to a newer subversion within
	     the same major RELEASE, IE: 8.0 to 8.1 there is no need  to  update
	     your  installed ports/packages. When going to a newer major RELEASE
	     IE; 8.1 to 9.0 then your installed ports/packages need updateing.

     -p      This option Invokes the portsnap utility to  fetch  and  extract  a
	     FreeBSD  ports  tree from "portsnap.FreeBSD.org" (475MB). By design
	     the "sharedfs" filesystem includes the "/usr/ports" directory which
	     is not automatically populated by "qjail install".

	     An    alternative	  to	executing    portsnap	 to	populate
	     "sharedfs/usr/ports"   would  be  to  temporarily	make  the  hosts
	     "/usr/ports" directory tree available to the  jails  by  using  the
	     "mv"		 command		like		   this:
	     mv   /usr/ports   /usr/jails/sharedfs/usr	 and   returned    doing
	     mv /usr/jails/sharedfs/usr/ports /usr

	     Portsnap  will  initially download a compressed file containing the
	     complete ports tree. Elapse download time greater than  15  minutes
	     is  normal.  On  its  initial  execution,	an  extract is performed
	     creating  the  /usr/ports	sub-directories  and  populating   them.
	     Subsequent  executions,  the  /usr/ports  directory  exists,  so an
	     update is done populating the /usr/ports directory tree  with  only
	     things  that have been changed or added. This is portsnap's default
	     behavior. This behavior can be somewhat modified  by  changing  the
	     content  of the /usr/local/etc/qjail.portsnap.conf file. Add REFUSE
	     statements to select the ports categories you don't want  populated
	     to  your  /usr/ports directory tree. Ideal candidates to REFUSE are
	     the non-English languages, astro,	biology,  cad,	finance,  games,
	     math,  mbone,  and  science.  From  there you can select additional
	     categories to REFUSE based on your normal jail port usage. For more
	     details see Appendix A.6-Using Portsnap and Chapter  24.3	Portsnap
	     in the FreeBSD Handbook or "man portsnap".

     -P      This  is  an  upper case P. This option copies the hosts /usr/ports
	     directory tree to the /usr/jails/sharedfs/usr/ports directory  tree
	     after first deleting the existing one.

     -S      This  is  an  upper  case	S. This option copies the hosts /usr/src
	     directory tree to the  /usr/jails/sharedfs/usr/src  directory  tree
	     after first deleting the existing one.

     -l      This  enables  or disables [on | off] logging of all qjail commands
	     and error messages to /var/log/qjail.log file. Each  log  entry  is
	     prefixed  with  a	date/time stamp and the user account name of the
	     user  entering  the  commands.   An   entry   is	also   made   in
	     /etc/newsyslog.conf to auto rotate the qjail.log file.

qjail logmsg
     This  subcommand  will  post what every follows the subcommand as a textual
     comment to the qjail system log. Offers the user the opportunity  to  place
     their  own documentation into the log about what or why their doing things.
     Totally free form.

qjail help
     Help without any sub-command displays the qjail(8) manual. Help followed by
     a valid sub-command displays the syntax of  that  sub-command  and  details
     about that sub-command option flags. "help help" gives help about help.

GENERAL QJAIL USAGE TIPS
     *	 Qjail must be run by a superuser login account such as "root"
	 or a normal user login account belonging to the "wheel" group.
	 For user accounts in the wheel group, after logging in they have
	 to issue the "su" command and reply with the root password to
	 gain the superuser access required by qjail. The "sudo" port
	 can be used instead of "su" to perform the same function
	 if so desired.

     *	 For a jail to receive unsolicited inbound traffic from the
	 public internet, the host's firewall must have a rule to allow
	 the desired port number to pass through the firewall and a NAT
	 forward rule targeting the IP address and port number of the
	 desired jail. For additional details read qjail-howto man page.

     *	 You can remotely access a jail through ssh if that option was
	 selected during the jail create process and the host's firewall
	 and NAT forwarding rules are in place.

     *	 The orderly stopping of jails that have databases or other
	 applications that may have delayed buffered writes to files is
	 accomplished by the use of the "qjail stop" command or issuing
	 the "shutdown now" command on the host. Using the host's halt
	 and reboot commands or pressing the computers reset or power on
	 buttons results in the running jails being instantly terminated
	 which some applications can not tolerate. Always use the host's
	 shutdown command or "qjail stop" command.

     *	 By design the "sharedfs" filesystem includes the "/usr/ports" and
	 "/usr/src" directories which are not automatically populated by
	 "qjail install". You can temporarily make the hosts "/usr/ports"
	 or "/usr/src" directory trees available to the jails by using the
	 "mv" command like this:
	 mv /usr/ports /usr/jails/sharedfs/usr and returned doing
	 mv /usr/jails/sharedfs/usr/ports /usr

     #	 There are some common utilities that require the "bfp" device to
	 function in a jail such as dhclient(8) and tcpdump(1). There is
	 a customized ruleset number 50 that adds the "bfp" device. The
	 first time you use the "qjail config -b 50" command it will be
	 created automatically.

     *	 In environments where you want all the jails to use the same set
	 of ports but don't want to have to compile these ports in every jail,
	 you can do the following. Populate sharedfs/usr/ports/packages/
	 directory with the packages you want. All jails have access to this
	 shared directory. Then create a SEED jail to be used as the source
	 to clone all of the other jails from. First create your basic SEED
	 jail using the template. You may wish to customize a flavor
	 to contain any desired /etc config files unique to that seed.
	 Additionally you can start the SEED jails console and perform any
	 other customization such as "pkg install" for the pre-staged
	 packages or "make install" on ports you want. When your satisfied
	 with the SEED jail's configuration, archive it. Then use the SEED's
	 archive file jailname in the -a option of the create subcommand so
	 it's used as the source template to create the other jails from.
	 Optionally you could use the -d and or -I options with the -a
	 option for mass duplication of jails based on that SEED
	 configuration.

     *	 In the situation where you want "all" the jails that you EVER create
	 to have the same selection of ports, create a "SEED" jail as
	 described above. When your satisfied with your "SEED" jail, delete
	 the /usr/jails/template directory and rename your "SEED" jail to
	 /usr/jails/template directory.
	 mv /usr/jails/SEED /usr/jails/template
	 rm /usr/local/etc/qjail.local/SEED
	 rm /usr/local/etc/qjail.global/SEED
	 rm /usr/local/etc/qjail.fstab/SEED
	 From that point on, all new jails created using the template
	 will contain your standard ports.

     *	 The /etc/rc.conf in the default flavor has this statement;
	 cron_flags="$cron_flags -J 60" this enables time jitter
	 for all /etc/crontab jobs run by the superuser, which on a
	 pristine jail environment is everything in the crontab file.
	 Time jitter works this way: Prior to executing commands in the
	 /etc/crontab file, cron will sleep a random number of seconds
	 in the range from 1 to 60 seconds. This option greatly helps
	 to reduce host system load spikes during moments when a
	 lot of cron jobs are likely to start at once, IE, at the
	 beginning of the first minute of each hour. Without this
	 statement in every deployed jail to randomly spread the
	 starting of cron tasks over the first minute, most likely
	 the host system would come to a darn near halt. The default
	 flavor has another customized configuration file just for
	 jails. The /etc/periodic.conf overrides the normal emailing
	 of reports and instead creates daily, weekly, and monthly
	 logs within each jails /var/log directory. These logs get
	 rotated and deleted as specified in the jails
	 /etc/newsyslog.conf.

     *	 Its a mandatory requirement of the FreeBSD "jail" system that the
	 host and the jails are both running the same version of the operating
	 system binaries. First you have to get your host system running at
	 the newer RELEASE version. You can do the fresh install from scratch
	 method, or update your host's current RELEASE version by using the
	 Freebsd-update utility or svn update your system source and make
	 buildworld/installworld. After the host is running the new RELEASE
	 version and before starting any qjail's. You can run the "install"
	 subcommand again and re-install with the newer RELEASE version
	 matching what is on the host, without disturbing the existing
	 installed jails, or run the "update" subcommand with the -b option
	 to copy the hosts operating system binaries to the sharedfs.
	 If going to a newer major RELEASE, IE: 6.4 to 7.1; 7.2 to 8.0;
	 then remember, all existing jails that have ports or packages in
	 them will need them updated to versions compatible with the new
	 major RELEASE version. On the other hand, if going from a
	 subversion to a newer subversion within the same major RELEASE,
	 IE: 7.1 to 7.2; 8.0 to 8.1, then there is no need to update your
	 installed ports/packages.

     *	 Each jail has a console log located in the host's /var/log/
	 directory named jail_*_console.log. Where "*" = jailname.
	 These logs don't grow much but if the jails are going to be
	 used long term, their names should be added to the hosts
	 /etc/newsyslog.conf so they get auto rotated and deleted.
	 You don't want some jail user to cause console messages and
	 flood the jails log until all the host's disk space is
	 consumed bring the host to a abrupt stop.

     *	 If you have qjail start a image jail, then the contents of its
	 sparse image file are accessible by the host system. From the host
	 you can "cd" into the image jails jailname directory and access
	 the directory tree there just like any other directory tree.

     *	 The ping command will get "Operation not permitted." error when
	 issued from inside of a jail. This is not a qjail restriction, but
	 a design default of the FreeBSD jail command. This default does not
	 allow users or jail applications to create raw sockets. This is a
	 security feature. With raw sockets a jail user could use perl or
	 python or some other port utilities to create raw sockets and launch
	 attacks on the host or the public network. The config -k option
	 maybe used to enable allow.raw_sockets function on a per-jail basis.

     *	 Once your jail has public network access, (test with whois)
	 then all your normal application install functions are available,
	 (ports tree update, svn update, ports and package installs) right
	 from the jails console using the "qjail console" command.

     *	 Jails do not have a network stack of their own, so they can't have
	 a firewall. The host's firewall and network is in control.

     *	 If you want absolute control over starting your Jails. (IE. no boot
	 time auto-start of the jails), then don't put the qjail_enable="YES"
	 statement in the hosts rc.conf file.

     *	 If for whatever reason you want to completely delete the qjail
	 jail environment so you can start over with the install
	 subcommand from scratch, execute these commands;
	  rm -rf /usr/jails
	  rm -rf /usr/local/etc/qjail.local
	  rm -rf /usr/local/etc/qjail.global
	  rm -rf /usr/local/etc/qjail.config
	  rm -rf /usr/local/etc/qjail.packages
	  rm -rf /usr/local/etc/qjail.fstab
	  rm /var/log/jail_*
	  rm /var/log/jails.lo*

FILES
     /usr/local/bin/qjail	     The main work horse
     /usr/local/etc/rc.d/qjail.bootime	Boot time jail starter
     /usr/local/etc/qjail.local/*    internal jail definition files for no zones
     /usr/local/etc/qjail.global/*    internal	jail  definition  files  for all
     zones
     /usr/local/etc/qjail.config/*   jail.config jail definition files	for  all
     zones
     /usr/local/etc/qjail.packages/* List of packages to "pkg install" per jail.
     /usr/local/etc/qjail.fstab/*    sharedfs null mount record for each jail
     /var/run/jail_*.pid	     Run pid record for each started jail
     /var/log/jail_*_console.log      * = jailname
     /usr/local/share/examples/qjail  Example flavors
     /usr/jails 		      Location of qjail's jails
     /usr/jails/archive 	      Location of qjail's archives
     /usr/jails/flavors 	      Location of qjail's flavors
     /var/log/jails.log 	      Location of qjail's system log file

SEE ALSO
     qjail-intro(8), qjail-howto(8), qjail-vnet-howto(8), qjail-ipv6-testing,
     jail(8), mount_nullfs(8), mdconfig(8), devfs(5), portsnap(8),
     freebsd-update(8)

AUTHOR
     ezjail version 3.1 which qjail was forked from was written by
     Dirk Engling <erdgeist@erdgeist.org>
     http://erdgeist.org/arts/software/ezjail/

     qjail versions 1.0 through 2.2 written by
     The Qjail project team, Angeles City, Philippines
     Joe Barbish <qjail1@a1poweruser.com> for the Qjail project team.

     qjail version 3.0 and newer maintained by
     Joe Barbish <qjail1@a1poweruser.com>
     http://qjail.sourceforge.net/

FreeBSD ports 15.1		  June 17, 2017 			qjail(8)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=qjail&sektion=8&manpath=FreeBSD+15.1-RELEASE+and+Ports>

home | help