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

update docs for 0.7.20200714 release

Browse Source
This commit is contained in:
Christer Edwards
2020-07-13 19:27:23 -06:00
parent 93bc945e90
commit da15b4f59a
25 changed files with 246 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/chapters/installation.rst
View File

@@ -4,7 +4,7 @@ Bastille is available in the official FreeBSD ports tree at
`sysutils/bastille`. Binary packages available in `quarterly` and `latest`
repositories.
Current version is `0.6.20200202`.
Current version is `0.7.20200714`.
To install from the FreeBSD package repository:

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

@@ -17,7 +17,7 @@ template looks like this:
devfs_ruleset = 4;
enforce_statfs = 2;
exec.clean;
exec.consolelog = /usr/local/bastille/logs/{name}_console.log;
exec.consolelog = /var/log/bastille/{name}_console.log;
exec.start = '/bin/sh /etc/rc';
exec.stop = '/bin/sh /etc/rc.shutdown';
host.hostname = {name};

81
docs/chapters/networking.rst
View File

@@ -5,29 +5,26 @@ to get started putting applications in secure little containers, but how do I
get these containers on the network?
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...
Three methods are described here. Consider each options when deciding
which design work best for your needs. One of the methods works better in the
cloud while the others are simpler if used in local area networks.
**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.
Shared Interface (IP alias)
---------------------------
In FreeBSD network interfaces have different names, but look something like
`em0`, `bge0`, `re0`, etc. On a virtual machine it may be `vtnet0`. You get the
idea...
Bastille allows you to define the interface you want the IP attached to when
you create it. An example:
@@ -43,13 +40,59 @@ 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.)
Bastille tries to verify that the interface name you provide it is a valid
interface. It also checks for a valid syntax IP4 or IP6 address.
Virtual Network (VNET)
----------------------
(Added in 0.6.x) VNET is supported on FreeBSD 12+ only.
Virtual Network (VNET) creates a private network interface for a container.
This includes a unique hardware address. This is required for VPN, DHCP, and
similar containers.
To create a VNET based container use the `-V` option, an IP/netmask and
external interface.
.. code-block:: shell
bastille create -V azkaban 12.1-RELEASE 192.168.1.50/24 em0
Bastille will automagically create the bridge interface and connect /
disconnect containers as they are started and stopped. A new interface will be
created on the host matching the pattern `interface0bridge`. In the example
here, `em0bridge`.
The `em0` interface will be attached to the bridge along with the unique
container interfaces as they are started and stopped. These interface names
match the pattern `eXb_bastilleX`. Internally to the containers these
interfaces are presented as `vnet0`.
VNET also requires a custom devfs ruleset. Create the file as needed on the
host system:
.. code-block:: shell
## /etc/devfs.rules (NOT .conf)
[bastille_vnet=13]
add include $devfsrules_hide_all
add include $devfsrules_unhide_basic
add include $devfsrules_unhide_login
add include $devfsrules_jail
add path 'bpf*' unhide
Lastly, you may want to consider these three `sysctl` values:
.. code-block:: shell
net.link.bridge.pfil_bridge=0
net.link.bridge.pfil_onlyip=0
net.link.bridge.pfil_member=0
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)
@@ -58,9 +101,11 @@ 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.
loopback (bastille0)
--------------------
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
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.

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

@@ -1,3 +1,4 @@
=========
bootstrap
=========
@@ -26,8 +27,7 @@ release version as the argument.
.. code-block:: shell
ishmael ~ # bastille bootstrap 11.3-RELEASE [update]
ishmael ~ # bastille bootstrap 12.0-RELEASE
ishmael ~ # bastille bootstrap 11.4-RELEASE [update]
ishmael ~ # bastille bootstrap 12.1-RELEASE
This command will ensure the required directory structures are in place and

17
docs/chapters/subcommands/clone.rst Normal file
View File

@@ -0,0 +1,17 @@
=====
clone
=====
To clone a container and make a duplicate use the `bastille clone`
sub-command..
.. code-block:: shell
ishmael ~ # bastille clone azkaban rikers ip
[azkaban]:
Syntax requires a name for the new container and an IP address assignment.
.. code-block:: shell
Usage: bastille clone [TARGET] [NEW_NAME] [IPADRESS].

2
docs/chapters/subcommands/cmd.rst
View File

@@ -6,7 +6,7 @@ To execute commands within the container you can use `bastille cmd`.
.. code-block:: shell
ishmael ~ # bastille cmd folsom 'ps -auxw'
ishmael ~ # bastille cmd folsom ps -auxw
[folsom]:
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

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

@@ -1,3 +1,4 @@
=======
console
=======
@@ -8,27 +9,6 @@ root login.
ishmael ~ # bastille console folsom
[folsom]:
FreeBSD 12.1-RELEASE-p1 GENERIC
Welcome to FreeBSD!
Release Notes, Errata: https://www.FreeBSD.org/releases/
Security Advisories: https://www.FreeBSD.org/security/
FreeBSD Handbook: https://www.FreeBSD.org/handbook/
FreeBSD FAQ: https://www.FreeBSD.org/faq/
Questions List: https://lists.FreeBSD.org/mailman/listinfo/freebsd-questions/
FreeBSD Forums: https://forums.FreeBSD.org/
Documents installed with the system are in the /usr/local/share/doc/freebsd/
directory, or can be installed later with: pkg install en-freebsd-doc
For other languages, replace "en" with a language code like de or fr.
Show the version of FreeBSD installed: freebsd-version ; uname -a
Please include that output and any error messages when posting questions.
Introduction to manual pages: man man
FreeBSD directory layout: man hier
Edit /etc/motd to change this login announcement.
root@folsom:~ #
At this point you are logged in to the container and have full shell access. The

16
docs/chapters/subcommands/convert.rst Normal file
View File

@@ -0,0 +1,16 @@
=======
convert
=======
To convert a thin container to a thick container use `bastille convert`.
.. code-block:: shell
ishmael ~ # bastille convert azkaban
[azkaban]:
Syntax requires only the target container to convert.
.. code-block:: shell
Usage: bastille convert TARGET

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

@@ -1,3 +1,4 @@
==
cp
==

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

@@ -1,3 +1,4 @@
======
create
======

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

@@ -1,3 +1,4 @@
=======
destroy
=======

16
docs/chapters/subcommands/edit.rst Normal file
View File

@@ -0,0 +1,16 @@
====
edit
====
To edit container configuration use `bastille edit`.
.. code-block:: shell
ishmael ~ # bastille edit azkaban [filename]
Syntax requires a target an optional filename. By default the file edited will
be `jail.conf`. Other common filenames are `fstab` or `rctl.conf`.
.. code-block:: shell
Usage: bastille edit TARGET

18
docs/chapters/subcommands/export.rst Normal file
View File

@@ -0,0 +1,18 @@
======
export
======
Exporting a container creates an archive or image that can be sent to a
different machine to be imported later. These exported archives can be used as
container backups.
.. code-block:: shell
ishmael ~ # bastille export azkaban
The export sub-command supports both UFS and ZFS storage. ZFS based containers
will use ZFS snapshots. UFS based containers will use `txz` archives.
.. code-block:: shell
Usage: bastille export TARGET

16
docs/chapters/subcommands/import.rst Normal file
View File

@@ -0,0 +1,16 @@
======
import
======
Import a container backup image or archive.
.. code-block:: shell
ishmael ~ # bastille import /path/to/archive.file
The import sub-command supports both UFS and ZFS storage. ZFS based containers
will use ZFS snapshots. UFS based containers will use `txz` archives.
.. code-block:: shell
Usage: bastille import file [option]

16
docs/chapters/subcommands/mount.rst Normal file
View File

@@ -0,0 +1,16 @@
=====
mount
=====
To mount storage within the container use `bastille mount`.
.. code-block:: shell
ishmael ~ # bastille mount azkaban /storage/foo /media/foo nullfs ro 0 0
[azkaban]:
Syntax follows standard `/etc/fstab` format:
.. code-block:: shell
Usage: bastille mount TARGET host_path container_path [filesystem_type options dump pass_number]

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

@@ -0,0 +1,13 @@
======
rename
======
Rename a container.
.. code-block:: shell
ishmael ~ # bastille rename azkaban arkham
.. code-block:: shell
Usage: bastille rename TARGET new_name

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

@@ -1,3 +1,4 @@
=======
restart
=======

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

@@ -1,3 +1,4 @@
=====
start
=====

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

@@ -1,3 +1,4 @@
====
stop
====

16
docs/chapters/subcommands/umount.rst Normal file
View File

@@ -0,0 +1,16 @@
======
umount
======
To unmount storage from a container use `bastille umount`.
.. code-block:: shell
ishmael ~ # bastille umount azkaban /media/foo
[azkaban]:
Syntax requires only the container path to unmount:
.. code-block:: shell
Usage: bastille umount TARGET container_path

2
docs/chapters/subcommands/upgrade.rst
View File

@@ -7,4 +7,4 @@ workflow this can be similar to a `bootstrap`.
.. code-block:: shell
ishmael ~ # bastille upgrade 11.2-RELEASE 12.0-RELEASE
ishmael ~ # bastille upgrade 12.0-RELEASE 12.1-RELEASE

16
docs/chapters/targeting.rst
View File

@@ -1,12 +1,12 @@
Targeting
=========
Bastille uses a `command-target-args` syntax, meaning that each command
Bastille uses a `command target arguments` syntax, meaning that each command
requires a target. Targets are usually containers, but can also be releases.
Targeting a containers is done by providing the exact containers name.
Targeting a container is done by providing the exact containers name.
Targeting a release is done by providing the release name. (Note: do note
Targeting a release is done by providing the release name. (Note: do not
include the `-pX` point-release version.)
Bastille includes a pre-defined keyword ALL to target all running containers.
@@ -42,7 +42,7 @@ Examples: Containers
+-----------+--------+-----+------------+-------------------------------------------------------------+
| cp | bastion03 | /tmp/resolv.conf-cf etc/resolv.conf | copy host-path to container-path in bastion03|
+----+------+----+---+------------------+--------------+----------------------------------------------+
| create | folsom | 12.0-RELEASE 10.17.89.10 | create 12.0 container named `folsom` with IP |
| create | folsom | 12.1-RELEASE 10.17.89.10 | create 12.1 container named `folsom` with IP |
+-----------+--------+------------------+--------------+----------------------------------------------+
@@ -56,11 +56,11 @@ Examples: Releases
+-----------+--------------+--------------+-------------------------------------------------------------+
| command | target | args | description |
+===========+==============+==============+=============================================================+
| bootstrap | 12.0-RELEASE | --- | bootstrap 12.0-RELEASE release |
| bootstrap | 12.1-RELEASE | --- | bootstrap 12.1-RELEASE release |
+-----------+--------------+--------------+-------------------------------------------------------------+
| update | 11.3-RELEASE | --- | update 11.2-RELEASE release |
| update | 11.4-RELEASE | --- | update 11.4-RELEASE release |
+-----------+--------------+--------------+-------------------------------------------------------------+
| upgrade | 11.2-RELEASE | 11.3-RELEASE | update 11.2-RELEASE release |
| upgrade | 11.3-RELEASE | 11.4-RELEASE | update 11.4-RELEASE release |
+-----------+--------------+--------------+-------------------------------------------------------------+
| verify | 11.3-RELEASE | --- | update 11.2-RELEASE release |
| verify | 11.4-RELEASE | --- | update 11.4-RELEASE release |
+-----------+--------------+--------------+-------------------------------------------------------------+

38
docs/chapters/template.rst
View File

@@ -9,27 +9,20 @@ execute commands inside the containers automatically.
Currently supported template hooks are: `LIMITS`, `INCLUDE`, `PRE`, `FSTAB`,
`PKG`, `OVERLAY`, `SYSRC`, `SERVICE`, `CMD`.
Planned template hooks include: `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;
the template hooks.
.. code-block:: shell
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/username/base/PKG
echo "/usr/bin/chsh -s /usr/local/bin/zsh" > /usr/local/bastille/templates/username/base/CMD
echo "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:
Bastille 0.7.x
--------------
Bastille 0.7.x introduces a template syntax that is more flexible and allows
any-order scripting. Previous versions had a hard template execution order and
instructions were spread across multiple files. The new syntax is done in a
`Bastillefile` and the template hook (see below) files are replaced with
template hook commands.
Template Automation Hooks
-------------------------
+---------+-------------------+-----------------------------------------+
| HOOK | format | example |
@@ -56,13 +49,16 @@ work as expected. This table outlines those requirements:
Note: SYSRC requires that NO quotes be used or that quotes (`"`) be escaped
ie; (`\\"`)
Place these uppercase template hook commands into a `Bastillefile` in any order
and automate container setup as needed.
In addition to supporting template hooks, Bastille supports overlaying
files into the container. This is done by placing the files in their full path,
using the template directory as "/".
An example here may help. Think of `bastille/templates/username/base`, our
An example here may help. Think of `bastille/templates/username/template`, 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
`etc/hosts` or `etc/resolv.conf` *inside* the template directory, these
can be overlayed into your container.
Note: due to the way FreeBSD segregates user-space, the majority of your
@@ -75,7 +71,7 @@ use, be sure to include `usr` in the template OVERLAY definition. eg;
.. code-block:: shell
echo "usr" > /usr/local/bastille/templates/username/base/OVERLAY
echo "usr" > /usr/local/bastille/templates/username/template/OVERLAY
The above example "usr" will include anything under "usr" inside the template.
You do not need to list individual files. Just include the top-level directory
@@ -92,7 +88,7 @@ directory names in the `bastille/templates` directory.
.. code-block:: shell
ishmael ~ # bastille template ALL username/base
ishmael ~ # bastille template ALL username/template
[proxy01]:
Copying files...
Copy complete.

20
docs/chapters/usage.rst
View File

@@ -3,31 +3,40 @@ Usage
.. code-block:: shell
ishmael ~ # bastille -h
ishmael ~ # bastille help
Bastille is an open-source system for automating deployment and management of
containerized applications on FreeBSD.
Usage:
bastille command [ALL|glob] [args]
bastille command TARGET [args]
Available Commands:
bootstrap Bootstrap a FreeBSD release for container base.
cmd Execute arbitrary command on targeted container(s).
clone Clone an existing container.
console Console into a running container.
convert Convert a Thin container into a Thick container.
cp cp(1) files from host to targeted container(s).
create Create a new thin container or a thick container if -T|--thick option specified.
destroy Destroy a stopped container or a FreeBSD release.
help Help about any command
edit Edit container configuration files (advanced).
export Exports a specified container.
help Help about any command.
htop Interactive process viewer (requires htop).
list List containers, releases, templates, or logs.
import Import a specified container.
list List containers (running and stopped).
mount Mount a volume inside the targeted container(s).
pkg Manipulate binary packages within targeted container(s). See pkg(8).
rdr Redirect host port to container port.
rename Rename a container.
restart Restart a running container.
service Manage services within targeted containers(s).
service Manage services within targeted container(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 container(s).
top Display and update information about the top(1) cpu processes.
umount Unmount a volume from within the targeted container(s).
update Update container base -pX release.
upgrade Upgrade container release to X.Y-RELEASE.
verify Compare release against a "known good" index.
@@ -35,3 +44,4 @@ Usage
Use "bastille -v|--version" for version information.
Use "bastille command -h|--help" for more information about a command.

4
docs/conf.py
View File

@@ -12,9 +12,9 @@ copyright = '2018-2020, Christer Edwards'
author = 'Christer Edwards'
# The short X.Y version
version = '0.6.20200202'
version = '0.7.20200714'
# The full version, including alpha/beta/rc tags
release = '0.6.20200202-beta'
release = '0.7.20200714-beta'
# -- General configuration ---------------------------------------------------