share/doc/papers/jail/mgt.ms

   1 .\"
   2 .\" $FreeBSD: src/share/doc/papers/jail/mgt.ms,v 1.1.2.1 2000/08/20 13:16:44 mpp Exp $
   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 MAKEDEV(8) has been modified to accept a ``jail'' argument that creates
  60 the correct set of nodes.
  61 .PP
  62 To improve storage efficiency, a fair number of the binaries in the system tree
  63 may be deleted, as they are not relevant in a jail environment.
  64 This includes the kernel, boot loader, and related files, as well as
  65 hardware and network configuration tools.
  66 .PP
  67 After the creation of the jail tree, the easiest way to configure it is
  68 to start up the jail in single-user mode.
  69 The sysinstall admin tool may be used to help with the task, although
  70 it is not installed by default as part of the system tree.
  71 These tools should be run in the jail environment, or they will affect
  72 the host environment's configuration.
  73 .DS
  74 .ft C
  75 .ps -2
  76 # mkdir /data/jail/192.168.11.100/stand
  77 # cp /stand/sysinstall /data/jail/192.168.11.100/stand
  78 # jail /data/jail/192.168.11.100 testhostname 192.168.11.100 \e
  79         /bin/sh
  80 .ps +2
  81 .R
  82 .DE
  83 .PP
  84 After running the jail command, the shell is now within the jail environment,
  85 and all further commands
  86 will be limited to the scope of the jail until the shell exits.
  87 If the network alias has not yet been configured, then the jail will be
  88 unable to access the network.
  89 .PP
  90 The startup configuration of the jail environment may be configured so
  91 as to quell warnings from services that cannot run in the jail.
  92 Also, any per-system configuration required for a normal FreeBSD system
  93 is also required for each jailbox.
  94 Typically, this includes:
  95 .IP "" 5n
  96 \(bu Create empty /etc/fstab
  97 .IP
  98 \(bu Disable portmapper
  99 .IP
 100 \(bu Run newaliases
 101 .IP
 102 \(bu Disabling interface configuration
 103 .IP
 104 \(bu Configure the resolver
 105 .IP
 106 \(bu Set root password
 107 .IP
 108 \(bu Set timezone
 109 .IP
 110 \(bu Add any local accounts
 111 .IP
 112 \(bu Install any packets
 113 .NH 2
 114 Starting Jails
 115 .PP
 116 Jails are typically started by executing their /etc/rc script in much
 117 the same manner a shell was started in the previous section.
 118 Before starting the jail, any relevant networking configuration
 119 should also be performed.
 120 Typically, this involves adding an additional IP address to the
 121 appropriate network interface, setting network properties for the
 122 IP address using IP filtering, forwarding, and bandwidth shaping,
 123 and mounting a process file system for the jail, if the ability to
 124 debug processes from within the jail is desired.
 125 .DS
 126 .ft C
 127 .ps -2
 128 # ifconfig ed0 inet add 192.168.11.100 netmask 255.255.255.255
 129 # mount -t procfs proc /data/jail/192.168.11.100/proc
 130 # jail /data/jail/192.168.11.100 testhostname 192.168.11.100 \e
 131         /bin/sh /etc/rc
 132 .ps +2
 133 .ft P
 134 .DE
 135 .PP
 136 A few warnings are generated for sysctl's that are not permitted
 137 to be set within the jail, but the end result is a set of processes
 138 in an isolated process environment, bound to a single IP address.
 139 Normal procedures for accessing a FreeBSD machine apply: telneting in
 140 through the network reveals a telnet prompt, login, and shell.
 141 .DS
 142 .ft C
 143 .ps -2
 144 % ps ax
 145   PID  TT  STAT      TIME COMMAND
 146   228  ??  SsJ    0:18.73 syslogd
 147   247  ??  IsJ    0:00.05 inetd -wW
 148   249  ??  IsJ    0:28.43 cron
 149   252  ??  SsJ    0:30.46 sendmail: accepting connections on port 25
 150   291  ??  IsJ    0:38.53 /usr/local/sbin/sshd
 151 93694  ??  SJ     0:01.01 sshd: rwatson@ttyp0 (sshd)
 152 93695  p0  SsJ    0:00.06 -csh (csh)
 153 93700  p0  R+J    0:00.00 ps ax
 154 .ps +2
 155 .ft P
 156 .DE
 157 .PP
 158 It is immediately obvious that the environment is within a jailbox: there
 159 is no init process, no kernel daemons, and a J flag is present beside all
 160 processes indicating the presence of a jail.
 161 .PP
 162 As with any FreeBSD system, accounts may be created and deleted,
 163 mail is delivered, logs are generated, packages may be added, and the
 164 system may be hacked into if configured incorrectly, or running a buggy
 165 version of a piece of software.
 166 However, all of this happens strictly within the scope of the jail.
 167 .NH 2
 168 Jail Management
 169 .PP
 170 Jail management is an interesting prospect, as there are two perspectives
 171 from which a jail environment may be administered: from within the jail,
 172 and from the host environment.
 173 From within the jail, as described above, the process is remarkably similar
 174 to any regular FreeBSD install, although certain actions are prohibited,
 175 such as mounting file systems, modifying system kernel properties, etc.
 176 The only area that really differs are that of shutting
 177 the system down: the processes within the jail may deliver signals
 178 between them, allowing all processes to be killed, but bringing the
 179 system back up requires intervention from outside of the jailbox.
 180 .PP
 181 From outside of the jail, there are a range of capabilities, as well
 182 as limitations.
 183 The jail environment is, in effect, a subset of the host environment:
 184 the jail file system appears as part of the host file system, and may
 185 be directly modified by processes in the host environment.
 186 Processes within the jail appear in the process listing of the host,
 187 and may likewise be signalled or debugged.
 188 The host process file system makes the hostname of the jail environment
 189 accessible in /proc/procnum/status, allowing utilities in the host
 190 environment to manage processes based on jailname.
 191 However, the default configuration allows privileged processes within
 192 jails to set the hostname of the jail, which makes the status file less
 193 useful from a management perspective if the contents of the jail are
 194 malicious.
 195 To prevent a jail from changing its hostname, the
 196 "jail.set_hostname_allowed" sysctl may be set to 0 prior to starting
 197 any jails.
 198 .PP
 199 One aspect immediately observable in an environment with multiple jails
 200 is that uids and gids are local to each jail environment: the uid associated
 201 with a process in one jail may be for a different user than in another
 202 jail.
 203 This collision of identifiers is only visible in the host environment,
 204 as normally processes from one jail are never visible in an environment
 205 with another scope for user/uid and group/gid mapping.
 206 Managers in the host environment should understand these scoping issues,
 207 or confusion and unintended consequences may result.
 208 .PP
 209 Jailed processes are subject to the normal restrictions present for
 210 any processes, including resource limits, and limits placed by the network
 211 code, including firewall rules.
 212 By specifying firewall rules for the IP address bound to a jail, it is
 213 possible to place connectivity and bandwidth limitations on individual
 214 jails, restricting services that may be consumed or offered.
 215 .PP
 216 Management of jails is an area that will see further improvement in
 217 future versions of FreeBSD.  Some of these potential improvements are
 218 discussed later in this paper.