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

FreeBSD Manual Pages


home | help
quail-howto(8)		User's Supplementary Documents		quail-howto(8)

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

     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

     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

     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)

     Joe Barbish <>

BSD				 July 22, 2010				   BSD


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

home | help