GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  QJAIL (8)

NAME

qjail - Utility for deployment of jail environments

CONTENTS

Synopsis
Description
General Qjail Usage Tips
Files
Author

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 incremented 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 deployments 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 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. 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 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.
-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 login 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) permanently 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 restore 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 selected 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 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. 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 determine the systems RELEASE level it’s not applicable in a jailed environment. Performing a make buildworld/installworld on basejail’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 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 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).

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


.An Joe Barbish <qjail@a1poweruser.com>
Search for    or go to Top of page |  Section 8 |  Main Index


Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.