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

brought README up to date with 0.5.20191125 RC

Browse Source
This commit is contained in:
Christer Edwards
2019-11-22 21:59:11 -07:00
parent 6c32bccbe6
commit 29a8b8a671
1 changed files with 197 additions and 264 deletions
Download Patch File Download Diff File Expand all files Collapse all files

461
README.md
View File

@@ -1,14 +1,14 @@
Bastille Bastille: Automated Container Security
======== ======================================
Bastille is a jail automation framework that allows you to quickly create and Bastille is an open-source system for automating deployment and management of
manage FreeBSD jails. containerized applications on FreeBSD.
Looking for [Bastille Templates](https://github.com/BastilleBSD-Templates)? Looking for [Bastille Templates](https://gitlab.com/BastilleBSD-Templates)?
Installation Installation
============ ============
Bastille is available in the official ports tree. Bastille is available in the official FreeBSD ports tree.
**pkg** **pkg**
```shell ```shell
@@ -17,6 +17,7 @@ pkg install bastille
**ports** **ports**
```shell ```shell
portsnap fetch auto
make -C /usr/ports/sysutils/bastille install clean make -C /usr/ports/sysutils/bastille install clean
``` ```
@@ -24,9 +25,11 @@ make -C /usr/ports/sysutils/bastille install clean
Basic Usage Basic Usage
----------- -----------
```shell ```shell
ishmael ~ # bastille -h Bastille is an open-source system for automating deployment and management of
containerized applications on FreeBSD.
Usage: Usage:
bastille command [ALL|glob] [args] bastille command TARGET args
Available Commands: Available Commands:
bootstrap Bootstrap a FreeBSD release for container base. bootstrap Bootstrap a FreeBSD release for container base.
@@ -40,36 +43,46 @@ Available Commands:
list List containers (running and stopped). list List containers (running and stopped).
pkg Manipulate binary packages within targeted container(s). See pkg(8). pkg Manipulate binary packages within targeted container(s). See pkg(8).
restart Restart a running container. restart Restart a running container.
service Manage services within targeted jail(s). service Manage services within targeted container(s).
start Start a stopped container. start Start a stopped container.
stop Stop a running container. stop Stop a running container.
sysrc Safely edit rc files within targeted container(s). sysrc Safely edit rc files within targeted container(s).
template Apply file templates to targeted jail(s). template Apply file templates to targeted container(s).
top Display and update information about the top(1) cpu processes. top Display and update information about the top(1) cpu processes.
update Update container base -pX release. update Update container base -pX release.
upgrade Upgrade container release to X.Y-RELEASE. upgrade Upgrade container release to X.Y-RELEASE.
verify Compare release against a "known good" index. verify Compare release against a "known good" index.
zfs Manage (get|set) zfs attributes on targeted jail(s). zfs Manage (get|set) zfs attributes on targeted container(s).
Use "bastille -v|--version" for version information. Use "bastille -v|--version" for version information.
Use "bastille command -h|--help" for more information about a command. Use "bastille command -h|--help" for more information about a command.
``` ```
## 0.4-beta ## 0.5-beta
This document outlines the basic usage of the Bastille jail management This document outlines the basic usage of the Bastille container management
framework. This release is still considered beta. framework. This release is still considered beta.
Network Requirements Network Requirements
==================== ====================
Several networking options can be performed regarding the user needs. Several networking options can be performed regarding the user needs. Basic
Basic jails can support IP alias networking, where the IP address is assigned containers can support IP alias networking, where the IP address is assigned to
to the host interface and used by the jail, generally known as "shared IP" based jails. the host interface and used by the container, generally known as "shared IP"
based containers.
However, in order to segregate jails from the network and from the world, Bastille If you administer your own network and can assign and remove unallocated IP
attaches jails to a loopback interface only. The host system then acts as addresses, then "shared IP" is a simple method to get started. If this is the
the firewall, permitting and denying traffic as needed. case, skip ahead to ZFS Support.
If you are not the administator of the network, or perhaps you're in "the
cloud" someplace and are only provided a single IP4 address. In this situation
Bastille can create and attach containers to a private loopback interface. The
host system then acts as the firewall, permitting and denying traffic as
needed. (This method has been my primary method for years.)
**bastille0**
First, create the loopback interface: First, create the loopback interface:
@@ -93,7 +106,7 @@ Create the firewall config, or merge as necessary.
``` ```
ext_if="vtnet0" ext_if="vtnet0"
set block-policy drop set block-policy return
scrub in on $ext_if all fragment reassemble scrub in on $ext_if all fragment reassemble
set skip on lo set skip on lo
@@ -102,7 +115,7 @@ nat on $ext_if from bastille0:network to any -> ($ext_if)
## rdr example ## rdr example
## rdr pass inet proto tcp from any to any port {80, 443} -> 10.17.89.45 ## rdr pass inet proto tcp from any to any port {80, 443} -> 10.17.89.45
block in log all block in all
pass out quick modulate state pass out quick modulate state
antispoof for $ext_if inet antispoof for $ext_if inet
pass in inet proto tcp from any to any port ssh flags S/SA keep state pass in inet proto tcp from any to any port ssh flags S/SA keep state
@@ -110,9 +123,10 @@ pass in inet proto tcp from any to any port ssh flags S/SA keep state
* Make sure to change the `ext_if` variable to match your host system interface. * Make sure to change the `ext_if` variable to match your host system interface.
* Make sure to include the last line (`port ssh`) or you'll end up locked * Make sure to include the last line (`port ssh`) or you'll end up locked
out. out of a remote system.
Note: if you have an existing firewall, the key lines for in/out traffic to jails are: Note: if you have an existing firewall, the key lines for in/out traffic to
containers are:
``` ```
nat on $ext_if from bastille0:network to any -> ($ext_if) nat on $ext_if from bastille0:network to any -> ($ext_if)
@@ -125,11 +139,8 @@ The `nat` routes traffic from the loopback interface to the external interface
for outbound access. for outbound access.
The `rdr pass ...` will redirect traffic from the host firewall on port X to The `rdr pass ...` will redirect traffic from the host firewall on port X to
the ip of Jail Y. The example shown redirects web traffic (80 & 443) to the the ip of container Y. The example shown redirects web traffic (80 & 443) to the
jails at `10.17.89.45`. container at `10.17.89.45`.
We'll get to that later, but when you're ready to allow traffic inbound to your
jails, that's where you'd do it.
Finally, start up the firewall: Finally, start up the firewall:
@@ -173,65 +184,70 @@ ishmael ~ # sysrc -f /usr/local/etc/bastille/bastille.conf bastille_zfs_zpool=ZP
``` ```
Replace `ZPOOL_NAME` with the zpool you want Bastille to use. Tip: `zpool list` Replace `ZPOOL_NAME` with the zpool you want Bastille to use. Tip: `zpool list`
and `zpool status` will help. and `zpool status` will help. If you get 'no pools available' you are likely
not using ZFS and can safely ignore these settings.
bastille bootstrap bastille bootstrap
------------------ ------------------
Before you can begin creating jails, Bastille needs to "bootstrap" a release. Before you can begin creating containers, Bastille needs to "bootstrap" a
Current supported releases are 11.2-RELEASE and 12.0-RELEASE, but you can release. Current supported releases are 11.3-RELEASE, 12.0-RELEASE and
bootstrap anything in the ftp.FreeBSD.org RELEASES directory. 12.1-RELEASE.
**Important: If you need ZFS support see the above section BEFORE bootstrapping.** **Important: If you need ZFS support see the above section BEFORE
bootstrapping.**
Note: your mileage may vary with unsupported releases and releases newer than
the host system likely will NOT work at all.
To `bootstrap` a release, run the bootstrap sub-command with the To `bootstrap` a release, run the bootstrap sub-command with the
release version as the argument. release version as the argument.
**FreeBSD 11.3-RELEASE**
```shell
ishmael ~ # bastille bootstrap 11.3-RELEASE
```
** FreeBSD 12.0-RELEASE ** **FreeBSD 12.0-RELEASE**
```shell ```shell
ishmael ~ # bastille bootstrap 12.0-RELEASE ishmael ~ # bastille bootstrap 12.0-RELEASE
``` ```
** FreeBSD 11.2-RELEASE ** **FreeBSD 12.1-RELEASE**
```shell ```shell
ishmael ~ # bastille bootstrap 11.2-RELEASE ishmael ~ # bastille bootstrap 12.1-RELEASE
``` ```
** HardenedBSD 12-STABLE-LAST ** **HardenedBSD 11-STABLE-LAST**
```shell
ishmael ~ # bastille bootstrap 11-STABLE-LAST
```
**HardenedBSD 12-STABLE-LAST**
```shell ```shell
ishmael ~ # bastille bootstrap 12-STABLE-LAST ishmael ~ # bastille bootstrap 12-STABLE-LAST
``` ```
** HardenedBSD 11-STABLE-LAST ** > `bastille bootstrap RELEASE update` to apply updates automatically at bootstrap.
```shell
ishmael ~ # bastille bootstrap 11-STABLE-LAST
```
This command will ensure the required directory structures are in place and This command will ensure the required directory structures are in place and
download the requested release. For each requested release, `bootstrap` will download the requested release. For each requested release, `bootstrap` will
download the base.txz. If you need more than base (eg; ports, lib32, src) you download the base.txz. If you need more than base (eg; ports, lib32, src) you
can configure the `bastille_bootstrap_archives` in the configuration file. By can configure the `bastille_bootstrap_archives` in the configuration file. By
default this value is set to "base". Additional components are added, space default this value is set to "base". Additional components are added, space
separated, without extension. separated, without file extension.
Bastille will attempt to fetch the required archives if they are not found in Bastille will attempt to fetch the required archives if they are not found in
the `cache/$RELEASE` directory. the `cache/$RELEASE` directory.
Downloaded artifacts are stored in the `cache/$RELEASE` directory. "bootstrapped" Downloaded artifacts are stored in the `cache/RELEASE` directory. "bootstrapped"
releases are stored in `releases/$RELEASE`. releases are stored in `releases/RELEASE`.
Advanced: If you want to create your own custom base.txz, or use an unsupported Advanced: If you want to create your own custom base.txz, or use an unsupported
variant of FreeBSD, drop your own base.txz in `cache/$RELEASE/base.txz` and variant of FreeBSD, drop your own base.txz in `cache/RELEASE/base.txz` and
`bastille bootstrap` will attempt to extract and use it. `bastille bootstrap` will attempt to extract and use it.
The bootstrap subcommand is generally only used once to prepare the system. The The bootstrap subcommand is generally only used once to prepare the system. The
other use cases for the bootstrap command are when a new FreeBSD version is other use cases for the bootstrap command are when a new FreeBSD version is
released and you want to start building jails on that version, or bootstrapping released and you want to start building containers on that version, or
templates from GitHub or GitLab. bootstrapping templates from GitHub or GitLab.
See `bastille update` to ensure your bootstrapped releases include the latest See `bastille update` to ensure your bootstrapped releases include the latest
patches. patches.
@@ -239,33 +255,42 @@ patches.
bastille create bastille create
--------------- ---------------
`bastille create` uses a bootstrapped release to create a lightweight `bastille create` uses a bootstrapped release to create a lightweight container
jailed system. To create a jail simply provide a name, release and system. To create a container simply provide a name, release and a private
a private (rfc1918) IP address. (rfc1918) IP address. Optionally provide a network interface name to attach the
IP at container creation.
- name - name
- release (bootstrapped) - release (bootstrapped)
- ip - ip
- interface (optional)
```shell ```shell
ishmael ~ # bastille create folsom 12.0-RELEASE 10.17.89.10 ishmael ~ # bastille create folsom 12.0-RELEASE 10.17.89.10
Valid: (10.17.89.10).
RELEASE: 12.0-RELEASE.
NAME: folsom. NAME: folsom.
IP: 10.17.89.10. IP: 10.17.89.10.
RELEASE: 12.0-RELEASE.
syslogd_flags: -s -> -ss
sendmail_enable: NO -> NONE
cron_flags: -> -J 60
``` ```
This command will create a 12.0-RELEASE jail assigning the 10.17.89.10 ip This command will create a 12.0-RELEASE container assigning the 10.17.89.10 ip
address to the new system. address to the new system.
Optionally `bastille create [ -T | --thick ]` will create a self contained Thickjail system instead. Optionally `bastille create [ -T | --thick ]` will create a container with a
private base. This is sometimes referred to as a "thick" container (whereas the
shared base container is a "thin").
```shell ```shell
ishmael ~ # bastille create -T folsom 12.0-RELEASE 10.17.89.10 ishmael ~ # bastille create -T folsom 12.0-RELEASE 10.17.89.10
``` ```
I recommend using private (rfc1918) ip address ranges for your jails. I recommend using private (rfc1918) ip address ranges for your containers.
These ranges include: These ranges include:
- 10.0.0.0/8 - 10.0.0.0/8
@@ -273,15 +298,15 @@ These ranges include:
- 192.168.0.0/16 - 192.168.0.0/16
If your Bastille host also uses private (rfc1918) addresses, use a different If your Bastille host also uses private (rfc1918) addresses, use a different
range for your jails. ie; Host uses 192.168.0.0/16, jails use 10.0.0.0/8. range for your containers. ie; Host uses 192.168.0.0/16, containers use 10.0.0.0/8.
Bastille does its best to validate the submitted ip is valid. This has not been Bastille does its best to validate the submitted ip is valid. I generally use
thouroughly tested. I generally use the 10.0.0.0/8 range for jails. the 10.0.0.0/8 range for containers.
bastille start bastille start
-------------- --------------
To start a jail you can use the `bastille start` command. To start a containers you can use the `bastille start` command.
```shell ```shell
ishmael ~ # bastille start folsom ishmael ~ # bastille start folsom
@@ -293,7 +318,7 @@ folsom: created
bastille stop bastille stop
------------- -------------
To stop a jail you can use the `bastille stop` command. To stop a containers you can use the `bastille stop` command.
```shell ```shell
ishmael ~ # bastille stop folsom ishmael ~ # bastille stop folsom
@@ -305,7 +330,7 @@ folsom: removed
bastille restart bastille restart
---------------- ----------------
To restart a jail you can use the `bastille restart` command. To restart a container you can use the `bastille restart` command.
```shell ```shell
ishmael ~ # bastille restart folsom ishmael ~ # bastille restart folsom
@@ -317,13 +342,33 @@ folsom: created
``` ```
bastille list
-------------
This sub-command will show you the running containers on your system.
```shell
ishmael ~ # bastille list
JID IP Address Hostname Path
bastion 10.17.89.65 bastion /usr/local/bastille/jails/bastion/root
unbound0 10.17.89.60 unbound0 /usr/local/bastille/jails/unbound0/root
unbound1 10.17.89.61 unbound1 /usr/local/bastille/jails/unbound1/root
squid 10.17.89.30 squid /usr/local/bastille/jails/squid/root
nginx 10.17.89.45 nginx /usr/local/bastille/jails/nginx/root
folsom 10.17.89.10 folsom /usr/local/bastille/jails/folsom/root
```
You can also list non-running containers with `bastille list jails`. In the
same manner you can list archived `logs`, downloaded `templates`, and
`releases.
bastille service bastille service
---------------- ----------------
To restart services inside a jail you can use the `bastille service` command. To restart services inside a containers you can use the `bastille service`
command.
```shell ```shell
ishmael ~ # bastille service folsom 'postfix restart' ishmael ~ # bastille service folsom postfix restart
[folsom] [folsom]
postfix/postfix-script: stopping the Postfix mail system postfix/postfix-script: stopping the Postfix mail system
postfix/postfix-script: starting the Postfix mail system postfix/postfix-script: starting the Postfix mail system
@@ -333,10 +378,10 @@ postfix/postfix-script: starting the Postfix mail system
bastille cmd bastille cmd
------------ ------------
To execute commands within the jail you can use `bastille cmd`. To execute commands within the container you can use `bastille cmd`.
```shell ```shell
ishmael ~ # bastille cmd folsom 'ps -auxw' ishmael ~ # bastille cmd folsom ps -auxw
[folsom]: [folsom]:
USER PID %CPU %MEM VSZ RSS TT STAT STARTED TIME COMMAND USER PID %CPU %MEM VSZ RSS TT STAT STARTED TIME COMMAND
root 71464 0.0 0.0 14536 2000 - IsJ 4:52PM 0:00.00 /usr/sbin/syslogd -ss root 71464 0.0 0.0 14536 2000 - IsJ 4:52PM 0:00.00 /usr/sbin/syslogd -ss
@@ -348,80 +393,39 @@ root 80591 0.0 0.0 18784 2340 1 R+J 4:53PM 0:00.00 ps -auxw
bastille pkg bastille pkg
------------ ------------
To manage binary packages within the jail use `bastille pkg`. To manage binary packages within the container use `bastille pkg`.
```shell ```shell
ishmael ~ # bastille pkg folsom 'install vim-console git-lite zsh' ishmael ~ # bastille pkg folsom install vim-console git-lite zsh
[folsom]: [folsom]:
The package management tool is not yet installed on your system.
Do you want to fetch and install it now? [y/N]: y
Bootstrapping pkg from pkg+http://pkg.FreeBSD.org/FreeBSD:10:amd64/quarterly, please wait...
Verifying signature with trusted certificate pkg.freebsd.org.2013102301... done
[folsom] Installing pkg-1.10.5_5...
[folsom] Extracting pkg-1.10.5_5: 100%
Updating FreeBSD repository catalogue... Updating FreeBSD repository catalogue...
pkg: Repository FreeBSD load error: access repo file(/var/db/pkg/repo-FreeBSD.sqlite) failed: No such file or directory
[folsom] Fetching meta.txz: 100% 944 B 0.9kB/s 00:01 [folsom] Fetching meta.txz: 100% 944 B 0.9kB/s 00:01
[folsom] Fetching packagesite.txz: 100% 6 MiB 3.4MB/s 00:02 [folsom] Fetching packagesite.txz: 100% 6 MiB 6.6MB/s 00:01
Processing entries: 100% Processing entries: 100%
FreeBSD repository update completed. 32550 packages processed. FreeBSD repository update completed. 32617 packages processed.
All repositories are up to date. All repositories are up to date.
Updating database digests format: 100% Updating database digests format: 100%
The following 10 package(s) will be affected (of 0 checked): The following 10 package(s) will be affected (of 0 checked):
New packages to be INSTALLED: New packages to be INSTALLED:
vim-console: 8.1.0342 vim-console: 8.1.1954
git-lite: 2.19.1 git-lite: 2.23.0
zsh: 5.6.2 zsh: 5.7.1_1
expat: 2.2.6_1 expat: 2.2.8
curl: 7.61.1 curl: 7.66.0
libnghttp2: 1.33.0 libnghttp2: 1.39.2
ca_root_nss: 3.40 ca_root_nss: 3.47.1
pcre: 8.42 pcre: 8.43_2
gettext-runtime: 0.19.8.1_1 gettext-runtime: 0.20.1
indexinfo: 0.3.1 indexinfo: 0.3.1
Number of packages to be installed: 10 Number of packages to be installed: 10
The process will require 77 MiB more space. The process will require 87 MiB more space.
17 MiB to be downloaded. 18 MiB to be downloaded.
Proceed with this action? [y/N]: y Proceed with this action? [y/N]:
[folsom] [1/10] Fetching vim-console-8.1.0342.txz: 100% 5 MiB 5.8MB/s 00:01 ...[snip]...
[folsom] [2/10] Fetching git-lite-2.19.1.txz: 100% 4 MiB 2.1MB/s 00:02
[folsom] [3/10] Fetching zsh-5.6.2.txz: 100% 4 MiB 4.4MB/s 00:01
[folsom] [4/10] Fetching expat-2.2.6_1.txz: 100% 109 KiB 111.8kB/s 00:01
[folsom] [5/10] Fetching curl-7.61.1.txz: 100% 1 MiB 1.2MB/s 00:01
[folsom] [6/10] Fetching libnghttp2-1.33.0.txz: 100% 107 KiB 109.8kB/s 00:01
[folsom] [7/10] Fetching ca_root_nss-3.40.txz: 100% 287 KiB 294.3kB/s 00:01
[folsom] [8/10] Fetching pcre-8.42.txz: 100% 1 MiB 1.2MB/s 00:01
[folsom] [9/10] Fetching gettext-runtime-0.19.8.1_1.txz: 100% 148 KiB 151.3kB/s 00:01
[folsom] [10/10] Fetching indexinfo-0.3.1.txz: 100% 6 KiB 5.7kB/s 00:01
Checking integrity... done (0 conflicting)
[folsom] [1/10] Installing libnghttp2-1.33.0...
[folsom] [1/10] Extracting libnghttp2-1.33.0: 100%
[folsom] [2/10] Installing ca_root_nss-3.40...
[folsom] [2/10] Extracting ca_root_nss-3.40: 100%
[folsom] [3/10] Installing indexinfo-0.3.1...
[folsom] [3/10] Extracting indexinfo-0.3.1: 100%
[folsom] [4/10] Installing expat-2.2.6_1...
[folsom] [4/10] Extracting expat-2.2.6_1: 100%
[folsom] [5/10] Installing curl-7.61.1...
[folsom] [5/10] Extracting curl-7.61.1: 100%
[folsom] [6/10] Installing pcre-8.42...
[folsom] [6/10] Extracting pcre-8.42: 100%
[folsom] [7/10] Installing gettext-runtime-0.19.8.1_1...
[folsom] [7/10] Extracting gettext-runtime-0.19.8.1_1: 100%
[folsom] [8/10] Installing vim-console-8.1.0342...
[folsom] [8/10] Extracting vim-console-8.1.0342: 100%
[folsom] [9/10] Installing git-lite-2.19.1...
===> Creating groups.
Creating group 'git_daemon' with gid '964'.
===> Creating users
Creating user 'git_daemon' with uid '964'.
[folsom] [9/10] Extracting git-lite-2.19.1: 100%
[folsom] [10/10] Installing zsh-5.6.2...
[folsom] [10/10] Extracting zsh-5.6.2: 100%
``` ```
The PKG sub-command can, of course, do more than just `install`. The The PKG sub-command can, of course, do more than just `install`. The
@@ -511,8 +515,8 @@ You may need to manually remove /usr/local/etc/nginx/nginx.conf if it is no long
bastille destroy bastille destroy
---------------- ----------------
Jails can be destroyed and thrown away just as easily as they were created. Containers can be destroyed and thrown away just as easily as they were
Note: jails must be stopped before destroyed. created. Note: containers must be stopped before destroyed.
```shell ```shell
ishmael ~ # bastille stop folsom ishmael ~ # bastille stop folsom
@@ -520,8 +524,8 @@ ishmael ~ # bastille stop folsom
folsom: removed folsom: removed
ishmael ~ # bastille destroy folsom ishmael ~ # bastille destroy folsom
Deleting Jail: folsom. Deleting Container: folsom.
Note: jail console logs not destroyed. Note: container console logs not destroyed.
/usr/local/bastille/logs/folsom_console.log /usr/local/bastille/logs/folsom_console.log
``` ```
@@ -529,7 +533,7 @@ Note: jail console logs not destroyed.
bastille template bastille template
----------------- -----------------
Bastille supports a templating system allowing you to apply files, pkgs and Bastille supports a templating system allowing you to apply files, pkgs and
execute commands inside the jail automatically. execute commands inside the container automatically.
Currently supported template hooks are: `PRE`, `CONFIG`, `PKG`, `SYSRC`, `CMD`. Currently supported template hooks are: `PRE`, `CONFIG`, `PKG`, `SYSRC`, `CMD`.
Planned template hooks include: `FSTAB`, `PF`, `LOG` Planned template hooks include: `FSTAB`, `PF`, `LOG`
@@ -538,16 +542,16 @@ Templates are created in `${bastille_prefix}/templates` and can leverage any of
the template hooks. Simply create a new directory named after the template. eg; the template hooks. Simply create a new directory named after the template. eg;
```shell ```shell
mkdir -p /usr/local/bastille/templates/base mkdir -p /usr/local/bastille/templates/username/base
``` ```
To leverage a template hook, create an UPPERCASE file in the root of the To leverage a template hook, create an UPPERCASE file in the root of the
template directory named after the hook you want to execute. eg; template directory named after the hook you want to execute. eg;
```shell ```shell
echo "zsh vim-console git-lite htop" > /usr/local/bastille/templates/base/PKG echo "install zsh vim-console git-lite htop" > /usr/local/bastille/templates/base/PKG
echo "/usr/bin/chsh -s /usr/local/bin/zsh" > /usr/local/bastille/templates/base/CMD echo "/usr/bin/chsh -s /usr/local/bin/zsh" > /usr/local/bastille/templates/base/CMD
echo "etc root usr" > /usr/local/bastille/templates/base/CONFIG echo "etc\nroot\nusr" > /usr/local/bastille/templates/base/OVERLAY
``` ```
Template hooks are executed in specific order and require specific syntax to Template hooks are executed in specific order and require specific syntax to
@@ -564,29 +568,30 @@ work as expected. This table outlines those requirements:
|---------|------------------|----------------------------------------------------------------| |---------|------------------|----------------------------------------------------------------|
| PF | pf rdr entry | rdr pass inet proto tcp from any to any port 80 -> 10.17.89.80 | | PF | pf rdr entry | rdr pass inet proto tcp from any to any port 80 -> 10.17.89.80 |
| LOG | path | /var/log/nginx/access.log | | LOG | path | /var/log/nginx/access.log |
| FSTAB | fstab syntax | /path/on/host /path/in/jail nullfs ro 0 0 | | FSTAB | fstab syntax | /path/on/host /path/in/container nullfs ro 0 0 |
Note: SYSRC requires NO quotes or that quotes (`"`) be escaped. ie; `\"`) Note: SYSRC requires NO quotes or that quotes (`"`) be escaped. ie; `\"`)
In addition to supporting template hooks, Bastille supports overlaying files In addition to supporting template hooks, Bastille supports overlaying files
into the jail. This is done by placing the files in their full path, using the into the container. This is done by placing the files in their full path, using the
template directory as "/". template directory as "/".
An example here may help. Think of `/usr/local/bastille/templates/base`, our An example here may help. Think of
example template, as the root of our filesystem overlay. If you create an `/usr/local/bastille/templates/username/base`, our example template, as the
`etc/hosts` or `etc/resolv.conf` *inside* the base template directory, these root of our filesystem overlay. If you create an `etc/hosts` or
can be overlayed into your jail. `etc/resolv.conf` *inside* the base template directory, these can be overlayed
into your container.
Note: due to the way FreeBSD segregates user-space, the majority of your Note: due to the way FreeBSD segregates user-space, the majority of your
overlayed template files will be in `usr/local`. The few general overlayed template files will be in `usr/local`. The few general
exceptions are the `etc/hosts`, `etc/resolv.conf`, and `etc/rc.conf.local`. exceptions are the `etc/hosts`, `etc/resolv.conf`, and `etc/rc.conf.local`, etc.
After populating `usr/local/` with custom config files that your jail will After populating `usr/local/` with custom config files that your container will
use, be sure to include `usr` in the template CONFIG definition. eg; use, be sure to include `usr` in the template OVERLAY definition. eg;
```shell ```shell
echo "etc" > /usr/local/bastille/templates/base/OVERLAY echo "etc" > /usr/local/bastille/templates/username/base/OVERLAY
echo "usr" >> /usr/local/bastille/templates/base/OVERLAY echo "usr" >> /usr/local/bastille/templates/username/base/OVERLAY
``` ```
The above example will include anything under "etc" and "usr" inside The above example will include anything under "etc" and "usr" inside
@@ -597,14 +602,14 @@ top-level directory name.
Applying Templates Applying Templates
------------------ ------------------
Jails must be running to apply templates. Containers must be running to apply templates.
Bastille includes a `template` sub-command. This sub-command requires a target Bastille includes a `template` sub-command. This sub-command requires a target
and a template name. As covered in the previous section, template names and a template name. As covered in the previous section, template names
correspond to directory names in the `bastille/templates` directory. correspond to directory names in the `bastille/templates` directory.
```shell ```shell
ishmael ~ # bastille template folsom base ishmael ~ # bastille template folsom username/base
[folsom]: [folsom]:
Copying files... Copying files...
Copy complete. Copy complete.
@@ -619,20 +624,20 @@ Template Complete.
bastille top bastille top
------------ ------------
This one simply runs `top` in that jail. This command is interactive, as `top` This one simply runs `top` in that container. This command is interactive, as
is interactive. `top` is interactive.
bastille htop bastille htop
------------- -------------
This one simply runs `htop` inside the jail. This one is a quick and dirty This one simply runs `htop` inside the container. This one is a quick and dirty
addition. note: won't work if you don't have htop installed in the jail. addition. note: won't work if you don't have htop installed in the container.
bastille sysrc bastille sysrc
-------------- --------------
The `sysrc` sub-command allows for safely editing system configuration files. The `sysrc` sub-command allows for safely editing system configuration files.
In jail terms, this allows us to toggle on/off services and options at In container terms, this allows us to toggle on/off services and options at
startup. startup.
```shell ```shell
@@ -646,13 +651,14 @@ See `man sysrc(8)` for more info.
bastille console bastille console
---------------- ----------------
This sub-command launches a login shell into the jail. Default is This sub-command launches a login shell into the container. Default is
password-less root login. password-less root login. If you provide an additional argument of a username
you will be logged in as that user. (user must be created first)
```shell ```shell
ishmael ~ # bastille console folsom ishmael ~ # bastille console folsom
[folsom]: [folsom]:
FreeBSD 11.2-RELEASE-p4 (GENERIC) #0: Thu Sep 27 08:16:24 UTC 2018 FreeBSD 11.3-RELEASE-p4 (GENERIC) #0: Thu Sep 27 08:16:24 UTC 2018
Welcome to FreeBSD! Welcome to FreeBSD!
@@ -676,59 +682,37 @@ Edit /etc/motd to change this login announcement.
root@folsom:~ # root@folsom:~ #
``` ```
At this point you are logged in to the jail and have full shell access. At this point you are logged in to the container and have full shell access.
The system is yours to use and/or abuse as you like. Any changes made inside The system is yours to use and/or abuse as you like. Any changes made inside
the jail are limited to the jail. the container are limited to the container.
bastille cp bastille cp
----------- -----------
Note: this sub-command may need a little work. This sub-command allows efficiently copying files from host to container(s).
This sub-command allows efficiently copying files from host to jail(s).
```shell ```shell
ishmael ~ # bastille cp ALL /tmp/resolv.conf-cf etc/resolv.conf ishmael ~ # bastille cp ALL /tmp/resolv.conf-cf etc/resolv.conf
[bastion]: [folsom]:
/tmp/resolv.conf-cf -> /usr/local/bastille/jails/folsom/root/etc/resolv.conf
[unbound0]:
[unbound1]:
[squid]:
[nginx]: [nginx]:
/tmp/resolv.conf-cf -> /usr/local/bastille/jails/nginx/root/etc/resolv.conf
[folsom]: [squid]:
/tmp/resolv.conf-cf -> /usr/local/bastille/jails/squid/root/etc/resolv.conf
[unbound0]:
/tmp/resolv.conf-cf -> /usr/local/bastille/jails/unbound0/root/etc/resolv.conf
``` ```
Unless you see errors reported in the output the `cp` was successful.
bastille list
-------------
This sub-command will show you the running jails on your system.
```shell
ishmael ~ # bastille list
JID IP Address Hostname Path
bastion 10.17.89.65 bastion /usr/local/bastille/jails/bastion/root
unbound0 10.17.89.60 unbound0 /usr/local/bastille/jails/unbound0/root
unbound1 10.17.89.61 unbound1 /usr/local/bastille/jails/unbound1/root
squid 10.17.89.30 squid /usr/local/bastille/jails/squid/root
nginx 10.17.89.45 nginx /usr/local/bastille/jails/nginx/root
folsom 10.17.89.10 folsom /usr/local/bastille/jails/folsom/root
```
bastille update bastille update
--------------- ---------------
The `update` command targets a release instead of a jail. Because every The `update` command targets a release instead of a container. Because every
jail is based on a release, when the release is updated all the jails are container is based on a release, when the release is updated all the containers
automatically updated as well. are automatically updated as well.
To update all jails based on the 11.2-RELEASE `release`: To update all containers based on the 11.2-RELEASE `release`:
Up to date 11.2-RELEASE: Up to date 11.2-RELEASE:
```shell ```shell
@@ -746,27 +730,7 @@ No updates needed to update system to 11.2-RELEASE-p4.
No updates are available to install. No updates are available to install.
``` ```
Updating 10.4-RELEASE: To be safe, you may want to restart any containers that have been updated live.
```shell
ishmael ~ # bastille update 10.4-RELEASE
Targeting specified release.
10.4-RELEASE
Looking up update.FreeBSD.org mirrors... 2 mirrors found.
Fetching metadata signature for 10.4-RELEASE from update1.freebsd.org... done.
Fetching metadata index... done.
Fetching 2 metadata patches.. done.
Applying metadata patches... done.
Fetching 2 metadata files... done.
Inspecting system... done.
Preparing to download files... done.
The following files will be added as part of updating to 10.4-RELEASE-p13:
...[snip]...
```
To be safe, you may want to restart any jails that have been updated
live.
bastille upgrade bastille upgrade
@@ -775,7 +739,7 @@ This sub-command lets you upgrade a release to a new release. Depending on the
workflow this can be similar to a `bootstrap`. workflow this can be similar to a `bootstrap`.
```shell ```shell
ishmael ~ # bastille upgrade 11.2-RELEASE 12.0-RELEASE ishmael ~ # bastille upgrade 11.3-RELEASE 12.0-RELEASE
... ...
``` ```
@@ -789,15 +753,19 @@ release against a "known good" index.
If you see errors or issues here, consider deleting and re-bootstrapping the If you see errors or issues here, consider deleting and re-bootstrapping the
release. release.
It should be noted that releases bootstrapped through Bastille are validated
using `sha256` checksum against the release manifest. Archives that fail
validation are not used.
bastille zfs bastille zfs
------------ ------------
This sub-command allows managing zfs attributes for the targeted jail(s). This sub-command allows managing zfs attributes for the targeted container(s).
Common usage includes setting jail quotas. Common usage includes setting container quotas.
** set quota ** ** set quota **
```shell ```shell
ishmael ~ # bastille zfs folsom 'set quota=1G' ishmael ~ # bastille zfs folsom set quota=1G
``` ```
** built-in: df ** ** built-in: df **
@@ -813,7 +781,7 @@ ishmael ~ # bastille zfs folsom df
Example (create, start, console) Example (create, start, console)
================================ ================================
This example creates, starts and consoles into the jail. This example creates, starts and consoles into the container.
```shell ```shell
ishmael ~ # bastille create alcatraz 11.2-RELEASE 10.17.89.7 ishmael ~ # bastille create alcatraz 11.2-RELEASE 10.17.89.7
@@ -872,14 +840,14 @@ Project Goals
============= =============
These tools are created initially with the mindset of function over form. I 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 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 sort of meta-container-port system. Instead of installing the MySQL port
a system, you would use Bastille to install the MySQL port within a jail directly on a system, you would use Bastille to install the MySQL port within a
template built for MySQL. The same goes for DNS servers, and everything else in container template built for MySQL. The same goes for DNS servers, and
the ports tree. everything else in the ports tree.
Eventually I would like to have Bastille templates created for popular Eventually I would like to have Bastille templates created for popular
FreeBSD-based services. From Plex Media Servers to ad-blocking DNS resolvers. FreeBSD-based services. From Plex Media Servers to ad-blocking DNS resolvers.
From tiny SSH jails to dynamic web servers. From tiny SSH containers to dynamic web servers. [COMPLETE]
I don't want to tell you what you can and can't run within this framework. 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 There are no arbitrary limitations based on what I think may or may not be the
@@ -887,35 +855,7 @@ best way to design systems. This is not my goal.
My goal is to provide a secure framework where processes and services can run 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 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. limit the target areas available to anyone that has (or has gained) access.
Possible Jail names
-------------------
prisons:
- alcatraz
- arkham
- ashecliffe
- astralqueen
- attica
- azkaban
- coldmountain
- corcoran
- dolguldur
- folsom
- foxriver
- leavenworth
- litchfield
- oswald
- pelicanbay
- rikers
- sanquentin
- shawshank
- singsing
- stockton
- stormcage
- ziggurat
Networking Tips Networking Tips
=============== ===============
@@ -928,7 +868,8 @@ rdr pass inet proto tcp from any to any port {80, 443} -> {10.17.89.45, 10.17.89
``` ```
This rule would redirect any traffic to the host on ports 80 or 443 and This rule would redirect any traffic to the host on ports 80 or 443 and
round-robin between jails with ips 45, 46, 47, and 48 (on ports 80 or 443). round-robin between containers with ips 45, 46, 47, and 48 (on ports 80 or
443).
Tip #2: Tip #2:
@@ -943,22 +884,14 @@ rdr pass inet proto tcp from any to any port 8181 -> 10.17.89.5 port 443
Tip #3: Tip #3:
------- -------
Don't worry too much about IP assignments. Don't worry too much about IP assignments.
Initially I spent time worrying about what IP addresses to assign. In the
end I've come to the conclusion that it _really_ doesn't matter. Pick *any* Initially I spent time worrying about what IP addresses to assign. In the end
private address and be done with it. These are all isolated networks. In the I've come to the conclusion that it _really_ doesn't matter. Pick *any* private
end, what matters is you can map host:port to jail:port reliably, and we address and be done with it. These are all isolated networks. In the end, what
can. matters is you can map host:port to container:port reliably, and we can.
Community Support Community Support
================= =================
We would love to hear your feedback on Bastille! Please join us in the
[#bastillebsd](ircs://chat.freenode.net:6697/bastillebsd) and let us know what
you think.
Be mindful of the [Bastille Code of
Conduct](https://github.com/BastilleBSD/bastille/blob/master/CODE-OF-CONDUCT.md)
when participating in the chat rooms.
If you've found a bug in Bastille, please submit it to the [Bastille Issue If you've found a bug in Bastille, please submit it to the [Bastille Issue
Tracker](https://github.com/bastillebsd/bastille/issues/new). Tracker](https://github.com/bastillebsd/bastille/issues/new).