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 Bastille is configured using a default config file located at
``/usr/local/etc/bastille/bastille.conf``. When first installing bastille, you ``/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 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 config file to the above location. The defaults are sensible for UFS, but
want to use ZFS, you will have to change a few options. See the chapter on ZFS if you use ZFS, ``bastille setup`` will configure it for you. If you have
Support. 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. 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_clone="default/clone" ## default: "default/clone"
bastille_template_thin="default/thin" ## default: "default/thin" bastille_template_thin="default/thin" ## default: "default/thin"
bastille_template_vnet="default/vnet" ## default: "default/vnet" bastille_template_vnet="default/vnet" ## default: "default/vnet"
bastille_template_vlan="default/vlan" ## default: "default/vlan"
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.
Custom Configuration 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 is nice if you have multiple users, or want to store different
jails at different locations based on your needs. jails at different locations based on your needs.

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

@@ -1,84 +1,84 @@
Getting Started Getting Started
=============== ===============
This guide is meant to get you up and running with bastille, and will show you Bastille has many different options when it comes to creating
a number of different options to create and manage your jails. and managing jails. This guide is meant to show some basic
setup and configuration options.
Setup Setup
----- -----
The first command a new user should run is the ``bastille setup`` command. This The first command a new user should run is ``bastille setup``. This
will attempt to configure the networking, storage, and firewall on your system will configure the networking, storage, and firewall on your system
for use with Bastille. for use with Bastille.
By default the setup command will configure a loopback interface, storage (ZFS if By default the ``bastille setup`` will configure a loopback interface, storage (ZFS if
enabled, otherwise UFS) and the pf firewall if you run it as below without any enabled, otherwise UFS) and the ``pf`` firewall.
options.
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. 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 .. code-block:: shell
ishmael ~ # bastille setup ishmael ~ # bastille setup
Now we are ready to bootstrap a release and start creating jails.
Bootstrapping a Release Bootstrapping a Release
----------------------- -----------------------
Then we need to bootstrap a release for bastille to use. We will use To bootstrap a release, run ``bastille bootstrap RELEASE``.
14.2-RELEASE.
.. code-block:: shell .. code-block:: shell
ishmael ~ # bastille bootstrap 14.2-RELEASE 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 Creating a Jail
--------------- ---------------
Next we can create our first jail. Bastille can create a few different types of There are a few different types of jails we can create, described below.
jails.
* Thin jails are the default, and are called thin because they use symlinks to * Thin jails are the default, and are called thin because they use symlinks to
the bootstrapped release. They are lightweight and are created quickly. 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. 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 * 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 * 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 this guide.
We will focus on thin jails for the guide.
Classic/Standard Jail Classic/Standard Jail
^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^
.. code-block:: shell .. 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 This will create a classic jail, which uses the loopback interface
interface. This jail will use NAT for its outbound traffic. If you want to run (created with ``bastille setup``) for outbound connections.
a webserver of something similar inside it, you will have to redirect traffic
from the host using ``bastille rdr``
It the IP is reachable within your local subnet, however, then it is not To be able to reach a service inside the jail, use ``bastille rdr``.
necessary to redirect the traffic. It will pass in and out normally.
.. code-block:: shell .. code-block:: shell
ishmael ~ # bastille rdr nextcloud tcp 80 80 ishmael ~ # bastille rdr nextcloud tcp 80 80
This will forward traffic from port 80 on the host to port 80 inside the jail. This will forward traffic from port 80 on the host to port 80 inside the jail.
See also :doc:`rdr <rdr>`.
VNET Jail VNET Jail
^^^^^^^^^ ^^^^^^^^^
@@ -99,20 +99,3 @@ or
The IP used for VNET jails should be an IP reachable inside your local network. 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. 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 Installation
============ ============
Bastille is available in the official FreeBSD ports tree at Bastille is available in the official FreeBSD ports tree at
``sysutils/bastille``. Binary packages are available in quarterly and latest ``sysutils/bastille``. Binary packages are available in quarterly and latest
repositories. repositories.
@@ -18,9 +19,6 @@ pkg
.. code-block:: shell .. code-block:: shell
pkg install bastille pkg install bastille
bastille setup
To install from source (don't worry, no compiling):
ports ports
----- -----
@@ -28,7 +26,6 @@ ports
.. code-block:: shell .. code-block:: shell
make -C /usr/ports/sysutils/bastille install clean make -C /usr/ports/sysutils/bastille install clean
bastille setup
git git
--- ---
@@ -38,9 +35,8 @@ git
git clone https://github.com/BastilleBSD/bastille.git git clone https://github.com/BastilleBSD/bastille.git
cd bastille cd bastille
make install 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 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 has a ``make uninstall`` target. You may need to manually copy the sample
config into place before Bastille will run. (ie; 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 will stop in order starting at the highest value. So, jails with a priority value
of 1 will start first, and stop last. 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 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 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 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 more than one jail, a tag, or by typing the starting few characters of a jail.
matching jail is found, you will see an error saying so.
If you use a tag as the TARGET, Bastille will target any and all jail(s) that have If you use a tag as the TARGET, Bastille will target any and all jails that have
the tag assigned. If you have a jail with the same name as the tag you are trying to 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. target, Bastille will target the jail, and not the tag.
Targeting a release is done by providing the exact release name. (Note: do not Targeting a release is done by providing the exact release name. (Note: do not
include the ``-pX`` point-release version.) include the ``-pX`` point-release version.)
Bastille includes a pre-defined keyword [ALL|all] to target all running Bastille includes a pre-defined keyword of [ALL|all] to target all running
containers. It is also possible to target multiple jails by grouping them in jails. It is also possible to target multiple jails by grouping them in
quotes, as seen below. quotes, as seen below.
.. code-block:: shell .. code-block:: shell
@@ -27,7 +26,7 @@ Priority
-------- --------
The priority value determines in what order commands are executed if multiple 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 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``. 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``. This value will be shown using ``bastille list all``.
Examples: Containers Examples: Jails
-------------------- ---------------
.. code-block:: shell .. code-block:: shell
@@ -53,25 +52,25 @@ Examples: Containers
+-----------+--------+------------------+-------------------------------------------------------------+ +-----------+--------+------------------+-------------------------------------------------------------+
| command | target | args | description | | 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 | | 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 :maxdepth: 2
:caption: Contents: :caption: Contents:
chapters/installation
chapters/gettin-gstarted
chapters/configuration
chapters/targeting
chapters/jail-startup-configuration
chapters/networking
chapters/usage
chapters/comparing chapters/comparing
chapters/upgrading chapters/installation
chapters/centralized-assets chapters/getting-started
chapters/subcommands/index chapters/configuration
chapters/template
chapters/jail-config chapters/jail-config
chapters/zfs-support chapters/jail-startup-configuration
chapters/targeting
chapters/subcommands/index
chapters/usage
chapters/networking
chapters/gcp chapters/gcp
chapters/upgrading
chapters/migration chapters/migration
chapters/centralized-assets
chapters/template
chapters/linux-jails
chapters/pkgbase chapters/pkgbase
chapters/zfs-support
copyright copyright