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

FreeBSD Manual Pages


home | help
qchroot(8)		  BSD System Manager's Manual		    qchroot(8)

     qchroot --	Utility	for deployment of chroot environments

     qchroot install
     qchroot create  chroot_container_name
     qchroot list
     qchroot start   [-A] [chroot_container_name...]
     qchroot stop    [-A] [chroot_container_name...]
     qchroot console chroot_container_name
     qchroot delete  [-A] [chroot_container_name...]
     qchroot config  chroot_container_name [service_name...]
     qchroot version

     qchroot is	a csh script for simplified administration of chroots on a
     host system. This is a viable alternate to	jail(8)	when jail(8) is	too
     restrictive. This runs on RELEASE-9.3 and all newer RELEASES.

     The chroot	filesystem shares a single copy	of the system binaries which
     is	mounted	nullfs "read only" to the named	chroot container filesystem.
     This provides 2 levels of security	protection which is better than	chroot
     by	its self.

     You have to be logged in as root or have root permissions to use this.
     After the chroot filesystem is created and	populated with a service
     application, when started the internal chroot command will	start the
     service application contained in the chroot filesystem container.
     Issuing ps	ax" command will show you the service application is running.
     There is no host command to show which started services are from a
     chrooted filesystem.

     The qchroot utility is used to manage the qchroot environment and all the
     chroot containers inside the qchroot scope. Qchroot's administration ease
     does not evaporate	as chroot containers deployed grow beyond 2 chroot

     This utility deploys chroot containers based on a Directory tree
     filesystem. It uses the host's disk space.
     Adding qchroot_enable="YES" to the	"host's" /etc/rc.conf file, will cause
     all chroot	containers to be started when the system is booted.

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

     From the hosts view point,	it can not tell	nor does it care if a running
     task was started from a chrooted filesystem. The Network still functions
     in	the normal manner and service applications still select	network
     traffic based on port number or IP	address/port number combination	which
     the service application is	configured to listen for.

qchroot	install
     Allocates the directory structure used by the qchroot system that must be
     populated with the	same RELEASE version as	the host is running. For
     security purposes its necessary that the qchroot system 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". By default, qchroot 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	the
     original distribution files available for download	from the FreeBSD FTP

     During the	"qchroot install" process the following	directory structure is

     sharedfs contains all of the operating system's executable	libraries as
     read-only files and is mounted as an "nullfs" that	is shared between all
     the individual chroot containers. It's populated with a pristine version
     of	the operating systems binaries.	This design effectively	secures	all
     the executable files from being updated or	deleted	and also secures the
     directories containing the	executable files from having new files
     inserted by any process running inside of a chroot	container. The
     "usr/src" and "usr/ports" directories are also included, but not

     template contains the operating system configuration files. It is copied
     to	form the chroot	container filesystem.

     A single internal administration directory	is populated with information
     unique to each chroot container.

     This command can be run any time to rebuild the sharedfs and the template
     from scratch while	not disturbing the existing chroot containers.

     If	rebuilding using a newer major RELEASE,	IE: 9.3	to 10.0, then
     remember, all existing chroot containers that have	ports or packages in
     them will need them updated to versions compatible	with the new major
     RELEASE version. This means you should issue these	commands first
     "qchroot delete -A" followed by "rm -rf /usr/qchroot" to delete all the
     qchroot system filesystems, and then doing	"qchroot install" to rebuild
     the qchroot system	filesystems anew.

     If	going from a subversion	to a newer subversion within the same major
     RELEASE, IE: 10.0 to 10.1,	then there is no need to update	your installed
     ports/packages. Just do "qchroot install" to build	the qchroot system
     filesystems anew so it matches the	FreeBSD	version	running	on the host.

qchroot	create
     Creates a new chroot container inside qchroot's scope. Chroot container
     name is an	mandatory parameter.

     During the	creation process a single administration file is created for
     the container_name. IE; /usr/local/etc/qchrootl.local/container_name.

	     Chroot_container_name is an mandatory parameter. Only a single
	     chroot_container_name is valid. The chroot_container_name can
	     only contain alphanumeric,	dash, and underscore characters, all
	     numeric chroot_container_names are	invalid.
	     chroot_container_names have to be unique across the qchroot
	     scope. Just remember that you will	be typing in this
	     chroot_container_name on all the subcommands you use, so try to
	     keep the name short but meaningful.

qchroot	list
     Lists information about all the chroot containers inside qchroot's	scope.
     They are shown in ascending alphanumerically order, based on the spelling
     of	the container_name.

qchroot	[start | stop]
     Only chroot_containers with service_names can be started or stopped.
     When start	or stop	subcommand is issued WITH -A parameter,	all the
     chroot_containers under qchroot control are processed. When start or
     stop, subcommand is issued	WITH a single container_name, or with a	string
     of	space separated	container_names, "IE; name1 name2 name3" only those
     names are processed. A single line	informational message is issued	as
     each container_name is processed saying

	     Bypassed; No service configured yet
	     Start chroot completed.
	     Error; Chroot is already started.
	     Chroot is stopped.
	     Error; Chroot is already stopped.

     The function subcommands are as follows:

	     start -A	     Start all containers.
	     start name	     Start this	container.
	     start name	name name  Start this list of containers.

	     stop -A	     Stop all containers.
	     stop name	     Stop this container.
	     stop name name name   Start this list of containers.

qchroot	console
     Attaches your host	console	to the selected	chrooted_container_name. The
     command line prompt shows the container name and the path.	Entering exit
     will terminate the	console. This is intended for administration use only.
     Normally used to install ports or packages	and do other system
     customization. An example would be	to install apache22 by issuing this
     command "pkg install apache22" and	then edit its httpd.conf file.

	     Chroot_container_name is a	mandatory parameter. Only a single
	     name is valid. Use	the subcommand "list" to display list of all
	     chroot_container_names. Chroot_container must be in "stopped"

qchroot	delete
     Totally removes the chroot_container_name filesystem directories
     /usr/qchroot/chroot_container_name, and its entry in the administration
     control file /usr/local/etc/qchroot.local/container_name. The
     chroot_container_names to be deleted are required to be in	stopped	mode
     before this "delete" command executes.

     -A	     This option will delete all the chroot_containers under qchroot's

	     A single chroot_container_name or multiple	chroot_container_names
	     separated by a space are allowed.

qchroot	config
     Used to add the service application names of service applications that
     are installed in the specific chroot_container_named container.

	     This is the chroot_container_name you want	to add or change the
	     service application name to automatically start at	boot time and
	     stop at shutdown.

	     A single service_name or multiple service_names separated by a
	     space are allowed.	What ever service application you installed
	     into the chroot_container using "qchroot console" command will
	     inform you	to place a zzzz_enable="YES" parameter in the hosts
	     /etc/rc.conf file to auto start it	at boot	time. You don't	do
	     that for service applications you installed in the	chrooted
	     filesystems. The zzzz is the service_name you enter here.

	     Note: You can't start a chroot container unless it	has a
	     service_name which	means it has a service application installed
	     in	it. The	installed service application will have	a script in
	     the chroot	container at /usr/local/etc/rc.d/service_name.

qchroot	version
     This displays the version of the qchroot script.

     *	 Qchroot 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 qchroot.	The "sudo" port
	 can be	used instead of	"su" to	perform	the same function
	 if so desired.

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

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

     *	 Its a mandatory requirement of	the qchroot system that	the
	 host and the sharedfs flesystem 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, you run the "install"	subcommand again and re-install
	 with the newer	RELEASE	version	matching what is on the	host,
	 without disturbing the	existing chroot	containers.
	 If going to a newer major RELEASE, IE:	9.2 to 10.0 then remember,
	 all existing chroot containers	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: 9.2 to 9.3, then there is no need to update your
	 installed ports/packages.

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

     /usr/local/bin/qchroot		  The main work	horse script
     /usr/local/etc/rc.d/qchroot.bootime  Boot time starter script
     /usr/local/etc/qchroot.local/*	  Admin	control	files
     /usr/qchroot			  Location of qchroot filesystems

     Joe Barbish <>

BSD				March 31, 2015				   BSD

NAME | SYNOPSIS | DESCRIPTION | qchroot install | qchroot create | qchroot list | qchroot console | qchroot delete | qchroot config | qchroot version | GENERAL USAGE TIPS | FILES | AUTHOR

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

home | help