1.\" Copyright (c) 2000, 2003 Robert N. M. Watson 2.\" Copyright (c) 2008-2012 James Gritton 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd October 12, 2013 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 is specified via parameters on the command line, or in the 67.Xr jail.conf 5 68file. 69.Pp 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: 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 122.It Fl d 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 . 131.It Fl h 132Resolve the 133.Va host.hostname 134parameter (or 135.Va hostname ) 136and add all IP addresses returned by the resolver 137to the list of addresses for this prison. 138This is equivalent to the 139.Va ip_hostname 140parameter. 141.It Fl i 142Output (only) the jail identifier of the newly created jail(s). 143This implies the 144.Fl q 145option. 146.It Fl J Ar jid_file 147Write a 148.Ar jid_file 149file, containing parameters used to start the jail. 150.It Fl l 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. 171.It Fl s Ar securelevel 172Set the 173.Va kern.securelevel 174MIB entry to the specified value inside the newly created jail. 175This is deprecated and is equivalent to the 176.Va securelevel 177parameter. 178.It Fl u Ar username 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 182and 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. 193.El 194.Pp 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 201.Fl r 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.Pp 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 . 224.Pp 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: 231.Ar path , 232.Ar hostname , 233.Ar ip , 234and 235.Ar command . 236This mode will always create a new jail, and the 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 parameters 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). 264.Pp 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. 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. 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 291or 292.Xr jexec 8 . 293.It Va name 294The jail name. 295This is an arbitrary string that identifies a jail (except it may not 296contain a 297.Sq \&. ) . 298Like the 299.Va jid , 300it can be passed to later 301.Nm 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 . 310The 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. 323.It Va ip4.addr 324A list of IPv4 addresses assigned to the prison. 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. 338Source address selection is enabled by default for all jails and the 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 347to restrict addresses via 348.Va ip4.addr 349above, and 350.Dq disable 351to stop the jail from using IPv4 entirely. 352Setting the 353.Va ip4.addr 354parameter implies a value of 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. 375.It Va host.hostname 376The hostname of the prison. 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 385.Dq inherit 386to use the system information and 387.Dq new 388for the jail to use the information from the above fields. 389Setting any of the above fields implies a value of 390.Dq new . 391.It Va securelevel 392The value of the jail's 393.Va kern.securelevel 394sysctl. 395A jail never has a lower securelevel than the default system, but by 396setting this parameter it may have a higher one. 397If the system securelevel is changed, any jail securelevels will be at 398least as secure. 399.It Va devfs_ruleset 400The number of the devfs ruleset that is enforced for mounting devfs in 401this jail. 402A value of zero (default) means no ruleset is enforced. 403Descendant jails inherit the parent jail's devfs ruleset enforcement. 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 . 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 429.Sx "Hierarchical Jails" 430section for more information. 431.It Va children.cur 432The number of descendants 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: 438.Xr statfs 2 , 439.Xr fstatfs 2 , 440.Xr getfsstat 2 441and 442.Xr fhstatfs 2 443(as well as similar compatibility syscalls). 444When set to 0, all mount points are available without any restrictions. 445When set to 1, only mount points below the jail's chroot directory are 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. 454Normally, a command is run as part of jail creation, and then the jail 455is destroyed as its last process exits. 456A new jail must have either the 457.Va persist 458parameter or 459.Va exec.start 460or 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 469.Va jid 470of the parent of this jail, or zero if this is a top-level jail 471(read-only). 472.It Va allow.* 473Some restrictions of the jail environment may be set on a per-jail 474basis. 475With the exception of 476.Va allow.set_hostname , 477these boolean parameters are off by default. 478.Bl -tag -width indent 479.It Va allow.set_hostname 480The jail's hostname may be changed via 481.Xr hostname 1 482or 483.Xr sethostname 3 . 484.It Va allow.sysvipc 485A process within the jail has access to System V IPC primitives. 486In the current jail implementation, System V primitives share a single 487namespace across the host and jail environments, meaning that processes 488within a jail would be able to communicate with (and potentially interfere 489with) processes outside of the jail, and in other jails. 490.It Va allow.raw_sockets 491The prison root is allowed to create raw sockets. 492Setting this parameter allows utilities like 493.Xr ping 8 494and 495.Xr traceroute 8 496to operate inside the prison. 497If this is set, the source IP addresses are enforced to comply 498with the IP address bound to the jail, regardless of whether or not 499the 500.Dv IP_HDRINCL 501flag has been set on the socket. 502Since raw sockets can be used to configure and interact with various 503network subsystems, extra caution should be used where privileged access 504to jails is given out to untrusted parties. 505.It Va allow.chflags 506Normally, privileged users inside a jail are treated as unprivileged by 507.Xr chflags 2 . 508When this parameter is set, such users are treated as privileged, and 509may manipulate system file flags subject to the usual constraints on 510.Va kern.securelevel . 511.It Va allow.mount 512privileged users inside the jail will be able to mount and unmount file 513system types marked as jail-friendly. 514The 515.Xr lsvfs 1 516command can be used to find file system types available for mount from 517within a jail. 518This permission is effective only if 519.Va enforce_statfs 520is set to a value lower than 2. 521.It Va allow.mount.devfs 522privileged users inside the jail will be able to mount and unmount the 523devfs file system. 524This permission is effective only together with 525.Va allow.mount 526and if 527.Va enforce_statfs 528is set to a value lower than 2. 529Please consider restricting the devfs ruleset with the 530.Va devfs_ruleset 531option. 532.It Va allow.mount.nullfs 533privileged users inside the jail will be able to mount and unmount the 534nullfs file system. 535This permission is effective only together with 536.Va allow.mount 537and if 538.Va enforce_statfs 539is set to a value lower than 2. 540.It Va allow.mount.procfs 541privileged users inside the jail will be able to mount and unmount the 542procfs file system. 543This permission is effective only together with 544.Va allow.mount 545and if 546.Va enforce_statfs 547is set to a value lower than 2. 548.It Va allow.mount.tmpfs 549privileged users inside the jail will be able to mount and unmount the 550tmpfs file system. 551This permission is effective only together with 552.Va allow.mount 553and if 554.Va enforce_statfs 555is set to a value lower than 2. 556.It Va allow.mount.zfs 557privileged users inside the jail will be able to mount and unmount the 558ZFS file system. 559This permission is effective only together with 560.Va allow.mount 561and if 562.Va enforce_statfs 563is set to a value lower than 2. 564See 565.Xr zfs 8 566for information on how to configure the ZFS filesystem to operate from 567within a jail. 568.It Va allow.quotas 569The prison root may administer quotas on the jail's filesystem(s). 570This includes filesystems that the jail may share with other jails or 571with non-jailed parts of the system. 572.It Va allow.socket_af 573Sockets within a jail are normally restricted to IPv4, IPv6, local 574(UNIX), and route. This allows access to other protocol stacks that 575have not had jail functionality added to them. 576.El 577.El 578.Pp 579There are pseudo-parameters that aren't passed to the kernel, but are 580used by 581.Nm 582to set up the prison environment, often by running specified commands 583when jails are created or removed. 584The 585.Va exec.* 586command parameters are 587.Xr sh 1 588command lines that are run in either the system or prison environment. 589They may be given multiple values, which run would the specified 590commands in sequence. 591All commands must succeed (return a zero exit status), or the jail will 592not be created or removed. 593.Pp 594The pseudo-parameters are: 595.Bl -tag -width indent 596.It Va exec.prestart 597Command(s) to run in the system environment before a prison is created. 598.It Va exec.start 599Command(s) to run in the prison environment when a jail is created. 600A typical command to run is 601.Dq sh /etc/rc . 602.It Va command 603A synonym for 604.Va exec.start 605for use when specifying a prison directly on the command line. 606Unlike other parameters whose value is a single string, 607.Va command 608uses the remainder of the 609.Nm 610command line as its own arguments. 611.It Va exec.poststart 612Command(s) to run in the system environment after a jail is created, 613and after any 614.Va exec.start 615commands have completed. 616.It Va exec.prestop 617Command(s) to run in the system environment before a jail is removed. 618.It Va exec.stop 619Command(s) to run in the prison environment before a jail is removed, 620and after any 621.Va exec.prestop 622commands have completed. 623A typical command to run is 624.Dq sh /etc/rc.shutdown . 625.It Va exec.poststop 626Command(s) to run in the system environment after a jail is removed. 627.It Va exec.clean 628Run commands in a clean environment. 629The environment is discarded except for 630.Ev HOME , SHELL , TERM 631and 632.Ev USER . 633.Ev HOME 634and 635.Ev SHELL 636are set to the target login's default values. 637.Ev USER 638is set to the target login. 639.Ev TERM 640is imported from the current environment. 641The environment variables from the login class capability database for the 642target login are also set. 643.It Va exec.jail_user 644The user to run commands as, when running in the prison environment. 645The default is to run the commands as the current user. 646.It Va exec.system_jail_user 647This boolean option looks for the 648.Va exec.jail_user 649in the system 650.Xr passwd 5 651file, instead of in the prison's file. 652.It Va exec.system_user 653The user to run commands as, when running in the system environment. 654The default is to run the commands as the current user. 655.It Va exec.timeout 656The maximum amount of time to wait for a command to complete. 657If a command is still running after this many seconds have passed, 658the jail not be created or removed. 659.It Va exec.consolelog 660A file to direct command output (stdout and stderr) to. 661.It Va exec.fib 662The FIB (routing table) to set when running commands inside the prison. 663.It Va stop.timeout 664The maximum amount of time to wait for a prison's processes to exit 665after sending them a 666.Dv SIGTERM 667signal (which happens after the 668.Va exec.stop 669commands have completed). 670After this many seconds have passed, the prison will be removed, which 671will kill any remaining processes. 672If this is set to zero, no 673.Dv SIGTERM 674is sent and the prison is immediately removed. 675The default is 10 seconds. 676.It Va interface 677A network interface to add the prison's IP addresses 678.Va ( ip4.addr 679and 680.Va ip6.addr ) 681to. 682An alias for each address will be added to the interface before the 683prison is created, and will be removed from the interface after the 684prison is removed. 685.It Va ip4.addr 686In addition to the IP addresses that are passed to the kernel, and 687interface and/or a netmask may also be specified, in the form 688.Dq Ar interface Ns | Ns Ar ip-address Ns / Ns Ar netmask . 689If an interface is given before the IP address, an alias for the address 690will be added to that interface, as it is with the 691.Va interface 692parameter. If a netmask in either dotted-quad or CIDR form is given 693after IP address, it will be used when adding the IP alias. 694.It Va ip6.addr 695In addition to the IP addresses that are passed to the kernel, 696and interface and/or a prefix may also be specified, in the form 697.Dq Ar interface Ns | Ns Ar ip-address Ns / Ns Ar prefix . 698.It Va vnet.interface 699A network interface to give to a vnet-enabled jail after is it created. 700The interface will automatically be returned when the jail is removed. 701.It Va ip_hostname 702Resolve the 703.Va host.hostname 704parameter and add all IP addresses returned by the resolver 705to the list of addresses 706.Va ( ip4.addr 707or 708.Va ip6.addr ) 709for this prison. 710This may affect default address selection for outgoing IPv4 connections 711of prisons. 712The address first returned by the resolver for each address family 713will be used as primary address. 714.It Va mount 715A filesystem to mount before creating the jail (and to unmount after 716removing it), given as a single 717.Xr fstab 5 718line. 719.It Va mount.fstab 720An 721.Xr fstab 5 722format file containing filesystems to mount before creating a jail. 723.It Va mount.devfs 724Mount a 725.Xr devfs 5 726filesystem on the chrooted 727.Pa /dev 728directory, and apply the ruleset in the 729.Va devfs_ruleset 730parameter (or a default of ruleset 4: devfsrules_jail) 731to restrict the devices visible inside the prison. 732.It Va mount.fdescfs 733Mount a 734.Xr fdescfs 5 735filesystem on the chrooted 736.Pa /dev/fd 737directory. 738.It Va allow.dying 739Allow making changes to a 740.Va dying 741jail. 742.It Va depend 743Specify a jail (or jails) that this jail depends on. 744Any such jails must be fully created, up to the last 745.Va exec.poststart 746command, before any action will taken to create this jail. 747When jails are removed the opposite is true: 748this jail must be fully removed, up to the last 749.Va exec.poststop 750command, before the jail(s) it depends on are stopped. 751.El 752.Sh EXAMPLES 753Jails are typically set up using one of two philosophies: either to 754constrain a specific application (possibly running with privilege), or 755to create a 756.Dq "virtual system image" 757running a variety of daemons and services. 758In both cases, a fairly complete file system install of 759.Fx 760is 761required, so as to provide the necessary command line tools, daemons, 762libraries, application configuration files, etc. 763However, for a virtual server configuration, a fair amount of 764additional work is required so as to configure the 765.Dq boot 766process. 767This manual page documents the configuration steps necessary to support 768either of these steps, although the configuration steps may be 769refined based on local requirements. 770.Ss "Setting up a Jail Directory Tree" 771To set up a jail directory tree containing an entire 772.Fx 773distribution, the following 774.Xr sh 1 775command script can be used: 776.Bd -literal 777D=/here/is/the/jail 778cd /usr/src 779mkdir -p $D 780make world DESTDIR=$D 781make distribution DESTDIR=$D 782.Ed 783.Pp 784In many cases this example would put far more in the jail than needed. 785In the other extreme case a jail might contain only one file: 786the executable to be run in the jail. 787.Pp 788We recommend experimentation and caution that it is a lot easier to 789start with a 790.Dq fat 791jail and remove things until it stops working, 792than it is to start with a 793.Dq thin 794jail and add things until it works. 795.Ss "Setting Up a Jail" 796Do what was described in 797.Sx "Setting Up a Jail Directory Tree" 798to build the jail directory tree. 799For the sake of this example, we will 800assume you built it in 801.Pa /data/jail/testjail , 802for a jail named 803.Dq testjail . 804Substitute below as needed with your 805own directory, IP address, and hostname. 806.Ss "Setting up the Host Environment" 807First, you will want to set up your real system's environment to be 808.Dq jail-friendly . 809For consistency, we will refer to the parent box as the 810.Dq "host environment" , 811and to the jailed virtual machine as the 812.Dq "jail environment" . 813Since jail is implemented using IP aliases, one of the first things to do 814is to disable IP services on the host system that listen on all local 815IP addresses for a service. 816If a network service is present in the host environment that binds all 817available IP addresses rather than specific IP addresses, it may service 818requests sent to jail IP addresses if the jail did not bind the port. 819This means changing 820.Xr inetd 8 821to only listen on the 822appropriate IP address, and so forth. 823Add the following to 824.Pa /etc/rc.conf 825in the host environment: 826.Bd -literal -offset indent 827sendmail_enable="NO" 828inetd_flags="-wW -a 192.0.2.23" 829rpcbind_enable="NO" 830.Ed 831.Pp 832.Li 192.0.2.23 833is the native IP address for the host system, in this example. 834Daemons that run out of 835.Xr inetd 8 836can be easily set to use only the specified host IP address. 837Other daemons 838will need to be manually configured\(emfor some this is possible through 839the 840.Xr rc.conf 5 841flags entries; for others it is necessary to modify per-application 842configuration files, or to recompile the applications. 843The following frequently deployed services must have their individual 844configuration files modified to limit the application to listening 845to a specific IP address: 846.Pp 847To configure 848.Xr sshd 8 , 849it is necessary to modify 850.Pa /etc/ssh/sshd_config . 851.Pp 852To configure 853.Xr sendmail 8 , 854it is necessary to modify 855.Pa /etc/mail/sendmail.cf . 856.Pp 857For 858.Xr named 8 , 859it is necessary to modify 860.Pa /etc/namedb/named.conf . 861.Pp 862In addition, a number of services must be recompiled in order to run 863them in the host environment. 864This includes most applications providing services using 865.Xr rpc 3 , 866such as 867.Xr rpcbind 8 , 868.Xr nfsd 8 , 869and 870.Xr mountd 8 . 871In general, applications for which it is not possible to specify which 872IP address to bind should not be run in the host environment unless they 873should also service requests sent to jail IP addresses. 874Attempting to serve 875NFS from the host environment may also cause confusion, and cannot be 876easily reconfigured to use only specific IPs, as some NFS services are 877hosted directly from the kernel. 878Any third-party network software running 879in the host environment should also be checked and configured so that it 880does not bind all IP addresses, which would result in those services' also 881appearing to be offered by the jail environments. 882.Pp 883Once 884these daemons have been disabled or fixed in the host environment, it is 885best to reboot so that all daemons are in a known state, to reduce the 886potential for confusion later (such as finding that when you send mail 887to a jail, and its sendmail is down, the mail is delivered to the host, 888etc.). 889.Ss "Configuring the Jail" 890Start any jail for the first time without configuring the network 891interface so that you can clean it up a little and set up accounts. 892As 893with any machine (virtual or not) you will need to set a root password, time 894zone, etc. 895Some of these steps apply only if you intend to run a full virtual server 896inside the jail; others apply both for constraining a particular application 897or for running a virtual server. 898.Pp 899Start a shell in the jail: 900.Bd -literal -offset indent 901jail -c path=/data/jail/testjail mount.devfs \\ 902 host.hostname=testhostname ip4.addr=192.0.2.100 \\ 903 command=/bin/sh 904.Ed 905.Pp 906Assuming no errors, you will end up with a shell prompt within the jail. 907You can now run 908.Pa /usr/sbin/sysinstall 909and do the post-install configuration to set various configuration options, 910or perform these actions manually by editing 911.Pa /etc/rc.conf , 912etc. 913.Pp 914.Bl -bullet -offset indent -compact 915.It 916Configure 917.Pa /etc/resolv.conf 918so that name resolution within the jail will work correctly 919.It 920Run 921.Xr newaliases 1 922to quell 923.Xr sendmail 8 924warnings. 925.It 926Set a root password, probably different from the real host system 927.It 928Set the timezone 929.It 930Add accounts for users in the jail environment 931.It 932Install any packages the environment requires 933.El 934.Pp 935You may also want to perform any package-specific configuration (web servers, 936SSH servers, etc), patch up 937.Pa /etc/syslog.conf 938so it logs as you would like, etc. 939If you are not using a virtual server, you may wish to modify 940.Xr syslogd 8 941in the host environment to listen on the syslog socket in the jail 942environment; in this example, the syslog socket would be stored in 943.Pa /data/jail/testjail/var/run/log . 944.Pp 945Exit from the shell, and the jail will be shut down. 946.Ss "Starting the Jail" 947You are now ready to restart the jail and bring up the environment with 948all of its daemons and other programs. 949Create an entry for the jail in 950.Pa /etc/jail.conf : 951.Bd -literal -offset indent 952testjail { 953 path = /tmp/jail/testjail; 954 mount.devfs; 955 host.hostname = testhostname; 956 ip4.addr = 192.0.2.100; 957 interface = ed0; 958 exec.start = "/bin/sh /etc/rc"; 959 exec.stop = "/bin/sh /etc/rc.shutdown"; 960} 961.Ed 962.Pp 963To start a virtual server environment, 964.Pa /etc/rc 965is run to launch various daemons and services, and 966.Pa /etc/rc.shutdown 967is run to shut them down when the jail is removed. 968If you are running a single application in the jail, 969substitute the command used to start the application for 970.Dq /bin/sh /etc/rc ; 971there may be some script available to cleanly shut down the application, 972or it may be sufficient to go without a stop command, and have 973.Nm 974send 975.Dv SIGTERM 976to the application. 977.Pp 978Start the jail by running: 979.Bd -literal -offset indent 980jail -c testjail 981.Ed 982.Pp 983A few warnings may be produced; however, it should all work properly. 984You should be able to see 985.Xr inetd 8 , 986.Xr syslogd 8 , 987and other processes running within the jail using 988.Xr ps 1 , 989with the 990.Ql J 991flag appearing beside jailed processes. 992To see an active list of jails, use the 993.Xr jls 8 994utility. 995You should also be able to 996.Xr telnet 1 997to the hostname or IP address of the jailed environment, and log 998in using the accounts you created previously. 999.Pp 1000It is possible to have jails started at boot time. 1001Please refer to the 1002.Dq jail_* 1003variables in 1004.Xr rc.conf 5 1005for more information. 1006.Ss "Managing the Jail" 1007Normal machine shutdown commands, such as 1008.Xr halt 8 , 1009.Xr reboot 8 , 1010and 1011.Xr shutdown 8 , 1012cannot be used successfully within the jail. 1013To kill all processes from within a jail, you may use one of the 1014following commands, depending on what you want to accomplish: 1015.Bd -literal -offset indent 1016kill -TERM -1 1017kill -KILL -1 1018.Ed 1019.Pp 1020This will send the 1021.Dv SIGTERM 1022or 1023.Dv SIGKILL 1024signals to all processes in the jail - be careful not to run this from 1025the host environment! 1026Once all of the jail's processes have died, unless the jail was created 1027with the 1028.Va persist 1029parameter, the jail will be removed. 1030Depending on 1031the intended use of the jail, you may also want to run 1032.Pa /etc/rc.shutdown 1033from within the jail. 1034.Pp 1035To shut down the jail from the outside, simply remove it with 1036.Nm 1037.Ar -r , 1038which will run any commands specified by 1039.Va exec.stop , 1040and then send 1041.Dv SIGTERM 1042and eventually 1043.Dv SIGKILL 1044to any remaining jailed processes. 1045.Pp 1046The 1047.Pa /proc/ Ns Ar pid Ns Pa /status 1048file contains, as its last field, the name of the jail in which the 1049process runs, or 1050.Dq Li - 1051to indicate that the process is not running within a jail. 1052The 1053.Xr ps 1 1054command also shows a 1055.Ql J 1056flag for processes in a jail. 1057.Pp 1058You can also list/kill processes based on their jail ID. 1059To show processes and their jail ID, use the following command: 1060.Pp 1061.Dl "ps ax -o pid,jid,args" 1062.Pp 1063To show and then kill processes in jail number 3 use the following commands: 1064.Bd -literal -offset indent 1065pgrep -lfj 3 1066pkill -j 3 1067.Ed 1068or: 1069.Pp 1070.Dl "killall -j 3" 1071.Ss "Jails and File Systems" 1072It is not possible to 1073.Xr mount 8 1074or 1075.Xr umount 8 1076any file system inside a jail unless the file system is marked 1077jail-friendly, the jail's 1078.Va allow.mount 1079parameter is set and the jail's 1080.Va enforce_statfs 1081parameter is lower than 2. 1082.Pp 1083Multiple jails sharing the same file system can influence each other. 1084For example a user in one jail can fill the file system also 1085leaving no space for processes in the other jail. 1086Trying to use 1087.Xr quota 1 1088to prevent this will not work either as the file system quotas 1089are not aware of jails but only look at the user and group IDs. 1090This means the same user ID in two jails share the same file 1091system quota. 1092One would need to use one file system per jail to make this work. 1093.Ss "Sysctl MIB Entries" 1094The read-only entry 1095.Va security.jail.jailed 1096can be used to determine if a process is running inside a jail (value 1097is one) or not (value is zero). 1098.Pp 1099The variable 1100.Va security.jail.max_af_ips 1101determines how may address per address family a prison may have. 1102The default is 255. 1103.Pp 1104Some MIB variables have per-jail settings. 1105Changes to these variables by a jailed process do not effect the host 1106environment, only the jail environment. 1107These variables are 1108.Va kern.securelevel , 1109.Va kern.hostname , 1110.Va kern.domainname , 1111.Va kern.hostid , 1112and 1113.Va kern.hostuuid . 1114.Ss "Hierarchical Jails" 1115By setting a jail's 1116.Va children.max 1117parameter, processes within a jail may be able to create jails of their own. 1118These child jails are kept in a hierarchy, with jails only able to see and/or 1119modify the jails they created (or those jails' children). 1120Each jail has a read-only 1121.Va parent 1122parameter, containing the 1123.Va jid 1124of the jail that created it; a 1125.Va jid 1126of 0 indicates the jail is a child of the current jail (or is a top-level 1127jail if the current process isn't jailed). 1128.Pp 1129Jailed processes are not allowed to confer greater permissions than they 1130themselves are given, e.g. if a jail is created with 1131.Va allow.nomount , 1132it is not able to create a jail with 1133.Va allow.mount 1134set. 1135Similarly, such restrictions as 1136.Va ip4.addr 1137and 1138.Va securelevel 1139may not be bypassed in child jails. 1140.Pp 1141A child jail may in turn create its own child jails if its own 1142.Va children.max 1143parameter is set (remember it is zero by default). 1144These jails are visible to and can be modified by their parent and all 1145ancestors. 1146.Pp 1147Jail names reflect this hierarchy, with a full name being an MIB-type string 1148separated by dots. 1149For example, if a base system process creates a jail 1150.Dq foo , 1151and a process under that jail creates another jail 1152.Dq bar , 1153then the second jail will be seen as 1154.Dq foo.bar 1155in the base system (though it is only seen as 1156.Dq bar 1157to any processes inside jail 1158.Dq foo ) . 1159Jids on the other hand exist in a single space, and each jail must have a 1160unique jid. 1161.Pp 1162Like the names, a child jail's 1163.Va path 1164appears relative to its creator's own 1165.Va path . 1166This is by virtue of the child jail being created in the chrooted 1167environment of the first jail. 1168.Sh SEE ALSO 1169.Xr killall 1 , 1170.Xr lsvfs 1 , 1171.Xr newaliases 1 , 1172.Xr pgrep 1 , 1173.Xr pkill 1 , 1174.Xr ps 1 , 1175.Xr quota 1 , 1176.Xr jail_set 2 , 1177.Xr devfs 5 , 1178.Xr fdescfs 5 , 1179.Xr jail.conf 5 , 1180.Xr procfs 5 , 1181.Xr rc.conf 5 , 1182.Xr sysctl.conf 5 , 1183.Xr chroot 8 , 1184.Xr devfs 8 , 1185.Xr halt 8 , 1186.Xr inetd 8 , 1187.Xr jexec 8 , 1188.Xr jls 8 , 1189.Xr mount 8 , 1190.Xr named 8 , 1191.Xr reboot 8 , 1192.Xr rpcbind 8 , 1193.Xr sendmail 8 , 1194.Xr shutdown 8 , 1195.Xr sysctl 8 , 1196.Xr syslogd 8 , 1197.Xr umount 8 1198.Sh HISTORY 1199The 1200.Nm 1201utility appeared in 1202.Fx 4.0 . 1203Hierarchical/extensible jails were introduced in 1204.Fx 8.0 . 1205The configuration file was introduced in 1206.Fx 9.1 . 1207.Sh AUTHORS 1208.An -nosplit 1209The jail feature was written by 1210.An Poul-Henning Kamp 1211for R&D Associates 1212.Pa http://www.rndassociates.com/ 1213who contributed it to 1214.Fx . 1215.Pp 1216.An Robert Watson 1217wrote the extended documentation, found a few bugs, added 1218a few new features, and cleaned up the userland jail environment. 1219.Pp 1220.An Bjoern A. Zeeb 1221added multi-IP jail support for IPv4 and IPv6 based on a patch 1222originally done by 1223.An Pawel Jakub Dawidek 1224for IPv4. 1225.Pp 1226.An James Gritton 1227added the extensible jail parameters, hierarchical jails, 1228and the configuration file. 1229.Sh BUGS 1230It might be a good idea to add an 1231address alias flag such that daemons listening on all IPs 1232.Pq Dv INADDR_ANY 1233will not bind on that address, which would facilitate building a safe 1234host environment such that host daemons do not impose on services offered 1235from within jails. 1236Currently, the simplest answer is to minimize services 1237offered on the host, possibly limiting it to services offered from 1238.Xr inetd 8 1239which is easily configurable. 1240.Sh NOTES 1241Great care should be taken when managing directories visible within the jail. 1242For example, if a jailed process has its current working directory set to a 1243directory that is moved out of the jail's chroot, then the process may gain 1244access to the file space outside of the jail. 1245It is recommended that directories always be copied, rather than moved, out 1246of a jail. 1247.Pp 1248In addition, there are several ways in which an unprivileged user 1249outside the jail can cooperate with a privileged user inside the jail 1250and thereby obtain elevated privileges in the host environment. 1251Most of these attacks can be mitigated by ensuring that the jail root 1252is not accessible to unprivileged users in the host environment. 1253Regardless, as a general rule, untrusted users with privileged access 1254to a jail should not be given access to the host environment. 1255