From 830de68bf9f924328192f5d758a1f883b6943c2f Mon Sep 17 00:00:00 2001 From: Christer Edwards Date: Sun, 2 Feb 2020 13:56:02 -0700 Subject: [PATCH] preparing docs for 0.6.x release --- AUTHORS.md | 1 + README.md | 32 ++--- ROADMAP.md | 86 ++++++------ docs/chapters/installation.rst | 2 +- docs/chapters/jail-config.rst | 233 +++++++++++++++++---------------- docs/conf.py | 6 +- 6 files changed, 182 insertions(+), 178 deletions(-) diff --git a/AUTHORS.md b/AUTHORS.md index 7044792a..70b4d177 100644 --- a/AUTHORS.md +++ b/AUTHORS.md @@ -13,6 +13,7 @@ Giacomo Olgeni JP Mens Jose Rivera Lars E. +Paul C. Sven R. ### Special thanks diff --git a/README.md b/README.md index 3afe2eaf..05b09dac 100644 --- a/README.md +++ b/README.md @@ -46,14 +46,16 @@ Available Commands: bootstrap Bootstrap a FreeBSD release for container base. cmd Execute arbitrary command on targeted container(s). console Console into a running container. + convert Convert a thin container into a thick container. cp cp(1) files from host to targeted container(s). - create Create a new thin container or a thick container if -T|--thick option specified. - destroy Destroy a stopped container or a FreeBSD release. - export Exports a specified container. + create Create a new thin or thick container. + destroy Destroy a stopped container or a bootstrapped release. + export Exports a container archive or image. help Help about any command htop Interactive process viewer (requires htop). - import Import a specified container. - list List containers (running and stopped). + import Import a container archive or image. + limits Apply resources limits to targeted container(s). See rctl(8). + list List containers, releases, templates, logs, limits or backups. pkg Manipulate binary packages within targeted container(s). See pkg(8). rdr Redirect host port to container port. restart Restart a running container. @@ -61,11 +63,11 @@ Available Commands: start Start a stopped container. stop Stop a running container. sysrc Safely edit rc files within targeted container(s). - template Apply file templates to targeted container(s). + template Apply automation templates to targeted container(s). top Display and update information about the top(1) cpu processes. update Update container base -pX release. upgrade Upgrade container release to X.Y-RELEASE. - verify Compare release against a "known good" index. + verify Verify bootstrapped release or automation template. zfs Manage (get|set) zfs attributes on targeted container(s). Use "bastille -v|--version" for version information. @@ -73,7 +75,7 @@ Use "bastille command -h|--help" for more information about a command. ``` -## 0.5-beta +## 0.6-beta This document outlines the basic usage of the Bastille container management framework. This release is still considered beta. @@ -393,7 +395,8 @@ ishmael ~ # bastille list You can also list non-running containers with `bastille list containers`. In the same manner you can list archived `logs`, downloaded `templates`, and -`releases`. Providing the `-j` flag to list alone will result in JSON output. +`releases` and `backups`. Providing the `-j` flag to list alone will result in +JSON output. bastille service @@ -872,17 +875,6 @@ Receiving zfs data stream... Container 'folsom' imported successfully. ``` -bastille import list --------------------- -Exported containers can be listed easily before import. -```shell -ishmael ~ # bastille import list -folsom_2020-01-26-19:23:04.xz -thickjail_2020-01-25-04:00:19.xz -thinjail_2020-01-25-02:10:16.txz -root@nas-mserver: ~# -``` - Example (create, start, console) ================================ This example creates, starts and consoles into the container. diff --git a/ROADMAP.md b/ROADMAP.md index f18859eb..39934cac 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,45 +1,55 @@ -Bastille Roadmap -================ -This is the general roadmap for the next nine months. I would like the -near-term done by the end of 2018. The mid-term should be done by March 2019. -The long-term by summer 2019. +2020 Bastille Roadmap +===================== -At that point, if the templating is mature, and the top 50 is complete, the -platform is ready for general purpose use. +1. Virtual Networking +1. Bastille CI/CD +1. Template Maturity & Consolidation +1. Container Monitoring +1. Bastille API +Rough timeline and description below. -near-term ---------- -1. zfs support (configurable) -2. bastille-dev template (see below): -```shell -## jail -c name=foo host.hostname=foo allow.raw_sockets children.max=99 -## ip4.addr=10.20.12.68 persist -## jexec foo /bin/csh -## foo# jail -c name=bar host.hostname=bar allow.raw_sockets -## ip4.addr=10.20.12.68 persist -## foo# jexec bar /bin/csh -## bar# ping gritton.org -``` -3. branding +Virtual Networking (Jan-Feb) ~ 0.6.x-beta +----------------------------------------- +VNET (Virtual Networking) will allow fully virtualized network stacks. This +would bring the total network options to three (loopback, LAN, VNET). The +anticipated design would use a bridge device connected to containers via epair +interfaces. +Bastille CI/CD (March-May) ~ 0.7.x-beta +--------------------------------------- +While we have many of the templates validated by automatic CI/CD, we are not +validating updates to Bastille itself. This automated validation of Pull +Requests should be a priority early in the year with a full test suite designed +to validate all expected uses of Bastille sub-commands. -mid-term --------- -1. templating -2. ssh-to-jail demo (ie; ldap + .authorized_keys + command) -```shell -## TODO: .ssh/authorized_keys auto-launch into user jail -## jail_create_login_hook() { -## echo "permit nopass ${user} cmd /usr/sbin/jexec args ${name} /usr/bin/login -f ${user}" >> /usr/local/etc/doas.conf -## echo "command='/usr/local/bin/doas /usr/sbin/jexec ${name} /usr/bin/login -f ${user}' ${pubkey}" >> $HOME/.ssh/authorized_keys -## } -``` -3. additional modules: ps, sockstat, pf, fstab. +Template Maturity & Consolidation (June-Aug) ~ 0.8.x-beta +--------------------------------------------------------- +Put the 101 templates found in GitHub's BastilleBSD-Templates repository into +GitLab CI/CD pipeline until fully covered. This is a great place for community +contribution. Templates are easy to create and verify and we'd love to +replicate as much of the FreeBSD ports tree as possible! +In addition, it would be nice to create a consolidated repository of curated +templates similar in design to the FreeBSD ports tree. This would contain all +templates in a single repository and mimick ports behavior where appropriate. -long-term ---------- -1. top 50 -2. monitoring -3. rctl +Container Monitoring (Sept-Oct) ~ 0.9.x-beta +-------------------------------------------- +The ability to monitor processes, services, mounts, sockets, etc from the host. +Auto-remediation would be simple enough to define. Notifications would probably +require a plugin system for methods/endpoints. + +Possible monitoring modules: ps, sockstat, pf, fstab + +Possible notification modules: pagerduty, slack, splunk, ELK, etc. + +Bastille API (Nov-Dec) ~ 1.0.x-beta +----------------------------------- +I have thoughts about a lightweight API for Bastille that would accept (json?) +payloads of Bastille commands. The API should be lightweight just as Bastille +is. + +The API is scheduled later in the roadmap because I want to have the other +components stable before we implement an API on top of it. The addition of the +API should match up with Bastille 1.0-stable. diff --git a/docs/chapters/installation.rst b/docs/chapters/installation.rst index 9b4f9023..7750c616 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.5.20191128`. +Current version is `0.6.20200202`. To install from the FreeBSD package repository: diff --git a/docs/chapters/jail-config.rst b/docs/chapters/jail-config.rst index ea3e812e..457637d3 100644 --- a/docs/chapters/jail-config.rst +++ b/docs/chapters/jail-config.rst @@ -13,25 +13,115 @@ template looks like this: .. code-block:: shell - interface = {interface}; - host.hostname = {name}; - exec.consolelog = /usr/local/bastille/logs/{name}_console.log; - path = /usr/local/bastille/jails/{name}/root; - ip6 = disable; - securelevel = 2; - devfs_ruleset = 4; - enforce_statfs = 2; - exec.start = '/bin/sh /etc/rc'; - exec.stop = '/bin/sh /etc/rc.shutdown'; - exec.clean; - mount.devfs; - mount.fstab = /usr/local/bastille/jails/{name}/fstab; - {name} { + devfs_ruleset = 4; + enforce_statfs = 2; + exec.clean; + exec.consolelog = /usr/local/bastille/logs/{name}_console.log; + exec.start = '/bin/sh /etc/rc'; + exec.stop = '/bin/sh /etc/rc.shutdown'; + host.hostname = {name}; + interface = {interface}; + mount.devfs; + mount.fstab = /usr/local/bastille/jails/{name}/fstab; + path = /usr/local/bastille/jails/{name}/root; + securelevel = 2; + ip4.addr = x.x.x.x; + ip6 = disable; } +devfs_ruleset +------------- +.. code-block:: shell + + devfs_ruleset + The number of the devfs ruleset that is enforced for mounting + devfs in this jail. A value of zero (default) means no ruleset + is enforced. Descendant jails inherit the parent jail's devfs + ruleset enforcement. Mounting devfs inside a jail is possible + only if the allow.mount and allow.mount.devfs permissions are + effective and enforce_statfs is set to a value lower than 2. + Devfs rules and rulesets cannot be viewed or modified from inside + a jail. + + NOTE: It is important that only appropriate device nodes in devfs + be exposed to a jail; access to disk devices in the jail may + permit processes in the jail to bypass the jail sandboxing by + modifying files outside of the jail. See devfs(8) for + information on how to use devfs rules to limit access to entries + in the per-jail devfs. A simple devfs ruleset for jails is + available as ruleset #4 in /etc/defaults/devfs.rules. + + +enforce_statfs +-------------- +.. code-block:: shell + + enforce_statfs + This determines what information processes in a jail are able to + get about mount points. It affects the behaviour of the + following syscalls: statfs(2), fstatfs(2), getfsstat(2), and + fhstatfs(2) (as well as similar compatibility syscalls). When + set to 0, all mount points are available without any + restrictions. When set to 1, only mount points below the jail's + chroot directory are visible. In addition to that, the path to + the jail's chroot directory is removed from the front of their + pathnames. When set to 2 (default), above syscalls can operate + only on a mount-point where the jail's chroot directory is + located. + + +exec.clean +---------- +.. code-block:: shell + + exec.clean + Run commands in a clean environment. The environment is + discarded except for HOME, SHELL, TERM and USER. HOME and SHELL + are set to the target login's default values. USER is set to the + target login. TERM is imported from the current environment. + The environment variables from the login class capability + database for the target login are also set. + + +exec.consolelog +--------------- +.. code-block:: shell + + exec.consolelog + A file to direct command output (stdout and stderr) to. + + +exec.start +---------- +.. code-block:: shell + + exec.start + Command(s) to run in the jail environment when a jail is created. + A typical command to run is "sh /etc/rc". + + +exec.stop +--------- +.. code-block:: shell + + exec.stop + Command(s) to run in the jail environment before a jail is + removed, and after any exec.prestop commands have completed. A + typical command to run is "sh /etc/rc.shutdown". + + +host.hostname +------------- +.. code-block:: shell + + host.hostname + The hostname of the jail. Other similar parameters are + host.domainname, host.hostuuid and host.hostid. + + interface --------- .. code-block:: shell @@ -43,28 +133,31 @@ interface the interface after the jail is removed. -host.hostname -------------- +mount.devfs +----------- .. code-block:: shell - host.hostname - The hostname of the jail. Other similar parameters are - host.domainname, host.hostuuid and host.hostid. + 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. -exec.consolelog ---------------- +mount.fstab +----------- .. code-block:: shell - exec.consolelog - A file to direct command output (stdout and stderr) to. + mount.fstab + An fstab(5) format file containing filesystems to mount before + creating a jail. path ---- .. code-block:: shell - path + path The directory which is to be the root of the jail. Any commands run inside the jail, either by jail or from jexec(8), are run from this directory. @@ -114,95 +207,3 @@ cases. filter rules (see ipfw(8), ipfirewall(4) and pfctl(8)) cannot be changed and dummynet(4) or pf(4) configuration cannot be adjusted. - -devfs_ruleset -------------- -.. code-block:: shell - - devfs_ruleset - The number of the devfs ruleset that is enforced for mounting - devfs in this jail. A value of zero (default) means no ruleset - is enforced. Descendant jails inherit the parent jail's devfs - ruleset enforcement. Mounting devfs inside a jail is possible - only if the allow.mount and allow.mount.devfs permissions are - effective and enforce_statfs is set to a value lower than 2. - Devfs rules and rulesets cannot be viewed or modified from inside - a jail. - - NOTE: It is important that only appropriate device nodes in devfs - be exposed to a jail; access to disk devices in the jail may - permit processes in the jail to bypass the jail sandboxing by - modifying files outside of the jail. See devfs(8) for - information on how to use devfs rules to limit access to entries - in the per-jail devfs. A simple devfs ruleset for jails is - available as ruleset #4 in /etc/defaults/devfs.rules. - - -enforce_statfs --------------- -.. code-block:: shell - - enforce_statfs - This determines what information processes in a jail are able to - get about mount points. It affects the behaviour of the - following syscalls: statfs(2), fstatfs(2), getfsstat(2), and - fhstatfs(2) (as well as similar compatibility syscalls). When - set to 0, all mount points are available without any - restrictions. When set to 1, only mount points below the jail's - chroot directory are visible. In addition to that, the path to - the jail's chroot directory is removed from the front of their - pathnames. When set to 2 (default), above syscalls can operate - only on a mount-point where the jail's chroot directory is - located. - - -exec.start ----------- -.. code-block:: shell - - exec.start - Command(s) to run in the jail environment when a jail is created. - A typical command to run is "sh /etc/rc". - - -exec.stop ---------- -.. code-block:: shell - - exec.stop - Command(s) to run in the jail environment before a jail is - removed, and after any exec.prestop commands have completed. A - typical command to run is "sh /etc/rc.shutdown". - - -exec.clean ----------- -.. code-block:: shell - - exec.clean - Run commands in a clean environment. The environment is - discarded except for HOME, SHELL, TERM and USER. HOME and SHELL - are set to the target login's default values. USER is set to the - target login. TERM is imported from the current environment. - The environment variables from the login class capability - database for the target login are also set. - - -mount.devfs ------------ -.. code-block:: shell - - mount.devfs - Mount a devfs(5) filesystem on the chrooted /dev directory, and - apply the ruleset in the devfs_ruleset parameter (or a default of - ruleset 4: devfsrules_jail) to restrict the devices visible - inside the jail. - - -mount.fstab ------------ -.. code-block:: shell - - mount.fstab - An fstab(5) format file containing filesystems to mount before - creating a jail. diff --git a/docs/conf.py b/docs/conf.py index 296dde63..8b990411 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -8,13 +8,13 @@ else: # -- Project information ----------------------------------------------------- project = 'Bastille' -copyright = '2018-2019, Christer Edwards' +copyright = '2018-2020, Christer Edwards' author = 'Christer Edwards' # The short X.Y version -version = '0.5.20191128' +version = '0.6.20200202' # The full version, including alpha/beta/rc tags -release = '0.5.20191128-beta' +release = '0.6.20200202-beta' # -- General configuration ---------------------------------------------------