| jail.8 (232291) | jail.8 (234712) |
|---|---|
| 1.\" | |
| 2.\" Copyright (c) 2000, 2003 Robert N. M. Watson | 1.\" Copyright (c) 2000, 2003 Robert N. M. Watson |
| 3.\" Copyright (c) 2008 James Gritton | 2.\" Copyright (c) 2008-2012 James Gritton |
| 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright --- 7 unchanged lines hidden (view full) --- 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" | 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 --- 7 unchanged lines hidden (view full) --- 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" |
| 26.\" $FreeBSD: head/usr.sbin/jail/jail.8 234712 2012-04-26 17:36:05Z jamie $ |
|
| 27.\" | 27.\" |
| 28.\" ---------------------------------------------------------------------------- 29.\" "THE BEER-WARE LICENSE" (Revision 42): 30.\" <phk@FreeBSD.org> wrote this file. As long as you retain this notice you 31.\" can do whatever you want with this stuff. If we meet some day, and you think 32.\" this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp 33.\" ---------------------------------------------------------------------------- 34.\" 35.\" $FreeBSD: head/usr.sbin/jail/jail.8 232291 2012-02-29 07:33:07Z mm $ 36.\" 37.Dd February 29, 2012 | 28.Dd April 26, 2012 |
| 38.Dt JAIL 8 39.Os 40.Sh NAME 41.Nm jail | 29.Dt JAIL 8 30.Os 31.Sh NAME 32.Nm jail |
| 42.Nd "create or modify a system jail" | 33.Nd "manage system jails" |
| 43.Sh SYNOPSIS 44.Nm | 34.Sh SYNOPSIS 35.Nm |
| 45.Op Fl dhi | 36.Op Fl dhilqv |
| 46.Op Fl J Ar jid_file | 37.Op Fl J Ar jid_file |
| 47.Op Fl l u Ar username | Fl U Ar username 48.Op Fl c | m 49.Op Ar parameter=value ... | 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 ... |
| 50.Nm | 43.Nm |
| 51.Op Fl hi 52.Op Fl n Ar jailname | 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 |
| 53.Op Fl J Ar jid_file | 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 |
|
| 54.Op Fl s Ar securelevel | 60.Op Fl s Ar securelevel |
| 55.Op Fl l u Ar username | Fl U Ar username 56.Op Ar path hostname [ip[,..]] command ... 57.Nm 58.Op Fl r Ar jail | 61.Op Ar path hostname [ Ar ip Ns [ Ns Ar ,... Ns ]] Ar command ... |
| 59.Sh DESCRIPTION 60The 61.Nm | 62.Sh DESCRIPTION 63The 64.Nm |
| 62utility creates a new jail or modifies an existing jail, optionally 63imprisoning the current process (and future descendants) inside it. | 65utility creates new jails, or modifies or removes existing jails. 66A jail is specified via parameters on the command line, or in the 67.Xr jail.conf 5 68file. |
| 64.Pp | 69.Pp |
| 65The options are as follows: | 70At least one of the options 71.Fl c , 72.Fl m 73or 74.Fl r 75must be specified. 76These options are used alone or in combination describe the operation to 77perform: |
| 66.Bl -tag -width indent | 78.Bl -tag -width indent |
| 79.It Fl c 80Create a new jail. 81The jail 82.Va jid 83and 84.Va name 85parameters (if specified) on the command line, 86or any jails 87must not refer to an existing jail. 88.It Fl m 89Modify an existing jail. 90One of the 91.Va jid 92or 93.Va name 94parameters must exist and refer to an existing jail. 95Some parameters may not be changed on a running jail. 96.It Fl r 97Remove the 98.Ar jail 99specified by jid or name. 100All jailed processes are killed, and all children of this jail are also 101removed. 102.It Fl rc 103Restart an existing jail. 104The jail is first removed and then re-created, as if 105.Dq Nm Fl c 106and 107.Dq Nm Fl r 108were run in succession. 109.It Fl cm 110Create a jail if it does not exist, or modify the jail if it does exist. 111.It Fl mr 112Modify an existing jail. 113The jail may be restarted if necessary to modify parameters than could 114not otherwise be changed. 115.It Fl cmr 116Create a jail if it doesn't exist, or modify (and possibly restart) the 117jail if it does exist. 118.El 119.Pp 120Other available options are: 121.Bl -tag -width indent |
|
| 67.It Fl d | 122.It Fl d |
| 68Allow making changes to a dying jail. | 123Allow making changes to a dying jail, equivalent to the 124.Va allow.dying 125parameter. 126.It Fl f Ar conf_file 127Use configuration file 128.Ar conf_file 129instead of the default 130.Pa /etc/jail.conf . |
| 69.It Fl h 70Resolve the 71.Va host.hostname 72parameter (or 73.Va hostname ) 74and add all IP addresses returned by the resolver | 131.It Fl h 132Resolve the 133.Va host.hostname 134parameter (or 135.Va hostname ) 136and add all IP addresses returned by the resolver |
| 75to the list of 76.Va ip 77addresses for this prison. 78This may affect default address selection for outgoing IPv4 connections 79of prisons. 80The address first returned by the resolver for each address family 81will be used as primary address. 82See the 83.Va ip4.addr 84and 85.Va ip6.addr 86parameters further down for details. 87.It Fl i 88Output the jail identifier of the newly created jail. 89.It Fl n Ar jailname 90Set the jail's name. 91This is deprecated and is equivalent to setting the 92.Va name | 137to the list of addresses for this prison. 138This is equivalent to the 139.Va ip_hostname |
| 93parameter. | 140parameter. |
| 141.It Fl i 142Output (only) the jail identifier of the newly created jail(s). 143This implies the 144.Fl q 145option. |
|
| 94.It Fl J Ar jid_file 95Write a 96.Ar jid_file | 146.It Fl J Ar jid_file 147Write a 148.Ar jid_file |
| 97file, containing jail identifier, path, hostname, IP and 98command used to start the jail. | 149file, containing parameters used to start the jail. |
| 99.It Fl l | 150.It Fl l |
| 100Run program in the clean environment. 101The environment is discarded except for 102.Ev HOME , SHELL , TERM 103and 104.Ev USER . 105.Ev HOME 106and 107.Ev SHELL 108are set to the target login's default values. 109.Ev USER 110is set to the target login. 111.Ev TERM 112is imported from the current environment. 113The environment variables from the login class capability database for the 114target login are also set. | 151Run commands in a clean environment. 152This is deprecated and is equivalent to the exec.clean parameter. 153.It Fl n Ar jailname 154Set the jail's name. 155This is deprecated and is equivalent to the 156.Va name 157parameter. 158.It Fl p Ar limit 159Limit the number of commands from 160.Va exec.* 161that can run simultaneously. 162.It Fl q 163Suppress the message printed whenever a jail is created, modified or removed. 164Only error messages will be printed. 165.It Fl R 166A variation of the 167.Fl r 168option that removes an existing jail without using the configuration file. 169No removal-related parameters for this jail will be used - the jail will 170simply be removed. |
| 115.It Fl s Ar securelevel 116Set the 117.Va kern.securelevel 118MIB entry to the specified value inside the newly created jail. | 171.It Fl s Ar securelevel 172Set the 173.Va kern.securelevel 174MIB entry to the specified value inside the newly created jail. |
| 119This is deprecated and is equivalent to setting the | 175This is deprecated and is equivalent to the |
| 120.Va securelevel 121parameter. 122.It Fl u Ar username | 176.Va securelevel 177parameter. 178.It Fl u Ar username |
| 123The user name from host environment as whom the 124.Ar command 125should run. 126.It Fl U Ar username 127The user name from jailed environment as whom the 128.Ar command 129should run. 130.It Fl c 131Create a new jail. 132The 133.Va jid | 179The user name from host environment as whom jailed commands should run. 180This is deprecated and is equivalent to the 181.Va exec.jail_user |
| 134and | 182and |
| 135.Va name 136parameters (if specified) must not refer to an existing jail. 137.It Fl m 138Modify an existing jail. 139One of the 140.Va jid 141or 142.Va name 143parameters must exist and refer to an existing jail. 144.It Fl cm 145Create a jail if it does not exist, or modify a jail if it does exist. 146.It Fl r 147Remove the 148.Ar jail 149specified by jid or name. 150All jailed processes are killed, and all children of this jail are also 151removed. | 183.Va exec.system_jail_user 184parameters. 185.It Fl U Ar username 186The user name from jailed environment as whom jailed commands should run. 187This is deprecated and is equivalent to the 188.Va exec.jail_user 189parameter. 190.It Fl v 191Print a message on every operation, such as running commands and 192mounting filesystems. |
| 152.El 153.Pp | 193.El 194.Pp |
| 154At least one of the 155.Fl c , 156.Fl m 157or | 195If no arguments are given after the options, the operation (except 196remove) will be performed on all jails specified in the 197.Xr jail.conf 5 198file. 199A single argument of a jail name will operate only on the specified jail. 200The |
| 158.Fl r | 201.Fl r |
| 159options must be specified. | 202and 203.Fl R 204options can also remove running jails that aren't in the 205.Xr jail.conf 5 206file, specified by name or jid. 207.P 208An argument of 209.Dq * 210is a wildcard that will operate on all jails, regardless of whether 211they appear in 212.Xr jail.conf 5 ; 213this is the surest way for 214.Fl r 215to remove all jails. 216If hierarchical jails exist, a partial-matching wildcard definition may 217be specified. 218For example, an argument of 219.Dq foo.* 220would apply to jails with names like 221.Dq foo.bar 222and 223.Dq foo.bar.baz . |
| 160.Pp | 224.Pp |
| 161.Ar Parameters 162are listed in 163.Dq name=value 164form, following the options. 165Some parameters are boolean, and do not have a value but are set by the 166name alone with or without a 167.Dq no 168prefix, e.g. 169.Va persist 170or 171.Va nopersist . 172Any parameters not set will be given default values, often based on the 173current environment. 174.Pp 175The pseudo-parameter 176.Va command 177specifies that the current process should enter the new (or modified) jail, 178and run the specified command. 179It must be the last parameter specified, because it includes not only 180the value following the 181.Sq = 182sign, but also passes the rest of the arguments to the command. 183.Pp 184Instead of supplying named 185.Ar parameters , 186four fixed parameters may be supplied in order on the command line: | 225A jail may be specified with parameters directly on the command line. 226In this case, the 227.Xr jail.conf 5 228file will not be used. 229For backward compatibility, the command line may also have four fixed 230parameters, without names: |
| 187.Ar path , 188.Ar hostname , 189.Ar ip , 190and 191.Ar command . | 231.Ar path , 232.Ar hostname , 233.Ar ip , 234and 235.Ar command . |
| 192As the 193.Va jid 194and 195.Va name 196parameters aren't in this list, this mode will always create a new jail, and 197the | 236This mode will always create a new jail, and the |
| 198.Fl c 199and 200.Fl m 201options don't apply (and must not exist). | 237.Fl c 238and 239.Fl m 240options don't apply (and must not exist). |
| 241.Ss Jail Parameters 242Parameters in the 243.Xr jail.conf 5 244file, or on the command line, are generally in 245.Dq name=value 246form. 247Some parameters are boolean, and do not have a value but are set by the 248name alone with or without a 249.Dq no 250prefix, e.g. 251.Va persist 252or 253.Va nopersist . 254They can also be given the values 255.Dq true 256and 257.Dq false . 258Other partameters may have more than one value, specified as a 259comma-separated list or with 260.Dq += 261in the configuration file (see 262.Xr jail.conf 5 263for details). |
|
| 202.Pp | 264.Pp |
| 203Jails have a set a core parameters, and modules can add their own jail 204parameters. | 265The 266.Nm 267utility recognizes two classes of parameters. There are the true jail 268parameters that are passed to the kernel when the jail is created, 269can be seen with 270.Xr jls 8 , 271and can (usually) be changed with 272.Dq Nm Fl m. 273Then there are pseudo-parameters that are only used by 274.Nm 275itself. 276.Pp 277Jails have a set a core parameters, and kernel modules can add their own 278jail parameters. |
| 205The current set of available parameters can be retrieved via 206.Dq Nm sysctl Fl d Va security.jail.param . | 279The current set of available parameters can be retrieved via 280.Dq Nm sysctl Fl d Va security.jail.param . |
| 281Any parameters not set will be given default values, often based on the 282current environment. |
|
| 207The core parameters are: 208.Bl -tag -width indent 209.It Va jid 210The jail identifier. 211This will be assigned automatically to a new jail (or can be explicitly 212set), and can be used to identify the jail for later modification, or 213for such commands as 214.Xr jls 8 --- 11 unchanged lines hidden (view full) --- 226commands, or to 227.Xr jls 8 228or 229.Xr jexec 8 . 230If no 231.Va name 232is supplied, a default is assumed that is the same as the 233.Va jid . | 283The core parameters are: 284.Bl -tag -width indent 285.It Va jid 286The jail identifier. 287This will be assigned automatically to a new jail (or can be explicitly 288set), and can be used to identify the jail for later modification, or 289for such commands as 290.Xr jls 8 --- 11 unchanged lines hidden (view full) --- 302commands, or to 303.Xr jls 8 304or 305.Xr jexec 8 . 306If no 307.Va name 308is supplied, a default is assumed that is the same as the 309.Va jid . |
| 234.It Va path 235Directory which is to be the root of the prison. | |
| 236The | 310The |
| 237.Va command 238(if any) is run from this directory, as are commands from 239.Xr jexec 8 . | 311.Va name 312parameter is implied by the 313.Xr jail.conf 5 314file format, and need not be explicitly set when using the configuration 315file. 316.It Va path 317The directory which is to be the root of the prison. 318Any commands run inside the prison, either by 319.Nm 320or from 321.Xr jexec 8 , 322are run from this directory. |
| 240.It Va ip4.addr | 323.It Va ip4.addr |
| 241A comma-separated list of IPv4 addresses assigned to the prison. | 324A list of IPv4 addresses assigned to the prison. |
| 242If this is set, the jail is restricted to using only these addresses. 243Any attempts to use other addresses fail, and attempts to use wildcard 244addresses silently use the jailed address instead. 245For IPv4 the first address given will be kept used as the source address 246in case source address selection on unbound sockets cannot find a better 247match. 248It is only possible to start multiple jails with the same IP address, 249if none of the jails has more than this single overlapping IP address 250assigned to itself. 251.It Va ip4.saddrsel 252A boolean option to change the formerly mentioned behaviour and disable 253IPv4 source address selection for the prison in favour of the primary 254IPv4 address of the jail. | 325If this is set, the jail is restricted to using only these addresses. 326Any attempts to use other addresses fail, and attempts to use wildcard 327addresses silently use the jailed address instead. 328For IPv4 the first address given will be kept used as the source address 329in case source address selection on unbound sockets cannot find a better 330match. 331It is only possible to start multiple jails with the same IP address, 332if none of the jails has more than this single overlapping IP address 333assigned to itself. 334.It Va ip4.saddrsel 335A boolean option to change the formerly mentioned behaviour and disable 336IPv4 source address selection for the prison in favour of the primary 337IPv4 address of the jail. |
| 255Source address selection is enabled by default for all jails and a | 338Source address selection is enabled by default for all jails and the |
| 256.Va ip4.nosaddrsel 257setting of a parent jail is not inherited for any child jails. 258.It Va ip4 259Control the availability of IPv4 addresses. 260Possible values are 261.Dq inherit 262to allow unrestricted access to all system addresses, 263.Dq new --- 8 unchanged lines hidden (view full) --- 272.Dq new . 273.It Va ip6.addr , Va ip6.saddrsel , Va ip6 274A set of IPv6 options for the prison, the counterparts to 275.Va ip4.addr , 276.Va ip4.saddrsel 277and 278.Va ip4 279above. | 339.Va ip4.nosaddrsel 340setting of a parent jail is not inherited for any child jails. 341.It Va ip4 342Control the availability of IPv4 addresses. 343Possible values are 344.Dq inherit 345to allow unrestricted access to all system addresses, 346.Dq new --- 8 unchanged lines hidden (view full) --- 355.Dq new . 356.It Va ip6.addr , Va ip6.saddrsel , Va ip6 357A set of IPv6 options for the prison, the counterparts to 358.Va ip4.addr , 359.Va ip4.saddrsel 360and 361.Va ip4 362above. |
| 363.It vnet 364Create the prison with its own virtual network stack, 365with its own network interfaces, addresses, routing table, etc. 366The kernel must have been compiled with the 367.Sy VIMAGE option 368for this to be available. 369Possible values are 370.Dq inherit 371to use the system network stack, possibly with restricted IP addresses, 372and 373.Dq new 374to create a new network stack. |
|
| 280.It Va host.hostname | 375.It Va host.hostname |
| 281Hostname of the prison. | 376The hostname of the prison. |
| 282Other similar parameters are 283.Va host.domainname , 284.Va host.hostuuid 285and 286.Va host.hostid . 287.It Va host 288Set the origin of hostname and related information. 289Possible values are --- 19 unchanged lines hidden (view full) --- 309Mounting devfs inside a jail is possible only if the 310.Va allow.mount 311and 312.Va allow.mount.devfs 313permissions are effective and 314.Va enforce_statfs 315is set to a value lower than 2. 316Devfs rules and rulesets cannot be viewed or modified from inside a jail. | 377Other similar parameters are 378.Va host.domainname , 379.Va host.hostuuid 380and 381.Va host.hostid . 382.It Va host 383Set the origin of hostname and related information. 384Possible values are --- 19 unchanged lines hidden (view full) --- 404Mounting devfs inside a jail is possible only if the 405.Va allow.mount 406and 407.Va allow.mount.devfs 408permissions are effective and 409.Va enforce_statfs 410is set to a value lower than 2. 411Devfs rules and rulesets cannot be viewed or modified from inside a jail. |
| 412.Pp 413NOTE: It is important that only appropriate device nodes in devfs be 414exposed to a jail; access to disk devices in the jail may permit processes 415in the jail to bypass the jail sandboxing by modifying files outside of 416the jail. 417See 418.Xr devfs 8 419for information on how to use devfs rules to limit access to entries 420in the per-jail devfs. 421A simple devfs ruleset for jails is available as ruleset #4 in 422.Pa /etc/defaults/devfs.rules . |
|
| 317.It Va children.max 318The number of child jails allowed to be created by this jail (or by 319other jails under this jail). 320This limit is zero by default, indicating the jail is not allowed to 321create child jails. 322See the | 423.It Va children.max 424The number of child jails allowed to be created by this jail (or by 425other jails under this jail). 426This limit is zero by default, indicating the jail is not allowed to 427create child jails. 428See the |
| 323.Va "Hierarchical Jails" | 429.Sx "Hierarchical Jails" |
| 324section for more information. 325.It Va children.cur 326The number of descendents of this jail, including its own child jails 327and any jails created under them. 328.It Va enforce_statfs 329This determines which information processes in a jail are able to get 330about mount points. 331It affects the behaviour of the following syscalls: --- 8 unchanged lines hidden (view full) --- 340visible. 341In addition to that, the path to the jail's chroot directory is removed 342from the front of their pathnames. 343When set to 2 (default), above syscalls can operate only on a mount-point 344where the jail's chroot directory is located. 345.It Va persist 346Setting this boolean parameter allows a jail to exist without any 347processes. | 430section for more information. 431.It Va children.cur 432The number of descendents of this jail, including its own child jails 433and any jails created under them. 434.It Va enforce_statfs 435This determines which information processes in a jail are able to get 436about mount points. 437It affects the behaviour of the following syscalls: --- 8 unchanged lines hidden (view full) --- 446visible. 447In addition to that, the path to the jail's chroot directory is removed 448from the front of their pathnames. 449When set to 2 (default), above syscalls can operate only on a mount-point 450where the jail's chroot directory is located. 451.It Va persist 452Setting this boolean parameter allows a jail to exist without any 453processes. |
| 348Normally, a jail is destroyed as its last process exits. | 454Normally, a command is run as part of jail creation, and then the jail 455is destroyed as its last process exits. |
| 349A new jail must have either the 350.Va persist 351parameter or | 456A new jail must have either the 457.Va persist 458parameter or |
| 459.Va exec.start 460or |
|
| 352.Va command 353pseudo-parameter set. 354.It Va cpuset.id 355The ID of the cpuset associated with this jail (read-only). 356.It Va dying 357This is true if the jail is in the process of shutting down (read-only). 358.It Va parent 359The --- 94 unchanged lines hidden (view full) --- 454with non-jailed parts of the system. 455.It Va allow.socket_af 456Sockets within a jail are normally restricted to IPv4, IPv6, local 457(UNIX), and route. This allows access to other protocol stacks that 458have not had jail functionality added to them. 459.El 460.El 461.Pp | 461.Va command 462pseudo-parameter set. 463.It Va cpuset.id 464The ID of the cpuset associated with this jail (read-only). 465.It Va dying 466This is true if the jail is in the process of shutting down (read-only). 467.It Va parent 468The --- 94 unchanged lines hidden (view full) --- 563with non-jailed parts of the system. 564.It Va allow.socket_af 565Sockets within a jail are normally restricted to IPv4, IPv6, local 566(UNIX), and route. This allows access to other protocol stacks that 567have not had jail functionality added to them. 568.El 569.El 570.Pp |
| 571There are pseudo-parameters that aren't passed to the kernel, but are 572used by 573.Nm 574to set up the prison environment, often by running specified commands 575when jails are created or removed. 576The 577.Va exec.* 578command parameters are 579.Xr sh 1 580command lines that are run in either the system or prison environment. 581They may be given multiple values, which run would the specified 582commands in sequence. 583All commands must succed (return a zero exit status), or the jail will 584not be created or removed. 585.Pp 586The pseudo-parameters are: 587.Bl -tag -width indent 588.It Va exec.prestart 589Command(s) to run in the system environment before a prison is created. 590.It Va exec.start 591Command(s) to run in the prison environment when a jail is created. 592A typical command to run is 593.Dq sh /etc/rc . 594.It Va command 595A synonym for 596.Va exec.start 597for use when specifying a prison directly on the command line. 598Unlike other parameters whose value is a single string, 599.Va command 600uses the remainder of the 601.Nm 602command line as its own arguments. 603.It Va exec.poststart 604Command(s) to run in the system environment after a jail is created, 605and after any 606.Va exec.start 607commands have completed. 608.It Va exec.prestop 609Command(s) to run in the system environment before a jail is removed. 610.It Va exec.stop 611Command(s) to run in the prison environment before a jail is removed, 612and after any 613.Va exec.prestop 614commands have completed. 615A typical command to run is 616.Dq sh /etc/rc.shutdown . 617.It Va exec.poststop 618Command(s) to run in the system environment after a jail is removed. 619.It Va exec.clean 620Run commands in a clean environment. 621The environment is discarded except for 622.Ev HOME , SHELL , TERM 623and 624.Ev USER . 625.Ev HOME 626and 627.Ev SHELL 628are set to the target login's default values. 629.Ev USER 630is set to the target login. 631.Ev TERM 632is imported from the current environment. 633The environment variables from the login class capability database for the 634target login are also set. 635.It Va exec.jail_user 636The user to run commands as, when running in the prison environment. 637The default is to run the commands as the current user. 638.It Va exec.system_jail_user 639This boolean option looks for the 640.Va exec.jail_user 641in the system 642.Xr passwd 5 643file, instead of in the prison's file. 644.It Va exec.system_user 645The user to run commands as, when running in the system environment. 646The default is to run the commands as the current user. 647.It Va exec.timeout 648The maximum amount of time to wait for a command to complete. 649If a command is still running after this many seconds have passed, 650the jail not be created or removed. 651.It Va exec.consolelog 652A file to direct command output (stdout and stderr) to. 653.It Va exec.fib 654The FIB (routing table) to set when running commands inside the prison. 655.It Va stop.timeout 656The maximum amount of time to wait for a prison's processes to exit 657after sending them a 658.Dv SIGTERM 659signal (which happens after the 660.Va exec.stop commands have completed). 661After this many seconds have passed, the prison will be removed, which 662will kill any remaining processes. 663If this is set to zero, no 664.Dv SIGTERM 665is sent and the prison is immediately removed. 666The default is 10 seconds. 667.It Va interface 668A network interface to add the prison's IP addresses 669.Va ( ip4.addr 670and 671.Va ip6.addr ) 672to. 673An alias for each address will be added to the interface before the 674prison is created, and will be removed from the interface after the 675prison is removed. 676.It Op Va ip4.addr 677In addition to the IP addresses that are passed to the kernel, and 678interface and/or a netmask may also be specified, in the form 679.Dq Ar interface Ns | Ns Ar ip-address Ns / Ns Ar netmask . 680If an interface is given before the IP address, an alias for the address 681will be added to that interface, as it is with the 682.Va interface 683parameter. If a netmask in either dotted-quad or CIDR form is given 684after IP address, it will be used when adding the IP alias. 685.It Op Va ip6.addr 686In addition to the IP addresses that are passed to the kernel, 687and interface and/or a prefix may also be specified, in the form 688.Dq Ar interface Ns | Ns Ar ip-address Ns / Ns Ar prefix . 689.It Va vnet.interface 690A network interface to give to a vnet-enabled jail after is it created. 691The interface will automatically be returned when the jail is removed. 692.It Va ip_hostname 693Resolve the 694.Va host.hostname 695parameter and add all IP addresses returned by the resolver 696to the list of addresses 697.Va ( ip4.addr 698or 699.Va ip6.addr ) 700for this prison. 701This may affect default address selection for outgoing IPv4 connections 702of prisons. 703The address first returned by the resolver for each address family 704will be used as primary address. 705.It Va mount 706A filesystem to mount before creating the jail (and to unmount after 707removing it), given as a single 708.Xr fstab 5 709line. 710.It Va mount.fstab 711An 712.Xr fstab 5 713format file containing filesystems to mount before creating a jail. 714.It Va mount.devfs 715Mount a 716.Xr devfs 717filesystem on the chrooted /dev directory, and apply the ruleset in the 718.Va devfs_ruleset 719parameter (or a default of ruleset 4: devfsrules_jail) 720to restrict the devices visible inside the prison. 721.It Va allow.dying 722Allow making changes to a 723.Va dying 724jail. 725.It Va depend 726Specify a jail (or jails) that this jail depends on. 727Any such jails must be fully created, up to the last 728.Va exec.poststart 729command, before any action will taken to create this jail. 730When jails are removed the opposite is true: 731this jail must be fully removed, up to the last 732.Va exec.poststop 733command, before the jail(s) it depends on are stopped. 734.El 735.Sh EXAMPLES |
|
| 462Jails are typically set up using one of two philosophies: either to 463constrain a specific application (possibly running with privilege), or 464to create a 465.Dq "virtual system image" 466running a variety of daemons and services. 467In both cases, a fairly complete file system install of 468.Fx 469is 470required, so as to provide the necessary command line tools, daemons, 471libraries, application configuration files, etc. 472However, for a virtual server configuration, a fair amount of 473additional work is required so as to configure the 474.Dq boot 475process. 476This manual page documents the configuration steps necessary to support 477either of these steps, although the configuration steps may be 478refined based on local requirements. | 736Jails are typically set up using one of two philosophies: either to 737constrain a specific application (possibly running with privilege), or 738to create a 739.Dq "virtual system image" 740running a variety of daemons and services. 741In both cases, a fairly complete file system install of 742.Fx 743is 744required, so as to provide the necessary command line tools, daemons, 745libraries, application configuration files, etc. 746However, for a virtual server configuration, a fair amount of 747additional work is required so as to configure the 748.Dq boot 749process. 750This manual page documents the configuration steps necessary to support 751either of these steps, although the configuration steps may be 752refined based on local requirements. |
| 479.Sh EXAMPLES | |
| 480.Ss "Setting up a Jail Directory Tree" 481To set up a jail directory tree containing an entire 482.Fx 483distribution, the following 484.Xr sh 1 485command script can be used: 486.Bd -literal 487D=/here/is/the/jail 488cd /usr/src 489mkdir -p $D 490make world DESTDIR=$D 491make distribution DESTDIR=$D | 753.Ss "Setting up a Jail Directory Tree" 754To set up a jail directory tree containing an entire 755.Fx 756distribution, the following 757.Xr sh 1 758command script can be used: 759.Bd -literal 760D=/here/is/the/jail 761cd /usr/src 762mkdir -p $D 763make world DESTDIR=$D 764make distribution DESTDIR=$D |
| 492mount -t devfs devfs $D/dev | |
| 493.Ed 494.Pp | 765.Ed 766.Pp |
| 495NOTE: It is important that only appropriate device nodes in devfs be 496exposed to a jail; access to disk devices in the jail may permit processes 497in the jail to bypass the jail sandboxing by modifying files outside of 498the jail. 499See 500.Xr devfs 8 501for information on how to use devfs rules to limit access to entries 502in the per-jail devfs. 503A simple devfs ruleset for jails is available as ruleset #4 in 504.Pa /etc/defaults/devfs.rules . 505.Pp | |
| 506In many cases this example would put far more in the jail than needed. 507In the other extreme case a jail might contain only one file: 508the executable to be run in the jail. 509.Pp 510We recommend experimentation and caution that it is a lot easier to 511start with a 512.Dq fat 513jail and remove things until it stops working, 514than it is to start with a 515.Dq thin 516jail and add things until it works. 517.Ss "Setting Up a Jail" 518Do what was described in 519.Sx "Setting Up a Jail Directory Tree" 520to build the jail directory tree. 521For the sake of this example, we will 522assume you built it in | 767In many cases this example would put far more in the jail than needed. 768In the other extreme case a jail might contain only one file: 769the executable to be run in the jail. 770.Pp 771We recommend experimentation and caution that it is a lot easier to 772start with a 773.Dq fat 774jail and remove things until it stops working, 775than it is to start with a 776.Dq thin 777jail and add things until it works. 778.Ss "Setting Up a Jail" 779Do what was described in 780.Sx "Setting Up a Jail Directory Tree" 781to build the jail directory tree. 782For the sake of this example, we will 783assume you built it in |
| 523.Pa /data/jail/192.0.2.100 , 524named for the jailed IP address. | 784.Pa /data/jail/testjail , 785for a jail named 786.Dq testjail . |
| 525Substitute below as needed with your 526own directory, IP address, and hostname. 527.Ss "Setting up the Host Environment" 528First, you will want to set up your real system's environment to be 529.Dq jail-friendly . 530For consistency, we will refer to the parent box as the 531.Dq "host environment" , 532and to the jailed virtual machine as the --- 81 unchanged lines hidden (view full) --- 614with any machine (virtual or not) you will need to set a root password, time 615zone, etc. 616Some of these steps apply only if you intend to run a full virtual server 617inside the jail; others apply both for constraining a particular application 618or for running a virtual server. 619.Pp 620Start a shell in the jail: 621.Bd -literal -offset indent | 787Substitute below as needed with your 788own directory, IP address, and hostname. 789.Ss "Setting up the Host Environment" 790First, you will want to set up your real system's environment to be 791.Dq jail-friendly . 792For consistency, we will refer to the parent box as the 793.Dq "host environment" , 794and to the jailed virtual machine as the --- 81 unchanged lines hidden (view full) --- 876with any machine (virtual or not) you will need to set a root password, time 877zone, etc. 878Some of these steps apply only if you intend to run a full virtual server 879inside the jail; others apply both for constraining a particular application 880or for running a virtual server. 881.Pp 882Start a shell in the jail: 883.Bd -literal -offset indent |
| 622jail -c path=/data/jail/192.0.2.100 host.hostname=testhostname \\ | 884jail -c path=/data/jail/testjail mount.devfs host.hostname=testhostname \\ |
| 623 ip4.addr=192.0.2.100 command=/bin/sh 624.Ed 625.Pp 626Assuming no errors, you will end up with a shell prompt within the jail. 627You can now run 628.Pa /usr/sbin/sysinstall 629and do the post-install configuration to set various configuration options, 630or perform these actions manually by editing 631.Pa /etc/rc.conf , 632etc. 633.Pp 634.Bl -bullet -offset indent -compact 635.It | 885 ip4.addr=192.0.2.100 command=/bin/sh 886.Ed 887.Pp 888Assuming no errors, you will end up with a shell prompt within the jail. 889You can now run 890.Pa /usr/sbin/sysinstall 891and do the post-install configuration to set various configuration options, 892or perform these actions manually by editing 893.Pa /etc/rc.conf , 894etc. 895.Pp 896.Bl -bullet -offset indent -compact 897.It |
| 636Create an empty 637.Pa /etc/fstab 638to quell startup warnings about missing fstab (virtual server only) 639.It 640Disable the port mapper 641.Pa ( /etc/rc.conf : 642.Li rpcbind_enable="NO" ) 643(virtual server only) 644.It | |
| 645Configure 646.Pa /etc/resolv.conf 647so that name resolution within the jail will work correctly 648.It 649Run 650.Xr newaliases 1 651to quell 652.Xr sendmail 8 653warnings. 654.It | 898Configure 899.Pa /etc/resolv.conf 900so that name resolution within the jail will work correctly 901.It 902Run 903.Xr newaliases 1 904to quell 905.Xr sendmail 8 906warnings. 907.It |
| 655Disable interface configuration to quell startup warnings about 656.Xr ifconfig 8 657.Pq Li network_interfaces="" 658(virtual server only) 659.It | |
| 660Set a root password, probably different from the real host system 661.It 662Set the timezone 663.It 664Add accounts for users in the jail environment 665.It 666Install any packages the environment requires 667.El 668.Pp 669You may also want to perform any package-specific configuration (web servers, 670SSH servers, etc), patch up 671.Pa /etc/syslog.conf 672so it logs as you would like, etc. 673If you are not using a virtual server, you may wish to modify 674.Xr syslogd 8 675in the host environment to listen on the syslog socket in the jail 676environment; in this example, the syslog socket would be stored in | 908Set a root password, probably different from the real host system 909.It 910Set the timezone 911.It 912Add accounts for users in the jail environment 913.It 914Install any packages the environment requires 915.El 916.Pp 917You may also want to perform any package-specific configuration (web servers, 918SSH servers, etc), patch up 919.Pa /etc/syslog.conf 920so it logs as you would like, etc. 921If you are not using a virtual server, you may wish to modify 922.Xr syslogd 8 923in the host environment to listen on the syslog socket in the jail 924environment; in this example, the syslog socket would be stored in |
| 677.Pa /data/jail/192.0.2.100/var/run/log . | 925.Pa /data/jail/testjail/var/run/log . |
| 678.Pp 679Exit from the shell, and the jail will be shut down. 680.Ss "Starting the Jail" 681You are now ready to restart the jail and bring up the environment with 682all of its daemons and other programs. | 926.Pp 927Exit from the shell, and the jail will be shut down. 928.Ss "Starting the Jail" 929You are now ready to restart the jail and bring up the environment with 930all of its daemons and other programs. |
| 683If you are running a single application in the jail, substitute the 684command used to start the application for 685.Pa /etc/rc 686in the examples below. | 931Create an entry for the jail in 932.Pa /etc/jail.conf : 933.Bd -literal -offset indent 934testjail { 935 path = /tmp/jail/testjail; 936 mount.devfs; 937 host.hostname = testhostname; 938 ip4.addr = 192.0.2.100; 939 interface = ed0; 940 exec.start = "/bin/sh /etc/rc"; 941 exec.stop = "/bin/sh /etc/rc.shutdown"; 942} 943.Ed 944.Pp |
| 687To start a virtual server environment, 688.Pa /etc/rc | 945To start a virtual server environment, 946.Pa /etc/rc |
| 689is run to launch various daemons and services. 690To do this, first bring up the 691virtual host interface, and then start the jail's 692.Pa /etc/rc 693script from within the jail. | 947is run to launch various daemons and services, and 948.Pa /etc/rc.shutdown 949is run to shut them down when the jail is removed. 950If you are running a single application in the jail, 951substitute the command used to start the application for 952.Dq /bin/sh /etc/rc ; 953there may be some script available to cleanly shut down the application, 954or it may be sufficient to go without a stop command, and have 955.Nm 956send 957.Dv SIGTERM 958to the application. 959.Pp 960Start the jail by running: |
| 694.Bd -literal -offset indent | 961.Bd -literal -offset indent |
| 695ifconfig ed0 inet alias 192.0.2.100/32 696mount -t procfs proc /data/jail/192.0.2.100/proc 697jail -c path=/data/jail/192.0.2.100 host.hostname=testhostname \\ 698 ip4.addr=192.0.2.100 command=/bin/sh /etc/rc | 962jail -c testjail |
| 699.Ed 700.Pp | 963.Ed 964.Pp |
| 701A few warnings will be produced, because most 702.Xr sysctl 8 703configuration variables cannot be set from within the jail, as they are 704global across all jails and the host environment. 705However, it should all 706work properly. | 965A few warnings may be produced; however, it should all work properly. |
| 707You should be able to see 708.Xr inetd 8 , 709.Xr syslogd 8 , 710and other processes running within the jail using 711.Xr ps 1 , 712with the 713.Ql J 714flag appearing beside jailed processes. --- 6 unchanged lines hidden (view full) --- 721in using the accounts you created previously. 722.Pp 723It is possible to have jails started at boot time. 724Please refer to the 725.Dq jail_* 726variables in 727.Xr rc.conf 5 728for more information. | 966You should be able to see 967.Xr inetd 8 , 968.Xr syslogd 8 , 969and other processes running within the jail using 970.Xr ps 1 , 971with the 972.Ql J 973flag appearing beside jailed processes. --- 6 unchanged lines hidden (view full) --- 980in using the accounts you created previously. 981.Pp 982It is possible to have jails started at boot time. 983Please refer to the 984.Dq jail_* 985variables in 986.Xr rc.conf 5 987for more information. |
| 729The 730.Xr rc 8 731jail script provides a flexible system to start/stop jails: 732.Bd -literal 733/etc/rc.d/jail start 734/etc/rc.d/jail stop 735/etc/rc.d/jail start myjail 736/etc/rc.d/jail stop myjail 737.Ed | |
| 738.Ss "Managing the Jail" 739Normal machine shutdown commands, such as 740.Xr halt 8 , 741.Xr reboot 8 , 742and 743.Xr shutdown 8 , 744cannot be used successfully within the jail. | 988.Ss "Managing the Jail" 989Normal machine shutdown commands, such as 990.Xr halt 8 , 991.Xr reboot 8 , 992and 993.Xr shutdown 8 , 994cannot be used successfully within the jail. |
| 745To kill all processes in a 746jail, you may log into the jail and, as root, use one of the following 747commands, depending on what you want to accomplish: | 995To kill all processes from within a jail, you may use one of the 996following commands, depending on what you want to accomplish: |
| 748.Bd -literal -offset indent 749kill -TERM -1 750kill -KILL -1 751.Ed 752.Pp 753This will send the 754.Dv SIGTERM 755or 756.Dv SIGKILL | 997.Bd -literal -offset indent 998kill -TERM -1 999kill -KILL -1 1000.Ed 1001.Pp 1002This will send the 1003.Dv SIGTERM 1004or 1005.Dv SIGKILL |
| 757signals to all processes in the jail from within the jail. | 1006signals to all processes in the jail - be careful not to run this from 1007the host environment! 1008Once all of the jail's processes have died, unless the jail was created 1009with the 1010.Va persist 1011parameter, the jail will be removed. |
| 758Depending on 759the intended use of the jail, you may also want to run 760.Pa /etc/rc.shutdown 761from within the jail. | 1012Depending on 1013the intended use of the jail, you may also want to run 1014.Pa /etc/rc.shutdown 1015from within the jail. |
| 762To kill processes from outside the jail, use the 763.Xr jexec 8 764utility in conjunction with the one of the 765.Xr kill 1 766commands above. 767You may also remove the jail with | 1016.Pp 1017To shut down the jail from the outside, simply remove it with |
| 768.Nm 769.Ar -r , | 1018.Nm 1019.Ar -r , |
| 770which will killall the jail's processes with 771.Dv SIGKILL . | 1020which will run any commands specified by 1021.Va exec.stop , 1022and then send 1023.Dv SIGTERM 1024and eventually 1025.Dv SIGKILL 1026to any remaining jailed processes. |
| 772.Pp 773The 774.Pa /proc/ Ns Ar pid Ns Pa /status 775file contains, as its last field, the name of the jail in which the 776process runs, or 777.Dq Li - 778to indicate that the process is not running within a jail. 779The --- 103 unchanged lines hidden (view full) --- 883.Dq bar 884to any processes inside jail 885.Dq foo ) . 886Jids on the other hand exist in a single space, and each jail must have a 887unique jid. 888.Pp 889Like the names, a child jail's 890.Va path | 1027.Pp 1028The 1029.Pa /proc/ Ns Ar pid Ns Pa /status 1030file contains, as its last field, the name of the jail in which the 1031process runs, or 1032.Dq Li - 1033to indicate that the process is not running within a jail. 1034The --- 103 unchanged lines hidden (view full) --- 1138.Dq bar 1139to any processes inside jail 1140.Dq foo ) . 1141Jids on the other hand exist in a single space, and each jail must have a 1142unique jid. 1143.Pp 1144Like the names, a child jail's 1145.Va path |
| 891is relative to its creator's own | 1146appears relative to its creator's own |
| 892.Va path . 893This is by virtue of the child jail being created in the chrooted 894environment of the first jail. 895.Sh SEE ALSO 896.Xr killall 1 , 897.Xr lsvfs 1 , 898.Xr newaliases 1 , 899.Xr pgrep 1 , 900.Xr pkill 1 , 901.Xr ps 1 , 902.Xr quota 1 , | 1147.Va path . 1148This is by virtue of the child jail being created in the chrooted 1149environment of the first jail. 1150.Sh SEE ALSO 1151.Xr killall 1 , 1152.Xr lsvfs 1 , 1153.Xr newaliases 1 , 1154.Xr pgrep 1 , 1155.Xr pkill 1 , 1156.Xr ps 1 , 1157.Xr quota 1 , |
| 903.Xr chroot 2 , | |
| 904.Xr jail_set 2 , | 1158.Xr jail_set 2 , |
| 905.Xr jail_attach 2 , | 1159.Xr jail.conf 5 , |
| 906.Xr procfs 5 , 907.Xr rc.conf 5 , 908.Xr sysctl.conf 5 , | 1160.Xr procfs 5 , 1161.Xr rc.conf 5 , 1162.Xr sysctl.conf 5 , |
| 1163.Xr chroot 8 , |
|
| 909.Xr devfs 8 , 910.Xr halt 8 , 911.Xr inetd 8 , 912.Xr jexec 8 , 913.Xr jls 8 , 914.Xr mount 8 , 915.Xr named 8 , 916.Xr reboot 8 , --- 5 unchanged lines hidden (view full) --- 922.Xr umount 8 923.Sh HISTORY 924The 925.Nm 926utility appeared in 927.Fx 4.0 . 928Hierarchical/extensible jails were introduced in 929.Fx 8.0 . | 1164.Xr devfs 8 , 1165.Xr halt 8 , 1166.Xr inetd 8 , 1167.Xr jexec 8 , 1168.Xr jls 8 , 1169.Xr mount 8 , 1170.Xr named 8 , 1171.Xr reboot 8 , --- 5 unchanged lines hidden (view full) --- 1177.Xr umount 8 1178.Sh HISTORY 1179The 1180.Nm 1181utility appeared in 1182.Fx 4.0 . 1183Hierarchical/extensible jails were introduced in 1184.Fx 8.0 . |
| 1185The configuration file was introduced in 1186.Fx 10.0 . |
|
| 930.Sh AUTHORS 931.An -nosplit 932The jail feature was written by 933.An Poul-Henning Kamp 934for R&D Associates 935.Pa http://www.rndassociates.com/ 936who contributed it to 937.Fx . --- 4 unchanged lines hidden (view full) --- 942.Pp 943.An Bjoern A. Zeeb 944added multi-IP jail support for IPv4 and IPv6 based on a patch 945originally done by 946.An Pawel Jakub Dawidek 947for IPv4. 948.Pp 949.An James Gritton | 1187.Sh AUTHORS 1188.An -nosplit 1189The jail feature was written by 1190.An Poul-Henning Kamp 1191for R&D Associates 1192.Pa http://www.rndassociates.com/ 1193who contributed it to 1194.Fx . --- 4 unchanged lines hidden (view full) --- 1199.Pp 1200.An Bjoern A. Zeeb 1201added multi-IP jail support for IPv4 and IPv6 based on a patch 1202originally done by 1203.An Pawel Jakub Dawidek 1204for IPv4. 1205.Pp 1206.An James Gritton |
| 950added the extensible jail parameters and hierarchical jails. | 1207added the extensible jail parameters, hierarchical jails, 1208and the configuration file. |
| 951.Sh BUGS | 1209.Sh BUGS |
| 952Jail currently lacks the ability to allow access to 953specific jail information via 954.Xr ps 1 955as opposed to 956.Xr procfs 5 . 957Similarly, it might be a good idea to add an | 1210It might be a good idea to add an |
| 958address alias flag such that daemons listening on all IPs 959.Pq Dv INADDR_ANY 960will not bind on that address, which would facilitate building a safe 961host environment such that host daemons do not impose on services offered 962from within jails. 963Currently, the simplest answer is to minimize services 964offered on the host, possibly limiting it to services offered from 965.Xr inetd 8 966which is easily configurable. 967.Sh NOTES 968Great care should be taken when managing directories visible within the jail. 969For example, if a jailed process has its current working directory set to a 970directory that is moved out of the jail's chroot, then the process may gain 971access to the file space outside of the jail. 972It is recommended that directories always be copied, rather than moved, out 973of a jail. | 1211address alias flag such that daemons listening on all IPs 1212.Pq Dv INADDR_ANY 1213will not bind on that address, which would facilitate building a safe 1214host environment such that host daemons do not impose on services offered 1215from within jails. 1216Currently, the simplest answer is to minimize services 1217offered on the host, possibly limiting it to services offered from 1218.Xr inetd 8 1219which is easily configurable. 1220.Sh NOTES 1221Great care should be taken when managing directories visible within the jail. 1222For example, if a jailed process has its current working directory set to a 1223directory that is moved out of the jail's chroot, then the process may gain 1224access to the file space outside of the jail. 1225It is recommended that directories always be copied, rather than moved, out 1226of a jail. |