Merge pull request #56 from cedwards/docs_update

updating documentation for 0.4.20191025

docs/chapters/installation.rst

@@ -1,30 +1,27 @@
 Installation
 ============
+Bastille is available in the official FreeBSD ports tree at
+`sysutils/bastille`. Binary packages available in `quarterly` and `latest`
+repositories.
 
-Bastille is not (yet) in the official ports tree, but I have built and
+Current version is `0.3.20191025`.
-verified binary packages.
 
-To install using one of the BETA binary packages, copy the URL for the
+To install from the FreeBSD package repository:
-latest release here (TXZ file):
-https://github.com/bastillebsd/bastille/releases
 
-Then, install via pkg. 
+* quarterly repository may be older version
-Example:
+* latest repository will match recent ports
 
-.. code-block:: shell
 
-  pkg add https://github.com/BastilleBSD/bastille/releases/download/0.3.20181124/bastille-0.3.20181124.txz
+PKG
+---
+```shell
+pkg install bastille
+```
 
-BETA binary packages are signed. These can be verified with this pubkey:
+To install from source (don't worry, no compiling):
 
-.. code-block:: shell
+ports
-
+-----
-  -----BEGIN PUBLIC KEY-----
+```shell
-  MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAq28OLDhJ12JmsKKcJpnn
+make -C /usr/ports/sysutils/bastille install clean
-  pCW3fFYBNI1BtdvTvFx57ZXvQ2qecBvnR9+XWi83hKS9ALTKZI6CLC2uTv1fIsZl
+```
-  u6rDRRNZwZFfITACSfwI+7UObMXz3oBZjk94J3rIegk49EyjDswKdVWv5k1EiVXF
-  SAwXSl2kA2hGfQJkj5NS4nrfoRBc0z6fm+BGdNuHKSTmeZh1dbLEHt9EArD20DJ7
-  HIr8vUSPLwONeqJCBFA/MeDO+GpwtwA/ldc2ZZy1RCPctdC2NeiGW7oy1yVDu6wp
-  mHCq8qDfmCx5Aex84rWUf9iH8TM92AWmegTaz2p+BgESctpjNRCUuSEwOCBIO6g5
-  3wIDAQAB
-  -----END PUBLIC KEY-----

docs/chapters/jail-config.rst

@@ -0,0 +1,208 @@
+Note: FreeBSD introduced container technology twenty years ago, long before the
+industry standardized on the term "container". Internally, FreeBSD refers to
+these containers as "jails".
+
+jail.conf
+=========
+In this section we'll look at the default config for a new container. The
+defaults are sane for most applications, but if you want to tweak the settings
+here they are.
+
+A `jail.conf` template is used each time a new container is created. This
+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} {
+    ip4.addr = x.x.x.x;
+  }
+
+
+interface
+---------
+.. code-block:: shell
+
+  interface
+    A network interface to add the jail's IP addresses (ip4.addr and
+    ip6.addr) to.  An alias for each address will be added to the
+    interface before the jail is created, and will be removed from
+    the interface after the jail is removed.
+
+
+host.hostname
+-------------
+.. code-block:: shell
+
+  host.hostname
+    The hostname of the jail.  Other similar parameters are
+    host.domainname, host.hostuuid and host.hostid.
+
+
+exec.consolelog
+---------------
+.. code-block:: shell
+
+  exec.consolelog
+    A file to direct command output (stdout and stderr) to.
+
+
+path
+----
+.. code-block:: shell
+
+  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.
+
+
+securelevel
+-----------
+By default, Bastille containers run at `securelevel = 2;`. See below for the
+implications of kernel security levels and when they might be altered.
+
+Note: Bastille does not currently have any mechanism to automagically change
+securelevel settings. My recommendation is this only be altered manually on a
+case-by-case basis and that "Highly secure mode" is a sane default for most use
+cases.
+
+.. code-block:: shell
+
+  The kernel runs with five different security levels.  Any super-user
+  process can raise the level, but no process can lower it.  The security
+  levels are:
+   
+  -1    Permanently insecure mode - always run the system in insecure mode.
+        This is the default initial value.
+   
+  0     Insecure mode - immutable and append-only flags may be turned off.
+        All devices may be read or written subject to their permissions.
+   
+  1     Secure mode - the system immutable and system append-only flags may
+        not be turned off; disks for mounted file systems, /dev/mem and
+        /dev/kmem may not be opened for writing; /dev/io (if your platform
+        has it) may not be opened at all; kernel modules (see kld(4)) may
+        not be loaded or unloaded.  The kernel debugger may not be entered
+        using the debug.kdb.enter sysctl.  A panic or trap cannot be forced
+        using the debug.kdb.panic and other sysctl's.
+   
+  2     Highly secure mode - same as secure mode, plus disks may not be
+        opened for writing (except by mount(2)) whether mounted or not.
+        This level precludes tampering with file systems by unmounting
+        them, but also inhibits running newfs(8) while the system is multi-
+        user.
+   
+        In addition, kernel time changes are restricted to less than or
+        equal to one second.  Attempts to change the time by more than this
+        will log the message "Time adjustment clamped to +1 second".
+   
+  3     Network secure mode - same as highly secure mode, plus IP packet
+        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/chapters/networking.rst

@@ -1,71 +1,134 @@
-====================
 Network Requirements
 ====================
+Here's the scenario. You've installed Bastille at home or in the cloud and want
+to get started putting applications in secure little containers, but how do I
+get these containers on the network?
 
-In order to segregate jails from the network and from the world, Bastille
+Bastille tries to be flexible about how to network containerized applications.
-attaches jails to a loopback interface only. The host system then acts as
+The two most common methods are described here. Consider both options to decide
-the firewall, permitting and denying traffic as needed.
+which design work best for your needs. One of the methods works better across
+clouds while the other is simpler if used in local area networks.
+
+As you've probably seen, Bastille containers require certain information when
+they are created. An IP address has to be assigned to the container through
+which all network traffic will flow.
+
+When the container is started the IP address assigned at creation will be bound
+to a network interface. In FreeBSD these interfaces have different names, but
+look something like `em0`, `bge0`, `re0`, etc. On a virtual machine it may be
+`vtnet0`. You get the idea...
+
+**Note: if you are running in the cloud and only have a single public IP you
+may want the Public Network option. See below.**
+
+
+Local Area Network
+------------------
+I will cover the local area network (LAN) method first. This method is simpler
+to get going and works well in a home network (or similar) where adding alias
+IP addresses is no problem.
+
+Bastille allows you to define the interface you want the IP attached to when
+you create it. An example:
+
+```shell
+bastille create alcatraz 12.1-RELEASE 192.168.1.50 em0
+```
+
+When the `alcatraz` container is started it will add `192.168.1.60` as an IP
+alias to the `em0` interface. It will then simply be another member of the
+hosts network. Other networked systems (firewall permitting) should be able to
+reach services at that address.
+
+This method is the simplest. All you need to know is the name of your network
+interface and a free IP on your current network.
+
+(Bastille does try to verify that the interface name you provide it is a valid
+interface. This validation has not been exhaustively tested yet in Bastille's
+beta state.)
+
+
+Public Network
+--------------
+In this section I'll describe how to network containers in a public network
+such as a cloud hosting provider (AWS, digital ocean, vultr, etc)
+
+In the public cloud you don't often have access to multiple private IP
+addresses for your virtual machines. This means if you want to create multiple
+containers and assign them all IP addresses, you'll need to create a new
+network.
+
+What I recommend is creating a cloned loopback interface (`bastille0`) and
+assigning all the containers private (rfc1918) addresses on that interface. The
+setup I develop on and use Bastille day to day uses the `10.0.0.0/8` address
+range. I have the ability to use whatever address I want within that range
+because I've created my own private network. The host system then acts as the
+firewall, permitting and denying traffic as needed.
+
+I find this setup the most flexible across all types of networks. It can be
+used in public and private networks just the same and it allows me to keep
+containers off the network until I allow access.
+
+Having said all that here are instructions I used to configure the network with
+a private loopback interface and system firewall. The system firewall NATs
+traffic out of containers and can selectively redirect traffic into containers
+based on connection ports (ie; 80, 443, etc.)
 
 First, create the loopback interface:
 
 .. code-block:: shell
 
   ishmael ~ # sysrc cloned_interfaces+=lo1
+  ishmael ~ # ifconfig_lo1_name="bastille0"
   ishmael ~ # service netif cloneup
 
-Second, enable NAT through the firewall:
+Second, enable the firewall:
 
 .. code-block:: shell
 
   ishmael ~ # sysrc pf_enable="YES"
 
+Create the firewall rules:
+
 /etc/pf.conf
 ------------
-
-Create the firewall config, or merge as necessary.
-
 .. code-block:: shell
 
   ext_if="vtnet0"
   
-  set block-policy drop
+  set block-policy return
   scrub in on $ext_if all fragment reassemble
   
   set skip on lo
-  nat on $ext_if from !($ext_if) -> ($ext_if:0)
+  nat on $ext_if from bastille0:network to any -> ($ext_if)
   
   ## rdr example
-  ## rdr pass inet proto tcp from any to any port {80, 443} -> 10.88.9.45
+  ## rdr pass inet proto tcp from any to any port {80, 443} -> 10.17.89.45
   
-  block in log all
+  block in all
   pass out quick modulate state
   antispoof for $ext_if inet
-  pass in inet proto tcp from any to any port ssh flags S/SA keep state
+  pass in inet proto tcp from any to any port ssh flags S/SA modulate state
-
 
 - Make sure to change the `ext_if` variable to match your host system interface.
 - Make sure to include the last line (`port ssh`) or you'll end up locked out.
 
-
 Note: if you have an existing firewall, the key lines for in/out traffic
-to jails are:
+to containers are:
 
 .. code-block:: shell
 
-  nat on $ext_if from lo1:network to any -> ($ext_if)
+  nat on $ext_if from bastille0:network to any -> ($ext_if)
   
   ## rdr example
-  ## rdr pass inet proto tcp from any to any port {80, 443} -> 10.88.9.45
+  ## rdr pass inet proto tcp from any to any port {80, 443} -> 10.17.89.45
 
 The `nat` routes traffic from the loopback interface to the external
 interface for outbound access.
 
-The `rdr pass ...` will redirect traffic from the host firewall on port X
+The `rdr pass ...` will redirect traffic from the host firewall on port X to
-to the ip of Jail Y. The example shown redirects web traffic (80 & 443) to
+the ip of Container Y. The example shown redirects web traffic (80 & 443) to the
-the jails at `10.88.9.45`.
+containers at `10.17.89.45`.
-
-We'll get to that later, but when you're ready to allow traffic inbound to
-your jails, that's where you'd do it.
 
 Finally, start up the firewall:
 

docs/chapters/subcommands/bootstrap.rst

@@ -1,34 +1,100 @@
-=========
 bootstrap
 =========
 
-The first step is to "bootstrap" a release. Current supported release is
+The bootstrap sub-command is used to download and extract releases and
-11.2-RELEASE, but you can bootstrap anything in the ftp.FreeBSD.org
+templates for use with Bastille containers. A valid release is needed before
-RELEASES directory. 
+containers can be created. Templates are optional but are managed in the same
+manner.
 
 Note: your mileage may vary with unsupported releases and releases newer
-than the host system likely will NOT work at all.
+than the host system likely will NOT work at all. Bastille tries to filter for
+valid release names. If you find it will not bootstrap a valid release, please
+let us know.
+
+In this document we will describe using the `bootstrap` sub-command with both
+releases and templates. We begin with releases.
+
+
+Releases
+========
+
+Example
+-------
 
 To `bootstrap` a release, run the bootstrap sub-command with the
 release version as the argument.
 
 .. code-block:: shell
     
-  ishmael ~ # bastille bootstrap 11.2-RELEASE
+  ishmael ~ # bastille bootstrap 11.3-RELEASE [update]
   ishmael ~ # bastille bootstrap 12.0-RELEASE
+  ishmael ~ # bastille bootstrap 12.1-RELEASE
 
-This command will ensure the required directory structures are in place
+This command will ensure the required directory structures are in place and
-and download the requested release. For each requested release,
+download the requested release. For each requested release, `bootstrap` will
-`bootstrap` will download the base.txz and lib32.txz. These are both
+download the base.txz. These files are verified (sha256 via MANIFEST file)
-verified (sha256 via MANIFEST file) before they are extracted for use.
+before they are extracted for use.
 
-Downloaded artifacts are stored in the `cache` directory. "bootstrapped"
+Tips
-releases are stored in `releases/version`.
+----
 
-The bootstrap subcommand is generally only used once to prepare the
+The `bootstrap` sub-command can now take (0.5.20191125+) an optional second
-system. The only other use case for the bootstrap command is when a new
+argument of "update". If this argument is used, `bastille update` will be run
-FreeBSD version is released and you want to start building jails on that
+immediately after the bootstrap, effectively bootstrapping and applying
-version.
+security patches and errata in one motion.
 
-To update a release as patches are made available, see the `bastille
+Notes
-update` command.
+-----
+
+The bootstrap subcommand is generally only used once to prepare the system. The
+only other use case for the bootstrap command is when a new FreeBSD version is
+released and you want to start deploying containers on that version.
+
+To update a release as patches are made available, see the `bastille update`
+command.
+
+Downloaded artifacts are stored in the `bastille/cache/version` directory.
+"bootstrapped" releases are stored in `bastille/releases/version`.
+
+To manually bootstrap a release (aka bring your own archive), place your
+archive in bastille/cache/name and extract to bastille/releases/name. Your
+mileage may vary; let me know what happens.
+
+
+Templates
+=========
+
+Bastille aims to integrate container automation into the platform while
+maintaining a simple, uncomplicated design. Templates are git repositories with
+automation definitions for packages, services, file overlays, etc.
+
+To download one of these templates see the example below.
+
+Example
+-------
+
+.. code-block:: shell
+
+  ishmael ~ # bastille bootstrap https://gitlab.com/bastillebsd-templates/nginx
+  ishmael ~ # bastille bootstrap https://gitlab.com/bastillebsd-templates/mariadb-server
+  ishmael ~ # bastille bootstrap https://gitlab.com/bastillebsd-templates/python3
+
+Tips
+----
+See the documentation on templates for more information on how they work and
+how you can create or customize your own. Templates are a powerful part of
+Bastille and facilitate full container automation.
+
+Notes
+-----
+If you don't want to bother with git to use templates you can create them
+manually on the Bastille system and apply them.
+
+Templates are stored in `bastille/templates/namespace/name`. If you'd like to
+create a new template on your local system, simply create a new namespace
+within the templates directory and then one for the template. This namespacing
+allows users and groups to have templates without conflicting template names.
+
+Once you've created the directory structure you can begin filling it with
+template hooks. Once you have a minimum number of hooks (at least one) you can
+begin applying your template.

docs/chapters/subcommands/cmd.rst

@@ -2,7 +2,7 @@
 cmd
 ===
 
-To execute commands within the jail you can use `bastille cmd`.
+To execute commands within the container you can use `bastille cmd`.
 
 .. code-block:: shell
 

docs/chapters/subcommands/console.rst

@@ -1,14 +1,14 @@
 console
 =======
 
-This sub-command launches a login shell into the jail. Default is
+This sub-command launches a login shell into the container. Default is password-less
-password-less root login.
+root login.
 
 .. code-block:: shell
 
   ishmael ~ # bastille console folsom
   [folsom]:
-  FreeBSD 11.2-RELEASE-p4 (GENERIC) #0: Thu Sep 27 08:16:24 UTC 2018
+  FreeBSD 12.1-RELEASE-p1 GENERIC
   
   Welcome to FreeBSD!
   
@@ -31,6 +31,6 @@ password-less root login.
   Edit /etc/motd to change this login announcement.
   root@folsom:~ #
 
-At this point you are logged in to the jail and have full shell access.
+At this point you are logged in to the container and have full shell access.  The
-The system is yours to use and/or abuse as you like. Any changes made
+system is yours to use and/or abuse as you like. Any changes made inside the
-inside the jail are limited to the jail. 
+container are limited to the container.

docs/chapters/subcommands/cp.rst

@@ -1,7 +1,7 @@
 cp
 ==
 
-This command allows efficiently copying files from host to jail(s).
+This command allows efficiently copying files from host to container(s).
 
 .. code-block:: shell
 

docs/chapters/subcommands/create.rst

@@ -1,32 +1,32 @@
-======
 create
 ======
 
 Bastille create uses any available bootstrapped release to create a
-lightweight jailed system. To create a jail simply provide a name,
+lightweight container system. To create a container simply provide a name,
 bootstrapped release and a private (rfc1918) IP address.
 
 - name
 - release
 - ip
+- interface (optional)
 
 .. code-block:: shell
 
-  ishmael ~ # bastille create folsom 11.2-RELEASE 10.8.62.1
+  ishmael ~ # bastille create folsom 11.3-RELEASE 10.17.89.10 [interface]
   
-  RELEASE: 11.2-RELEASE.
+  RELEASE: 11.3-RELEASE.
   NAME: folsom.
-  IP: 10.8.62.1.
+  IP: 10.17.89.10.
 
-This command will create a 11.2-RELEASE jail assigning the 10.8.62.1 ip
+This command will create a 11.3-RELEASE container assigning the 10.17.89.10 ip
 address to the new system.
 
-I recommend using private (rfc1918) ip address ranges for your jails.
+I recommend using private (rfc1918) ip address ranges for your container.  These
-These ranges include:
+ranges include:
 
 - 10.0.0.0/8
 - 172.16.0.0/12
 - 192.168.0.0/16
 
-Bastille does its best to validate the submitted ip is valid. This has not
+Bastille does its best to validate the submitted ip is valid. This has not been
-been thouroughly tested--I generally use the 10/8 range.
+thouroughly tested--I generally use the 10/8 range.

docs/chapters/subcommands/destroy.rst

@@ -1,8 +1,8 @@
 destroy
 =======
 
-Jails can be destroyed and thrown away just as easily as they were
+Containers can be destroyed and thrown away just as easily as they were
-created.  Note: jails must be stopped before destroyed.
+created.  Note: containers must be stopped before destroyed.
 
 .. code-block:: shell
 
@@ -13,6 +13,6 @@ created.  Note: jails must be stopped before destroyed.
 .. code-block:: shell
 
   ishmael ~ # bastille destroy folsom
-  Deleting Jail: folsom.
+  Deleting Container: folsom.
-  Note: jail console logs not destroyed.
+  Note: containers console logs not destroyed.
   /usr/local/bastille/logs/folsom_console.log

docs/chapters/subcommands/htop.rst

@@ -2,10 +2,10 @@
 htop
 ====
 
-This one runs `htop` inside the jail. 
+This one runs `htop` inside the container. 
-note: won't work if you don't have htop installed in the jail.
+note: won't work if you don't have htop installed in the container.
 
 
 .. image:: ../../images/htop.png
     :align: center
-    :alt: bastille htop jail
+    :alt: bastille htop container

docs/chapters/subcommands/index.rst

@@ -14,6 +14,7 @@ Bastille sub-commands
    htop
    pkg
    restart
+   service
    start
    stop
    sysrc

docs/chapters/subcommands/pkg.rst

@@ -2,7 +2,7 @@
 pkg
 ===
 
-To manage binary packages within the jail use `bastille pkg`.
+To manage binary packages within the container use `bastille pkg`.
 
 .. code-block:: shell
 
@@ -87,11 +87,11 @@ expectation is that you can fully leverage the pkg manager. This means,
 
   ishmael ~ # bastille pkg ALL upgrade
   [bastion]:
-  Updating iniquity.io repository catalogue...
+  Updating pkg.bastillebsd.org repository catalogue...
   [bastion] Fetching meta.txz: 100%    560 B   0.6kB/s    00:01
   [bastion] Fetching packagesite.txz: 100%  118 KiB 121.3kB/s    00:01
   Processing entries: 100%
-  iniquity.io repository update completed. 493 packages processed.
+  pkg.bastillebsd.org repository update completed. 493 packages processed.
   All repositories are up to date.
   Checking for upgrades (1 candidates): 100%
   Processing candidates (1 candidates): 100%
@@ -99,11 +99,11 @@ expectation is that you can fully leverage the pkg manager. This means,
   Your packages are up to date.
   
   [unbound0]:
-  Updating iniquity.io repository catalogue...
+  Updating pkg.bastillebsd.org repository catalogue...
   [unbound0] Fetching meta.txz: 100%    560 B   0.6kB/s    00:01
   [unbound0] Fetching packagesite.txz: 100%  118 KiB 121.3kB/s    00:01
   Processing entries: 100%
-  iniquity.io repository update completed. 493 packages processed.
+  pkg.bastillebsd.org repository update completed. 493 packages processed.
   All repositories are up to date.
   Checking for upgrades (0 candidates): 100%
   Processing candidates (0 candidates): 100%
@@ -111,11 +111,11 @@ expectation is that you can fully leverage the pkg manager. This means,
   Your packages are up to date.
   
   [unbound1]:
-  Updating iniquity.io repository catalogue...
+  Updating pkg.bastillebsd.org repository catalogue...
   [unbound1] Fetching meta.txz: 100%    560 B   0.6kB/s    00:01
   [unbound1] Fetching packagesite.txz: 100%  118 KiB 121.3kB/s    00:01
   Processing entries: 100%
-  iniquity.io repository update completed. 493 packages processed.
+  pkg.bastillebsd.org repository update completed. 493 packages processed.
   All repositories are up to date.
   Checking for upgrades (0 candidates): 100%
   Processing candidates (0 candidates): 100%
@@ -123,11 +123,11 @@ expectation is that you can fully leverage the pkg manager. This means,
   Your packages are up to date.
   
   [squid]:
-  Updating iniquity.io repository catalogue...
+  Updating pkg.bastillebsd.org repository catalogue...
   [squid] Fetching meta.txz: 100%    560 B   0.6kB/s    00:01
   [squid] Fetching packagesite.txz: 100%  118 KiB 121.3kB/s    00:01
   Processing entries: 100%
-  iniquity.io repository update completed. 493 packages processed.
+  pkg.bastillebsd.org repository update completed. 493 packages processed.
   All repositories are up to date.
   Checking for upgrades (0 candidates): 100%
   Processing candidates (0 candidates): 100%
@@ -135,11 +135,11 @@ expectation is that you can fully leverage the pkg manager. This means,
   Your packages are up to date.
   
   [nginx]:
-  Updating iniquity.io repository catalogue...
+  Updating pkg.bastillebsd.org repository catalogue...
   [nginx] Fetching meta.txz: 100%    560 B   0.6kB/s    00:01
   [nginx] Fetching packagesite.txz: 100%  118 KiB 121.3kB/s    00:01
   Processing entries: 100%
-  iniquity.io repository update completed. 493 packages processed.
+  pkg.bastillebsd.org repository update completed. 493 packages processed.
   All repositories are up to date.
   Checking for upgrades (1 candidates): 100%
   Processing candidates (1 candidates): 100%

docs/chapters/subcommands/restart.rst

@@ -1,7 +1,7 @@
 restart
 =======
 
-To restart a jail you can use the `bastille restart` command.
+To restart a container you can use the `bastille restart` command.
 
 .. code-block:: shell
 

docs/chapters/subcommands/service.rst

@@ -0,0 +1,13 @@
+=======
+service
+=======
+
+The `service` sub-command allows for managing services within containers. This
+allows you to start, stop, restart, and otherwise interact with services
+running inside the containers.
+
+.. code-block:: shell
+
+  ishmael ~ # bastille service web01 'nginx start'
+  ishmael ~ # bastille service db01 'mysql-server restart'
+  ishmael ~ # bastille service proxy 'nginx configtest'

docs/chapters/subcommands/start.rst

@@ -1,7 +1,7 @@
 start
 =====
 
-To start a jail you can use the `bastille start` command.
+To start a container you can use the `bastille start` command.
 
 .. code-block:: shell
 

docs/chapters/subcommands/stop.rst

@@ -1,7 +1,7 @@
 stop
 ====
 
-To stop a jail you can use the `bastille stop` command.
+To stop a container you can use the `bastille stop` command.
 
 .. code-block:: shell
 

docs/chapters/subcommands/sysrc.rst

@@ -3,7 +3,7 @@ sysrc
 =====
 
 The `sysrc` sub-command allows for safely editing system configuration files.
-In jail terms, this allows us to toggle on/off services and options at startup.
+In container terms, this allows us to toggle on/off services and options at startup.
 
 .. code-block:: shell
 

docs/chapters/subcommands/top.rst

@@ -2,9 +2,9 @@
 top
 ===
 
-This one runs `top` in that jail. 
+This one runs `top` in that container. 
 
 
 .. image:: ../../images/top.png
     :align: center
-    :alt: bastille top jail
+    :alt: bastille top container

docs/chapters/subcommands/update.rst

@@ -2,8 +2,8 @@
 update
 ======
 
-The `update` command targets a release instead of a jail. Because every jail is
+The `update` command targets a release instead of a container. Because every container is
-based on a release, when the release is updated all the jails are automatically
+based on a release, when the release is updated all the containers are automatically
 updated as well.
 
 If no updates are available, a message will be shown:
@@ -38,4 +38,4 @@ The older the release, however, the more updates will be available:
   The following files will be added as part of updating to 10.4-RELEASE-p13:
   ...[snip]...
 
-To be safe, you may want to restart any jails that have been updated live.
+To be safe, you may want to restart any containers that have been updated live.

docs/chapters/targeting.rst

@@ -1,50 +1,48 @@
-=========
 Targeting
 =========
 
 Bastille uses a `command-target-args` syntax, meaning that each command
-requires a target. Targets are usually jails, but can also be releases.
+requires a target. Targets are usually containers, but can also be releases.
 
-Targeting a jail is done by providing the exact jail name.
+Targeting a containers is done by providing the exact containers name.
 
 Targeting a release is done by providing the release name. (Note: do note
 include the `-pX` point-release version.)
 
-Bastille includes a pre-defined keyword ALL to target all running jails.
+Bastille includes a pre-defined keyword ALL to target all running containers.
 
 In the future I would like to support more options, including globbing, lists
 and regular-expressions.
 
-Examples: Jails
+Examples: Containers
-===============
+====================
 
 .. code-block:: shell
 
   ishmael ~ # bastille ...
 
-
 +-----------+--------+------------------+-------------------------------------------------------------+
 | command   | target | args             | description                                                 |
 +===========+========+==================+=============================================================+
-| cmd       | ALL    | 'sockstat -4'    | execute `sockstat -4` in ALL jails (listening ip4 sockets)  |
+| cmd       | ALL    | 'sockstat -4'    | execute `sockstat -4` in ALL containers (ip4 sockets)       |
 +-----------+--------+-----+------------+-------------------------------------------------------------+ 
 | console   | mariadb02    | ---        | console (shell) access to mariadb02                         |
 +----+------+----+---------+------------+--------------+----------------------------------------------+ 
-| pkg       | web01  | 'install nginx'  | install nginx package in web01 jail                         |
+| pkg       | web01  | 'install nginx'  | install nginx package in web01 container                    |
 +-----------+--------+------------------+-------------------------------------------------------------+
-| pkg       | ALL    | upgrade          | upgrade packages in ALL jails                               |
+| pkg       | ALL    | upgrade          | upgrade packages in ALL containers                          |
 +-----------+--------+------------------+-------------------------------------------------------------+ 
-| pkg       | ALL    | audit            | (CVE) audit packages in ALL jails                           |
+| pkg       | ALL    | audit            | (CVE) audit packages in ALL containers                      |
 +-----------+--------+------------------+-------------------------------------------------------------+ 
-| sysrc     | web01  | nginx_enable=YES | execute `sysrc nginx_enable=YES` in web01 jail              |
+| sysrc     | web01  | nginx_enable=YES | execute `sysrc nginx_enable=YES` in web01 container         |
 +-----------+--------+------------------+-------------------------------------------------------------+ 
-| template  | ALL    | base             | apply `base` template to ALL jails                          |
+| template  | ALL    | username/base    | apply `username/base` template to ALL containers            |
 +-----------+--------+------------------+-------------------------------------------------------------+ 
-| start     | web02  | ---              | start web02 jail                                            |
+| start     | web02  | ---              | start web02 container                                       |
 +-----------+--------+-----+------------+-------------------------------------------------------------+ 
-| cp | bastion03 | /tmp/resolv.conf-cf etc/resolv.conf | copy host-path to jail-path in bastion03     |
+| cp | bastion03 | /tmp/resolv.conf-cf etc/resolv.conf | copy host-path to container-path in bastion03|
 +----+------+----+---+------------------+--------------+----------------------------------------------+ 
-| create    | folsom | 12.0-RELEASE 10.10.10.10        | create v12.0 jail named `folsom` with IP     |
+| create    | folsom | 12.0-RELEASE 10.17.89.10        | create 12.0 container named `folsom` with IP |
 +-----------+--------+------------------+--------------+----------------------------------------------+
 
 
@@ -55,15 +53,14 @@ Examples: Releases
 
   ishmael ~ # bastille ...
 
-
 +-----------+--------------+--------------+-------------------------------------------------------------+
 | command   | target       | args         | description                                                 |
 +===========+==============+==============+=============================================================+
 | bootstrap | 12.0-RELEASE | ---          | bootstrap 12.0-RELEASE release                              |
 +-----------+--------------+--------------+-------------------------------------------------------------+ 
-| update    | 11.2-RELEASE | ---          | update 11.2-RELEASE release                                 |
+| update    | 11.3-RELEASE | ---          | update 11.2-RELEASE release                                 |
 +-----------+--------------+--------------+-------------------------------------------------------------+ 
-| upgrade   | 11.1-RELEASE | 11.2-RELEASE | update 11.2-RELEASE release                                 |
+| upgrade   | 11.2-RELEASE | 11.3-RELEASE | update 11.2-RELEASE release                                 |
 +-----------+--------------+--------------+-------------------------------------------------------------+ 
-| verify    | 11.2-RELEASE | ---          | update 11.2-RELEASE release                                 |
+| verify    | 11.3-RELEASE | ---          | update 11.2-RELEASE release                                 |
 +-----------+--------------+--------------+-------------------------------------------------------------+ 

docs/chapters/template.rst

@@ -3,26 +3,26 @@ Template
 ========
 
 Bastille supports a templating system allowing you to apply files, pkgs and
-execute commands inside the jail automatically.
+execute commands inside the containers automatically.
 
-Currently supported template hooks are: `PRE`, `CONFIG`, `PKG`, `SYSRC`, `CMD`.
+Currently supported template hooks are: `PRE`, `OVERLAY`, `PKG`, `SYSRC`, `CMD`.
-Planned template hooks include: `FSTAB`, `PF`
+Planned template hooks include: `FSTAB`, `PF`, `LOG`.
 
 Templates are created in `${bastille_prefix}/templates` and can leverage any of
 the template hooks. Simply create a new directory named after the template. eg;
 
 .. code-block:: shell
 
-  mkdir -p /usr/local/bastille/templates/base
+  mkdir -p /usr/local/bastille/templates/username/base
 
 To leverage a template hook, create an UPPERCASE file in the root of the
 template directory named after the hook you want to execute. eg;
 
 .. code-block:: shell
 
-  echo "zsh vim-console git-lite htop" > /usr/local/bastille/templates/base/PKG
+  echo "zsh vim-console git-lite htop" > /usr/local/bastille/templates/username/base/PKG
-  echo "/usr/bin/chsh -s /usr/local/bin/zsh" > /usr/local/bastille/templates/base/CMD
+  echo "/usr/bin/chsh -s /usr/local/bin/zsh" > /usr/local/bastille/templates/username/base/CMD
-  echo "etc root usr" > /usr/local/bastille/templates/base/CONFIG
+  echo "etc\nrootjn usr" > /usr/local/bastille/templates/username/base/OVERLAY
 
 Template hooks are executed in specific order and require specific syntax to
 work as expected. This table outlines those requirements:
@@ -31,46 +31,52 @@ work as expected. This table outlines those requirements:
 +---------+------------------+--------------------------------------+
 | HOOK    | format           | example                              |
 +=========+==================+======================================+
-| PRE/CMD | /bin/sh command  | /usr/bin/chsh -s /usr/local/bin/zsh  |
+| PRE     | /bin/sh command  | mkdir -p /usr/local/my_app/html      |
 +---------+------------------+--------------------------------------+
-| CONFIG  | path             | etc root usr                         |
+| OVERLAY | path(s)          | etc root usr (one per line)          |
 +---------+------------------+--------------------------------------+
 | PKG     | port/pkg name(s) | vim-console zsh git-lite tree htop   |
 +---------+------------------+--------------------------------------+
 | SYSRC   | sysrc command(s) | nginx_enable=YES                     |
 +---------+------------------+--------------------------------------+
+| SERVICE | service command  | 'nginx start' OR 'postfix reload'    |
++---------+------------------+--------------------------------------+
+| CMD     | /bin/sh command  | /usr/bin/chsh -s /usr/local/bin/zsh  |
++---------+------------------+--------------------------------------+
 
-Note: SYSRC requires NO quotes or that quotes (`"`) be escaped. ie; `\"`)
+Note: SYSRC requires that NO quotes be used or that quotes (`"`) be escaped.
+ie; `\"`)
 
 In addition to supporting template hooks, Bastille supports overlaying
-files into the jail. This is done by placing the files in their full path,
+files into the container. This is done by placing the files in their full path,
 using the template directory as "/".
 
-An example here may help. Think of `/usr/local/bastille/templates/base`,
+An example here may help. Think of `bastille/templates/username/base`, our
-our example template, as the root of our filesystem overlay. If you create
+example template, as the root of our filesystem overlay. If you create an
-an `etc/hosts` or `etc/resolv.conf` *inside* the base template directory,
+`etc/hosts` or `etc/resolv.conf` *inside* the base template directory, these
-these can be overlayed into your jail.
+can be overlayed into your container.
 
 Note: due to the way FreeBSD segregates user-space, the majority of your
 overlayed template files will be in `usr/local`. The few general
 exceptions are the `etc/hosts`, `etc/resolv.conf`, and
 `etc/rc.conf.local`.
 
-After populating `usr/local/` with custom config files that your jail will
+After populating `usr/local/` with custom config files that your container will
-use, be sure to include `usr` in the template CONFIG definition. eg;
+use, be sure to include `usr` in the template OVERLAY definition. eg;
 
 .. code-block:: shell
 
-  echo "etc usr" > /usr/local/bastille/templates/base/CONFIG
+  echo "etc\nusr" > /usr/local/bastille/templates/username/base/OVERLAY
 
 The above example "etc usr" will include anything under "etc" and "usr"
 inside the template. You do not need to list individual files. Just
-include the top-level directory name.
+include the top-level directory name. List these top-level directories one per
+line.
 
 Applying Templates
 ------------------
 
-Jails must be running to apply templates.
+Containers must be running to apply templates.
 
 Bastille includes a `template` command. This command requires a target and a
 template name. As covered in the previous section, template names correspond to
@@ -78,19 +84,19 @@ directory names in the `bastille/templates` directory.
 
 .. code-block:: shell
 
-  ishmael ~ # bastille template ALL base
+  ishmael ~ # bastille template ALL username/base
-  [cdn]:
+  [proxy01]:
   Copying files...
   Copy complete.
   Installing packages.
   pkg already bootstrapped at /usr/local/sbin/pkg
   vulnxml file up-to-date
   0 problem(s) in the installed packages found.
-  Updating iniquity.io repository catalogue...
+  Updating bastillebsd.org repository catalogue...
   [cdn] Fetching meta.txz: 100%    560 B   0.6kB/s    00:01
   [cdn] Fetching packagesite.txz: 100%  121 KiB 124.3kB/s    00:01
   Processing entries: 100%
-  iniquity.io repository update completed. 499 packages processed.
+  bastillebsd.org repository update completed. 499 packages processed.
   All repositories are up to date.
   Checking integrity... done (0 conflicting)
   The most recent version of packages are already installed
@@ -102,23 +108,23 @@ directory names in the `bastille/templates` directory.
   chsh: user information updated
   Template Complete.
   
-  [poudriere]:
+  [web01]:
   Copying files...
   Copy complete.
   Installing packages.
   pkg already bootstrapped at /usr/local/sbin/pkg
   vulnxml file up-to-date
   0 problem(s) in the installed packages found.
-  Updating cdn.iniquity.io repository catalogue...
+  Updating pkg.bastillebsd.org repository catalogue...
   [poudriere] Fetching meta.txz: 100%    560 B   0.6kB/s    00:01
   [poudriere] Fetching packagesite.txz: 100%  121 KiB 124.3kB/s    00:01
   Processing entries: 100%
-  cdn.iniquity.io repository update completed. 499 packages processed.
+  pkg.bastillebsd.org repository update completed. 499 packages processed.
-  Updating iniquity.io repository catalogue...
+  Updating bastillebsd.org repository catalogue...
   [poudriere] Fetching meta.txz: 100%    560 B   0.6kB/s    00:01
   [poudriere] Fetching packagesite.txz: 100%  121 KiB 124.3kB/s    00:01
   Processing entries: 100%
-  iniquity.io repository update completed. 499 packages processed.
+  bastillebsd.org repository update completed. 499 packages processed.
   All repositories are up to date.
   Checking integrity... done (0 conflicting)
   The most recent version of packages are already installed

docs/chapters/usage.rst

@@ -1,32 +1,37 @@
-=====
 Usage
 =====
 
 .. code-block:: shell
 
     ishmael ~ # bastille -h
+    Bastille is an open-source system for automating deployment and management of
+    containerized applications on FreeBSD.
+    
     Usage:
       bastille command [ALL|glob] [args]
     
     Available Commands:
-      bootstrap   Bootstrap a FreeBSD release for jail base.
+      bootstrap   Bootstrap a FreeBSD release for container base.
-      cmd         Execute arbitrary command on targeted jail(s).
+      cmd         Execute arbitrary command on targeted container(s).
-      console     Console into a running jail.
+      console     Console into a running container.
-      cp          cp(1) files from host to targeted jail(s).
+      cp          cp(1) files from host to targeted container(s).
-      create      Create a new jail.
+      create      Create a new thin container or a thick container if -T|--thick option specified.
-      destroy     Destroy a stopped jail.
+      destroy     Destroy a stopped container or a FreeBSD release.
       help        Help about any command
       htop        Interactive process viewer (requires htop).
-      list        List jails (running and stopped).
+      list        List containers, releases, templates, or logs.
-      pkg         Manipulate binary packages within targeted jail(s). See pkg(8).
+      pkg         Manipulate binary packages within targeted container(s). See pkg(8).
-      restart     Restart a running jail.
+      restart     Restart a running container.
-      start       Start a stopped jail.
+      service     Manage services within targeted containers(s).
-      stop        Stop a running jail.
+      start       Start a stopped container.
-      sysrc       Safely edit rc files within targeted jail(s).
+      stop        Stop a running container.
-      template    Apply Bastille template to running jail(s).
+      sysrc       Safely edit rc files within targeted container(s).
+      template    Apply file templates to targeted container(s).
       top         Display and update information about the top(1) cpu processes.
-      update      Update jail base -pX release.
+      update      Update container base -pX release.
-      upgrade     Upgrade jail release to X.Y-RELEASE.
+      upgrade     Upgrade container release to X.Y-RELEASE.
+      verify      Compare release against a "known good" index.
+      zfs         Manage (get|set) zfs attributes on targeted container(s).
     
     Use "bastille -v|--version" for version information.
     Use "bastille command -h|--help" for more information about a command.

docs/conf.py

@@ -12,9 +12,9 @@ copyright = '2018-2019, Christer Edwards'
 author = 'Christer Edwards'
 
 # The short X.Y version
-version = '0.3.20181124'
+version = '0.4.20191025'
 # The full version, including alpha/beta/rc tags
-release = '0.3.20181124-beta'
+release = '0.4.20191025-beta'
 
 
 # -- General configuration ---------------------------------------------------
@@ -67,7 +67,7 @@ man_pages = [
 
 texinfo_documents = [
     (master_doc, 'Bastille', 'Bastille Documentation',
-     author, 'Bastille', 'Bastille is a jail automation framework that allows you to quickly and easily create and manage FreeBSD jails.',
+     author, 'Bastille', 'Bastille is an open-source system for automating deployment and management of containerized applications on FreeBSD.',
      'Miscellaneous'),
 ]
 

docs/index.rst

@@ -17,6 +17,7 @@ https://docs.bastillebsd.org.
    chapters/targeting
    chapters/subcommands/index
    chapters/template
+   chapters/jail-config
 
    copyright