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