2 .\" Copyright (c) 2000, 2003 Robert N. M. Watson
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
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 .\" ----------------------------------------------------------------------------
41 .Nd "imprison process and its descendants"
45 .Op Fl l u Ar username | Fl U Ar username
46 .Ar path hostname ip-number command ...
50 utility imprisons a process and all future descendants.
52 The options are as follows:
53 .Bl -tag -width ".Fl u Ar username"
55 Output the jail identifier of the newly created jail.
57 Run program in the clean environment.
58 The environment is discarded except for
59 .Ev HOME , SHELL , TERM
65 are set to the target login's default values.
67 is set to the target login.
69 is imported from the current environment.
70 The environment variables from the login class capability database for the
71 target login are also set.
73 The user name from host environment as whom the
77 The user name from jailed environment as whom the
81 Directory which is to be the root of the prison.
83 Hostname of the prison.
85 IP number assigned to the prison.
87 Pathname of the program which is to be executed.
90 Jails are typically set up using one of two philosophies: either to
91 constrain a specific application (possibly running with privilege), or
93 .Dq "virtual system image"
94 running a variety of daemons and services.
95 In both cases, a fairly complete file system install of
98 required, so as to provide the necessary command line tools, daemons,
99 libraries, application configuration files, etc.
100 However, for a virtual server configuration, a fair amount of
101 additional work is required so as to configure the
104 This manual page documents the configuration steps necessary to support
105 either of these steps, although the configuration steps may be
106 refined based on local requirements.
110 man page for further details.
112 .Ss "Setting up a Jail Directory Tree"
113 This example shows how to set up a jail directory tree
121 make world DESTDIR=$D
122 make distribution DESTDIR=$D
123 mount_devfs devfs $D/dev
126 NOTE: It is important that only appropriate device nodes in devfs be
127 exposed to a jail; access to disk devices in the jail may permit processes
128 in the jail to bypass the jail sandboxing by modifying files outside of
132 for information on how to use devfs rules to limit access to entries
133 in the per-jail devfs.
135 In many cases this example would put far more in the jail than needed.
136 In the other extreme case a jail might contain only one file:
137 the executable to be run in the jail.
139 We recommend experimentation and caution that it is a lot easier to
142 jail and remove things until it stops working,
143 than it is to start with a
145 jail and add things until it works.
146 .Ss "Setting Up a Jail"
147 Do what was described in
148 .Sx "Setting Up a Jail Directory Tree"
149 to build the jail directory tree.
150 For the sake of this example, we will
151 assume you built it in
152 .Pa /data/jail/192.168.11.100 ,
153 named for the jailed IP address.
154 Substitute below as needed with your
155 own directory, IP address, and hostname.
156 .Ss "Setting up the Host Environment"
157 First, you will want to set up your real system's environment to be
159 For consistency, we will refer to the parent box as the
160 .Dq "host environment" ,
161 and to the jailed virtual machine as the
162 .Dq "jail environment" .
163 Since jail is implemented using IP aliases, one of the first things to do
164 is to disable IP services on the host system that listen on all local
165 IP addresses for a service.
166 If a network service is present in the host environment that binds all
167 available IP addresses rather than specific IP addresses, it may service
168 requests sent to jail IP addresses.
171 to only listen on the
172 appropriate IP address, and so forth.
175 in the host environment:
176 .Bd -literal -offset indent
178 inetd_flags="-wW -a 192.168.11.23"
183 is the native IP address for the host system, in this example.
184 Daemons that run out of
186 can be easily set to use only the specified host IP address.
188 will need to be manually configured\(emfor some this is possible through
191 flags entries; for others it is necessary to modify per-application
192 configuration files, or to recompile the applications.
193 The following frequently deployed services must have their individual
194 configuration files modified to limit the application to listening
195 to a specific IP address:
199 it is necessary to modify
200 .Pa /etc/ssh/sshd_config .
204 it is necessary to modify
205 .Pa /etc/mail/sendmail.cf .
209 it is necessary to modify
210 .Pa /etc/namedb/named.conf .
212 In addition, a number of services must be recompiled in order to run
213 them in the host environment.
214 This includes most applications providing services using
221 In general, applications for which it is not possible to specify which
222 IP address to bind should not be run in the host environment unless they
223 should also service requests sent to jail IP addresses.
225 NFS from the host environment may also cause confusion, and cannot be
226 easily reconfigured to use only specific IPs, as some NFS services are
227 hosted directly from the kernel.
228 Any third-party network software running
229 in the host environment should also be checked and configured so that it
230 does not bind all IP addresses, which would result in those services' also
231 appearing to be offered by the jail environments.
234 these daemons have been disabled or fixed in the host environment, it is
235 best to reboot so that all daemons are in a known state, to reduce the
236 potential for confusion later (such as finding that when you send mail
237 to a jail, and its sendmail is down, the mail is delivered to the host,
239 .Ss "Configuring the Jail"
240 Start any jail for the first time without configuring the network
241 interface so that you can clean it up a little and set up accounts.
243 with any machine (virtual or not) you will need to set a root password, time
245 Some of these steps apply only if you intend to run a full virtual server
246 inside the jail; others apply both for constraining a particular application
247 or for running a virtual server.
249 Start a shell in the jail:
251 .Dl "jail /data/jail/192.168.11.100 testhostname 192.168.11.100 /bin/sh"
253 Assuming no errors, you will end up with a shell prompt within the jail.
255 .Pa /usr/sbin/sysinstall
256 and do the post-install configuration to set various configuration options,
257 or perform these actions manually by editing
261 .Bl -bullet -offset indent -compact
265 to quell startup warnings about missing fstab (virtual server only)
267 Disable the port mapper
269 .Li rpcbind_enable="NO" )
270 (virtual server only)
274 so that name resolution within the jail will work correctly
282 Disable interface configuration to quell startup warnings about
284 .Pq Li network_interfaces=""
285 (virtual server only)
287 Set a root password, probably different from the real host system
291 Add accounts for users in the jail environment
293 Install any packages the environment requires
296 You may also want to perform any package-specific configuration (web servers,
297 SSH servers, etc), patch up
299 so it logs as you would like, etc.
300 If you are not using a virtual server, you may wish to modify
302 in the host environment to listen on the syslog socket in the jail
303 environment; in this example, the syslog socket would be stored in
304 .Pa /data/jail/192.168.11.100/var/run/log .
306 Exit from the shell, and the jail will be shut down.
307 .Ss "Starting the Jail"
308 You are now ready to restart the jail and bring up the environment with
309 all of its daemons and other programs.
310 If you are running a single application in the jail, substitute the
311 command used to start the application for
313 in the examples below.
314 To start a virtual server environment,
316 is run to launch various daemons and services.
317 To do this, first bring up the
318 virtual host interface, and then start the jail's
320 script from within the jail.
322 NOTE: If you plan to allow untrusted users to have root access inside the
323 jail, you may wish to consider setting the
324 .Va security.jail.set_hostname_allowed
325 sysctl variable to 0.
326 Please see the management discussion later in this document as to why this
328 If you do decide to set this variable,
329 it must be set before starting any jails, and once each boot.
330 .Bd -literal -offset indent
331 ifconfig ed0 inet alias 192.168.11.100/32
332 mount -t procfs proc /data/jail/192.168.11.100/proc
333 jail /data/jail/192.168.11.100 testhostname 192.168.11.100 \\
337 A few warnings will be produced, because most
339 configuration variables cannot be set from within the jail, as they are
340 global across all jails and the host environment.
341 However, it should all
343 You should be able to see
346 and other processes running within the jail using
350 flag appearing beside jailed processes.
351 To see an active list of jails, use the
354 You should also be able to
356 to the hostname or IP address of the jailed environment, and log
357 in using the accounts you created previously.
359 It is possible to have jails started at boot time.
364 for more information.
367 jail script provides a flexible system to start/stop jails:
371 /etc/rc.d/jail start myjail
372 /etc/rc.d/jail stop myjail
374 .Ss "Managing the Jail"
375 Normal machine shutdown commands, such as
380 cannot be used successfully within the jail.
381 To kill all processes in a
382 jail, you may log into the jail and, as root, use one of the following
383 commands, depending on what you want to accomplish:
385 .Bd -literal -offset indent
394 signals to all processes in the jail from within the jail.
396 the intended use of the jail, you may also want to run
398 from within the jail.
399 To kill processes from outside the jail, use the
401 utility in conjunction with the one of the
406 .Pa /proc/ Ns Ar pid Ns Pa /status
407 file contains, as its last field, the hostname of the jail in which the
410 to indicate that the process is not running within a jail.
415 flag for processes in a jail.
416 However, the hostname for a jail may be, by
417 default, modified from within the jail, so the
419 status entry is unreliable by default.
420 To disable the setting of the hostname
421 from within a jail, set the
422 .Va security.jail.set_hostname_allowed
423 sysctl variable in the host environment to 0, which will affect all jails.
424 You can have this sysctl set on each boot using
426 Just add the following line to
427 .Pa /etc/sysctl.conf :
429 .Dl security.jail.set_hostname_allowed=0
431 You can also list/kill processes based on their jail ID.
432 To show processes and their jail ID, use the following command:
434 .Dl "ps ax -o pid,jid,args"
436 To show and then kill processes in jail number 3 use the following commands:
437 .Bd -literal -offset indent
444 .Ss "Sysctl MIB Entries"
445 Certain aspects of the jail containments environment may be modified from
446 the host environment using
449 Currently, these variables affect all jails on the system, although in
450 the future this functionality may be finer grained.
452 .It Va security.jail.allow_raw_sockets
453 This MIB entry determines whether or not prison root is allowed to
455 Setting this MIB to 1 allows utilities like
459 to operate inside the prison.
461 is set, the source IP addresses are enforced to comply
462 with the IP address bound to the jail, regardless of whether or not
465 flag has been set on the socket.
466 Since raw sockets can be used to configure
467 and interact with various network subsystems, extra caution should be used
468 where privileged access to jails is given out to untrusted parties.
470 by default this option is disabled.
471 .It Va security.jail.enforce_statfs
472 This MIB entry determines which information processes in a jail are
473 able to get about mount-points.
474 It affects the behaviour of the following syscalls:
480 (as well as similar compatibility syscalls).
481 When set to 0, all mount-points are available without any restrictions.
482 When set to 1, only mount-points below the jail's chroot directory are
484 In addition to that, the path to the jail's chroot directory is removed
485 from the front of their pathnames.
486 When set to 2 (default), above syscalls can operate only on a mount-point
487 where the jail's chroot directory is located.
488 .It Va security.jail.set_hostname_allowed
489 This MIB entry determines whether or not processes within a jail are
490 allowed to change their hostname via
494 In the current jail implementation, the ability to set the hostname from
495 within the jail can impact management tools relying on the accuracy of jail
498 As such, this should be disabled in environments where privileged access to
499 jails is given out to untrusted parties.
500 .It Va security.jail.socket_unixiproute_only
501 The jail functionality binds an IPv4 address to each jail, and limits
502 access to other network addresses in the IPv4 space that may be available
503 in the host environment.
504 However, jail is not currently able to limit access to other network
505 protocol stacks that have not had jail functionality added to them.
506 As such, by default, processes within jails may only access protocols
507 in the following domains:
508 .Dv PF_LOCAL , PF_INET ,
511 permitting them access to
514 IPv4 addresses, and routing sockets.
515 To enable access to other domains, this MIB variable may be set to
517 .It Va security.jail.sysvipc_allowed
518 This MIB entry determines whether or not processes within a jail have access
519 to System V IPC primitives.
520 In the current jail implementation, System V primitives share a single
521 namespace across the host and jail environments, meaning that processes
522 within a jail would be able to communicate with (and potentially interfere
523 with) processes outside of the jail, and in other jails.
524 As such, this functionality is disabled by default, but can be enabled
525 by setting this MIB entry to 1.
526 .It Va security.jail.chflags_allowed
527 This MIB entry determines how a privileged user inside a jail will be
530 If zero, such users are treated as unprivileged, and are unable to set
531 or clear system file flags; if non-zero, such users are treated as
532 privileged, and may manipulate system file flags subject to the usual
534 .Va kern.securelevel .
537 There are currently two MIB related variables that have per-jail settings.
538 Changes to these variables by a jailed process do not effect the host
539 environment, only the jail environment.
576 The jail feature was written by
577 .An Poul-Henning Kamp
579 .Pa http://www.rndassociates.com/
580 who contributed it to
584 wrote the extended documentation, found a few bugs, added
585 a few new features, and cleaned up the userland jail environment.
587 Jail currently lacks the ability to allow access to
588 specific jail information via
592 Similarly, it might be a good idea to add an
593 address alias flag such that daemons listening on all IPs
595 will not bind on that address, which would facilitate building a safe
596 host environment such that host daemons do not impose on services offered
598 Currently, the simplest answer is to minimize services
599 offered on the host, possibly limiting it to services offered from
601 which is easily configurable.