1.\" Copyright (c) 2000, 2003 Robert N. M. Watson
2.\" Copyright (c) 2008-2012 James Gritton
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.\" $FreeBSD: head/usr.sbin/jail/jail.8 254741 2013-08-23 22:52:20Z delphij $
27.\"
28.Dd August 23, 2013
29.Dt JAIL 8
30.Os
31.Sh NAME
32.Nm jail
33.Nd "manage system jails"
34.Sh SYNOPSIS
35.Nm
36.Op Fl dhilqv
37.Op Fl J Ar jid_file
38.Op Fl u Ar username
39.Op Fl U Ar username
40.Op Fl cmr
41.Ar param Ns = Ns Ar value ...
42.Op Cm command Ns = Ns Ar command ...
43.Nm
44.Op Fl dqv
45.Op Fl f Ar conf_file
46.Op Fl p Ar limit
47.Op Fl cmr
48.Op Ar jail
49.Nm
50.Op Fl qv
51.Op Fl f Ar conf_file
52.Op Fl rR
53.Op Cm * | Ar jail ...
54.Nm
55.Op Fl dhilqv
56.Op Fl J Ar jid_file
57.Op Fl u Ar username
58.Op Fl U Ar username
59.Op Fl n Ar jailname
60.Op Fl s Ar securelevel
61.Op Ar path hostname [ Ar ip Ns [ Ns Ar ,... Ns ]] Ar command ...
62.Sh DESCRIPTION
63The
64.Nm
65utility creates new jails, or modifies or removes existing jails.
66A jail is specified via parameters on the command line, or in the
67.Xr jail.conf 5
68file.
69.Pp
70At least one of the options
71.Fl c ,
72.Fl m
73or
74.Fl r
75must be specified.
76These options are used alone or in combination describe the operation to
77perform:
78.Bl -tag -width indent
79.It Fl c
80Create a new jail.
81The jail
82.Va jid
83and
84.Va name
85parameters (if specified) on the command line,
86or any jails
87must not refer to an existing jail.
88.It Fl m
89Modify an existing jail.
90One of the
91.Va jid
92or
93.Va name
94parameters must exist and refer to an existing jail.
95Some parameters may not be changed on a running jail.
96.It Fl r
97Remove the
98.Ar jail
99specified by jid or name.
100All jailed processes are killed, and all children of this jail are also
101removed.
102.It Fl rc
103Restart an existing jail.
104The jail is first removed and then re-created, as if
105.Dq Nm Fl c
106and
107.Dq Nm Fl r
108were run in succession.
109.It Fl cm
110Create a jail if it does not exist, or modify the jail if it does exist.
111.It Fl mr
112Modify an existing jail.
113The jail may be restarted if necessary to modify parameters than could
114not otherwise be changed.
115.It Fl cmr
116Create a jail if it doesn't exist, or modify (and possibly restart) the
117jail if it does exist.
118.El
119.Pp
120Other available options are:
121.Bl -tag -width indent
122.It Fl d
123Allow making changes to a dying jail, equivalent to the
124.Va allow.dying
125parameter.
126.It Fl f Ar conf_file
127Use configuration file
128.Ar conf_file
129instead of the default
130.Pa /etc/jail.conf .
131.It Fl h
132Resolve the
133.Va host.hostname
134parameter (or
135.Va hostname )
136and add all IP addresses returned by the resolver
137to the list of addresses for this prison.
138This is equivalent to the
139.Va ip_hostname
140parameter.
141.It Fl i
142Output (only) the jail identifier of the newly created jail(s).
143This implies the
144.Fl q
145option.
146.It Fl J Ar jid_file
147Write a
148.Ar jid_file
149file, containing parameters used to start the jail.
150.It Fl l
151Run commands in a clean environment.
152This is deprecated and is equivalent to the exec.clean parameter.
153.It Fl n Ar jailname
154Set the jail's name.
155This is deprecated and is equivalent to the
156.Va name
157parameter.
158.It Fl p Ar limit
159Limit the number of commands from
160.Va exec.*
161that can run simultaneously.
162.It Fl q
163Suppress the message printed whenever a jail is created, modified or removed.
164Only error messages will be printed.
165.It Fl R
166A variation of the
167.Fl r
168option that removes an existing jail without using the configuration file.
169No removal-related parameters for this jail will be used - the jail will
170simply be removed.
171.It Fl s Ar securelevel
172Set the
173.Va kern.securelevel
174MIB entry to the specified value inside the newly created jail.
175This is deprecated and is equivalent to the
176.Va securelevel
177parameter.
178.It Fl u Ar username
179The user name from host environment as whom jailed commands should run.
180This is deprecated and is equivalent to the
181.Va exec.jail_user
182and
183.Va exec.system_jail_user
184parameters.
185.It Fl U Ar username
186The user name from jailed environment as whom jailed commands should run.
187This is deprecated and is equivalent to the
188.Va exec.jail_user
189parameter.
190.It Fl v
191Print a message on every operation, such as running commands and
192mounting filesystems.
193.El
194.Pp
195If no arguments are given after the options, the operation (except
196remove) will be performed on all jails specified in the
197.Xr jail.conf 5
198file.
199A single argument of a jail name will operate only on the specified jail.
200The
201.Fl r
202and
203.Fl R
204options can also remove running jails that aren't in the
205.Xr jail.conf 5
206file, specified by name or jid.
207.Pp
208An argument of
209.Dq *
210is a wildcard that will operate on all jails, regardless of whether
211they appear in
212.Xr jail.conf 5 ;
213this is the surest way for
214.Fl r
215to remove all jails.
216If hierarchical jails exist, a partial-matching wildcard definition may
217be specified.
218For example, an argument of
219.Dq foo.*
220would apply to jails with names like
221.Dq foo.bar
222and
223.Dq foo.bar.baz .
224.Pp
225A jail may be specified with parameters directly on the command line.
226In this case, the
227.Xr jail.conf 5
228file will not be used.
229For backward compatibility, the command line may also have four fixed
230parameters, without names:
231.Ar path ,
232.Ar hostname ,
233.Ar ip ,
234and
235.Ar command .
236This mode will always create a new jail, and the
237.Fl c
238and
239.Fl m
240options don't apply (and must not exist).
241.Ss Jail Parameters
242Parameters in the
243.Xr jail.conf 5
244file, or on the command line, are generally in
245.Dq name=value
246form.
247Some parameters are boolean, and do not have a value but are set by the
248name alone with or without a
249.Dq no
250prefix, e.g.
251.Va persist
252or
253.Va nopersist .
254They can also be given the values
255.Dq true
256and
257.Dq false .
258Other parameters may have more than one value, specified as a
259comma-separated list or with
260.Dq +=
261in the configuration file (see
262.Xr jail.conf 5
263for details).
264.Pp
265The
266.Nm
267utility recognizes two classes of parameters. There are the true jail
268parameters that are passed to the kernel when the jail is created,
269can be seen with
270.Xr jls 8 ,
271and can (usually) be changed with
272.Dq Nm Fl m .
273Then there are pseudo-parameters that are only used by
274.Nm
275itself.
276.Pp
277Jails have a set a core parameters, and kernel modules can add their own
278jail parameters.
279The current set of available parameters can be retrieved via
280.Dq Nm sysctl Fl d Va security.jail.param .
281Any parameters not set will be given default values, often based on the
282current environment.
283The core parameters are:
284.Bl -tag -width indent
285.It Va jid
286The jail identifier.
287This will be assigned automatically to a new jail (or can be explicitly
288set), and can be used to identify the jail for later modification, or
289for such commands as
290.Xr jls 8
291or
292.Xr jexec 8 .
293.It Va name
294The jail name.
295This is an arbitrary string that identifies a jail (except it may not
296contain a
297.Sq \&. ) .
298Like the
299.Va jid ,
300it can be passed to later
301.Nm
302commands, or to
303.Xr jls 8
304or
305.Xr jexec 8 .
306If no
307.Va name
308is supplied, a default is assumed that is the same as the
309.Va jid .
310The
311.Va name
312parameter is implied by the
313.Xr jail.conf 5
314file format, and need not be explicitly set when using the configuration
315file.
316.It Va path
317The directory which is to be the root of the prison.
318Any commands run inside the prison, either by
319.Nm
320or from
321.Xr jexec 8 ,
322are run from this directory.
323.It Va ip4.addr
324A list of IPv4 addresses assigned to the prison.
325If this is set, the jail is restricted to using only these addresses.
326Any attempts to use other addresses fail, and attempts to use wildcard
327addresses silently use the jailed address instead.
328For IPv4 the first address given will be kept used as the source address
329in case source address selection on unbound sockets cannot find a better
330match.
331It is only possible to start multiple jails with the same IP address,
332if none of the jails has more than this single overlapping IP address
333assigned to itself.
334.It Va ip4.saddrsel
335A boolean option to change the formerly mentioned behaviour and disable
336IPv4 source address selection for the prison in favour of the primary
337IPv4 address of the jail.
338Source address selection is enabled by default for all jails and the
339.Va ip4.nosaddrsel
340setting of a parent jail is not inherited for any child jails.
341.It Va ip4
342Control the availability of IPv4 addresses.
343Possible values are
344.Dq inherit
345to allow unrestricted access to all system addresses,
346.Dq new
347to restrict addresses via
348.Va ip4.addr
349above, and
350.Dq disable
351to stop the jail from using IPv4 entirely.
352Setting the
353.Va ip4.addr
354parameter implies a value of
355.Dq new .
356.It Va ip6.addr , Va ip6.saddrsel , Va ip6
357A set of IPv6 options for the prison, the counterparts to
358.Va ip4.addr ,
359.Va ip4.saddrsel
360and
361.Va ip4
362above.
363.It vnet
364Create the prison with its own virtual network stack,
365with its own network interfaces, addresses, routing table, etc.
366The kernel must have been compiled with the
367.Sy VIMAGE option
368for this to be available.
369Possible values are
370.Dq inherit
371to use the system network stack, possibly with restricted IP addresses,
372and
373.Dq new
374to create a new network stack.
375.It Va host.hostname
376The hostname of the prison.
377Other similar parameters are
378.Va host.domainname ,
379.Va host.hostuuid
380and
381.Va host.hostid .
382.It Va host
383Set the origin of hostname and related information.
384Possible values are
385.Dq inherit
386to use the system information and
387.Dq new
388for the jail to use the information from the above fields.
389Setting any of the above fields implies a value of
390.Dq new .
391.It Va securelevel
392The value of the jail's
393.Va kern.securelevel
394sysctl.
395A jail never has a lower securelevel than the default system, but by
396setting this parameter it may have a higher one.
397If the system securelevel is changed, any jail securelevels will be at
398least as secure.
399.It Va devfs_ruleset
400The number of the devfs ruleset that is enforced for mounting devfs in
401this jail.
402A value of zero (default) means no ruleset is enforced.
403Descendant jails inherit the parent jail's devfs ruleset enforcement.
404Mounting devfs inside a jail is possible only if the
405.Va allow.mount
406and
407.Va allow.mount.devfs
408permissions are effective and
409.Va enforce_statfs
410is set to a value lower than 2.
411Devfs rules and rulesets cannot be viewed or modified from inside a jail.
412.Pp
413NOTE: It is important that only appropriate device nodes in devfs be
414exposed to a jail; access to disk devices in the jail may permit processes
415in the jail to bypass the jail sandboxing by modifying files outside of
416the jail.
417See
418.Xr devfs 8
419for information on how to use devfs rules to limit access to entries
420in the per-jail devfs.
421A simple devfs ruleset for jails is available as ruleset #4 in
422.Pa /etc/defaults/devfs.rules .
423.It Va children.max
424The number of child jails allowed to be created by this jail (or by
425other jails under this jail).
426This limit is zero by default, indicating the jail is not allowed to
427create child jails.
428See the
429.Sx "Hierarchical Jails"
430section for more information.
431.It Va children.cur
432The number of descendants of this jail, including its own child jails
433and any jails created under them.
434.It Va enforce_statfs
435This determines which information processes in a jail are able to get
436about mount points.
437It affects the behaviour of the following syscalls:
438.Xr statfs 2 ,
439.Xr fstatfs 2 ,
440.Xr getfsstat 2
441and
442.Xr fhstatfs 2
443(as well as similar compatibility syscalls).
444When set to 0, all mount points are available without any restrictions.
445When set to 1, only mount points below the jail's chroot directory are
446visible.
447In addition to that, the path to the jail's chroot directory is removed
448from the front of their pathnames.
449When set to 2 (default), above syscalls can operate only on a mount-point
450where the jail's chroot directory is located.
451.It Va persist
452Setting this boolean parameter allows a jail to exist without any
453processes.
454Normally, a command is run as part of jail creation, and then the jail
455is destroyed as its last process exits.
456A new jail must have either the
457.Va persist
458parameter or
459.Va exec.start
460or
461.Va command
462pseudo-parameter set.
463.It Va cpuset.id
464The ID of the cpuset associated with this jail (read-only).
465.It Va dying
466This is true if the jail is in the process of shutting down (read-only).
467.It Va parent
468The
469.Va jid
470of the parent of this jail, or zero if this is a top-level jail
471(read-only).
472.It Va allow.*
473Some restrictions of the jail environment may be set on a per-jail
474basis.
475With the exception of
476.Va allow.set_hostname ,
477these boolean parameters are off by default.
478.Bl -tag -width indent
479.It Va allow.set_hostname
480The jail's hostname may be changed via
481.Xr hostname 1
482or
483.Xr sethostname 3 .
484.It Va allow.sysvipc
485A process within the jail has access to System V IPC primitives.
486In the current jail implementation, System V primitives share a single
487namespace across the host and jail environments, meaning that processes
488within a jail would be able to communicate with (and potentially interfere
489with) processes outside of the jail, and in other jails.
490.It Va allow.raw_sockets
491The prison root is allowed to create raw sockets.
492Setting this parameter allows utilities like
493.Xr ping 8
494and
495.Xr traceroute 8
496to operate inside the prison.
497If this is set, the source IP addresses are enforced to comply
498with the IP address bound to the jail, regardless of whether or not
499the
500.Dv IP_HDRINCL
501flag has been set on the socket.
502Since raw sockets can be used to configure and interact with various
503network subsystems, extra caution should be used where privileged access
504to jails is given out to untrusted parties.
505.It Va allow.chflags
506Normally, privileged users inside a jail are treated as unprivileged by
507.Xr chflags 2 .
508When this parameter is set, such users are treated as privileged, and
509may manipulate system file flags subject to the usual constraints on
510.Va kern.securelevel .
511.It Va allow.mount
512privileged users inside the jail will be able to mount and unmount file
513system types marked as jail-friendly.
514The
515.Xr lsvfs 1
516command can be used to find file system types available for mount from
517within a jail.
518This permission is effective only if
519.Va enforce_statfs
520is set to a value lower than 2.
521.It Va allow.mount.devfs
522privileged users inside the jail will be able to mount and unmount the
523devfs file system.
524This permission is effective only together with
525.Va allow.mount
526and if
527.Va enforce_statfs
528is set to a value lower than 2.
529Please consider restricting the devfs ruleset with the
530.Va devfs_ruleset
531option.
532.It Va allow.mount.nullfs
533privileged users inside the jail will be able to mount and unmount the
534nullfs file system.
535This permission is effective only together with
536.Va allow.mount
537and if
538.Va enforce_statfs
539is set to a value lower than 2.
540.It Va allow.mount.procfs
541privileged users inside the jail will be able to mount and unmount the
542procfs file system.
543This permission is effective only together with
544.Va allow.mount
545and if
546.Va enforce_statfs
547is set to a value lower than 2.
548.It Va allow.mount.tmpfs
549privileged users inside the jail will be able to mount and unmount the
550tmpfs file system.
551This permission is effective only together with
552.Va allow.mount
553and if
554.Va enforce_statfs
555is set to a value lower than 2.
556.It Va allow.mount.zfs
557privileged users inside the jail will be able to mount and unmount the
558ZFS file system.
559This permission is effective only together with
560.Va allow.mount
561and if
562.Va enforce_statfs
563is set to a value lower than 2.
564See
565.Xr zfs 8
566for information on how to configure the ZFS filesystem to operate from
567within a jail.
568.It Va allow.quotas
569The prison root may administer quotas on the jail's filesystem(s).
570This includes filesystems that the jail may share with other jails or
571with non-jailed parts of the system.
572.It Va allow.socket_af
573Sockets within a jail are normally restricted to IPv4, IPv6, local
574(UNIX), and route. This allows access to other protocol stacks that
575have not had jail functionality added to them.
576.El
577.El
578.Pp
579There are pseudo-parameters that aren't passed to the kernel, but are
580used by
581.Nm
582to set up the prison environment, often by running specified commands
583when jails are created or removed.
584The
585.Va exec.*
586command parameters are
587.Xr sh 1
588command lines that are run in either the system or prison environment.
589They may be given multiple values, which run would the specified
590commands in sequence.
591All commands must succeed (return a zero exit status), or the jail will
592not be created or removed.
593.Pp
594The pseudo-parameters are:
595.Bl -tag -width indent
596.It Va exec.prestart
597Command(s) to run in the system environment before a prison is created.
598.It Va exec.start
599Command(s) to run in the prison environment when a jail is created.
600A typical command to run is
601.Dq sh /etc/rc .
602.It Va command
603A synonym for
604.Va exec.start
605for use when specifying a prison directly on the command line.
606Unlike other parameters whose value is a single string,
607.Va command
608uses the remainder of the
609.Nm
610command line as its own arguments.
611.It Va exec.poststart
612Command(s) to run in the system environment after a jail is created,
613and after any
614.Va exec.start
615commands have completed.
616.It Va exec.prestop
617Command(s) to run in the system environment before a jail is removed.
618.It Va exec.stop
619Command(s) to run in the prison environment before a jail is removed,
620and after any
621.Va exec.prestop
622commands have completed.
623A typical command to run is
624.Dq sh /etc/rc.shutdown .
625.It Va exec.poststop
626Command(s) to run in the system environment after a jail is removed.
627.It Va exec.clean
628Run commands in a clean environment.
629The environment is discarded except for
630.Ev HOME , SHELL , TERM
631and
632.Ev USER .
633.Ev HOME
634and
635.Ev SHELL
636are set to the target login's default values.
637.Ev USER
638is set to the target login.
639.Ev TERM
640is imported from the current environment.
641The environment variables from the login class capability database for the
642target login are also set.
643.It Va exec.jail_user
644The user to run commands as, when running in the prison environment.
645The default is to run the commands as the current user.
646.It Va exec.system_jail_user
647This boolean option looks for the
648.Va exec.jail_user
649in the system
650.Xr passwd 5
651file, instead of in the prison's file.
652.It Va exec.system_user
653The user to run commands as, when running in the system environment.
654The default is to run the commands as the current user.
655.It Va exec.timeout
656The maximum amount of time to wait for a command to complete.
657If a command is still running after this many seconds have passed,
658the jail not be created or removed.
659.It Va exec.consolelog
660A file to direct command output (stdout and stderr) to.
661.It Va exec.fib
662The FIB (routing table) to set when running commands inside the prison.
663.It Va stop.timeout
664The maximum amount of time to wait for a prison's processes to exit
665after sending them a
666.Dv SIGTERM
667signal (which happens after the
668.Va exec.stop
669commands have completed).
670After this many seconds have passed, the prison will be removed, which
671will kill any remaining processes.
672If this is set to zero, no
673.Dv SIGTERM
674is sent and the prison is immediately removed.
675The default is 10 seconds.
676.It Va interface
677A network interface to add the prison's IP addresses
678.Va ( ip4.addr
679and
680.Va ip6.addr )
681to.
682An alias for each address will be added to the interface before the
683prison is created, and will be removed from the interface after the
684prison is removed.
685.It Op Va ip4.addr
686In addition to the IP addresses that are passed to the kernel, and
687interface and/or a netmask may also be specified, in the form
688.Dq Ar interface Ns | Ns Ar ip-address Ns / Ns Ar netmask .
689If an interface is given before the IP address, an alias for the address
690will be added to that interface, as it is with the
691.Va interface
692parameter. If a netmask in either dotted-quad or CIDR form is given
693after IP address, it will be used when adding the IP alias.
694.It Op Va ip6.addr
695In addition to the IP addresses that are passed to the kernel,
696and interface and/or a prefix may also be specified, in the form
697.Dq Ar interface Ns | Ns Ar ip-address Ns / Ns Ar prefix .
698.It Va vnet.interface
699A network interface to give to a vnet-enabled jail after is it created.
700The interface will automatically be returned when the jail is removed.
701.It Va ip_hostname
702Resolve the
703.Va host.hostname
704parameter and add all IP addresses returned by the resolver
705to the list of addresses
706.Va ( ip4.addr
707or
708.Va ip6.addr )
709for this prison.
710This may affect default address selection for outgoing IPv4 connections
711of prisons.
712The address first returned by the resolver for each address family
713will be used as primary address.
714.It Va mount
715A filesystem to mount before creating the jail (and to unmount after
716removing it), given as a single
717.Xr fstab 5
718line.
719.It Va mount.fstab
720An
721.Xr fstab 5
722format file containing filesystems to mount before creating a jail.
723.It Va mount.devfs
724Mount a
725.Xr devfs
726filesystem on the chrooted /dev directory, and apply the ruleset in the
727.Va devfs_ruleset
728parameter (or a default of ruleset 4: devfsrules_jail)
729to restrict the devices visible inside the prison.
730.It Va allow.dying
731Allow making changes to a
732.Va dying
733jail.
734.It Va depend
735Specify a jail (or jails) that this jail depends on.
736Any such jails must be fully created, up to the last
737.Va exec.poststart
738command, before any action will taken to create this jail.
739When jails are removed the opposite is true:
740this jail must be fully removed, up to the last
741.Va exec.poststop
742command, before the jail(s) it depends on are stopped.
743.El
744.Sh EXAMPLES
745Jails are typically set up using one of two philosophies: either to
746constrain a specific application (possibly running with privilege), or
747to create a
748.Dq "virtual system image"
749running a variety of daemons and services.
750In both cases, a fairly complete file system install of
751.Fx
752is
753required, so as to provide the necessary command line tools, daemons,
754libraries, application configuration files, etc.
755However, for a virtual server configuration, a fair amount of
756additional work is required so as to configure the
757.Dq boot
758process.
759This manual page documents the configuration steps necessary to support
760either of these steps, although the configuration steps may be
761refined based on local requirements.
762.Ss "Setting up a Jail Directory Tree"
763To set up a jail directory tree containing an entire
764.Fx
765distribution, the following
766.Xr sh 1
767command script can be used:
768.Bd -literal
769D=/here/is/the/jail
770cd /usr/src
771mkdir -p $D
772make world DESTDIR=$D
773make distribution DESTDIR=$D
774.Ed
775.Pp
776In many cases this example would put far more in the jail than needed.
777In the other extreme case a jail might contain only one file:
778the executable to be run in the jail.
779.Pp
780We recommend experimentation and caution that it is a lot easier to
781start with a
782.Dq fat
783jail and remove things until it stops working,
784than it is to start with a
785.Dq thin
786jail and add things until it works.
787.Ss "Setting Up a Jail"
788Do what was described in
789.Sx "Setting Up a Jail Directory Tree"
790to build the jail directory tree.
791For the sake of this example, we will
792assume you built it in
793.Pa /data/jail/testjail ,
794for a jail named
795.Dq testjail .
796Substitute below as needed with your
797own directory, IP address, and hostname.
798.Ss "Setting up the Host Environment"
799First, you will want to set up your real system's environment to be
800.Dq jail-friendly .
801For consistency, we will refer to the parent box as the
802.Dq "host environment" ,
803and to the jailed virtual machine as the
804.Dq "jail environment" .
805Since jail is implemented using IP aliases, one of the first things to do
806is to disable IP services on the host system that listen on all local
807IP addresses for a service.
808If a network service is present in the host environment that binds all
809available IP addresses rather than specific IP addresses, it may service
810requests sent to jail IP addresses if the jail did not bind the port.
811This means changing
812.Xr inetd 8
813to only listen on the
814appropriate IP address, and so forth.
815Add the following to
816.Pa /etc/rc.conf
817in the host environment:
818.Bd -literal -offset indent
819sendmail_enable="NO"
820inetd_flags="-wW -a 192.0.2.23"
821rpcbind_enable="NO"
822.Ed
823.Pp
824.Li 192.0.2.23
825is the native IP address for the host system, in this example.
826Daemons that run out of
827.Xr inetd 8
828can be easily set to use only the specified host IP address.
829Other daemons
830will need to be manually configured\(emfor some this is possible through
831the
832.Xr rc.conf 5
833flags entries; for others it is necessary to modify per-application
834configuration files, or to recompile the applications.
835The following frequently deployed services must have their individual
836configuration files modified to limit the application to listening
837to a specific IP address:
838.Pp
839To configure
840.Xr sshd 8 ,
841it is necessary to modify
842.Pa /etc/ssh/sshd_config .
843.Pp
844To configure
845.Xr sendmail 8 ,
846it is necessary to modify
847.Pa /etc/mail/sendmail.cf .
848.Pp
849For
850.Xr named 8 ,
851it is necessary to modify
852.Pa /etc/namedb/named.conf .
853.Pp
854In addition, a number of services must be recompiled in order to run
855them in the host environment.
856This includes most applications providing services using
857.Xr rpc 3 ,
858such as
859.Xr rpcbind 8 ,
860.Xr nfsd 8 ,
861and
862.Xr mountd 8 .
863In general, applications for which it is not possible to specify which
864IP address to bind should not be run in the host environment unless they
865should also service requests sent to jail IP addresses.
866Attempting to serve
867NFS from the host environment may also cause confusion, and cannot be
868easily reconfigured to use only specific IPs, as some NFS services are
869hosted directly from the kernel.
870Any third-party network software running
871in the host environment should also be checked and configured so that it
872does not bind all IP addresses, which would result in those services' also
873appearing to be offered by the jail environments.
874.Pp
875Once
876these daemons have been disabled or fixed in the host environment, it is
877best to reboot so that all daemons are in a known state, to reduce the
878potential for confusion later (such as finding that when you send mail
879to a jail, and its sendmail is down, the mail is delivered to the host,
880etc.).
881.Ss "Configuring the Jail"
882Start any jail for the first time without configuring the network
883interface so that you can clean it up a little and set up accounts.
884As
885with any machine (virtual or not) you will need to set a root password, time
886zone, etc.
887Some of these steps apply only if you intend to run a full virtual server
888inside the jail; others apply both for constraining a particular application
889or for running a virtual server.
890.Pp
891Start a shell in the jail:
892.Bd -literal -offset indent
893jail -c path=/data/jail/testjail mount.devfs host.hostname=testhostname \\
894 ip4.addr=192.0.2.100 command=/bin/sh
895.Ed
896.Pp
897Assuming no errors, you will end up with a shell prompt within the jail.
898You can now run
899.Pa /usr/sbin/sysinstall
900and do the post-install configuration to set various configuration options,
901or perform these actions manually by editing
902.Pa /etc/rc.conf ,
903etc.
904.Pp
905.Bl -bullet -offset indent -compact
906.It
907Configure
908.Pa /etc/resolv.conf
909so that name resolution within the jail will work correctly
910.It
911Run
912.Xr newaliases 1
913to quell
914.Xr sendmail 8
915warnings.
916.It
917Set a root password, probably different from the real host system
918.It
919Set the timezone
920.It
921Add accounts for users in the jail environment
922.It
923Install any packages the environment requires
924.El
925.Pp
926You may also want to perform any package-specific configuration (web servers,
927SSH servers, etc), patch up
928.Pa /etc/syslog.conf
929so it logs as you would like, etc.
930If you are not using a virtual server, you may wish to modify
931.Xr syslogd 8
932in the host environment to listen on the syslog socket in the jail
933environment; in this example, the syslog socket would be stored in
934.Pa /data/jail/testjail/var/run/log .
935.Pp
936Exit from the shell, and the jail will be shut down.
937.Ss "Starting the Jail"
938You are now ready to restart the jail and bring up the environment with
939all of its daemons and other programs.
940Create an entry for the jail in
941.Pa /etc/jail.conf :
942.Bd -literal -offset indent
943testjail {
944 path = /tmp/jail/testjail;
945 mount.devfs;
946 host.hostname = testhostname;
947 ip4.addr = 192.0.2.100;
948 interface = ed0;
949 exec.start = "/bin/sh /etc/rc";
950 exec.stop = "/bin/sh /etc/rc.shutdown";
951}
952.Ed
953.Pp
954To start a virtual server environment,
955.Pa /etc/rc
956is run to launch various daemons and services, and
957.Pa /etc/rc.shutdown
958is run to shut them down when the jail is removed.
959If you are running a single application in the jail,
960substitute the command used to start the application for
961.Dq /bin/sh /etc/rc ;
962there may be some script available to cleanly shut down the application,
963or it may be sufficient to go without a stop command, and have
964.Nm
965send
966.Dv SIGTERM
967to the application.
968.Pp
969Start the jail by running:
970.Bd -literal -offset indent
971jail -c testjail
972.Ed
973.Pp
974A few warnings may be produced; however, it should all work properly.
975You should be able to see
976.Xr inetd 8 ,
977.Xr syslogd 8 ,
978and other processes running within the jail using
979.Xr ps 1 ,
980with the
981.Ql J
982flag appearing beside jailed processes.
983To see an active list of jails, use the
984.Xr jls 8
985utility.
986You should also be able to
987.Xr telnet 1
988to the hostname or IP address of the jailed environment, and log
989in using the accounts you created previously.
990.Pp
991It is possible to have jails started at boot time.
992Please refer to the
993.Dq jail_*
994variables in
995.Xr rc.conf 5
996for more information.
997.Ss "Managing the Jail"
998Normal machine shutdown commands, such as
999.Xr halt 8 ,
1000.Xr reboot 8 ,
1001and
1002.Xr shutdown 8 ,
1003cannot be used successfully within the jail.
1004To kill all processes from within a jail, you may use one of the
1005following commands, depending on what you want to accomplish:
1006.Bd -literal -offset indent
1007kill -TERM -1
1008kill -KILL -1
1009.Ed
1010.Pp
1011This will send the
1012.Dv SIGTERM
1013or
1014.Dv SIGKILL
1015signals to all processes in the jail - be careful not to run this from
1016the host environment!
1017Once all of the jail's processes have died, unless the jail was created
1018with the
1019.Va persist
1020parameter, the jail will be removed.
1021Depending on
1022the intended use of the jail, you may also want to run
1023.Pa /etc/rc.shutdown
1024from within the jail.
1025.Pp
1026To shut down the jail from the outside, simply remove it with
1027.Nm
1028.Ar -r ,
1029which will run any commands specified by
1030.Va exec.stop ,
1031and then send
1032.Dv SIGTERM
1033and eventually
1034.Dv SIGKILL
1035to any remaining jailed processes.
1036.Pp
1037The
1038.Pa /proc/ Ns Ar pid Ns Pa /status
1039file contains, as its last field, the name of the jail in which the
1040process runs, or
1041.Dq Li -
1042to indicate that the process is not running within a jail.
1043The
1044.Xr ps 1
1045command also shows a
1046.Ql J
1047flag for processes in a jail.
1048.Pp
1049You can also list/kill processes based on their jail ID.
1050To show processes and their jail ID, use the following command:
1051.Pp
1052.Dl "ps ax -o pid,jid,args"
1053.Pp
1054To show and then kill processes in jail number 3 use the following commands:
1055.Bd -literal -offset indent
1056pgrep -lfj 3
1057pkill -j 3
1058.Ed
1059or:
1060.Pp
1061.Dl "killall -j 3"
1062.Ss "Jails and File Systems"
1063It is not possible to
1064.Xr mount 8
1065or
1066.Xr umount 8
1067any file system inside a jail unless the file system is marked
1068jail-friendly, the jail's
1069.Va allow.mount
1070parameter is set and the jail's
1071.Va enforce_statfs
1072parameter is lower than 2.
1073.Pp
1074Multiple jails sharing the same file system can influence each other.
1075For example a user in one jail can fill the file system also
1076leaving no space for processes in the other jail.
1077Trying to use
1078.Xr quota 1
1079to prevent this will not work either as the file system quotas
1080are not aware of jails but only look at the user and group IDs.
1081This means the same user ID in two jails share the same file
1082system quota.
1083One would need to use one file system per jail to make this work.
1084.Ss "Sysctl MIB Entries"
1085The read-only entry
1086.Va security.jail.jailed
1087can be used to determine if a process is running inside a jail (value
1088is one) or not (value is zero).
1089.Pp
1090The variable
1091.Va security.jail.max_af_ips
1092determines how may address per address family a prison may have.
1093The default is 255.
1094.Pp
1095Some MIB variables have per-jail settings.
1096Changes to these variables by a jailed process do not effect the host
1097environment, only the jail environment.
1098These variables are
1099.Va kern.securelevel ,
1100.Va kern.hostname ,
1101.Va kern.domainname ,
1102.Va kern.hostid ,
1103and
1104.Va kern.hostuuid .
1105.Ss "Hierarchical Jails"
1106By setting a jail's
1107.Va children.max
1108parameter, processes within a jail may be able to create jails of their own.
1109These child jails are kept in a hierarchy, with jails only able to see and/or
1110modify the jails they created (or those jails' children).
1111Each jail has a read-only
1112.Va parent
1113parameter, containing the
1114.Va jid
1115of the jail that created it; a
1116.Va jid
1117of 0 indicates the jail is a child of the current jail (or is a top-level
1118jail if the current process isn't jailed).
1119.Pp
1120Jailed processes are not allowed to confer greater permissions than they
1121themselves are given, e.g. if a jail is created with
1122.Va allow.nomount ,
1123it is not able to create a jail with
1124.Va allow.mount
1125set.
1126Similarly, such restrictions as
1127.Va ip4.addr
1128and
1129.Va securelevel
1130may not be bypassed in child jails.
1131.Pp
1132A child jail may in turn create its own child jails if its own
1133.Va children.max
1134parameter is set (remember it is zero by default).
1135These jails are visible to and can be modified by their parent and all
1136ancestors.
1137.Pp
1138Jail names reflect this hierarchy, with a full name being an MIB-type string
1139separated by dots.
1140For example, if a base system process creates a jail
1141.Dq foo ,
1142and a process under that jail creates another jail
1143.Dq bar ,
1144then the second jail will be seen as
1145.Dq foo.bar
1146in the base system (though it is only seen as
1147.Dq bar
1148to any processes inside jail
1149.Dq foo ) .
1150Jids on the other hand exist in a single space, and each jail must have a
1151unique jid.
1152.Pp
1153Like the names, a child jail's
1154.Va path
1155appears relative to its creator's own
1156.Va path .
1157This is by virtue of the child jail being created in the chrooted
1158environment of the first jail.
1159.Sh SEE ALSO
1160.Xr killall 1 ,
1161.Xr lsvfs 1 ,
1162.Xr newaliases 1 ,
1163.Xr pgrep 1 ,
1164.Xr pkill 1 ,
1165.Xr ps 1 ,
1166.Xr quota 1 ,
1167.Xr jail_set 2 ,
1168.Xr jail.conf 5 ,
1169.Xr procfs 5 ,
1170.Xr rc.conf 5 ,
1171.Xr sysctl.conf 5 ,
1172.Xr chroot 8 ,
1173.Xr devfs 8 ,
1174.Xr halt 8 ,
1175.Xr inetd 8 ,
1176.Xr jexec 8 ,
1177.Xr jls 8 ,
1178.Xr mount 8 ,
1179.Xr named 8 ,
1180.Xr reboot 8 ,
1181.Xr rpcbind 8 ,
1182.Xr sendmail 8 ,
1183.Xr shutdown 8 ,
1184.Xr sysctl 8 ,
1185.Xr syslogd 8 ,
1186.Xr umount 8
1187.Sh HISTORY
1188The
1189.Nm
1190utility appeared in
1191.Fx 4.0 .
1192Hierarchical/extensible jails were introduced in
1193.Fx 8.0 .
1194The configuration file was introduced in
1195.Fx 9.1 .
1196.Sh AUTHORS
1197.An -nosplit
1198The jail feature was written by
1199.An Poul-Henning Kamp
1200for R&D Associates
1201.Pa http://www.rndassociates.com/
1202who contributed it to
1203.Fx .
1204.Pp
1205.An Robert Watson
1206wrote the extended documentation, found a few bugs, added
1207a few new features, and cleaned up the userland jail environment.
1208.Pp
1209.An Bjoern A. Zeeb
1210added multi-IP jail support for IPv4 and IPv6 based on a patch
1211originally done by
1212.An Pawel Jakub Dawidek
1213for IPv4.
1214.Pp
1215.An James Gritton
1216added the extensible jail parameters, hierarchical jails,
1217and the configuration file.
1218.Sh BUGS
1219It might be a good idea to add an
1220address alias flag such that daemons listening on all IPs
1221.Pq Dv INADDR_ANY
1222will not bind on that address, which would facilitate building a safe
1223host environment such that host daemons do not impose on services offered
1224from within jails.
1225Currently, the simplest answer is to minimize services
1226offered on the host, possibly limiting it to services offered from
1227.Xr inetd 8
1228which is easily configurable.
1229.Sh NOTES
1230Great care should be taken when managing directories visible within the jail.
1231For example, if a jailed process has its current working directory set to a
1232directory that is moved out of the jail's chroot, then the process may gain
1233access to the file space outside of the jail.
1234It is recommended that directories always be copied, rather than moved, out
1235of a jail.
1236.Pp
1237In addition, there are several ways in which an unprivileged user
1238outside the jail can cooperate with a privileged user inside the jail
1239and thereby obtain elevated privileges in the host environment.
1240Most of these attacks can be mitigated by ensuring that the jail root
1241is not accessible to unprivileged users in the host environment.
1242Regardless, as a general rule, untrusted users with privileged access
1243to a jail should not be given access to the host environment.
2.\" Copyright (c) 2008-2012 James Gritton
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.\" $FreeBSD: head/usr.sbin/jail/jail.8 254741 2013-08-23 22:52:20Z delphij $
27.\"
28.Dd August 23, 2013
29.Dt JAIL 8
30.Os
31.Sh NAME
32.Nm jail
33.Nd "manage system jails"
34.Sh SYNOPSIS
35.Nm
36.Op Fl dhilqv
37.Op Fl J Ar jid_file
38.Op Fl u Ar username
39.Op Fl U Ar username
40.Op Fl cmr
41.Ar param Ns = Ns Ar value ...
42.Op Cm command Ns = Ns Ar command ...
43.Nm
44.Op Fl dqv
45.Op Fl f Ar conf_file
46.Op Fl p Ar limit
47.Op Fl cmr
48.Op Ar jail
49.Nm
50.Op Fl qv
51.Op Fl f Ar conf_file
52.Op Fl rR
53.Op Cm * | Ar jail ...
54.Nm
55.Op Fl dhilqv
56.Op Fl J Ar jid_file
57.Op Fl u Ar username
58.Op Fl U Ar username
59.Op Fl n Ar jailname
60.Op Fl s Ar securelevel
61.Op Ar path hostname [ Ar ip Ns [ Ns Ar ,... Ns ]] Ar command ...
62.Sh DESCRIPTION
63The
64.Nm
65utility creates new jails, or modifies or removes existing jails.
66A jail is specified via parameters on the command line, or in the
67.Xr jail.conf 5
68file.
69.Pp
70At least one of the options
71.Fl c ,
72.Fl m
73or
74.Fl r
75must be specified.
76These options are used alone or in combination describe the operation to
77perform:
78.Bl -tag -width indent
79.It Fl c
80Create a new jail.
81The jail
82.Va jid
83and
84.Va name
85parameters (if specified) on the command line,
86or any jails
87must not refer to an existing jail.
88.It Fl m
89Modify an existing jail.
90One of the
91.Va jid
92or
93.Va name
94parameters must exist and refer to an existing jail.
95Some parameters may not be changed on a running jail.
96.It Fl r
97Remove the
98.Ar jail
99specified by jid or name.
100All jailed processes are killed, and all children of this jail are also
101removed.
102.It Fl rc
103Restart an existing jail.
104The jail is first removed and then re-created, as if
105.Dq Nm Fl c
106and
107.Dq Nm Fl r
108were run in succession.
109.It Fl cm
110Create a jail if it does not exist, or modify the jail if it does exist.
111.It Fl mr
112Modify an existing jail.
113The jail may be restarted if necessary to modify parameters than could
114not otherwise be changed.
115.It Fl cmr
116Create a jail if it doesn't exist, or modify (and possibly restart) the
117jail if it does exist.
118.El
119.Pp
120Other available options are:
121.Bl -tag -width indent
122.It Fl d
123Allow making changes to a dying jail, equivalent to the
124.Va allow.dying
125parameter.
126.It Fl f Ar conf_file
127Use configuration file
128.Ar conf_file
129instead of the default
130.Pa /etc/jail.conf .
131.It Fl h
132Resolve the
133.Va host.hostname
134parameter (or
135.Va hostname )
136and add all IP addresses returned by the resolver
137to the list of addresses for this prison.
138This is equivalent to the
139.Va ip_hostname
140parameter.
141.It Fl i
142Output (only) the jail identifier of the newly created jail(s).
143This implies the
144.Fl q
145option.
146.It Fl J Ar jid_file
147Write a
148.Ar jid_file
149file, containing parameters used to start the jail.
150.It Fl l
151Run commands in a clean environment.
152This is deprecated and is equivalent to the exec.clean parameter.
153.It Fl n Ar jailname
154Set the jail's name.
155This is deprecated and is equivalent to the
156.Va name
157parameter.
158.It Fl p Ar limit
159Limit the number of commands from
160.Va exec.*
161that can run simultaneously.
162.It Fl q
163Suppress the message printed whenever a jail is created, modified or removed.
164Only error messages will be printed.
165.It Fl R
166A variation of the
167.Fl r
168option that removes an existing jail without using the configuration file.
169No removal-related parameters for this jail will be used - the jail will
170simply be removed.
171.It Fl s Ar securelevel
172Set the
173.Va kern.securelevel
174MIB entry to the specified value inside the newly created jail.
175This is deprecated and is equivalent to the
176.Va securelevel
177parameter.
178.It Fl u Ar username
179The user name from host environment as whom jailed commands should run.
180This is deprecated and is equivalent to the
181.Va exec.jail_user
182and
183.Va exec.system_jail_user
184parameters.
185.It Fl U Ar username
186The user name from jailed environment as whom jailed commands should run.
187This is deprecated and is equivalent to the
188.Va exec.jail_user
189parameter.
190.It Fl v
191Print a message on every operation, such as running commands and
192mounting filesystems.
193.El
194.Pp
195If no arguments are given after the options, the operation (except
196remove) will be performed on all jails specified in the
197.Xr jail.conf 5
198file.
199A single argument of a jail name will operate only on the specified jail.
200The
201.Fl r
202and
203.Fl R
204options can also remove running jails that aren't in the
205.Xr jail.conf 5
206file, specified by name or jid.
207.Pp
208An argument of
209.Dq *
210is a wildcard that will operate on all jails, regardless of whether
211they appear in
212.Xr jail.conf 5 ;
213this is the surest way for
214.Fl r
215to remove all jails.
216If hierarchical jails exist, a partial-matching wildcard definition may
217be specified.
218For example, an argument of
219.Dq foo.*
220would apply to jails with names like
221.Dq foo.bar
222and
223.Dq foo.bar.baz .
224.Pp
225A jail may be specified with parameters directly on the command line.
226In this case, the
227.Xr jail.conf 5
228file will not be used.
229For backward compatibility, the command line may also have four fixed
230parameters, without names:
231.Ar path ,
232.Ar hostname ,
233.Ar ip ,
234and
235.Ar command .
236This mode will always create a new jail, and the
237.Fl c
238and
239.Fl m
240options don't apply (and must not exist).
241.Ss Jail Parameters
242Parameters in the
243.Xr jail.conf 5
244file, or on the command line, are generally in
245.Dq name=value
246form.
247Some parameters are boolean, and do not have a value but are set by the
248name alone with or without a
249.Dq no
250prefix, e.g.
251.Va persist
252or
253.Va nopersist .
254They can also be given the values
255.Dq true
256and
257.Dq false .
258Other parameters may have more than one value, specified as a
259comma-separated list or with
260.Dq +=
261in the configuration file (see
262.Xr jail.conf 5
263for details).
264.Pp
265The
266.Nm
267utility recognizes two classes of parameters. There are the true jail
268parameters that are passed to the kernel when the jail is created,
269can be seen with
270.Xr jls 8 ,
271and can (usually) be changed with
272.Dq Nm Fl m .
273Then there are pseudo-parameters that are only used by
274.Nm
275itself.
276.Pp
277Jails have a set a core parameters, and kernel modules can add their own
278jail parameters.
279The current set of available parameters can be retrieved via
280.Dq Nm sysctl Fl d Va security.jail.param .
281Any parameters not set will be given default values, often based on the
282current environment.
283The core parameters are:
284.Bl -tag -width indent
285.It Va jid
286The jail identifier.
287This will be assigned automatically to a new jail (or can be explicitly
288set), and can be used to identify the jail for later modification, or
289for such commands as
290.Xr jls 8
291or
292.Xr jexec 8 .
293.It Va name
294The jail name.
295This is an arbitrary string that identifies a jail (except it may not
296contain a
297.Sq \&. ) .
298Like the
299.Va jid ,
300it can be passed to later
301.Nm
302commands, or to
303.Xr jls 8
304or
305.Xr jexec 8 .
306If no
307.Va name
308is supplied, a default is assumed that is the same as the
309.Va jid .
310The
311.Va name
312parameter is implied by the
313.Xr jail.conf 5
314file format, and need not be explicitly set when using the configuration
315file.
316.It Va path
317The directory which is to be the root of the prison.
318Any commands run inside the prison, either by
319.Nm
320or from
321.Xr jexec 8 ,
322are run from this directory.
323.It Va ip4.addr
324A list of IPv4 addresses assigned to the prison.
325If this is set, the jail is restricted to using only these addresses.
326Any attempts to use other addresses fail, and attempts to use wildcard
327addresses silently use the jailed address instead.
328For IPv4 the first address given will be kept used as the source address
329in case source address selection on unbound sockets cannot find a better
330match.
331It is only possible to start multiple jails with the same IP address,
332if none of the jails has more than this single overlapping IP address
333assigned to itself.
334.It Va ip4.saddrsel
335A boolean option to change the formerly mentioned behaviour and disable
336IPv4 source address selection for the prison in favour of the primary
337IPv4 address of the jail.
338Source address selection is enabled by default for all jails and the
339.Va ip4.nosaddrsel
340setting of a parent jail is not inherited for any child jails.
341.It Va ip4
342Control the availability of IPv4 addresses.
343Possible values are
344.Dq inherit
345to allow unrestricted access to all system addresses,
346.Dq new
347to restrict addresses via
348.Va ip4.addr
349above, and
350.Dq disable
351to stop the jail from using IPv4 entirely.
352Setting the
353.Va ip4.addr
354parameter implies a value of
355.Dq new .
356.It Va ip6.addr , Va ip6.saddrsel , Va ip6
357A set of IPv6 options for the prison, the counterparts to
358.Va ip4.addr ,
359.Va ip4.saddrsel
360and
361.Va ip4
362above.
363.It vnet
364Create the prison with its own virtual network stack,
365with its own network interfaces, addresses, routing table, etc.
366The kernel must have been compiled with the
367.Sy VIMAGE option
368for this to be available.
369Possible values are
370.Dq inherit
371to use the system network stack, possibly with restricted IP addresses,
372and
373.Dq new
374to create a new network stack.
375.It Va host.hostname
376The hostname of the prison.
377Other similar parameters are
378.Va host.domainname ,
379.Va host.hostuuid
380and
381.Va host.hostid .
382.It Va host
383Set the origin of hostname and related information.
384Possible values are
385.Dq inherit
386to use the system information and
387.Dq new
388for the jail to use the information from the above fields.
389Setting any of the above fields implies a value of
390.Dq new .
391.It Va securelevel
392The value of the jail's
393.Va kern.securelevel
394sysctl.
395A jail never has a lower securelevel than the default system, but by
396setting this parameter it may have a higher one.
397If the system securelevel is changed, any jail securelevels will be at
398least as secure.
399.It Va devfs_ruleset
400The number of the devfs ruleset that is enforced for mounting devfs in
401this jail.
402A value of zero (default) means no ruleset is enforced.
403Descendant jails inherit the parent jail's devfs ruleset enforcement.
404Mounting devfs inside a jail is possible only if the
405.Va allow.mount
406and
407.Va allow.mount.devfs
408permissions are effective and
409.Va enforce_statfs
410is set to a value lower than 2.
411Devfs rules and rulesets cannot be viewed or modified from inside a jail.
412.Pp
413NOTE: It is important that only appropriate device nodes in devfs be
414exposed to a jail; access to disk devices in the jail may permit processes
415in the jail to bypass the jail sandboxing by modifying files outside of
416the jail.
417See
418.Xr devfs 8
419for information on how to use devfs rules to limit access to entries
420in the per-jail devfs.
421A simple devfs ruleset for jails is available as ruleset #4 in
422.Pa /etc/defaults/devfs.rules .
423.It Va children.max
424The number of child jails allowed to be created by this jail (or by
425other jails under this jail).
426This limit is zero by default, indicating the jail is not allowed to
427create child jails.
428See the
429.Sx "Hierarchical Jails"
430section for more information.
431.It Va children.cur
432The number of descendants of this jail, including its own child jails
433and any jails created under them.
434.It Va enforce_statfs
435This determines which information processes in a jail are able to get
436about mount points.
437It affects the behaviour of the following syscalls:
438.Xr statfs 2 ,
439.Xr fstatfs 2 ,
440.Xr getfsstat 2
441and
442.Xr fhstatfs 2
443(as well as similar compatibility syscalls).
444When set to 0, all mount points are available without any restrictions.
445When set to 1, only mount points below the jail's chroot directory are
446visible.
447In addition to that, the path to the jail's chroot directory is removed
448from the front of their pathnames.
449When set to 2 (default), above syscalls can operate only on a mount-point
450where the jail's chroot directory is located.
451.It Va persist
452Setting this boolean parameter allows a jail to exist without any
453processes.
454Normally, a command is run as part of jail creation, and then the jail
455is destroyed as its last process exits.
456A new jail must have either the
457.Va persist
458parameter or
459.Va exec.start
460or
461.Va command
462pseudo-parameter set.
463.It Va cpuset.id
464The ID of the cpuset associated with this jail (read-only).
465.It Va dying
466This is true if the jail is in the process of shutting down (read-only).
467.It Va parent
468The
469.Va jid
470of the parent of this jail, or zero if this is a top-level jail
471(read-only).
472.It Va allow.*
473Some restrictions of the jail environment may be set on a per-jail
474basis.
475With the exception of
476.Va allow.set_hostname ,
477these boolean parameters are off by default.
478.Bl -tag -width indent
479.It Va allow.set_hostname
480The jail's hostname may be changed via
481.Xr hostname 1
482or
483.Xr sethostname 3 .
484.It Va allow.sysvipc
485A process within the jail has access to System V IPC primitives.
486In the current jail implementation, System V primitives share a single
487namespace across the host and jail environments, meaning that processes
488within a jail would be able to communicate with (and potentially interfere
489with) processes outside of the jail, and in other jails.
490.It Va allow.raw_sockets
491The prison root is allowed to create raw sockets.
492Setting this parameter allows utilities like
493.Xr ping 8
494and
495.Xr traceroute 8
496to operate inside the prison.
497If this is set, the source IP addresses are enforced to comply
498with the IP address bound to the jail, regardless of whether or not
499the
500.Dv IP_HDRINCL
501flag has been set on the socket.
502Since raw sockets can be used to configure and interact with various
503network subsystems, extra caution should be used where privileged access
504to jails is given out to untrusted parties.
505.It Va allow.chflags
506Normally, privileged users inside a jail are treated as unprivileged by
507.Xr chflags 2 .
508When this parameter is set, such users are treated as privileged, and
509may manipulate system file flags subject to the usual constraints on
510.Va kern.securelevel .
511.It Va allow.mount
512privileged users inside the jail will be able to mount and unmount file
513system types marked as jail-friendly.
514The
515.Xr lsvfs 1
516command can be used to find file system types available for mount from
517within a jail.
518This permission is effective only if
519.Va enforce_statfs
520is set to a value lower than 2.
521.It Va allow.mount.devfs
522privileged users inside the jail will be able to mount and unmount the
523devfs file system.
524This permission is effective only together with
525.Va allow.mount
526and if
527.Va enforce_statfs
528is set to a value lower than 2.
529Please consider restricting the devfs ruleset with the
530.Va devfs_ruleset
531option.
532.It Va allow.mount.nullfs
533privileged users inside the jail will be able to mount and unmount the
534nullfs file system.
535This permission is effective only together with
536.Va allow.mount
537and if
538.Va enforce_statfs
539is set to a value lower than 2.
540.It Va allow.mount.procfs
541privileged users inside the jail will be able to mount and unmount the
542procfs file system.
543This permission is effective only together with
544.Va allow.mount
545and if
546.Va enforce_statfs
547is set to a value lower than 2.
548.It Va allow.mount.tmpfs
549privileged users inside the jail will be able to mount and unmount the
550tmpfs file system.
551This permission is effective only together with
552.Va allow.mount
553and if
554.Va enforce_statfs
555is set to a value lower than 2.
556.It Va allow.mount.zfs
557privileged users inside the jail will be able to mount and unmount the
558ZFS file system.
559This permission is effective only together with
560.Va allow.mount
561and if
562.Va enforce_statfs
563is set to a value lower than 2.
564See
565.Xr zfs 8
566for information on how to configure the ZFS filesystem to operate from
567within a jail.
568.It Va allow.quotas
569The prison root may administer quotas on the jail's filesystem(s).
570This includes filesystems that the jail may share with other jails or
571with non-jailed parts of the system.
572.It Va allow.socket_af
573Sockets within a jail are normally restricted to IPv4, IPv6, local
574(UNIX), and route. This allows access to other protocol stacks that
575have not had jail functionality added to them.
576.El
577.El
578.Pp
579There are pseudo-parameters that aren't passed to the kernel, but are
580used by
581.Nm
582to set up the prison environment, often by running specified commands
583when jails are created or removed.
584The
585.Va exec.*
586command parameters are
587.Xr sh 1
588command lines that are run in either the system or prison environment.
589They may be given multiple values, which run would the specified
590commands in sequence.
591All commands must succeed (return a zero exit status), or the jail will
592not be created or removed.
593.Pp
594The pseudo-parameters are:
595.Bl -tag -width indent
596.It Va exec.prestart
597Command(s) to run in the system environment before a prison is created.
598.It Va exec.start
599Command(s) to run in the prison environment when a jail is created.
600A typical command to run is
601.Dq sh /etc/rc .
602.It Va command
603A synonym for
604.Va exec.start
605for use when specifying a prison directly on the command line.
606Unlike other parameters whose value is a single string,
607.Va command
608uses the remainder of the
609.Nm
610command line as its own arguments.
611.It Va exec.poststart
612Command(s) to run in the system environment after a jail is created,
613and after any
614.Va exec.start
615commands have completed.
616.It Va exec.prestop
617Command(s) to run in the system environment before a jail is removed.
618.It Va exec.stop
619Command(s) to run in the prison environment before a jail is removed,
620and after any
621.Va exec.prestop
622commands have completed.
623A typical command to run is
624.Dq sh /etc/rc.shutdown .
625.It Va exec.poststop
626Command(s) to run in the system environment after a jail is removed.
627.It Va exec.clean
628Run commands in a clean environment.
629The environment is discarded except for
630.Ev HOME , SHELL , TERM
631and
632.Ev USER .
633.Ev HOME
634and
635.Ev SHELL
636are set to the target login's default values.
637.Ev USER
638is set to the target login.
639.Ev TERM
640is imported from the current environment.
641The environment variables from the login class capability database for the
642target login are also set.
643.It Va exec.jail_user
644The user to run commands as, when running in the prison environment.
645The default is to run the commands as the current user.
646.It Va exec.system_jail_user
647This boolean option looks for the
648.Va exec.jail_user
649in the system
650.Xr passwd 5
651file, instead of in the prison's file.
652.It Va exec.system_user
653The user to run commands as, when running in the system environment.
654The default is to run the commands as the current user.
655.It Va exec.timeout
656The maximum amount of time to wait for a command to complete.
657If a command is still running after this many seconds have passed,
658the jail not be created or removed.
659.It Va exec.consolelog
660A file to direct command output (stdout and stderr) to.
661.It Va exec.fib
662The FIB (routing table) to set when running commands inside the prison.
663.It Va stop.timeout
664The maximum amount of time to wait for a prison's processes to exit
665after sending them a
666.Dv SIGTERM
667signal (which happens after the
668.Va exec.stop
669commands have completed).
670After this many seconds have passed, the prison will be removed, which
671will kill any remaining processes.
672If this is set to zero, no
673.Dv SIGTERM
674is sent and the prison is immediately removed.
675The default is 10 seconds.
676.It Va interface
677A network interface to add the prison's IP addresses
678.Va ( ip4.addr
679and
680.Va ip6.addr )
681to.
682An alias for each address will be added to the interface before the
683prison is created, and will be removed from the interface after the
684prison is removed.
685.It Op Va ip4.addr
686In addition to the IP addresses that are passed to the kernel, and
687interface and/or a netmask may also be specified, in the form
688.Dq Ar interface Ns | Ns Ar ip-address Ns / Ns Ar netmask .
689If an interface is given before the IP address, an alias for the address
690will be added to that interface, as it is with the
691.Va interface
692parameter. If a netmask in either dotted-quad or CIDR form is given
693after IP address, it will be used when adding the IP alias.
694.It Op Va ip6.addr
695In addition to the IP addresses that are passed to the kernel,
696and interface and/or a prefix may also be specified, in the form
697.Dq Ar interface Ns | Ns Ar ip-address Ns / Ns Ar prefix .
698.It Va vnet.interface
699A network interface to give to a vnet-enabled jail after is it created.
700The interface will automatically be returned when the jail is removed.
701.It Va ip_hostname
702Resolve the
703.Va host.hostname
704parameter and add all IP addresses returned by the resolver
705to the list of addresses
706.Va ( ip4.addr
707or
708.Va ip6.addr )
709for this prison.
710This may affect default address selection for outgoing IPv4 connections
711of prisons.
712The address first returned by the resolver for each address family
713will be used as primary address.
714.It Va mount
715A filesystem to mount before creating the jail (and to unmount after
716removing it), given as a single
717.Xr fstab 5
718line.
719.It Va mount.fstab
720An
721.Xr fstab 5
722format file containing filesystems to mount before creating a jail.
723.It Va mount.devfs
724Mount a
725.Xr devfs
726filesystem on the chrooted /dev directory, and apply the ruleset in the
727.Va devfs_ruleset
728parameter (or a default of ruleset 4: devfsrules_jail)
729to restrict the devices visible inside the prison.
730.It Va allow.dying
731Allow making changes to a
732.Va dying
733jail.
734.It Va depend
735Specify a jail (or jails) that this jail depends on.
736Any such jails must be fully created, up to the last
737.Va exec.poststart
738command, before any action will taken to create this jail.
739When jails are removed the opposite is true:
740this jail must be fully removed, up to the last
741.Va exec.poststop
742command, before the jail(s) it depends on are stopped.
743.El
744.Sh EXAMPLES
745Jails are typically set up using one of two philosophies: either to
746constrain a specific application (possibly running with privilege), or
747to create a
748.Dq "virtual system image"
749running a variety of daemons and services.
750In both cases, a fairly complete file system install of
751.Fx
752is
753required, so as to provide the necessary command line tools, daemons,
754libraries, application configuration files, etc.
755However, for a virtual server configuration, a fair amount of
756additional work is required so as to configure the
757.Dq boot
758process.
759This manual page documents the configuration steps necessary to support
760either of these steps, although the configuration steps may be
761refined based on local requirements.
762.Ss "Setting up a Jail Directory Tree"
763To set up a jail directory tree containing an entire
764.Fx
765distribution, the following
766.Xr sh 1
767command script can be used:
768.Bd -literal
769D=/here/is/the/jail
770cd /usr/src
771mkdir -p $D
772make world DESTDIR=$D
773make distribution DESTDIR=$D
774.Ed
775.Pp
776In many cases this example would put far more in the jail than needed.
777In the other extreme case a jail might contain only one file:
778the executable to be run in the jail.
779.Pp
780We recommend experimentation and caution that it is a lot easier to
781start with a
782.Dq fat
783jail and remove things until it stops working,
784than it is to start with a
785.Dq thin
786jail and add things until it works.
787.Ss "Setting Up a Jail"
788Do what was described in
789.Sx "Setting Up a Jail Directory Tree"
790to build the jail directory tree.
791For the sake of this example, we will
792assume you built it in
793.Pa /data/jail/testjail ,
794for a jail named
795.Dq testjail .
796Substitute below as needed with your
797own directory, IP address, and hostname.
798.Ss "Setting up the Host Environment"
799First, you will want to set up your real system's environment to be
800.Dq jail-friendly .
801For consistency, we will refer to the parent box as the
802.Dq "host environment" ,
803and to the jailed virtual machine as the
804.Dq "jail environment" .
805Since jail is implemented using IP aliases, one of the first things to do
806is to disable IP services on the host system that listen on all local
807IP addresses for a service.
808If a network service is present in the host environment that binds all
809available IP addresses rather than specific IP addresses, it may service
810requests sent to jail IP addresses if the jail did not bind the port.
811This means changing
812.Xr inetd 8
813to only listen on the
814appropriate IP address, and so forth.
815Add the following to
816.Pa /etc/rc.conf
817in the host environment:
818.Bd -literal -offset indent
819sendmail_enable="NO"
820inetd_flags="-wW -a 192.0.2.23"
821rpcbind_enable="NO"
822.Ed
823.Pp
824.Li 192.0.2.23
825is the native IP address for the host system, in this example.
826Daemons that run out of
827.Xr inetd 8
828can be easily set to use only the specified host IP address.
829Other daemons
830will need to be manually configured\(emfor some this is possible through
831the
832.Xr rc.conf 5
833flags entries; for others it is necessary to modify per-application
834configuration files, or to recompile the applications.
835The following frequently deployed services must have their individual
836configuration files modified to limit the application to listening
837to a specific IP address:
838.Pp
839To configure
840.Xr sshd 8 ,
841it is necessary to modify
842.Pa /etc/ssh/sshd_config .
843.Pp
844To configure
845.Xr sendmail 8 ,
846it is necessary to modify
847.Pa /etc/mail/sendmail.cf .
848.Pp
849For
850.Xr named 8 ,
851it is necessary to modify
852.Pa /etc/namedb/named.conf .
853.Pp
854In addition, a number of services must be recompiled in order to run
855them in the host environment.
856This includes most applications providing services using
857.Xr rpc 3 ,
858such as
859.Xr rpcbind 8 ,
860.Xr nfsd 8 ,
861and
862.Xr mountd 8 .
863In general, applications for which it is not possible to specify which
864IP address to bind should not be run in the host environment unless they
865should also service requests sent to jail IP addresses.
866Attempting to serve
867NFS from the host environment may also cause confusion, and cannot be
868easily reconfigured to use only specific IPs, as some NFS services are
869hosted directly from the kernel.
870Any third-party network software running
871in the host environment should also be checked and configured so that it
872does not bind all IP addresses, which would result in those services' also
873appearing to be offered by the jail environments.
874.Pp
875Once
876these daemons have been disabled or fixed in the host environment, it is
877best to reboot so that all daemons are in a known state, to reduce the
878potential for confusion later (such as finding that when you send mail
879to a jail, and its sendmail is down, the mail is delivered to the host,
880etc.).
881.Ss "Configuring the Jail"
882Start any jail for the first time without configuring the network
883interface so that you can clean it up a little and set up accounts.
884As
885with any machine (virtual or not) you will need to set a root password, time
886zone, etc.
887Some of these steps apply only if you intend to run a full virtual server
888inside the jail; others apply both for constraining a particular application
889or for running a virtual server.
890.Pp
891Start a shell in the jail:
892.Bd -literal -offset indent
893jail -c path=/data/jail/testjail mount.devfs host.hostname=testhostname \\
894 ip4.addr=192.0.2.100 command=/bin/sh
895.Ed
896.Pp
897Assuming no errors, you will end up with a shell prompt within the jail.
898You can now run
899.Pa /usr/sbin/sysinstall
900and do the post-install configuration to set various configuration options,
901or perform these actions manually by editing
902.Pa /etc/rc.conf ,
903etc.
904.Pp
905.Bl -bullet -offset indent -compact
906.It
907Configure
908.Pa /etc/resolv.conf
909so that name resolution within the jail will work correctly
910.It
911Run
912.Xr newaliases 1
913to quell
914.Xr sendmail 8
915warnings.
916.It
917Set a root password, probably different from the real host system
918.It
919Set the timezone
920.It
921Add accounts for users in the jail environment
922.It
923Install any packages the environment requires
924.El
925.Pp
926You may also want to perform any package-specific configuration (web servers,
927SSH servers, etc), patch up
928.Pa /etc/syslog.conf
929so it logs as you would like, etc.
930If you are not using a virtual server, you may wish to modify
931.Xr syslogd 8
932in the host environment to listen on the syslog socket in the jail
933environment; in this example, the syslog socket would be stored in
934.Pa /data/jail/testjail/var/run/log .
935.Pp
936Exit from the shell, and the jail will be shut down.
937.Ss "Starting the Jail"
938You are now ready to restart the jail and bring up the environment with
939all of its daemons and other programs.
940Create an entry for the jail in
941.Pa /etc/jail.conf :
942.Bd -literal -offset indent
943testjail {
944 path = /tmp/jail/testjail;
945 mount.devfs;
946 host.hostname = testhostname;
947 ip4.addr = 192.0.2.100;
948 interface = ed0;
949 exec.start = "/bin/sh /etc/rc";
950 exec.stop = "/bin/sh /etc/rc.shutdown";
951}
952.Ed
953.Pp
954To start a virtual server environment,
955.Pa /etc/rc
956is run to launch various daemons and services, and
957.Pa /etc/rc.shutdown
958is run to shut them down when the jail is removed.
959If you are running a single application in the jail,
960substitute the command used to start the application for
961.Dq /bin/sh /etc/rc ;
962there may be some script available to cleanly shut down the application,
963or it may be sufficient to go without a stop command, and have
964.Nm
965send
966.Dv SIGTERM
967to the application.
968.Pp
969Start the jail by running:
970.Bd -literal -offset indent
971jail -c testjail
972.Ed
973.Pp
974A few warnings may be produced; however, it should all work properly.
975You should be able to see
976.Xr inetd 8 ,
977.Xr syslogd 8 ,
978and other processes running within the jail using
979.Xr ps 1 ,
980with the
981.Ql J
982flag appearing beside jailed processes.
983To see an active list of jails, use the
984.Xr jls 8
985utility.
986You should also be able to
987.Xr telnet 1
988to the hostname or IP address of the jailed environment, and log
989in using the accounts you created previously.
990.Pp
991It is possible to have jails started at boot time.
992Please refer to the
993.Dq jail_*
994variables in
995.Xr rc.conf 5
996for more information.
997.Ss "Managing the Jail"
998Normal machine shutdown commands, such as
999.Xr halt 8 ,
1000.Xr reboot 8 ,
1001and
1002.Xr shutdown 8 ,
1003cannot be used successfully within the jail.
1004To kill all processes from within a jail, you may use one of the
1005following commands, depending on what you want to accomplish:
1006.Bd -literal -offset indent
1007kill -TERM -1
1008kill -KILL -1
1009.Ed
1010.Pp
1011This will send the
1012.Dv SIGTERM
1013or
1014.Dv SIGKILL
1015signals to all processes in the jail - be careful not to run this from
1016the host environment!
1017Once all of the jail's processes have died, unless the jail was created
1018with the
1019.Va persist
1020parameter, the jail will be removed.
1021Depending on
1022the intended use of the jail, you may also want to run
1023.Pa /etc/rc.shutdown
1024from within the jail.
1025.Pp
1026To shut down the jail from the outside, simply remove it with
1027.Nm
1028.Ar -r ,
1029which will run any commands specified by
1030.Va exec.stop ,
1031and then send
1032.Dv SIGTERM
1033and eventually
1034.Dv SIGKILL
1035to any remaining jailed processes.
1036.Pp
1037The
1038.Pa /proc/ Ns Ar pid Ns Pa /status
1039file contains, as its last field, the name of the jail in which the
1040process runs, or
1041.Dq Li -
1042to indicate that the process is not running within a jail.
1043The
1044.Xr ps 1
1045command also shows a
1046.Ql J
1047flag for processes in a jail.
1048.Pp
1049You can also list/kill processes based on their jail ID.
1050To show processes and their jail ID, use the following command:
1051.Pp
1052.Dl "ps ax -o pid,jid,args"
1053.Pp
1054To show and then kill processes in jail number 3 use the following commands:
1055.Bd -literal -offset indent
1056pgrep -lfj 3
1057pkill -j 3
1058.Ed
1059or:
1060.Pp
1061.Dl "killall -j 3"
1062.Ss "Jails and File Systems"
1063It is not possible to
1064.Xr mount 8
1065or
1066.Xr umount 8
1067any file system inside a jail unless the file system is marked
1068jail-friendly, the jail's
1069.Va allow.mount
1070parameter is set and the jail's
1071.Va enforce_statfs
1072parameter is lower than 2.
1073.Pp
1074Multiple jails sharing the same file system can influence each other.
1075For example a user in one jail can fill the file system also
1076leaving no space for processes in the other jail.
1077Trying to use
1078.Xr quota 1
1079to prevent this will not work either as the file system quotas
1080are not aware of jails but only look at the user and group IDs.
1081This means the same user ID in two jails share the same file
1082system quota.
1083One would need to use one file system per jail to make this work.
1084.Ss "Sysctl MIB Entries"
1085The read-only entry
1086.Va security.jail.jailed
1087can be used to determine if a process is running inside a jail (value
1088is one) or not (value is zero).
1089.Pp
1090The variable
1091.Va security.jail.max_af_ips
1092determines how may address per address family a prison may have.
1093The default is 255.
1094.Pp
1095Some MIB variables have per-jail settings.
1096Changes to these variables by a jailed process do not effect the host
1097environment, only the jail environment.
1098These variables are
1099.Va kern.securelevel ,
1100.Va kern.hostname ,
1101.Va kern.domainname ,
1102.Va kern.hostid ,
1103and
1104.Va kern.hostuuid .
1105.Ss "Hierarchical Jails"
1106By setting a jail's
1107.Va children.max
1108parameter, processes within a jail may be able to create jails of their own.
1109These child jails are kept in a hierarchy, with jails only able to see and/or
1110modify the jails they created (or those jails' children).
1111Each jail has a read-only
1112.Va parent
1113parameter, containing the
1114.Va jid
1115of the jail that created it; a
1116.Va jid
1117of 0 indicates the jail is a child of the current jail (or is a top-level
1118jail if the current process isn't jailed).
1119.Pp
1120Jailed processes are not allowed to confer greater permissions than they
1121themselves are given, e.g. if a jail is created with
1122.Va allow.nomount ,
1123it is not able to create a jail with
1124.Va allow.mount
1125set.
1126Similarly, such restrictions as
1127.Va ip4.addr
1128and
1129.Va securelevel
1130may not be bypassed in child jails.
1131.Pp
1132A child jail may in turn create its own child jails if its own
1133.Va children.max
1134parameter is set (remember it is zero by default).
1135These jails are visible to and can be modified by their parent and all
1136ancestors.
1137.Pp
1138Jail names reflect this hierarchy, with a full name being an MIB-type string
1139separated by dots.
1140For example, if a base system process creates a jail
1141.Dq foo ,
1142and a process under that jail creates another jail
1143.Dq bar ,
1144then the second jail will be seen as
1145.Dq foo.bar
1146in the base system (though it is only seen as
1147.Dq bar
1148to any processes inside jail
1149.Dq foo ) .
1150Jids on the other hand exist in a single space, and each jail must have a
1151unique jid.
1152.Pp
1153Like the names, a child jail's
1154.Va path
1155appears relative to its creator's own
1156.Va path .
1157This is by virtue of the child jail being created in the chrooted
1158environment of the first jail.
1159.Sh SEE ALSO
1160.Xr killall 1 ,
1161.Xr lsvfs 1 ,
1162.Xr newaliases 1 ,
1163.Xr pgrep 1 ,
1164.Xr pkill 1 ,
1165.Xr ps 1 ,
1166.Xr quota 1 ,
1167.Xr jail_set 2 ,
1168.Xr jail.conf 5 ,
1169.Xr procfs 5 ,
1170.Xr rc.conf 5 ,
1171.Xr sysctl.conf 5 ,
1172.Xr chroot 8 ,
1173.Xr devfs 8 ,
1174.Xr halt 8 ,
1175.Xr inetd 8 ,
1176.Xr jexec 8 ,
1177.Xr jls 8 ,
1178.Xr mount 8 ,
1179.Xr named 8 ,
1180.Xr reboot 8 ,
1181.Xr rpcbind 8 ,
1182.Xr sendmail 8 ,
1183.Xr shutdown 8 ,
1184.Xr sysctl 8 ,
1185.Xr syslogd 8 ,
1186.Xr umount 8
1187.Sh HISTORY
1188The
1189.Nm
1190utility appeared in
1191.Fx 4.0 .
1192Hierarchical/extensible jails were introduced in
1193.Fx 8.0 .
1194The configuration file was introduced in
1195.Fx 9.1 .
1196.Sh AUTHORS
1197.An -nosplit
1198The jail feature was written by
1199.An Poul-Henning Kamp
1200for R&D Associates
1201.Pa http://www.rndassociates.com/
1202who contributed it to
1203.Fx .
1204.Pp
1205.An Robert Watson
1206wrote the extended documentation, found a few bugs, added
1207a few new features, and cleaned up the userland jail environment.
1208.Pp
1209.An Bjoern A. Zeeb
1210added multi-IP jail support for IPv4 and IPv6 based on a patch
1211originally done by
1212.An Pawel Jakub Dawidek
1213for IPv4.
1214.Pp
1215.An James Gritton
1216added the extensible jail parameters, hierarchical jails,
1217and the configuration file.
1218.Sh BUGS
1219It might be a good idea to add an
1220address alias flag such that daemons listening on all IPs
1221.Pq Dv INADDR_ANY
1222will not bind on that address, which would facilitate building a safe
1223host environment such that host daemons do not impose on services offered
1224from within jails.
1225Currently, the simplest answer is to minimize services
1226offered on the host, possibly limiting it to services offered from
1227.Xr inetd 8
1228which is easily configurable.
1229.Sh NOTES
1230Great care should be taken when managing directories visible within the jail.
1231For example, if a jailed process has its current working directory set to a
1232directory that is moved out of the jail's chroot, then the process may gain
1233access to the file space outside of the jail.
1234It is recommended that directories always be copied, rather than moved, out
1235of a jail.
1236.Pp
1237In addition, there are several ways in which an unprivileged user
1238outside the jail can cooperate with a privileged user inside the jail
1239and thereby obtain elevated privileges in the host environment.
1240Most of these attacks can be mitigated by ensuring that the jail root
1241is not accessible to unprivileged users in the host environment.
1242Regardless, as a general rule, untrusted users with privileged access
1243to a jail should not be given access to the host environment.