Utility for deployment of chroot environments
|start [-A] [chroot_container_name...]
|stop [-A] [chroot_container_name...]
|delete [-A] [chroot_container_name...]
|config chroot_container_name [service_name...]
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
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.
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 containers.
This utility deploys chroot containers based on a Directory tree filesystem. It
uses the host's disk space. Adding qchroot_enable="YES"
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.
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
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 populated.
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. /usr/local/etc/qchroot.local
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.
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.
Lists information about all the chroot containers inside qchroot's scope. They
are shown in ascending alphanumerically order, based on the spelling of the
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 all containers.
Start this container.
start name name name
Start this list of containers.
Stop all containers.
Stop this container.
stop name name name
Start this list of containers.
Attaches your host
console to the selected chrooted_container_name. The
command line prompt shows the container name and the path. Entering
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"
Totally removes the chroot_container_name filesystem directories
, and its entry in the administration
control file /usr/local/etc/qchroot.local/container_name
chroot_container_names to be deleted are required to be in stopped mode before
this "delete" command executes.
- 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.
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
- 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
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/src" directories which are not automatically populated by
"qchroot install". You can temporarily make the hosts
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
* 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 <firstname.lastname@example.org>