BastilleBSD/bastille
2
0
Fork 0
Code Pull Requests Actions Packages Releases Activity

0.3.2018112401 bastille.rtfd.org

Browse Source
This commit is contained in:
Christer Edwards
2018-11-24 20:07:20 -07:00
parent 06e3fdacd4
commit 9431af5eb0
29 changed files with 796 additions and 132 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
docs/chapters/subcommands/bootstrap.rst Normal file
View File

@@ -0,0 +1,34 @@
=========
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.
Note: your mileage may vary with unsupported releases and releases newer
than the host system likely will NOT work at all.
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 12.0-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.
Downloaded artifacts are stored in the `cache` directory. "bootstrapped"
releases are stored in `releases/version`.
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.
To update a release as patches are made available, see the `bastille
update` command.

14
docs/chapters/subcommands/cmd.rst Normal file
View File

@@ -0,0 +1,14 @@
===
cmd
===
To execute commands within the jail you can use `bastille cmd`.
.. code-block:: shell
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
root 77447 0.0 0.0 16632 2140 - SsJ 4:52PM 0:00.00 /usr/sbin/cron -J 60 -s
root 80591 0.0 0.0 18784 2340 1 R+J 4:53PM 0:00.00 ps -auxw

36
docs/chapters/subcommands/console.rst Normal file
View File

@@ -0,0 +1,36 @@
console
=======
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
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 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.

21
docs/chapters/subcommands/cp.rst Normal file
View File

@@ -0,0 +1,21 @@
cp
==
This command allows efficiently copying files from host to jail(s).
.. code-block:: shell
ishmael ~ # bastille cp ALL /tmp/resolv.conf-cf etc/resolv.conf
[bastion]:
[unbound0]:
[unbound1]:
[squid]:
[nginx]:
[folsom]:
Unless you see errors reported in the output the `cp` was successful.

32
docs/chapters/subcommands/create.rst Normal file
View File

@@ -0,0 +1,32 @@
======
create
======
Bastille create uses any available bootstrapped release to create a
lightweight jailed system. To create a jail simply provide a name,
bootstrapped release and a private (rfc1918) IP address.
- name
- release
- ip
.. code-block:: shell
ishmael ~ # bastille create folsom 11.2-RELEASE 10.8.62.1
RELEASE: 11.2-RELEASE.
NAME: folsom.
IP: 10.8.62.1.
This command will create a 11.2-RELEASE jail assigning the 10.8.62.1 ip
address to the new system.
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.

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

@@ -0,0 +1,18 @@
destroy
=======
Jails can be destroyed and thrown away just as easily as they were
created. Note: jails must be stopped before destroyed.
.. code-block:: shell
ishmael ~ # bastille stop folsom
[folsom]:
folsom: removed
.. code-block:: shell
ishmael ~ # bastille destroy folsom
Deleting Jail: folsom.
Note: jail console logs not destroyed.
/usr/local/bastille/logs/folsom_console.log

11
docs/chapters/subcommands/htop.rst Normal file
View File

@@ -0,0 +1,11 @@
====
htop
====
This one runs `htop` inside the jail.
note: won't work if you don't have htop installed in the jail.
.. image:: ../../images/htop.png
:align: center
:alt: bastille htop jail

24
docs/chapters/subcommands/index.rst Normal file
View File

@@ -0,0 +1,24 @@
Bastille sub-commands
=====================
.. toctree::
:maxdepth: 2
:caption: Contents:
bootstrap
cmd
console
cp
create
destroy
htop
pkg
restart
start
stop
sysrc
top
update
update
upgrade
verify

164
docs/chapters/subcommands/pkg.rst Normal file
View File

@@ -0,0 +1,164 @@
===
pkg
===
To manage binary packages within the jail use `bastille pkg`.
.. code-block:: shell
ishmael ~ # bastille pkg folsom 'install vim-console git-lite zsh'
[folsom]:
The package management tool is not yet installed on your system.
Do you want to fetch and install it now? [y/N]: y
Bootstrapping pkg from pkg+http://pkg.FreeBSD.org/FreeBSD:10:amd64/quarterly, please wait...
Verifying signature with trusted certificate pkg.freebsd.org.2013102301... done
[folsom] Installing pkg-1.10.5_5...
[folsom] Extracting pkg-1.10.5_5: 100%
Updating FreeBSD repository catalogue...
pkg: Repository FreeBSD load error: access repo file(/var/db/pkg/repo-FreeBSD.sqlite) failed: No such file or directory
[folsom] Fetching meta.txz: 100% 944 B 0.9kB/s 00:01
[folsom] Fetching packagesite.txz: 100% 6 MiB 3.4MB/s 00:02
Processing entries: 100%
FreeBSD repository update completed. 32550 packages processed.
All repositories are up to date.
Updating database digests format: 100%
The following 10 package(s) will be affected (of 0 checked):
New packages to be INSTALLED:
vim-console: 8.1.0342
git-lite: 2.19.1
zsh: 5.6.2
expat: 2.2.6_1
curl: 7.61.1
libnghttp2: 1.33.0
ca_root_nss: 3.40
pcre: 8.42
gettext-runtime: 0.19.8.1_1
indexinfo: 0.3.1
Number of packages to be installed: 10
The process will require 77 MiB more space.
17 MiB to be downloaded.
Proceed with this action? [y/N]: y
[folsom] [1/10] Fetching vim-console-8.1.0342.txz: 100% 5 MiB 5.8MB/s 00:01
[folsom] [2/10] Fetching git-lite-2.19.1.txz: 100% 4 MiB 2.1MB/s 00:02
[folsom] [3/10] Fetching zsh-5.6.2.txz: 100% 4 MiB 4.4MB/s 00:01
[folsom] [4/10] Fetching expat-2.2.6_1.txz: 100% 109 KiB 111.8kB/s 00:01
[folsom] [5/10] Fetching curl-7.61.1.txz: 100% 1 MiB 1.2MB/s 00:01
[folsom] [6/10] Fetching libnghttp2-1.33.0.txz: 100% 107 KiB 109.8kB/s 00:01
[folsom] [7/10] Fetching ca_root_nss-3.40.txz: 100% 287 KiB 294.3kB/s 00:01
[folsom] [8/10] Fetching pcre-8.42.txz: 100% 1 MiB 1.2MB/s 00:01
[folsom] [9/10] Fetching gettext-runtime-0.19.8.1_1.txz: 100% 148 KiB 151.3kB/s 00:01
[folsom] [10/10] Fetching indexinfo-0.3.1.txz: 100% 6 KiB 5.7kB/s 00:01
Checking integrity... done (0 conflicting)
[folsom] [1/10] Installing libnghttp2-1.33.0...
[folsom] [1/10] Extracting libnghttp2-1.33.0: 100%
[folsom] [2/10] Installing ca_root_nss-3.40...
[folsom] [2/10] Extracting ca_root_nss-3.40: 100%
[folsom] [3/10] Installing indexinfo-0.3.1...
[folsom] [3/10] Extracting indexinfo-0.3.1: 100%
[folsom] [4/10] Installing expat-2.2.6_1...
[folsom] [4/10] Extracting expat-2.2.6_1: 100%
[folsom] [5/10] Installing curl-7.61.1...
[folsom] [5/10] Extracting curl-7.61.1: 100%
[folsom] [6/10] Installing pcre-8.42...
[folsom] [6/10] Extracting pcre-8.42: 100%
[folsom] [7/10] Installing gettext-runtime-0.19.8.1_1...
[folsom] [7/10] Extracting gettext-runtime-0.19.8.1_1: 100%
[folsom] [8/10] Installing vim-console-8.1.0342...
[folsom] [8/10] Extracting vim-console-8.1.0342: 100%
[folsom] [9/10] Installing git-lite-2.19.1...
===> Creating groups.
Creating group 'git_daemon' with gid '964'.
===> Creating users
Creating user 'git_daemon' with uid '964'.
[folsom] [9/10] Extracting git-lite-2.19.1: 100%
[folsom] [10/10] Installing zsh-5.6.2...
[folsom] [10/10] Extracting zsh-5.6.2: 100%
The PKG sub-command can, of course, 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., etc.
.. code-block:: shell
ishmael ~ # bastille pkg ALL upgrade
[bastion]:
Updating iniquity.io 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.
All repositories are up to date.
Checking for upgrades (1 candidates): 100%
Processing candidates (1 candidates): 100%
Checking integrity... done (0 conflicting)
Your packages are up to date.
[unbound0]:
Updating iniquity.io 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.
All repositories are up to date.
Checking for upgrades (0 candidates): 100%
Processing candidates (0 candidates): 100%
Checking integrity... done (0 conflicting)
Your packages are up to date.
[unbound1]:
Updating iniquity.io 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.
All repositories are up to date.
Checking for upgrades (0 candidates): 100%
Processing candidates (0 candidates): 100%
Checking integrity... done (0 conflicting)
Your packages are up to date.
[squid]:
Updating iniquity.io 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.
All repositories are up to date.
Checking for upgrades (0 candidates): 100%
Processing candidates (0 candidates): 100%
Checking integrity... done (0 conflicting)
Your packages are up to date.
[nginx]:
Updating iniquity.io 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.
All repositories are up to date.
Checking for upgrades (1 candidates): 100%
Processing candidates (1 candidates): 100%
The following 1 package(s) will be affected (of 0 checked):
Installed packages to be UPGRADED:
nginx-lite: 1.14.0_14,2 -> 1.14.1,2
Number of packages to be upgraded: 1
315 KiB to be downloaded.
Proceed with this action? [y/N]: y
[nginx] [1/1] Fetching nginx-lite-1.14.1,2.txz: 100% 315 KiB 322.8kB/s 00:01
Checking integrity... done (0 conflicting)
[nginx] [1/1] Upgrading nginx-lite from 1.14.0_14,2 to 1.14.1,2...
===> Creating groups.
Using existing group 'www'.
===> Creating users
Using existing user 'www'.
[nginx] [1/1] Extracting nginx-lite-1.14.1,2: 100%
You may need to manually remove /usr/local/etc/nginx/nginx.conf if it is no longer needed.

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

@@ -0,0 +1,13 @@
restart
=======
To restart a jail you can use the `bastille restart` command.
.. code-block:: shell
ishmael ~ # bastille restart folsom
[folsom]:
folsom: removed
[folsom]:
folsom: created

10
docs/chapters/subcommands/start.rst Normal file
View File

@@ -0,0 +1,10 @@
start
=====
To start a jail you can use the `bastille start` command.
.. code-block:: shell
ishmael ~ # bastille start folsom
[folsom]:
folsom: created

10
docs/chapters/subcommands/stop.rst Normal file
View File

@@ -0,0 +1,10 @@
stop
====
To stop a jail you can use the `bastille stop` command.
.. code-block:: shell
ishmael ~ # bastille stop folsom
[folsom]:
folsom: removed

14
docs/chapters/subcommands/sysrc.rst Normal file
View File

@@ -0,0 +1,14 @@
=====
sysrc
=====
The `sysrc` sub-command allows for safely editing system configuration files.
In jail terms, this allows us to toggle on/off services and options at startup.
.. code-block:: shell
ishmael ~ # bastille sysrc nginx nginx_enable="YES"
[nginx]:
nginx_enable: NO -> YES
See `man sysrc(8)` for more info.

10
docs/chapters/subcommands/top.rst Normal file
View File

@@ -0,0 +1,10 @@
===
top
===
This one runs `top` in that jail.
.. image:: ../../images/top.png
:align: center
:alt: bastille top jail

41
docs/chapters/subcommands/update.rst Normal file
View File

@@ -0,0 +1,41 @@
======
update
======
The `update` command targets a release instead of a jail. Because every jail is
based on a release, when the release is updated all the jails are automatically
updated as well.
If no updates are available, a message will be shown:
.. code-block:: shell
ishmael ~ # bastille update 11.2-RELEASE
Looking up update.FreeBSD.org mirrors... 2 mirrors found.
Fetching metadata signature for 11.2-RELEASE from update4.freebsd.org... done.
Fetching metadata index... done.
Inspecting system... done.
Preparing to download files... done.
No updates needed to update system to 11.2-RELEASE-p4.
No updates are available to install.
The older the release, however, the more updates will be available:
.. code-block:: shell
ishmael ~ # bastille update 10.4-RELEASE
Looking up update.FreeBSD.org mirrors... 2 mirrors found.
Fetching metadata signature for 10.4-RELEASE from update1.freebsd.org... done.
Fetching metadata index... done.
Fetching 2 metadata patches.. done.
Applying metadata patches... done.
Fetching 2 metadata files... done.
Inspecting system... done.
Preparing to download files... done.
The following files will be added as part of updating to 10.4-RELEASE-p13:
...[snip]...
To be safe, you may want to restart any jails that have been updated live.

11
docs/chapters/subcommands/upgrade.rst Normal file
View File

@@ -0,0 +1,11 @@
=======
upgrade
=======
This command lets you upgrade a release to a new release. Depending on the
workflow this can be similar to a `bootstrap`.
.. code-block:: shell
ishmael ~ # bastille upgrade 11.2-RELEASE 12.0-RELEASE

21
docs/chapters/subcommands/verify.rst Normal file
View File

@@ -0,0 +1,21 @@
======
verify
======
This command scans a bootstrapped release and validates that everything looks
in order. This is not a 100% comprehensive check, but it compares the release
against a "known good" index.
If you see errors or issues here, consider deleting and re-bootstrapping
the release.
.. code-block:: shell
ishmael ~ # bastille verify 11.2-RELEASE
Looking up update.FreeBSD.org mirrors... 2 mirrors found.
Fetching metadata signature for 11.2-RELEASE from update1.freebsd.org... done.
Fetching metadata index... done.
Fetching 1 metadata patches. done.
Applying metadata patches... done.
Fetching 1 metadata files... done.
Inspecting system... done.