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.4 2004/11/09 08:52:46 joerg 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. 184.Pp 185Now start the jail: 186.Pp 187.Dl "jail /data/jail/192.168.11.100 testhostname 192.168.11.100 /bin/sh" 188.Pp 189You will end up with a shell prompt, assuming no errors, within the jail. 190You can now do the post-install configuration to set various configuration 191options by editing 192.Pa /etc/rc.conf , 193etc. 194.Pp 195.Bl -bullet -offset indent -compact 196.It 197Create an empty 198.Pa /etc/fstab 199to quell startup warnings about missing fstab 200.It 201Disable the port mapper 202.Pa ( /etc/rc.conf : 203.Li portmap_enable="NO" ) 204.It 205Run 206.Xr newaliases 1 207to quell 208.Xr sendmail 8 209warnings. 210.It 211Disable interface configuration to quell startup warnings about 212.Xr ifconfig 8 213.Pq Li network_interfaces="" 214.It 215Configure 216.Pa /etc/resolv.conf 217so that name resolution within the jail will work correctly 218.It 219Set a root password, probably different from the real host system 220.It 221Set the timezone with 222.Xr tzsetup 8 223.It 224Add accounts for users in the jail environment 225.It 226Install any packages that you think the environment requires 227.El 228.Pp 229You may also want to perform any package-specific configuration (web servers, 230SSH servers, etc), patch up 231.Pa /etc/syslog.conf 232so it logs as you would like, etc. 233.Pp 234Exit from the shell, and the jail will be shut down. 235.Ss "Starting the Jail" 236You are now ready to restart the jail and bring up the environment with 237all of its daemons and other programs. 238To do this, first bring up the 239virtual host interface, and then start the jail's 240.Pa /etc/rc 241script from within the jail. 242.Pp 243NOTE: If you plan to allow untrusted users to have root access inside the 244jail, you may wish to consider setting the 245.Va jail.set_hostname_allowed 246to 0. 247Please see the management reasons why this is a good idea. 248If you do decide to set this variable, 249it must be set before starting any jails, and once each boot. 250.Bd -literal -offset indent 251ifconfig ed0 inet alias 192.168.11.100/32 252mount -t procfs proc /data/jail/192.168.11.100/proc 253jail /data/jail/192.168.11.100 testhostname 192.168.11.100 \\ 254 /bin/sh /etc/rc 255.Ed 256.Pp 257A few warnings will be produced, because most 258.Xr sysctl 8 259configuration variables cannot be set from within the jail, as they are 260global across all jails and the host environment. 261However, it should all 262work properly. 263You should be able to see 264.Xr inetd 8 , 265.Xr syslogd 8 , 266and other processes running within the jail using 267.Xr ps 1 , 268with the 269.Ql J 270flag appearing beside jailed processes. 271You should also be able to 272.Xr telnet 1 273to the hostname or IP address of the jailed environment, and log 274in using the accounts you created previously. 275.Ss "Managing the Jail" 276Normal machine shutdown commands, such as 277.Xr halt 8 , 278.Xr reboot 8 , 279and 280.Xr shutdown 8 , 281cannot be used successfully within the jail. 282To kill all processes in a 283jail, you may log into the jail and, as root, use one of the following 284commands, depending on what you want to accomplish: 285.Pp 286.Bd -literal -offset indent 287kill -TERM -1 288kill -KILL -1 289.Ed 290.Pp 291This will send the 292.Dv SIGTERM 293or 294.Dv SIGKILL 295signals to all processes in the jail from within the jail. 296Depending on 297the intended use of the jail, you may also want to run 298.Pa /etc/rc.shutdown 299from within the jail. 300Currently there is no way to insert new processes 301into a jail, so you must first log into the jail before performing these 302actions. 303.Pp 304To kill processes from outside the jail, you must individually identify the 305PID of each process to be killed. 306The 307.Pa /proc/ Ns Ar pid Ns Pa /status 308file contains, as its last field, the hostname of the jail in which the 309process runs, or 310.Dq Li - 311to indicate that the process is not running within a jail. 312The 313.Xr ps 1 314command also shows a 315.Ql J 316flag for processes in a jail. 317However, the hostname for a jail may be, by 318default, modified from within the jail, so the 319.Pa /proc 320status entry is unreliable by default. 321To disable the setting of the hostname 322from within a jail, set the 323.Va jail.set_hostname_allowed 324sysctl variable in the host environment to 0, which will affect all jails. 325You can have this sysctl set on each boot using 326.Xr sysctl.conf 5 . 327Just add the following line to 328.Pa /etc/sysctl.conf : 329.Pp 330.Dl jail.set_hostname_allowed=0 331.Pp 332In a future version of 333.Dx , 334the mechanisms for managing jails may be 335more refined. 336.Ss "Sysctl MIB Entries" 337Certain aspects of the jail containments environment may be modified from 338the host environment using 339.Xr sysctl 8 340MIB variables. 341Currently, these variables affect all jails on the system, although in 342the future this functionality may be finer grained. 343.Bl -tag -width XXX 344.It Va jail.set_hostname_allowed 345This MIB entry determines whether or not processes within a jail are 346allowed to change their hostname via 347.Xr hostname 1 348or 349.Xr sethostname 3 . 350In the current jail implementation, the ability to set the hostname from 351within the jail can impact management tools relying on the accuracy of jail 352information in 353.Pa /proc . 354As such, this should be disabled in environments where privileged access to 355jails is given out to untrusted parties. 356.It Va jail.socket_unixiproute_only 357The jail functionality binds an IPv4 address to each jail, and limits 358access to other network addresses in the IPv4 space that may be available 359in the host environment. 360However, jail is not currently able to limit access to other network 361protocol stacks that have not had jail functionality added to them. 362As such, by default, processes within jails may only access protocols 363in the following domains: 364.Dv PF_LOCAL , PF_INET , 365and 366.Dv PF_ROUTE , 367permitting them access to 368.Ux 369domain sockets, 370IPv4 addresses, and routing sockets. 371To enable access to other domains, this MIB variable may be set to 3720. 373.It Va jail.sysvipc_allowed 374This MIB entry determines whether or not processes within a jail have access 375to System V IPC primitives. 376In the current jail implementation, System V primitives share a single 377namespace across the host and jail environments, meaning that processes 378within a jail would be able to communicate with (and potentially interfere 379with) processes outside of the jail, and in other jails. 380As such, this functionality is disabled by default, but can be enabled 381by setting this MIB entry to 1. 382.El 383.Sh SEE ALSO 384.Xr newaliases 1 , 385.Xr ps 1 , 386.Xr chroot 2 , 387.Xr jail 2 , 388.Xr procfs 5 , 389.Xr rc.conf 5 , 390.Xr sysctl.conf 5 , 391.Xr halt 8 , 392.Xr inetd 8 , 393.Xr named 8 , 394.Xr portmap 8 , 395.Xr pw 8 , 396.Xr reboot 8 , 397.Xr sendmail 8 , 398.Xr shutdown 8 , 399.Xr sysctl 8 , 400.Xr syslogd 8 , 401.Xr tzsetup 8 402.Sh HISTORY 403The 404.Nm 405command appeared in 406.Fx 4.0 . 407.Sh AUTHORS 408.An -nosplit 409The jail feature was written by 410.An Poul-Henning Kamp 411for R&D Associates 412.Pa http://www.rndassociates.com/ 413who contributed it to 414.Fx . 415.Pp 416.An Robert Watson 417wrote the extended documentation, found a few bugs, added 418a few new features, and cleaned up the userland jail environment. 419.Sh BUGS 420Jail currently lacks strong management functionality, such as the ability 421to deliver signals to all processes in a jail, and to allow access to 422specific jail information via 423.Xr ps 1 424as opposed to 425.Xr procfs 5 . 426Similarly, it might be a good idea to add an 427address alias flag such that daemons listening on all IPs 428.Pq Dv INADDR_ANY 429will not bind on that address, which would facilitate building a safe 430host environment such that host daemons do not impose on services offered 431from within jails. 432Currently, the simplist answer is to minimize services 433offered on the host, possibly limiting it to services offered from 434.Xr inetd 8 435which is easily configurable. 436