xref: /freebsd/usr.sbin/jail/jail.8 (revision ab00ac327a66a53edaac95b536b209db3ae2cd9f)
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$
27.\"
28.Dd April 30, 2016
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 of 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 osrelease
475The string for the jail's
476.Va kern.osrelease
477sysctl and uname -r.
478.It Va osreldate
479The number for the jail's
480.Va kern.osreldate
481and uname -K.
482.It Va allow.*
483Some restrictions of the jail environment may be set on a per-jail
484basis.
485With the exception of
486.Va allow.set_hostname ,
487these boolean parameters are off by default.
488.Bl -tag -width indent
489.It Va allow.set_hostname
490The jail's hostname may be changed via
491.Xr hostname 1
492or
493.Xr sethostname 3 .
494.It Va allow.sysvipc
495A process within the jail has access to System V IPC primitives.
496This is deprecated in favor of the per-module parameters (see below).
497When this parameter is set, it is equivalent to setting
498.Va sysvmsg ,
499.Va sysvsem ,
500and
501.Va sysvshm
502all to
503.Dq inherit .
504.It Va allow.raw_sockets
505The jail root is allowed to create raw sockets.
506Setting this parameter allows utilities like
507.Xr ping 8
508and
509.Xr traceroute 8
510to operate inside the jail.
511If this is set, the source IP addresses are enforced to comply
512with the IP address bound to the jail, regardless of whether or not
513the
514.Dv IP_HDRINCL
515flag has been set on the socket.
516Since raw sockets can be used to configure and interact with various
517network subsystems, extra caution should be used where privileged access
518to jails is given out to untrusted parties.
519.It Va allow.chflags
520Normally, privileged users inside a jail are treated as unprivileged by
521.Xr chflags 2 .
522When this parameter is set, such users are treated as privileged, and
523may manipulate system file flags subject to the usual constraints on
524.Va kern.securelevel .
525.It Va allow.mount
526privileged users inside the jail will be able to mount and unmount file
527system types marked as jail-friendly.
528The
529.Xr lsvfs 1
530command can be used to find file system types available for mount from
531within a jail.
532This permission is effective only if
533.Va enforce_statfs
534is set to a value lower than 2.
535.It Va allow.mount.devfs
536privileged users inside the jail will be able to mount and unmount the
537devfs file system.
538This permission is effective only together with
539.Va allow.mount
540and only when
541.Va enforce_statfs
542is set to a value lower than 2.
543The devfs ruleset should be restricted from the default by using the
544.Va devfs_ruleset
545option.
546.It Va allow.mount.fdescfs
547privileged users inside the jail will be able to mount and unmount the
548fdescfs file system.
549This permission is effective only together with
550.Va allow.mount
551and only when
552.Va enforce_statfs
553is set to a value lower than 2.
554.It Va allow.mount.nullfs
555privileged users inside the jail will be able to mount and unmount the
556nullfs file system.
557This permission is effective only together with
558.Va allow.mount
559and only when
560.Va enforce_statfs
561is set to a value lower than 2.
562.It Va allow.mount.procfs
563privileged users inside the jail will be able to mount and unmount the
564procfs file system.
565This permission is effective only together with
566.Va allow.mount
567and only when
568.Va enforce_statfs
569is set to a value lower than 2.
570.It Va allow.mount.linprocfs
571privileged users inside the jail will be able to mount and unmount the
572linprocfs file system.
573This permission is effective only together with
574.Va allow.mount
575and only when
576.Va enforce_statfs
577is set to a value lower than 2.
578.It Va allow.mount.linsysfs
579privileged users inside the jail will be able to mount and unmount the
580linsysfs file system.
581This permission is effective only together with
582.Va allow.mount
583and only when
584.Va enforce_statfs
585is set to a value lower than 2.
586.It Va allow.mount.tmpfs
587privileged users inside the jail will be able to mount and unmount the
588tmpfs file system.
589This permission is effective only together with
590.Va allow.mount
591and only when
592.Va enforce_statfs
593is set to a value lower than 2.
594.It Va allow.mount.zfs
595privileged users inside the jail will be able to mount and unmount the
596ZFS file system.
597This permission is effective only together with
598.Va allow.mount
599and only when
600.Va enforce_statfs
601is set to a value lower than 2.
602See
603.Xr zfs 8
604for information on how to configure the ZFS filesystem to operate from
605within a jail.
606.It Va allow.quotas
607The jail root may administer quotas on the jail's filesystem(s).
608This includes filesystems that the jail may share with other jails or
609with non-jailed parts of the system.
610.It Va allow.socket_af
611Sockets within a jail are normally restricted to IPv4, IPv6, local
612(UNIX), and route.  This allows access to other protocol stacks that
613have not had jail functionality added to them.
614.El
615.El
616.Pp
617Kernel modules may add their own parameters, which only exist when the
618module is loaded.
619These are typically headed under a parameter named after the module,
620with values of
621.Dq inherit
622to give the jail full use of the module,
623.Dq new
624to encapsulate the jail in some module-specific way,
625and
626.Dq disable
627to make the module unavailable to the jail.
628There also may be other parameters to define jail behavior within the module.
629Module-specific parameters include:
630.Bl -tag -width indent
631.It Va linux
632Determine how a jail's Linux emulation environment appears.
633A value of
634.Dq inherit
635will keep the same environment, and
636.Dq new
637will give the jail it's own environment (still originally inherited when
638the jail is created).
639.It Va linux.osname , linux.osrelease , linux.oss_version
640The Linux OS name, OS release, and OSS version associated with this jail.
641.It Va sysvmsg
642Allow access to SYSV IPC message primitives.
643If set to
644.Dq inherit ,
645all IPC objects on the system are visible to this jail, whether they
646were created by the jail itself, the base system, or other jails.
647If set to
648.Dq new ,
649the jail will have its own key namespace, and can only see the objects
650that it has created;
651the system (or parent jail) has access to the jail's objects, but not to
652its keys.
653If set to
654.Dq disable ,
655the jail cannot perform any sysvmsg-related system calls.
656.It Va sysvsem, sysvshm
657Allow access to SYSV IPC semaphore and shared memory primitives, in the
658same manner as
659.Va sysvmsg.
660.El
661.Pp
662There are pseudo-parameters that are not passed to the kernel, but are
663used by
664.Nm
665to set up the jail environment, often by running specified commands
666when jails are created or removed.
667The
668.Va exec.*
669command parameters are
670.Xr sh 1
671command lines that are run in either the system or jail environment.
672They may be given multiple values, which would run the specified
673commands in sequence.
674All commands must succeed (return a zero exit status), or the jail will
675not be created or removed, as appropriate.
676.Pp
677The pseudo-parameters are:
678.Bl -tag -width indent
679.It Va exec.prestart
680Command(s) to run in the system environment before a jail is created.
681.It Va exec.start
682Command(s) to run in the jail environment when a jail is created.
683A typical command to run is
684.Dq sh /etc/rc .
685.It Va command
686A synonym for
687.Va exec.start
688for use when specifying a jail directly on the command line.
689Unlike other parameters whose value is a single string,
690.Va command
691uses the remainder of the
692.Nm
693command line as its own arguments.
694.It Va exec.poststart
695Command(s) to run in the system environment after a jail is created,
696and after any
697.Va exec.start
698commands have completed.
699.It Va exec.prestop
700Command(s) to run in the system environment before a jail is removed.
701.It Va exec.stop
702Command(s) to run in the jail environment before a jail is removed,
703and after any
704.Va exec.prestop
705commands have completed.
706A typical command to run is
707.Dq sh /etc/rc.shutdown .
708.It Va exec.poststop
709Command(s) to run in the system environment after a jail is removed.
710.It Va exec.clean
711Run commands in a clean environment.
712The environment is discarded except for
713.Ev HOME , SHELL , TERM
714and
715.Ev USER .
716.Ev HOME
717and
718.Ev SHELL
719are set to the target login's default values.
720.Ev USER
721is set to the target login.
722.Ev TERM
723is imported from the current environment.
724The environment variables from the login class capability database for the
725target login are also set.
726.It Va exec.jail_user
727The user to run commands as, when running in the jail environment.
728The default is to run the commands as the current user.
729.It Va exec.system_jail_user
730This boolean option looks for the
731.Va exec.jail_user
732in the system
733.Xr passwd 5
734file, instead of in the jail's file.
735.It Va exec.system_user
736The user to run commands as, when running in the system environment.
737The default is to run the commands as the current user.
738.It Va exec.timeout
739The maximum amount of time to wait for a command to complete, in
740seconds.
741If a command is still running after this timeout has passed,
742the jail will not be created or removed, as appropriate.
743.It Va exec.consolelog
744A file to direct command output (stdout and stderr) to.
745.It Va exec.fib
746The FIB (routing table) to set when running commands inside the jail.
747.It Va stop.timeout
748The maximum amount of time to wait for a jail's processes to exit
749after sending them a
750.Dv SIGTERM
751signal (which happens after the
752.Va exec.stop
753commands have completed).
754After this many seconds have passed, the jail will be removed, which
755will kill any remaining processes.
756If this is set to zero, no
757.Dv SIGTERM
758is sent and the jail is immediately removed.
759The default is 10 seconds.
760.It Va interface
761A network interface to add the jail's IP addresses
762.Va ( ip4.addr
763and
764.Va ip6.addr )
765to.
766An alias for each address will be added to the interface before the
767jail is created, and will be removed from the interface after the
768jail is removed.
769.It Va ip4.addr
770In addition to the IP addresses that are passed to the kernel, an
771interface, netmask and additional parameters (as supported by
772.Xr ifconfig 8 Ns )
773may also be specified, in the form
774.Dq Ar interface Ns | Ns Ar ip-address Ns / Ns Ar netmask param ... .
775If an interface is given before the IP address, an alias for the address
776will be added to that interface, as it is with the
777.Va interface
778parameter.
779If a netmask in either dotted-quad or CIDR form is given
780after an IP address, it will be used when adding the IP alias.
781If additional parameters are specified then they will also be used when
782adding the IP alias.
783.It Va ip6.addr
784In addition to the IP addresses that are passed to the kernel,
785an interface, prefix and additional parameters (as supported by
786.Xr ifconfig 8 Ns )
787may also be specified, in the form
788.Dq Ar interface Ns | Ns Ar ip-address Ns / Ns Ar prefix param ... .
789.It Va vnet.interface
790A network interface to give to a vnet-enabled jail after is it created.
791The interface will automatically be released when the jail is removed.
792.It Va ip_hostname
793Resolve the
794.Va host.hostname
795parameter and add all IP addresses returned by the resolver
796to the list of addresses
797.Po Va ip4.addr
798or
799.Va ip6.addr Pc
800for this jail.
801This may affect default address selection for outgoing IPv4 connections
802from jails.
803The address first returned by the resolver for each address family
804will be used as the primary address.
805.It Va mount
806A filesystem to mount before creating the jail (and to unmount after
807removing it), given as a single
808.Xr fstab 5
809line.
810.It Va mount.fstab
811An
812.Xr fstab 5
813format file containing filesystems to mount before creating a jail.
814.It Va mount.devfs
815Mount a
816.Xr devfs 5
817filesystem on the chrooted
818.Pa /dev
819directory, and apply the ruleset in the
820.Va devfs_ruleset
821parameter (or a default of ruleset 4: devfsrules_jail)
822to restrict the devices visible inside the jail.
823.It Va mount.fdescfs
824Mount a
825.Xr fdescfs 5
826filesystem on the chrooted
827.Pa /dev/fd
828directory.
829.It Va mount.procfs
830Mount a
831.Xr procfs 5
832filesystem on the chrooted
833.Pa /proc
834directory.
835.It Va allow.dying
836Allow making changes to a
837.Va dying
838jail.
839.It Va depend
840Specify a jail (or jails) that this jail depends on.
841When this jail is to be created, any jail(s) it depends on must already exist.
842If not, they will be created automatically, up to the completion of the last
843.Va exec.poststart
844command, before any action will taken to create this jail.
845When jails are removed the opposite is true:
846this jail will be removed, up to the last
847.Va exec.poststop
848command, before any jail(s) it depends on are stopped.
849.El
850.Sh EXAMPLES
851Jails are typically set up using one of two philosophies: either to
852constrain a specific application (possibly running with privilege), or
853to create a
854.Dq "virtual system image"
855running a variety of daemons and services.
856In both cases, a fairly complete file system install of
857.Fx
858is
859required, so as to provide the necessary command line tools, daemons,
860libraries, application configuration files, etc.
861However, for a virtual server configuration, a fair amount of
862additional work is required so as to replace the
863.Dq boot
864process.
865This manual page documents the configuration steps necessary to support
866either of these steps, although the configuration steps may need to be
867refined based on local requirements.
868.Ss "Setting up a Jail Directory Tree"
869To set up a jail directory tree containing an entire
870.Fx
871distribution, the following
872.Xr sh 1
873command script can be used:
874.Bd -literal
875D=/here/is/the/jail
876cd /usr/src
877mkdir -p $D
878make world DESTDIR=$D
879make distribution DESTDIR=$D
880.Ed
881.Pp
882In many cases this example would put far more in the jail than needed.
883In the other extreme case a jail might contain only one file:
884the executable to be run in the jail.
885.Pp
886We recommend experimentation, and caution that it is a lot easier to
887start with a
888.Dq fat
889jail and remove things until it stops working,
890than it is to start with a
891.Dq thin
892jail and add things until it works.
893.Ss "Setting Up a Jail"
894Do what was described in
895.Sx "Setting Up a Jail Directory Tree"
896to build the jail directory tree.
897For the sake of this example, we will
898assume you built it in
899.Pa /data/jail/testjail ,
900for a jail named
901.Dq testjail .
902Substitute below as needed with your
903own directory, IP address, and hostname.
904.Ss "Setting up the Host Environment"
905First, set up the real system's environment to be
906.Dq jail-friendly .
907For consistency, we will refer to the parent box as the
908.Dq "host environment" ,
909and to the jailed virtual machine as the
910.Dq "jail environment" .
911Since jails are implemented using IP aliases, one of the first things to do
912is to disable IP services on the host system that listen on all local
913IP addresses for a service.
914If a network service is present in the host environment that binds all
915available IP addresses rather than specific IP addresses, it may service
916requests sent to jail IP addresses if the jail did not bind the port.
917This means changing
918.Xr inetd 8
919to only listen on the
920appropriate IP address, and so forth.
921Add the following to
922.Pa /etc/rc.conf
923in the host environment:
924.Bd -literal -offset indent
925sendmail_enable="NO"
926inetd_flags="-wW -a 192.0.2.23"
927rpcbind_enable="NO"
928.Ed
929.Pp
930.Li 192.0.2.23
931is the native IP address for the host system, in this example.
932Daemons that run out of
933.Xr inetd 8
934can be easily configured to use only the specified host IP address.
935Other daemons
936will need to be manually configured \(em for some this is possible through
937.Xr rc.conf 5
938flags entries; for others it is necessary to modify per-application
939configuration files, or to recompile the application.
940The following frequently deployed services must have their individual
941configuration files modified to limit the application to listening
942to a specific IP address:
943.Pp
944To configure
945.Xr sshd 8 ,
946it is necessary to modify
947.Pa /etc/ssh/sshd_config .
948.Pp
949To configure
950.Xr sendmail 8 ,
951it is necessary to modify
952.Pa /etc/mail/sendmail.cf .
953.Pp
954For
955.Xr named 8 ,
956it is necessary to modify
957.Pa /etc/namedb/named.conf .
958.Pp
959In addition, a number of services must be recompiled in order to run
960them in the host environment.
961This includes most applications providing services using
962.Xr rpc 3 ,
963such as
964.Xr rpcbind 8 ,
965.Xr nfsd 8 ,
966and
967.Xr mountd 8 .
968In general, applications for which it is not possible to specify which
969IP address to bind should not be run in the host environment unless they
970should also service requests sent to jail IP addresses.
971Attempting to serve
972NFS from the host environment may also cause confusion, and cannot be
973easily reconfigured to use only specific IPs, as some NFS services are
974hosted directly from the kernel.
975Any third-party network software running
976in the host environment should also be checked and configured so that it
977does not bind all IP addresses, which would result in those services also
978appearing to be offered by the jail environments.
979.Pp
980Once
981these daemons have been disabled or fixed in the host environment, it is
982best to reboot so that all daemons are in a known state, to reduce the
983potential for confusion later (such as finding that when you send mail
984to a jail, and its sendmail is down, the mail is delivered to the host,
985etc.).
986.Ss "Configuring the Jail"
987Start any jail for the first time without configuring the network
988interface so that you can clean it up a little and set up accounts.
989As
990with any machine (virtual or not), you will need to set a root password, time
991zone, etc.
992Some of these steps apply only if you intend to run a full virtual server
993inside the jail; others apply both for constraining a particular application
994or for running a virtual server.
995.Pp
996Start a shell in the jail:
997.Bd -literal -offset indent
998jail -c path=/data/jail/testjail mount.devfs \\
999	host.hostname=testhostname ip4.addr=192.0.2.100 \\
1000	command=/bin/sh
1001.Ed
1002.Pp
1003Assuming no errors, you will end up with a shell prompt within the jail.
1004You can now run
1005.Pa /usr/sbin/sysinstall
1006and do the post-install configuration to set various configuration options,
1007or perform these actions manually by editing
1008.Pa /etc/rc.conf ,
1009etc.
1010.Pp
1011.Bl -bullet -offset indent -compact
1012.It
1013Configure
1014.Pa /etc/resolv.conf
1015so that name resolution within the jail will work correctly.
1016.It
1017Run
1018.Xr newaliases 1
1019to quell
1020.Xr sendmail 8
1021warnings.
1022.It
1023Set a root password, probably different from the real host system.
1024.It
1025Set the timezone.
1026.It
1027Add accounts for users in the jail environment.
1028.It
1029Install any packages the environment requires.
1030.El
1031.Pp
1032You may also want to perform any package-specific configuration (web servers,
1033SSH servers, etc), patch up
1034.Pa /etc/syslog.conf
1035so it logs as you would like, etc.
1036If you are not using a virtual server, you may wish to modify
1037.Xr syslogd 8
1038in the host environment to listen on the syslog socket in the jail
1039environment; in this example, the syslog socket would be stored in
1040.Pa /data/jail/testjail/var/run/log .
1041.Pp
1042Exit from the shell, and the jail will be shut down.
1043.Ss "Starting the Jail"
1044You are now ready to restart the jail and bring up the environment with
1045all of its daemons and other programs.
1046Create an entry for the jail in
1047.Pa /etc/jail.conf :
1048.Bd -literal -offset indent
1049testjail {
1050	path = /tmp/jail/testjail;
1051	mount.devfs;
1052	host.hostname = testhostname;
1053	ip4.addr = 192.0.2.100;
1054	interface = ed0;
1055	exec.start = "/bin/sh /etc/rc";
1056	exec.stop = "/bin/sh /etc/rc.shutdown";
1057}
1058.Ed
1059.Pp
1060To start a virtual server environment,
1061.Pa /etc/rc
1062is run to launch various daemons and services, and
1063.Pa /etc/rc.shutdown
1064is run to shut them down when the jail is removed.
1065If you are running a single application in the jail,
1066substitute the command used to start the application for
1067.Dq /bin/sh /etc/rc ;
1068there may be some script available to cleanly shut down the application,
1069or it may be sufficient to go without a stop command, and have
1070.Nm
1071send
1072.Dv SIGTERM
1073to the application.
1074.Pp
1075Start the jail by running:
1076.Bd -literal -offset indent
1077jail -c testjail
1078.Ed
1079.Pp
1080A few warnings may be produced; however, it should all work properly.
1081You should be able to see
1082.Xr inetd 8 ,
1083.Xr syslogd 8 ,
1084and other processes running within the jail using
1085.Xr ps 1 ,
1086with the
1087.Ql J
1088flag appearing beside jailed processes.
1089To see an active list of jails, use
1090.Xr jls 8 .
1091If
1092.Xr sshd 8
1093is enabled in the jail environment, you should be able to
1094.Xr ssh 1
1095to the hostname or IP address of the jailed environment, and log
1096in using the accounts you created previously.
1097.Pp
1098It is possible to have jails started at boot time.
1099Please refer to the
1100.Dq jail_*
1101variables in
1102.Xr rc.conf 5
1103for more information.
1104.Ss "Managing the Jail"
1105Normal machine shutdown commands, such as
1106.Xr halt 8 ,
1107.Xr reboot 8 ,
1108and
1109.Xr shutdown 8 ,
1110cannot be used successfully within the jail.
1111To kill all processes from within a jail, you may use one of the
1112following commands, depending on what you want to accomplish:
1113.Bd -literal -offset indent
1114kill -TERM -1
1115kill -KILL -1
1116.Ed
1117.Pp
1118This will send the
1119.Dv SIGTERM
1120or
1121.Dv SIGKILL
1122signals to all processes in the jail \(em be careful not to run this from
1123the host environment!
1124Once all of the jail's processes have died, unless the jail was created
1125with the
1126.Va persist
1127parameter, the jail will be removed.
1128Depending on
1129the intended use of the jail, you may also want to run
1130.Pa /etc/rc.shutdown
1131from within the jail.
1132.Pp
1133To shut down the jail from the outside, simply remove it with
1134.Nm
1135.Ar -r ,
1136which will run any commands specified by
1137.Va exec.stop ,
1138and then send
1139.Dv SIGTERM
1140and eventually
1141.Dv SIGKILL
1142to any remaining jailed processes.
1143.Pp
1144The
1145.Pa /proc/ Ns Ar pid Ns Pa /status
1146file contains, as its last field, the name of the jail in which the
1147process runs, or
1148.Dq Li -
1149to indicate that the process is not running within a jail.
1150The
1151.Xr ps 1
1152command also shows a
1153.Ql J
1154flag for processes in a jail.
1155.Pp
1156You can also list/kill processes based on their jail ID.
1157To show processes and their jail ID, use the following command:
1158.Pp
1159.Dl "ps ax -o pid,jid,args"
1160.Pp
1161To show and then kill processes in jail number 3 use the following commands:
1162.Bd -literal -offset indent
1163pgrep -lfj 3
1164pkill -j 3
1165.Ed
1166or:
1167.Pp
1168.Dl "killall -j 3"
1169.Ss "Jails and File Systems"
1170It is not possible to
1171.Xr mount 8
1172or
1173.Xr umount 8
1174any file system inside a jail unless the file system is marked
1175jail-friendly, the jail's
1176.Va allow.mount
1177parameter is set, and the jail's
1178.Va enforce_statfs
1179parameter is lower than 2.
1180.Pp
1181Multiple jails sharing the same file system can influence each other.
1182For example, a user in one jail can fill the file system,
1183leaving no space for processes in the other jail.
1184Trying to use
1185.Xr quota 1
1186to prevent this will not work either, as the file system quotas
1187are not aware of jails but only look at the user and group IDs.
1188This means the same user ID in two jails share a single file
1189system quota.
1190One would need to use one file system per jail to make this work.
1191.Ss "Sysctl MIB Entries"
1192The read-only entry
1193.Va security.jail.jailed
1194can be used to determine if a process is running inside a jail (value
1195is one) or not (value is zero).
1196.Pp
1197The variable
1198.Va security.jail.max_af_ips
1199determines how may address per address family a jail may have.
1200The default is 255.
1201.Pp
1202Some MIB variables have per-jail settings.
1203Changes to these variables by a jailed process do not affect the host
1204environment, only the jail environment.
1205These variables are
1206.Va kern.securelevel ,
1207.Va kern.hostname ,
1208.Va kern.domainname ,
1209.Va kern.hostid ,
1210and
1211.Va kern.hostuuid .
1212.Ss "Hierarchical Jails"
1213By setting a jail's
1214.Va children.max
1215parameter, processes within a jail may be able to create jails of their own.
1216These child jails are kept in a hierarchy, with jails only able to see and/or
1217modify the jails they created (or those jails' children).
1218Each jail has a read-only
1219.Va parent
1220parameter, containing the
1221.Va jid
1222of the jail that created it; a
1223.Va jid
1224of 0 indicates the jail is a child of the current jail (or is a top-level
1225jail if the current process isn't jailed).
1226.Pp
1227Jailed processes are not allowed to confer greater permissions than they
1228themselves are given, e.g., if a jail is created with
1229.Va allow.nomount ,
1230it is not able to create a jail with
1231.Va allow.mount
1232set.
1233Similarly, such restrictions as
1234.Va ip4.addr
1235and
1236.Va securelevel
1237may not be bypassed in child jails.
1238.Pp
1239A child jail may in turn create its own child jails if its own
1240.Va children.max
1241parameter is set (remember it is zero by default).
1242These jails are visible to and can be modified by their parent and all
1243ancestors.
1244.Pp
1245Jail names reflect this hierarchy, with a full name being an MIB-type string
1246separated by dots.
1247For example, if a base system process creates a jail
1248.Dq foo ,
1249and a process under that jail creates another jail
1250.Dq bar ,
1251then the second jail will be seen as
1252.Dq foo.bar
1253in the base system (though it is only seen as
1254.Dq bar
1255to any processes inside jail
1256.Dq foo ) .
1257Jids on the other hand exist in a single space, and each jail must have a
1258unique jid.
1259.Pp
1260Like the names, a child jail's
1261.Va path
1262appears relative to its creator's own
1263.Va path .
1264This is by virtue of the child jail being created in the chrooted
1265environment of the first jail.
1266.Sh SEE ALSO
1267.Xr killall 1 ,
1268.Xr lsvfs 1 ,
1269.Xr newaliases 1 ,
1270.Xr pgrep 1 ,
1271.Xr pkill 1 ,
1272.Xr ps 1 ,
1273.Xr quota 1 ,
1274.Xr jail_set 2 ,
1275.Xr devfs 5 ,
1276.Xr fdescfs 5 ,
1277.Xr jail.conf 5 ,
1278.Xr linprocfs 5 ,
1279.Xr linsysfs 5 ,
1280.Xr procfs 5 ,
1281.Xr rc.conf 5 ,
1282.Xr sysctl.conf 5 ,
1283.Xr chroot 8 ,
1284.Xr devfs 8 ,
1285.Xr halt 8 ,
1286.Xr ifconfig 8 ,
1287.Xr inetd 8 ,
1288.Xr jexec 8 ,
1289.Xr jls 8 ,
1290.Xr mount 8 ,
1291.Xr named 8 ,
1292.Xr reboot 8 ,
1293.Xr rpcbind 8 ,
1294.Xr sendmail 8 ,
1295.Xr shutdown 8 ,
1296.Xr sysctl 8 ,
1297.Xr syslogd 8 ,
1298.Xr umount 8
1299.Sh HISTORY
1300The
1301.Nm
1302utility appeared in
1303.Fx 4.0 .
1304Hierarchical/extensible jails were introduced in
1305.Fx 8.0 .
1306The configuration file was introduced in
1307.Fx 9.1 .
1308.Sh AUTHORS
1309.An -nosplit
1310The jail feature was written by
1311.An Poul-Henning Kamp
1312for R&D Associates
1313who contributed it to
1314.Fx .
1315.Pp
1316.An Robert Watson
1317wrote the extended documentation, found a few bugs, added
1318a few new features, and cleaned up the userland jail environment.
1319.Pp
1320.An Bjoern A. Zeeb
1321added multi-IP jail support for IPv4 and IPv6 based on a patch
1322originally done by
1323.An Pawel Jakub Dawidek
1324for IPv4.
1325.Pp
1326.An James Gritton
1327added the extensible jail parameters, hierarchical jails,
1328and the configuration file.
1329.Sh BUGS
1330It might be a good idea to add an
1331address alias flag such that daemons listening on all IPs
1332.Pq Dv INADDR_ANY
1333will not bind on that address, which would facilitate building a safe
1334host environment such that host daemons do not impose on services offered
1335from within jails.
1336Currently, the simplest answer is to minimize services
1337offered on the host, possibly limiting it to services offered from
1338.Xr inetd 8
1339which is easily configurable.
1340.Sh NOTES
1341Great care should be taken when managing directories visible within the jail.
1342For example, if a jailed process has its current working directory set to a
1343directory that is moved out of the jail's chroot, then the process may gain
1344access to the file space outside of the jail.
1345It is recommended that directories always be copied, rather than moved, out
1346of a jail.
1347.Pp
1348In addition, there are several ways in which an unprivileged user
1349outside the jail can cooperate with a privileged user inside the jail
1350and thereby obtain elevated privileges in the host environment.
1351Most of these attacks can be mitigated by ensuring that the jail root
1352is not accessible to unprivileged users in the host environment.
1353Regardless, as a general rule, untrusted users with privileged access
1354to a jail should not be given access to the host environment.
1355