share/doc/papers/jail/mgt.ms

   1 .\"
   2 .\" $FreeBSD: head/share/doc/papers/jail/mgt.ms 215334 2010-11-15 05:25:51Z dougb $
   3 .\"
   4 .NH
   5 Managing Jails and the Jail File System Environment
   6 .NH 2
   7 Creating a Jail Environment
   8 .PP
   9 While the jail(2) call could be used in a number of ways, the expected
  10 configuration creates a complete FreeBSD installation for each jail.
  11 This includes copies of all relevant system binaries, data files, and its
  12 own \fC/etc\fP directory.
  13 Such a configuration maximises the independence of various jails,
  14 and reduces the chances of interference between jails being possible,
  15 especially when it is desirable to provide root access within a jail to
  16 a less trusted user.
  17 .PP
  18 On a box making use of the jail facility, we refer to two types of
  19 environment: the host environment, and the jail environment.
  20 The host environment is the real operating system environment, which is
  21 used to configure interfaces, and start up the jails.
  22 There are then one or more jail environments, effectively virtual
  23 FreeBSD machines.
  24 When configuring Jail for use, it is necessary to configure both the
  25 host and jail environments to prevent overlap.
  26 .PP
  27 As jailed virtual machines are generally bound to an IP address configured
  28 using the normal IP alias mechanism, those jail IP addresses are also
  29 accessible to host environment applications to use.
  30 If the accessibility of some host applications in the jail environment is
  31 not desirable, it is necessary to configure those applications to only
  32 listen on appropriate addresses.
  33 .PP
  34 In most of the production environments where jail is currently in use,
  35 one IP address is allocated to the host environment, and then a number
  36 are allocated to jail boxes, with each jail box receiving a unique IP.
  37 In this situation, it is sufficient to configure the networking applications
  38 on the host to listen only on the host IP.
  39 Generally, this consists of specifying the appropriate IP address to be
  40 used by inetd and SSH, and disabling applications that are not capable
  41 of limiting their address scope, such as sendmail, the port mapper, and
  42 syslogd.
  43 Other third party applications that have been installed on the host must also be
  44 configured in this manner, or users connecting to the jailbox will
  45 discover the host environment service, unless the jailbox has
  46 specifically bound a service to that port.
  47 In some situations, this can actually be the desirable behaviour.
  48 .PP
  49 The jail environments must also be custom-configured.
  50 This consists of building and installing a miniature version of the
  51 FreeBSD file system tree off of a subdirectory in the host environment,
  52 usually \fC/usr/jail\fP, or \fC/data/jail\fP, with a subdirectory per jail.
  53 Appropriate instructions for generating this tree are included in the
  54 jail(8) man page, but generally this process may be automated using the
  55 FreeBSD build environment.
  56 .PP
  57 One notable difference from the default FreeBSD install is that only
  58 a limited set of device nodes should be created.
  59 .PP
  60 To improve storage efficiency, a fair number of the binaries in the system tree
  61 may be deleted, as they are not relevant in a jail environment.
  62 This includes the kernel, boot loader, and related files, as well as
  63 hardware and network configuration tools.
  64 .PP
  65 After the creation of the jail tree, the easiest way to configure it is
  66 to start up the jail in single-user mode.
  67 The sysinstall admin tool may be used to help with the task, although
  68 it is not installed by default as part of the system tree.
  69 These tools should be run in the jail environment, or they will affect
  70 the host environment's configuration.
  71 .DS
  72 .ft C
  73 .ps -2
  74 # mkdir /data/jail/192.168.11.100/stand
  75 # cp /stand/sysinstall /data/jail/192.168.11.100/stand
  76 # jail /data/jail/192.168.11.100 testhostname 192.168.11.100 \e
  77         /bin/sh
  78 .ps +2
  79 .R
  80 .DE
  81 .PP
  82 After running the jail command, the shell is now within the jail environment,
  83 and all further commands
  84 will be limited to the scope of the jail until the shell exits.
  85 If the network alias has not yet been configured, then the jail will be
  86 unable to access the network.
  87 .PP
  88 The startup configuration of the jail environment may be configured so
  89 as to quell warnings from services that cannot run in the jail.
  90 Also, any per-system configuration required for a normal FreeBSD system
  91 is also required for each jailbox.
  92 Typically, this includes:
  93 .IP "" 5n
  94 \(bu Create empty /etc/fstab
  95 .IP
  96 \(bu Disable portmapper
  97 .IP
  98 \(bu Run newaliases
  99 .IP
 100 \(bu Disabling interface configuration
 101 .IP
 102 \(bu Configure the resolver
 103 .IP
 104 \(bu Set root password
 105 .IP
 106 \(bu Set timezone
 107 .IP
 108 \(bu Add any local accounts
 109 .IP
 110 \(bu Install any packets
 111 .NH 2
 112 Starting Jails
 113 .PP
 114 Jails are typically started by executing their /etc/rc script in much
 115 the same manner a shell was started in the previous section.
 116 Before starting the jail, any relevant networking configuration
 117 should also be performed.
 118 Typically, this involves adding an additional IP address to the
 119 appropriate network interface, setting network properties for the
 120 IP address using IP filtering, forwarding, and bandwidth shaping,
 121 and mounting a process file system for the jail, if the ability to
 122 debug processes from within the jail is desired.
 123 .DS
 124 .ft C
 125 .ps -2
 126 # ifconfig ed0 inet add 192.168.11.100 netmask 255.255.255.255
 127 # mount -t procfs proc /data/jail/192.168.11.100/proc
 128 # jail /data/jail/192.168.11.100 testhostname 192.168.11.100 \e
 129         /bin/sh /etc/rc
 130 .ps +2
 131 .ft P
 132 .DE
 133 .PP
 134 A few warnings are generated for sysctl's that are not permitted
 135 to be set within the jail, but the end result is a set of processes
 136 in an isolated process environment, bound to a single IP address.
 137 Normal procedures for accessing a FreeBSD machine apply: telneting in
 138 through the network reveals a telnet prompt, login, and shell.
 139 .DS
 140 .ft C
 141 .ps -2
 142 % ps ax
 143   PID  TT  STAT      TIME COMMAND
 144   228  ??  SsJ    0:18.73 syslogd
 145   247  ??  IsJ    0:00.05 inetd -wW
 146   249  ??  IsJ    0:28.43 cron
 147   252  ??  SsJ    0:30.46 sendmail: accepting connections on port 25
 148   291  ??  IsJ    0:38.53 /usr/local/sbin/sshd
 149 93694  ??  SJ     0:01.01 sshd: rwatson@ttyp0 (sshd)
 150 93695  p0  SsJ    0:00.06 -csh (csh)
 151 93700  p0  R+J    0:00.00 ps ax
 152 .ps +2
 153 .ft P
 154 .DE
 155 .PP
 156 It is immediately obvious that the environment is within a jailbox: there
 157 is no init process, no kernel daemons, and a J flag is present beside all
 158 processes indicating the presence of a jail.
 159 .PP
 160 As with any FreeBSD system, accounts may be created and deleted,
 161 mail is delivered, logs are generated, packages may be added, and the
 162 system may be hacked into if configured incorrectly, or running a buggy
 163 version of a piece of software.
 164 However, all of this happens strictly within the scope of the jail.
 165 .NH 2
 166 Jail Management
 167 .PP
 168 Jail management is an interesting prospect, as there are two perspectives
 169 from which a jail environment may be administered: from within the jail,
 170 and from the host environment.
 171 From within the jail, as described above, the process is remarkably similar
 172 to any regular FreeBSD install, although certain actions are prohibited,
 173 such as mounting file systems, modifying system kernel properties, etc.
 174 The only area that really differs are that of shutting
 175 the system down: the processes within the jail may deliver signals
 176 between them, allowing all processes to be killed, but bringing the
 177 system back up requires intervention from outside of the jailbox.
 178 .PP
 179 From outside of the jail, there are a range of capabilities, as well
 180 as limitations.
 181 The jail environment is, in effect, a subset of the host environment:
 182 the jail file system appears as part of the host file system, and may
 183 be directly modified by processes in the host environment.
 184 Processes within the jail appear in the process listing of the host,
 185 and may likewise be signalled or debugged.
 186 The host process file system makes the hostname of the jail environment
 187 accessible in /proc/procnum/status, allowing utilities in the host
 188 environment to manage processes based on jailname.
 189 However, the default configuration allows privileged processes within
 190 jails to set the hostname of the jail, which makes the status file less
 191 useful from a management perspective if the contents of the jail are
 192 malicious.
 193 To prevent a jail from changing its hostname, the
 194 "jail.set_hostname_allowed" sysctl may be set to 0 prior to starting
 195 any jails.
 196 .PP
 197 One aspect immediately observable in an environment with multiple jails
 198 is that uids and gids are local to each jail environment: the uid associated
 199 with a process in one jail may be for a different user than in another
 200 jail.
 201 This collision of identifiers is only visible in the host environment,
 202 as normally processes from one jail are never visible in an environment
 203 with another scope for user/uid and group/gid mapping.
 204 Managers in the host environment should understand these scoping issues,
 205 or confusion and unintended consequences may result.
 206 .PP
 207 Jailed processes are subject to the normal restrictions present for
 208 any processes, including resource limits, and limits placed by the network
 209 code, including firewall rules.
 210 By specifying firewall rules for the IP address bound to a jail, it is
 211 possible to place connectivity and bandwidth limitations on individual
 212 jails, restricting services that may be consumed or offered.
 213 .PP
 214 Management of jails is an area that will see further improvement in
 215 future versions of FreeBSD.  Some of these potential improvements are
 216 discussed later in this paper.