io7m-jguard 0.1.0 Documentation
1
Package Information
1.1
Orientation
1.1.1
Overview
1
The jguard package implements a set of tools for managing FreeBSD jails.
1.2
Installation
1.2.1
Source compilation
1
The project can be compiled and installed with Maven:
2
$ mvn -C clean install
1.2.2
Maven
1
Regular releases are made to the Central Repository.
2
All 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
1
The package only works on FreeBSD.
1.4
License
1
All files distributed with the io7m-jguard package are placed under the following license:
1.4.2.2 License
Copyright © 2016 <code@io7m.com> 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
2.1
jguard
2.1.1
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
1
The version subcommand displays the version of the package.
2.1.3
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
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 currently has a misconfigured TLS certificate (the certificate is only valid for 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 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
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
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
[0]
http://semver.org