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