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 | 100 +++++++++------- docs/chapters/installation.rst | 2 +- docs/chapters/jail-config.rst | 213 +++++++++++++++++---------------- docs/conf.py | 6 +- 6 files changed, 179 insertions(+), 175 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. - -At that point, if the templating is mature, and the top 50 is complete, the -platform is ready for general purpose use. - - -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 - - -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. - - -long-term ---------- -1. top 50 -2. monitoring -3. rctl +2020 Bastille Roadmap +===================== + +1. Virtual Networking +1. Bastille CI/CD +1. Template Maturity & Consolidation +1. Container Monitoring +1. Bastille API + +Rough timeline and description below. + +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. + +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. + +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,108 +13,25 @@ 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; } -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 @@ -156,6 +73,27 @@ enforce_statfs 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 @@ -175,17 +113,24 @@ exec.stop typical command to run is "sh /etc/rc.shutdown". -exec.clean ----------- +host.hostname +------------- .. 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. + host.hostname + The hostname of the jail. Other similar parameters are + host.domainname, host.hostuuid and host.hostid. + + +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. mount.devfs @@ -206,3 +151,59 @@ mount.fstab mount.fstab An fstab(5) format file containing filesystems to mount before creating a jail. + + +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. + 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 @@ # -- 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 ---------------------------------------------------