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