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