Quick Navigator

Search Site

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

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  QJAIL-HOWTO (8)


qjail-howto - Details explaining how to use qjail to quickly build a jail system using static IP address and LAN IP addresses.


Scenario Description
Static Versus Dynamic Ip Address
Domain Names
Technical Overview
Basic Host Lan Config Setup
Jail Config Setup Using Qjail


This howto will strive to explain how the qjail utility is used in a real world application using jails that utilize both static public routable IP addresses assigned by the ISP and private LAN jails that have access to both the public internet and a internal private LAN. Utilizing a approach that fills in the blanks of how all the network separate functions fit together.


Please keep in mind that all this is fictitious, complete fake. For the purpose of this discussion, we are an County Jobs Service Center. People are referred to us from Social Services for computer training as csh script, html and php programmers. In addition Job seekers can search the jobs offered by employers through the County Unemployment Department web site. We host the County and City email systems, as well as information only websites describing the departments in the City and the County.

In the County Jobs Service Center building we have a room with 20 desktop computers running MS/Windows7 for use by job applicants who are taught interview skills by taking Computer assisted learning videos and another room with 20 desktop computers running MS/Windows7 for computer education. There is another 45 PC’s spread across the 3 floors of the building located at County employee desks. All 85 PC’s are cabled through switches and WiFi routers to the FreeBSD host. There are WiFi routers on each floor for people who have County issued laptops used for field work. A description of the hardware is not important here.

The qjail utility is the only vehicle used for administration of our jail environment. The port version of qjail is always the current version and most times is newer than what the package system offers.


There is a big difference between the two in how they get configured on the host system.

Static IP address are only assigned by the ISP for Business Class Internet service. The IP addresses assigned are public routable and permanent. The ISP does not provide any auto configuration services. The host configuration files have to be manually configured. The ISP will convey the following information;

List of the assigned static IP addresses that will need /etc/rc.conf ifconfig statements written to enable their usage. The fully qualified domain name of their DNS server plus the 2 IP addresses of their DNS servers. This info is used to populate /etc/resolv.conf.

Dynamic IP addresses are assigned as a single IP address by the ISP for Home Class Internet service. The IP address assigned is public routable. Home Class Internet service is much cheaper than Business Class. Don’t be fooled by who uses Home Class internet service. Many small to medium sized businesses have this type of service. Dynamic means the ISP provides auto configuration through DHCP and that the assigned IP address can change on you while in use. The ISP can reconfigure their network on the fly to use a different block of network IP address or change the DSN IP addresses. The /etc/rc.conf ifconfig_rl0="DHCP" statement will automatically handle this change on the fly transparently.

While were talking about IP addresses, per RFC 1918, there are groups of IP address ranges reserved for private networks that will never be connected to the public internet. These are intended for Local Area Networks. They are not routable on the public Internet without first being NATed. - - -


Domain names have to be registered in the country where they are located and a yearly fee is charged. The domain name is linked to your static IP address and this information is distributed to public Internet DNS servers so users on the internet can put your fully qualified domain name in the URL field of their web browser and find it’s way to the Business’s website.

If you used a dynamic IP address to link to your domain name then when the dynamic IP address changes the linked domain name no longer points to your host and all Internet traffic stops. Now there are solutions to address this problem. Some domain name registers, and companies that host domain names, offer services where a program is run on the host that watches for dynamic IP changes and then updates the linked IP address of the domain name with the new dynamic IP address when a change occurs. Using this technique will keep your domain name pointing at your host.


Our domain name register hosts our domain names. The ISP assigned us 10 static IP addresses. We are only going to talk about six of them to demonstrate how they are used with jails.

The host only has 3 services running on it, SSH, DHCP and IPFILTER firewall. The firewall blocks public Internet access to SSH. SSH is only allowed to be used over the LAN. Only Tech Support personal have user accounts on the host and can only SSH into the host from a LAN PC. DHCP is what issues private LAN IP address to LAN PC’s as they power up. All the WiFi routers have their internal NAT function disabled so as not to interfere with the host DHCP IP address assignments and the IPFILTER firewall NAT function.

Name of NIC facing the public internet xl0
Public routable static IP address 73.x.97.50

ISP’s DNS search name
ISP’s 2 IP addresses of there DNS servers 73.x.95.1

Domain names and their linked IP addresses -> 73.x.97.51 -> 73.x.97.52 -> 73.x.97.53 -> 73.x.97.54

Name of NIC facing the private LAN rl0
LAN IP address means through
LAN IP address assigned to host’s DHCP through
LAN IP address reserved for jails through


It’s assumed that the DHCP port was previous installed on the host.

Place these in the hosts /etc/rc.conf
ifconfig_xl0="inet 73.x.97.50 broadcast 73.x.97.59"
ifconfig_rl0="inet netmask 0xffffff00"



Place these in the hosts /etc/resolv.conf
nameserver 173.xx.195.1
nameserver 173.xx.195.2

Add these to /usr/local/etc/dhcpd.conf
option domain-name "";
option domain-name-servers 73.x.95.1 73.x.95.2;
subnet netmask {
option routers;}

Add these to /etc/ipnat.rules
# NOTE: xl0 is the interface facing the public internet
# Provide special NAT services for FTP from LAN users.
map xl0 -> 0/32 proxy port 21 ftp/tcp
# Provide special NAT services for FTP from gateway system.
map xl0 -> 0/32 proxy port 21 ftp/tcp
# Provide Normal NAT services for LAN users.
map xl0 -> 0/32

Put these in /etc/ipf.rules.script
# No restrictions on Inside Lan Interface for private network
pass in quick on rl0 all
pass out quick on rl0 all
# No restrictions on Loopback Interface
pass in quick on lo0 all
pass out quick on lo0 all
# No restrictions on external Interface facing public Internet
pass in quick on xl0 all
pass out quick on xl0 all
# Create your own rules per handbook IPFILTER firewall section

Now if you have your network cabled correctly, the host DHCP server will assign a 10.0.10.??? IP address to each PC when they are powered on. Each PC will have Internet access if your firewall NAT rules are correct. This is a normal LAN configuration.


Step 1. Install the qjail environment
qjail install
qjail update -p will perform a portsnap which downloads the complete
port tree which is shared between all jails. This is
an optional step and not necessary if only using the
port packages to install software in all the jails.

Step 2. Create 2 directory tree type jails accessible from the public Internet, one for the City info website and one for the County info web site. These jails will have SSH enabled so Tech Support personal can install the package version of apache and the html application on the 2 web server jails.

qjail create -n xl0 -f ssh-default www-city 73.x.97,51,

This will create a directory tree type jail and bind the 2 IP address to the NIC facing the public internet. When the jail is started, aliases will automatically be created on the NIC name contained in the -n option and automatically removed when the jail is stopped. The jails name will be www-city. The -f option uses the ssh-default flavor that creates a user account in the jail with a login ID/PW of qjail. From any LAN MS/Windows PC can use putty to target IP address and login to that jail.

qjail list Lists status of all jails
qjail list www-city Only list status of this jail
qjail start www-city Start just this jail

qjail console www-city Will open a root console in that jail.
Then execute pkg_add -r apache22 to
install the web server software.
Enter "exit" to close console.

An alternate method would be to use "putty" and login to the jail and once logged in issue "su" then pkg_add -r apache22 to install the web server software.

qjail create -n xl0 -c www-county 73.x.97.52,

This is the same as the www-city jail, except this time the -c option stages a pw adduser command using the jail name as the ID/PW that will get executed the first time the jail is started.

qjail start www-county This executes the staged adduser command
and enables SSH in the jail.

qjail restart www-county Will stop and start the jail activating
SSH from this point on.

This jail can be customized using either of the 2 methods shown above.

Step 3. Create 2 directory tree type jails accessible from the public Internet, one for the City email server, and one for the County email server. These jails will have SSH enabled so Tech Support personal can install the package version of postfix on the 2 email jails.

qjail create -n xl0 -c smtp-city 73.x.97.53,

qjail start smtp-city This executes the staged adduser command
and enables SSH in the jail.

qjail restart smtp-city Will stop and start the jail activating
SSH from this point on.

This jail can be customized using either of the 2 methods shown above. But this time doing pkg_add -r postfix.

qjail stop smtp-city Only stopped jails can be archived.
qjail archive smtp-city This creates an archive of this jail. Do
this after postfix is installed but
before it’s configured or user accounts

qjail create -n xl0 -c -a smtp-city smtp-county 73.x.97.54,

This will create the new jail using the smtp-city archive as a template resulting in the new jail already having postfix installed.

qjail start smtp-county This executes the staged adduser command
and enables SSH in the jail.

qjail restart smtp-county Will stop and start the jail activating
SSH from this point on.

This jail can be customized using either of the 2 methods shown above.

Step 4. Create 2 additional jails, one for the County Unemployment Department website, and one for the Computer assisted learning web site. Both of these jail run apache/php/mysql and are loaded with an proprietary application that uses mysql for storing entered application data. To put a upper limit on the disk space consumed by these applications an sparse file image type jail will be used. For proprietary reasons these jails can only be accessible from the LAN and no ssh access is allowed to these jails. Tech Support personal can ssh from the LAN into the host and use "qjail console" command to gain access to these jails to install the package version of apache and mysql and the ports version of php because php needs the "apache module" compiled into it.

qjail create -n rl0 -i -s 5g www-jobsdb

This will create an image jail 5 gig in size with no SSH support.

qjail start www-jobsdb
qjail console www-jobsdb Only the host console can gain access to
the jail as root. From here the apache,
php and mysql ports get installed.
qjail stop www-jobsdb Only stopped jails can be archived.
qjail archive www-jobsdb After installing the software and before
installing the proprietary html
application do a archive because the
Computer assisted learning jail and the
computer training class jails need this
same group of software.

qjail create -n rl0 -a www-jobsdb -i -s 5g www-cal

This just created the Computer assisted learning jail.

qjail start www-cal
qjail console www-cal Only the host console can gain access to the
jail as root. From here the proprietary html
application and mysql db are loaded.

So the jail’s IP address don’t have to be used to access the website we make a entry in the /etc/hosts file relating the jails IP address to it’s LAN domain name lanjobsdb lan-cal

Step 5. We also need to create jails for the computer training class. The maximum number of students per session is 60. Each student gets there own jail to work in. These students use "putty" a free SSH MS/Windows application to login over SSH to their jail. The jails IP address is the only info "putty" needs to get a login prompt. Students learn to write csh scripts, html web sites and html/php/mysql web sites. These jails are only accessible through the LAN using SSH. Because the computer training class cycle through 4 session per year, at the end of each session all the computer training class jails are deleted and recreated from a standard class-template each session. To further protect the host from student abuse image jails will be created putting a maximum on the amount of disk space the class jails can grow to consume.

qjail -n rl0 -a www-jobsdb class-template
qjail start class-template
qjail console class-template Install additional software used
by students phpmyadmin unix2dos ytree.
qjail stop class-template
qjail archive class-template
qjail delete class-template

Note: Because of wrap around the following is shown on 2 lines but
would be issued on the hosts command line as a single command.

qjail create -n rl0 -a class-template -i -s 50m -D 60 -I -C

This creates 60 image type jails appending a -00 counter suffix on the jail name while at the same time bumping the last octal of the IP address by one. At the same time SSH is enabled in the jail and a user account using the jailname as ID/PW is created.

Note: The wildcard symbol "=" will consider text to it’s left as a prefix, all qjail commands can use the prefix wildcard symbol "=" to cause the command to match on all jailnames having that prefix.

qjail start course101= Will start all the just created jails.
This first start of the new jails enables
SSH in the jail.

qjail restart course101= Will stop the jails and then start all
the jails. This has to be done to activate
SSH in the jails from this point on.

qjail config -r norun course101= Will set the status.

When students register for the class they are given the login ID/PW of the jail being assigned to them. Then the teacher changes the status to run. First thing student does is change the password of his jail account.

qjail config -r run course101-15 Or whatever the next free jail is.
qjail start course101-15 The jail runs 24/7.
qjail list Will show you the status of all the jails.

qjail delete course101= Will delete all the jail at end of course.

Every week day at midnight a cron script is run to archive all the class jails. This way a jail can be restored to last night’s status if the student somehow managed to kill his jail.

qjail stop course101=
qjail archive course101=
qjail start course101=

To restore a jail do this
qjail stop course101-43
qjail delete course101-43
qjail restore course101-43
qjail start course101-43

Lets say the student forgets their password. The teacher uses SSH to login into the host, does a qjail console command for the students jailname. Deletes the students account and recreates it again.

Lets say the www-jobsdb jail consumes all of its allocated disk space and additional jail image disk space needs to be allocated.
qjail stop www-jobsdb
qjail archive www-jobsdb
qjail delete www-jobsdb
qjail create -n rl0 -a www-jobsdb -i -s 15g www-jobsdb
Here we increased the size of the image file from the original 5g to
15g and everything else stays the same. No content data is lost.

A more conservative method could by done this way.
qjail stop www-jobsdb
qjail archive www-jobsdb
qjail config -r norun -n www-jobsdb-old www-jobsdb
qjail config -I -c null www-jobsdb-old
qjail create -n rl0 -a www-jobsdb -i -s 15g www-jobsdb

The above qjail config command put the jail in norun status, gives the jail a new name, new IP address, unbinds the jail from the NIC. In short the jail is present in the jail environment but is dead. Just as easily as it was made dead it can also be brought back to life.


qjail(8), qjail.conf(8), qjail-intro(8)


.An Joe Barbish <>
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.