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

FreeBSD Manual Pages

  
 
  

home | help
qjail(8)		  BSD 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] [-c]
		   [-F]	[-i size] [-d duplicate#] jailname [jailip...]
     qjail list	   [-z zone] [jailname...]
     qjail start   [-z zone] [jailname...]
     qjail stop	   [-z zone] [jailname...]
     qjail restart [-z zone] [jailname...]
     qjail console [-z zone] [-e]  jailname
     qjail archive [-z zone] [-A] [jailname...]
     qjail delete  [-z zone] [-A] [jailname...]
     qjail restore [-z zone] [-f] [jailname...]
     qjail config  [-z zone] [-r run|norun -A] [-n newname]
		   [-i newip] [-c newnic] [jailname...]
     qjail update  [-z zone] [-b] [-p] [-l on|off]
     qjail logmsg  [text....]
     qjail help	   [manual]

DESCRIPTION
     The qjail utility is used to manage the qjail environment and all the
     jails inside the qjail scope. Qjail's administration ease does not
     evaporate as jails	deployed grow beyond 15	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.

qjail install
     Allocates the directory structure used by qjail and must be populated
     with the same RELEASE 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
     a fresh install newly compiled from the sources, or installed from	an iso
     image file, or from the original distribution files. By default, Qjail
     downloads the original distribution files to populate its directory
     structure with a pristine version.

     This is doable only with production versions of the operating system.
     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" are only made available
     as	iso image files	on the FTP servers for user testing. The last X.X-RCx
     version becomes the next X.X-RELEASE version released to the public. You
     can install the qjail directory structure using these pre-release
     versions by using this command, "qjail install -f path.to.file.location"
     to	point to the iso file on your hard drive or to a cdrom containing the
     burned iso	file.

     The "X.X-STABLE, X.X-PRERELEASE and X.X-CURRENT" versions are only
     creatable by compiling the	FreeBSD	sources. Qjail will not	install	on
     host's running these versions. You	can work around	this by	issuing	these
     commands.
	 setenv	UNAME_r	"X.X-RELEASE"  Code what ever the current RELEASE is.
	 qjail install		 This will load	the above version into qjail.
	 qjail update -b	 Copy the host's binaries into qjail system.

     This command can be run any time to rebuild the basejail and the newjail
     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: 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.	If
     going from	a subversion to	a newer	subversion within the same major
     RELEASE, IE: 8.0 to 8.1, then there is no need to update your installed
     ports/packages.

     The default location for qjail's basejail is /usr/jails, so be sure you
     have enough space there, a	FreeBSD	base Release is	around 145MB.

     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.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/jail	and
	     /usr/local/etc/fstab.qjail	and /usr/local/etc/qjail/ is 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 or permanently change it by	using
	     the qjail.conf file. 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 imagefile, 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/8.0-RELEASE
	       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".

	 qjail install -z env1 -f /mnt/usr/freebsd-dist
	       Same as above accept now	targeting 9.x release original
	       distribution files.

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

     4.	 mdconfig -a -f	/usr/8.0-RELEASE-i386-disc1.iso	md0
	 mount -v -t cd9660 /dev/md0 /mnt
	 qjail install -f /mnt/8.0-RELEASE
	       If you downloaded the disc1.iso to /usr.
	       Use this	option to target the mounted disc1.iso RELEASE
	       file as the source of the original distribution files used
	       to populate the qjail directory structure.

	 mdconfig -a -f	/usr/9.0-RELEASE-i386-disc1.iso	md0
	 mount -v -t cd9660 /dev/md0 /mnt
	 qjail install -f /mnt/usr/freebsd-dist
	       Same as above accept now	targeting 9.x release.

	       After the install completes, execute the	following commands
	       to release the disc1.iso	md0 file.
		    cd /usr
		    umount  /mnt
		    mdconfig -d	-u md0

     5.	 To fetch the RELEASE original distribution files files	for 8.x
	 manually create the .netrc file in your user id's home	directory (~/)
	 and populate it with this.
	    machine ftp2.FreeBSD.org
	    login anonymous
	    password FBSD@home.com
	    macdef init
	    prompt off
	    cd /pub/FreeBSD/releases/i386/8.0-RELEASE
	    epsv4 off
	    $ getdir base manpages
	    quit

	    macdef getdir
	    ! mkdir $i
	    mreget $i/*

	 Then issue these commands on the command line.	If the FTP download
	 times out re-issue the	FTP command again to resume where it left off.
	 mkdir /usr/8.0-RELEASE
	 cd /usr/8.0-RELEASE
	 ftp -v	ftp2.FreeBSD.org

	 qjail install -f /usr/8.0-RELEASE
	       Use this	option to target the 8.0-RELEASE files you FTP'ed
	       as the source of	the original distribution files	used
	       to populate the qjail directory structure.

	 For 9.x releases;
	 mkdir /usr/9.0-RELEASE
	 cd /usr/9.0-RELEASE
	 ftp
     ftp2.FreeBSD.org:pub/FreeBSD/releases/i386/i386/9.0-RELEASE/base.txz
	 qjail install -f /usr/9.0-RELEASE/usr/freebsd-dist

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 newjail 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 three administration files are	created	for
     each jail.	They are /usr/local/etc/fstab.qjail.jailname file,
     /usr/local/etc/qjail/jailname file, and the
     /usr/local/etc/qjail.global/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
	     address range. If this option is coded, then when qjail starts
	     the 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. The benefit is you
	     don't have	to code	all the	possible jail IP addresses using the
	     ifconfig alias command in /etc/rc.conf for	that "network
	     interface name".

	     Normally this option should be used on all	jails. 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
	     these 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 jailip below 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 on. 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 newjail 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. The -n
	     option has	to be coded if one is desired.

     -f	     Using the flavor option you can apply an qjail flavor to your new
	     jailname. If the -f flavor	option is coded, the 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.

	     A additional sample flavor	is located at
	     /usr/local/share/examples/qjail/nullmailer-example.

     -c	     This option will enable ssh and create a user account having the
	     login ID and password of the jailname. On first login the user
	     will be prompted to enter a new password to address basic
	     security concerns.	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.

     -F	     This upper	case -F	option is used to force	the use	of IP
	     addresses that are	already	assigned to existing jails. Two	or
	     more jails	may share the same IP addresses	only if	the -n option
	     is	not enabled on those jails. Just because you force qjail to
	     create jails sharing IP addresses does not	mean those jails will
	     have network access. To gain network access you must manually add
	     alias statements to /etc/rc.conf for those	shared IP addresses.

     -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 25m	is the bare minimum size for a
	     image jail.

	     NOTE: If you get error message "create/symlink failed, no inodes
	     free" or "(bsdcpio) out of	inodes"	increasing your	-i value by
	     15M will correct the problem.

     -d	     Enter a numeric number representing the number of times you want
	     this jailname duplicated. A suffix	number starting	at one and in-
	     cremented by one for each duplication is appended to each newly
	     created jailname. Any number greater than 100 is invalid. Only a
	     single IP address is valid	with the -d option.

	     For each repetition of the	duplication cycle the last octal of
	     the IP address increments by 1. If	multiple IP addresses are
	     coded, they have to be a list of IP addresses separated by	a
	     comma ",".	Example	10.0.0.2,10.0.0.3,10.0.0.4 In this case	the
	     last octal	of the last IP address coded will be the one getting
	     incremented. In the above example that would be the number	4.

     jailname
	     Only a single jailname is valid. To better	manage large jail de-
	     ployments a jail naming convention	that groups jails by common
	     function or user groups is	advised. The maximum jailname size is
	     55	characters. The	equal sign "=" is not valid in jailnames.
	     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.

     jailip  This is either a static IP	address	or a private IP	address. More
	     than a single IP address can be assigned to a jail. Multiple IP
	     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

	     According to RFC 1918, you	can use	the following IP address
	     ranges for	private	nets which will	never be connected to the In-
	     ternet.  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.	Use at your own	risk.

qjail create examples
     1.	 qjail create -n rl0 webserver 8.8.178.135,10.0.10.20
	       This creates a single new directory tree	type jail as
	       /usr/jails/webserver from the newjail template.
	       The auto	alias function is enabled.

     2.	 qjail create -n rl0 -c	-f myflavor bld21a-floorA-cell01 10.0.10.20
	       This creates a single new directory tree	type jail as
	       /usr/jails/bld21a-floorA-cell01 from the	newjail	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 -n rl0 -a	cell-a prison-B	10.0.10.20,10.0.10.30
	       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 function is enabled.

     4.	 qjail create -n rl0 -a	cell-a -d 15 room 10.0.10.20
	       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 function is enabled

     5.	 qjail create -n rl0 -d	15 room	10.0.10.20
	       This creates a new directory tree type jail using the newjail
	       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 room 10.0.10.20
	       This does the same as the previous one except these jails
	       also has	ssh access enabled.

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

     8.	 qjail create -n rl0 -d	15 -C -i 100m class 10.0.10.20
	       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 -n rl0 -c	-a cell-a -i 1g	room 10.0.10.20
	       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 function is enabled and ssh access is enabled.

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

qjail list
     Lists jails inside	qjail's	scope. They are	shown by the order they	start
     up, as defined by rcorder.

     The format	of the listing is straightforward. The left most column	is the
     status flag consisting of 2 letters, the first letter can be a (D)	for
     Directory tree based jail,	or (I) for image file based jail, the second
     letter can	be a (R) meaning the jail is currently running,	or a (S)
     meaning the jail is stopped. An optional third letter (N) means the jail
     is	in norun status. You use the qjail config subcommand -r	option to
     enable and	disable	the norun setting.

     The rest of the columns in	the row	is the jail's jid (only	available if
     the jail is started), the network interface device	name, (You use the
     qjail config subcommand -c	option to change this setting),	the jails IP
     address or	addresses, and 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.

     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 listed. 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 jail-
	     names 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.

     -e	     If	this is	absent,	the /usr/bin/login -f root command is executed
	     logging you in as root. A one time	change to use the standard lo-
	     gin prompt	to enter the user id and password of some user account
	     all ready created in the jail can be accomplished by using	this
	     -e	/usr/bin/login option on the "console" command (or) perma-
	     nently changed using the qjail.conf file.

     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 gzip	file. The jails	to be archived are required to
     be	in stopped mode	before this "archive" command executes.	The basejail
     and the newjail 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 name and
     location can be permanently changed using the /qjail.conf file.

     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.

     -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	are
	     also candidates for archiving.

	     If	jailname is basejail or	newjail	and it's the only jailname on
	     the command, it will be archived. A basejail containing only the
	     minimum system install, takes less	than one minute	elapse time to
	     complete. A basejail containing manpages and portsnap downloaded
	     ports tree	may take up to 7 minutes elapse	time to	complete.
	     Newjail and all other jails without any "desktop" installed 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
     three administration control files	/usr/local/etc/fstab.qjail.jailname
     /usr/local/etc/qjail/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.

     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 will be restored with "norun" status intact. The name
     and location of the archive directory can be permanently changed using
     the qjail.conf file.

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

     -f	     By	design restore refuses to restore a archive file created on a
	     different host system than	the one	the restore is running on.
	     This means	the selected archive file and the current basejail are
	     of	different RELEASE versions. Use	the -f flag to force the re-
	     store of this archive file.

     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 enabled for this subcommand.
	     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. Use this command to
	     ls	/usr/jails/archive/ to view all	the full archive file names.

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

qjail config
     Manage parameters of specific jails.

     The options are as	follows:

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

     -r	     file, then	all jails will be started when the system is booted.
	     If	qjail_enable="YES" is present in the "host's" /etc/rc.conf
	     file, then	all jails will be started when the system is booted.
	     You can prevent this behavior by using the	-r norun option	on the
	     jailnames you don't want auto started at boot time	and re-enable
	     boot auto start by	using the -r run option	on those jailnames.

     -A	     This option is only valid when coded with option -r. When coded,
	     jailnames are invalid. This -A option means to set	"ALL" the
	     jailnames to the "norun" status or	the "run" status.

     -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.

     -i	     The new IP	address	you want to replace the	selected jailname IP
	     address with. More	than a single IP address can be	assigned to a
	     jail. Multiple IP 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

     -c	     The new network interface device name you want to replace the se-
	     lected jailname "NIC" network interface device name with.	Coding
	     -c	null will disable the auto alias feature. Review the create
	     subcommand	-n option for details.

     jailname
	     For the -c	-r and -i options multiple jailnames separated by a
	     space are allowed on the command. The group prefix	option is en-
	     abled. 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. For the -n option	only a single jailname is
	     valid. 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 basejail,
     and a method for synchronizing the	host's system binaries and those of
     the basejail.

     -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 de-
	     termine the systems RELEASE level it's not	applicable in a	jailed
	     environment. Performing a make buildworld/installworld on base-
	     jail's source is such a waste of effort and resources after hav-
	     ing 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 basejail and
	     them copies the host's system binaries to basejail. 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 basejail get-
	     ting 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	RE-
	     LEASE IE; 8.1 to 9.0 then your installed ports/packages need up-
	     dateing.

     -p	     This option Invokes the portsnap utility to fetch and extract a
	     FreeBSD ports tree	from portsnap.FreeBSD.org (475MB).

	     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".

     -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 there doing
     things. Totally free form.

qjail help
     The "help"	function displays the syntax of	all the	subcommands.

     manual  This Launches the man 8 qjail command to display the full manual.

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.

     *	 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 basejail/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	newjail	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_add 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/newjail	directory and rename your "SEED" jail to
	  /usr/jails/newjail directory.
	 mv /usr/jails/SEED /usr/jails/newjail
	 From that point on, all new jails created using the newjail 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 basejail.
	 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. However this restriction
	 may be	nullified for all jails	by setting the
	 security.jail.allow_raw_sockets sysctl	MIB to 1 on the	host.
	 echo "security.jail.allow_raw_sockets=1" >> /etc/sysctl.conf
	 Doing so allows utilities like	ping and traceroute to operate from
	 in side of all	the jails.

     *	 Once your jail	has public network access, (test with whois or dig)
	 then all your normal application install functions are	available,
	 (ports	tree update, svn update, ports and package installs) right
	 from the jails	console	or through ssh if that option was selected
	 during	the jail create	process.

     *	 Jails in their	current	form (RELEASE-9.0) 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;
	  chflags -R noschg /usr/jails
	  chflags -R nosunlink /usr/jails
	  rm -rf /usr/jails
	  rm -rf /usr/local/etc/qjail
	  rm -rf /usr/local/etc/qjail.global
	  rm /usr/local/etc/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-jail2  Boot time	jail starter
				      (Clone of	/etc/rc.d/jail)
     /usr/local/etc/rc.d/qjail2	      Qjail jail starter stopper
     /usr/local/etc/qjail.conf	      Changes defaults permanently
     /usr/local/etc/qjail/*	      List of jail property files for no zones
     /usr/local/etc/qjail.global/*    List of jail property filess for all
     zones
     /usr/local/etc/fstab.*	      basejail null mount record for each jail
     /var/run/*			      Run id 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.conf(8), jail(8), chroot(8),
     mount_nullfs(8), mdconfig(8), devfs(5), fdescfs(5), procfs(5),
     portsnap(8) freebsd-update(8)

AUTHOR
     Joe Barbish <qjail@a1poweruser.com>

BSD				March 01, 2012				   BSD

NAME | SYNOPSIS | DESCRIPTION | qjail install | qjail install examples | qjail create | qjail create examples | qjail list | qjail [start | stop | restart] jailname..... | qjail console | qjail archive | qjail delete | qjail restore | qjail config | qjail update | qjail logmsg | qjail help | GENERAL QJAIL USAGE TIPS | FILES | SEE ALSO | AUTHOR

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

home | help