1.\" 2.\" Copyright (c) 2000 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: src/usr.sbin/jail/jail.8,v 1.13.2.15 2003/05/08 13:04:24 maxim Exp $ 35.\" 36.Dd August 6, 2009 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 u Ar username | Fl U Ar username 46.Ar path hostname ip-list command ... 47.Sh DESCRIPTION 48The 49.Nm 50command 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 , SHELL , TERM 60and 61.Ev USER . 62.Ev HOME 63and 64.Ev SHELL 65are set to the target login's default values. 66.Ev USER 67is set to the target login. 68.Ev TERM 69is imported from the current environment. 70The environment variables from the login class capability database for the 71target login are also set. 72.It Fl u Ar username 73The user name as whom the 74.Ar command 75should run. 76.It Fl U Ar username 77The user name from jailed environment as whom the 78.Ar command 79should run. 80.It Ar path 81Directory which is to be the root of the prison. 82.It Ar hostname 83Hostname of the prison. 84.It Ar ip-list 85Comma separated IP list assigned to the prison. 86.It Ar command 87Pathname of the program which is to be executed. 88.El 89.Pp 90Please see the 91.Xr jail 2 92man page for further details. 93.Sh EXAMPLES 94.Ss "Setting Up a Jail Directory Tree" 95This example shows how to setup a jail directory tree 96containing an entire 97.Dx 98distribution, provided that you built world before already: 99.Bd -literal 100D=/here/is/the/jail 101cd /usr/src 102mkdir -p $D 103make installworld DESTDIR=$D 104cd etc 105make distribution DESTDIR=$D 106cd $D 107ln -sf dev/null boot/kernel 108.Ed 109.Pp 110In many cases this example would put far more stuff in the jail than is needed. 111In the other extreme case a jail might contain only one single file: 112the executable to be run in the jail. 113.Pp 114We recommend experimentation and caution that it is a lot easier to 115start with a 116.Dq fat 117jail and remove things until it stops working, 118than it is to start with a 119.Dq thin 120jail and add things until it works. 121.Ss "Setting Up a Jail" 122Do what was described in 123.Sx "Setting Up a Jail Directory Tree" 124to build the jail directory tree. 125For the sake of this example, we will 126assume you built it in 127.Pa /data/jail/192.168.11.100 , 128named for the external jail IP address. 129Substitute below as needed with your 130own directory, IP addresses, and hostname. 131.Pp 132First, you will want to set up your real system's environment to be 133.Dq jail-friendly . 134For consistency, we will refer to the parent box as the 135.Dq "host environment" , 136and to the jailed virtual machine as the 137.Dq "jail environment" . 138Because jail is implemented using IP aliases, one of the first things to do 139is to disable IP services on the host system that listen on all local 140IP addresses for a service. 141This means changing 142.Xr inetd 8 143to only listen on the 144appropriate IP address, and so forth. 145Add the following to 146.Pa /etc/rc.conf 147in the host environment: 148.Bd -literal -offset indent 149sendmail_enable="NO" 150inetd_flags="-wW -a 192.168.11.23" 151rpcbind_enable="NO" 152.Ed 153.Pp 154.Li 192.168.11.23 155is the native IP address for the host system, in this example. 156Daemons that run out of 157.Xr inetd 8 158can be easily set to use only the specified host IP address. 159Other daemons 160will need to be manually configured\(emfor some this is possible through 161the 162.Xr rc.conf 5 163flags entries, for others it is not possible without munging 164the per-application configuration files, or even recompiling. 165For those 166applications that cannot specify the IP they run on, it is better to disable 167them, if possible. 168.Pp 169A number of daemons ship with the base system that may have problems when 170run from outside of a jail in a jail-centric environment. 171This includes 172.Xr sendmail 8 , 173.Xr named 8 , 174and 175.Xr rpcbind 8 . 176While 177.Xr sendmail 8 178and 179.Xr named 8 180can be configured to listen only on a specific 181IP using their configuration files, in most cases it is easier to simply 182run the daemons in jails only, and not in the host environment. 183Attempting to serve 184NFS from the host environment may also cause confusion, and cannot be 185easily reconfigured to use only specific IPs, as some NFS services are 186hosted directly from the kernel. 187Any third party network software running 188in the host environment should also be checked and configured so that it 189does not bind all IP addresses, which would result in those services also 190appearing to be offered by the jail environments. 191.Pp 192Once 193these daemons have been disabled or fixed in the host environment, it is 194best to reboot so that all daemons are in a known state, to reduce the 195potential for confusion later (such as finding that when you send mail 196to a jail, and its sendmail is down, the mail is delivered to the host, 197etc.) 198.Pp 199Start any jails for the first time without configuring the network 200interface so that you can clean it up a little and set up accounts. 201As 202with any machine (virtual or not) you will need to set a root password, time 203zone, etc. 204.Pp 205Now start the jail: 206.Pp 207.Dl "jail /data/jail/192.168.11.100 testhostname 127.0.0.1,192.168.11.100 /bin/sh" 208.Pp 209You will end up with a shell prompt, assuming no errors, within the jail. 210You can now do the post-install configuration to set various configuration 211options by editing 212.Pa /etc/rc.conf , 213etc. 214.Pp 215.Bl -bullet -offset indent -compact 216.It 217Disable the port mapper 218.Pa ( /etc/rc.conf : 219.Li rpcbind_enable="NO" ) 220.It 221Run 222.Xr newaliases 1 223to quell 224.Xr sendmail 8 225warnings. 226.It 227Disable interface configuration to quell startup warnings about 228.Xr ifconfig 8 229.Pq Li network_interfaces="" 230.It 231Configure 232.Pa /etc/resolv.conf 233so that name resolution within the jail will work correctly 234.It 235Set a root password, probably different from the real host system 236.It 237Set the timezone with 238.Xr tzsetup 8 239.It 240Add accounts for users in the jail environment 241.It 242Install any packages that you think the environment requires 243.El 244.Pp 245You may also want to perform any package-specific configuration (web servers, 246SSH servers, etc), patch up 247.Pa /etc/syslog.conf 248so it logs as you would like, etc. 249.Pp 250Exit from the shell, and the jail will be shut down. 251.Ss "Starting the Jail" 252You are now ready to restart the jail and bring up the environment with 253all of its daemons and other programs. 254To do this, first bring up the 255virtual host interface, and then start the jail's 256.Pa /etc/rc 257script from within the jail. 258.Pp 259NOTE: If you plan to allow untrusted users to have root access inside the 260jail, you may wish to consider setting the 261.Va jail.set_hostname_allowed 262to 0. 263Please see the management reasons why this is a good idea. 264If you do decide to set this variable, 265it must be set before starting any jails, and once each boot. 266.Bd -literal -offset indent 267ifconfig ed0 inet alias 192.168.11.100/32 268mount -t procfs proc /data/jail/192.168.11.100/proc 269jail /data/jail/192.168.11.100 testhostname 127.0.0.1,192.168.11.100 \\ 270 /bin/sh /etc/rc 271.Ed 272.Pp 273A few warnings will be produced, because most 274.Xr sysctl 8 275configuration variables cannot be set from within the jail, as they are 276global across all jails and the host environment. 277However, it should all 278work properly. 279You should be able to see 280.Xr inetd 8 , 281.Xr syslogd 8 , 282and other processes running within the jail using 283.Xr ps 1 , 284with the 285.Ql J 286flag appearing beside jailed processes. 287You should also be able to 288.Xr telnet 1 289to the hostname or IP address of the jailed environment, and log 290in using the accounts you created previously. 291.Ss "Managing the Jail" 292Normal machine shutdown commands, such as 293.Xr halt 8 , 294.Xr reboot 8 , 295and 296.Xr shutdown 8 , 297cannot be used successfully within the jail. 298To kill all processes in a 299jail, you may log into the jail and, as root, use one of the following 300commands, depending on what you want to accomplish: 301.Bd -literal -offset indent 302kill -TERM -1 303kill -KILL -1 304.Ed 305.Pp 306This will send the 307.Dv SIGTERM 308or 309.Dv SIGKILL 310signals to all processes in the jail from within the jail. 311Depending on 312the intended use of the jail, you may also want to run 313.Pa /etc/rc.shutdown 314from within the jail. 315Currently there is no way to insert new processes 316into a jail, so you must first log into the jail before performing these 317actions. 318.Pp 319To kill processes from outside the jail, you must individually identify the 320PID of each process to be killed. 321The 322.Pa /proc/ Ns Ar pid Ns Pa /status 323file contains, as its last field, the hostname of the jail in which the 324process runs, or 325.Dq Li - 326to indicate that the process is not running within a jail. 327The 328.Xr ps 1 329command also shows a 330.Ql J 331flag for processes in a jail. 332However, the hostname for a jail may be, by 333default, modified from within the jail, so the 334.Pa /proc 335status entry is unreliable by default. 336To disable the setting of the hostname 337from within a jail, set the 338.Va jail.set_hostname_allowed 339sysctl variable in the host environment to 0, which will affect all jails. 340You can have this sysctl set on each boot using 341.Xr sysctl.conf 5 . 342Just add the following line to 343.Pa /etc/sysctl.conf : 344.Pp 345.Dl jail.set_hostname_allowed=0 346.Pp 347In a future version of 348.Dx , 349the mechanisms for managing jails may be 350more refined. 351.Ss "Sysctl MIB Entries" 352Certain aspects of the jail containments environment may be modified from 353the host environment using 354.Xr sysctl 8 355MIB variables. 356Currently, these variables affect all jails on the system, although in 357the future this functionality may be finer grained. 358.Bl -tag -width XXX 359.It Va jail.set_hostname_allowed 360This MIB entry determines whether or not processes within a jail are 361allowed to change their hostname via 362.Xr hostname 1 363or 364.Xr sethostname 3 . 365In the current jail implementation, the ability to set the hostname from 366within the jail can impact management tools relying on the accuracy of jail 367information in 368.Pa /proc . 369As such, this should be disabled in environments where privileged access to 370jails is given out to untrusted parties. 371.It Va jail.socket_unixiproute_only 372The jail functionality binds IPv4 and IPv6 addresses to each jail, and limits 373access to other network addresses in the IPv4 and IPv6 space that may be available 374in the host environment. 375However, jail is not currently able to limit access to other network 376protocol stacks that have not had jail functionality added to them. 377As such, by default, processes within jails may only access protocols 378in the following domains: 379.Dv PF_LOCAL , PF_INET , PF_INET6 , 380and 381.Dv PF_ROUTE , 382permitting them access to 383.Ux 384domain sockets, 385IPv4 and IPv6 addresses, and routing sockets. 386To enable access to other domains, this MIB variable may be set to 3870. 388.It Va jail.sysvipc_allowed 389This MIB entry determines whether or not processes within a jail have access 390to System V IPC primitives. 391In the current jail implementation, System V primitives share a single 392namespace across the host and jail environments, meaning that processes 393within a jail would be able to communicate with (and potentially interfere 394with) processes outside of the jail, and in other jails. 395As such, this functionality is disabled by default, but can be enabled 396by setting this MIB entry to 1. 397.El 398.Sh SEE ALSO 399.Xr newaliases 1 , 400.Xr ps 1 , 401.Xr chroot 2 , 402.Xr jail 2 , 403.Xr procfs 5 , 404.Xr rc.conf 5 , 405.Xr sysctl.conf 5 , 406.Xr halt 8 , 407.Xr inetd 8 , 408.Xr named 8 , 409.Xr pw 8 , 410.Xr reboot 8 , 411.Xr rpcbind 8 , 412.Xr sendmail 8 , 413.Xr shutdown 8 , 414.Xr sysctl 8 , 415.Xr syslogd 8 , 416.Xr tzsetup 8 417.Sh HISTORY 418The 419.Nm 420command appeared in 421.Fx 4.0 . 422.Pp 423Support for multiple IPs and IPv6 appeared in 424.Dx 4251.7. 426.Sh AUTHORS 427.An -nosplit 428The jail feature was written by 429.An Poul-Henning Kamp 430for R&D Associates 431.Pa http://www.rndassociates.com/ 432who contributed it to 433.Fx . 434.Pp 435.An Robert Watson 436wrote the extended documentation, found a few bugs, added 437a few new features, and cleaned up the userland jail environment. 438.Pp 439.An Victor Balada Diaz 440wrote the support for multiple IPs and IPv6. Multiple IPs support 441is based on work done by 442.An Pawel Jakub Dawidek . 443.Sh BUGS 444Jail currently lacks strong management functionality, such as the ability 445to deliver signals to all processes in a jail, and to allow access to 446specific jail information via 447.Xr ps 1 448as opposed to 449.Xr procfs 5 . 450Similarly, it might be a good idea to add an 451address alias flag such that daemons listening on all IPs 452.Pq Dv INADDR_ANY 453will not bind on that address, which would facilitate building a safe 454host environment such that host daemons do not impose on services offered 455from within jails. 456Currently, the simplist answer is to minimize services 457offered on the host, possibly limiting it to services offered from 458.Xr inetd 8 459which is easily configurable. 460