usr.sbin/jail/jail.8

   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 .\"
  35 .Dd October 24, 2023
  36 .Dt JAIL 8
  37 .Os
  38 .Sh NAME
  39 .Nm jail
  40 .Nd "imprison process and its descendants"
  41 .Sh SYNOPSIS
  42 .Nm
  43 .Op Fl i
  44 .Op Fl l u Ar username | Fl U Ar username
  45 .Ar path hostname ip-list command ...
  46 .Sh DESCRIPTION
  47 The
  48 .Nm
  49 command imprisons a process and all future descendants.
  50 .Pp
  51 The options are as follows:
  52 .Bl -tag -width ".Fl u Ar username"
  53 .It Fl i
  54 Output the jail identifier of the newly created jail.
  55 .It Fl l
  56 Run program in the clean environment.
  57 The environment is discarded except for
  58 .Ev HOME , SHELL , TERM
  59 and
  60 .Ev USER .
  61 .Ev HOME
  62 and
  63 .Ev SHELL
  64 are set to the target login's default values.
  65 .Ev USER
  66 is set to the target login.
  67 .Ev TERM
  68 is imported from the current environment.
  69 The environment variables from the login class capability database for the
  70 target login are also set.
  71 .It Fl u Ar username
  72 The user name as whom the
  73 .Ar command
  74 should run.
  75 .It Fl U Ar username
  76 The user name from jailed environment as whom the
  77 .Ar command
  78 should run.
  79 .It Ar path
  80 Directory which is to be the root of the prison.
  81 .It Ar hostname
  82 Hostname of the prison.
  83 .It Ar ip-list
  84 Comma separated IP list assigned to the prison.
  85 .It Ar command
  86 Pathname of the program which is to be executed.
  87 .El
  88 .Pp
  89 Please see the
  90 .Xr jail 2
  91 man page for further details.
  92 .Sh EXAMPLES
  93 .Ss "Setting Up a Jail Directory Tree"
  94 This example shows how to setup a jail directory tree
  95 containing an entire
  96 .Dx
  97 distribution, provided that you built world before already:
  98 .Bd -literal
  99 D=/here/is/the/jail
 100 cd /usr/src
 101 mkdir -p $D
 102 make installworld DESTDIR=$D
 103 cd etc
 104 make distribution DESTDIR=$D
 105 cd $D
 106 ln -sf dev/null boot/kernel
 107 .Ed
 108 .Pp
 109 In many cases this example would put far more stuff in the jail than is needed.
 110 In the other extreme case a jail might contain only one single file:
 111 the executable to be run in the jail.
 112 .Pp
 113 We recommend experimentation and caution that it is a lot easier to
 114 start with a
 115 .Dq fat
 116 jail and remove things until it stops working,
 117 than it is to start with a
 118 .Dq thin
 119 jail and add things until it works.
 120 .Ss "Setting Up a Jail"
 121 Do what was described in
 122 .Sx "Setting Up a Jail Directory Tree"
 123 to build the jail directory tree.
 124 For the sake of this example, we will
 125 assume you built it in
 126 .Pa /data/jail/192.168.11.100 ,
 127 named for the external jail IP address.
 128 Substitute below as needed with your
 129 own directory, IP addresses, and hostname.
 130 .Pp
 131 First, you will want to set up your real system's environment to be
 132 .Dq jail-friendly .
 133 For consistency, we will refer to the parent box as the
 134 .Dq "host environment" ,
 135 and to the jailed virtual machine as the
 136 .Dq "jail environment" .
 137 Generally speaking making a system jail-friendly does not require much
 138 work if you have
 139 .Va jail.defaults.allow_listen_override
 140 set to 1.
 141 This will allow all listen sockets inside the jail to overload
 142 and override wildcard listen sockets on the host.
 143 This methodology works extremely well as long as you restrict the IPs you
 144 pass into the jail to avoid any security concerns, which typically means
 145 making at least two IP aliases for each jail that you create (an external
 146 IP and a localhost IP).
 147 .Pp
 148 If you do not want to allow listener socket overloading, you must modify
 149 services you intend to leave running on the host system to listen only on
 150 specific IPs and not all IPs, or generally only run services inside your
 151 jails that do not conflict with services on the host system.
 152 This can be difficult and is not recommended.
 153 .Pp
 154 Common services include:
 155 .Xr inetd 8 ,
 156 .Xr sendmail 8 ,
 157 .Xr named 8 ,
 158 .Xr rpcbind 8 ,
 159 .Xr mountd 8 ,
 160 .Xr nfsd 8 ,
 161 .Xr sendmail 1 ,
 162 and
 163 .Xr named 8 .
 164 .Pp
 165 For the purposes of our examples below,
 166 .Li 192.168.11.1
 167 is the host IP and we create aliases
 168 .Li 192.168.11.X
 169 for each jail.
 170 In addition, we leave
 171 .Li 127.0.0.1
 172 on the host only and create aliases
 173 .Li 127.0.0.X
 174 for each jail.
 175 .Pp
 176 Start any jails for the first time without configuring the network
 177 interface so that you can clean it up a little and set up accounts.
 178 As
 179 with any machine (virtual or not) you will need to set a root password, time
 180 zone, etc.
 181 .Pp
 182 To set the jail up for real you need to ifconfig some interface aliases.
 183 and set jail defaults.  Here is an example:
 184 .Pp
 185 .Dl "sysctl jail.defaults.allow_raw_sockets=1"
 186 .Dl "sysctl jail.defaults.allow_listen_override=1"
 187 .Dl "ifconfig lo0 127.0.0.2 alias"
 188 .Dl "ifconfig em0 192.168.11.100 netmask 255.255.255.0 alias"
 189 .Pp
 190 From within your jail you can generally run services normally. Just use
 191 .Dq localhost
 192 normally.  Do not inform services that localhost is 127.0.0.2.
 193 The kernel will automatically remap 'localhost' (e.g. 127.0.0.1) to the
 194 localhost IP you specify for the jail.  The kernel will also map the jail's
 195 localhost IP back to 127.0.0.1 in the
 196 .Xr accept 2 ,
 197 .Xr getsockname 2 ,
 198 and
 199 .Xr getpeername 2
 200 system calls.
 201 .Pp
 202 Listen sockets can be overloaded between jails and between the host and its
 203 jails.  You can continue to use services that listen on the wildcard *.*
 204 socket normally on both the host and its jails if you set the
 205 .Va allow_listen_override
 206 flag to 1, and jailed listen sockets will override any host listen sockets
 207 listening on the wildcard address for the allowed jail IPs.
 208 .Pp
 209 .Dx
 210 also allows you to overload specific ports, but the jailed service will
 211 not receive any connections if the host is also specifically listening
 212 on the addr/port pair that the jail is using.  If multiple jails are listening
 213 on the same addr/port pair (as specified by the jail's IP list), and the
 214 host is not, then only one jail will receive connections on that pair.
 215 .Pp
 216 In otherwords, it is still a good idea to give each jail its own local
 217 and non-local IP address rather than have jails share.
 218 .Pp
 219 Now start the jail:
 220 .Pp
 221 .Dl "jail /data/jail/192.168.11.100 testhostname 127.0.0.2,192.168.11.100 /bin/sh"
 222 .Pp
 223 You will end up with a shell prompt, assuming no errors, within the jail.
 224 You can now do the post-install configuration to set various configuration
 225 options by editing
 226 .Pa /etc/rc.conf ,
 227 etc.
 228 .Pp
 229 .Bl -bullet -offset indent -compact
 230 .It
 231 Disable the port mapper
 232 .Pa ( /etc/rc.conf :
 233 .Li rpcbind_enable="NO" )
 234 .It
 235 Run
 236 .Xr newaliases 1
 237 to quell
 238 .Xr sendmail 8
 239 warnings.
 240 .It
 241 Disable interface configuration to quell startup warnings about
 242 .Xr ifconfig 8
 243 .Pq Li network_interfaces=""
 244 .It
 245 Configure
 246 .Pa /etc/resolv.conf
 247 so that name resolution within the jail will work correctly
 248 .It
 249 Set a root password, probably different from the real host system
 250 .It
 251 Set the timezone with
 252 .Xr tzsetup 8
 253 .It
 254 Add accounts for users in the jail environment
 255 .It
 256 Install any packages that you think the environment requires
 257 .El
 258 .Pp
 259 You may also want to perform any package-specific configuration (web servers,
 260 SSH servers, etc), patch up
 261 .Pa /etc/syslog.conf
 262 so it logs as you would like, etc.
 263 .Pp
 264 Exit from the shell, and the jail will be shut down.
 265 .Ss "Starting the Jail"
 266 You are now ready to restart the jail and bring up the environment with
 267 all of its daemons and other programs.
 268 To do this, first bring up the
 269 virtual host interface, and then start the jail's
 270 .Pa /etc/rc
 271 script from within the jail.
 272 .Pp
 273 NOTE: If you plan to allow untrusted users to have root access inside the
 274 jail, you may wish to consider setting the
 275 .Va jail.defaults.set_hostname_allowed
 276 to 0.
 277 Please see the management reasons why this is a good idea.
 278 If you do decide to set this variable,
 279 it must be set before starting any jails, and once each boot.
 280 .Bd -literal -offset indent
 281 sysctl jail.defaults.allow_raw_sockets=1
 282 sysctl jail.defaults.allow_listen_override=1
 283 ifconfig em0 inet alias 192.168.11.100/32
 284 ifconfig lo0 inet alias 127.0.0.2
 285 mount -t procfs proc /data/jail/192.168.11.100/proc
 286 jail /data/jail/192.168.11.100 testhostname 127.0.0.2,192.168.11.100 \\
 287         /bin/sh /etc/rc
 288 .Ed
 289 .Pp
 290 A few warnings will be produced, because most
 291 .Xr sysctl 8
 292 configuration variables cannot be set from within the jail, as they are
 293 global across all jails and the host environment.
 294 However, it should all
 295 work properly.
 296 You should be able to see
 297 .Xr inetd 8 ,
 298 .Xr syslogd 8 ,
 299 and other processes running within the jail using
 300 .Xr ps 1 ,
 301 with the
 302 .Ql J
 303 flag appearing beside jailed processes.
 304 You should also be able to
 305 .Xr telnet 1
 306 to the hostname or IP address of the jailed environment, and log
 307 in using the accounts you created previously.
 308 .Ss "Managing the Jail"
 309 Normal machine shutdown commands, such as
 310 .Xr halt 8 ,
 311 .Xr reboot 8 ,
 312 and
 313 .Xr shutdown 8 ,
 314 cannot be used successfully within the jail.
 315 To kill all processes in a
 316 jail, you may log into the jail and, as root, use one of the following
 317 commands, depending on what you want to accomplish:
 318 .Bd -literal -offset indent
 319 kill -TERM -1
 320 kill -KILL -1
 321 .Ed
 322 .Pp
 323 This will send the
 324 .Dv SIGTERM
 325 or
 326 .Dv SIGKILL
 327 signals to all processes in the jail from within the jail.
 328 Depending on
 329 the intended use of the jail, you may also want to run
 330 .Pa /etc/rc.shutdown
 331 from within the jail.
 332 Currently there is no way to insert new processes
 333 into a jail, so you must first log into the jail before performing these
 334 actions.
 335 .Pp
 336 To kill processes from outside the jail, you must individually identify the
 337 PID of each process to be killed.
 338 The
 339 .Pa /proc/ Ns Ar pid Ns Pa /status
 340 file contains, as its last field, the hostname of the jail in which the
 341 process runs, or
 342 .Dq Li -
 343 to indicate that the process is not running within a jail.
 344 The
 345 .Xr ps 1
 346 command also shows a
 347 .Ql J
 348 flag for processes in a jail.
 349 However, the hostname for a jail may be, by
 350 default, modified from within the jail, so the
 351 .Pa /proc
 352 status entry is unreliable by default.
 353 To disable the setting of the hostname
 354 from within a jail, set the
 355 .Va jail.set_hostname_allowed
 356 sysctl variable in the host environment to 0, which will affect all jails.
 357 You can have this sysctl set on each boot using
 358 .Xr sysctl.conf 5 .
 359 Just add the following line to
 360 .Pa /etc/sysctl.conf :
 361 .Pp
 362 .Dl jail.defaults.set_hostname_allowed=0
 363 .Pp
 364 In a future version of
 365 .Dx ,
 366 the mechanisms for managing jails may be
 367 more refined.
 368 .Ss "Sysctl MIB Entries"
 369 Certain aspects of the jail containments environment may be modified from
 370 the host environment using
 371 .Xr sysctl 8
 372 MIB variables.
 373 For each jail there will be the same set of MIB variables as shown below but
 374 under
 375 .Va jail.<id>
 376 which allows control of every jail individually.
 377 The values of the variables under
 378 .Va jail.defaults
 379 will be copied to the per-jail MIB variables upon creation thus serving as
 380 a kind of system-wide template.
 381 .Bl -tag -width XXX
 382 .It Va jail.jailed
 383 This read-only MIB entry can be used to determine if a process is running
 384 inside a jail (value is 1) or not (value is 0).
 385 .It Va jail.defaults.allow_raw_sockets
 386 This MIB entry determines whether or not prison root is allowed to
 387 create raw sockets.
 388 Setting this MIB to 1 allows utilities like
 389 .Xr ping 8
 390 and
 391 .Xr traceroute 8
 392 to operate inside the prison.
 393 If this MIB is set, the source IP addresses are enforced to comply
 394 with the IP address bound to the jail, regardless of whether or not the
 395 .Dv IP_HDRINCL
 396 flag has been set on the socket. Because raw sockets can be used to configure
 397 and interact with various network subsystems, extra caution should be used
 398 where privileged access to jails is given out to untrusted parties.
 399 As such, this option is disabled by default.
 400 .It Va jail.defaults.chflags_allowed
 401 This MIB entry determines how a privileged user inside a jail will be
 402 treated by
 403 .Xr chflags 2 .
 404 If zero, such users are treated as unprivileged, and are unable to set
 405 or clear system file flags; if non-zero, such users are treated as
 406 privileged, and may manipulate system file flags subject to the usual
 407 constraints on
 408 .Va kern.securelevel .
 409 .It Va jail.defaults.set_hostname_allowed
 410 This MIB entry determines whether or not processes within a jail are
 411 allowed to change their hostname via
 412 .Xr hostname 1
 413 or
 414 .Xr sethostname 3 .
 415 In the current jail implementation, the ability to set the hostname from
 416 within the jail can impact management tools relying on the accuracy of jail
 417 information in
 418 .Pa /proc .
 419 As such, this should be disabled in environments where privileged access to
 420 jails is given out to untrusted parties.
 421 .It Va jail.defaults.allow_listen_override
 422 This feature allows both the host and your jails to overload services on
 423 the same ports.
 424 If enabled, the services in the jails will override wildcarded services on
 425 the host for the jail's IP list.
 426 As a safety mechanism, any services the host specifically binds to an IP
 427 will not be overridden.  The host has visibility to all jail IPs but
 428 jails only have visibility to their specific IPs.
 429 .It Va jail.defaults.socket_unixiproute_only
 430 The jail functionality binds IPv4 and IPv6 addresses to each jail, and limits
 431 access to other network addresses in the IPv4 and IPv6 space that may be available
 432 in the host environment.
 433 However, jail is not currently able to limit access to other network
 434 protocol stacks that have not had jail functionality added to them.
 435 As such, by default, processes within jails may only access protocols
 436 in the following domains:
 437 .Dv PF_LOCAL , PF_INET , PF_INET6 ,
 438 and
 439 .Dv PF_ROUTE ,
 440 permitting them access to
 441 .Ux
 442 domain sockets,
 443 IPv4 and IPv6 addresses, and routing sockets.
 444 To enable access to other domains, this MIB variable may be set to 0.
 445 .It Va jail.defaults.sysvipc_allowed
 446 This MIB entry determines whether or not processes within a jail have access
 447 to System V IPC primitives.
 448 In the current jail implementation, System V primitives share a single
 449 namespace across the host and jail environments, meaning that processes
 450 within a jail would be able to communicate with (and potentially interfere
 451 with) processes outside of the jail, and in other jails.
 452 As such, this functionality is disabled by default, but can be enabled
 453 by setting this MIB entry to 1.
 454 .El
 455 .Sh SEE ALSO
 456 .Xr newaliases 1 ,
 457 .Xr ps 1 ,
 458 .Xr chroot 2 ,
 459 .Xr jail 2 ,
 460 .Xr procfs 5 ,
 461 .Xr rc.conf 5 ,
 462 .Xr sysctl.conf 5 ,
 463 .Xr halt 8 ,
 464 .Xr inetd 8 ,
 465 .Xr jexec 8 ,
 466 .Xr jls 8 ,
 467 .Xr named 8 ,
 468 .Xr pw 8 ,
 469 .Xr reboot 8 ,
 470 .Xr rpcbind 8 ,
 471 .Xr sendmail 8 ,
 472 .Xr shutdown 8 ,
 473 .Xr sysctl 8 ,
 474 .Xr syslogd 8 ,
 475 .Xr tzsetup 8
 476 .Sh HISTORY
 477 The
 478 .Nm
 479 command appeared in
 480 .Fx 4.0 .
 481 .Pp
 482 Support for multiple IPs and IPv6 appeared in
 483 .Dx
 484 1.7.
 485 .Sh AUTHORS
 486 .An -nosplit
 487 The jail feature was originally written by
 488 .An Poul-Henning Kamp
 489 for R&D Associates
 490 .Pa http://www.rndassociates.com/
 491 who contributed it to
 492 .Fx .
 493 .Pp
 494 .An Robert Watson
 495 wrote the extended documentation, found a few bugs, added
 496 a few new features, and cleaned up the userland jail environment.
 497 .Pp
 498 .An Victor Balada Diaz
 499 wrote the support for multiple IPs and IPv6. Multiple IPs support
 500 is based on work done by
 501 .An Pawel Jakub Dawidek .
 502 .Pp
 503 .An Matthew Dillon
 504 added port overloading to make configuration easier.
 505 .Sh BUGS
 506 Jail currently lacks strong management functionality, such as the ability
 507 to deliver signals to all processes in a jail, and to allow access to
 508 specific jail information via
 509 .Xr ps 1
 510 as opposed to
 511 .Xr procfs 5 .
 512 Similarly, it might be a good idea to add an
 513 address alias flag such that daemons listening on all IPs
 514 .Pq Dv INADDR_ANY
 515 will not bind on that address, which would facilitate building a safe
 516 host environment such that host daemons do not impose on services offered
 517 from within jails.
 518 Currently, the simplest answer is to minimize services
 519 offered on the host, possibly limiting it to services offered from
 520 .Xr inetd 8
 521 which is easily configurable.