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

more doc fixes

Browse Source
This commit is contained in:
tschettervictor
2025-11-09 17:24:39 -07:00
parent b401ba1e01
commit 8c8fc32569
7 changed files with 71 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
docs/chapters/configuration.rst
View File

@@ -4,9 +4,10 @@ Configuration
Bastille is configured using a default config file located at
``/usr/local/etc/bastille/bastille.conf``. When first installing bastille, you
should run ``bastille setup``. This will ask if you want to copy the sample
config file to the above location. The defaults are sensible for UFS, but if you
want to use ZFS, you will have to change a few options. See the chapter on ZFS
Support.
config file to the above location. The defaults are sensible for UFS, but
if you use ZFS, ``bastille setup`` will configure it for you. If you have
multiple zpools, Bastille will ask which one you want to use. See also
:doc:`ZFS Support <chapters/zfs-support>`.
This is the default `bastille.conf` file.
@@ -98,28 +99,12 @@ This is the default `bastille.conf` file.
bastille_template_clone="default/clone" ## default: "default/clone"
bastille_template_thin="default/thin" ## default: "default/thin"
bastille_template_vnet="default/vnet" ## default: "default/vnet"
Notes
-----
The options here are fairly self-explanitory, but there are some things to note.
* If you use ZFS, DO NOT create the bastille dataset. You must only create the
parent. Bastille must be allowed to create the ``bastille`` child dataset, or
you will have issues. So, if you want bastille to live at
``zroot/data/bastille`` you should set ``bastille_zfs_zpool`` to ``zroot`` and
``bastille_zfs_prefix`` to ``data/bastille`` but you should only create
``zroot/data`` before running bastille for the first time.
* Bastille will mount the dataset it creates at ``bastille_prefix`` which
defaults to ``/usr/local/bastille``. So if you want to navigate to your jails,
you will use the ``bastille_prefix`` as the location because this is where the
will be mounted.
bastille_template_vlan="default/vlan" ## default: "default/vlan"
Custom Configuration
--------------------
Bastille now supports using a custom config in addition to the default one. This
Bastille supports using a custom config in addition to the default one. This
is nice if you have multiple users, or want to store different
jails at different locations based on your needs.

73
docs/chapters/getting-started.rst
View File

@@ -1,84 +1,84 @@
Getting Started
===============
This guide is meant to get you up and running with bastille, and will show you
a number of different options to create and manage your jails.
Bastille has many different options when it comes to creating
and managing jails. This guide is meant to show some basic
setup and configuration options.
Setup
-----
The first command a new user should run is the ``bastille setup`` command. This
will attempt to configure the networking, storage, and firewall on your system
The first command a new user should run is ``bastille setup``. This
will configure the networking, storage, and firewall on your system
for use with Bastille.
By default the setup command will configure a loopback interface, storage (ZFS if
enabled, otherwise UFS) and the pf firewall if you run it as below without any
options.
By default the ``bastille setup`` will configure a loopback interface, storage (ZFS if
enabled, otherwise UFS) and the ``pf`` firewall.
Alternatively, you can run the ``setup`` command with any of the supported
Alternatively, you can run ``bastille setup OPTION`` command with any of the supported
options to configure the selected option by itself.
To see a list of available options and switches, see the ``setup`` subcommand.
To see a list of available options, see the ``setup`` subcommand.
.. code-block:: shell
ishmael ~ # bastille setup
Now we are ready to bootstrap a release and start creating jails.
Bootstrapping a Release
-----------------------
Then we need to bootstrap a release for bastille to use. We will use
14.2-RELEASE.
To bootstrap a release, run ``bastille bootstrap RELEASE``.
.. code-block:: shell
ishmael ~ # bastille bootstrap 14.2-RELEASE
This will fetch the necessary components of the specified release, and
enable us to create jails from the downloaded release.
Creating a Jail
---------------
Next we can create our first jail. Bastille can create a few different types of
jails.
There are a few different types of jails we can create, described below.
* Thin jails are the default, and are called thin because they use symlinks to
the bootstrapped release. They are lightweight and are created quickly.
* Thick jails used the entire release, which is copied into the jail. The jail
* Thick jails use the entire release, which is copied into the jail. The jail
then acts like a full BSD install, completely independent of the release.
Created with ``bastille create -T``.
Created with the ``--thick|-T`` option.
* Clone jails are essentially clones of the bootstrapped release. Changes to the
release will affect the clone jail. Created with ``bastille create -C``.
release will affect the clone jail. Created with the ``--clone|-C`` option.
* Empty jails are just that, empty. These should be used only if you know what
you are doing. Created with ``bastille create -E``.
you are doing. Created with the ``--empty|-E`` option.
* Linux jails are jails that run linux. Created with ``bastille create -L``.
* Linux jails are jails that run linux. Created with the ``--linux|-L`` option.
See :doc:`Linux Jails <chapters/linux-jails>`.
Only clone, thin, and thick jails can be created with ``-V`` ``-B`` and ``-M``.
We will focus on thin jails for the guide.
We will focus on thin jails for this guide.
Classic/Standard Jail
^^^^^^^^^^^^^^^^^^^^^
.. code-block:: shell
ishmael ~ # bastille create nextcloud 14.2-RELEASE 10.1.1.4/24 vtnet0
ishmael ~ # bastille create nextcloud 14.2-RELEASE 10.1.1.4/24
This will create a classic jail and add the IP as an alias to the vtnet0
interface. This jail will use NAT for its outbound traffic. If you want to run
a webserver of something similar inside it, you will have to redirect traffic
from the host using ``bastille rdr``
This will create a classic jail, which uses the loopback interface
(created with ``bastille setup``) for outbound connections.
It the IP is reachable within your local subnet, however, then it is not
necessary to redirect the traffic. It will pass in and out normally.
To be able to reach a service inside the jail, use ``bastille rdr``.
.. code-block:: shell
ishmael ~ # bastille rdr nextcloud tcp 80 80
This will forward traffic from port 80 on the host to port 80 inside the jail.
See also :doc:`rdr <rdr>`.
VNET Jail
^^^^^^^^^
@@ -99,20 +99,3 @@ or
The IP used for VNET jails should be an IP reachable inside your local network.
You can also specify 0.0.0.0 or DHCP to use DHCP.
Linux Jail
^^^^^^^^^^
Linux jails are still considered experimental, but they seem to work. First we
must bootstrap a linux distro (Linux distros are bootstrapped with the Debian
tool debootstrap).
.. code-block:: shell
ishmael ~ # bastille bootstrap bionic
Then we can create our linux jail using this release. This will take a while...
.. code-block:: shell
ishmael ~ # bastille create -L linux_jail bionic 10.1.1.7/24 vtnet0

8
docs/chapters/installation.rst
View File

@@ -1,5 +1,6 @@
Installation
============
Bastille is available in the official FreeBSD ports tree at
``sysutils/bastille``. Binary packages are available in quarterly and latest
repositories.
@@ -18,9 +19,6 @@ pkg
.. code-block:: shell
pkg install bastille
bastille setup
To install from source (don't worry, no compiling):
ports
-----
@@ -28,7 +26,6 @@ ports
.. code-block:: shell
make -C /usr/ports/sysutils/bastille install clean
bastille setup
git
---
@@ -38,9 +35,8 @@ git
git clone https://github.com/BastilleBSD/bastille.git
cd bastille
make install
bastille setup
This method will install the latest files from GitHub directly onto your
The ``git`` method will install the latest files from GitHub directly onto your
system. It is verbose about the files it installs (for later removal), and also
has a ``make uninstall`` target. You may need to manually copy the sample
config into place before Bastille will run. (ie;

2
docs/chapters/jail-startup-configuration.rst
View File

@@ -11,7 +11,7 @@ the priority option. Jails will start in order starting at the lowest value, and
will stop in order starting at the highest value. So, jails with a priority value
of 1 will start first, and stop last.
See the chapter on targeting for more info.
See :doc:`Targeting <chapters/targeting>`for more info.
Boot
----

2
docs/chapters/linux-jails.rst Normal file
View File

@@ -0,0 +1,2 @@
Linux Jails
===========

39
docs/chapters/targeting.rst
View File

@@ -2,21 +2,20 @@ Targeting
=========
Bastille uses a ``subcommand TARGET ARGS`` syntax, meaning that each command
requires a target. Targets are usually containers, but can also be releases.
requires a target. Targets are usually jails, but can also be releases.
Targeting a container is done by providing the exact jail name, the JID of the
jail, a tag, or by typing the starting few characters of a jail. If more than one
matching jail is found, you will see an error saying so.
Targeting a jail is done by providing the exact jail name, the JID of the
jail, a tag, or by typing the starting few characters of a jail.
If you use a tag as the TARGET, Bastille will target any and all jail(s) that have
the tag assigned. If you have a jail with the same name as the tag you are trying to
If you use a tag as the TARGET, Bastille will target any and all jails that have
that tag assigned. If you have a jail with the same name as the tag you are trying to
target, Bastille will target the jail, and not the tag.
Targeting a release is done by providing the exact release name. (Note: do not
include the ``-pX`` point-release version.)
Bastille includes a pre-defined keyword [ALL|all] to target all running
containers. It is also possible to target multiple jails by grouping them in
Bastille includes a pre-defined keyword of [ALL|all] to target all running
jails. It is also possible to target multiple jails by grouping them in
quotes, as seen below.
.. code-block:: shell
@@ -27,7 +26,7 @@ Priority
--------
The priority value determines in what order commands are executed if multiple
jails are targetted, including the ALL target.
jails are targetted, including the [ALL|all] target.
It also controls in what order jails are started and stopped on system startup
and shutdown. This requires Bastille to be enabled with ``sysrc bastille_enable=YES``.
@@ -43,8 +42,8 @@ This value can be changed using ``bastille config TARGET set priority VALUE``.
This value will be shown using ``bastille list all``.
Examples: Containers
--------------------
Examples: Jails
---------------
.. code-block:: shell
@@ -53,25 +52,25 @@ Examples: Containers
+-----------+--------+------------------+-------------------------------------------------------------+
| command | target | args | description |
+===========+========+==================+=============================================================+
| cmd | ALL | 'sockstat -4' | execute `sockstat -4` in ALL containers (ip4 sockets) |
| cmd | ALL | 'sockstat -4' | execute `sockstat -4` in ALL jails (ip4 sockets) |
+-----------+--------+-----+------------+-------------------------------------------------------------+
| console | mariadb02 | --- | console (shell) access to mariadb02 |
+----+------+--------+-----+------------+-------------------------------------------------------------+
| pkg | web01 | 'install nginx' | install nginx package in web01 container |
| pkg | web01 | 'install nginx' | install nginx package in web01 jail |
+-----------+--------+------------------+-------------------------------------------------------------+
| pkg | ALL | upgrade | upgrade packages in ALL containers |
| pkg | ALL | upgrade | upgrade packages in ALL jails |
+-----------+--------+------------------+-------------------------------------------------------------+
| pkg | ALL | audit | (CVE) audit packages in ALL containers |
| pkg | ALL | audit | (CVE) audit packages in ALL jails |
+-----------+--------+------------------+-------------------------------------------------------------+
| sysrc | web01 | nginx_enable=YES | execute `sysrc nginx_enable=YES` in web01 container |
| sysrc | web01 | nginx_enable=YES | execute `sysrc nginx_enable=YES` in web01 jail |
+-----------+--------+------------------+-------------------------------------------------------------+
| template | ALL | username/base | apply `username/base` template to ALL containers |
| template | ALL | username/base | apply `username/base` template to ALL jails |
+-----------+--------+------------------+-------------------------------------------------------------+
| start | web02 | --- | start web02 container |
| start | web02 | --- | start web02 jail |
+----+------+----+---+------------------+--------------+----------------------------------------------+
| cp | bastion03 | /tmp/resolv.conf-cf etc/resolv.conf | copy host-path to container-path in bastion03|
| cp | bastion03 | /tmp/resolv.conf-cf etc/resolv.conf | copy host-path to jail-path in bastion03 |
+----+------+----+---+---------------------------------+----------------------------------------------+
| create | folsom | 13.2-RELEASE 10.17.89.10 | create 13.2 container named `folsom` with IP |
| create | folsom | 13.2-RELEASE 10.17.89.10 | create 13.2 jail named `folsom` with IP |
+-----------+--------+---------------------------------+----------------------------------------------+

25
docs/index.rst
View File

@@ -11,23 +11,24 @@ https://docs.bastillebsd.org.
:maxdepth: 2
:caption: Contents:
chapters/installation
chapters/gettin-gstarted
chapters/configuration
chapters/targeting
chapters/jail-startup-configuration
chapters/networking
chapters/usage
chapters/comparing
chapters/upgrading
chapters/centralized-assets
chapters/subcommands/index
chapters/template
chapters/installation
chapters/getting-started
chapters/configuration
chapters/jail-config
chapters/zfs-support
chapters/jail-startup-configuration
chapters/targeting
chapters/subcommands/index
chapters/usage
chapters/networking
chapters/gcp
chapters/upgrading
chapters/migration
chapters/centralized-assets
chapters/template
chapters/linux-jails
chapters/pkgbase
chapters/zfs-support
copyright