mirror of
https://github.com/hackacad/bastille.git
synced 2025-12-18 00:00:40 +01:00
doc: general reformatting to use 80 columns in the text
This commit is contained in:
Juan David Hurtado G
@@ -1,15 +1,14 @@
|
||||
bootstrap
|
||||
=========
|
||||
|
||||
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.
|
||||
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. Bastille tries to filter for
|
||||
valid release names. If you find it will not bootstrap a valid release, please
|
||||
let us know.
|
||||
Note: your mileage may vary with unsupported releases and releases newer 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.
|
||||
@@ -60,8 +59,8 @@ Tips
|
||||
^^^^
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
Notes
|
||||
@@ -126,4 +125,4 @@ begin applying your template.
|
||||
Usage: bastille bootstrap [option(s)] [RELEASE|TEMPLATE] [update|arch]
|
||||
Options:
|
||||
|
||||
-x | --debug Enable debug mode.
|
||||
-x | --debug Enable debug mode.
|
||||
|
||||
@@ -2,7 +2,7 @@ clone
|
||||
=====
|
||||
|
||||
To clone a container and make a duplicate, use the ``bastille clone``
|
||||
sub-command..
|
||||
sub-command.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
console
|
||||
=======
|
||||
|
||||
This sub-command launches a login shell into the container. Default is password-less root login.
|
||||
This sub-command launches a login shell into the container. Default is password-
|
||||
less root login.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
@@ -9,7 +10,7 @@ This sub-command launches a login shell into the container. Default is password-
|
||||
[folsom]:
|
||||
root@folsom:~ #
|
||||
|
||||
At this point you are logged in to the container and have full shell access. The
|
||||
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
|
||||
container are limited to the container.
|
||||
|
||||
|
||||
@@ -1,14 +1,11 @@
|
||||
create
|
||||
======
|
||||
|
||||
Bastille create uses any available bootstrapped release to create a
|
||||
lightweight container system. To create a container simply provide a name,
|
||||
bootstrapped release and a private (rfc1918) IP address.
|
||||
Bastille create uses any available bootstrapped release to create a lightweight
|
||||
container system. To create a container simply provide a name, bootstrapped
|
||||
release and a private (rfc1918) IP address.
|
||||
|
||||
- name
|
||||
- release
|
||||
- ip
|
||||
- interface (optional)
|
||||
- name - release - ip - interface (optional)
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
@@ -26,31 +23,31 @@ address to the new system.
|
||||
ishmael ~ # bastille create alcatraz 13.2-RELEASE 10.17.89.113/24
|
||||
|
||||
|
||||
The above code will create a jail with a /24 mask. At the time of this documentation you
|
||||
can only use CIDR notation, and not use a netmask 255.255.255.0 to accomplish this.
|
||||
The above code will create a jail with a /24 mask. At the time of this
|
||||
documentation you can only use CIDR notation, and not use a netmask
|
||||
255.255.255.0 to accomplish this.
|
||||
|
||||
I recommend using private (rfc1918) ip address ranges for your container. These
|
||||
ranges include:
|
||||
|
||||
- 10.0.0.0/8
|
||||
- 172.16.0.0/12
|
||||
- 192.168.0.0/16
|
||||
- 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.
|
||||
|
||||
A couple of notes about the created jails. First, MOTD has been disabled inside
|
||||
of the jails because it does not give information about the jail, but about the host
|
||||
system. This caused confusion for some users, so we implemented the .hushlogin which
|
||||
silences the MOTD at login.
|
||||
A couple of notes about the created jails. First, MOTD has been disabled inside
|
||||
of the jails because it does not give information about the jail, but about the
|
||||
host system. This caused confusion for some users, so we implemented the
|
||||
.hushlogin which silences the MOTD at login.
|
||||
|
||||
Also, uname does not work from within a jail. Much like MOTD, it gives you the version
|
||||
information about the host system instead of the jail. If you need to check the version
|
||||
of freebsd running on the jail use the freebsd-version command to get accurate information.
|
||||
Also, uname does not work from within a jail. Much like MOTD, it gives you the
|
||||
version information about the host system instead of the jail. If you need to
|
||||
check the version of freebsd running on the jail use the freebsd-version command
|
||||
to get accurate information.
|
||||
|
||||
|
||||
Bastille can create many different types of jails, along with many different options. See
|
||||
the below help output.
|
||||
Bastille can create many different types of jails, along with many different
|
||||
options. See the below help output.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
@@ -72,4 +69,3 @@ the below help output.
|
||||
-v | --vlan VLANID Creates the jail with specified VLAN ID (VNET only).
|
||||
-x | --debug Enable debug mode.
|
||||
-Z | --zfs-opts [zfs,options] Comma separated list of ZFS options to create the jail with. This overrides the defaults.
|
||||
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
destroy
|
||||
=======
|
||||
|
||||
Jails can be destroyed and thrown away just as easily as they were
|
||||
created. Note: containers must be stopped before destroyed. Using
|
||||
the ``-a|--auto`` option will automatically stop the jail before destroying it.
|
||||
Jails can be destroyed and thrown away just as easily as they were created.
|
||||
Note: containers must be stopped before destroyed. Using the ``-a|--auto``
|
||||
option will automatically stop the jail before destroying it.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
@@ -14,8 +14,8 @@ the ``-a|--auto`` option will automatically stop the jail before destroying it.
|
||||
Note: containers console logs not destroyed.
|
||||
/usr/local/bastille/logs/folsom_console.log
|
||||
|
||||
Release can be destroyed provided there are no child jails. The `-c|--no-cache` option
|
||||
will retain the release cache directory, if you choose to keep it.
|
||||
Release can be destroyed provided there are no child jails. The `-c|--no-cache`
|
||||
option will retain the release cache directory, if you choose to keep it.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
etcupdate
|
||||
=========
|
||||
|
||||
This command will update the contents of ``/etc`` inside a jail. It should be run after a jail upgrade
|
||||
This command will update the contents of ``/etc`` inside a jail. It should be
|
||||
run after a jail upgrade
|
||||
|
||||
First we need to bootstrap a release for ``etcupdate`` to use.
|
||||
|
||||
@@ -21,8 +22,9 @@ Next we can use the ``update`` command to apply the update to the jail.
|
||||
|
||||
ishmael ~ # bastille etcupdate ishmael update 14.1-RELEASE
|
||||
|
||||
The output will show you which files were added, updated, changed, deleted, or have conflicts.
|
||||
To automatically resolve the conflicts, run the ``resolve`` command.
|
||||
The output will show you which files were added, updated, changed, deleted, or
|
||||
have conflicts. To automatically resolve the conflicts, run the ``resolve``
|
||||
command.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
htop
|
||||
====
|
||||
|
||||
This command runs ``htop`` in the targeted jail.
|
||||
Requires htop to be installed in the jail.
|
||||
This command runs ``htop`` in the targeted jail. Requires htop to be installed
|
||||
in the jail.
|
||||
|
||||
.. image:: ../../images/htop.png
|
||||
:align: center
|
||||
|
||||
@@ -7,7 +7,8 @@ To add a limit, use ``bastille limits TARGET add OPTION VALUE``
|
||||
|
||||
To clear the limits from the system, use ``bastille limits TARGET clear``
|
||||
|
||||
To clear the limits, and remove the rctl.conf, use ``bastille limits TARGET reset``
|
||||
To clear the limits, and remove the rctl.conf, use ``bastille limits TARGET
|
||||
reset``
|
||||
|
||||
To remove a limit, use ``bastille limits TARGET remove OPTION``
|
||||
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
list
|
||||
====
|
||||
|
||||
List jails, ports, releases, templates, logs, limits, exports and imports managed by bastille.
|
||||
List jails, ports, releases, templates, logs, limits, exports and imports
|
||||
managed by bastille.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
|
||||
@@ -9,7 +9,8 @@ Syntax follows standard ``/etc/fstab`` format:
|
||||
|
||||
Usage: bastille mount TARGET HOST_PATH JAIL_PATH [filesystem_type options dump pass_number]
|
||||
|
||||
The ``options`` string can include a comma-separated list of mount options, but must include one of (rw,ro,rq,sw,xx) according to fstab documentation.
|
||||
The ``options`` string can include a comma-separated list of mount options, but
|
||||
must include one of (rw,ro,rq,sw,xx) according to fstab documentation.
|
||||
|
||||
Example: Mount a tmpfs filesystem with options.
|
||||
|
||||
@@ -31,11 +32,16 @@ Example: Mount a nullfs filesystem
|
||||
[azkaban]:
|
||||
Added: /media/bar /usr/local/bastille/jails/azkaban/root/media/bar nullfs ro 0 0
|
||||
|
||||
Notice the JAIL_PATH format can be /media/foo or simply media/bar. The leading slash / is optional. The HOST_PATH howerver, must be the full path including the leading slash /.
|
||||
Notice the JAIL_PATH format can be /media/foo or simply media/bar. The leading
|
||||
slash / is optional. The HOST_PATH howerver, must be the full path including the
|
||||
leading slash /.
|
||||
|
||||
It is also possible to mount individual files into a jail as seen below.
|
||||
Bastille will not mount if a file is already present at the specified mount point.
|
||||
If the jail file name does not match the host file name, bastille will treat the jail path as a directory, and mount the file underneath as seen in the second example below.
|
||||
Bastille will not mount if a file is already present at the specified mount
|
||||
point.
|
||||
If the jail file name does not match the host file name, bastille will treat the
|
||||
jail path as a directory, and mount the file underneath as seen in the second
|
||||
example below.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
@@ -46,8 +52,10 @@ If the jail file name does not match the host file name, bastille will treat the
|
||||
[azkaban]:
|
||||
Added: /etc/rc.conf usr/local/bastille/jails/azkaban/root/media/bar/rc.conf nullfs ro 0 0
|
||||
|
||||
It is also possible (but not recommended) to have spaces in the directories that are mounted.
|
||||
It is necessary to escape each space with a backslash \ and enclose the mount point in quotes "" as seen below.
|
||||
It is also possible (but not recommended) to have spaces in the directories that
|
||||
are mounted.
|
||||
It is necessary to escape each space with a backslash \ and enclose the mount
|
||||
point in quotes "" as seen below.
|
||||
It is possible to do the same for the jail path, but again, not recommemded.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
@@ -5,15 +5,30 @@ Add or remove interfaces to existing jails.
|
||||
|
||||
You can only add an interface once to a jail, with two exceptions.
|
||||
|
||||
1. For classic jails, you can add an interface as many times as you want, but each time with a different IP. All this does is add the IP as another alias on that interface.
|
||||
1. For classic jails, you can add an interface as many times as you want, but
|
||||
each time with a different IP. All this does is add the IP as another alias
|
||||
on that interface.
|
||||
|
||||
2. For VNET jails, if the ``-v|--vlan`` switch is given along with a numerical VLAN ID, Bastille will add the VLAN ID to the jail as a vnetX.X interface, depending on which interface is specified.
|
||||
2. For VNET jails, if the ``-v|--vlan`` switch is given along with a numerical
|
||||
VLAN ID, Bastille will add the VLAN ID to the jail as a vnetX.X interface,
|
||||
depending on which interface is specified.
|
||||
|
||||
Bridges and VNET interfaces can be added to VNET jails, no matter if they were created with ``-V`` or ``-B``.
|
||||
Bridges and VNET interfaces can be added to VNET jails, no matter if they were
|
||||
created with ``-V`` or ``-B``.
|
||||
|
||||
It is possible to passthrough an entire interface from the host to the jail using the ``-P|--passthrough`` option. This will make the interface fully available without the need for additional configuration. It will be available inside the jail just like it would be on the host. Adding an interface using this method will render it only available inside the jail. It will not be present on the host until the jail is stopped.
|
||||
It is possible to passthrough an entire interface from the host to the jail
|
||||
using the ``-P|--passthrough`` option. This will make the interface fully
|
||||
available without the need for additional configuration. It will be available
|
||||
inside the jail just like it would be on the host. Adding an interface using
|
||||
this method will render it only available inside the jail. It will not be
|
||||
present on the host until the jail is stopped.
|
||||
|
||||
When cloning a jail that has a ``-P|--passthrough`` interface, you will have warnings when running both jails at the same time. The first jail to start will be assigned the interface, and since it will no longer be available to the host, it will not be possible to add it to the second jail. To solve this, you must manually remove the interface from the jail.conf file, or running ``bastille network TARGET remove INTERFACE`` while both jails are stopped.
|
||||
When cloning a jail that has a ``-P|--passthrough`` interface, you will have
|
||||
warnings when running both jails at the same time. The first jail to start will
|
||||
be assigned the interface, and since it will no longer be available to the host,
|
||||
it will not be possible to add it to the second jail. To solve this, you must
|
||||
manually remove the interface from the jail.conf file, or running ``bastille
|
||||
network TARGET remove INTERFACE`` while both jails are stopped.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
|
||||
@@ -20,9 +20,9 @@ Manage binary packages inside jails.
|
||||
...[snip]...
|
||||
|
||||
|
||||
The PKG sub-command can do more than just ``install``. The
|
||||
expectation is that you can fully leverage the pkg manager. This means,
|
||||
``install``, ``update``, ``upgrade``, ``audit``, ``clean``, ``autoremove``, etc...
|
||||
The PKG sub-command can do more than just ``install``. The expectation is that
|
||||
you can fully leverage the pkg manager. This means, ``install``, ``update``,
|
||||
``upgrade``, ``audit``, ``clean``, ``autoremove``, etc...
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
|
||||
@@ -3,12 +3,12 @@ rdr
|
||||
|
||||
``bastille rdr`` allows you to configure dynamic rdr rules for your containers
|
||||
without modifying pf.conf (assuming you are using the ``bastille0`` interface
|
||||
for a private network and have enabled ``rdr-anchor 'rdr/*'`` in /etc/pf.conf
|
||||
as described in the Networking section).
|
||||
for a private network and have enabled ``rdr-anchor 'rdr/*'`` in /etc/pf.conf as
|
||||
described in the Networking section).
|
||||
|
||||
Note: you need to be careful if host services are configured to run
|
||||
on all interfaces as this will include the jail interface - you should
|
||||
specify the interface they run on in rc.conf (or other config files)
|
||||
Note: you need to be careful if host services are configured to run on all
|
||||
interfaces as this will include the jail interface - you should specify the
|
||||
interface they run on in rc.conf (or other config files)
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
|
||||
@@ -2,8 +2,8 @@ service
|
||||
=======
|
||||
|
||||
The ``service`` sub-command allows for managing services within jails. This
|
||||
allows you to start, stop, restart, and otherwise interact with services
|
||||
running inside the jail(s).
|
||||
allows you to start, stop, restart, and otherwise interact with services running
|
||||
inside the jail(s).
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
|
||||
@@ -2,8 +2,8 @@ setup
|
||||
=====
|
||||
|
||||
The ``setup`` sub-command attempts to automatically configure a host system for
|
||||
Bastille containers. This allows you to configure networking, firewall, and storage
|
||||
options for a Bastille host with one command.
|
||||
Bastille containers. This allows you to configure networking, firewall, and
|
||||
storage options for a Bastille host with one command.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
|
||||
@@ -7,8 +7,9 @@ Run preconfigured template files inside targeted jail(s).
|
||||
|
||||
ishmael ~ # bastille template azkaban project/template
|
||||
|
||||
Templates should be structured in ``project/template/Bastillefile`` format, and placed in the template
|
||||
directory, which defaults to ``/usr/local/bastille/templates``. The Bastillefile should contain the template
|
||||
Templates should be structured in ``project/template/Bastillefile`` format, and
|
||||
placed in the template directory, which defaults to
|
||||
``/usr/local/bastille/templates``. The Bastillefile should contain the template
|
||||
hooks. See the chapter called Template for a list of supported hooks.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
@@ -18,7 +18,8 @@ Syntax requires only the jail path to unmount.
|
||||
|
||||
Usage: bastille umount TARGET JAIL_PATH
|
||||
|
||||
If the directory you are unmounting has spaces, make sure to escape them with a backslash \, and enclose the mount point in quotes "".
|
||||
If the directory you are unmounting has spaces, make sure to escape them with a
|
||||
backslash \, and enclose the mount point in quotes "".
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
|
||||
@@ -2,8 +2,8 @@ update
|
||||
======
|
||||
|
||||
The ``update`` command targets a release or a thick jail. Because thin jails are
|
||||
based on a release, when the release is updated all the thin jails are automatically
|
||||
updated as well.
|
||||
based on a release, when the release is updated all the thin jails are
|
||||
automatically updated as well.
|
||||
|
||||
If no updates are available, a message will be shown:
|
||||
|
||||
@@ -38,8 +38,8 @@ The older the release or jail, however, the more updates will be available:
|
||||
|
||||
To be safe, you may want to restart any jails that have been updated live.
|
||||
|
||||
If the jail is a thin jail, an error will be shown. If it is a thick jail, it will be updated just like
|
||||
the release shown above.
|
||||
If the jail is a thin jail, an error will be shown. If it is a thick jail, it
|
||||
will be updated just like the release shown above.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
@@ -49,4 +49,4 @@ the release shown above.
|
||||
|
||||
-a | --auto Auto mode. Start/stop jail(s) if required.
|
||||
-f | --force Force update a release.
|
||||
-x | --debug Enable debug mode.
|
||||
-x | --debug Enable debug mode.
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
upgrade
|
||||
=======
|
||||
|
||||
The ``upgrade`` command targets a thick or thin jail. Thin jails will be updated by changing the
|
||||
release mount point that it is based on. Thick jails will be upgraded normally.
|
||||
The ``upgrade`` command targets a thick or thin jail. Thin jails will be updated
|
||||
by changing the release mount point that it is based on. Thick jails will be
|
||||
upgraded normally.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
verify
|
||||
======
|
||||
|
||||
This command scans a bootstrapped release or template and validates that everything looks
|
||||
in order. This is not a 100% comprehensive check, but it compares the release or template
|
||||
against a "known good" index.
|
||||
This command scans a bootstrapped release or template and validates that
|
||||
everything looks in order. This is not a 100% comprehensive check, but it
|
||||
compares the release or template against a "known good" index.
|
||||
|
||||
If you see errors or issues here, consider deleting and re-bootstrapping
|
||||
the release or template .
|
||||
If you see errors or issues here, consider deleting and re-bootstrapping the
|
||||
release or template .
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
zfs
|
||||
===
|
||||
|
||||
Manage ZFS properties, ceate and destroy snapshots, and check ZFS usage for targeted jail(s).
|
||||
Manage ZFS properties, ceate and destroy snapshots, and check ZFS usage for
|
||||
targeted jail(s).
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
|
||||
Reference in New Issue
Block a user