1.\"
2.\" Copyright (c) 2000, 2003 Robert N. M. Watson
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\" notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\" notice, this list of conditions and the following disclaimer in the
12.\" documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
26.\"
27.\" ----------------------------------------------------------------------------
28.\" "THE BEER-WARE LICENSE" (Revision 42):
29.\" <phk@FreeBSD.ORG> wrote this file. As long as you retain this notice you
30.\" can do whatever you want with this stuff. If we meet some day, and you think
31.\" this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp
32.\" ----------------------------------------------------------------------------
33.\"
34.\" $FreeBSD: head/usr.sbin/jail/jail.8 131500 2004-07-02 23:13:00Z ru $
35.\"
36.Dd April 8, 2003
37.Dt JAIL 8
38.Os
39.Sh NAME
40.Nm jail
41.Nd "imprison process and its descendants"
42.Sh SYNOPSIS
43.Nm
44.Op Fl i
45.Op Fl u Ar username | Fl U Ar username
46.Ar path hostname ip-number command ...
47.Sh DESCRIPTION
48The
49.Nm
50utility imprisons a process and all future descendants.
51.Pp
52The options are as follows:
53.Bl -tag -width ".Fl u Ar username"
54.It Fl i
55Output the jail identifier of the newly created jail.
56.It Fl u Ar username
57The user name from host environment as whom the
58.Ar command
59should run.
60.It Fl U Ar username
61The user name from jailed environment as whom the
62.Ar command
63should run.
64.It Ar path
65Directory which is to be the root of the prison.
66.It Ar hostname
67Hostname of the prison.
68.It Ar ip-number
69IP number assigned to the prison.
70.It Ar command
71Pathname of the program which is to be executed.
72.El
73.Pp
74Jails are typically set up using one of two philosophies: either to
75constrain a specific application (possibly running with privilege), or
76to create a
77.Dq "virtual system image"
78running a variety of daemons and services.
79In both cases, a fairly complete file system install of
80.Fx
81is
82required, so as to provide the necessary command line tools, daemons,
83libraries, application configuration files, etc.
84However, for a virtual server configuration, a fair amount of
85additional work is required so as to configure the
86.Dq boot
87process.
88This manual page documents the configuration steps necessary to support
89either of these steps, although the configuration steps may be
90refined based on local requirements.
91.Pp
92Please see the
93.Xr jail 2
94man page for further details.
95.Sh EXAMPLES
96.Ss "Setting up a Jail Directory Tree"
97This example shows how to set up a jail directory tree
98containing an entire
99.Fx
100distribution:
101.Bd -literal
102D=/here/is/the/jail
103cd /usr/src
104mkdir -p $D
105make world DESTDIR=$D
106cd etc
107make distribution DESTDIR=$D
108mount_devfs devfs $D/dev
109cd $D
110ln -sf dev/null kernel
111.Ed
112.Pp
113NOTE: It is important that only appropriate device nodes in devfs be
114exposed to a jail; access to disk devices in the jail may permit processes
115in the jail to bypass the jail sandboxing by modifying files outside of
116the jail.
117See
118.Xr devfs 8
119for information on how to use devfs rules to limit access to entries
120in the per-jail devfs.
121.Pp
122In many cases this example would put far more in the jail than needed.
123In the other extreme case a jail might contain only one file:
124the executable to be run in the jail.
125.Pp
126We recommend experimentation and caution that it is a lot easier to
127start with a
128.Dq fat
129jail and remove things until it stops working,
130than it is to start with a
131.Dq thin
132jail and add things until it works.
133.Ss "Setting Up a Jail"
134Do what was described in
135.Sx "Setting Up a Jail Directory Tree"
136to build the jail directory tree.
137For the sake of this example, we will
138assume you built it in
139.Pa /data/jail/192.168.11.100 ,
140named for the jailed IP address.
141Substitute below as needed with your
142own directory, IP address, and hostname.
143.Ss "Setting up the Host Environment"
144First, you will want to set up your real system's environment to be
145.Dq jail-friendly .
146For consistency, we will refer to the parent box as the
147.Dq "host environment" ,
148and to the jailed virtual machine as the
149.Dq "jail environment" .
150Since jail is implemented using IP aliases, one of the first things to do
151is to disable IP services on the host system that listen on all local
152IP addresses for a service.
153If a network service is present in the host environment that binds all
154available IP addresses rather than specific IP addresses, it may service
155requests sent to jail IP addresses.
156This means changing
157.Xr inetd 8
158to only listen on the
159appropriate IP address, and so forth.
160Add the following to
161.Pa /etc/rc.conf
162in the host environment:
163.Bd -literal -offset indent
164sendmail_enable="NO"
165inetd_flags="-wW -a 192.168.11.23"
166rpcbind_enable="NO"
167.Ed
168.Pp
169.Li 192.168.11.23
170is the native IP address for the host system, in this example.
171Daemons that run out of
172.Xr inetd 8
173can be easily set to use only the specified host IP address.
174Other daemons
175will need to be manually configured\(emfor some this is possible through
176the
177.Xr rc.conf 5
178flags entries; for others it is necessary to modify per-application
179configuration files, or to recompile the applications.
180The following frequently deployed services must have their individual
181configuration files modified to limit the application to listening
182to a specific IP address:
183.Pp
184To configure
185.Xr sshd 8 ,
186it is necessary to modify
187.Pa /etc/ssh/sshd_config .
188.Pp
189To configure
190.Xr sendmail 8 ,
191it is necessary to modify
192.Pa /etc/mail/sendmail.cf .
193.Pp
194For
195.Xr named 8 ,
196it is necessary to modify
197.Pa /etc/namedb/named.conf .
198.Pp
199In addition, a number of services must be recompiled in order to run
200them in the host environment.
201This includes most applications providing services using
202.Xr rpc 3 ,
203such as
204.Xr rpcbind 8,
205.Xr nfsd 8 ,
206and
207.Xr mountd 8 .
208In general, applications for which it is not possible to specify which
209IP address to bind should not be run in the host environment unless they
210should also service requests sent to jail IP addresses.
211Attempting to serve
212NFS from the host environment may also cause confusion, and cannot be
213easily reconfigured to use only specific IPs, as some NFS services are
214hosted directly from the kernel.
215Any third-party network software running
216in the host environment should also be checked and configured so that it
217does not bind all IP addresses, which would result in those services' also
218appearing to be offered by the jail environments.
219.Pp
220Once
221these daemons have been disabled or fixed in the host environment, it is
222best to reboot so that all daemons are in a known state, to reduce the
223potential for confusion later (such as finding that when you send mail
224to a jail, and its sendmail is down, the mail is delivered to the host,
225etc.).
226.Ss "Configuring the Jail"
227Start any jail for the first time without configuring the network
228interface so that you can clean it up a little and set up accounts.
229As
230with any machine (virtual or not) you will need to set a root password, time
231zone, etc.
232Some of these steps apply only if you intend to run a full virtual server
233inside the jail; others apply both for constraining a particular application
234or for running a virtual server.
235.Pp
236Start a shell in the jail:
237.Pp
238.Dl "jail /data/jail/192.168.11.100 testhostname 192.168.11.100 /bin/sh"
239.Pp
240Assuming no errors, you will end up with a shell prompt within the jail.
241You can now run
242.Pa /usr/sbin/sysinstall
243and do the post-install configuration to set various configuration options,
244or perform these actions manually by editing
245.Pa /etc/rc.conf ,
246etc.
247.Pp
248.Bl -bullet -offset indent -compact
249.It
250Create an empty
251.Pa /etc/fstab
252to quell startup warnings about missing fstab (virtual server only)
253.It
254Disable the port mapper
255.Pa ( /etc/rc.conf :
256.Li rpcbind_enable="NO" )
257(virtual server only)
258.It
259Run
260.Xr newaliases 1
261to quell
262.Xr sendmail 8
263warnings.
264.It
265Disable interface configuration to quell startup warnings about
266.Xr ifconfig 8
267.Pq Li network_interfaces=""
268(virtual server only)
269.It
270Configure
271.Pa /etc/resolv.conf
272so that name resolution within the jail will work correctly
273.It
274Set a root password, probably different from the real host system
275.It
276Set the timezone
277.It
278Add accounts for users in the jail environment
279.It
280Install any packages the environment requires
281.El
282.Pp
283You may also want to perform any package-specific configuration (web servers,
284SSH servers, etc), patch up
285.Pa /etc/syslog.conf
286so it logs as you would like, etc.
287If you are not using a virtual server, you may wish to modify
288.Xr syslogd 8
289in the host environment to listen on the syslog socket in the jail
290environment; in this example, the syslog socket would be stored in
291.Pa /data/jail/192.168.11.100/var/run/log .
292.Pp
293Exit from the shell, and the jail will be shut down.
294.Ss "Starting the Jail"
295You are now ready to restart the jail and bring up the environment with
296all of its daemons and other programs.
297If you are running a single application in the jail, substitute the
298command used to start the application for
299.Pa /etc/rc
300in the examples below.
301To start a virtual server environment,
302.Pa /etc/rc
303is run to launch various daemons and services.
304To do this, first bring up the
305virtual host interface, and then start the jail's
306.Pa /etc/rc
307script from within the jail.
308.Pp
309NOTE: If you plan to allow untrusted users to have root access inside the
310jail, you may wish to consider setting the
311.Va security.jail.set_hostname_allowed
312sysctl variable to 0.
313Please see the management discussion later in this document as to why this
314may be a good idea.
315If you do decide to set this variable,
316it must be set before starting any jails, and once each boot.
317.Bd -literal -offset indent
318ifconfig ed0 inet alias 192.168.11.100/32
319mount -t procfs proc /data/jail/192.168.11.100/proc
320jail /data/jail/192.168.11.100 testhostname 192.168.11.100 \\
321 /bin/sh /etc/rc
322.Ed
323.Pp
324A few warnings will be produced, because most
325.Xr sysctl 8
326configuration variables cannot be set from within the jail, as they are
327global across all jails and the host environment.
328However, it should all
329work properly.
330You should be able to see
331.Xr inetd 8 ,
332.Xr syslogd 8 ,
333and other processes running within the jail using
334.Xr ps 1 ,
335with the
336.Ql J
337flag appearing beside jailed processes.
338To see an active list of jails, use the
339.Xr jls 8
340utility.
341You should also be able to
342.Xr telnet 1
343to the hostname or IP address of the jailed environment, and log
344in using the accounts you created previously.
345.Ss "Managing the Jail"
346Normal machine shutdown commands, such as
347.Xr halt 8 ,
348.Xr reboot 8 ,
349and
350.Xr shutdown 8 ,
351cannot be used successfully within the jail.
352To kill all processes in a
353jail, you may log into the jail and, as root, use one of the following
354commands, depending on what you want to accomplish:
355.Pp
356.Bd -literal -offset indent
357kill -TERM -1
358kill -KILL -1
359.Ed
360.Pp
361This will send the
362.Dv SIGTERM
363or
364.Dv SIGKILL
365signals to all processes in the jail from within the jail.
366Depending on
367the intended use of the jail, you may also want to run
368.Pa /etc/rc.shutdown
369from within the jail.
370To kill processes from outside the jail, use the
371.Xr jexec 8
372utility in conjuction with the one of the
373.Xr kill 1
374commands above, or use the
375.Xr killall 1
376utility with the
377.Fl j
378option.
379.Pp
380The
381.Pa /proc/ Ns Ar pid Ns Pa /status
382file contains, as its last field, the hostname of the jail in which the
383process runs, or
384.Dq Li -
385to indicate that the process is not running within a jail.
386The
387.Xr ps 1
388command also shows a
389.Ql J
390flag for processes in a jail.
391However, the hostname for a jail may be, by
392default, modified from within the jail, so the
393.Pa /proc
394status entry is unreliable by default.
395To disable the setting of the hostname
396from within a jail, set the
397.Va security.jail.set_hostname_allowed
398sysctl variable in the host environment to 0, which will affect all jails.
399You can have this sysctl set on each boot using
400.Xr sysctl.conf 5 .
401Just add the following line to
402.Pa /etc/sysctl.conf :
403.Pp
404.Dl security.jail.set_hostname_allowed=0
405.Ss "Sysctl MIB Entries"
406Certain aspects of the jail containments environment may be modified from
407the host environment using
408.Xr sysctl 8
409MIB variables.
410Currently, these variables affect all jails on the system, although in
411the future this functionality may be finer grained.
412.Bl -tag -width XXX
413.It Va security.jail.allow_raw_sockets
414This MIB entry determines whether or not prison root is allowed to
415create raw sockets.
416Setting this MIB to 1 allows utilities like
417.Xr ping 8
418and
419.Xr traceroute 8
420to operate inside the prison.
421If this MIB
422is set, the source IP addresses are enforced to comply
423with the IP address bound to the jail, regardless of whether or not
424the
425.Dv IP_HDRINCL
426flag has been set on the socket.
427Since raw sockets can be used to configure
428and interact with various network subsystems, extra caution should be used
429where privileged access to jails is given out to untrusted parties.
430As such,
431by default this option is disabled.
432.It Va security.jail.getfsstatroot_only
433This MIB entry determines whether or not processes within a jail are able
434to see data for all mountpoints.
435When set to 1 (default), the
436.Xr getfsstat 2
437system call returns only (when called by jailed processes) the data for
438the file system on which the jail's root vnode is located.
439Note: this also has the effect of hiding other mounts inside a jail,
440such as
441.Pa /dev ,
442.Pa /tmp ,
443and
444.Pa /proc ,
445but errs on the side of leaking less information.
446.It Va security.jail.set_hostname_allowed
447This MIB entry determines whether or not processes within a jail are
448allowed to change their hostname via
449.Xr hostname 1
450or
451.Xr sethostname 3 .
452In the current jail implementation, the ability to set the hostname from
453within the jail can impact management tools relying on the accuracy of jail
454information in
455.Pa /proc .
456As such, this should be disabled in environments where privileged access to
457jails is given out to untrusted parties.
458.It Va security.jail.socket_unixiproute_only
459The jail functionality binds an IPv4 address to each jail, and limits
460access to other network addresses in the IPv4 space that may be available
461in the host environment.
462However, jail is not currently able to limit access to other network
463protocol stacks that have not had jail functionality added to them.
464As such, by default, processes within jails may only access protocols
465in the following domains:
466.Dv PF_LOCAL , PF_INET ,
467and
468.Dv PF_ROUTE ,
469permitting them access to
470.Ux
471domain sockets,
472IPv4 addresses, and routing sockets.
473To enable access to other domains, this MIB variable may be set to
4740.
475.It Va security.jail.sysvipc_allowed
476This MIB entry determines whether or not processes within a jail have access
477to System V IPC primitives.
478In the current jail implementation, System V primitives share a single
479namespace across the host and jail environments, meaning that processes
480within a jail would be able to communicate with (and potentially interfere
481with) processes outside of the jail, and in other jails.
482As such, this functionality is disabled by default, but can be enabled
483by setting this MIB entry to 1.
484.El
485.Pp
486There are currently two MIB related variables that have per-jail settings.
487Changes to these variables by a jailed process do not effect the host
488environment, only the jail environment.
489The variables are
490.Va kern.securelevel
491and
492.Va kern.hostname .
493.Sh SEE ALSO
494.Xr killall 1 ,
495.Xr newaliases 1 ,
496.Xr ps 1 ,
497.Xr chroot 2 ,
498.Xr jail 2 ,
499.Xr jail_attach 2 ,
500.Xr procfs 5 ,
501.Xr rc.conf 5 ,
502.Xr sysctl.conf 5 ,
503.Xr devfs 8 ,
504.Xr halt 8 ,
505.Xr inetd 8 ,
506.Xr jexec 8 ,
507.Xr jls 8 ,
508.Xr mount_devfs 8 ,
509.Xr named 8 ,
510.Xr reboot 8 ,
511.Xr rpcbind 8 ,
512.Xr sendmail 8 ,
513.Xr shutdown 8 ,
514.Xr sysctl 8 ,
515.Xr syslogd 8
516.Sh HISTORY
517The
518.Nm
519utility appeared in
520.Fx 4.0 .
521.Sh AUTHORS
522.An -nosplit
523The jail feature was written by
524.An Poul-Henning Kamp
525for R&D Associates
526.Pa http://www.rndassociates.com/
527who contributed it to
528.Fx .
529.Pp
530.An Robert Watson
531wrote the extended documentation, found a few bugs, added
532a few new features, and cleaned up the userland jail environment.
533.Sh BUGS
534Jail currently lacks the ability to allow access to
535specific jail information via
536.Xr ps 1
537as opposed to
538.Xr procfs 5 .
539Similarly, it might be a good idea to add an
540address alias flag such that daemons listening on all IPs
541.Pq Dv INADDR_ANY
542will not bind on that address, which would facilitate building a safe
543host environment such that host daemons do not impose on services offered
544from within jails.
545Currently, the simplest answer is to minimize services
546offered on the host, possibly limiting it to services offered from
547.Xr inetd 8
548which is easily configurable.
2.\" Copyright (c) 2000, 2003 Robert N. M. Watson
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\" notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\" notice, this list of conditions and the following disclaimer in the
12.\" documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
26.\"
27.\" ----------------------------------------------------------------------------
28.\" "THE BEER-WARE LICENSE" (Revision 42):
29.\" <phk@FreeBSD.ORG> wrote this file. As long as you retain this notice you
30.\" can do whatever you want with this stuff. If we meet some day, and you think
31.\" this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp
32.\" ----------------------------------------------------------------------------
33.\"
34.\" $FreeBSD: head/usr.sbin/jail/jail.8 131500 2004-07-02 23:13:00Z ru $
35.\"
36.Dd April 8, 2003
37.Dt JAIL 8
38.Os
39.Sh NAME
40.Nm jail
41.Nd "imprison process and its descendants"
42.Sh SYNOPSIS
43.Nm
44.Op Fl i
45.Op Fl u Ar username | Fl U Ar username
46.Ar path hostname ip-number command ...
47.Sh DESCRIPTION
48The
49.Nm
50utility imprisons a process and all future descendants.
51.Pp
52The options are as follows:
53.Bl -tag -width ".Fl u Ar username"
54.It Fl i
55Output the jail identifier of the newly created jail.
56.It Fl u Ar username
57The user name from host environment as whom the
58.Ar command
59should run.
60.It Fl U Ar username
61The user name from jailed environment as whom the
62.Ar command
63should run.
64.It Ar path
65Directory which is to be the root of the prison.
66.It Ar hostname
67Hostname of the prison.
68.It Ar ip-number
69IP number assigned to the prison.
70.It Ar command
71Pathname of the program which is to be executed.
72.El
73.Pp
74Jails are typically set up using one of two philosophies: either to
75constrain a specific application (possibly running with privilege), or
76to create a
77.Dq "virtual system image"
78running a variety of daemons and services.
79In both cases, a fairly complete file system install of
80.Fx
81is
82required, so as to provide the necessary command line tools, daemons,
83libraries, application configuration files, etc.
84However, for a virtual server configuration, a fair amount of
85additional work is required so as to configure the
86.Dq boot
87process.
88This manual page documents the configuration steps necessary to support
89either of these steps, although the configuration steps may be
90refined based on local requirements.
91.Pp
92Please see the
93.Xr jail 2
94man page for further details.
95.Sh EXAMPLES
96.Ss "Setting up a Jail Directory Tree"
97This example shows how to set up a jail directory tree
98containing an entire
99.Fx
100distribution:
101.Bd -literal
102D=/here/is/the/jail
103cd /usr/src
104mkdir -p $D
105make world DESTDIR=$D
106cd etc
107make distribution DESTDIR=$D
108mount_devfs devfs $D/dev
109cd $D
110ln -sf dev/null kernel
111.Ed
112.Pp
113NOTE: It is important that only appropriate device nodes in devfs be
114exposed to a jail; access to disk devices in the jail may permit processes
115in the jail to bypass the jail sandboxing by modifying files outside of
116the jail.
117See
118.Xr devfs 8
119for information on how to use devfs rules to limit access to entries
120in the per-jail devfs.
121.Pp
122In many cases this example would put far more in the jail than needed.
123In the other extreme case a jail might contain only one file:
124the executable to be run in the jail.
125.Pp
126We recommend experimentation and caution that it is a lot easier to
127start with a
128.Dq fat
129jail and remove things until it stops working,
130than it is to start with a
131.Dq thin
132jail and add things until it works.
133.Ss "Setting Up a Jail"
134Do what was described in
135.Sx "Setting Up a Jail Directory Tree"
136to build the jail directory tree.
137For the sake of this example, we will
138assume you built it in
139.Pa /data/jail/192.168.11.100 ,
140named for the jailed IP address.
141Substitute below as needed with your
142own directory, IP address, and hostname.
143.Ss "Setting up the Host Environment"
144First, you will want to set up your real system's environment to be
145.Dq jail-friendly .
146For consistency, we will refer to the parent box as the
147.Dq "host environment" ,
148and to the jailed virtual machine as the
149.Dq "jail environment" .
150Since jail is implemented using IP aliases, one of the first things to do
151is to disable IP services on the host system that listen on all local
152IP addresses for a service.
153If a network service is present in the host environment that binds all
154available IP addresses rather than specific IP addresses, it may service
155requests sent to jail IP addresses.
156This means changing
157.Xr inetd 8
158to only listen on the
159appropriate IP address, and so forth.
160Add the following to
161.Pa /etc/rc.conf
162in the host environment:
163.Bd -literal -offset indent
164sendmail_enable="NO"
165inetd_flags="-wW -a 192.168.11.23"
166rpcbind_enable="NO"
167.Ed
168.Pp
169.Li 192.168.11.23
170is the native IP address for the host system, in this example.
171Daemons that run out of
172.Xr inetd 8
173can be easily set to use only the specified host IP address.
174Other daemons
175will need to be manually configured\(emfor some this is possible through
176the
177.Xr rc.conf 5
178flags entries; for others it is necessary to modify per-application
179configuration files, or to recompile the applications.
180The following frequently deployed services must have their individual
181configuration files modified to limit the application to listening
182to a specific IP address:
183.Pp
184To configure
185.Xr sshd 8 ,
186it is necessary to modify
187.Pa /etc/ssh/sshd_config .
188.Pp
189To configure
190.Xr sendmail 8 ,
191it is necessary to modify
192.Pa /etc/mail/sendmail.cf .
193.Pp
194For
195.Xr named 8 ,
196it is necessary to modify
197.Pa /etc/namedb/named.conf .
198.Pp
199In addition, a number of services must be recompiled in order to run
200them in the host environment.
201This includes most applications providing services using
202.Xr rpc 3 ,
203such as
204.Xr rpcbind 8,
205.Xr nfsd 8 ,
206and
207.Xr mountd 8 .
208In general, applications for which it is not possible to specify which
209IP address to bind should not be run in the host environment unless they
210should also service requests sent to jail IP addresses.
211Attempting to serve
212NFS from the host environment may also cause confusion, and cannot be
213easily reconfigured to use only specific IPs, as some NFS services are
214hosted directly from the kernel.
215Any third-party network software running
216in the host environment should also be checked and configured so that it
217does not bind all IP addresses, which would result in those services' also
218appearing to be offered by the jail environments.
219.Pp
220Once
221these daemons have been disabled or fixed in the host environment, it is
222best to reboot so that all daemons are in a known state, to reduce the
223potential for confusion later (such as finding that when you send mail
224to a jail, and its sendmail is down, the mail is delivered to the host,
225etc.).
226.Ss "Configuring the Jail"
227Start any jail for the first time without configuring the network
228interface so that you can clean it up a little and set up accounts.
229As
230with any machine (virtual or not) you will need to set a root password, time
231zone, etc.
232Some of these steps apply only if you intend to run a full virtual server
233inside the jail; others apply both for constraining a particular application
234or for running a virtual server.
235.Pp
236Start a shell in the jail:
237.Pp
238.Dl "jail /data/jail/192.168.11.100 testhostname 192.168.11.100 /bin/sh"
239.Pp
240Assuming no errors, you will end up with a shell prompt within the jail.
241You can now run
242.Pa /usr/sbin/sysinstall
243and do the post-install configuration to set various configuration options,
244or perform these actions manually by editing
245.Pa /etc/rc.conf ,
246etc.
247.Pp
248.Bl -bullet -offset indent -compact
249.It
250Create an empty
251.Pa /etc/fstab
252to quell startup warnings about missing fstab (virtual server only)
253.It
254Disable the port mapper
255.Pa ( /etc/rc.conf :
256.Li rpcbind_enable="NO" )
257(virtual server only)
258.It
259Run
260.Xr newaliases 1
261to quell
262.Xr sendmail 8
263warnings.
264.It
265Disable interface configuration to quell startup warnings about
266.Xr ifconfig 8
267.Pq Li network_interfaces=""
268(virtual server only)
269.It
270Configure
271.Pa /etc/resolv.conf
272so that name resolution within the jail will work correctly
273.It
274Set a root password, probably different from the real host system
275.It
276Set the timezone
277.It
278Add accounts for users in the jail environment
279.It
280Install any packages the environment requires
281.El
282.Pp
283You may also want to perform any package-specific configuration (web servers,
284SSH servers, etc), patch up
285.Pa /etc/syslog.conf
286so it logs as you would like, etc.
287If you are not using a virtual server, you may wish to modify
288.Xr syslogd 8
289in the host environment to listen on the syslog socket in the jail
290environment; in this example, the syslog socket would be stored in
291.Pa /data/jail/192.168.11.100/var/run/log .
292.Pp
293Exit from the shell, and the jail will be shut down.
294.Ss "Starting the Jail"
295You are now ready to restart the jail and bring up the environment with
296all of its daemons and other programs.
297If you are running a single application in the jail, substitute the
298command used to start the application for
299.Pa /etc/rc
300in the examples below.
301To start a virtual server environment,
302.Pa /etc/rc
303is run to launch various daemons and services.
304To do this, first bring up the
305virtual host interface, and then start the jail's
306.Pa /etc/rc
307script from within the jail.
308.Pp
309NOTE: If you plan to allow untrusted users to have root access inside the
310jail, you may wish to consider setting the
311.Va security.jail.set_hostname_allowed
312sysctl variable to 0.
313Please see the management discussion later in this document as to why this
314may be a good idea.
315If you do decide to set this variable,
316it must be set before starting any jails, and once each boot.
317.Bd -literal -offset indent
318ifconfig ed0 inet alias 192.168.11.100/32
319mount -t procfs proc /data/jail/192.168.11.100/proc
320jail /data/jail/192.168.11.100 testhostname 192.168.11.100 \\
321 /bin/sh /etc/rc
322.Ed
323.Pp
324A few warnings will be produced, because most
325.Xr sysctl 8
326configuration variables cannot be set from within the jail, as they are
327global across all jails and the host environment.
328However, it should all
329work properly.
330You should be able to see
331.Xr inetd 8 ,
332.Xr syslogd 8 ,
333and other processes running within the jail using
334.Xr ps 1 ,
335with the
336.Ql J
337flag appearing beside jailed processes.
338To see an active list of jails, use the
339.Xr jls 8
340utility.
341You should also be able to
342.Xr telnet 1
343to the hostname or IP address of the jailed environment, and log
344in using the accounts you created previously.
345.Ss "Managing the Jail"
346Normal machine shutdown commands, such as
347.Xr halt 8 ,
348.Xr reboot 8 ,
349and
350.Xr shutdown 8 ,
351cannot be used successfully within the jail.
352To kill all processes in a
353jail, you may log into the jail and, as root, use one of the following
354commands, depending on what you want to accomplish:
355.Pp
356.Bd -literal -offset indent
357kill -TERM -1
358kill -KILL -1
359.Ed
360.Pp
361This will send the
362.Dv SIGTERM
363or
364.Dv SIGKILL
365signals to all processes in the jail from within the jail.
366Depending on
367the intended use of the jail, you may also want to run
368.Pa /etc/rc.shutdown
369from within the jail.
370To kill processes from outside the jail, use the
371.Xr jexec 8
372utility in conjuction with the one of the
373.Xr kill 1
374commands above, or use the
375.Xr killall 1
376utility with the
377.Fl j
378option.
379.Pp
380The
381.Pa /proc/ Ns Ar pid Ns Pa /status
382file contains, as its last field, the hostname of the jail in which the
383process runs, or
384.Dq Li -
385to indicate that the process is not running within a jail.
386The
387.Xr ps 1
388command also shows a
389.Ql J
390flag for processes in a jail.
391However, the hostname for a jail may be, by
392default, modified from within the jail, so the
393.Pa /proc
394status entry is unreliable by default.
395To disable the setting of the hostname
396from within a jail, set the
397.Va security.jail.set_hostname_allowed
398sysctl variable in the host environment to 0, which will affect all jails.
399You can have this sysctl set on each boot using
400.Xr sysctl.conf 5 .
401Just add the following line to
402.Pa /etc/sysctl.conf :
403.Pp
404.Dl security.jail.set_hostname_allowed=0
405.Ss "Sysctl MIB Entries"
406Certain aspects of the jail containments environment may be modified from
407the host environment using
408.Xr sysctl 8
409MIB variables.
410Currently, these variables affect all jails on the system, although in
411the future this functionality may be finer grained.
412.Bl -tag -width XXX
413.It Va security.jail.allow_raw_sockets
414This MIB entry determines whether or not prison root is allowed to
415create raw sockets.
416Setting this MIB to 1 allows utilities like
417.Xr ping 8
418and
419.Xr traceroute 8
420to operate inside the prison.
421If this MIB
422is set, the source IP addresses are enforced to comply
423with the IP address bound to the jail, regardless of whether or not
424the
425.Dv IP_HDRINCL
426flag has been set on the socket.
427Since raw sockets can be used to configure
428and interact with various network subsystems, extra caution should be used
429where privileged access to jails is given out to untrusted parties.
430As such,
431by default this option is disabled.
432.It Va security.jail.getfsstatroot_only
433This MIB entry determines whether or not processes within a jail are able
434to see data for all mountpoints.
435When set to 1 (default), the
436.Xr getfsstat 2
437system call returns only (when called by jailed processes) the data for
438the file system on which the jail's root vnode is located.
439Note: this also has the effect of hiding other mounts inside a jail,
440such as
441.Pa /dev ,
442.Pa /tmp ,
443and
444.Pa /proc ,
445but errs on the side of leaking less information.
446.It Va security.jail.set_hostname_allowed
447This MIB entry determines whether or not processes within a jail are
448allowed to change their hostname via
449.Xr hostname 1
450or
451.Xr sethostname 3 .
452In the current jail implementation, the ability to set the hostname from
453within the jail can impact management tools relying on the accuracy of jail
454information in
455.Pa /proc .
456As such, this should be disabled in environments where privileged access to
457jails is given out to untrusted parties.
458.It Va security.jail.socket_unixiproute_only
459The jail functionality binds an IPv4 address to each jail, and limits
460access to other network addresses in the IPv4 space that may be available
461in the host environment.
462However, jail is not currently able to limit access to other network
463protocol stacks that have not had jail functionality added to them.
464As such, by default, processes within jails may only access protocols
465in the following domains:
466.Dv PF_LOCAL , PF_INET ,
467and
468.Dv PF_ROUTE ,
469permitting them access to
470.Ux
471domain sockets,
472IPv4 addresses, and routing sockets.
473To enable access to other domains, this MIB variable may be set to
4740.
475.It Va security.jail.sysvipc_allowed
476This MIB entry determines whether or not processes within a jail have access
477to System V IPC primitives.
478In the current jail implementation, System V primitives share a single
479namespace across the host and jail environments, meaning that processes
480within a jail would be able to communicate with (and potentially interfere
481with) processes outside of the jail, and in other jails.
482As such, this functionality is disabled by default, but can be enabled
483by setting this MIB entry to 1.
484.El
485.Pp
486There are currently two MIB related variables that have per-jail settings.
487Changes to these variables by a jailed process do not effect the host
488environment, only the jail environment.
489The variables are
490.Va kern.securelevel
491and
492.Va kern.hostname .
493.Sh SEE ALSO
494.Xr killall 1 ,
495.Xr newaliases 1 ,
496.Xr ps 1 ,
497.Xr chroot 2 ,
498.Xr jail 2 ,
499.Xr jail_attach 2 ,
500.Xr procfs 5 ,
501.Xr rc.conf 5 ,
502.Xr sysctl.conf 5 ,
503.Xr devfs 8 ,
504.Xr halt 8 ,
505.Xr inetd 8 ,
506.Xr jexec 8 ,
507.Xr jls 8 ,
508.Xr mount_devfs 8 ,
509.Xr named 8 ,
510.Xr reboot 8 ,
511.Xr rpcbind 8 ,
512.Xr sendmail 8 ,
513.Xr shutdown 8 ,
514.Xr sysctl 8 ,
515.Xr syslogd 8
516.Sh HISTORY
517The
518.Nm
519utility appeared in
520.Fx 4.0 .
521.Sh AUTHORS
522.An -nosplit
523The jail feature was written by
524.An Poul-Henning Kamp
525for R&D Associates
526.Pa http://www.rndassociates.com/
527who contributed it to
528.Fx .
529.Pp
530.An Robert Watson
531wrote the extended documentation, found a few bugs, added
532a few new features, and cleaned up the userland jail environment.
533.Sh BUGS
534Jail currently lacks the ability to allow access to
535specific jail information via
536.Xr ps 1
537as opposed to
538.Xr procfs 5 .
539Similarly, it might be a good idea to add an
540address alias flag such that daemons listening on all IPs
541.Pq Dv INADDR_ANY
542will not bind on that address, which would facilitate building a safe
543host environment such that host daemons do not impose on services offered
544from within jails.
545Currently, the simplest answer is to minimize services
546offered on the host, possibly limiting it to services offered from
547.Xr inetd 8
548which is easily configurable.