preparing docs for 0.6.x release

AUTHORS.md

@@ -13,6 +13,7 @@ Giacomo Olgeni
 JP Mens  
 Jose Rivera  
 Lars E.  
+Paul C.  
 Sven R.  
 
 ### Special thanks

README.md

@@ -46,14 +46,16 @@ Available Commands:
   bootstrap   Bootstrap a FreeBSD release for container base.
   cmd         Execute arbitrary command on targeted container(s).
   console     Console into a running container.
+  convert     Convert a thin container into a thick container.
   cp          cp(1) files from host to targeted container(s).
-  create      Create a new thin container or a thick container if -T|--thick option specified.
+  create      Create a new thin or thick container.
-  destroy     Destroy a stopped container or a FreeBSD release.
+  destroy     Destroy a stopped container or a bootstrapped release.
-  export      Exports a specified container.
+  export      Exports a container archive or image.
   help        Help about any command
   htop        Interactive process viewer (requires htop).
-  import      Import a specified container.
+  import      Import a container archive or image.
-  list        List containers (running and stopped).
+  limits      Apply resources limits to targeted container(s). See rctl(8).
+  list        List containers, releases, templates, logs, limits or backups.
   pkg         Manipulate binary packages within targeted container(s). See pkg(8).
   rdr         Redirect host port to container port.
   restart     Restart a running container.
@@ -61,11 +63,11 @@ Available Commands:
   start       Start a stopped container.
   stop        Stop a running container.
   sysrc       Safely edit rc files within targeted container(s).
-  template    Apply file templates to targeted container(s).
+  template    Apply automation templates to targeted container(s).
   top         Display and update information about the top(1) cpu processes.
   update      Update container base -pX release.
   upgrade     Upgrade container release to X.Y-RELEASE.
-  verify      Compare release against a "known good" index.
+  verify      Verify bootstrapped release or automation template.
   zfs         Manage (get|set) zfs attributes on targeted container(s).
 
 Use "bastille -v|--version" for version information.
@@ -73,7 +75,7 @@ Use "bastille command -h|--help" for more information about a command.
 
 ```
 
-## 0.5-beta
+## 0.6-beta
 This document outlines the basic usage of the Bastille container management
 framework. This release is still considered beta.
 
@@ -393,7 +395,8 @@ ishmael ~ # bastille list
 
 You can also list non-running containers with `bastille list containers`.  In
 the same manner you can list archived `logs`, downloaded `templates`, and
-`releases`.  Providing the `-j` flag to list alone will result in JSON output.
+`releases` and `backups`.  Providing the `-j` flag to list alone will result in
+JSON output.
 
 
 bastille service
@@ -872,17 +875,6 @@ Receiving zfs data stream...
 Container 'folsom' imported successfully.
 ```
 
-bastille import list
---------------------
-Exported containers can be listed easily before import.
-```shell
-ishmael ~ # bastille import list
-folsom_2020-01-26-19:23:04.xz
-thickjail_2020-01-25-04:00:19.xz
-thinjail_2020-01-25-02:10:16.txz
-root@nas-mserver: ~#
-```
-
 Example (create, start, console)
 ================================
 This example creates, starts and consoles into the container.

ROADMAP.md

@@ -1,45 +1,55 @@
-Bastille Roadmap
+2020 Bastille Roadmap
-================
+=====================
-This is the general roadmap for the next nine months. I would like the
-near-term done by the end of 2018. The mid-term should be done by March 2019.
-The long-term by summer 2019.
 
-At that point, if the templating is mature, and the top 50 is complete, the
+1. Virtual Networking
-platform is ready for general purpose use. 
+1. Bastille CI/CD
+1. Template Maturity & Consolidation
+1. Container Monitoring
+1. Bastille API
 
+Rough timeline and description below.
 
-near-term
+Virtual Networking (Jan-Feb) ~ 0.6.x-beta
----------
+-----------------------------------------
-1. zfs support (configurable)
+VNET (Virtual Networking) will allow fully virtualized network stacks. This
-2. bastille-dev template (see below):
+would bring the total network options to three (loopback, LAN, VNET). The
-```shell
+anticipated design would use a bridge device connected to containers via epair
-## jail -c name=foo host.hostname=foo allow.raw_sockets children.max=99 
+interfaces.
-## ip4.addr=10.20.12.68 persist
-## jexec foo /bin/csh
-## foo# jail -c name=bar host.hostname=bar allow.raw_sockets 
-## ip4.addr=10.20.12.68 persist
-## foo# jexec bar /bin/csh
-## bar# ping gritton.org
-```
-3. branding
 
+Bastille CI/CD (March-May) ~ 0.7.x-beta
+---------------------------------------
+While we have many of the templates validated by automatic CI/CD, we are not
+validating updates to Bastille itself. This automated validation of Pull
+Requests should be a priority early in the year with a full test suite designed
+to validate all expected uses of Bastille sub-commands.
 
-mid-term
+Template Maturity & Consolidation (June-Aug) ~ 0.8.x-beta
---------
+---------------------------------------------------------
-1. templating
+Put the 101 templates found in GitHub's BastilleBSD-Templates repository into
-2. ssh-to-jail demo (ie; ldap + .authorized_keys + command)
+GitLab CI/CD pipeline until fully covered. This is a great place for community
-```shell
+contribution. Templates are easy to create and verify and we'd love to
-## TODO: .ssh/authorized_keys auto-launch into user jail
+replicate as much of the FreeBSD ports tree as possible!
-## jail_create_login_hook() {
-##     echo "permit nopass ${user} cmd /usr/sbin/jexec args ${name} /usr/bin/login -f ${user}" >> /usr/local/etc/doas.conf
-##     echo "command='/usr/local/bin/doas /usr/sbin/jexec ${name} /usr/bin/login -f ${user}' ${pubkey}" >> $HOME/.ssh/authorized_keys
-## }
-```
-3. additional modules: ps, sockstat, pf, fstab.
 
+In addition, it would be nice to create a consolidated repository of curated
+templates similar in design to the FreeBSD ports tree. This would contain all
+templates in a single repository and mimick ports behavior where appropriate.
 
-long-term
+Container Monitoring (Sept-Oct) ~ 0.9.x-beta
----------
+--------------------------------------------
-1. top 50
+The ability to monitor processes, services, mounts, sockets, etc from the host.
-2. monitoring
+Auto-remediation would be simple enough to define. Notifications would probably
-3. rctl
+require a plugin system for methods/endpoints.
+
+Possible monitoring modules: ps, sockstat, pf, fstab
+
+Possible notification modules: pagerduty, slack, splunk, ELK, etc.
+
+Bastille API (Nov-Dec) ~ 1.0.x-beta
+-----------------------------------
+I have thoughts about a lightweight API for Bastille that would accept (json?)
+payloads of Bastille commands. The API should be lightweight just as Bastille
+is.
+
+The API is scheduled later in the roadmap because I want to have the other
+components stable before we implement an API on top of it. The addition of the
+API should match up with Bastille 1.0-stable.

docs/chapters/installation.rst

@@ -4,7 +4,7 @@ Bastille is available in the official FreeBSD ports tree at
 `sysutils/bastille`. Binary packages available in `quarterly` and `latest`
 repositories.
 
-Current version is `0.5.20191128`.
+Current version is `0.6.20200202`.
 
 To install from the FreeBSD package repository:
 

docs/chapters/jail-config.rst

@@ -13,25 +13,115 @@ template looks like this:
 
 .. code-block:: shell
 
-  interface = {interface};
-  host.hostname = {name};
-  exec.consolelog = /usr/local/bastille/logs/{name}_console.log;
-  path = /usr/local/bastille/jails/{name}/root;
-  ip6 = disable;
-  securelevel = 2;
-  devfs_ruleset = 4;
-  enforce_statfs = 2;
-  exec.start = '/bin/sh /etc/rc';
-  exec.stop = '/bin/sh /etc/rc.shutdown';
-  exec.clean;
-  mount.devfs;
-  mount.fstab = /usr/local/bastille/jails/{name}/fstab;
-  
   {name} {
+    devfs_ruleset = 4;
+    enforce_statfs = 2;
+    exec.clean;
+    exec.consolelog = /usr/local/bastille/logs/{name}_console.log;
+    exec.start = '/bin/sh /etc/rc';
+    exec.stop = '/bin/sh /etc/rc.shutdown';
+    host.hostname = {name};
+    interface = {interface};
+    mount.devfs;
+    mount.fstab = /usr/local/bastille/jails/{name}/fstab;
+    path = /usr/local/bastille/jails/{name}/root;
+    securelevel = 2;
+
     ip4.addr = x.x.x.x;
+    ip6 = disable;
   }
 
 
+devfs_ruleset
+-------------
+.. code-block:: shell
+
+  devfs_ruleset
+    The number of the devfs ruleset that is enforced for mounting
+    devfs in this jail.  A value of zero (default) means no ruleset
+    is enforced.  Descendant jails inherit the parent jail's devfs
+    ruleset enforcement.  Mounting devfs inside a jail is possible
+    only if the allow.mount and allow.mount.devfs permissions are
+    effective and enforce_statfs is set to a value lower than 2.
+    Devfs rules and rulesets cannot be viewed or modified from inside
+    a jail.
+   
+    NOTE: It is important that only appropriate device nodes in devfs
+    be exposed to a jail; access to disk devices in the jail may
+    permit processes in the jail to bypass the jail sandboxing by
+    modifying files outside of the jail.  See devfs(8) for
+    information on how to use devfs rules to limit access to entries
+    in the per-jail devfs.  A simple devfs ruleset for jails is
+    available as ruleset #4 in /etc/defaults/devfs.rules.
+
+
+enforce_statfs
+--------------
+.. code-block:: shell
+
+  enforce_statfs
+    This determines what information processes in a jail are able to
+    get about mount points.  It affects the behaviour of the
+    following syscalls: statfs(2), fstatfs(2), getfsstat(2), and
+    fhstatfs(2) (as well as similar compatibility syscalls).  When
+    set to 0, all mount points are available without any
+    restrictions.  When set to 1, only mount points below the jail's
+    chroot directory are visible.  In addition to that, the path to
+    the jail's chroot directory is removed from the front of their
+    pathnames.  When set to 2 (default), above syscalls can operate
+    only on a mount-point where the jail's chroot directory is
+    located.
+
+
+exec.clean
+----------
+.. code-block:: shell
+
+  exec.clean
+    Run commands in a clean environment.  The environment is
+    discarded except for HOME, SHELL, TERM and USER.  HOME and SHELL
+    are set to the target login's default values.  USER is set to the
+    target login.  TERM is imported from the current environment.
+    The environment variables from the login class capability
+    database for the target login are also set.
+
+
+exec.consolelog
+---------------
+.. code-block:: shell
+
+  exec.consolelog
+    A file to direct command output (stdout and stderr) to.
+
+
+exec.start
+----------
+.. code-block:: shell
+
+  exec.start
+    Command(s) to run in the jail environment when a jail is created.
+    A typical command to run is "sh /etc/rc".
+
+
+exec.stop
+---------
+.. code-block:: shell
+
+  exec.stop
+    Command(s) to run in the jail environment before a jail is
+    removed, and after any exec.prestop commands have completed.  A
+    typical command to run is "sh /etc/rc.shutdown".
+
+
+host.hostname
+-------------
+.. code-block:: shell
+
+  host.hostname
+    The hostname of the jail.  Other similar parameters are
+    host.domainname, host.hostuuid and host.hostid.
+
+
 interface
 ---------
 .. code-block:: shell
@@ -43,28 +133,31 @@ interface
     the interface after the jail is removed.
 
 
-host.hostname
+mount.devfs
--------------
+-----------
 .. code-block:: shell
 
-  host.hostname
+  mount.devfs
-    The hostname of the jail.  Other similar parameters are
+    Mount a devfs(5) filesystem on the chrooted /dev directory, and
-    host.domainname, host.hostuuid and host.hostid.
+    apply the ruleset in the devfs_ruleset parameter (or a default of
+    ruleset 4: devfsrules_jail) to restrict the devices visible
+    inside the jail.
 
 
-exec.consolelog
+mount.fstab
----------------
+-----------
 .. code-block:: shell
 
-  exec.consolelog
+  mount.fstab
-    A file to direct command output (stdout and stderr) to.
+    An fstab(5) format file containing filesystems to mount before
+    creating a jail.
 
 
 path
 ----
 .. code-block:: shell
 
-  path   
+  path
     The directory which is to be the root of the jail.  Any commands
     run inside the jail, either by jail or from jexec(8), are run
     from this directory.
@@ -114,95 +207,3 @@ cases.
         filter rules (see ipfw(8), ipfirewall(4) and pfctl(8)) cannot be
         changed and dummynet(4) or pf(4) configuration cannot be adjusted.
 
-
-devfs_ruleset
--------------
-.. code-block:: shell
-
-  devfs_ruleset
-    The number of the devfs ruleset that is enforced for mounting
-    devfs in this jail.  A value of zero (default) means no ruleset
-    is enforced.  Descendant jails inherit the parent jail's devfs
-    ruleset enforcement.  Mounting devfs inside a jail is possible
-    only if the allow.mount and allow.mount.devfs permissions are
-    effective and enforce_statfs is set to a value lower than 2.
-    Devfs rules and rulesets cannot be viewed or modified from inside
-    a jail.
-   
-    NOTE: It is important that only appropriate device nodes in devfs
-    be exposed to a jail; access to disk devices in the jail may
-    permit processes in the jail to bypass the jail sandboxing by
-    modifying files outside of the jail.  See devfs(8) for
-    information on how to use devfs rules to limit access to entries
-    in the per-jail devfs.  A simple devfs ruleset for jails is
-    available as ruleset #4 in /etc/defaults/devfs.rules.
-
-
-enforce_statfs
---------------
-.. code-block:: shell
-
-  enforce_statfs
-    This determines what information processes in a jail are able to
-    get about mount points.  It affects the behaviour of the
-    following syscalls: statfs(2), fstatfs(2), getfsstat(2), and
-    fhstatfs(2) (as well as similar compatibility syscalls).  When
-    set to 0, all mount points are available without any
-    restrictions.  When set to 1, only mount points below the jail's
-    chroot directory are visible.  In addition to that, the path to
-    the jail's chroot directory is removed from the front of their
-    pathnames.  When set to 2 (default), above syscalls can operate
-    only on a mount-point where the jail's chroot directory is
-    located.
-
-
-exec.start
-----------
-.. code-block:: shell
-
-  exec.start
-    Command(s) to run in the jail environment when a jail is created.
-    A typical command to run is "sh /etc/rc".
-
-
-exec.stop
----------
-.. code-block:: shell
-
-  exec.stop
-    Command(s) to run in the jail environment before a jail is
-    removed, and after any exec.prestop commands have completed.  A
-    typical command to run is "sh /etc/rc.shutdown".
-
-
-exec.clean
-----------
-.. code-block:: shell
-
-  exec.clean
-    Run commands in a clean environment.  The environment is
-    discarded except for HOME, SHELL, TERM and USER.  HOME and SHELL
-    are set to the target login's default values.  USER is set to the
-    target login.  TERM is imported from the current environment.
-    The environment variables from the login class capability
-    database for the target login are also set.
-
-
-mount.devfs
------------
-.. code-block:: shell
-
-  mount.devfs
-    Mount a devfs(5) filesystem on the chrooted /dev directory, and
-    apply the ruleset in the devfs_ruleset parameter (or a default of
-    ruleset 4: devfsrules_jail) to restrict the devices visible
-    inside the jail.
-
-
-mount.fstab
------------
-.. code-block:: shell
-
-  mount.fstab
-    An fstab(5) format file containing filesystems to mount before
-    creating a jail.

docs/conf.py

@@ -8,13 +8,13 @@ else:
 # -- Project information -----------------------------------------------------
 
 project = 'Bastille'
-copyright = '2018-2019, Christer Edwards'
+copyright = '2018-2020, Christer Edwards'
 author = 'Christer Edwards'
 
 # The short X.Y version
-version = '0.5.20191128'
+version = '0.6.20200202'
 # The full version, including alpha/beta/rc tags
-release = '0.5.20191128-beta'
+release = '0.6.20200202-beta'
 
 
 # -- General configuration ---------------------------------------------------