# Bastille Bastille Jail Management Tool ## 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 ishmael ~ # bbsd-bootstrap activate bastille 11.1-RELEASE ishmael ~ # ``` 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 ishmael ~ # 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 ishmael ~ # ``` ### 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 ishmael ~ # bbsd-create unbound0 https://github.com/bastillebsd/local_unbound.git 11.1-RELEASE ...[snip]... ishmael ~ # ``` 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 ishmael ~ # bbsd-start unbound0 unbound0: created ishmael ~ # ``` This command can also take a space-separated list of jails to start. ```shell ishmael ~ # bbsd-start unbound0 unbound1 unbound2 unbound0: created unbound1: created unbound2: created ishmael ~ # ``` ### bbsd-stop To stop a jail you can use the `bbsd-stop` command. ```shell ishmael ~ # bbsd-stop unbound0 unbound0: removed ishmael ~ # ``` This command can also take a space-separated list of jails to stop. ```shell ishmael ~ # bbsd-stop unbound0 unbound1 unbound2 unbound0: removed unbound1: removed unbound2: removed ishmael ~ # ``` ### 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 ishmael ~ # 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 ishmael ~ # 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 ishmael ~ # ishmael ~ # ishmael ~ # 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 *:* ishmael ~ # bbsd-cmd beast 'freebsd-version' Targeting specified containers. beastie beastie: 11.1-RELEASE-p9 ishmael ~ # ``` 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 ishmael ~ # bbsd-login beastie root@beastie:~ # exit ishmael ~ # ``` ### 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 ishmael ~ # bbsd-destroy unbound0 /usr/local/bastille/jails/unbound0 Jail destroyed. RIP. ishmael ~ # ``` ### 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 ishmael ~ # bbsd-init-repo ~/Projects/www_nginx.git ishmael ~ # ``` 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.