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

updating documentation for 0.4.20191025

Browse Source
This commit is contained in:
Christer Edwards
2019-11-20 18:54:05 -07:00
parent 481dc5111f
commit 7e2b03b73b
14 changed files with 494 additions and 141 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
docs/chapters/installation.rst
View File

@@ -1,30 +1,27 @@
Installation
============
Bastille is available in the official FreeBSD ports tree at
`sysutils/bastille`. Binary packages available in `quarterly` and `latest`
repositories.
Bastille is not (yet) in the official ports tree, but I have built and
verified binary packages.
Current version is `0.3.20191025`.
To install using one of the BETA binary packages, copy the URL for the
latest release here (TXZ file):
https://github.com/bastillebsd/bastille/releases
To install from the FreeBSD package repository:
Then, install via pkg.
Example:
* quarterly repository may be older version
* latest repository will match recent ports
.. code-block:: shell
pkg add https://github.com/BastilleBSD/bastille/releases/download/0.3.20181124/bastille-0.3.20181124.txz
PKG
---
```shell
pkg install bastille
```
BETA binary packages are signed. These can be verified with this pubkey:
To install from source (don't worry, no compiling):
.. code-block:: shell
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAq28OLDhJ12JmsKKcJpnn
pCW3fFYBNI1BtdvTvFx57ZXvQ2qecBvnR9+XWi83hKS9ALTKZI6CLC2uTv1fIsZl
u6rDRRNZwZFfITACSfwI+7UObMXz3oBZjk94J3rIegk49EyjDswKdVWv5k1EiVXF
SAwXSl2kA2hGfQJkj5NS4nrfoRBc0z6fm+BGdNuHKSTmeZh1dbLEHt9EArD20DJ7
HIr8vUSPLwONeqJCBFA/MeDO+GpwtwA/ldc2ZZy1RCPctdC2NeiGW7oy1yVDu6wp
mHCq8qDfmCx5Aex84rWUf9iH8TM92AWmegTaz2p+BgESctpjNRCUuSEwOCBIO6g5
3wIDAQAB
-----END PUBLIC KEY-----
ports
-----
```shell
make -C /usr/ports/sysutils/bastille install clean
```

204
docs/chapters/jail-config.rst Normal file
View File

@@ -0,0 +1,204 @@
jail.conf
=========
In this section we'll look at the default config for a new container. The
defaults are sane for most applications, but if you want to tweak the settings
here they are.
A `jail.conf` template is used each time a new container is created. This
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} {
ip4.addr = x.x.x.x;
}
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
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.

109
docs/chapters/networking.rst
View File

@@ -1,71 +1,134 @@
====================
Network Requirements
====================
Here's the scenario. You've installed Bastille at home or in the cloud and want
to get started putting applications in secure little containers, but how do I
get these containers on the network?
In order to segregate jails from the network and from the world, Bastille
attaches jails to a loopback interface only. The host system then acts as
the firewall, permitting and denying traffic as needed.
Bastille tries to be flexible about how to network containerized applications.
The two most common methods are described here. Consider both options to decide
which design work best for your needs. One of the methods works better across
clouds while the other is simpler if used in local area networks.
As you've probably seen, Bastille containers require certain information when
they are created. An IP address has to be assigned to the container through
which all network traffic will flow.
When the container is started the IP address assigned at creation will be bound
to a network interface. In FreeBSD these interfaces have different names, but
look something like `em0`, `bge0`, `re0`, etc. On a virtual machine it may be
`vtnet0`. You get the idea...
**Note: if you are running in the cloud and only have a single public IP you
may want the Public Network option. See below.**
Local Area Network
------------------
I will cover the local area network (LAN) method first. This method is simpler
to get going and works well in a home network (or similar) where adding alias
IP addresses is no problem.
Bastille allows you to define the interface you want the IP attached to when
you create it. An example:
```shell
bastille create alcatraz 12.1-RELEASE 192.168.1.50 em0
```
When the `alcatraz` container is started it will add `192.168.1.60` as an IP
alias to the `em0` interface. It will then simply be another member of the
hosts network. Other networked systems (firewall permitting) should be able to
reach services at that address.
This method is the simplest. All you need to know is the name of your network
interface and a free IP on your current network.
(Bastille does try to verify that the interface name you provide it is a valid
interface. This validation has not been exhaustively tested yet in Bastille's
beta state.)
Public Network
--------------
In this section I'll describe how to network containers in a public network
such as a cloud hosting provider (AWS, digital ocean, vultr, etc)
In the public cloud you don't often have access to multiple private IP
addresses for your virtual machines. This means if you want to create multiple
containers and assign them all IP addresses, you'll need to create a new
network.
What I recommend is creating a cloned loopback interface (`bastille0`) and
assigning all the containers private (rfc1918) addresses on that interface. The
setup I develop on and use Bastille day to day uses the `10.0.0.0/8` address
range. I have the ability to use whatever address I want within that range
because I've created my own private network. The host system then acts as the
firewall, permitting and denying traffic as needed.
I find this setup the most flexible across all types of networks. It can be
used in public and private networks just the same and it allows me to keep
containers off the network until I allow access.
Having said all that here are instructions I used to configure the network with
a private loopback interface and system firewall. The system firewall NATs
traffic out of containers and can selectively redirect traffic into containers
based on connection ports (ie; 80, 443, etc.)
First, create the loopback interface:
.. code-block:: shell
ishmael ~ # sysrc cloned_interfaces+=lo1
ishmael ~ # ifconfig_lo1_name="bastille0"
ishmael ~ # service netif cloneup
Second, enable NAT through the firewall:
Second, enable the firewall:
.. code-block:: shell
ishmael ~ # sysrc pf_enable="YES"
Create the firewall rules:
/etc/pf.conf
------------
Create the firewall config, or merge as necessary.
.. code-block:: shell
ext_if="vtnet0"
set block-policy drop
set block-policy return
scrub in on $ext_if all fragment reassemble
set skip on lo
nat on $ext_if from !($ext_if) -> ($ext_if:0)
nat on $ext_if from bastille0:network to any -> ($ext_if)
## rdr example
## rdr pass inet proto tcp from any to any port {80, 443} -> 10.88.9.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
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 modulate state
- 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 out.
Note: if you have an existing firewall, the key lines for in/out traffic
to jails are:
.. code-block:: shell
nat on $ext_if from lo1:network to any -> ($ext_if)
nat on $ext_if from bastille0:network to any -> ($ext_if)
## rdr example
## rdr pass inet proto tcp from any to any port {80, 443} -> 10.88.9.45
## rdr pass inet proto tcp from any to any port {80, 443} -> 10.17.89.45
The `nat` routes traffic from the loopback interface to the external
interface for outbound access.
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 jails at `10.88.9.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.
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
jails at `10.17.89.45`.
Finally, start up the firewall:

102
docs/chapters/subcommands/bootstrap.rst
View File

@@ -1,34 +1,100 @@
=========
bootstrap
=========
The first step is to "bootstrap" a release. Current supported release is
11.2-RELEASE, but you can bootstrap anything in the ftp.FreeBSD.org
RELEASES directory.
The bootstrap sub-command is used to download and extract releases and
templates for use with Bastille containers. A valid release is needed before
containers can be created. Templates are optional but are managed in the same
manner.
Note: your mileage may vary with unsupported releases and releases newer
than the host system likely will NOT work at all.
than the host system likely will NOT work at all. Bastille tries to filter for
valid release names. If you find it will not bootstrap a valid release, please
let us know.
In this document we will describe using the `bootstrap` sub-command with both
releases and templates. We begin with releases.
Releases
========
Example
-------
To `bootstrap` a release, run the bootstrap sub-command with the
release version as the argument.
.. code-block:: shell
ishmael ~ # bastille bootstrap 11.2-RELEASE
ishmael ~ # bastille bootstrap 11.3-RELEASE [update]
ishmael ~ # bastille bootstrap 12.0-RELEASE
ishmael ~ # bastille bootstrap 12.1-RELEASE
This command will ensure the required directory structures are in place
and download the requested release. For each requested release,
`bootstrap` will download the base.txz and lib32.txz. These are both
verified (sha256 via MANIFEST file) before they are extracted for use.
This command will ensure the required directory structures are in place and
download the requested release. For each requested release, `bootstrap` will
download the base.txz. These files are verified (sha256 via MANIFEST file)
before they are extracted for use.
Downloaded artifacts are stored in the `cache` directory. "bootstrapped"
releases are stored in `releases/version`.
Tips
----
The bootstrap subcommand is generally only used once to prepare the
system. The only other use case for the bootstrap command is when a new
FreeBSD version is released and you want to start building jails on that
version.
The `bootstrap` sub-command can now take (0.5.20191125+) an optional second
argument of "update". If this argument is used, `bastille update` will be run
immediately after the bootstrap, effectively bootstrapping and applying
security patches and errata in one motion.
To update a release as patches are made available, see the `bastille
update` command.
Notes
-----
The bootstrap subcommand is generally only used once to prepare the system. The
only other use case for the bootstrap command is when a new FreeBSD version is
released and you want to start deploying containers on that version.
To update a release as patches are made available, see the `bastille update`
command.
Downloaded artifacts are stored in the `bastille/cache/version` directory.
"bootstrapped" releases are stored in `bastille/releases/version`.
To manually bootstrap a release (aka bring your own archive), place your
archive in bastille/cache/name and extract to bastille/releases/name. Your
mileage may vary; let me know what happens.
Templates
=========
Bastille aims to integrate container automation into the platform while
maintaining a simple, uncomplicated design. Templates are git repositories with
automation definitions for packages, services, file overlays, etc.
To download one of these templates see the example below.
Example
-------
.. code-block:: shell
ishmael ~ # bastille bootstrap https://gitlab.com/bastillebsd-templates/nginx
ishmael ~ # bastille bootstrap https://gitlab.com/bastillebsd-templates/mariadb-server
ishmael ~ # bastille bootstrap https://gitlab.com/bastillebsd-templates/python3
Tips
----
See the documentation on templates for more information on how they work and
how you can create or customize your own. Templates are a powerful part of
Bastille and facilitate full container automation.
Notes
-----
If you don't want to bother with git to use templates you can create them
manually on the Bastille system and apply them.
Templates are stored in `bastille/templates/namespace/name`. If you'd like to
create a new template on your local system, simply create a new namespace
within the templates directory and then one for the template. This namespacing
allows users and groups to have templates without conflicting template names.
Once you've created the directory structure you can begin filling it with
template hooks. Once you have a minimum number of hooks (at least one) you can
begin applying your template.

12
docs/chapters/subcommands/console.rst
View File

@@ -1,14 +1,14 @@
console
=======
This sub-command launches a login shell into the jail. Default is
password-less root login.
This sub-command launches a login shell into the jail. Default is password-less
root login.
.. code-block:: shell
ishmael ~ # bastille console folsom
[folsom]:
FreeBSD 11.2-RELEASE-p4 (GENERIC) #0: Thu Sep 27 08:16:24 UTC 2018
FreeBSD 12.1-RELEASE-p1 GENERIC
Welcome to FreeBSD!
@@ -31,6 +31,6 @@ password-less root login.
Edit /etc/motd to change this login announcement.
root@folsom:~ #
At this point you are logged in to the jail and have full shell access.
The system is yours to use and/or abuse as you like. Any changes made
inside the jail are limited to the jail.
At this point you are logged in to the jail and have full shell access. The
system is yours to use and/or abuse as you like. Any changes made inside the
jail are limited to the jail.

18
docs/chapters/subcommands/create.rst
View File

@@ -1,4 +1,3 @@
======
create
======
@@ -9,24 +8,25 @@ bootstrapped release and a private (rfc1918) IP address.
- name
- release
- ip
- interface (optional)
.. code-block:: shell
ishmael ~ # bastille create folsom 11.2-RELEASE 10.8.62.1
ishmael ~ # bastille create folsom 11.3-RELEASE 10.17.89.10 [interface]
RELEASE: 11.2-RELEASE.
RELEASE: 11.3-RELEASE.
NAME: folsom.
IP: 10.8.62.1.
IP: 10.17.89.10.
This command will create a 11.2-RELEASE jail assigning the 10.8.62.1 ip
This command will create a 11.3-RELEASE jail assigning the 10.17.89.10 ip
address to the new system.
I recommend using private (rfc1918) ip address ranges for your jails.
These ranges include:
I recommend using private (rfc1918) ip address ranges for your jails. These
ranges include:
- 10.0.0.0/8
- 172.16.0.0/12
- 192.168.0.0/16
Bastille does its best to validate the submitted ip is valid. This has not
been thouroughly tested--I generally use the 10/8 range.
Bastille does its best to validate the submitted ip is valid. This has not been
thouroughly tested--I generally use the 10/8 range.

1
docs/chapters/subcommands/index.rst
View File

@@ -14,6 +14,7 @@ Bastille sub-commands
htop
pkg
restart
service
start
stop
sysrc

20
docs/chapters/subcommands/pkg.rst
View File

@@ -87,11 +87,11 @@ expectation is that you can fully leverage the pkg manager. This means,
ishmael ~ # bastille pkg ALL upgrade
[bastion]:
Updating iniquity.io repository catalogue...
Updating pkg.bastillebsd.org repository catalogue...
[bastion] Fetching meta.txz: 100% 560 B 0.6kB/s 00:01
[bastion] Fetching packagesite.txz: 100% 118 KiB 121.3kB/s 00:01
Processing entries: 100%
iniquity.io repository update completed. 493 packages processed.
pkg.bastillebsd.org repository update completed. 493 packages processed.
All repositories are up to date.
Checking for upgrades (1 candidates): 100%
Processing candidates (1 candidates): 100%
@@ -99,11 +99,11 @@ expectation is that you can fully leverage the pkg manager. This means,
Your packages are up to date.
[unbound0]:
Updating iniquity.io repository catalogue...
Updating pkg.bastillebsd.org repository catalogue...
[unbound0] Fetching meta.txz: 100% 560 B 0.6kB/s 00:01
[unbound0] Fetching packagesite.txz: 100% 118 KiB 121.3kB/s 00:01
Processing entries: 100%
iniquity.io repository update completed. 493 packages processed.
pkg.bastillebsd.org repository update completed. 493 packages processed.
All repositories are up to date.
Checking for upgrades (0 candidates): 100%
Processing candidates (0 candidates): 100%
@@ -111,11 +111,11 @@ expectation is that you can fully leverage the pkg manager. This means,
Your packages are up to date.
[unbound1]:
Updating iniquity.io repository catalogue...
Updating pkg.bastillebsd.org repository catalogue...
[unbound1] Fetching meta.txz: 100% 560 B 0.6kB/s 00:01
[unbound1] Fetching packagesite.txz: 100% 118 KiB 121.3kB/s 00:01
Processing entries: 100%
iniquity.io repository update completed. 493 packages processed.
pkg.bastillebsd.org repository update completed. 493 packages processed.
All repositories are up to date.
Checking for upgrades (0 candidates): 100%
Processing candidates (0 candidates): 100%
@@ -123,11 +123,11 @@ expectation is that you can fully leverage the pkg manager. This means,
Your packages are up to date.
[squid]:
Updating iniquity.io repository catalogue...
Updating pkg.bastillebsd.org repository catalogue...
[squid] Fetching meta.txz: 100% 560 B 0.6kB/s 00:01
[squid] Fetching packagesite.txz: 100% 118 KiB 121.3kB/s 00:01
Processing entries: 100%
iniquity.io repository update completed. 493 packages processed.
pkg.bastillebsd.org repository update completed. 493 packages processed.
All repositories are up to date.
Checking for upgrades (0 candidates): 100%
Processing candidates (0 candidates): 100%
@@ -135,11 +135,11 @@ expectation is that you can fully leverage the pkg manager. This means,
Your packages are up to date.
[nginx]:
Updating iniquity.io repository catalogue...
Updating pkg.bastillebsd.org repository catalogue...
[nginx] Fetching meta.txz: 100% 560 B 0.6kB/s 00:01
[nginx] Fetching packagesite.txz: 100% 118 KiB 121.3kB/s 00:01
Processing entries: 100%
iniquity.io repository update completed. 493 packages processed.
pkg.bastillebsd.org repository update completed. 493 packages processed.
All repositories are up to date.
Checking for upgrades (1 candidates): 100%
Processing candidates (1 candidates): 100%

13
docs/chapters/subcommands/service.rst Normal file
View File

@@ -0,0 +1,13 @@
=======
service
=======
The `service` sub-command allows for managing services within containers. This
allows you to start, stop, restart, and otherwise interact with services
running inside the containers.
.. code-block:: shell
ishmael ~ # bastille service web01 'nginx start'
ishmael ~ # bastille service db01 'mysql-server restart'
ishmael ~ # bastille service proxy 'nginx configtest'

13
docs/chapters/targeting.rst
View File

@@ -1,4 +1,3 @@
=========
Targeting
=========
@@ -22,7 +21,6 @@ Examples: Jails
ishmael ~ # bastille ...
+-----------+--------+------------------+-------------------------------------------------------------+
| command | target | args | description |
+===========+========+==================+=============================================================+
@@ -38,13 +36,13 @@ Examples: Jails
+-----------+--------+------------------+-------------------------------------------------------------+
| sysrc | web01 | nginx_enable=YES | execute `sysrc nginx_enable=YES` in web01 jail |
+-----------+--------+------------------+-------------------------------------------------------------+
| template | ALL | base | apply `base` template to ALL jails |
| template | ALL | username/base | apply `username/base` template to ALL jails |
+-----------+--------+------------------+-------------------------------------------------------------+
| start | web02 | --- | start web02 jail |
+-----------+--------+-----+------------+-------------------------------------------------------------+
| cp | bastion03 | /tmp/resolv.conf-cf etc/resolv.conf | copy host-path to jail-path in bastion03 |
+----+------+----+---+------------------+--------------+----------------------------------------------+
| create | folsom | 12.0-RELEASE 10.10.10.10 | create v12.0 jail named `folsom` with IP |
| create | folsom | 12.0-RELEASE 10.17.89.10 | create v12.0 jail named `folsom` with IP |
+-----------+--------+------------------+--------------+----------------------------------------------+
@@ -55,15 +53,14 @@ Examples: Releases
ishmael ~ # bastille ...
+-----------+--------------+--------------+-------------------------------------------------------------+
| command | target | args | description |
+===========+==============+==============+=============================================================+
| bootstrap | 12.0-RELEASE | --- | bootstrap 12.0-RELEASE release |
+-----------+--------------+--------------+-------------------------------------------------------------+
| update | 11.2-RELEASE | --- | update 11.2-RELEASE release |
| update | 11.3-RELEASE | --- | update 11.2-RELEASE release |
+-----------+--------------+--------------+-------------------------------------------------------------+
| upgrade | 11.1-RELEASE | 11.2-RELEASE | update 11.2-RELEASE release |
| upgrade | 11.2-RELEASE | 11.3-RELEASE | update 11.2-RELEASE release |
+-----------+--------------+--------------+-------------------------------------------------------------+
| verify | 11.2-RELEASE | --- | update 11.2-RELEASE release |
| verify | 11.3-RELEASE | --- | update 11.2-RELEASE release |
+-----------+--------------+--------------+-------------------------------------------------------------+

56
docs/chapters/template.rst
View File

@@ -5,24 +5,24 @@ Template
Bastille supports a templating system allowing you to apply files, pkgs and
execute commands inside the jail automatically.
Currently supported template hooks are: `PRE`, `CONFIG`, `PKG`, `SYSRC`, `CMD`.
Planned template hooks include: `FSTAB`, `PF`
Currently supported template hooks are: `PRE`, `OVERLAY`, `PKG`, `SYSRC`, `CMD`.
Planned template hooks include: `FSTAB`, `PF`, `LOG`.
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;
.. code-block:: 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
template directory named after the hook you want to execute. eg;
.. code-block:: shell
echo "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 "etc root usr" > /usr/local/bastille/templates/base/CONFIG
echo "zsh vim-console git-lite htop" > /usr/local/bastille/templates/username/base/PKG
echo "/usr/bin/chsh -s /usr/local/bin/zsh" > /usr/local/bastille/templates/username/base/CMD
echo "etc\nrootjn usr" > /usr/local/bastille/templates/username/base/OVERLAY
Template hooks are executed in specific order and require specific syntax to
work as expected. This table outlines those requirements:
@@ -31,25 +31,30 @@ work as expected. This table outlines those requirements:
+---------+------------------+--------------------------------------+
| HOOK | format | example |
+=========+==================+======================================+
| PRE/CMD | /bin/sh command | /usr/bin/chsh -s /usr/local/bin/zsh |
| PRE | /bin/sh command | mkdir -p /usr/local/my_app/html |
+---------+------------------+--------------------------------------+
| CONFIG | path | etc root usr |
| OVERLAY | path(s) | etc root usr (one per line) |
+---------+------------------+--------------------------------------+
| PKG | port/pkg name(s) | vim-console zsh git-lite tree htop |
+---------+------------------+--------------------------------------+
| SYSRC | sysrc command(s) | nginx_enable=YES |
+---------+------------------+--------------------------------------+
| SERVICE | service command | 'nginx start' OR 'postfix reload' |
+---------+------------------+--------------------------------------+
| CMD | /bin/sh command | /usr/bin/chsh -s /usr/local/bin/zsh |
+---------+------------------+--------------------------------------+
Note: SYSRC requires NO quotes or that quotes (`"`) be escaped. ie; `\"`)
Note: SYSRC requires that NO quotes be used or that quotes (`"`) be escaped.
ie; `\"`)
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 template directory as "/".
An example here may help. Think of `/usr/local/bastille/templates/base`,
our example template, as the root of our filesystem overlay. If you create
an `etc/hosts` or `etc/resolv.conf` *inside* the base template directory,
these can be overlayed into your jail.
An example here may help. Think of `bastille/templates/username/base`, our
example template, as the root of our filesystem overlay. If you create an
`etc/hosts` or `etc/resolv.conf` *inside* the base template directory, these
can be overlayed into your jail.
Note: due to the way FreeBSD segregates user-space, the majority of your
overlayed template files will be in `usr/local`. The few general
@@ -57,15 +62,16 @@ exceptions are the `etc/hosts`, `etc/resolv.conf`, and
`etc/rc.conf.local`.
After populating `usr/local/` with custom config files that your jail 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;
.. code-block:: shell
echo "etc usr" > /usr/local/bastille/templates/base/CONFIG
echo "etc\nusr" > /usr/local/bastille/templates/username/base/OVERLAY
The above example "etc usr" will include anything under "etc" and "usr"
inside the template. You do not need to list individual files. Just
include the top-level directory name.
include the top-level directory name. List these top-level directories one per
line.
Applying Templates
------------------
@@ -78,19 +84,19 @@ directory names in the `bastille/templates` directory.
.. code-block:: shell
ishmael ~ # bastille template ALL base
[cdn]:
ishmael ~ # bastille template ALL username/base
[proxy01]:
Copying files...
Copy complete.
Installing packages.
pkg already bootstrapped at /usr/local/sbin/pkg
vulnxml file up-to-date
0 problem(s) in the installed packages found.
Updating iniquity.io repository catalogue...
Updating bastillebsd.org repository catalogue...
[cdn] Fetching meta.txz: 100% 560 B 0.6kB/s 00:01
[cdn] Fetching packagesite.txz: 100% 121 KiB 124.3kB/s 00:01
Processing entries: 100%
iniquity.io repository update completed. 499 packages processed.
bastillebsd.org repository update completed. 499 packages processed.
All repositories are up to date.
Checking integrity... done (0 conflicting)
The most recent version of packages are already installed
@@ -102,23 +108,23 @@ directory names in the `bastille/templates` directory.
chsh: user information updated
Template Complete.
[poudriere]:
[web01]:
Copying files...
Copy complete.
Installing packages.
pkg already bootstrapped at /usr/local/sbin/pkg
vulnxml file up-to-date
0 problem(s) in the installed packages found.
Updating cdn.iniquity.io repository catalogue...
Updating pkg.bastillebsd.org repository catalogue...
[poudriere] Fetching meta.txz: 100% 560 B 0.6kB/s 00:01
[poudriere] Fetching packagesite.txz: 100% 121 KiB 124.3kB/s 00:01
Processing entries: 100%
cdn.iniquity.io repository update completed. 499 packages processed.
Updating iniquity.io repository catalogue...
pkg.bastillebsd.org repository update completed. 499 packages processed.
Updating bastillebsd.org repository catalogue...
[poudriere] Fetching meta.txz: 100% 560 B 0.6kB/s 00:01
[poudriere] Fetching packagesite.txz: 100% 121 KiB 124.3kB/s 00:01
Processing entries: 100%
iniquity.io repository update completed. 499 packages processed.
bastillebsd.org repository update completed. 499 packages processed.
All repositories are up to date.
Checking integrity... done (0 conflicting)
The most recent version of packages are already installed

41
docs/chapters/usage.rst
View File

@@ -1,32 +1,37 @@
=====
Usage
=====
.. code-block:: shell
ishmael ~ # bastille -h
Bastille is an open-source system for automating deployment and management
of containerized applications on FreeBSD.
Usage:
bastille command [ALL|glob] [args]
bastille command [ALL|glob] [args]
Available Commands:
bootstrap Bootstrap a FreeBSD release for jail base.
cmd Execute arbitrary command on targeted jail(s).
console Console into a running jail.
cp cp(1) files from host to targeted jail(s).
create Create a new jail.
destroy Destroy a stopped jail.
bootstrap Bootstrap a FreeBSD release for container base.
cmd Execute arbitrary command on targeted container(s).
console Console into a running container.
cp cp(1) files from host to targeted container(s).
create Create a new container.
destroy Destroy a stopped container or a FreeBSD release.
help Help about any command
htop Interactive process viewer (requires htop).
list List jails (running and stopped).
pkg Manipulate binary packages within targeted jail(s). See pkg(8).
restart Restart a running jail.
start Start a stopped jail.
stop Stop a running jail.
sysrc Safely edit rc files within targeted jail(s).
template Apply Bastille template to running jail(s).
list List containers (running and stopped).
pkg Manipulate binary packages within targeted container(s). See pkg(8).
restart Restart a running container.
service Manage services within targeted jail(s).
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 jail(s).
top Display and update information about the top(1) cpu processes.
update Update jail base -pX release.
upgrade Upgrade jail release to X.Y-RELEASE.
update Update container base -pX release.
upgrade Upgrade container release to X.Y-RELEASE.
verify Compare release against a "known good" index.
zfs Manage (get|set) zfs attributes on targeted jail(s).
Use "bastille -v|--version" for version information.
Use "bastille command -h|--help" for more information about a command.

6
docs/conf.py
View File

@@ -12,9 +12,9 @@ copyright = '2018-2019, Christer Edwards'
author = 'Christer Edwards'
# The short X.Y version
version = '0.3.20181124'
version = '0.4.20191025'
# The full version, including alpha/beta/rc tags
release = '0.3.20181124-beta'
release = '0.4.20191025-beta'
# -- General configuration ---------------------------------------------------
@@ -67,7 +67,7 @@ man_pages = [
texinfo_documents = [
(master_doc, 'Bastille', 'Bastille Documentation',
author, 'Bastille', 'Bastille is a jail automation framework that allows you to quickly and easily create and manage FreeBSD jails.',
author, 'Bastille', 'Bastille is an open-source system for automating deployment and management of containerized applications on FreeBSD.',
'Miscellaneous'),
]

1
docs/index.rst
View File

@@ -17,6 +17,7 @@ https://docs.bastillebsd.org.
chapters/targeting
chapters/subcommands/index
chapters/template
chapters/jail-config
copyright