1.\" 2.\" Copyright (c) 2000, 2003 Robert N. M. Watson 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.\" 27.\" ---------------------------------------------------------------------------- 28.\" "THE BEER-WARE LICENSE" (Revision 42): 29.\" <phk@FreeBSD.ORG> wrote this file. As long as you retain this notice you 30.\" can do whatever you want with this stuff. If we meet some day, and you think 31.\" this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp 32.\" ---------------------------------------------------------------------------- 33.\" 34.\" $FreeBSD$ 35.\" 36.Dd April 5, 2007 37.Dt JAIL 8 38.Os 39.Sh NAME 40.Nm jail 41.Nd "imprison process and its descendants" 42.Sh SYNOPSIS 43.Nm 44.Op Fl i 45.Op Fl J Ar jid_file 46.Op Fl s Ar securelevel 47.Op Fl l u Ar username | Fl U Ar username 48.Ar path hostname ip-number command ... 49.Sh DESCRIPTION 50The 51.Nm 52utility imprisons a process and all future descendants. 53.Pp 54The options are as follows: 55.Bl -tag -width ".Fl u Ar username" 56.It Fl i 57Output the jail identifier of the newly created jail. 58.It Fl J Ar jid_file 59Write a 60.Ar jid_file 61file, containing jail identifier, path, hostname, IP and 62command used to start the jail. 63.It Fl l 64Run program in the clean environment. 65The environment is discarded except for 66.Ev HOME , SHELL , TERM 67and 68.Ev USER . 69.Ev HOME 70and 71.Ev SHELL 72are set to the target login's default values. 73.Ev USER 74is set to the target login. 75.Ev TERM 76is imported from the current environment. 77The environment variables from the login class capability database for the 78target login are also set. 79.It Fl s Ar securelevel 80Sets the 81.Va kern.securelevel 82sysctl variable to the specified value inside the newly created jail. 83.It Fl u Ar username 84The user name from host environment as whom the 85.Ar command 86should run. 87.It Fl U Ar username 88The user name from jailed environment as whom the 89.Ar command 90should run. 91.It Ar path 92Directory which is to be the root of the prison. 93.It Ar hostname 94Hostname of the prison. 95.It Ar ip-number 96IP number assigned to the prison. 97.It Ar command 98Pathname of the program which is to be executed. 99.El 100.Pp 101Jails are typically set up using one of two philosophies: either to 102constrain a specific application (possibly running with privilege), or 103to create a 104.Dq "virtual system image" 105running a variety of daemons and services. 106In both cases, a fairly complete file system install of 107.Fx 108is 109required, so as to provide the necessary command line tools, daemons, 110libraries, application configuration files, etc. 111However, for a virtual server configuration, a fair amount of 112additional work is required so as to configure the 113.Dq boot 114process. 115This manual page documents the configuration steps necessary to support 116either of these steps, although the configuration steps may be 117refined based on local requirements. 118.Pp 119Please see the 120.Xr jail 2 121man page for further details. 122.Sh EXAMPLES 123.Ss "Setting up a Jail Directory Tree" 124To set up a jail directory tree containing an entire 125.Fx 126distribution, the following 127.Xr sh 1 128command script can be used: 129.Bd -literal 130D=/here/is/the/jail 131cd /usr/src 132mkdir -p $D 133make world DESTDIR=$D 134make distribution DESTDIR=$D 135mount -t devfs devfs $D/dev 136.Ed 137.Pp 138NOTE: It is important that only appropriate device nodes in devfs be 139exposed to a jail; access to disk devices in the jail may permit processes 140in the jail to bypass the jail sandboxing by modifying files outside of 141the jail. 142See 143.Xr devfs 8 144for information on how to use devfs rules to limit access to entries 145in the per-jail devfs. 146A simple devfs ruleset for jails is available as ruleset #4 in 147.Pa /etc/defaults/devfs.rules . 148.Pp 149In many cases this example would put far more in the jail than needed. 150In the other extreme case a jail might contain only one file: 151the executable to be run in the jail. 152.Pp 153We recommend experimentation and caution that it is a lot easier to 154start with a 155.Dq fat 156jail and remove things until it stops working, 157than it is to start with a 158.Dq thin 159jail and add things until it works. 160.Ss "Setting Up a Jail" 161Do what was described in 162.Sx "Setting Up a Jail Directory Tree" 163to build the jail directory tree. 164For the sake of this example, we will 165assume you built it in 166.Pa /data/jail/192.0.2.100 , 167named for the jailed IP address. 168Substitute below as needed with your 169own directory, IP address, and hostname. 170.Ss "Setting up the Host Environment" 171First, you will want to set up your real system's environment to be 172.Dq jail-friendly . 173For consistency, we will refer to the parent box as the 174.Dq "host environment" , 175and to the jailed virtual machine as the 176.Dq "jail environment" . 177Since jail is implemented using IP aliases, one of the first things to do 178is to disable IP services on the host system that listen on all local 179IP addresses for a service. 180If a network service is present in the host environment that binds all 181available IP addresses rather than specific IP addresses, it may service 182requests sent to jail IP addresses. 183This means changing 184.Xr inetd 8 185to only listen on the 186appropriate IP address, and so forth. 187Add the following to 188.Pa /etc/rc.conf 189in the host environment: 190.Bd -literal -offset indent 191sendmail_enable="NO" 192inetd_flags="-wW -a 192.0.2.23" 193rpcbind_enable="NO" 194.Ed 195.Pp 196.Li 192.0.2.23 197is the native IP address for the host system, in this example. 198Daemons that run out of 199.Xr inetd 8 200can be easily set to use only the specified host IP address. 201Other daemons 202will need to be manually configured\(emfor some this is possible through 203the 204.Xr rc.conf 5 205flags entries; for others it is necessary to modify per-application 206configuration files, or to recompile the applications. 207The following frequently deployed services must have their individual 208configuration files modified to limit the application to listening 209to a specific IP address: 210.Pp 211To configure 212.Xr sshd 8 , 213it is necessary to modify 214.Pa /etc/ssh/sshd_config . 215.Pp 216To configure 217.Xr sendmail 8 , 218it is necessary to modify 219.Pa /etc/mail/sendmail.cf . 220.Pp 221For 222.Xr named 8 , 223it is necessary to modify 224.Pa /etc/namedb/named.conf . 225.Pp 226In addition, a number of services must be recompiled in order to run 227them in the host environment. 228This includes most applications providing services using 229.Xr rpc 3 , 230such as 231.Xr rpcbind 8 , 232.Xr nfsd 8 , 233and 234.Xr mountd 8 . 235In general, applications for which it is not possible to specify which 236IP address to bind should not be run in the host environment unless they 237should also service requests sent to jail IP addresses. 238Attempting to serve 239NFS from the host environment may also cause confusion, and cannot be 240easily reconfigured to use only specific IPs, as some NFS services are 241hosted directly from the kernel. 242Any third-party network software running 243in the host environment should also be checked and configured so that it 244does not bind all IP addresses, which would result in those services' also 245appearing to be offered by the jail environments. 246.Pp 247Once 248these daemons have been disabled or fixed in the host environment, it is 249best to reboot so that all daemons are in a known state, to reduce the 250potential for confusion later (such as finding that when you send mail 251to a jail, and its sendmail is down, the mail is delivered to the host, 252etc.). 253.Ss "Configuring the Jail" 254Start any jail for the first time without configuring the network 255interface so that you can clean it up a little and set up accounts. 256As 257with any machine (virtual or not) you will need to set a root password, time 258zone, etc. 259Some of these steps apply only if you intend to run a full virtual server 260inside the jail; others apply both for constraining a particular application 261or for running a virtual server. 262.Pp 263Start a shell in the jail: 264.Pp 265.Dl "jail /data/jail/192.0.2.100 testhostname 192.0.2.100 /bin/sh" 266.Pp 267Assuming no errors, you will end up with a shell prompt within the jail. 268You can now run 269.Pa /usr/sbin/sysinstall 270and do the post-install configuration to set various configuration options, 271or perform these actions manually by editing 272.Pa /etc/rc.conf , 273etc. 274.Pp 275.Bl -bullet -offset indent -compact 276.It 277Create an empty 278.Pa /etc/fstab 279to quell startup warnings about missing fstab (virtual server only) 280.It 281Disable the port mapper 282.Pa ( /etc/rc.conf : 283.Li rpcbind_enable="NO" ) 284(virtual server only) 285.It 286Configure 287.Pa /etc/resolv.conf 288so that name resolution within the jail will work correctly 289.It 290Run 291.Xr newaliases 1 292to quell 293.Xr sendmail 8 294warnings. 295.It 296Disable interface configuration to quell startup warnings about 297.Xr ifconfig 8 298.Pq Li network_interfaces="" 299(virtual server only) 300.It 301Set a root password, probably different from the real host system 302.It 303Set the timezone 304.It 305Add accounts for users in the jail environment 306.It 307Install any packages the environment requires 308.El 309.Pp 310You may also want to perform any package-specific configuration (web servers, 311SSH servers, etc), patch up 312.Pa /etc/syslog.conf 313so it logs as you would like, etc. 314If you are not using a virtual server, you may wish to modify 315.Xr syslogd 8 316in the host environment to listen on the syslog socket in the jail 317environment; in this example, the syslog socket would be stored in 318.Pa /data/jail/192.0.2.100/var/run/log . 319.Pp 320Exit from the shell, and the jail will be shut down. 321.Ss "Starting the Jail" 322You are now ready to restart the jail and bring up the environment with 323all of its daemons and other programs. 324If you are running a single application in the jail, substitute the 325command used to start the application for 326.Pa /etc/rc 327in the examples below. 328To start a virtual server environment, 329.Pa /etc/rc 330is run to launch various daemons and services. 331To do this, first bring up the 332virtual host interface, and then start the jail's 333.Pa /etc/rc 334script from within the jail. 335.Pp 336NOTE: If you plan to allow untrusted users to have root access inside the 337jail, you may wish to consider setting the 338.Va security.jail.set_hostname_allowed 339sysctl variable to 0. 340Please see the management discussion later in this document as to why this 341may be a good idea. 342If you do decide to set this variable, 343it must be set before starting any jails, and once each boot. 344.Bd -literal -offset indent 345ifconfig ed0 inet alias 192.0.2.100/32 346mount -t procfs proc /data/jail/192.0.2.100/proc 347jail /data/jail/192.0.2.100 testhostname 192.0.2.100 \\ 348 /bin/sh /etc/rc 349.Ed 350.Pp 351A few warnings will be produced, because most 352.Xr sysctl 8 353configuration variables cannot be set from within the jail, as they are 354global across all jails and the host environment. 355However, it should all 356work properly. 357You should be able to see 358.Xr inetd 8 , 359.Xr syslogd 8 , 360and other processes running within the jail using 361.Xr ps 1 , 362with the 363.Ql J 364flag appearing beside jailed processes. 365To see an active list of jails, use the 366.Xr jls 8 367utility. 368You should also be able to 369.Xr telnet 1 370to the hostname or IP address of the jailed environment, and log 371in using the accounts you created previously. 372.Pp 373It is possible to have jails started at boot time. 374Please refer to the 375.Dq jail_* 376variables in 377.Xr rc.conf 5 378for more information. 379The 380.Xr rc 8 381jail script provides a flexible system to start/stop jails: 382.Bd -literal 383/etc/rc.d/jail start 384/etc/rc.d/jail stop 385/etc/rc.d/jail start myjail 386/etc/rc.d/jail stop myjail 387.Ed 388.Ss "Managing the Jail" 389Normal machine shutdown commands, such as 390.Xr halt 8 , 391.Xr reboot 8 , 392and 393.Xr shutdown 8 , 394cannot be used successfully within the jail. 395To kill all processes in a 396jail, you may log into the jail and, as root, use one of the following 397commands, depending on what you want to accomplish: 398.Pp 399.Bd -literal -offset indent 400kill -TERM -1 401kill -KILL -1 402.Ed 403.Pp 404This will send the 405.Dv SIGTERM 406or 407.Dv SIGKILL 408signals to all processes in the jail from within the jail. 409Depending on 410the intended use of the jail, you may also want to run 411.Pa /etc/rc.shutdown 412from within the jail. 413To kill processes from outside the jail, use the 414.Xr jexec 8 415utility in conjunction with the one of the 416.Xr kill 1 417commands above. 418.Pp 419The 420.Pa /proc/ Ns Ar pid Ns Pa /status 421file contains, as its last field, the hostname of the jail in which the 422process runs, or 423.Dq Li - 424to indicate that the process is not running within a jail. 425The 426.Xr ps 1 427command also shows a 428.Ql J 429flag for processes in a jail. 430However, the hostname for a jail may be, by 431default, modified from within the jail, so the 432.Pa /proc 433status entry is unreliable by default. 434To disable the setting of the hostname 435from within a jail, set the 436.Va security.jail.set_hostname_allowed 437sysctl variable in the host environment to 0, which will affect all jails. 438You can have this sysctl set on each boot using 439.Xr sysctl.conf 5 . 440Just add the following line to 441.Pa /etc/sysctl.conf : 442.Pp 443.Dl security.jail.set_hostname_allowed=0 444.Pp 445You can also list/kill processes based on their jail ID. 446To show processes and their jail ID, use the following command: 447.Pp 448.Dl "ps ax -o pid,jid,args" 449.Pp 450To show and then kill processes in jail number 3 use the following commands: 451.Bd -literal -offset indent 452pgrep -lfj 3 453pkill -j 3 454.Ed 455or: 456.Pp 457.Dl "killall -j 3" 458.Ss "Sysctl MIB Entries" 459Certain aspects of the jail containments environment may be modified from 460the host environment using 461.Xr sysctl 8 462MIB variables. 463Currently, these variables affect all jails on the system, although in 464the future this functionality may be finer grained. 465.Bl -tag -width XXX 466.It Va security.jail.allow_raw_sockets 467This MIB entry determines whether or not prison root is allowed to 468create raw sockets. 469Setting this MIB to 1 allows utilities like 470.Xr ping 8 471and 472.Xr traceroute 8 473to operate inside the prison. 474If this MIB 475is set, the source IP addresses are enforced to comply 476with the IP address bound to the jail, regardless of whether or not 477the 478.Dv IP_HDRINCL 479flag has been set on the socket. 480Since raw sockets can be used to configure 481and interact with various network subsystems, extra caution should be used 482where privileged access to jails is given out to untrusted parties. 483As such, 484by default this option is disabled. 485.It Va security.jail.enforce_statfs 486This MIB entry determines which information processes in a jail are 487able to get about mount-points. 488It affects the behaviour of the following syscalls: 489.Xr statfs 2 , 490.Xr fstatfs 2 , 491.Xr getfsstat 2 492and 493.Xr fhstatfs 2 494(as well as similar compatibility syscalls). 495When set to 0, all mount-points are available without any restrictions. 496When set to 1, only mount-points below the jail's chroot directory are 497visible. 498In addition to that, the path to the jail's chroot directory is removed 499from the front of their pathnames. 500When set to 2 (default), above syscalls can operate only on a mount-point 501where the jail's chroot directory is located. 502.It Va security.jail.set_hostname_allowed 503This MIB entry determines whether or not processes within a jail are 504allowed to change their hostname via 505.Xr hostname 1 506or 507.Xr sethostname 3 . 508In the current jail implementation, the ability to set the hostname from 509within the jail can impact management tools relying on the accuracy of jail 510information in 511.Pa /proc . 512As such, this should be disabled in environments where privileged access to 513jails is given out to untrusted parties. 514.It Va security.jail.socket_unixiproute_only 515The jail functionality binds an IPv4 address to each jail, and limits 516access to other network addresses in the IPv4 space that may be available 517in the host environment. 518However, jail is not currently able to limit access to other network 519protocol stacks that have not had jail functionality added to them. 520As such, by default, processes within jails may only access protocols 521in the following domains: 522.Dv PF_LOCAL , PF_INET , 523and 524.Dv PF_ROUTE , 525permitting them access to 526.Ux 527domain sockets, 528IPv4 addresses, and routing sockets. 529To enable access to other domains, this MIB variable may be set to 5300. 531.It Va security.jail.sysvipc_allowed 532This MIB entry determines whether or not processes within a jail have access 533to System V IPC primitives. 534In the current jail implementation, System V primitives share a single 535namespace across the host and jail environments, meaning that processes 536within a jail would be able to communicate with (and potentially interfere 537with) processes outside of the jail, and in other jails. 538As such, this functionality is disabled by default, but can be enabled 539by setting this MIB entry to 1. 540.It Va security.jail.chflags_allowed 541This MIB entry determines how a privileged user inside a jail will be 542treated by 543.Xr chflags 2 . 544If zero, such users are treated as unprivileged, and are unable to set 545or clear system file flags; if non-zero, such users are treated as 546privileged, and may manipulate system file flags subject to the usual 547constraints on 548.Va kern.securelevel . 549.It Va security.jail.mount_allowed 550This MIB entry determines if a privileged user inside a jail will be 551able to mount and unmount file system types marked as jail-friendly. 552The 553.Xr lsvfs 1 554command can be used to find file system types available for mount from within 555a jail. 556This functionality is disabled by default, but can be enabled by setting this 557MIB entry to 1. 558.El 559.Pp 560The read-only sysctl variable 561.Va security.jail.jailed 562can be used to determine if a process is running inside a jail (value 563is one) or not (value is zero). 564.Pp 565The 566.Va security.jail.list 567MIB entry is read-only and it returns an array of 568.Vt "struct xprison" 569defined in 570.In sys/jail.h . 571It is recommended to use the 572.Xr jls 8 573utility to see current active list of jails. 574.Pp 575There are currently two MIB related variables that have per-jail settings. 576Changes to these variables by a jailed process do not effect the host 577environment, only the jail environment. 578The variables are 579.Va kern.securelevel 580and 581.Va kern.hostname . 582.Sh SEE ALSO 583.Xr killall 1 , 584.Xr lsvfs 1 , 585.Xr newaliases 1 , 586.Xr pgrep 1 , 587.Xr pkill 1 , 588.Xr ps 1 , 589.Xr chroot 2 , 590.Xr jail 2 , 591.Xr jail_attach 2 , 592.Xr procfs 5 , 593.Xr rc.conf 5 , 594.Xr sysctl.conf 5 , 595.Xr devfs 8 , 596.Xr halt 8 , 597.Xr inetd 8 , 598.Xr jexec 8 , 599.Xr jls 8 , 600.Xr mount 8 , 601.Xr named 8 , 602.Xr reboot 8 , 603.Xr rpcbind 8 , 604.Xr sendmail 8 , 605.Xr shutdown 8 , 606.Xr sysctl 8 , 607.Xr syslogd 8 608.Sh HISTORY 609The 610.Nm 611utility appeared in 612.Fx 4.0 . 613.Sh AUTHORS 614.An -nosplit 615The jail feature was written by 616.An Poul-Henning Kamp 617for R&D Associates 618.Pa http://www.rndassociates.com/ 619who contributed it to 620.Fx . 621.Pp 622.An Robert Watson 623wrote the extended documentation, found a few bugs, added 624a few new features, and cleaned up the userland jail environment. 625.Sh BUGS 626Jail currently lacks the ability to allow access to 627specific jail information via 628.Xr ps 1 629as opposed to 630.Xr procfs 5 . 631Similarly, it might be a good idea to add an 632address alias flag such that daemons listening on all IPs 633.Pq Dv INADDR_ANY 634will not bind on that address, which would facilitate building a safe 635host environment such that host daemons do not impose on services offered 636from within jails. 637Currently, the simplest answer is to minimize services 638offered on the host, possibly limiting it to services offered from 639.Xr inetd 8 640which is easily configurable. 641