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$ 35.\" 36.Dd April 28, 1999 37.Dt JAIL 8 38.Os FreeBSD 4.0 39.Sh NAME 40.Nm jail 41.Nd imprison process and its descendants 42.Sh SYNOPSIS 43.Nm jail 44.Ar path 45.Ar hostname 46.Ar ip-number 47.Ar command 48.Ar ... 49.Sh DESCRIPTION 50The 51.Nm 52command imprisons a process and all future descendants. 53.Pp 54Please see the 55.Xr jail 2 56man page for further details. 57.Sh EXAMPLES 58.Ss Setting up a Jail Directory Tree 59This shows how to setup a jail directory tree: 60.Bd -literal 61D=/here/is/the/jail 62cd /usr/src 63make hierarchy DESTDIR=$D 64make obj 65make depend 66make all 67make install DESTDIR=$D 68cd etc 69make distribution DESTDIR=$D NO_MAKEDEV=yes 70cd $D/dev 71sh MAKEDEV jail 72cd $D 73ln -sf dev/null kernel 74.Ed 75.Ss Setting Up a Jail 76Do what was described in 77.Sx Setting Up a Jail Directory Tree 78to build the jail directory tree. For the sake of this example, we will 79assume you built it in 80.Pa /data/jail/192.168.11.100 , 81named for the jailed IP address. Substitute below as needed with your 82own directory, IP address, and hostname. 83.Pp 84First, you will want to set up your real system's environment to be 85.Dq jail-friendly. 86For consistency, we will refer to the parent box as the 87.Dq host environment, 88and to the jailed virtual machine as the 89.Dq jail environment. 90Because jail is implemented using IP aliases, one of the first things to do 91is to disable IP services on the host system that listen on all local 92IP addresses for a service. This means changing 93.Xr inetd 8 94to only listen on the 95appropriate IP address, and so forth. Add the following to 96.Pa /etc/rc.conf 97in the host environment: 98.Bd -literal -offset indent 99sendmail_enable="NO" 100inetd_flags="-wW -a 192.168.11.23" 101portmap_enable="NO" 102syslogd_flags="-ss" 103.Ed 104.Pp 105.Li 192.169.11.23 106is the native IP address for the host system, in this example. Daemons that 107run out of 108.Xr inetd 8 109can be easily set to use only the specified host IP address. Other daemons 110will need to be manually configured--for some this is possible through 111the 112.Xr rc.conf 5 113flags entries, for others it is not possible without munging 114the per-application configuration files, or even recompiling. For those 115applications that cannot specify the IP they run on, it is better to disable 116them, if possible. 117.Pp 118A number of daemons ship with the base system that may have problems when 119run from outside of a jail in a jail-centric environment. This includes 120.Xr syslogd 8 , 121.Xr sendmail 8 , 122.Xr named 8 , 123and 124.Xr portmap 8 . 125While sendmail and named can be configured to listen only on a specific 126IP using their configuration files, in most cases it is easier to simply 127run the daemons in jails only, and not in the host environment. Syslogd 128cannot be configured to bind only a single IP, but can be configured to 129not bind a network port, using the ``-ss'' argument. Attempting to serve 130NFS from the host environment may also cause confusion, and cannot be 131easily reconfigured to use only specific IPs, as some NFS services are 132hosted directly from the kernel. Any third party network software running 133in the host environment should also be checked and configured so that it 134does not bind all IP addresses, which would result in those services also 135appearing to be offered by the jail environments. 136.Pp 137Once 138these daemons have been disabled or fixed in the host environment, it is 139best to reboot so that all daemons are in a known state, to reduce the 140potential for confusion later (such as finding that when you send mail 141to a jail, and its sendmail is down, the mail is delivered to the host, 142etc.) 143.Pp 144Start any jails for the first time without configuring the network 145interface so that you can clean it up a little and set up accounts. As 146with any machine (virtual or not) you will need to set a root password, time 147zone, etc. Before beginning, you may want to copy 148.Xr sysinstall 8 149into the tree so that you can use it to set things up easily. Do this using: 150.Bd -literal -offset indent 151# mkdir /data/jail/192.168.11.100/stand 152# cp /stand/sysinstall /data/jail/192.168.11.100/stand 153.Ed 154.Pp 155Now start the jail: 156.Bd -literal -offset indent 157# jail /data/jail/192.168.11.100 testhostname 192.168.11.100 /bin/sh 158.Ed 159.Pp 160You will end up with a shell prompt, assuming no errors, within the jail. You 161can now run 162.Pa /stand/sysinstall 163and do the post-install configuration to set various configuration options, 164or perform these actions manually by editing rc.conf, etc. 165.Pp 166.Bl -bullet -offset indent -compact 167.It 168Create an empty /etc/fstab to quell startup warnings about missing fstab 169.It 170Disable the port mapper (rc.conf: portmap_enable="NO") 171.It 172Run 173.Xr newaliases 1 174to quell sendmail warnings. 175.It 176Disable interface configuration to quell startup warnings about ifconfig 177(network_interfaces="") 178.It 179Configure /etc/resolv.conf 180so that name resolution within the jail will work correctly 181.It 182Set a root password, probably different from the real host system 183.It 184Set the timezone 185.It 186Add accounts for users in the jail environment 187.It 188Install any packages that you think the environment requires 189.El 190.Pp 191You may also want to perform any package-specific configuration (web servers, 192SSH servers, etc), patch up /etc/syslog.conf so it logs as you'd like, etc. 193.Pp 194Exit from the shell, and the jail will be shut down. 195.Ss Starting the Jail 196You are now ready to restart the jail and bring up the environment with 197all of its daemons and other programs. To do this, first bring up the 198virtual host interface, and then start the jail's 199.Pa /etc/rc 200script from within the jail. 201.Pp 202NOTE: If you plan to allow untrusted users to have root access inside the 203jail, you may wish to consider setting the jail.set_hostname_allowed to 2040. Please see the management reasons why this is a good idea. If you 205do decide to set this variable, it must be set before starting any jails, 206and once each boot. 207.Bd -literal -offset indent 208# ifconfig ed0 inet alias 192.168.11.100 netmask 255.255.255.255 209# mount -t procfs proc /data/jail/192.168.11.100/proc 210# jail /data/jail/192.168.11.100 testhostname 192.168.11.100 \\ 211 /bin/sh /etc/rc 212.Ed 213.Pp 214A few warnings will be produced, because most 215.Xr sysctl 8 216configuration variables cannot be set from within the jail, as they are 217global across all jails and the host environment. 218However, it should all 219work properly. 220You should be able to see 221.Xr inetd 8 , 222.Xr syslogd 8 , 223and other processes running within the jail using 224.Xr ps 1 , 225with the 226.Dq J 227flag appearing beside jailed processes. You should also be able to 228telnet to the hostname or IP address of the jailed environment, and log 229in using the accounts you created previously. 230.Ss Managing the jail 231Normal machine shutdown commands, such as 232.Xr halt 8 , 233.Xr reboot 8 , 234and 235.Xr shutdown 8 , 236cannot be used successfully within the jail. To kill all processes in a 237jail, you may log into the jail and, as root, use one of the following 238commands, depending on what you want to accomplish: 239.Pp 240.Bl -bullet -offset indent -compact 241.It 242.Li kill -TERM -1 243.It 244.Li kill -KILL -1 245.El 246.Pp 247This will send the 248.Dq TERM 249or 250.Dq KILL 251signals to all processes in the jail from within the jail. Depending on 252the intended use of the jail, you may also want to run 253.Pa /etc/rc.shutdown 254from within the jail. Currently there is no way to insert new processes 255into a jail, so you must first log into the jail before performing these 256actions. 257.Pp 258To kill processes from outside the jail, you must individually identify the 259PID of each process to be killed. The 260.Pa /proc/ Ns Va pid Ns Pa /status 261file contains, as its last field, the hostname of the jail in which the 262process runs, or 263.Dq - 264to indicate that the process is not running within a jail. The 265.Xr ps 1 266command also shows a 267.Dq J 268flag for processes in a jail. However, the hostname for a jail may be, by 269default, modified from within the jail, so the 270.Pa /proc 271status entry is unreliable by default. To disable the setting of the hostname 272from within a jail, set the 273.Dq Va jail.set_hostname_allowed 274sysctl variable in the host environment to 0, which will affect all jails. 275You can have this sysctl set each boot using 276.Xr sysctl.conf 5 . 277Just add the following line to sysctl.conf: 278.Bd -literal -offset indent 279jail.set_hostname_allowed=0 280.Ed 281.Pp 282In a future version of FreeBSD, the mechanisms for managing jails will be 283more refined. 284.Sh SEE ALSO 285.Xr newaliases 1 , 286.Xr ps 1 , 287.Xr chroot 2 , 288.Xr jail 2 , 289.Xr procfs 5 , 290.Xr rc.conf 5 , 291.Xr sysctl.conf 5 , 292.Xr halt 8 , 293.Xr inetd 8 , 294.Xr named 8 , 295.Xr portmap 8 , 296.Xr reboot 8 , 297.Xr sendmail 8 , 298.Xr shutdown 8 , 299.Xr sysctl 8 , 300.Xr syslogd 8 301.Sh HISTORY 302The 303.Fn jail 304function call appeared in 305.Fx 4.0 . 306.Sh AUTHORS 307The jail feature was written by 308.An Poul-Henning Kamp 309for R&D Associates 310.Dq Li http://www.rndassociates.com/ 311who contributed it to FreeBSD. 312.Pp 313Robert Watson wrote the extended documentation, found a few bugs, added 314a few new features, and cleaned up the userland jail environment. 315.Sh BUGS 316Jail currently lacks strong management functionality, such as the ability 317to deliver signals to all processes in a jail, and to allow access to 318specific jail information via 319.Xr ps 1 320as opposed to 321.Xr procfs 5 . 322Similarly, it might be a good idea to add an 323address alias flag such that daemons listening on all IPs (INADDR_ANY) 324will not bind on that address, which would facilitate building a safe 325host environment such that host daemons do not impose on services offered 326from within jails. Currently, the simplist answer is to minimize services 327offered on the host, possibly limiting it to services offered from 328.Xr inetd 8 329which is easily configurable. 330