NAME

qchroot —

Utility for deployment of chroot environments

SYNOPSIS

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

DESCRIPTION

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 containers.

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 servers.

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

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 populated.

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. /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.

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: 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: 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" status.

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 control.
chroot_container_name: 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.

chroot_container_name: 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.
service_name: 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.

GENERAL USAGE TIPS

* 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.

FILES

/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

AUTHOR

Joe Barbish <qchroot1@a1poweruser.com>
http://qchroot.sourceforge.net/