diff --git a/README.md b/README.md index e6fb5d44..ababdf99 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,230 @@ # Bastille Bastille Jail Management Tool -README pending; still a little bit in flux. +## 0.1 alpha +This document outlines the basic usage of the Bastille jail management +framework. This release, obviously, is alpha quality. I make no guarantees of +quality, and if it screws up your system... Sorry, bro. DO NOT USE THIS IN +PRODUCTION unless you are the embodiment of The Chaos Monkey. + +With all that said, here's how to use this tool in its current ALPHA state. + +### bbsd-bootstrap +The first step is to "bootstrap" a release. Currently this uses ZFS, but I +would very much like to keep things flexible enough to not *require* ZFS. To +bootstrap a release use the `bbsd-bootstrap` command. + +```shell + bbsd-bootstrap activate bastille 11.1-RELEASE +``` + +This command creates the directory structure, fetches the specified release, +extracts and creates a ZFS snapshot. Once a system is "activated" it should +have everything it needs to create a jail. + +```shell + pebbles ~ # ll /usr/local/bastille + total 27 + drwxr-xr-x 2 root wheel 3B Mar 17 15:34 downloads + drwxr-xr-x 2 root wheel 8B Apr 6 18:52 fstab + drwxr-xr-x 8 root wheel 8B Mar 31 08:35 jails + drwxr-xr-x 2 root wheel 8B Mar 30 20:50 logs + drwxr-xr-x 3 root wheel 3B Mar 17 15:37 releases +``` + +### bbsd-create +Bastille creates jails using pre-defined templates (which are generally stored +in GitHub), and the concept of basejails. The general workflow requires three +things: + +- Jail name +- Git repo / template +- FreeBSD release (ie; 11.1-RELEASE) + +```shell + bbsd-create unbound0 https://github.com/bastillebsd/local_unbound.git 11.1-RELEASE +``` + +This command will create a 11.1-based basejail, and pre-populate the root +file system with the required configuration. At creation time the following is +done: + +- 11.1-RELEASE directories created +- Git repo / template contents fetched +- Any required pkgs are installed + +By default it uses the basejail concept, but I don't want it to be limited to +_just_ that in the long-term. The other jail-type that I envision is simply +ZFS-snapshots of pre-created profiles. + +### bbsd-start +To start a jail you can use the `bbsd-start` command. + +```shell + bbsd-start unbound0 +``` + +This command can also take a space-separated list of jails to start. + +```shell + bbsd-start unbound0 unbound1 unbound2 +``` + +### bbsd-stop +To stop a jail you can use the `bbsd-stop` command. + +```shell + bbsd-stop unbound0 +``` + +This command can also take a space-separated list of jails to stop. + +```shell + bbsd-stop unbound0 unbound1 unbound2 +``` + +### bbsd-restart +You can probably guess what this one does. It takes the same options as +`bbsd-start` or `bbsd-stop`. + +### bbsd-cmd +This tool is an extension of a tiny set of scripts I have been using personally +to manage my jails. It started out as a simple for-loop and have now evolved +into something a _little_ more mature. + +```shell + bbsd-cmd ALL 'sockstat -4' +``` + +This command will execute the "$2" argument (note the use of quotes to +encapsulate longer commands) inside the targeted jail(s). Yes, I said +targeting, but I will admit it is VERY rudimentary. It has all the flexibility +of a simple `grep "$1"` within the list of jails, with a built-in for `ALL`. +This could/should be expanded to use PCRE and any other targeting method people +want (think SaltStack targeting options). For now, it's simple. + +Remember, `bbsd-cmd TARGET "QUOTED COMMAND INCLUDING OPTIONS"` will execute the +command on *ALL* systems matching the target. Here is an example from a dev +system. + +```shell + pebbles ~ # jls + JID IP Address Hostname Path + unbound0 10.0.0.10 unbound0 /usr/local/bastille/jails/unbound0/root + unbound1 10.0.0.20 unbound1 /usr/local/bastille/jails/unbound1/root + unbound2 10.0.0.30 unbound2 /usr/local/bastille/jails/unbound2/root + beastie 10.0.0.79 beastie /usr/local/bastille/jails/beastie/root + xmakaba 10.0.0.137 xmakaba /usr/local/bastille/jails/xmakaba/root + pebbles ~ # bbsd-cmd unbound 'sockstat -4' + Targeting specified containers. + unbound0 + unbound1 + unbound2 + + unbound0: + USER COMMAND PID FD PROTO LOCAL ADDRESS FOREIGN ADDRESS + unbound unbound 9639 3 udp4 10.0.0.10:53 *:* + unbound unbound 9639 4 tcp4 10.0.0.10:53 *:* + + unbound1: + USER COMMAND PID FD PROTO LOCAL ADDRESS FOREIGN ADDRESS + unbound unbound 31590 3 udp4 10.0.0.20:53 *:* + unbound unbound 31590 4 tcp4 10.0.0.20:53 *:* + + unbound2: + USER COMMAND PID FD PROTO LOCAL ADDRESS FOREIGN ADDRESS + unbound unbound 66761 3 udp4 10.0.0.30:53 *:* + unbound unbound 66761 4 tcp4 10.0.0.30:53 *:* + + pebbles ~ # bbsd-cmd beast 'freebsd-version' + Targeting specified containers. + beastie + + beastie: + 11.1-RELEASE-p9 + + pebbles ~ # +``` + +As you can see, the very basic `grep` is done and limits the targeting to the +specified machine(s). The hope here is to provide flexible targeting to N +number of arbitrary systems. + +### bbsd-pkg +This component is very similar to the `bbsd-cmd` tool above, but is restricted +to the `pkg` system. If you need to install, delete, upgrade or otherwise +manage installed pkgs within a jail this is the tool to use. + +In documenting this section it looks like this script might need a little love. +I'll take a look when I'm done here. + +### bbsd-login +This command will log you into a jail. Current support is password-less root +login, but this will support specifying users. It will likely remain +password-less. + +```shell + pebbles ~ # bbsd-login beastie + root@beastie:~ # +``` + +### bbsd-destroy +This command will destroy a non-running jail. No, it can't destroy running +jails. You have to stop them first. It takes two arguments: jail name & path. +The path, at this point, is probably extraneous. I added it initially as kind +of a fail-safe. I just need to make the script a little more mature to make +sure it handles the file system deletions properly. + +```shell + bbsd-destroy unbound0 /usr/local/bastille/jails/unbound0 +``` + +### bbsd-top +This one simply runs `top` in that jail. This command is interactive, as `top` +is interactive. If you want metrics other than actually running `top`, use +`bbsd-cmd TARGET 'ps -auxwww'` or the like. + +### bbsd-init-repo +This command is a convenience tool to create the template structure for a +template. The idea here is that it creates all the appropriate directories +needed for a basejail-style jail. It also includes the other required template +files such as the `jail.conf` and the `pkgs.conf`. + +This command requires a path argument and then creates a bunch of directories +at that path. For example. + +```shell + bbsd-init-repo ~/Projects/www_nginx.git +``` + +This would create the required template structure in the pre-existing directory +of `www_nginx.git` within the `Projects` directory of the users HOME. This +script also needs a little work. + +This tool should be used by template developers who want to quickly create the +required structure for a template. The customization of config files can then +be put in place within that template directory structure. + +I want to evolve this tool to the point where it can help churn out templates +for much of what is in the FreeBSD ports tree. Initially I expect to build +services such as DNS, SMTP, Media (Plex), SSH, browser (Firefox) jails. + +## Goals +These tools are created initially with the mindset of function over form. I +want to simply prove the concept is sound for real work. The real work is a +sort of meta-jail-port system. Instead of installing the MySQL port directly on +a system, you would use Bastille to install the MySQL port within a jail +template built for MySQL. The same goes for DNS servers, and everything else in +the ports tree. + +Eventually I would like to have Bastille templates created for popular +FreeBSD-based services. From Plex Media Servers to ad-blocking DNS resolvers. +From tiny SSH jails to dynamic web servers. + +I don't want to tell you what you can and can't run within this framework. +There are no arbitrary limitations based on what I think may or may not be the +best way to design systems. This is not my goal. + +My goal is to provide a secure framework where processes and services can run +isolated. I want to limit the scope and reach of bad actors. I want to severely +limit the target areas available to anyone that has (or has gained!) access.