diff --git a/docs/README.md b/docs/README.md deleted file mode 120000 index 32d46ee8..00000000 --- a/docs/README.md +++ /dev/null @@ -1 +0,0 @@ -../README.md \ No newline at end of file diff --git a/docs/chapters/installation.rst b/docs/chapters/installation.rst new file mode 100644 index 00000000..fba201fa --- /dev/null +++ b/docs/chapters/installation.rst @@ -0,0 +1,30 @@ +Installation +============ + +Bastille is not (yet) in the official ports tree, but I have built and +verified binary packages. + +To install using one of the BETA binary packages, copy the URL for the +latest release here (TXZ file): +https://github.com/bastillebsd/bastille/releases + +Then, install via pkg. +Example: + +.. code-block:: shell + + pkg add https://github.com/BastilleBSD/bastille/releases/download/0.3.20181124/bastille-0.3.20181124.txz + +BETA binary packages are signed. These can be verified with this pubkey: + +.. code-block:: shell + + -----BEGIN PUBLIC KEY----- + MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAq28OLDhJ12JmsKKcJpnn + pCW3fFYBNI1BtdvTvFx57ZXvQ2qecBvnR9+XWi83hKS9ALTKZI6CLC2uTv1fIsZl + u6rDRRNZwZFfITACSfwI+7UObMXz3oBZjk94J3rIegk49EyjDswKdVWv5k1EiVXF + SAwXSl2kA2hGfQJkj5NS4nrfoRBc0z6fm+BGdNuHKSTmeZh1dbLEHt9EArD20DJ7 + HIr8vUSPLwONeqJCBFA/MeDO+GpwtwA/ldc2ZZy1RCPctdC2NeiGW7oy1yVDu6wp + mHCq8qDfmCx5Aex84rWUf9iH8TM92AWmegTaz2p+BgESctpjNRCUuSEwOCBIO6g5 + 3wIDAQAB + -----END PUBLIC KEY----- diff --git a/docs/chapters/networking.rst b/docs/chapters/networking.rst new file mode 100644 index 00000000..6b8cd847 --- /dev/null +++ b/docs/chapters/networking.rst @@ -0,0 +1,79 @@ +==================== +Network Requirements +==================== + +In order to segregate jails from the network and from the world, Bastille +attaches jails to a loopback interface only. The host system then acts as +the firewall, permitting and denying traffic as needed. + +First, create the loopback interface: + +.. code-block:: shell + + ishmael ~ # sysrc cloned_interfaces+=lo1 + ishmael ~ # service netif cloneup + +Second, enable NAT through the firewall: + +.. code-block:: shell + + ishmael ~ # sysrc pf_enable="YES" + +/etc/pf.conf +------------ + +Create the firewall config, or merge as necessary. + +.. code-block:: shell + + ext_if="vtnet0" + + set block-policy drop + scrub in on $ext_if all fragment reassemble + + set skip on lo + nat on $ext_if from !($ext_if) -> ($ext_if:0) + + ## rdr example + ## rdr pass inet proto tcp from any to any port {80, 443} -> 10.88.9.45 + + block in log all + pass out quick modulate state + antispoof for $ext_if inet + pass in inet proto tcp from any to any port ssh flags S/SA keep state + + +- Make sure to change the `ext_if` variable to match your host system interface. +- Make sure to include the last line (`port ssh`) or you'll end up locked out. + + +Note: if you have an existing firewall, the key lines for in/out traffic +to jails are: + +.. code-block:: shell + + nat on $ext_if from lo1:network to any -> ($ext_if) + + ## rdr example + ## rdr pass inet proto tcp from any to any port {80, 443} -> 10.88.9.45 + +The `nat` routes traffic from the loopback interface to the external +interface for outbound access. + +The `rdr pass ...` will redirect traffic from the host firewall on port X +to the ip of Jail Y. The example shown redirects web traffic (80 & 443) to +the jails at `10.88.9.45`. + +We'll get to that later, but when you're ready to allow traffic inbound to +your jails, that's where you'd do it. + +Finally, start up the firewall: + +.. code-block:: shell + + ishmael ~ # service pf restart + +At this point you'll likely be disconnected from the host. Reconnect the +ssh session and continue. + +This step only needs to be done once in order to prepare the host. diff --git a/docs/chapters/subcommands/bootstrap.rst b/docs/chapters/subcommands/bootstrap.rst new file mode 100644 index 00000000..ecd0957b --- /dev/null +++ b/docs/chapters/subcommands/bootstrap.rst @@ -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. diff --git a/docs/chapters/subcommands/cmd.rst b/docs/chapters/subcommands/cmd.rst new file mode 100644 index 00000000..bb09f2dd --- /dev/null +++ b/docs/chapters/subcommands/cmd.rst @@ -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 diff --git a/docs/chapters/subcommands/console.rst b/docs/chapters/subcommands/console.rst new file mode 100644 index 00000000..908d4525 --- /dev/null +++ b/docs/chapters/subcommands/console.rst @@ -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. diff --git a/docs/chapters/subcommands/cp.rst b/docs/chapters/subcommands/cp.rst new file mode 100644 index 00000000..45987037 --- /dev/null +++ b/docs/chapters/subcommands/cp.rst @@ -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. diff --git a/docs/chapters/subcommands/create.rst b/docs/chapters/subcommands/create.rst new file mode 100644 index 00000000..05a4b508 --- /dev/null +++ b/docs/chapters/subcommands/create.rst @@ -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. diff --git a/docs/chapters/subcommands/destroy.rst b/docs/chapters/subcommands/destroy.rst new file mode 100644 index 00000000..f6686145 --- /dev/null +++ b/docs/chapters/subcommands/destroy.rst @@ -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 diff --git a/docs/chapters/subcommands/htop.rst b/docs/chapters/subcommands/htop.rst new file mode 100644 index 00000000..c0f7951e --- /dev/null +++ b/docs/chapters/subcommands/htop.rst @@ -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 diff --git a/docs/chapters/subcommands/index.rst b/docs/chapters/subcommands/index.rst new file mode 100644 index 00000000..8f70966c --- /dev/null +++ b/docs/chapters/subcommands/index.rst @@ -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 diff --git a/docs/chapters/subcommands/pkg.rst b/docs/chapters/subcommands/pkg.rst new file mode 100644 index 00000000..cf98a816 --- /dev/null +++ b/docs/chapters/subcommands/pkg.rst @@ -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. diff --git a/docs/chapters/subcommands/restart.rst b/docs/chapters/subcommands/restart.rst new file mode 100644 index 00000000..eeabd3dc --- /dev/null +++ b/docs/chapters/subcommands/restart.rst @@ -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 diff --git a/docs/chapters/subcommands/start.rst b/docs/chapters/subcommands/start.rst new file mode 100644 index 00000000..ddf93fbf --- /dev/null +++ b/docs/chapters/subcommands/start.rst @@ -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 diff --git a/docs/chapters/subcommands/stop.rst b/docs/chapters/subcommands/stop.rst new file mode 100644 index 00000000..f9aeee46 --- /dev/null +++ b/docs/chapters/subcommands/stop.rst @@ -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 diff --git a/docs/chapters/subcommands/sysrc.rst b/docs/chapters/subcommands/sysrc.rst new file mode 100644 index 00000000..03a97a0a --- /dev/null +++ b/docs/chapters/subcommands/sysrc.rst @@ -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. diff --git a/docs/chapters/subcommands/top.rst b/docs/chapters/subcommands/top.rst new file mode 100644 index 00000000..571e8dee --- /dev/null +++ b/docs/chapters/subcommands/top.rst @@ -0,0 +1,10 @@ +=== +top +=== + +This one runs `top` in that jail. + + +.. image:: ../../images/top.png + :align: center + :alt: bastille top jail diff --git a/docs/chapters/subcommands/update.rst b/docs/chapters/subcommands/update.rst new file mode 100644 index 00000000..9a03fe55 --- /dev/null +++ b/docs/chapters/subcommands/update.rst @@ -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. diff --git a/docs/chapters/subcommands/upgrade.rst b/docs/chapters/subcommands/upgrade.rst new file mode 100644 index 00000000..af917c09 --- /dev/null +++ b/docs/chapters/subcommands/upgrade.rst @@ -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 + diff --git a/docs/chapters/subcommands/verify.rst b/docs/chapters/subcommands/verify.rst new file mode 100644 index 00000000..9ecec6ca --- /dev/null +++ b/docs/chapters/subcommands/verify.rst @@ -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. diff --git a/docs/chapters/targeting.rst b/docs/chapters/targeting.rst new file mode 100644 index 00000000..256d2b02 --- /dev/null +++ b/docs/chapters/targeting.rst @@ -0,0 +1,3 @@ +========= +Targeting +========= diff --git a/docs/chapters/template.rst b/docs/chapters/template.rst new file mode 100644 index 00000000..a25e816e --- /dev/null +++ b/docs/chapters/template.rst @@ -0,0 +1,132 @@ +======== +Template +======== + +Bastille supports a templating system allowing you to apply files, pkgs and +execute commands inside the jail automatically. + +Currently supported template hooks are: `PRE`, `CONFIG`, `PKG`, `SYSRC`, `CMD`. +Planned template hooks include: `FSTAB`, `PF` + +Templates are created in `${bastille_prefix}/templates` and can leverage any of +the template hooks. Simply create a new directory named after the template. eg; + +.. code-block:: shell + + mkdir -p /usr/local/bastille/templates/base + +To leverage a template hook, create an UPPERCASE file in the root of the +template directory named after the hook you want to execute. eg; + +.. code-block:: shell + + echo "zsh vim-console git-lite htop" > /usr/local/bastille/templates/base/PKG + echo "/usr/bin/chsh -s /usr/local/bin/zsh" > /usr/local/bastille/templates/base/CMD + echo "etc root usr" > /usr/local/bastille/templates/base/CONFIG + +Template hooks are executed in specific order and require specific syntax to +work as expected. This table outlines those requirements: + + ++---------+------------------+--------------------------------------+ +| HOOK | format | example | ++=========+==================+======================================+ +| PRE/CMD | /bin/sh command | /usr/bin/chsh -s /usr/local/bin/zsh | ++---------+------------------+--------------------------------------+ +| CONFIG | path | etc root usr | ++---------+------------------+--------------------------------------+ +| PKG | port/pkg name(s) | vim-console zsh git-lite tree htop | ++---------+------------------+--------------------------------------+ +| SYSRC | sysrc command(s) | nginx_enable=YES | ++---------+------------------+--------------------------------------+ + +Note: SYSRC requires NO quotes or that quotes (`"`) be escaped. ie; `\"`) + +In addition to supporting template hooks, Bastille supports overlaying +files into the jail. This is done by placing the files in their full path, +using the template directory as "/". + +An example here may help. Think of `/usr/local/bastille/templates/base`, +our example template, as the root of our filesystem overlay. If you create +an `etc/hosts` or `etc/resolv.conf` *inside* the base template directory, +these can be overlayed into your jail. + +Note: due to the way FreeBSD segregates user-space, the majority of your +overlayed template files will be in `usr/local`. The few general +exceptions are the `etc/hosts`, `etc/resolv.conf`, and +`etc/rc.conf.local`. + +After populating `usr/local/` with custom config files that your jail will +use, be sure to include `usr` in the template CONFIG definition. eg; + +.. code-block:: shell + + echo "etc usr" > /usr/local/bastille/templates/base/CONFIG + +The above example "etc usr" will include anything under "etc" and "usr" +inside the template. You do not need to list individual files. Just +include the top-level directory name. + +Applying Templates +------------------ + +Jails must be running to apply templates. + +Bastille includes a `template` command. This command requires a target and a +template name. As covered in the previous section, template names correspond to +directory names in the `bastille/templates` directory. + +.. code-block:: shell + + ishmael ~ # bastille template ALL base + [cdn]: + Copying files... + Copy complete. + Installing packages. + pkg already bootstrapped at /usr/local/sbin/pkg + vulnxml file up-to-date + 0 problem(s) in the installed packages found. + Updating iniquity.io repository catalogue... + [cdn] Fetching meta.txz: 100% 560 B 0.6kB/s 00:01 + [cdn] Fetching packagesite.txz: 100% 121 KiB 124.3kB/s 00:01 + Processing entries: 100% + iniquity.io repository update completed. 499 packages processed. + All repositories are up to date. + Checking integrity... done (0 conflicting) + The most recent version of packages are already installed + Updating services. + cron_flags: -J 60 -> -J 60 + sendmail_enable: NONE -> NONE + syslogd_flags: -ss -> -ss + Executing final command(s). + chsh: user information updated + Template Complete. + + [poudriere]: + Copying files... + Copy complete. + Installing packages. + pkg already bootstrapped at /usr/local/sbin/pkg + vulnxml file up-to-date + 0 problem(s) in the installed packages found. + Updating cdn.iniquity.io repository catalogue... + [poudriere] Fetching meta.txz: 100% 560 B 0.6kB/s 00:01 + [poudriere] Fetching packagesite.txz: 100% 121 KiB 124.3kB/s 00:01 + Processing entries: 100% + cdn.iniquity.io repository update completed. 499 packages processed. + Updating iniquity.io repository catalogue... + [poudriere] Fetching meta.txz: 100% 560 B 0.6kB/s 00:01 + [poudriere] Fetching packagesite.txz: 100% 121 KiB 124.3kB/s 00:01 + Processing entries: 100% + iniquity.io repository update completed. 499 packages processed. + All repositories are up to date. + Checking integrity... done (0 conflicting) + The most recent version of packages are already installed + Updating services. + cron_flags: -J 60 -> -J 60 + sendmail_enable: NONE -> NONE + syslogd_flags: -ss -> -ss + Executing final command(s). + chsh: user information updated + Template Complete. + diff --git a/docs/chapters/usage.rst b/docs/chapters/usage.rst new file mode 100644 index 00000000..f7e4cf80 --- /dev/null +++ b/docs/chapters/usage.rst @@ -0,0 +1,32 @@ +===== +Usage +===== + +.. code-block:: shell + + ishmael ~ # bastille -h + Usage: + bastille command [ALL|glob] [args] + + Available Commands: + bootstrap Bootstrap a FreeBSD release for jail base. + cmd Execute arbitrary command on targeted jail(s). + console Console into a running jail. + cp cp(1) files from host to targeted jail(s). + create Create a new jail. + destroy Destroy a stopped jail. + help Help about any command + htop Interactive process viewer (requires htop). + list List jails (running and stopped). + pkg Manipulate binary packages within targeted jail(s). See pkg(8). + restart Restart a running jail. + start Start a stopped jail. + stop Stop a running jail. + sysrc Safely edit rc files within targeted jail(s). + template Apply Bastille template to running jail(s). + top Display and update information about the top(1) cpu processes. + update Update jail base -pX release. + upgrade Upgrade jail release to X.Y-RELEASE. + + Use "bastille -v|--version" for version information. + Use "bastille command -h|--help" for more information about a command. diff --git a/docs/conf.py b/docs/conf.py index 848ff08d..b937144c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,21 +1,3 @@ -# -*- coding: utf-8 -*- -# -# Configuration file for the Sphinx documentation builder. -# -# This file does only contain a selection of the most common options. For a -# full list see the documentation: -# http://www.sphinx-doc.org/en/master/config - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - import os on_rtd = os.environ.get('READTHEDOCS') == 'True' if on_rtd: @@ -30,124 +12,51 @@ copyright = '2018, Christer Edwards' author = 'Christer Edwards' # The short X.Y version -version = '0.3' +version = '0.3.20181124' # The full version, including alpha/beta/rc tags -release = 'beta' +release = '0.3.20181124-beta' # -- General configuration --------------------------------------------------- -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. extensions = [ ] -# Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = '.md' +source_suffix = ['.rst', '.md'] from recommonmark.parser import CommonMarkParser source_parsers = { '.md': CommonMarkParser, } -# The master toctree document. -master_doc = 'README' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. +master_doc = 'index' language = None - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] - -# The name of the Pygments (syntax highlighting) style to use. pygments_style = None - # -- Options for HTML output ------------------------------------------------- -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -##html_theme = 'alabaster' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -# html_theme_options = {} - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] -# Custom sidebar templates, must be a dictionary that maps document names -# to template names. -# -# The default sidebars (for documents that don't match any pattern) are -# defined by theme itself. Builtin themes are using these templates by -# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', -# 'searchbox.html']``. -# -# html_sidebars = {} - - # -- Options for HTMLHelp output --------------------------------------------- -# Output file base name for HTML help builder. htmlhelp_basename = 'Bastilledoc' # -- Options for LaTeX output ------------------------------------------------ latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', } -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). latex_documents = [ (master_doc, 'Bastille.tex', 'Bastille Documentation', 'Christer Edwards', 'manual'), ] - # -- Options for manual page output ------------------------------------------ -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). man_pages = [ (master_doc, 'bastille', 'Bastille Documentation', [author], 1) @@ -156,30 +65,15 @@ man_pages = [ # -- Options for Texinfo output ---------------------------------------------- -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) texinfo_documents = [ (master_doc, 'Bastille', 'Bastille Documentation', - author, 'Bastille', 'One line description of project.', + author, 'Bastille', 'Bastille is a jail automation framework that allows you to quickly and easily create and manage FreeBSD jails.', 'Miscellaneous'), ] - # -- Options for Epub output ------------------------------------------------- -# Bibliographic Dublin Core info. epub_title = project -# The unique identifier of the text. This can be a ISBN number -# or the project homepage. -# -# epub_identifier = '' - -# A unique identification for the text. -# -# epub_uid = '' - # A list of files that should not be packed into the epub file. epub_exclude_files = ['search.html'] - diff --git a/docs/copyright.rst b/docs/copyright.rst new file mode 100644 index 00000000..88f1804c --- /dev/null +++ b/docs/copyright.rst @@ -0,0 +1,8 @@ +========= +Copyright +========= + +This content is copyright Christer Edwards. All rights reserved. + +Duplication of this content without the express written permission of the +author is not permitted. diff --git a/docs/images/htop.png b/docs/images/htop.png new file mode 100644 index 00000000..8cad2697 Binary files /dev/null and b/docs/images/htop.png differ diff --git a/docs/images/top.png b/docs/images/top.png new file mode 100644 index 00000000..1dbfdd0f Binary files /dev/null and b/docs/images/top.png differ diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..20b3426b --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,23 @@ +Bastille +======== + +Welcome to the official Bastille documentation. This collection of documents +will outline installation and usage of Bastille. + +The latest version of this documentation can always be found at +https://docs.bastillebsd.org. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + chapters/installation + chapters/networking + chapters/usage + chapters/targeting + chapters/subcommands/index + chapters/template + + copyright + +Note: this documentation is included with the source code in `docs`. diff --git a/docs/index.rst.sample b/docs/index.rst.sample deleted file mode 100644 index 25e15cae..00000000 --- a/docs/index.rst.sample +++ /dev/null @@ -1,20 +0,0 @@ -.. Bastille documentation master file, created by - sphinx-quickstart on Tue Nov 20 20:48:22 2018. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to Bastille's documentation! -==================================== - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search`