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