# $Id: README 138 2004-11-19 21:04:24Z kirk $ #### INTRODUCTION JailAdmin is a simple system for administering FreeBSD jail environments. It consists of four files: Jail.pm - A general-purpose module for gathering information, starting, and stopping jails jailadmin - A Perl program that serves as a command line interface to Jail.pm jailadmin.conf - Site-specific configuration options jail.sh - An rc.d file to start and stop jails at system boot or shutdown. The optional SNMP components are: jail-snmp - A plugin to the net-snmp package jail-snmp-persist - A persistent version of jail-snmp that avoids the startup overhead inherent in launching a new copy every time the associated OIDs are polled. JAIL-MIB.txt - A MIB file describing the SNMP attributes #### TERMINOLOGY Server: A named set of attributes uniquely describing a jail environment. This extra layer of abstraction provides a consistent anchor for jails whose hostnames and IPs may change. #### CONFIGURATION Edit jailadmin.conf with your favorite editor. It has an extremely simple format: - All global options are defined as 'key = value' - All server-specific options are defined by the appropriate servername on a line by itself, followed by one or more lines beginning with a space, in the format 'key: value' - Leading and trailing whitespace are ignored, except for the leading whitespace that distinguishes server-specific options (as above) - All characters on a line after a pound sign '#' are ignored - Blank lines are ignored The sample configuration file is heavily documented, and all available options are defined there. Example: Say that you have 4 servers (named 'server1', 'server2', 'server3', 'server4'). They are all rooted in subdirectories of /var/jail . They are all webservers to different domains. jailadmin.conf could be written as: ######################################## jaildir=/var/jail server1 ip: 10.0.1.2 hostname: www.domain1.com server2 ip: 10.0.1.3 hostname: www.domain2.com server3 ip: 10.0.1.4 hostname: www.domain3.com server4 ip: 10.0.1.5 hostname: www.domain4.com ######################################## #### USAGE jailadmin takes at least two arguments, 'operation' and one or more servernames, where servernames are the name of entries or groups defined in jailadmin.conf, and operation is one of 'start', 'stop', and 'status'. 'start' is pretty simple, but it does check to back sure that the specified jail is not currently running (defined as having one or more processes imprisoned within it. 'stop' invokes two distinctly different modes of operation. The first, "naive", works as follows: It sends a TERM signal to all processes within the jail. After a 5-second wait, if processes are still running, then it waits another 10 seconds. All processes still running at that time are sent the KILL signal. This is similar to FreeBSD's own shutdown process, although vastly less sophisticated. The second, "emulated", works by first invoking /etc/rc.shutdown within a jail. After that script has completed, it follows the "naive" process detailed above to remove all lingering processes. Recent versions of jailadmin can parallelize stages of the shutdown process for several jails at once, so that the waiting periods can be made as concurrent as possible. For example, given 10 jails where each needs to wait for the full 15 seconds, the total shutdown time can be reduced from 150 seconds to 15. This is very nice for quickly rebooting a number of servers. 'status' returns a ps(1)-like status report. For example: Server: virtual3 USER PID %CPU %MEM RSS TT STAT TIME COMMAND root 96703 0.0 0.1 908 ?? SsJ 0:00.19 /usr/sbin/syslogd -s root 96760 0.0 0.2 3028 ?? SsJ 0:00.16 /usr/sbin/sshd root 96767 0.0 0.1 1096 ?? IsJ 0:00.05 /usr/sbin/cron -s #### NOTES Jail.pm expects its configuration file to be /usr/local/etc/jailadmin.conf by default. However, upon initialization, it calls Getopt::Long::GetOptions to look for a command line argument '--conffile' to read instead. Therefore, all programs that use Jail.pm (such as jailadmin), can use any other configuration file. Example: jailadmin --conffile /tmp/generatedfile server2 start Jail.pm aggressively caches all information it acquires from its environment; you may call any of its functions as often as you like with little performance degradation. However, this also means that its information may be out-of-date, particularly its cache of running processes and their information. Call Jail::updateProcessList to force the module to reload this information as needed. For example, after calling Jail::signalProcs(), you would probably want to see if any processes are still running in a particular jail. updateProcessList() will ensure that you're examining current data. Jail.pm can use FreeBSD's "jls" and "jexec" commands to simplify and speed up the control of jail environments and data gathering. Furthermore, they remove the requirement of having /proc mounted in the host environment, which is certainly appealing to the security-conscious. There is virtually no ill effect from using these tools in a "normal" jail environment that's based on a cloned FreeBSD system. However, extremely minimal jails (such as those containing a single server process) or ones based on emulated Linux systems (where the "ps" command still looks in /proc for details) may require the continued use of the old system. To enable the use of "jls" and "jexec" globally, set "default_usejtools=1" inside jailadmin.conf. That value may be overridden for individual jails. #### SNMP As of version 1.3, the jailadmin package comes with an SNMP extension for the UCD-SNMP snmpd. By adding the extension and the included mib definitions to your snmpd configuration, you can easily monitor your jail environments with the same tools you're already using to track your network usage, hardware capacity, and other interesting data. An example tree traversal: # snmpwalk localhost mycommunity .1.3.6.1.4.1.2021.255 enterprises.ucdavis.jail.general.numJails = 3 enterprises.ucdavis.jail.jailTable.jailIndex.1 = 1 enterprises.ucdavis.jail.jailTable.jailIndex.2 = 2 enterprises.ucdavis.jail.jailTable.jailIndex.3 = 3 enterprises.ucdavis.jail.jailTable.jailServer.1 = "vserver1" enterprises.ucdavis.jail.jailTable.jailServer.2 = "vserver2" enterprises.ucdavis.jail.jailTable.jailServer.3 = "vserver3" enterprises.ucdavis.jail.jailTable.jailHostname.1 = "server1.int" enterprises.ucdavis.jail.jailTable.jailHostname.2 = "server2.int" enterprises.ucdavis.jail.jailTable.jailHostname.3 = "server3.int" enterprises.ucdavis.jail.jailTable.jailIp.1 = IpAddress: 10.0.5.1 enterprises.ucdavis.jail.jailTable.jailIp.2 = IpAddress: 10.0.5.2 enterprises.ucdavis.jail.jailTable.jailIp.3 = IpAddress: 10.0.5.3 enterprises.ucdavis.jail.jailTable.jailNumProcs.1 = 6 enterprises.ucdavis.jail.jailTable.jailNumProcs.2 = 23 enterprises.ucdavis.jail.jailTable.jailNumProcs.3 = 14 Future support for read-write settings is being considered. Imagine being able to start or stop a jail by writing to jailTable.isRunning.n without leaving your OpenView or Netcool console. #### CREDITS This package was developed by Kirk Strauser with the help and guidance of generous contributors. In no particular order, they include: - Dar Larsson - Jeremy Bobbio