usr.sbin/jail/jail.8

   1 .\"
   2 .\" Copyright (c) 2000, 2003 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 August 7, 2005
  37 .Dt JAIL 8
  38 .Os
  39 .Sh NAME
  40 .Nm jail
  41 .Nd "imprison process and its descendants"
  42 .Sh SYNOPSIS
  43 .Nm
  44 .Op Fl i
  45 .Op Fl l u Ar username | Fl U Ar username
  46 .Ar path hostname ip-number command ...
  47 .Sh DESCRIPTION
  48 The
  49 .Nm
  50 utility imprisons a process and all future descendants.
  51 .Pp
  52 The options are as follows:
  53 .Bl -tag -width ".Fl u Ar username"
  54 .It Fl i
  55 Output the jail identifier of the newly created jail.
  56 .It Fl l
  57 Run program in the clean environment.
  58 The environment is discarded except for
  59 .Ev HOME , SHELL , TERM
  60 and
  61 .Ev USER .
  62 .Ev HOME
  63 and
  64 .Ev SHELL
  65 are set to the target login's default values.
  66 .Ev USER
  67 is set to the target login.
  68 .Ev TERM
  69 is imported from the current environment.
  70 The environment variables from the login class capability database for the
  71 target login are also set.
  72 .It Fl u Ar username
  73 The user name from host environment as whom the
  74 .Ar command
  75 should run.
  76 .It Fl U Ar username
  77 The user name from jailed environment as whom the
  78 .Ar command
  79 should run.
  80 .It Ar path
  81 Directory which is to be the root of the prison.
  82 .It Ar hostname
  83 Hostname of the prison.
  84 .It Ar ip-number
  85 IP number assigned to the prison.
  86 .It Ar command
  87 Pathname of the program which is to be executed.
  88 .El
  89 .Pp
  90 Jails are typically set up using one of two philosophies: either to
  91 constrain a specific application (possibly running with privilege), or
  92 to create a
  93 .Dq "virtual system image"
  94 running a variety of daemons and services.
  95 In both cases, a fairly complete file system install of
  96 .Fx
  97 is
  98 required, so as to provide the necessary command line tools, daemons,
  99 libraries, application configuration files, etc.
 100 However, for a virtual server configuration, a fair amount of
 101 additional work is required so as to configure the
 102 .Dq boot
 103 process.
 104 This manual page documents the configuration steps necessary to support
 105 either of these steps, although the configuration steps may be
 106 refined based on local requirements.
 107 .Pp
 108 Please see the
 109 .Xr jail 2
 110 man page for further details.
 111 .Sh EXAMPLES
 112 .Ss "Setting up a Jail Directory Tree"
 113 To set up a jail directory tree containing an entire
 114 .Fx
 115 distribution, the following
 116 .Xr sh 1
 117 command script can be used:
 118 .Bd -literal
 119 D=/here/is/the/jail
 120 cd /usr/src
 121 mkdir -p $D
 122 make world DESTDIR=$D
 123 make distribution DESTDIR=$D
 124 mount_devfs devfs $D/dev
 125 .Ed
 126 .Pp
 127 NOTE: It is important that only appropriate device nodes in devfs be
 128 exposed to a jail; access to disk devices in the jail may permit processes
 129 in the jail to bypass the jail sandboxing by modifying files outside of
 130 the jail.
 131 See
 132 .Xr devfs 8
 133 for information on how to use devfs rules to limit access to entries
 134 in the per-jail devfs.
 135 .Pp
 136 In many cases this example would put far more in the jail than needed.
 137 In the other extreme case a jail might contain only one file:
 138 the executable to be run in the jail.
 139 .Pp
 140 We recommend experimentation and caution that it is a lot easier to
 141 start with a
 142 .Dq fat
 143 jail and remove things until it stops working,
 144 than it is to start with a
 145 .Dq thin
 146 jail and add things until it works.
 147 .Ss "Setting Up a Jail"
 148 Do what was described in
 149 .Sx "Setting Up a Jail Directory Tree"
 150 to build the jail directory tree.
 151 For the sake of this example, we will
 152 assume you built it in
 153 .Pa /data/jail/192.168.11.100 ,
 154 named for the jailed IP address.
 155 Substitute below as needed with your
 156 own directory, IP address, and hostname.
 157 .Ss "Setting up the Host Environment"
 158 First, you will want to set up your real system's environment to be
 159 .Dq jail-friendly .
 160 For consistency, we will refer to the parent box as the
 161 .Dq "host environment" ,
 162 and to the jailed virtual machine as the
 163 .Dq "jail environment" .
 164 Since jail is implemented using IP aliases, one of the first things to do
 165 is to disable IP services on the host system that listen on all local
 166 IP addresses for a service.
 167 If a network service is present in the host environment that binds all
 168 available IP addresses rather than specific IP addresses, it may service
 169 requests sent to jail IP addresses.
 170 This means changing
 171 .Xr inetd 8
 172 to only listen on the
 173 appropriate IP address, and so forth.
 174 Add the following to
 175 .Pa /etc/rc.conf
 176 in the host environment:
 177 .Bd -literal -offset indent
 178 sendmail_enable="NO"
 179 inetd_flags="-wW -a 192.168.11.23"
 180 rpcbind_enable="NO"
 181 .Ed
 182 .Pp
 183 .Li 192.168.11.23
 184 is the native IP address for the host system, in this example.
 185 Daemons that run out of
 186 .Xr inetd 8
 187 can be easily set to use only the specified host IP address.
 188 Other daemons
 189 will need to be manually configured\(emfor some this is possible through
 190 the
 191 .Xr rc.conf 5
 192 flags entries; for others it is necessary to modify per-application
 193 configuration files, or to recompile the applications.
 194 The following frequently deployed services must have their individual
 195 configuration files modified to limit the application to listening
 196 to a specific IP address:
 197 .Pp
 198 To configure
 199 .Xr sshd 8 ,
 200 it is necessary to modify
 201 .Pa /etc/ssh/sshd_config .
 202 .Pp
 203 To configure
 204 .Xr sendmail 8 ,
 205 it is necessary to modify
 206 .Pa /etc/mail/sendmail.cf .
 207 .Pp
 208 For
 209 .Xr named 8 ,
 210 it is necessary to modify
 211 .Pa /etc/namedb/named.conf .
 212 .Pp
 213 In addition, a number of services must be recompiled in order to run
 214 them in the host environment.
 215 This includes most applications providing services using
 216 .Xr rpc 3 ,
 217 such as
 218 .Xr rpcbind 8 ,
 219 .Xr nfsd 8 ,
 220 and
 221 .Xr mountd 8 .
 222 In general, applications for which it is not possible to specify which
 223 IP address to bind should not be run in the host environment unless they
 224 should also service requests sent to jail IP addresses.
 225 Attempting to serve
 226 NFS from the host environment may also cause confusion, and cannot be
 227 easily reconfigured to use only specific IPs, as some NFS services are
 228 hosted directly from the kernel.
 229 Any third-party network software running
 230 in the host environment should also be checked and configured so that it
 231 does not bind all IP addresses, which would result in those services' also
 232 appearing to be offered by the jail environments.
 233 .Pp
 234 Once
 235 these daemons have been disabled or fixed in the host environment, it is
 236 best to reboot so that all daemons are in a known state, to reduce the
 237 potential for confusion later (such as finding that when you send mail
 238 to a jail, and its sendmail is down, the mail is delivered to the host,
 239 etc.).
 240 .Ss "Configuring the Jail"
 241 Start any jail for the first time without configuring the network
 242 interface so that you can clean it up a little and set up accounts.
 243 As
 244 with any machine (virtual or not) you will need to set a root password, time
 245 zone, etc.
 246 Some of these steps apply only if you intend to run a full virtual server
 247 inside the jail; others apply both for constraining a particular application
 248 or for running a virtual server.
 249 .Pp
 250 Start a shell in the jail:
 251 .Pp
 252 .Dl "jail /data/jail/192.168.11.100 testhostname 192.168.11.100 /bin/sh"
 253 .Pp
 254 Assuming no errors, you will end up with a shell prompt within the jail.
 255 You can now run
 256 .Pa /usr/sbin/sysinstall
 257 and do the post-install configuration to set various configuration options,
 258 or perform these actions manually by editing
 259 .Pa /etc/rc.conf ,
 260 etc.
 261 .Pp
 262 .Bl -bullet -offset indent -compact
 263 .It
 264 Create an empty
 265 .Pa /etc/fstab
 266 to quell startup warnings about missing fstab (virtual server only)
 267 .It
 268 Disable the port mapper
 269 .Pa ( /etc/rc.conf :
 270 .Li rpcbind_enable="NO" )
 271 (virtual server only)
 272 .It
 273 Configure
 274 .Pa /etc/resolv.conf
 275 so that name resolution within the jail will work correctly
 276 .It
 277 Run
 278 .Xr newaliases 1
 279 to quell
 280 .Xr sendmail 8
 281 warnings.
 282 .It
 283 Disable interface configuration to quell startup warnings about
 284 .Xr ifconfig 8
 285 .Pq Li network_interfaces=""
 286 (virtual server only)
 287 .It
 288 Set a root password, probably different from the real host system
 289 .It
 290 Set the timezone
 291 .It
 292 Add accounts for users in the jail environment
 293 .It
 294 Install any packages the environment requires
 295 .El
 296 .Pp
 297 You may also want to perform any package-specific configuration (web servers,
 298 SSH servers, etc), patch up
 299 .Pa /etc/syslog.conf
 300 so it logs as you would like, etc.
 301 If you are not using a virtual server, you may wish to modify
 302 .Xr syslogd 8
 303 in the host environment to listen on the syslog socket in the jail
 304 environment; in this example, the syslog socket would be stored in
 305 .Pa /data/jail/192.168.11.100/var/run/log .
 306 .Pp
 307 Exit from the shell, and the jail will be shut down.
 308 .Ss "Starting the Jail"
 309 You are now ready to restart the jail and bring up the environment with
 310 all of its daemons and other programs.
 311 If you are running a single application in the jail, substitute the
 312 command used to start the application for
 313 .Pa /etc/rc
 314 in the examples below.
 315 To start a virtual server environment,
 316 .Pa /etc/rc
 317 is run to launch various daemons and services.
 318 To do this, first bring up the
 319 virtual host interface, and then start the jail's
 320 .Pa /etc/rc
 321 script from within the jail.
 322 .Pp
 323 NOTE: If you plan to allow untrusted users to have root access inside the
 324 jail, you may wish to consider setting the
 325 .Va security.jail.set_hostname_allowed
 326 sysctl variable to 0.
 327 Please see the management discussion later in this document as to why this
 328 may be a good idea.
 329 If you do decide to set this variable,
 330 it must be set before starting any jails, and once each boot.
 331 .Bd -literal -offset indent
 332 ifconfig ed0 inet alias 192.168.11.100/32
 333 mount -t procfs proc /data/jail/192.168.11.100/proc
 334 jail /data/jail/192.168.11.100 testhostname 192.168.11.100 \\
 335         /bin/sh /etc/rc
 336 .Ed
 337 .Pp
 338 A few warnings will be produced, because most
 339 .Xr sysctl 8
 340 configuration variables cannot be set from within the jail, as they are
 341 global across all jails and the host environment.
 342 However, it should all
 343 work properly.
 344 You should be able to see
 345 .Xr inetd 8 ,
 346 .Xr syslogd 8 ,
 347 and other processes running within the jail using
 348 .Xr ps 1 ,
 349 with the
 350 .Ql J
 351 flag appearing beside jailed processes.
 352 To see an active list of jails, use the
 353 .Xr jls 8
 354 utility.
 355 You should also be able to
 356 .Xr telnet 1
 357 to the hostname or IP address of the jailed environment, and log
 358 in using the accounts you created previously.
 359 .Pp
 360 It is possible to have jails started at boot time.
 361 Please refer to the
 362 .Dq jail_*
 363 variables in
 364 .Xr rc.conf 5
 365 for more information.
 366 The
 367 .Xr rc 8
 368 jail script provides a flexible system to start/stop jails:
 369 .Bd -literal
 370 /etc/rc.d/jail start
 371 /etc/rc.d/jail stop
 372 /etc/rc.d/jail start myjail
 373 /etc/rc.d/jail stop myjail
 374 .Ed
 375 .Ss "Managing the Jail"
 376 Normal machine shutdown commands, such as
 377 .Xr halt 8 ,
 378 .Xr reboot 8 ,
 379 and
 380 .Xr shutdown 8 ,
 381 cannot be used successfully within the jail.
 382 To kill all processes in a
 383 jail, you may log into the jail and, as root, use one of the following
 384 commands, depending on what you want to accomplish:
 385 .Pp
 386 .Bd -literal -offset indent
 387 kill -TERM -1
 388 kill -KILL -1
 389 .Ed
 390 .Pp
 391 This will send the
 392 .Dv SIGTERM
 393 or
 394 .Dv SIGKILL
 395 signals to all processes in the jail from within the jail.
 396 Depending on
 397 the intended use of the jail, you may also want to run
 398 .Pa /etc/rc.shutdown
 399 from within the jail.
 400 To kill processes from outside the jail, use the
 401 .Xr jexec 8
 402 utility in conjunction with the one of the
 403 .Xr kill 1
 404 commands above.
 405 .Pp
 406 The
 407 .Pa /proc/ Ns Ar pid Ns Pa /status
 408 file contains, as its last field, the hostname of the jail in which the
 409 process runs, or
 410 .Dq Li -
 411 to indicate that the process is not running within a jail.
 412 The
 413 .Xr ps 1
 414 command also shows a
 415 .Ql J
 416 flag for processes in a jail.
 417 However, the hostname for a jail may be, by
 418 default, modified from within the jail, so the
 419 .Pa /proc
 420 status entry is unreliable by default.
 421 To disable the setting of the hostname
 422 from within a jail, set the
 423 .Va security.jail.set_hostname_allowed
 424 sysctl variable in the host environment to 0, which will affect all jails.
 425 You can have this sysctl set on each boot using
 426 .Xr sysctl.conf 5 .
 427 Just add the following line to
 428 .Pa /etc/sysctl.conf :
 429 .Pp
 430 .Dl security.jail.set_hostname_allowed=0
 431 .Pp
 432 You can also list/kill processes based on their jail ID.
 433 To show processes and their jail ID, use the following command:
 434 .Pp
 435 .Dl "ps ax -o pid,jid,args"
 436 .Pp
 437 To show and then kill processes in jail number 3 use the following commands:
 438 .Bd -literal -offset indent
 439 pgrep -lfj 3
 440 pkill -j 3
 441 .Ed
 442 or:
 443 .Pp
 444 .Dl "killall -j 3"
 445 .Ss "Sysctl MIB Entries"
 446 Certain aspects of the jail containments environment may be modified from
 447 the host environment using
 448 .Xr sysctl 8
 449 MIB variables.
 450 Currently, these variables affect all jails on the system, although in
 451 the future this functionality may be finer grained.
 452 .Bl -tag -width XXX
 453 .It Va security.jail.allow_raw_sockets
 454 This MIB entry determines whether or not prison root is allowed to
 455 create raw sockets.
 456 Setting this MIB to 1 allows utilities like
 457 .Xr ping 8
 458 and
 459 .Xr traceroute 8
 460 to operate inside the prison.
 461 If this MIB
 462 is set, the source IP addresses are enforced to comply
 463 with the IP address bound to the jail, regardless of whether or not
 464 the
 465 .Dv IP_HDRINCL
 466 flag has been set on the socket.
 467 Since raw sockets can be used to configure
 468 and interact with various network subsystems, extra caution should be used
 469 where privileged access to jails is given out to untrusted parties.
 470 As such,
 471 by default this option is disabled.
 472 .It Va security.jail.enforce_statfs
 473 This MIB entry determines which information processes in a jail are
 474 able to get about mount-points.
 475 It affects the behaviour of the following syscalls:
 476 .Xr statfs 2 ,
 477 .Xr fstatfs 2 ,
 478 .Xr getfsstat 2
 479 and
 480 .Xr fhstatfs 2
 481 (as well as similar compatibility syscalls).
 482 When set to 0, all mount-points are available without any restrictions.
 483 When set to 1, only mount-points below the jail's chroot directory are
 484 visible.
 485 In addition to that, the path to the jail's chroot directory is removed
 486 from the front of their pathnames.
 487 When set to 2 (default), above syscalls can operate only on a mount-point
 488 where the jail's chroot directory is located.
 489 .It Va security.jail.set_hostname_allowed
 490 This MIB entry determines whether or not processes within a jail are
 491 allowed to change their hostname via
 492 .Xr hostname 1
 493 or
 494 .Xr sethostname 3 .
 495 In the current jail implementation, the ability to set the hostname from
 496 within the jail can impact management tools relying on the accuracy of jail
 497 information in
 498 .Pa /proc .
 499 As such, this should be disabled in environments where privileged access to
 500 jails is given out to untrusted parties.
 501 .It Va security.jail.socket_unixiproute_only
 502 The jail functionality binds an IPv4 address to each jail, and limits
 503 access to other network addresses in the IPv4 space that may be available
 504 in the host environment.
 505 However, jail is not currently able to limit access to other network
 506 protocol stacks that have not had jail functionality added to them.
 507 As such, by default, processes within jails may only access protocols
 508 in the following domains:
 509 .Dv PF_LOCAL , PF_INET ,
 510 and
 511 .Dv PF_ROUTE ,
 512 permitting them access to
 513 .Ux
 514 domain sockets,
 515 IPv4 addresses, and routing sockets.
 516 To enable access to other domains, this MIB variable may be set to
 517 0.
 518 .It Va security.jail.sysvipc_allowed
 519 This MIB entry determines whether or not processes within a jail have access
 520 to System V IPC primitives.
 521 In the current jail implementation, System V primitives share a single
 522 namespace across the host and jail environments, meaning that processes
 523 within a jail would be able to communicate with (and potentially interfere
 524 with) processes outside of the jail, and in other jails.
 525 As such, this functionality is disabled by default, but can be enabled
 526 by setting this MIB entry to 1.
 527 .It Va security.jail.chflags_allowed
 528 This MIB entry determines how a privileged user inside a jail will be
 529 treated by
 530 .Xr chflags 2 .
 531 If zero, such users are treated as unprivileged, and are unable to set
 532 or clear system file flags; if non-zero, such users are treated as
 533 privileged, and may manipulate system file flags subject to the usual
 534 constraints on
 535 .Va kern.securelevel .
 536 .El
 537 .Pp
 538 There are currently two MIB related variables that have per-jail settings.
 539 Changes to these variables by a jailed process do not effect the host
 540 environment, only the jail environment.
 541 The variables are
 542 .Va kern.securelevel
 543 and
 544 .Va kern.hostname .
 545 .Sh SEE ALSO
 546 .Xr killall 1 ,
 547 .Xr newaliases 1 ,
 548 .Xr pgrep 1 ,
 549 .Xr pkill 1 ,
 550 .Xr ps 1 ,
 551 .Xr chroot 2 ,
 552 .Xr jail 2 ,
 553 .Xr jail_attach 2 ,
 554 .Xr procfs 5 ,
 555 .Xr rc.conf 5 ,
 556 .Xr sysctl.conf 5 ,
 557 .Xr devfs 8 ,
 558 .Xr halt 8 ,
 559 .Xr inetd 8 ,
 560 .Xr jexec 8 ,
 561 .Xr jls 8 ,
 562 .Xr mount_devfs 8 ,
 563 .Xr named 8 ,
 564 .Xr reboot 8 ,
 565 .Xr rpcbind 8 ,
 566 .Xr sendmail 8 ,
 567 .Xr shutdown 8 ,
 568 .Xr sysctl 8 ,
 569 .Xr syslogd 8
 570 .Sh HISTORY
 571 The
 572 .Nm
 573 utility appeared in
 574 .Fx 4.0 .
 575 .Sh AUTHORS
 576 .An -nosplit
 577 The jail feature was written by
 578 .An Poul-Henning Kamp
 579 for R&D Associates
 580 .Pa http://www.rndassociates.com/
 581 who contributed it to
 582 .Fx .
 583 .Pp
 584 .An Robert Watson
 585 wrote the extended documentation, found a few bugs, added
 586 a few new features, and cleaned up the userland jail environment.
 587 .Sh BUGS
 588 Jail currently lacks the ability to allow access to
 589 specific jail information via
 590 .Xr ps 1
 591 as opposed to
 592 .Xr procfs 5 .
 593 Similarly, it might be a good idea to add an
 594 address alias flag such that daemons listening on all IPs
 595 .Pq Dv INADDR_ANY
 596 will not bind on that address, which would facilitate building a safe
 597 host environment such that host daemons do not impose on services offered
 598 from within jails.
 599 Currently, the simplest answer is to minimize services
 600 offered on the host, possibly limiting it to services offered from
 601 .Xr inetd 8
 602 which is easily configurable.