qchroot(8) BSD System Manager's Manual qchroot(8)NAMEqchroot — Utility for deployment of chroot environments
SYNOPSISqchroot 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
DESCRIPTIONqchroot 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/
BSD March 31, 2015 BSD
