diff --git a/docs/chapters/installation.rst b/docs/chapters/installation.rst index 7750c616..19b89c85 100644 --- a/docs/chapters/installation.rst +++ b/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: diff --git a/docs/chapters/jail-config.rst b/docs/chapters/jail-config.rst index cee43112..bdc9b1a6 100644 --- a/docs/chapters/jail-config.rst +++ b/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}; diff --git a/docs/chapters/networking.rst b/docs/chapters/networking.rst index 158f1e1c..31ce426a 100644 --- a/docs/chapters/networking.rst +++ b/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. diff --git a/docs/chapters/subcommands/bootstrap.rst b/docs/chapters/subcommands/bootstrap.rst index 15fe917f..ef06edcb 100644 --- a/docs/chapters/subcommands/bootstrap.rst +++ b/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 diff --git a/docs/chapters/subcommands/clone.rst b/docs/chapters/subcommands/clone.rst new file mode 100644 index 00000000..37c196bd --- /dev/null +++ b/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]. diff --git a/docs/chapters/subcommands/cmd.rst b/docs/chapters/subcommands/cmd.rst index d3d7031e..627418ca 100644 --- a/docs/chapters/subcommands/cmd.rst +++ b/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 diff --git a/docs/chapters/subcommands/console.rst b/docs/chapters/subcommands/console.rst index 40aa45c6..b1a218eb 100644 --- a/docs/chapters/subcommands/console.rst +++ b/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 diff --git a/docs/chapters/subcommands/convert.rst b/docs/chapters/subcommands/convert.rst new file mode 100644 index 00000000..c2c63e3c --- /dev/null +++ b/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 diff --git a/docs/chapters/subcommands/cp.rst b/docs/chapters/subcommands/cp.rst index ad985eb0..88c69cfb 100644 --- a/docs/chapters/subcommands/cp.rst +++ b/docs/chapters/subcommands/cp.rst @@ -1,3 +1,4 @@ +== cp == diff --git a/docs/chapters/subcommands/create.rst b/docs/chapters/subcommands/create.rst index 810e6fa4..eb9a9677 100644 --- a/docs/chapters/subcommands/create.rst +++ b/docs/chapters/subcommands/create.rst @@ -1,3 +1,4 @@ +====== create ====== diff --git a/docs/chapters/subcommands/destroy.rst b/docs/chapters/subcommands/destroy.rst index d03090ca..d8fcb8f4 100644 --- a/docs/chapters/subcommands/destroy.rst +++ b/docs/chapters/subcommands/destroy.rst @@ -1,3 +1,4 @@ +======= destroy ======= diff --git a/docs/chapters/subcommands/edit.rst b/docs/chapters/subcommands/edit.rst new file mode 100644 index 00000000..27492f05 --- /dev/null +++ b/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 diff --git a/docs/chapters/subcommands/export.rst b/docs/chapters/subcommands/export.rst new file mode 100644 index 00000000..23e95ddd --- /dev/null +++ b/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 diff --git a/docs/chapters/subcommands/import.rst b/docs/chapters/subcommands/import.rst new file mode 100644 index 00000000..be14e880 --- /dev/null +++ b/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] diff --git a/docs/chapters/subcommands/mount.rst b/docs/chapters/subcommands/mount.rst new file mode 100644 index 00000000..f7fb0ee3 --- /dev/null +++ b/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] diff --git a/docs/chapters/subcommands/rename.rst b/docs/chapters/subcommands/rename.rst new file mode 100644 index 00000000..99924134 --- /dev/null +++ b/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 diff --git a/docs/chapters/subcommands/restart.rst b/docs/chapters/subcommands/restart.rst index 2f6bf52a..8948fb7a 100644 --- a/docs/chapters/subcommands/restart.rst +++ b/docs/chapters/subcommands/restart.rst @@ -1,3 +1,4 @@ +======= restart ======= diff --git a/docs/chapters/subcommands/start.rst b/docs/chapters/subcommands/start.rst index 3d17e078..9057a707 100644 --- a/docs/chapters/subcommands/start.rst +++ b/docs/chapters/subcommands/start.rst @@ -1,3 +1,4 @@ +===== start ===== diff --git a/docs/chapters/subcommands/stop.rst b/docs/chapters/subcommands/stop.rst index 81bdfc7e..3ee7e507 100644 --- a/docs/chapters/subcommands/stop.rst +++ b/docs/chapters/subcommands/stop.rst @@ -1,3 +1,4 @@ +==== stop ==== diff --git a/docs/chapters/subcommands/umount.rst b/docs/chapters/subcommands/umount.rst new file mode 100644 index 00000000..f4aaeb49 --- /dev/null +++ b/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 diff --git a/docs/chapters/subcommands/upgrade.rst b/docs/chapters/subcommands/upgrade.rst index cf35e595..7104aab3 100644 --- a/docs/chapters/subcommands/upgrade.rst +++ b/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 diff --git a/docs/chapters/targeting.rst b/docs/chapters/targeting.rst index 6bf6bb14..680dfe18 100644 --- a/docs/chapters/targeting.rst +++ b/docs/chapters/targeting.rst @@ -1,12 +1,12 @@ Targeting ========= -Bastille uses a `command-target-args` syntax, meaning that each command +Bastille uses a `command target arguments` syntax, meaning that each command requires a target. Targets are usually containers, but can also be releases. -Targeting a containers is done by providing the exact containers name. +Targeting a container is done by providing the exact containers name. -Targeting a release is done by providing the release name. (Note: do note +Targeting a release is done by providing the release name. (Note: do not include the `-pX` point-release version.) Bastille includes a pre-defined keyword ALL to target all running containers. @@ -42,7 +42,7 @@ Examples: Containers +-----------+--------+-----+------------+-------------------------------------------------------------+ | cp | bastion03 | /tmp/resolv.conf-cf etc/resolv.conf | copy host-path to container-path in bastion03| +----+------+----+---+------------------+--------------+----------------------------------------------+ -| create | folsom | 12.0-RELEASE 10.17.89.10 | create 12.0 container named `folsom` with IP | +| create | folsom | 12.1-RELEASE 10.17.89.10 | create 12.1 container named `folsom` with IP | +-----------+--------+------------------+--------------+----------------------------------------------+ @@ -56,11 +56,11 @@ Examples: Releases +-----------+--------------+--------------+-------------------------------------------------------------+ | command | target | args | description | +===========+==============+==============+=============================================================+ -| bootstrap | 12.0-RELEASE | --- | bootstrap 12.0-RELEASE release | +| bootstrap | 12.1-RELEASE | --- | bootstrap 12.1-RELEASE release | +-----------+--------------+--------------+-------------------------------------------------------------+ -| update | 11.3-RELEASE | --- | update 11.2-RELEASE release | +| update | 11.4-RELEASE | --- | update 11.4-RELEASE release | +-----------+--------------+--------------+-------------------------------------------------------------+ -| upgrade | 11.2-RELEASE | 11.3-RELEASE | update 11.2-RELEASE release | +| upgrade | 11.3-RELEASE | 11.4-RELEASE | update 11.4-RELEASE release | +-----------+--------------+--------------+-------------------------------------------------------------+ -| verify | 11.3-RELEASE | --- | update 11.2-RELEASE release | +| verify | 11.4-RELEASE | --- | update 11.4-RELEASE release | +-----------+--------------+--------------+-------------------------------------------------------------+ diff --git a/docs/chapters/template.rst b/docs/chapters/template.rst index 21adcb9d..c92e3c7d 100644 --- a/docs/chapters/template.rst +++ b/docs/chapters/template.rst @@ -9,27 +9,20 @@ execute commands inside the containers automatically. Currently supported template hooks are: `LIMITS`, `INCLUDE`, `PRE`, `FSTAB`, `PKG`, `OVERLAY`, `SYSRC`, `SERVICE`, `CMD`. -Planned template hooks include: `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; +the template hooks. -.. code-block:: shell - - 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/username/base/PKG - echo "/usr/bin/chsh -s /usr/local/bin/zsh" > /usr/local/bastille/templates/username/base/CMD - echo "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: +Bastille 0.7.x +-------------- +Bastille 0.7.x introduces a template syntax that is more flexible and allows +any-order scripting. Previous versions had a hard template execution order and +instructions were spread across multiple files. The new syntax is done in a +`Bastillefile` and the template hook (see below) files are replaced with +template hook commands. +Template Automation Hooks +------------------------- +---------+-------------------+-----------------------------------------+ | HOOK | format | example | @@ -56,13 +49,16 @@ work as expected. This table outlines those requirements: Note: SYSRC requires that NO quotes be used or that quotes (`"`) be escaped ie; (`\\"`) +Place these uppercase template hook commands into a `Bastillefile` in any order +and automate container setup as needed. + In addition to supporting template hooks, Bastille supports overlaying 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 `bastille/templates/username/base`, our +An example here may help. Think of `bastille/templates/username/template`, our example template, as the root of our filesystem overlay. If you create an -`etc/hosts` or `etc/resolv.conf` *inside* the base template directory, these +`etc/hosts` or `etc/resolv.conf` *inside* the template directory, these can be overlayed into your container. Note: due to the way FreeBSD segregates user-space, the majority of your @@ -75,7 +71,7 @@ use, be sure to include `usr` in the template OVERLAY definition. eg; .. code-block:: shell - echo "usr" > /usr/local/bastille/templates/username/base/OVERLAY + echo "usr" > /usr/local/bastille/templates/username/template/OVERLAY The above example "usr" will include anything under "usr" inside the template. You do not need to list individual files. Just include the top-level directory @@ -92,7 +88,7 @@ directory names in the `bastille/templates` directory. .. code-block:: shell - ishmael ~ # bastille template ALL username/base + ishmael ~ # bastille template ALL username/template [proxy01]: Copying files... Copy complete. diff --git a/docs/chapters/usage.rst b/docs/chapters/usage.rst index 8e97eb9b..e6f4f78a 100644 --- a/docs/chapters/usage.rst +++ b/docs/chapters/usage.rst @@ -3,31 +3,40 @@ Usage .. code-block:: shell - ishmael ~ # bastille -h + ishmael ~ # bastille help Bastille is an open-source system for automating deployment and management of containerized applications on FreeBSD. Usage: - bastille command [ALL|glob] [args] + bastille command TARGET [args] Available Commands: bootstrap Bootstrap a FreeBSD release for container base. cmd Execute arbitrary command on targeted container(s). + clone Clone an existing container. 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. destroy Destroy a stopped container or a FreeBSD release. - help Help about any command + edit Edit container configuration files (advanced). + export Exports a specified container. + help Help about any command. htop Interactive process viewer (requires htop). - list List containers, releases, templates, or logs. + import Import a specified container. + list List containers (running and stopped). + mount Mount a volume inside the targeted container(s). pkg Manipulate binary packages within targeted container(s). See pkg(8). + rdr Redirect host port to container port. + rename Rename a container. restart Restart a running container. - service Manage services within targeted containers(s). + service Manage services within targeted container(s). 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). top Display and update information about the top(1) cpu processes. + umount Unmount a volume from within the targeted container(s). update Update container base -pX release. upgrade Upgrade container release to X.Y-RELEASE. verify Compare release against a "known good" index. @@ -35,3 +44,4 @@ Usage Use "bastille -v|--version" for version information. Use "bastille command -h|--help" for more information about a command. + diff --git a/docs/conf.py b/docs/conf.py index 8b990411..e8d83fbe 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,9 +12,9 @@ copyright = '2018-2020, Christer Edwards' author = 'Christer Edwards' # The short X.Y version -version = '0.6.20200202' +version = '0.7.20200714' # The full version, including alpha/beta/rc tags -release = '0.6.20200202-beta' +release = '0.7.20200714-beta' # -- General configuration ---------------------------------------------------