Merge branch 'BastilleBSD:master' into multiple-interfaces

docs/chapters/networking.rst

@@ -120,6 +120,10 @@ 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`.
 
+If you do not specify a subnet mask, you might have issues with jail to jail
+networking, especially VLAN to VLAN. We recommend always adding a subnet to
+VNET jail IPs when creating them to avoid these issues.
+
 VNET also requires a custom devfs ruleset. Create the file as needed on the
 host system:
 
@@ -305,3 +309,21 @@ At this point you'll likely be disconnected from the host. Reconnect the
 ssh session and continue.
 
 This step only needs to be done once in order to prepare the host.
+
+local_unbound
+=============
+
+If you are running "local_unbound" on your server, you will probably have issues with DNS resolution.
+
+To resolve this, add the following configuration to local_unbound:
+
+.. code-block:: shell
+
+  server:
+  interface: 0.0.0.0
+  access-control: 192.168.0.0/16 allow
+  access-control: 10.17.90.0/24 allow
+
+Also, change the nameserver to the servers IP instead of 127.0.0.1 inside /etc/rc.conf
+
+Adjust the above "access-control" strings to fit your network.

docs/chapters/subcommands/etcupdate.rst

@@ -0,0 +1,46 @@
+=========
+etcupdate
+=========
+
+This command will update the contents of `/etc` inside a jail. It should be run after a jail upgrade
+
+First we need to bootstrap a release for `etcupdate` to use.
+
+.. code-block:: shell
+
+  ishmael ~ # bastille etcupdate bootstrap 14.1-RELEASE
+  bastille_bootstrap_archives: base -> src
+  /usr/local/bastille/cache/14.1-RELEASE/MANIFES        1046  B 1134 kBps    00s
+  /usr/local/bastille/cache/14.1-RELEASE/src.txz         205 MB 2711 kBps 01m18s
+  bastille_bootstrap_archives: src -> base
+  Building tarball, please wait...
+  Etcupdate bootstrap complete: 14.1-RELEASE
+
+Next we can use the `update` command to apply the update to the jail.
+
+.. code-block:: shell
+
+  ishmael ~ # bastille etcupdate ishmael update 14.1-RELEASE
+
+The output will show you which files were added, updated, changed, deleted, or have conflicts.
+To automatically resolve the conflicts, run the `resolve` command.
+
+.. code-block:: shell
+
+  ishmael ~ # bastille etcupdate ishmael resolve
+
+To show only the differences between the releases, use the `diff` command.
+
+.. code-block:: shell
+
+  ishmael ~ # bastille etcupdate ishmael diff 14.1-RELEASE
+
+.. code-block:: shell
+
+  ishmael ~ # bastille etcupdate help
+  Usage: bastille etcupdate [option(s)] [bootstrap|TARGET] [diff|resolve|update RELEASE]
+    Options:
+
+    -d | --dry-run          Show output, but do not apply.
+    -f | --force            Force a re-bootstrap of a RELEASE.
+    -x | --debug            Enable debug mode.

docs/chapters/subcommands/rdr.rst

@@ -14,13 +14,67 @@ specify the interface they run on in rc.conf (or other config files)
 .. code-block:: shell
 
     # bastille rdr --help
-    Usage: bastille rdr TARGET [clear] | [list] | [tcp <host_port> <jail_port>] | [udp <host_port> <jail_port>]
+    Usage: bastille rdr TARGET [option(s)] [clear|reset|list|(tcp|udp host_port jail_port [log ['(' logopts ')'] ] )]
+    Options:
+
+    -i | --interface   [interface]               Set the interface to create the rdr rule on. Useful if you have multiple interfaces.
+    -s | --source      [source ip]               Limit rdr to a source IP. Useful to only allow access from a certian IP or subnet.
+    -d | --destination [destination ip]          Limit rdr to a destination IP. Useful if you have multiple IPs on one interface.
+    -t | --type        [ipv4|ipv6]               Specify IP type. Must be used if -s or -d are used. Defaults to both.
+    -x | --debug                                 Enable debug mode.
+    
     # bastille rdr dev1 tcp 2001 22
+    [jail1]:
+    IPv4 tcp/2001:22  on em0
+   
     # bastille rdr dev1 list
     rdr on em0 inet proto tcp from any to any port = 2001 -> 10.17.89.1 port 22
+    
     # bastille rdr dev1 udp 2053 53
+    [jail1]:
+    IPv4 udp/2053:53 on em0
+    
     # bastille rdr dev1 list
-    rdr on em0 inet proto tcp from any to any port = 2001 -> 10.17.89.1 port 22
-    rdr on em0 inet proto udp from any to any port = 2053 -> 10.17.89.1 port 53
+    rdr pass on em0 inet proto tcp from any to any port = 2001 -> 10.17.89.1 port 22
+    rdr pass on em0 inet proto udp from any to any port = 2053 -> 10.17.89.1 port 53
+    
     # bastille rdr dev1 clear
     nat cleared
+
+The `rdr` command includes 4 additional options:
+
+.. code-block:: shell
+
+    -i | --interface   [interface]               Set the interface to create the rdr rule on. Useful if you have multiple interfaces.
+    -s | --source      [source ip]               Limit rdr to a source IP. Useful to only allow access from a certian IP or subnet.
+    -d | --destination [destination ip]          Limit rdr to a destination IP. Useful if you have multiple IPs on one interface.
+    -t | --type        [ipv4|ipv6]               Specify IP type. Must be used if -s or -d are used. Defaults to both.
+
+.. code-block:: shell
+
+    # bastille rdr dev1 -i vtnet0 udp 8000 80
+    [jail1]:
+    IPv4 tcp/8000:80 on vtnet0
+    
+    # bastille rdr dev1 -s 192.168.0.1 tcp 8080 81
+    [jail1]:
+    IPv4 tcp/8080:81 on em0
+
+    # bastille rdr dev1 -d 192.168.0.84 tcp 8082 82
+    [jail1]:
+    IPv4 tcp/8082:82 on em0
+
+    # bastille rdr dev1 -i vtnet0 -d 192.168.0.45 tcp 9000 9000
+    [jail1]:
+    IPv4 tcp/9000:9000 on vtnet0
+
+    # bastille rdr dev1 list
+    rdr pass on vtnet0 inet proto udp from any to any port = 2001 -> 10.17.89.1 port 22
+    rdr pass on em0 inet proto tcp from 192.168.0.1 to any port = 8080 -> 10.17.89.1 port 81
+    rdr pass on em0 inet proto tcp from any to 192.168.0.84 port = 8082 -> 10.17.89.1 port 82
+    rdr pass on vtnet0 inet proto tcp from any to 192.168.0.45 port = 9000 -> 10.17.89.1 port 9000
+
+The options can be used together, as seen above.
+
+If you have multiple interfaces assigned to your jail, `bastille rdr` will
+only redirect using the default one.

docs/chapters/subcommands/update.rst

@@ -2,8 +2,8 @@
 update
 ======
 
-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 containers are automatically
+The `update` command targets a release or a thick jail. Because thin jails are
+based on a release, when the release is updated all the thin jails are automatically
 updated as well.
 
 If no updates are available, a message will be shown:
@@ -20,8 +20,7 @@ If no updates are available, a message will be shown:
   No updates needed to update system to 11.4-RELEASE-p4.
   No updates are available to install.
 
-
-The older the release, however, the more updates will be available:
+The older the release or jail, however, the more updates will be available:
 
 .. code-block:: shell
 
@@ -38,4 +37,7 @@ The older the release, however, the more updates will be available:
   The following files will be added as part of updating to 13.2-RELEASE-p4:
   ...[snip]...
 
-To be safe, you may want to restart any containers that have been updated live.
+To be safe, you may want to restart any jails that have been updated live.
+
+If the jail is a thin jail, an error will be shown. If it is a thick jail, it will be updated just like
+the release shown above.

docs/chapters/subcommands/upgrade.rst

@@ -0,0 +1,16 @@
+=======
+upgrade
+=======
+
+The `upgrade` command targets a thick or thin jail. Thin jails will be updated by changing the
+release mount point that it is based on. Thick jails will be upgraded normally.
+
+.. code-block:: shell
+
+  ishmael ~ # bastille upgrade help
+  Usage: bastille upgrade [option(s)] TARGET [NEWRELEASE|install]
+    Options:
+
+    -a | --auto             Auto mode. Start/stop jail(s) if required.
+    -f | --force            Force upgrade a jail.
+    -x | --debug            Enable debug mode.

docs/chapters/template.rst

@@ -6,8 +6,8 @@ Looking for ready made CI/CD validated `Bastille Templates`_?
 Bastille supports a templating system allowing you to apply files, pkgs and
 execute commands inside the containers automatically.
 
-Currently supported template hooks are: `CMD`, `CP`, `INCLUDE`, `LIMITS`, `MOUNT`,
-`PKG`, `RDR`, `SERVICE`, `SYSRC`.
+Currently supported template hooks are: `ARG`, `CMD`, `CONFIG`, `CP`, `INCLUDE`,
+`LIMITS`, `MOUNT`, `OVERLAY`, `PKG`, `RDR`, `RENDER`, `RESTART`, `SERVICE`, `SYSRC`.
 
 Templates are created in `${bastille_prefix}/templates` and can leverage any of
 the template hooks.
@@ -23,27 +23,75 @@ template hook commands.
 Template Automation Hooks
 -------------------------
 
-+---------+-------------------+-----------------------------------------+
-| HOOK    | format            | example                                 |
-+=========+===================+=========================================+
-| CMD     | /bin/sh command   | /usr/bin/chsh -s /usr/local/bin/zsh     |
-+---------+-------------------+-----------------------------------------+
-| CP      | path(s)           | etc root usr (one per line)             |
-+---------+-------------------+-----------------------------------------+
-| INCLUDE | template path/URL | http?://TEMPLATE_URL or project/path    |
-+---------+-------------------+-----------------------------------------+
-| LIMITS  | resource value    | memoryuse 1G                            |
-+---------+-------------------+-----------------------------------------+
-| MOUNT   | fstab syntax      | /host/path container/path nullfs ro 0 0 |
-+---------+-------------------+-----------------------------------------+
-| PKG     | port/pkg name(s)  | vim-console zsh git-lite tree htop      |
-+---------+-------------------+-----------------------------------------+
-| RDR     | tcp port port     | tcp 2200 22 (hostport jailport)         |
-+---------+-------------------+-----------------------------------------+
-| SERVICE | service command   | 'nginx start' OR 'postfix reload'       |
-+---------+-------------------+-----------------------------------------+
-| SYSRC   | sysrc command(s)  | nginx_enable=YES                        |
-+---------+-------------------+-----------------------------------------+
++-------------+---------------------+-----------------------------------------+
+| HOOK        | format              | example                                 |
++=============+=====================+=========================================+
+| ARG         | ARG=VALUE           | MINECRAFT_MEMX="1024M"                  |
++-------------+---------------------+-----------------------------------------+
+| CMD         | /bin/sh command     | /usr/bin/chsh -s /usr/local/bin/zsh     |
++-------------+---------------------+-----------------------------------------+
+| CONFIG      | set property value  | set allow.mlock 1                       |
++-------------+---------------------+-----------------------------------------+
+| CP/OVERLAY  | path(s)             | etc root usr (one per line)             |
++-------------+---------------------+-----------------------------------------+
+| INCLUDE     | template path/URL   | http?://TEMPLATE_URL or project/path    |
++-------------+---------------------+-----------------------------------------+
+| LIMITS      | resource value      | memoryuse 1G                            |
++-------------+---------------------+-----------------------------------------+
+| MOUNT       | fstab syntax        | /host/path container/path nullfs ro 0 0 |
++-------------+---------------------+-----------------------------------------+
+| OVERLAY     | path(s)             | etc root usr (one per line)             |
++-------------+---------------------+-----------------------------------------+
+| PKG         | port/pkg name(s)    | vim-console zsh git-lite tree htop      |
++-------------+---------------------+-----------------------------------------+
+| RDR         | tcp port port       | tcp 2200 22 (hostport jailport)         |
++-------------+---------------------+-----------------------------------------+
+| RENDER      | /path/file.txt      | /usr/local/etc/gitea/conf/app.ini       |
++-------------+---------------------+-----------------------------------------+
+| RESTART     |                     | (restart jail)                          |
++-------------+---------------------+-----------------------------------------+
+| SERVICE     | service command     | 'nginx start' OR 'postfix reload'       |
++-------------+---------------------+-----------------------------------------+
+| SYSRC       | sysrc command(s)    | nginx_enable=YES                        |
++-------------+---------------------+-----------------------------------------+
+
+Template Hook Descriptions
+--------------------------
+
+ARG         - set an ARG value to be used in the template
+
+ARGS will default to the value set inside the template, but can be changed by including `--arg ARG=VALUE` when
+running the template. Multiple ARGS can also be specified as seen below. If no ARG value is given, the template 
+will show a warning, but will still continue.
+
+.. code-block:: shell
+
+  ishmael ~ # bastille template azkaban sample/template --arg ARG=VALUE --arg ARG1=VALUE
+
+
+CMD         - run the specified command
+
+CONFIG      - set the specified property and value
+
+CP/OVERLAY  - copy specified files from template directory to specified path inside jail
+
+INCLUDE     - specify a template to include. Make sure the template is bootstrapped, or you are using the template url
+
+LIMITS      - set the specified resource value for the jail
+
+MOUNT       - mount specified files/directories inside the jail
+
+PKG         - install specified packages inside jail
+
+RDR         - redirect specified ports to the jail
+
+RENDER      - replace ARG values inside specified files inside the jail. If a directory is specified, ARGS will be replaced in all files underneath
+
+RESTART     - restart the jail
+
+SERVICE     - run `service` command inside the jail with specified arguments
+
+SYSRC       - run `sysrc` inside the jail with specified arguments
 
 Special Hook Cases
 ------------------
@@ -54,6 +102,9 @@ ie; (`\\"`)
 ARG will always treat an ampersand "\&" literally, without the need to escape it.
 Escaping it will cause errors.
 
+Template Examples
+-----------------
+
 Place these uppercase template hook commands into a `Bastillefile` in any order
 and automate container setup as needed.