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