BastilleBSD/bastille
2
0
Fork 0
Code Pull Requests Actions Packages Releases 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

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'