Merge pull request #223 from cedwards/docs_update-20200714

update docs for 0.7.20200714 release

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.6.20200202`.
+Current version is `0.7.20200714`.
 
 To install from the FreeBSD package repository:
 

docs/chapters/jail-config.rst

@@ -17,7 +17,7 @@ template looks like this:
     devfs_ruleset = 4;
     enforce_statfs = 2;
     exec.clean;
-    exec.consolelog = /usr/local/bastille/logs/{name}_console.log;
+    exec.consolelog = /var/log/bastille/{name}_console.log;
     exec.start = '/bin/sh /etc/rc';
     exec.stop = '/bin/sh /etc/rc.shutdown';
     host.hostname = {name};

docs/chapters/networking.rst

@@ -5,29 +5,26 @@ to get started putting applications in secure little containers, but how do I
 get these containers on the network?
 
 Bastille tries to be flexible about how to network containerized applications.
-The two most common methods are described here. Consider both options to decide
-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...
+Three methods are described here. Consider each options when deciding
+which design work best for your needs. One of the methods works better in the 
+cloud while the others are simpler if used in local area networks.
 
 **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.
 
+Shared Interface (IP alias)
+---------------------------
+In FreeBSD network interfaces have different names, but look something like
+`em0`, `bge0`, `re0`, etc. On a virtual machine it may be `vtnet0`. You get the
+idea...
+
 Bastille allows you to define the interface you want the IP attached to when
 you create it. An example:
 
@@ -43,13 +40,59 @@ 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.)
+Bastille tries to verify that the interface name you provide it is a valid
+interface. It also checks for a valid syntax IP4 or IP6 address.
+
+Virtual Network (VNET)
+----------------------
+(Added in 0.6.x) VNET is supported on FreeBSD 12+ only.
+
+Virtual Network (VNET) creates a private network interface for a container.
+This includes a unique hardware address. This is required for VPN, DHCP, and
+similar containers.
+
+To create a VNET based container use the `-V` option, an IP/netmask and
+external interface.
+
+.. code-block:: shell
+
+  bastille create -V azkaban 12.1-RELEASE 192.168.1.50/24 em0
+
+Bastille will automagically create the bridge interface and connect /
+disconnect containers as they are started and stopped. A new interface will be
+created on the host matching the pattern `interface0bridge`. In the example
+here, `em0bridge`. 
+
+The `em0` interface will be attached to the bridge along with the unique
+container interfaces as they are started and stopped. These interface names
+match the pattern `eXb_bastilleX`. Internally to the containers these
+interfaces are presented as `vnet0`.
+
+VNET also requires a custom devfs ruleset. Create the file as needed on the
+host system:
+
+.. code-block:: shell
+
+  ## /etc/devfs.rules (NOT .conf)
+  
+  [bastille_vnet=13]
+  add include $devfsrules_hide_all
+  add include $devfsrules_unhide_basic
+  add include $devfsrules_unhide_login
+  add include $devfsrules_jail
+  add path 'bpf*' unhide
+
+Lastly, you may want to consider these three `sysctl` values:
+
+.. code-block:: shell
+
+  net.link.bridge.pfil_bridge=0
+  net.link.bridge.pfil_onlyip=0
+  net.link.bridge.pfil_member=0
 
 
 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)
 
@@ -58,9 +101,11 @@ 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.
 
+loopback (bastille0)
+--------------------
 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
+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.

docs/chapters/subcommands/bootstrap.rst

@@ -1,3 +1,4 @@
+=========
 bootstrap
 =========
 
@@ -26,8 +27,7 @@ release version as the argument.
 
 .. code-block:: shell
 
-  ishmael ~ # bastille bootstrap 11.3-RELEASE [update]
-  ishmael ~ # bastille bootstrap 12.0-RELEASE
+  ishmael ~ # bastille bootstrap 11.4-RELEASE [update]
   ishmael ~ # bastille bootstrap 12.1-RELEASE
 
 This command will ensure the required directory structures are in place and

docs/chapters/subcommands/clone.rst

@@ -0,0 +1,17 @@
+=====
+clone
+=====
+
+To clone a container and make a duplicate use the `bastille clone`
+sub-command..
+
+.. code-block:: shell
+
+  ishmael ~ # bastille clone azkaban rikers ip
+  [azkaban]:
+
+Syntax requires a name for the new container and an IP address assignment.
+
+.. code-block:: shell
+
+  Usage: bastille clone [TARGET] [NEW_NAME] [IPADRESS].

docs/chapters/subcommands/cmd.rst

@@ -6,7 +6,7 @@ To execute commands within the container you can use `bastille cmd`.
 
 .. code-block:: shell
 
-  ishmael ~ # bastille cmd folsom 'ps -auxw'
+  ishmael ~ # bastille cmd folsom ps -auxw
   [folsom]:
   USER   PID %CPU %MEM   VSZ  RSS TT  STAT STARTED    TIME COMMAND
   root 71464  0.0  0.0 14536 2000  -  IsJ   4:52PM 0:00.00 /usr/sbin/syslogd -ss

docs/chapters/subcommands/console.rst

@@ -1,3 +1,4 @@
+=======
 console
 =======
 
@@ -8,27 +9,6 @@ root login.
 
   ishmael ~ # bastille console folsom
   [folsom]:
-  FreeBSD 12.1-RELEASE-p1 GENERIC
-
-  Welcome to FreeBSD!
-
-  Release Notes, Errata: https://www.FreeBSD.org/releases/
-  Security Advisories:   https://www.FreeBSD.org/security/
-  FreeBSD Handbook:      https://www.FreeBSD.org/handbook/
-  FreeBSD FAQ:           https://www.FreeBSD.org/faq/
-  Questions List: https://lists.FreeBSD.org/mailman/listinfo/freebsd-questions/
-  FreeBSD Forums:        https://forums.FreeBSD.org/
-
-  Documents installed with the system are in the /usr/local/share/doc/freebsd/
-  directory, or can be installed later with:  pkg install en-freebsd-doc
-  For other languages, replace "en" with a language code like de or fr.
-
-  Show the version of FreeBSD installed:  freebsd-version ; uname -a
-  Please include that output and any error messages when posting questions.
-  Introduction to manual pages:  man man
-  FreeBSD directory layout:      man hier
-
-  Edit /etc/motd to change this login announcement.
   root@folsom:~ #
 
 At this point you are logged in to the container and have full shell access.  The

docs/chapters/subcommands/convert.rst

@@ -0,0 +1,16 @@
+=======
+convert
+=======
+
+To convert a thin container to a thick container use `bastille convert`.
+
+.. code-block:: shell
+
+  ishmael ~ # bastille convert azkaban
+  [azkaban]:
+
+Syntax requires only the target container to convert.
+
+.. code-block:: shell
+
+  Usage: bastille convert TARGET

docs/chapters/subcommands/cp.rst

@@ -1,3 +1,4 @@
+==
 cp
 ==
 

docs/chapters/subcommands/create.rst

@@ -1,3 +1,4 @@
+======
 create
 ======
 

docs/chapters/subcommands/destroy.rst

@@ -1,3 +1,4 @@
+=======
 destroy
 =======
 

docs/chapters/subcommands/edit.rst

@@ -0,0 +1,16 @@
+====
+edit
+====
+
+To edit container configuration use `bastille edit`.
+
+.. code-block:: shell
+
+  ishmael ~ # bastille edit azkaban [filename]
+
+Syntax requires a target an optional filename. By default the file edited will
+be `jail.conf`. Other common filenames are `fstab` or `rctl.conf`.
+
+.. code-block:: shell
+
+  Usage: bastille edit TARGET

docs/chapters/subcommands/export.rst

@@ -0,0 +1,18 @@
+======
+export
+======
+
+Exporting a container creates an archive or image that can be sent to a
+different machine to be imported later. These exported archives can be used as
+container backups.
+
+.. code-block:: shell
+
+  ishmael ~ # bastille export azkaban
+
+The export sub-command supports both UFS and ZFS storage. ZFS based containers
+will use ZFS snapshots. UFS based containers will use `txz` archives.
+
+.. code-block:: shell
+
+  Usage: bastille export TARGET

docs/chapters/subcommands/import.rst

@@ -0,0 +1,16 @@
+======
+import
+======
+
+Import a container backup image or archive.
+
+.. code-block:: shell
+
+  ishmael ~ # bastille import /path/to/archive.file
+
+The import sub-command supports both UFS and ZFS storage. ZFS based containers
+will use ZFS snapshots. UFS based containers will use `txz` archives.
+
+.. code-block:: shell
+
+  Usage: bastille import file [option]

docs/chapters/subcommands/index.rst

@@ -7,18 +7,27 @@ Bastille sub-commands
 
    bootstrap
    cmd
+   clone
    console
+   convert
    cp
    create
    destroy
+   edit
+   export
    htop
+   import
+   mount
    pkg
+   rdr
+   rename
    restart
    service
    start
    stop
    sysrc
    top
+   umount
    update
    upgrade
    verify

docs/chapters/subcommands/mount.rst

@@ -0,0 +1,16 @@
+=====
+mount
+=====
+
+To mount storage within the container use `bastille mount`.
+
+.. code-block:: shell
+
+  ishmael ~ # bastille mount azkaban /storage/foo /media/foo nullfs ro 0 0
+  [azkaban]:
+
+Syntax follows standard `/etc/fstab` format:
+
+.. code-block:: shell
+
+  Usage: bastille mount TARGET host_path container_path [filesystem_type options dump pass_number]

docs/chapters/subcommands/rename.rst

@@ -0,0 +1,13 @@
+======
+rename
+======
+
+Rename a container.
+
+.. code-block:: shell
+
+  ishmael ~ # bastille rename azkaban arkham
+
+.. code-block:: shell
+
+  Usage: bastille rename TARGET new_name

docs/chapters/subcommands/restart.rst

@@ -1,3 +1,4 @@
+=======
 restart
 =======
 

docs/chapters/subcommands/start.rst

@@ -1,3 +1,4 @@
+=====
 start
 =====
 

docs/chapters/subcommands/stop.rst

@@ -1,3 +1,4 @@
+====
 stop
 ====
 

docs/chapters/subcommands/umount.rst

@@ -0,0 +1,16 @@
+======
+umount
+======
+
+To unmount storage from a container use `bastille umount`.
+
+.. code-block:: shell
+
+  ishmael ~ # bastille umount azkaban /media/foo
+  [azkaban]:
+
+Syntax requires only the container path to unmount:
+
+.. code-block:: shell
+
+  Usage: bastille umount TARGET container_path

docs/chapters/subcommands/upgrade.rst

@@ -7,4 +7,4 @@ workflow this can be similar to a `bootstrap`.
 
 .. code-block:: shell
 
-  ishmael ~ # bastille upgrade 11.2-RELEASE 12.0-RELEASE
+  ishmael ~ # bastille upgrade 12.0-RELEASE 12.1-RELEASE