Whitespace-only fixes. Translators, please ignore.

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

View file

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