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