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