io7m-jguard 0.1.0 Documentation ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Contents ───────────────────────────────────────────────────────────────────────────── 1 Package Information ................................................... pkg 1.1 Orientation ........................................... pkg.orientation 1.2 Installation .............................................. pkg.install 1.3 Platform Specific Issues ................................. pkg.platform 1.4 License ................................................... pkg.license 2 Command Line Tools .................................................. tools 2.1 jguard ................................................... tools.jguard 1 Package Information [id: pkg] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Contents ───────────────────────────────────────────────────────────────────────────── 1.1 Orientation ............................................. pkg.orientation 1.1.1 Overview ................................... pkg.orientation.overview 1.2 Installation ................................................ pkg.install 1.2.1 Source compilation ............................... pkg.install.source 1.2.2 Maven ............................................. pkg.install.maven 1.3 Platform Specific Issues ................................... pkg.platform 1.4 License ..................................................... pkg.license 1.1 Orientation [id: pkg.orientation] 1.1.1 Overview [id: pkg.orientation.overview] 1 The jguard package implements a set of tools for managing FreeBSD jails [url: http://www.freebsd.org]. 1.2 Installation [id: pkg.install] 1.2.1 Source compilation [id: pkg.install.source] 1 The project can be compiled and installed with Maven [url: http://maven.apache.org]: 2 $ mvn -C clean install 1.2.2 Maven [id: pkg.install.maven] 1 Regular releases are made to the Central Repository [url: http://search.maven.org/#search%7Cga%7C1%7Cjguard]. 2 All io7m.com [url: http://io7m.com] packages use Semantic Versioning [0], which implies that it is always safe to use version ranges with an exclusive upper bound equal to the next major version - the API of the package will not change in a backwards-incompatible manner before the next major version. 1.3 Platform Specific Issues [id: pkg.platform] 1 The package only works on FreeBSD [url: http://www.freebsd.org]. 1.4 License [id: pkg.license] 1 All files distributed with the io7m-jguard package are placed under the following license: 1.4.2.2 License ─────────────── Copyright © 2016 http://io7m.com Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 2 Command Line Tools [id: tools] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Contents ───────────────────────────────────────────────────────────────────────────── 2.1 jguard ..................................................... tools.jguard 2.1.1 Synopsis ...................................... tools.jguard.synopsis 2.1.2 version ........................................ tools.jguard.version 2.1.3 start ............................................ tools.jguard.start 2.1.4 download-base-archive ............ tools.jguard.download_base_archive 2.1.5 create-jail-base ...................... tools.jguard.create_jail_base 2.1.6 create-jail ................................ tools.jguard.create_jail 2.1 jguard [id: tools.jguard] 2.1.1 Synopsis [id: tools.jguard.synopsis] 1 The jguard command provides various functions for creating and supervising FreeBSD jails. 2 Usage: jguard [options] [command] [command options] Options: -verbose Set the minimum logging verbosity level Default: info Possible Values: [trace, debug, info, warn, error] Commands: start Start a jail Usage: start [options] Options: * -file The jail configuration file -verbose Set the minimum logging verbosity level Default: info Possible Values: [trace, debug, info, warn, error] download-base-archive Download a binary archive for creating a jail Usage: download-base-archive [options] Options: -arch Override the system architecture * -archive The output file -base-uri Override the base URI Default: http://ftp.freebsd.org/pub/FreeBSD/releases/ -fetch-archive Select a specific archive file Default: base.txz -release Override the system release -retry Set the number of retries for failed downloads (0 is unlimited) Default: 10 -verbose Set the minimum logging verbosity level Default: info Possible Values: [trace, debug, info, warn, error] create-jail-base Create a base jail and template from an archive Usage: create-jail-base [options] Options: * -archive Select a specific archive file -archive-format Explicitly specify the archive format Possible Values: [JAIL_ARCHIVE_FORMAT_TAR_XZ] * -base The created base directory * -base-template The created base template directory -verbose Set the minimum logging verbosity level Default: info Possible Values: [trace, debug, info, warn, error] create-jail Create a jail Usage: create-jail [options] Options: * -base The base directory * -base-template The base template directory * -hostname The jail hostname -ipv4 The jail IPv4 address -ipv6 The jail IPv6 address * -name The jail name * -root The jail directory * -start-command The command that will be executed inside the jail on startup -verbose Set the minimum logging verbosity level Default: info Possible Values: [trace, debug, info, warn, error] version Retrieve the program version Usage: version [options] Options: -verbose Set the minimum logging verbosity level Default: info Possible Values: [trace, debug, info, warn, error] 3 The command line tool is distributed as part of the executable io7m-jguard-cmdline-0.1.0-main.jar file (referred to as jguard.jar in usage examples, for brevity): 4 $ java -jar io7m-jguard-cmdline-0.1.0-main.jar 2.1.2 version [id: tools.jguard.version] 1 The version subcommand displays the version of the package. 2.1.3 start [id: tools.jguard.start] 1 The start subcommand parses the given jail configuration file and starts the specified jail. The command directly executes a process within the specified jail: The current process image is completely replaced with the specified jail command and is intended to be used with a process supervision system. 2 # java -jar jguard.jar start -file jail0.conf 2.1.4 download-base-archive [id: tools.jguard.download_base_archive] 1 The download-base-archive subcommand downloads an installation archive intended for creating new jails. Typically, this archive will be the base.txz file distributed with FreeBSD releases. 2 # java -jar jguard.jar download-base-archive -archive /usr/jail/base.txz 3 The command supports the use of HTTP proxies via the standard Java http.proxyHost and http.proxyPort properties: 4 # java -jar jguard.jar -Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=3128 download-base-archive -archive /usr/jail/base.txz 5 Note that as of the time of writing, ftp.freebsd.org [url: https://ftp.freebsd.org] currently has a misconfigured TLS certificate (the certificate is only valid for download.freebsd.org [url: https://download.freebsd.org]) and therefore the command will fail with a TLS error when attempting to use the https site. Additionally, the FreeBSD project does not provide PGP signatures for the individual binary archives from the FTP sites and, bizarrely, instead relies on providing them via the misc/freebsd-release-manifests [url: https://svnweb.freebsd.org/ports/head/misc/freebsd-release-manifests/] package. It is STRONGLY recommended to check the signatures of any downloaded archives against the signatures in this package. 2.1.5 create-jail-base [id: tools.jguard.create_jail_base] 1 The create-jail-base subcommand unpacks an archive containing a FreeBSD base system and creates base and base-template directories that are shared between jail instances. 2 # java -jar jguard.jar create-jail-base -archive /usr/jail/base.txz -base /usr/jail/base -base-template /usr/jail/base-template 2.1.6 create-jail [id: tools.jguard.create_jail] 1 The create-jail subcommand creates a new jail. 2 # java -jar jguard.jar create-jail -base /usr/jail/base -base-template /usr/jail/base-template -hostname jail0.example.com -name jail0_example_com -root /usr/jail/jail0.example.com -start-command "/usr/local/bin/s6-svscan /service" -ipv4 10.8.0.23 Footnotes ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ [0] http://semver.org [url: http://semver.org]