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