os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Whitespace-only fixes. Translators, please ignore.

Browse source
This commit is contained in:
Warren Block 2013-06-25 14:37:56 +00:00
parent eab87bb917
commit fc8d8dfa92
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=42036
1 changed files with 346 additions and 295 deletions

597
en_US.ISO8859-1/books/handbook/jails/chapter.xml
View file

@ -24,9 +24,10 @@
<para>This chapter will provide an explanation of what &os; jails
are and how to use them. Jails, sometimes referred to as an
enhanced replacement of <emphasis>chroot environments</emphasis>,
are a very powerful tool for system administrators, but their basic
usage can also be useful for advanced users.</para>
enhanced replacement of
<emphasis>chroot environments</emphasis>, are a very powerful
tool for system administrators, but their basic usage can also
be useful for advanced users.</para>
<important>
<para>Jails are a powerful tool, but they are not a security
@ -66,77 +67,79 @@
<itemizedlist>
<listitem>
<para>The &man.jail.8; manual page. This is the full reference
of the <command>jail</command> utility &mdash; the
administrative tool which can be used in &os; to start, stop,
and control &os; jails.</para>
<para>The &man.jail.8; manual page. This is the full
reference of the <command>jail</command> utility &mdash; the
administrative tool which can be used in &os; to start,
stop, and control &os; jails.</para>
</listitem>
<listitem>
<para>The mailing lists and their archives. The archives of the
&a.questions; and other mailing lists hosted by the
<para>The mailing lists and their archives. The archives of
the &a.questions; and other mailing lists hosted by the
&a.mailman.lists; already contain a wealth of material for
jails. It should always be engaging to search the archives,
or post a new question to the &a.questions.name; mailing
list.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="jails-terms">
<title>Terms Related to Jails</title>
<para>To facilitate better understanding of parts of the &os; system
related to jails, their internals and the way they interact with
the rest of &os;, the following terms are used further in this
chapter:</para>
<para>To facilitate better understanding of parts of the &os;
system related to jails, their internals and the way they
interact with the rest of &os;, the following terms are used
further in this chapter:</para>
<variablelist>
<varlistentry>
<term>&man.chroot.8; (command)</term>
<listitem>
<para>Utility, which uses &man.chroot.2; &os; system call to change
the root directory of a process and all its descendants.</para>
<para>Utility, which uses &man.chroot.2; &os; system call to
change the root directory of a process and all its
descendants.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&man.chroot.2; (environment)</term>
<listitem>
<para>The environment of processes running in
a <quote>chroot</quote>. This includes resources such as the part
of the file system which is visible, user and group IDs which are
available, network interfaces and other IPC mechanisms,
etc.</para>
<para>The environment of processes running in a
<quote>chroot</quote>. This includes resources such as
the part of the file system which is visible, user and
group IDs which are available, network interfaces and
other IPC mechanisms, etc.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&man.jail.8; (command)</term>
<listitem>
<para>The system administration utility which allows launching of
processes within a jail environment.</para>
<para>The system administration utility which allows
launching of processes within a jail environment.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>host (system, process, user, etc.)</term>
<listitem>
<para>The controlling system of a jail environment. The host system
has access to all the hardware resources available, and can
control processes both outside of and inside a jail environment.
One of the important differences of the host system from a jail is
that the limitations which apply to superuser processes inside a
jail are not enforced for processes of the host system.</para>
<para>The controlling system of a jail environment. The
host system has access to all the hardware resources
available, and can control processes both outside of and
inside a jail environment. One of the important
differences of the host system from a jail is that the
limitations which apply to superuser processes inside a
jail are not enforced for processes of the host
system.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>hosted (system, process, user, etc.)</term>
<listitem>
<para>A process, user or other entity, whose access to resources is
restricted by a &os; jail.</para>
<para>A process, user or other entity, whose access to
resources is restricted by a &os; jail.</para>
</listitem>
</varlistentry>
</variablelist>
@ -147,39 +150,39 @@
<para>Since system administration is a difficult and perplexing
task, many powerful tools were developed to make life easier for
the administrator. These tools mostly provide enhancements of some sort
to the way systems are installed, configured and maintained.
Part of the tasks which an administrator is
expected to do is to properly configure the security of a system,
so that it can continue serving its real purpose, without allowing
security violations.</para>
the administrator. These tools mostly provide enhancements of
some sort to the way systems are installed, configured and
maintained. Part of the tasks which an administrator is
expected to do is to properly configure the security of a
system, so that it can continue serving its real purpose,
without allowing security violations.</para>
<para>One of the tools which can be used to enhance the security of
a &os; system are <emphasis>jails</emphasis>. Jails were
introduced in &os;&nbsp;4.X by &a.phk;, but were greatly improved in
&os;&nbsp;5.X to make them a powerful and flexible subsystem. Their
development still goes on, enhancing their usefulness, performance, reliability,
and security.</para>
<para>One of the tools which can be used to enhance the security
of a &os; system are <emphasis>jails</emphasis>. Jails were
introduced in &os;&nbsp;4.X by &a.phk;, but were greatly
improved in &os;&nbsp;5.X to make them a powerful and flexible
subsystem. Their development still goes on, enhancing their
usefulness, performance, reliability, and security.</para>
<sect2 id="jails-what">
<title>What is a Jail</title>
<para>BSD-like operating systems have had &man.chroot.2; since the
time of 4.2BSD. The &man.chroot.8; utility can be used to
change the root directory
of a set of processes, creating a safe environment, separate
from the rest of the system. Processes created in the chrooted
environment can not access files or resources outside of it.
For that reason, compromising a service running in a chrooted
environment should not allow the attacker to compromise the
entire system. The &man.chroot.8; utility is good for easy
tasks which do not require much flexibility or complex,
advanced features. Since the inception of the
chroot concept, however, many ways have been found to escape from a
chrooted environment and, although they have been fixed in
modern versions of the &os; kernel, it was clear that
&man.chroot.2; was not the ideal solution for securing services.
A new subsystem had to be implemented.</para>
<para>BSD-like operating systems have had &man.chroot.2; since
the time of 4.2BSD. The &man.chroot.8; utility can be used to
change the root directory of a set of processes, creating a
safe environment, separate from the rest of the system.
Processes created in the chrooted environment can not access
files or resources outside of it. For that reason,
compromising a service running in a chrooted environment
should not allow the attacker to compromise the entire system.
The &man.chroot.8; utility is good for easy tasks which do not
require much flexibility or complex, advanced features. Since
the inception of the chroot concept, however, many ways have
been found to escape from a chrooted environment and, although
they have been fixed in modern versions of the &os; kernel, it
was clear that &man.chroot.2; was not the ideal solution for
securing services. A new subsystem had to be
implemented.</para>
<para>This is one of the main reasons why
<emphasis>jails</emphasis> were developed.</para>
@ -187,16 +190,16 @@
<para>Jails improve on the concept of the traditional
&man.chroot.2; environment in several ways. In a traditional
&man.chroot.2; environment, processes are only limited in the
part of the file system they can access. The rest of the system
resources (like the set of system users, the running processes,
or the networking subsystem) are shared by the chrooted
processes and the processes of the host system. Jails expand
this model by virtualizing not only access to the file system,
but also the set of users, the networking subsystem of the &os;
kernel and a few other things. A more complete set of
fine-grained controls available for tuning the access of a
jailed environment is described in <xref
linkend="jails-tuning"/>.</para>
part of the file system they can access. The rest of the
system resources (like the set of system users, the running
processes, or the networking subsystem) are shared by the
chrooted processes and the processes of the host system.
Jails expand this model by virtualizing not only access to the
file system, but also the set of users, the networking
subsystem of the &os; kernel and a few other things. A more
complete set of fine-grained controls available for tuning the
access of a jailed environment is described in
<xref linkend="jails-tuning"/>.</para>
<para>A jail is characterized by four elements:</para>
@ -211,49 +214,52 @@
<listitem>
<para>A hostname &mdash; the hostname which will be used
within the jail. Jails are mainly used for hosting network
services, therefore having a descriptive hostname for each
jail can really help the system administrator.</para>
within the jail. Jails are mainly used for hosting
network services, therefore having a descriptive hostname
for each jail can really help the system
administrator.</para>
</listitem>
<listitem>
<para>An <acronym>IP</acronym> address &mdash; this will be
assigned to the jail and cannot be changed in any way during
the jail's life span. The IP address of a jail is usually an alias address
for an existing network interface, but this is not strictly necessary.</para>
assigned to the jail and cannot be changed in any way
during the jail's life span. The IP address of a jail is
usually an alias address for an existing network
interface, but this is not strictly necessary.</para>
</listitem>
<listitem>
<para>A command &mdash; the path name of an executable to run
inside the jail. The path name is relative to the root directory of
the jail environment.</para>
<para>A command &mdash; the path name of an executable to
run inside the jail. The path name is relative to the
root directory of the jail environment.</para>
</listitem>
</itemizedlist>
<para>Apart from these, jails can have their own set of users and
their own <username>root</username> user. Naturally, the powers
of the <username>root</username> user are limited within the
jail environment and, from the point of view of the host system,
the jail <username>root</username> user is not an omnipotent user.
In addition, the <username>root</username> user of a jail is not
allowed to perform critical operations to the system outside of
the associated &man.jail.8; environment. More information
about capabilities and restrictions of the
<username>root</username> user will be discussed in <xref
linkend="jails-tuning"/> below.</para>
<para>Apart from these, jails can have their own set of users
and their own <username>root</username> user. Naturally, the
powers of the <username>root</username> user are limited
within the jail environment and, from the point of view of the
host system, the jail <username>root</username> user is not an
omnipotent user. In addition, the <username>root</username>
user of a jail is not allowed to perform critical operations
to the system outside of the associated &man.jail.8;
environment. More information about capabilities and
restrictions of the <username>root</username> user will be
discussed in
<xref linkend="jails-tuning"/> below.</para>
</sect2>
</sect1>
<sect1 id="jails-build">
<title>Creating and Controlling Jails</title>
<para>Some administrators divide jails into the following two types:
<quote>complete</quote> jails, which resemble a real &os; system,
and <quote>service</quote> jails, dedicated to one application or
service, possibly running with privileges. This is only a
conceptual division and the process of building a jail is not
affected by it. The &man.jail.8; manual page is quite clear about
the procedure for building a jail:</para>
<para>Some administrators divide jails into the following two
types: <quote>complete</quote> jails, which resemble a real &os;
system, and <quote>service</quote> jails, dedicated to one
application or service, possibly running with privileges. This
is only a conceptual division and the process of building a jail
is not affected by it. The &man.jail.8; manual page is quite
clear about the procedure for building a jail:</para>
<screen>&prompt.root; <userinput>setenv D <replaceable>/here/is/the/jail</replaceable></userinput>
&prompt.root; <userinput>mkdir -p $D</userinput> <co id="jailpath"/>
@ -265,61 +271,67 @@
<calloutlist>
<callout arearefs="jailpath">
<para>Selecting a location for a jail is the best starting point.
This is where the jail will physically reside within the file system of the jail's host.
A good choice can be <filename
<para>Selecting a location for a jail is the best starting
point. This is where the jail will physically reside within
the file system of the jail's host. A good choice can be
<filename
class="directory">/usr/jail/<replaceable>jailname</replaceable></filename>,
where <replaceable>jailname</replaceable> is the hostname
identifying the jail. The <filename
class="directory">/usr/</filename> file system usually has
enough space for the jail file system, which for <quote>complete</quote> jails is, essentially,
a replication of every file present in a default installation
of the &os; base system.</para>
identifying the jail. The
<filename class="directory">/usr/</filename> file system
usually has enough space for the jail file system, which for
<quote>complete</quote> jails is, essentially, a replication
of every file present in a default installation of the &os;
base system.</para>
</callout>
<callout arearefs="jailbuildworld">
<para>If you have already rebuilt your userland using
<command>make world</command> or <command>make buildworld</command>,
you can skip this step and install your existing userland into the
new jail.</para>
<command>make world</command> or
<command>make buildworld</command>, you can skip this step
and install your existing userland into the new jail.</para>
</callout>
<callout arearefs="jailinstallworld">
<para>This command will populate the directory subtree chosen
as jail's physical location on the file system with the
necessary binaries, libraries, manual pages and so on.</para>
necessary binaries, libraries, manual pages and so
on.</para>
</callout>
<callout arearefs="jaildistrib">
<para>The <maketarget>distribution</maketarget> target for
<application>make</application> installs every needed
configuration file. In simple words, it installs every installable file of
configuration file. In simple words, it installs every
installable file of
<filename class="directory">/usr/src/etc/</filename> to the
<filename class="directory">/etc</filename> directory of the jail
environment:
<filename class="directory">/etc</filename> directory of the
jail environment:
<filename class="directory">$D/etc/</filename>.</para>
</callout>
<callout arearefs="jaildevfs">
<para>Mounting the &man.devfs.8; file system inside a jail is
not required. On the other hand, any, or almost any
application requires access to at least one device, depending
on the purpose of the given application. It is very important
to control access to devices from inside a jail, as improper
settings could permit an attacker to do nasty things in the
jail. Control over &man.devfs.8; is managed through rulesets
which are described in the &man.devfs.8; and
&man.devfs.conf.5; manual pages.</para>
application requires access to at least one device,
depending on the purpose of the given application. It is
very important to control access to devices from inside a
jail, as improper settings could permit an attacker to do
nasty things in the jail. Control over &man.devfs.8; is
managed through rulesets which are described in the
&man.devfs.8; and &man.devfs.conf.5; manual pages.</para>
</callout>
</calloutlist>
<para>Once a jail is installed, it can be started by using the
&man.jail.8; utility. The &man.jail.8; utility takes four
mandatory arguments which are described in the <xref
linkend="jails-what"/>. Other arguments may be
specified too, e.g., to run the jailed process with the credentials of a specific
user. The <option><replaceable>command</replaceable></option> argument depends on
the type of the jail; for a <emphasis>virtual system</emphasis>,
mandatory arguments which are described in the
<xref linkend="jails-what"/>. Other arguments may be specified
too, e.g., to run the jailed process with the credentials of a
specific user. The
<option><replaceable>command</replaceable></option> argument
depends on the type of the jail; for a
<emphasis>virtual system</emphasis>,
<filename>/etc/rc</filename> is a good choice, since it will
replicate the startup sequence of a real &os; system. For a
<emphasis>service</emphasis> jail, it depends on the service or
@ -377,11 +389,11 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep
&prompt.root; <userinput>service jail stop <replaceable>www</replaceable></userinput></screen>
<para>A clean way to shut down a &man.jail.8; is not available at
the moment. This is because commands normally used to accomplish
a clean system shutdown cannot be used inside a jail. The best
way to shut down a jail is to run the following command from
within the jail itself or using the &man.jexec.8; utility from
outside the jail:</para>
the moment. This is because commands normally used to
accomplish a clean system shutdown cannot be used inside a jail.
The best way to shut down a jail is to run the following command
from within the jail itself or using the &man.jexec.8; utility
from outside the jail:</para>
<screen>&prompt.root; <userinput>sh /etc/rc.shutdown</userinput></screen>
@ -393,20 +405,22 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep
<title>Fine Tuning and Administration</title>
<para>There are several options which can be set for any jail, and
various ways of combining a host &os; system with jails, to produce
higher level applications. This section presents:</para>
various ways of combining a host &os; system with jails, to
produce higher level applications. This section
presents:</para>
<itemizedlist>
<listitem>
<para>Some of the options available for tuning the behavior and
security restrictions implemented by a jail
<para>Some of the options available for tuning the behavior
and security restrictions implemented by a jail
installation.</para>
</listitem>
<listitem>
<para>Some of the high-level applications for jail management,
which are available through the &os; Ports Collection, and can
be used to implement overall jail-based solutions.</para>
which are available through the &os; Ports Collection, and
can be used to implement overall jail-based
solutions.</para>
</listitem>
</itemizedlist>
@ -469,14 +483,14 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep
<username>root</username> inside a jail may not load or unload
&man.devfs.8; rulesets, set firewall rules, or do many other
administrative tasks which require modifications of in-kernel
data, such as setting the <varname>securelevel</varname> of the
kernel.</para>
data, such as setting the <varname>securelevel</varname> of
the kernel.</para>
<para>The base system of &os; contains a basic set of tools for
viewing information about the active jails, and attaching to a
jail to run administrative commands. The &man.jls.8; and
&man.jexec.8; commands are part of the base &os; system, and can be used
to perform the following simple tasks:</para>
&man.jexec.8; commands are part of the base &os; system, and
can be used to perform the following simple tasks:</para>
<itemizedlist>
<listitem>
@ -486,13 +500,13 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep
</listitem>
<listitem>
<para>Attach to a running jail, from its host system, and run
a command inside the jail or perform administrative tasks inside the
jail itself. This is especially useful when the
<username>root</username> user wants to cleanly shut down a
jail. The &man.jexec.8; utility can also be used to start a
shell in a jail to do administration in it; for
example:</para>
<para>Attach to a running jail, from its host system, and
run a command inside the jail or perform administrative
tasks inside the jail itself. This is especially useful
when the <username>root</username> user wants to cleanly
shut down a jail. The &man.jexec.8; utility can also be
used to start a shell in a jail to do administration in
it; for example:</para>
<screen>&prompt.root; <userinput>jexec <replaceable>1</replaceable> tcsh</userinput></screen>
</listitem>
@ -503,11 +517,12 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep
<title>High-Level Administrative Tools in the &os; Ports
Collection</title>
<para>Among the many third-party utilities for jail administration,
one of the most complete and useful is <filename
role="package">sysutils/jailutils</filename>. It is a set of
small applications that contribute to &man.jail.8; management.
Please refer to its web page for more information.</para>
<para>Among the many third-party utilities for jail
administration, one of the most complete and useful is
<filename role="package">sysutils/jailutils</filename>. It is
a set of small applications that contribute to &man.jail.8;
management. Please refer to its web page for more
information.</para>
</sect2>
</sect1>
@ -530,8 +545,8 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep
<para>This section is based upon an idea originally presented by
&a.simon; at <ulink
url="http://simon.nitro.dk/service-jails.html"></ulink>, and an
updated article written by Ken Tom
url="http://simon.nitro.dk/service-jails.html"></ulink>, and
an updated article written by Ken Tom
<email>locals@gmail.com</email>. This section illustrates how
to set up a &os; system that adds an additional layer of
security, using the &man.jail.8; feature. It is also assumed
@ -542,22 +557,22 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep
<sect3 id="jails-service-jails-design">
<title>Design</title>
<para>One of the major problems with jails is the management of
their upgrade process. This tends to be a problem because
every jail has to be rebuilt from scratch whenever it is
updated. This is usually not a problem for a single jail,
since the update process is fairly simple, but can be quite
time consuming and tedious if a lot of jails are
<para>One of the major problems with jails is the management
of their upgrade process. This tends to be a problem
because every jail has to be rebuilt from scratch whenever
it is updated. This is usually not a problem for a single
jail, since the update process is fairly simple, but can be
quite time consuming and tedious if a lot of jails are
created.</para>
<warning>
<para>This setup requires advanced experience with &os; and
usage of its features. If the presented steps below look
too complicated, it is advised to take a look at a simpler
system such as <filename
role="package">sysutils/ezjail</filename>, which provides
an easier method of administering &os; jails and is not as
sophisticated as this setup.</para>
system such as
<filename role="package">sysutils/ezjail</filename>, which
provides an easier method of administering &os; jails and
is not as sophisticated as this setup.</para>
</warning>
<para>This idea has been presented to resolve such issues by
@ -571,7 +586,8 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep
<note>
<para>Examples of services in this context are: an
<acronym>HTTP</acronym> server, a <acronym>DNS</acronym>
server, a <acronym>SMTP</acronym> server, and so forth.</para>
server, a <acronym>SMTP</acronym> server, and so
forth.</para>
</note>
<para>The goals of the setup described in this section
@ -579,79 +595,93 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep
<itemizedlist>
<listitem>
<para>Create a simple and easy to understand jail structure.
This implies <emphasis>not</emphasis> having to run a full
installworld on each and every jail.</para>
<para>Create a simple and easy to understand jail
structure. This implies <emphasis>not</emphasis> having
to run a full installworld on each and every
jail.</para>
</listitem>
<listitem>
<para>Make it easy to add new jails or remove existing
ones.</para>
</listitem>
<listitem>
<para>Make it easy to update or upgrade existing
jails.</para>
</listitem>
<listitem>
<para>Make it possible to run a customized &os;
branch.</para>
</listitem>
<listitem>
<para>Be paranoid about security, reducing as much as
possible the possibility of compromise.</para>
</listitem>
<listitem>
<para>Save space and inodes, as much as possible.</para>
</listitem>
</itemizedlist>
<para>As it has been already mentioned, this design relies
heavily on having a single master template which is read-only
(known as <application>nullfs</application>) mounted into each
jail and one read-write device per jail. A device can be a
separate physical disc, a partition, or a vnode backed
&man.md.4; device. In this example, we will use read-write
<application>nullfs</application> mounts.</para>
heavily on having a single master template which is
read-only (known as <application>nullfs</application>)
mounted into each jail and one read-write device per jail.
A device can be a separate physical disc, a partition, or a
vnode backed &man.md.4; device. In this example, we will
use read-write <application>nullfs</application>
mounts.</para>
<para>The file system layout is described in the following
list:</para>
<itemizedlist>
<listitem>
<para>Each jail will be mounted under the <filename
class="directory">/home/j</filename> directory.</para>
</listitem>
<listitem>
<para><filename class="directory">/home/j/mroot</filename> is
the template for each jail and the read-only partition for
all of the jails.</para>
</listitem>
<listitem>
<para>A blank directory will be created for each jail under
the <filename class="directory">/home/j</filename>
<para>Each jail will be mounted under the
<filename class="directory">/home/j</filename>
directory.</para>
</listitem>
<listitem>
<para>Each jail will have a <filename
class="directory">/s</filename> directory, that will be
linked to the read-write portion of the system.</para>
<para><filename class="directory">/home/j/mroot</filename>
is the template for each jail and the read-only
partition for all of the jails.</para>
</listitem>
<listitem>
<para>Each jail shall have its own read-write system that is
based upon <filename
<para>A blank directory will be created for each jail
under the <filename class="directory">/home/j</filename>
directory.</para>
</listitem>
<listitem>
<para>Each jail will have a
<filename class="directory">/s</filename> directory,
that will be linked to the read-write portion of the
system.</para>
</listitem>
<listitem>
<para>Each jail shall have its own read-write system that
is based upon <filename
class="directory">/home/j/skel</filename>.</para>
</listitem>
<listitem>
<para>Each jailspace (read-write portion of each jail) shall
be created in <filename
<para>Each jailspace (read-write portion of each jail)
shall be created in <filename
class="directory">/home/js</filename>.</para>
</listitem>
</itemizedlist>
<note>
<para>This assumes that the jails are based under the
<filename class="directory">/home</filename> partition. This
can, of course, be changed to anything else, but this change
will have to be reflected in each of the examples
<filename class="directory">/home</filename> partition.
This can, of course, be changed to anything else, but this
change will have to be reflected in each of the examples
below.</para>
</note>
<!-- Insert an image or drawing here to illustrate the example. -->
@ -660,37 +690,40 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep
<sect3 id="jails-service-jails-template">
<title>Creating the Template</title>
<para>This section will describe the steps needed to create the
master template that will be the read-only portion for the
jails to use.</para>
<para>This section will describe the steps needed to create
the master template that will be the read-only portion for
the jails to use.</para>
<para>It is always a good idea to update the &os; system to the
latest -RELEASE branch. Check the corresponding Handbook
<ulink url="&url.books.handbook;/makeworld.html">Chapter</ulink>
<para>It is always a good idea to update the &os; system to
the latest -RELEASE branch. Check the corresponding
Handbook <ulink
url="&url.books.handbook;/makeworld.html">Chapter</ulink>
to accomplish this task. In the case the update is not
feasible, the buildworld will be required in order to be able
to proceed. Additionally, the <filename
role="package">sysutils/cpdup</filename> package will be
required. We will use the &man.portsnap.8; utility to
download the &os; Ports Collection. The Handbook <ulink
url="&url.books.handbook;/portsnap.html">Portsnap Chapter</ulink>
is always good reading for newcomers.</para>
feasible, the buildworld will be required in order to be
able to proceed. Additionally, the
<filename role="package">sysutils/cpdup</filename> package
will be required. We will use the &man.portsnap.8; utility
to download the &os; Ports Collection. The Handbook
<ulink url="&url.books.handbook;/portsnap.html">Portsnap
Chapter</ulink> is always good reading for
newcomers.</para>
<procedure>
<step>
<para>First, create a directory structure for the read-only
file system which will contain the &os; binaries for our
jails, then change directory to the &os; source tree and
install the read-only file system to the jail
template:</para>
<para>First, create a directory structure for the
read-only file system which will contain the &os;
binaries for our jails, then change directory to the
&os; source tree and install the read-only file system
to the jail template:</para>
<screen>&prompt.root; <userinput>mkdir /home/j /home/j/mroot</userinput>
&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make installworld DESTDIR=/home/j/mroot</userinput></screen>
</step>
<step>
<para>Next, prepare a &os; Ports Collection for the jails as
well as a &os; source tree, which is required for
<para>Next, prepare a &os; Ports Collection for the jails
as well as a &os; source tree, which is required for
<application>mergemaster</application>:</para>
<screen>&prompt.root; <userinput>cd /home/j/mroot</userinput>
@ -698,6 +731,7 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep
&prompt.root; <userinput>portsnap -p /home/j/mroot/usr/ports fetch extract</userinput>
&prompt.root; <userinput>cpdup /usr/src /home/j/mroot/usr/src</userinput></screen>
</step>
<step>
<para>Create a skeleton for the read-write portion of the
system:</para>
@ -709,23 +743,26 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep
&prompt.root; <userinput>mv var /home/j/skel</userinput>
&prompt.root; <userinput>mv root /home/j/skel</userinput></screen>
</step>
<step>
<para>Use <application>mergemaster</application> to install
missing configuration files. Then get rid of the extra
directories that <application>mergemaster</application>
creates:</para>
<para>Use <application>mergemaster</application> to
install missing configuration files. Then get rid of
the extra directories that
<application>mergemaster</application> creates:</para>
<screen>&prompt.root; <userinput>mergemaster -t /home/j/skel/var/tmp/temproot -D /home/j/skel -i</userinput>
&prompt.root; <userinput>cd /home/j/skel</userinput>
&prompt.root; <userinput>rm -R bin boot lib libexec mnt proc rescue sbin sys usr dev</userinput></screen>
</step>
<step>
<para>Now, symlink the read-write file system to the
read-only file system. Please make sure that the symlinks
are created in the correct <filename
class="directory">s/</filename> locations. Real
directories or the creation of directories in the wrong
locations will cause the installation to fail.</para>
read-only file system. Please make sure that the
symlinks are created in the correct
<filename class="directory">s/</filename> locations.
Real directories or the creation of directories in the
wrong locations will cause the installation to
fail.</para>
<screen>&prompt.root; <userinput>cd /home/j/mroot</userinput>
&prompt.root; <userinput>mkdir s</userinput>
@ -738,6 +775,7 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep
&prompt.root; <userinput>ln -s s/tmp tmp</userinput>
&prompt.root; <userinput>ln -s s/var var</userinput></screen>
</step>
<step>
<para>As a last step, create a generic
<filename>/home/j/skel/etc/make.conf</filename> with its
@ -745,7 +783,6 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep
<programlisting>WRKDIRPREFIX?= /s/portbuild</programlisting>
<para>Having <literal>WRKDIRPREFIX</literal> set up this
way will make it possible to compile &os; ports inside
each jail. Remember that the ports directory is part of
@ -761,16 +798,16 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep
<para>Now that we have a complete &os; jail template, we can
setup and configure the jails in
<filename>/etc/rc.conf</filename>. This example demonstrates
the creation of 3 jails: <quote>NS</quote>,
<filename>/etc/rc.conf</filename>. This example
demonstrates the creation of 3 jails: <quote>NS</quote>,
<quote>MAIL</quote> and <quote>WWW</quote>.</para>
<procedure>
<step>
<para>Put the following lines into the
<filename>/etc/fstab</filename> file, so that the
read-only template for the jails and the read-write space
will be available in the respective jails:</para>
read-only template for the jails and the read-write
space will be available in the respective jails:</para>
<programlisting>/home/j/mroot /home/j/ns nullfs ro 0 0
/home/j/mroot /home/j/mail nullfs ro 0 0
@ -786,12 +823,14 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep
&man.dump.8;. We do not want
<application>fsck</application> to check
<application>nullfs</application> mounts or
<application>dump</application> to back up the read-only
nullfs mounts of the jails. This is why they are marked
with <quote>0&nbsp;0</quote> in the last two columns of
each <filename>fstab</filename> entry above.</para>
<application>dump</application> to back up the
read-only nullfs mounts of the jails. This is why
they are marked with <quote>0&nbsp;0</quote> in the
last two columns of each <filename>fstab</filename>
entry above.</para>
</note>
</step>
<step>
<para>Configure the jails in
<filename>/etc/rc.conf</filename>:</para>
@ -815,34 +854,37 @@ jail_www_devfs_enable="YES"</programlisting>
<warning>
<para>The reason why the
<varname>jail_<replaceable>name</replaceable>_rootdir</varname>
variable is set to <filename
class="directory">/usr/home</filename> instead of
<filename class="directory">/home</filename> is that the
physical path of the <filename
class="directory">/home</filename> directory on a
default &os; installation is <filename
class="directory">/usr/home</filename>. The
variable is set to
<filename class="directory">/usr/home</filename>
instead of
<filename class="directory">/home</filename> is that
the physical path of the
<filename class="directory">/home</filename> directory
on a default &os; installation is
<filename class="directory">/usr/home</filename>. The
<varname>jail_<replaceable>name</replaceable>_rootdir</varname>
variable must <emphasis>not</emphasis> be set to a path
which includes a symbolic link, otherwise the jails will
refuse to start. Use the &man.realpath.1; utility to
determine a value which should be set to this variable.
Please see the &os;-SA-07:01.jail Security Advisory for
more information.</para>
variable must <emphasis>not</emphasis> be set to a
path which includes a symbolic link, otherwise the
jails will refuse to start. Use the &man.realpath.1;
utility to determine a value which should be set to
this variable. Please see the &os;-SA-07:01.jail
Security Advisory for more information.</para>
</warning>
</step>
<step>
<para>Create the required mount points for the read-only
file system of each jail:</para>
<screen>&prompt.root; <userinput>mkdir /home/j/ns /home/j/mail /home/j/www</userinput></screen>
</step>
<step>
<para>Install the read-write template into each jail. Note
the use of <filename
role="package">sysutils/cpdup</filename>, which helps to
ensure that a correct copy is done of each
directory:</para>
<para>Install the read-write template into each jail.
Note the use of
<filename role="package">sysutils/cpdup</filename>,
which helps to ensure that a correct copy is done of
each directory:</para>
<!-- keramida: Why is cpdup required here? Doesn't cpio(1)
already include adequate functionality for performing this
job *and* have the advantage of being part of the base
@ -853,6 +895,7 @@ jail_www_devfs_enable="YES"</programlisting>
&prompt.root; <userinput>cpdup /home/j/skel /home/js/mail</userinput>
&prompt.root; <userinput>cpdup /home/j/skel /home/js/www</userinput></screen>
</step>
<step>
<para>In this phase, the jails are built and prepared to
run. First, mount the required file systems for each
@ -878,8 +921,8 @@ jail_www_devfs_enable="YES"</programlisting>
jail, add new users or configure daemons. The
<literal>JID</literal> column indicates the jail
identification number of each running jail. Use the
following command in order to perform administrative tasks in
the jail whose <literal>JID</literal> is 3:</para>
following command in order to perform administrative tasks
in the jail whose <literal>JID</literal> is 3:</para>
<screen>&prompt.root; <userinput>jexec 3 tcsh</userinput></screen>
</sect3>
@ -888,13 +931,14 @@ jail_www_devfs_enable="YES"</programlisting>
<title>Upgrading</title>
<para>In time, there will be a need to upgrade the system to a
newer version of &os;, either because of a security issue, or
because new features have been implemented which are useful
for the existing jails. The design of this setup provides an
easy way to upgrade existing jails. Additionally, it
minimizes their downtime, as the jails will be brought down
only in the very last minute. Also, it provides a way to roll
back to the older versions should any problems occur.</para>
newer version of &os;, either because of a security issue,
or because new features have been implemented which are
useful for the existing jails. The design of this setup
provides an easy way to upgrade existing jails.
Additionally, it minimizes their downtime, as the jails will
be brought down only in the very last minute. Also, it
provides a way to roll back to the older versions should any
problems occur.</para>
<procedure>
<step>
@ -910,13 +954,14 @@ jail_www_devfs_enable="YES"</programlisting>
&prompt.root; <userinput>cpdup /usr/src usr/src</userinput>
&prompt.root; <userinput>mkdir s</userinput></screen>
<para>The <maketarget>installworld</maketarget> run creates
a few unnecessary directories, which should be
<para>The <maketarget>installworld</maketarget> run
creates a few unnecessary directories, which should be
removed:</para>
<screen>&prompt.root; <userinput>chflags -R 0 var</userinput>
&prompt.root; <userinput>rm -R etc var root usr/local tmp</userinput></screen>
</step>
<step>
<para>Recreate the read-write symlinks for the master file
system:</para>
@ -929,11 +974,13 @@ jail_www_devfs_enable="YES"</programlisting>
&prompt.root; <userinput>ln -s s/tmp tmp</userinput>
&prompt.root; <userinput>ln -s s/var var</userinput></screen>
</step>
<step>
<para>The right time to stop the jails is now:</para>
<screen>&prompt.root; <userinput>service jail stop</userinput></screen>
</step>
<step>
<para>Unmount the original file systems:</para>
<!-- keramida: Shouldn't we suggest a short script-based
@ -948,29 +995,33 @@ jail_www_devfs_enable="YES"</programlisting>
&prompt.root; <userinput>umount /home/j/www</userinput></screen>
<note>
<para>The read-write systems are attached to the read-only
system (<filename class="directory">/s</filename>) and
must be unmounted first.</para>
<para>The read-write systems are attached to the
read-only system
(<filename class="directory">/s</filename>) and must
be unmounted first.</para>
</note>
</step>
<step>
<para>Move the old read-only file system and replace it with
the new one. This will serve as a backup and archive of the
old read-only file system should something go wrong. The
naming convention used here corresponds to when a new
read-only file system has been created. Move the original
&os; Ports Collection over to the new file system to save
some space and inodes:</para>
<para>Move the old read-only file system and replace it
with the new one. This will serve as a backup and
archive of the old read-only file system should
something go wrong. The naming convention used here
corresponds to when a new read-only file system has been
created. Move the original &os; Ports Collection over
to the new file system to save some space and
inodes:</para>
<screen>&prompt.root; <userinput>cd /home/j</userinput>
&prompt.root; <userinput>mv mroot mroot.20060601</userinput>
&prompt.root; <userinput>mv mroot2 mroot</userinput>
&prompt.root; <userinput>mv mroot.20060601/usr/ports mroot/usr</userinput></screen>
</step>
<step>
<para>At this point the new read-only template is ready, so
the only remaining task is to remount the file systems and
start the jails:</para>
<para>At this point the new read-only template is ready,
so the only remaining task is to remount the file
systems and start the jails:</para>
<screen>&prompt.root; <userinput>mount -a</userinput>
&prompt.root; <userinput>service jail start</userinput></screen>