Mirrors/BastilleBSD_bastille
1
0
Fork 1
mirror of https://github.com/BastilleBSD/bastille.git synced 2025-12-10 17:09:48 +01:00
Code Issues Packages Projects Releases Wiki Activity

preparing docs for 0.6.x release

Browse Source
This commit is contained in:
Christer Edwards
2020-02-02 13:56:02 -07:00
parent 503f787d69
commit 830de68bf9
6 changed files with 182 additions and 178 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
AUTHORS.md
View File

@@ -13,6 +13,7 @@ Giacomo Olgeni
JP Mens
Jose Rivera
Lars E.
Paul C.
Sven R.
### Special thanks

32
README.md
View File

@@ -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.

86
ROADMAP.md
View File

@@ -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.

2
docs/chapters/installation.rst
View File

@@ -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:

233
docs/chapters/jail-config.rst
View File

@@ -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.

6
docs/conf.py
View File

@@ -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 ---------------------------------------------------