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