{"id":25640550,"url":"https://github.com/kstrauser/jailadmin","last_synced_at":"2026-06-23T11:30:20.199Z","repository":{"id":1786532,"uuid":"2710404","full_name":"kstrauser/jailadmin","owner":"kstrauser","description":"FreeBSD jail management tools","archived":false,"fork":false,"pushed_at":"2011-11-04T16:22:05.000Z","size":112,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-15T19:00:00.715Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://honeypot.net/project/jailadmin","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"ankane/chartkick","license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kstrauser.png","metadata":{"files":{"readme":"README","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-11-04T16:07:22.000Z","updated_at":"2017-04-22T23:17:23.000Z","dependencies_parsed_at":"2022-08-20T08:51:12.761Z","dependency_job_id":null,"html_url":"https://github.com/kstrauser/jailadmin","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kstrauser%2Fjailadmin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kstrauser%2Fjailadmin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kstrauser%2Fjailadmin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kstrauser%2Fjailadmin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kstrauser","download_url":"https://codeload.github.com/kstrauser/jailadmin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240271524,"owners_count":19774859,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-23T04:40:20.311Z","updated_at":"2026-06-23T11:30:20.131Z","avatar_url":"https://github.com/kstrauser.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"#### READ THIS FIRST\n\nI wrote this code in 2004 before anyone had solid ideas about the \"right\"\nway to manage FreeBSD jails. Since then, /etc/rc.d/jail has become part of\nthe base system and ezjail has taken over most of the day-to-day maintenance\nchores. Still, some people are still downloading this software, probably for\nthe SNMP bits or because they're used to it and don't want to change.\nIf that's you, here you go! Moving the project to GitHub should make it\neasier for you to find and any patches you happen to make would be most\nwelcome!\n\n#### INTRODUCTION\n\nJailAdmin is a simple system for administering FreeBSD jail environments.\nIt consists of four files:\n\n  Jail.pm - A general-purpose module for gathering information, starting,\n            and stopping jails\n\n  jailadmin - A Perl program that serves as a command line interface to\n              Jail.pm\n\n  jailadmin.conf - Site-specific configuration options\n\n  jail.sh - An rc.d file to start and stop jails at system boot or shutdown.\n\nThe optional SNMP components are:\n\n  jail-snmp - A plugin to the net-snmp package\n  \n  jail-snmp-persist - A persistent version of jail-snmp that avoids the\n                      startup overhead inherent in launching a new copy every\n                      time the associated OIDs are polled.\n\n  JAIL-MIB.txt - A MIB file describing the SNMP attributes\n\n#### TERMINOLOGY\n\n   Server:\n      A named set of attributes uniquely describing a jail environment.\n      This extra layer of abstraction provides a consistent anchor for jails\n      whose hostnames and IPs may change.\n\n\n#### CONFIGURATION\n\nEdit jailadmin.conf with your favorite editor.  It has an extremely simple\nformat:\n\n   - All global options are defined as 'key = value'\n\n   - All server-specific options are defined by the appropriate servername\n     on a line by itself, followed by one or more lines beginning with a\n     space, in the format 'key: value'\n\n   - Leading and trailing whitespace are ignored, except for the leading\n     whitespace that distinguishes server-specific options (as above)\n\n   - All characters on a line after a pound sign '#' are ignored\n\n   - Blank lines are ignored\n\nThe sample configuration file is heavily documented, and all available\noptions are defined there.\n\nExample:\n\nSay that you have 4 servers (named 'server1', 'server2', 'server3',\n'server4').  They are all rooted in subdirectories of /var/jail .  They are\nall webservers to different domains.  jailadmin.conf could be written as:\n\n########################################\njaildir=/var/jail\n\nserver1\n    ip: 10.0.1.2\n    hostname: www.domain1.com\n\nserver2\n    ip: 10.0.1.3\n    hostname: www.domain2.com\n\nserver3\n    ip: 10.0.1.4\n    hostname: www.domain3.com\n\nserver4\n    ip: 10.0.1.5\n    hostname: www.domain4.com\n########################################\n\n\n#### USAGE\n\njailadmin takes at least two arguments, 'operation' and one or more\nservernames, where servernames are the name of entries or groups defined in\njailadmin.conf, and operation is one of 'start', 'stop', and 'status'.\n\n'start' is pretty simple, but it does check to back sure that the specified\njail is not currently running (defined as having one or more processes\nimprisoned within it.\n\n'stop' invokes two distinctly different modes of operation.  The first,\n\"naive\", works as follows:\n\nIt sends a TERM signal to all processes within the jail.  After a 5-second\nwait, if processes are still running, then it waits another 10 seconds.\nAll processes still running at that time are sent the KILL signal.  This is\nsimilar to FreeBSD's own shutdown process, although vastly less\nsophisticated.\n\nThe second, \"emulated\", works by first invoking /etc/rc.shutdown within a\njail.  After that script has completed, it follows the \"naive\" process\ndetailed above to remove all lingering processes.\n\nRecent versions of jailadmin can parallelize stages of the shutdown process\nfor several jails at once, so that the waiting periods can be made as\nconcurrent as possible.  For example, given 10 jails where each needs to\nwait for the full 15 seconds, the total shutdown time can be reduced from\n150 seconds to 15.  This is very nice for quickly rebooting a number of\nservers.\n\n'status' returns a ps(1)-like status report.  For example:  \n\n    Server: virtual3\n\n    USER   PID  %CPU  %MEM  RSS TT STAT    TIME COMMAND\n    root 96703   0.0   0.1  908 ?? SsJ  0:00.19 /usr/sbin/syslogd -s\n    root 96760   0.0   0.2 3028 ?? SsJ  0:00.16 /usr/sbin/sshd\n    root 96767   0.0   0.1 1096 ?? IsJ  0:00.05 /usr/sbin/cron -s\n\n\n#### NOTES\n\nJail.pm expects its configuration file to be /usr/local/etc/jailadmin.conf\nby default.  However, upon initialization, it calls Getopt::Long::GetOptions\nto look for a command line argument '--conffile' to read instead.\nTherefore, all programs that use Jail.pm (such as jailadmin), can use any\nother configuration file.  Example:\n\n  jailadmin --conffile /tmp/generatedfile server2 start\n\nJail.pm aggressively caches all information it acquires from its\nenvironment; you may call any of its functions as often as you like with\nlittle performance degradation.  However, this also means that its\ninformation may be out-of-date, particularly its cache of running processes\nand their information.  Call Jail::updateProcessList to force the module to\nreload this information as needed.  For example, after calling\nJail::signalProcs(), you would probably want to see if any processes are\nstill running in a particular jail.  updateProcessList() will ensure that\nyou're examining current data.\n\nJail.pm can use FreeBSD's \"jls\" and \"jexec\" commands to simplify and speed\nup the control of jail environments and data gathering.  Furthermore, they\nremove the requirement of having /proc mounted in the host environment, which\nis certainly appealing to the security-conscious.  There is virtually no ill\neffect from using these tools in a \"normal\" jail environment that's based on\na cloned FreeBSD system.  However, extremely minimal jails (such as those\ncontaining a single server process) or ones based on emulated Linux systems\n(where the \"ps\" command still looks in /proc for details) may require the\ncontinued use of the old system.  To enable the use of \"jls\" and \"jexec\"\nglobally, set \"default_usejtools=1\" inside jailadmin.conf.  That value may\nbe overridden for individual jails.\n\n\n#### SNMP\n\nAs of version 1.3, the jailadmin package comes with an SNMP extension for\nthe UCD-SNMP snmpd.  By adding the extension and the included mib\ndefinitions to your snmpd configuration, you can easily monitor your jail\nenvironments with the same tools you're already using to track your network\nusage, hardware capacity, and other interesting data.\n\nAn example tree traversal:\n\n  # snmpwalk localhost mycommunity .1.3.6.1.4.1.2021.255\n  enterprises.ucdavis.jail.general.numJails = 3\n  enterprises.ucdavis.jail.jailTable.jailIndex.1 = 1\n  enterprises.ucdavis.jail.jailTable.jailIndex.2 = 2\n  enterprises.ucdavis.jail.jailTable.jailIndex.3 = 3\n  enterprises.ucdavis.jail.jailTable.jailServer.1 = \"vserver1\"\n  enterprises.ucdavis.jail.jailTable.jailServer.2 = \"vserver2\"\n  enterprises.ucdavis.jail.jailTable.jailServer.3 = \"vserver3\"\n  enterprises.ucdavis.jail.jailTable.jailHostname.1 = \"server1.int\"\n  enterprises.ucdavis.jail.jailTable.jailHostname.2 = \"server2.int\"\n  enterprises.ucdavis.jail.jailTable.jailHostname.3 = \"server3.int\"\n  enterprises.ucdavis.jail.jailTable.jailIp.1 = IpAddress: 10.0.5.1\n  enterprises.ucdavis.jail.jailTable.jailIp.2 = IpAddress: 10.0.5.2\n  enterprises.ucdavis.jail.jailTable.jailIp.3 = IpAddress: 10.0.5.3\n  enterprises.ucdavis.jail.jailTable.jailNumProcs.1 = 6\n  enterprises.ucdavis.jail.jailTable.jailNumProcs.2 = 23\n  enterprises.ucdavis.jail.jailTable.jailNumProcs.3 = 14\n\nFuture support for read-write settings is being considered.  Imagine being\nable to start or stop a jail by writing to jailTable.isRunning.n without\nleaving your OpenView or Netcool console.\n\n\n#### CREDITS\n\nThis package was developed by Kirk Strauser \u003ckirk@struaser.com\u003e with the\nhelp and guidance of generous contributors.  In no particular order, they\ninclude:\n\n  - Dar Larsson\n  - Jeremy Bobbio\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkstrauser%2Fjailadmin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkstrauser%2Fjailadmin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkstrauser%2Fjailadmin/lists"}