diff --git a/docs/chapters/installation.rst b/docs/chapters/installation.rst index fba201fa..c9b786c5 100644 --- a/docs/chapters/installation.rst +++ b/docs/chapters/installation.rst @@ -1,30 +1,27 @@ Installation ============ +Bastille is available in the official FreeBSD ports tree at +`sysutils/bastille`. Binary packages available in `quarterly` and `latest` +repositories. -Bastille is not (yet) in the official ports tree, but I have built and -verified binary packages. +Current version is `0.3.20191025`. -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 +To install from the FreeBSD package repository: -Then, install via pkg. -Example: +* quarterly repository may be older version +* latest repository will match recent ports -.. code-block:: shell - pkg add https://github.com/BastilleBSD/bastille/releases/download/0.3.20181124/bastille-0.3.20181124.txz +PKG +--- +```shell +pkg install bastille +``` -BETA binary packages are signed. These can be verified with this pubkey: +To install from source (don't worry, no compiling): -.. code-block:: shell - - -----BEGIN PUBLIC KEY----- - MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAq28OLDhJ12JmsKKcJpnn - pCW3fFYBNI1BtdvTvFx57ZXvQ2qecBvnR9+XWi83hKS9ALTKZI6CLC2uTv1fIsZl - u6rDRRNZwZFfITACSfwI+7UObMXz3oBZjk94J3rIegk49EyjDswKdVWv5k1EiVXF - SAwXSl2kA2hGfQJkj5NS4nrfoRBc0z6fm+BGdNuHKSTmeZh1dbLEHt9EArD20DJ7 - HIr8vUSPLwONeqJCBFA/MeDO+GpwtwA/ldc2ZZy1RCPctdC2NeiGW7oy1yVDu6wp - mHCq8qDfmCx5Aex84rWUf9iH8TM92AWmegTaz2p+BgESctpjNRCUuSEwOCBIO6g5 - 3wIDAQAB - -----END PUBLIC KEY----- +ports +----- +```shell +make -C /usr/ports/sysutils/bastille install clean +``` diff --git a/docs/chapters/jail-config.rst b/docs/chapters/jail-config.rst new file mode 100644 index 00000000..71cf998e --- /dev/null +++ b/docs/chapters/jail-config.rst @@ -0,0 +1,204 @@ +jail.conf +========= +In this section we'll look at the default config for a new container. The +defaults are sane for most applications, but if you want to tweak the settings +here they are. + +A `jail.conf` template is used each time a new container is created. This +template looks like this: + +.. code-block:: shell + + interface = {interface}; + host.hostname = {name}; + exec.consolelog = /usr/local/bastille/logs/{name}_console.log; + path = /usr/local/bastille/jails/{name}/root; + ip6 = disable; + securelevel = 2; + devfs_ruleset = 4; + enforce_statfs = 2; + exec.start = '/bin/sh /etc/rc'; + exec.stop = '/bin/sh /etc/rc.shutdown'; + exec.clean; + mount.devfs; + mount.fstab = /usr/local/bastille/jails/{name}/fstab; + + {name} { + ip4.addr = x.x.x.x; + } + + +interface +--------- +.. code-block:: shell + + interface + A network interface to add the jail's IP addresses (ip4.addr and + ip6.addr) to. An alias for each address will be added to the + interface before the jail is created, and will be removed from + the interface after the jail is removed. + + +host.hostname +------------- +.. code-block:: shell + + host.hostname + The hostname of the jail. Other similar parameters are + host.domainname, host.hostuuid and host.hostid. + + +exec.consolelog +--------------- +.. code-block:: shell + + exec.consolelog + A file to direct command output (stdout and stderr) to. + + +path +---- +.. code-block:: shell + + path + The directory which is to be the root of the jail. Any commands + run inside the jail, either by jail or from jexec(8), are run + from this directory. + + +securelevel +----------- +By default, Bastille containers run at `securelevel = 2;`. See below for the +implications of kernel security levels and when they might be altered. + +Note: Bastille does not currently have any mechanism to automagically change +securelevel settings. My recommendation is this only be altered manually on a +case-by-case basis and that "Highly secure mode" is a sane default for most use +cases. + +.. code-block:: shell + + The kernel runs with five different security levels. Any super-user + process can raise the level, but no process can lower it. The security + levels are: + + -1 Permanently insecure mode - always run the system in insecure mode. + This is the default initial value. + + 0 Insecure mode - immutable and append-only flags may be turned off. + All devices may be read or written subject to their permissions. + + 1 Secure mode - the system immutable and system append-only flags may + not be turned off; disks for mounted file systems, /dev/mem and + /dev/kmem may not be opened for writing; /dev/io (if your platform + has it) may not be opened at all; kernel modules (see kld(4)) may + not be loaded or unloaded. The kernel debugger may not be entered + using the debug.kdb.enter sysctl. A panic or trap cannot be forced + using the debug.kdb.panic and other sysctl's. + + 2 Highly secure mode - same as secure mode, plus disks may not be + opened for writing (except by mount(2)) whether mounted or not. + This level precludes tampering with file systems by unmounting + them, but also inhibits running newfs(8) while the system is multi- + user. + + In addition, kernel time changes are restricted to less than or + equal to one second. Attempts to change the time by more than this + will log the message "Time adjustment clamped to +1 second". + + 3 Network secure mode - same as highly secure mode, plus IP packet + filter rules (see ipfw(8), ipfirewall(4) and pfctl(8)) cannot be + changed and dummynet(4) or pf(4) configuration cannot be adjusted. + + +devfs_ruleset +------------- +.. code-block:: shell + + devfs_ruleset + The number of the devfs ruleset that is enforced for mounting + devfs in this jail. A value of zero (default) means no ruleset + is enforced. Descendant jails inherit the parent jail's devfs + ruleset enforcement. Mounting devfs inside a jail is possible + only if the allow.mount and allow.mount.devfs permissions are + effective and enforce_statfs is set to a value lower than 2. + Devfs rules and rulesets cannot be viewed or modified from inside + a jail. + + NOTE: It is important that only appropriate device nodes in devfs + be exposed to a jail; access to disk devices in the jail may + permit processes in the jail to bypass the jail sandboxing by + modifying files outside of the jail. See devfs(8) for + information on how to use devfs rules to limit access to entries + in the per-jail devfs. A simple devfs ruleset for jails is + available as ruleset #4 in /etc/defaults/devfs.rules. + + +enforce_statfs +-------------- +.. code-block:: shell + + enforce_statfs + This determines what information processes in a jail are able to + get about mount points. It affects the behaviour of the + following syscalls: statfs(2), fstatfs(2), getfsstat(2), and + fhstatfs(2) (as well as similar compatibility syscalls). When + set to 0, all mount points are available without any + restrictions. When set to 1, only mount points below the jail's + chroot directory are visible. In addition to that, the path to + the jail's chroot directory is removed from the front of their + pathnames. When set to 2 (default), above syscalls can operate + only on a mount-point where the jail's chroot directory is + located. + + +exec.start +---------- +.. code-block:: shell + + exec.start + Command(s) to run in the jail environment when a jail is created. + A typical command to run is "sh /etc/rc". + + +exec.stop +--------- +.. code-block:: shell + + exec.stop + Command(s) to run in the jail environment before a jail is + removed, and after any exec.prestop commands have completed. A + typical command to run is "sh /etc/rc.shutdown". + + +exec.clean +---------- +.. code-block:: shell + + exec.clean + Run commands in a clean environment. The environment is + discarded except for HOME, SHELL, TERM and USER. HOME and SHELL + are set to the target login's default values. USER is set to the + target login. TERM is imported from the current environment. + The environment variables from the login class capability + database for the target login are also set. + + +mount.devfs +----------- +.. code-block:: shell + + mount.devfs + Mount a devfs(5) filesystem on the chrooted /dev directory, and + apply the ruleset in the devfs_ruleset parameter (or a default of + ruleset 4: devfsrules_jail) to restrict the devices visible + inside the jail. + + +mount.fstab +----------- +.. code-block:: shell + + mount.fstab + An fstab(5) format file containing filesystems to mount before + creating a jail. diff --git a/docs/chapters/networking.rst b/docs/chapters/networking.rst index 6b8cd847..d0f71347 100644 --- a/docs/chapters/networking.rst +++ b/docs/chapters/networking.rst @@ -1,71 +1,134 @@ -==================== Network Requirements ==================== +Here's the scenario. You've installed Bastille at home or in the cloud and want +to get started putting applications in secure little containers, but how do I +get these containers on the network? -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. +Bastille tries to be flexible about how to network containerized applications. +The two most common methods are described here. Consider both options to decide +which design work best for your needs. One of the methods works better across +clouds while the other is simpler if used in local area networks. + +As you've probably seen, Bastille containers require certain information when +they are created. An IP address has to be assigned to the container through +which all network traffic will flow. + +When the container is started the IP address assigned at creation will be bound +to a network interface. In FreeBSD these interfaces have different names, but +look something like `em0`, `bge0`, `re0`, etc. On a virtual machine it may be +`vtnet0`. You get the idea... + +**Note: if you are running in the cloud and only have a single public IP you +may want the Public Network option. See below.** + + +Local Area Network +------------------ +I will cover the local area network (LAN) method first. This method is simpler +to get going and works well in a home network (or similar) where adding alias +IP addresses is no problem. + +Bastille allows you to define the interface you want the IP attached to when +you create it. An example: + +```shell +bastille create alcatraz 12.1-RELEASE 192.168.1.50 em0 +``` + +When the `alcatraz` container is started it will add `192.168.1.60` as an IP +alias to the `em0` interface. It will then simply be another member of the +hosts network. Other networked systems (firewall permitting) should be able to +reach services at that address. + +This method is the simplest. All you need to know is the name of your network +interface and a free IP on your current network. + +(Bastille does try to verify that the interface name you provide it is a valid +interface. This validation has not been exhaustively tested yet in Bastille's +beta state.) + + +Public Network +-------------- +In this section I'll describe how to network containers in a public network +such as a cloud hosting provider (AWS, digital ocean, vultr, etc) + +In the public cloud you don't often have access to multiple private IP +addresses for your virtual machines. This means if you want to create multiple +containers and assign them all IP addresses, you'll need to create a new +network. + +What I recommend is creating a cloned loopback interface (`bastille0`) and +assigning all the containers private (rfc1918) addresses on that interface. The +setup I develop on and use Bastille day to day uses the `10.0.0.0/8` address +range. I have the ability to use whatever address I want within that range +because I've created my own private network. The host system then acts as the +firewall, permitting and denying traffic as needed. + +I find this setup the most flexible across all types of networks. It can be +used in public and private networks just the same and it allows me to keep +containers off the network until I allow access. + +Having said all that here are instructions I used to configure the network with +a private loopback interface and system firewall. The system firewall NATs +traffic out of containers and can selectively redirect traffic into containers +based on connection ports (ie; 80, 443, etc.) First, create the loopback interface: .. code-block:: shell ishmael ~ # sysrc cloned_interfaces+=lo1 + ishmael ~ # ifconfig_lo1_name="bastille0" ishmael ~ # service netif cloneup -Second, enable NAT through the firewall: +Second, enable the firewall: .. code-block:: shell ishmael ~ # sysrc pf_enable="YES" +Create the firewall rules: + /etc/pf.conf ------------ - -Create the firewall config, or merge as necessary. - .. code-block:: shell ext_if="vtnet0" - set block-policy drop + set block-policy return scrub in on $ext_if all fragment reassemble set skip on lo - nat on $ext_if from !($ext_if) -> ($ext_if:0) + nat on $ext_if from bastille0:network to any -> ($ext_if) ## rdr example - ## rdr pass inet proto tcp from any to any port {80, 443} -> 10.88.9.45 + ## rdr pass inet proto tcp from any to any port {80, 443} -> 10.17.89.45 - block in log all + block in 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 - + pass in inet proto tcp from any to any port ssh flags S/SA modulate 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) + nat on $ext_if from bastille0:network to any -> ($ext_if) ## rdr example - ## rdr pass inet proto tcp from any to any port {80, 443} -> 10.88.9.45 + ## rdr pass inet proto tcp from any to any port {80, 443} -> 10.17.89.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. +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.17.89.45`. Finally, start up the firewall: diff --git a/docs/chapters/subcommands/bootstrap.rst b/docs/chapters/subcommands/bootstrap.rst index ecd0957b..1742371e 100644 --- a/docs/chapters/subcommands/bootstrap.rst +++ b/docs/chapters/subcommands/bootstrap.rst @@ -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. diff --git a/docs/chapters/subcommands/console.rst b/docs/chapters/subcommands/console.rst index 908d4525..4a16ad4a 100644 --- a/docs/chapters/subcommands/console.rst +++ b/docs/chapters/subcommands/console.rst @@ -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. diff --git a/docs/chapters/subcommands/create.rst b/docs/chapters/subcommands/create.rst index 05a4b508..b06d1bfe 100644 --- a/docs/chapters/subcommands/create.rst +++ b/docs/chapters/subcommands/create.rst @@ -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. diff --git a/docs/chapters/subcommands/index.rst b/docs/chapters/subcommands/index.rst index 8f70966c..53f2bf59 100644 --- a/docs/chapters/subcommands/index.rst +++ b/docs/chapters/subcommands/index.rst @@ -14,6 +14,7 @@ Bastille sub-commands htop pkg restart + service start stop sysrc diff --git a/docs/chapters/subcommands/pkg.rst b/docs/chapters/subcommands/pkg.rst index cf98a816..5f11203b 100644 --- a/docs/chapters/subcommands/pkg.rst +++ b/docs/chapters/subcommands/pkg.rst @@ -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% diff --git a/docs/chapters/subcommands/service.rst b/docs/chapters/subcommands/service.rst new file mode 100644 index 00000000..b14a9b4e --- /dev/null +++ b/docs/chapters/subcommands/service.rst @@ -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' diff --git a/docs/chapters/targeting.rst b/docs/chapters/targeting.rst index b9e08897..b613533d 100644 --- a/docs/chapters/targeting.rst +++ b/docs/chapters/targeting.rst @@ -1,4 +1,3 @@ -========= Targeting ========= @@ -22,7 +21,6 @@ Examples: Jails ishmael ~ # bastille ... - +-----------+--------+------------------+-------------------------------------------------------------+ | command | target | args | description | +===========+========+==================+=============================================================+ @@ -38,13 +36,13 @@ Examples: Jails +-----------+--------+------------------+-------------------------------------------------------------+ | sysrc | web01 | nginx_enable=YES | execute `sysrc nginx_enable=YES` in web01 jail | +-----------+--------+------------------+-------------------------------------------------------------+ -| template | ALL | base | apply `base` template to ALL jails | +| template | ALL | username/base | apply `username/base` template to ALL jails | +-----------+--------+------------------+-------------------------------------------------------------+ | start | web02 | --- | start web02 jail | +-----------+--------+-----+------------+-------------------------------------------------------------+ | cp | bastion03 | /tmp/resolv.conf-cf etc/resolv.conf | copy host-path to jail-path in bastion03 | +----+------+----+---+------------------+--------------+----------------------------------------------+ -| create | folsom | 12.0-RELEASE 10.10.10.10 | create v12.0 jail named `folsom` with IP | +| create | folsom | 12.0-RELEASE 10.17.89.10 | create v12.0 jail named `folsom` with IP | +-----------+--------+------------------+--------------+----------------------------------------------+ @@ -55,15 +53,14 @@ Examples: Releases ishmael ~ # bastille ... - +-----------+--------------+--------------+-------------------------------------------------------------+ | command | target | args | description | +===========+==============+==============+=============================================================+ | bootstrap | 12.0-RELEASE | --- | bootstrap 12.0-RELEASE release | +-----------+--------------+--------------+-------------------------------------------------------------+ -| update | 11.2-RELEASE | --- | update 11.2-RELEASE release | +| update | 11.3-RELEASE | --- | update 11.2-RELEASE release | +-----------+--------------+--------------+-------------------------------------------------------------+ -| upgrade | 11.1-RELEASE | 11.2-RELEASE | update 11.2-RELEASE release | +| upgrade | 11.2-RELEASE | 11.3-RELEASE | update 11.2-RELEASE release | +-----------+--------------+--------------+-------------------------------------------------------------+ -| verify | 11.2-RELEASE | --- | update 11.2-RELEASE release | +| verify | 11.3-RELEASE | --- | update 11.2-RELEASE release | +-----------+--------------+--------------+-------------------------------------------------------------+ diff --git a/docs/chapters/template.rst b/docs/chapters/template.rst index a25e816e..65db9fbc 100644 --- a/docs/chapters/template.rst +++ b/docs/chapters/template.rst @@ -5,24 +5,24 @@ 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` +Currently supported template hooks are: `PRE`, `OVERLAY`, `PKG`, `SYSRC`, `CMD`. +Planned template hooks include: `FSTAB`, `PF`, `LOG`. 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 + mkdir -p /usr/local/bastille/templates/username/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 + echo "zsh vim-console git-lite htop" > /usr/local/bastille/templates/username/base/PKG + echo "/usr/bin/chsh -s /usr/local/bin/zsh" > /usr/local/bastille/templates/username/base/CMD + echo "etc\nrootjn usr" > /usr/local/bastille/templates/username/base/OVERLAY Template hooks are executed in specific order and require specific syntax to work as expected. This table outlines those requirements: @@ -31,25 +31,30 @@ work as expected. This table outlines those requirements: +---------+------------------+--------------------------------------+ | HOOK | format | example | +=========+==================+======================================+ -| PRE/CMD | /bin/sh command | /usr/bin/chsh -s /usr/local/bin/zsh | +| PRE | /bin/sh command | mkdir -p /usr/local/my_app/html | +---------+------------------+--------------------------------------+ -| CONFIG | path | etc root usr | +| OVERLAY | path(s) | etc root usr (one per line) | +---------+------------------+--------------------------------------+ | PKG | port/pkg name(s) | vim-console zsh git-lite tree htop | +---------+------------------+--------------------------------------+ | SYSRC | sysrc command(s) | nginx_enable=YES | +---------+------------------+--------------------------------------+ +| SERVICE | service command | 'nginx start' OR 'postfix reload' | ++---------+------------------+--------------------------------------+ +| CMD | /bin/sh command | /usr/bin/chsh -s /usr/local/bin/zsh | ++---------+------------------+--------------------------------------+ -Note: SYSRC requires NO quotes or that quotes (`"`) be escaped. ie; `\"`) +Note: SYSRC requires that NO quotes be used 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. +An example here may help. Think of `bastille/templates/username/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 @@ -57,15 +62,16 @@ 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; +use, be sure to include `usr` in the template OVERLAY definition. eg; .. code-block:: shell - echo "etc usr" > /usr/local/bastille/templates/base/CONFIG + echo "etc\nusr" > /usr/local/bastille/templates/username/base/OVERLAY 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. +include the top-level directory name. List these top-level directories one per +line. Applying Templates ------------------ @@ -78,19 +84,19 @@ directory names in the `bastille/templates` directory. .. code-block:: shell - ishmael ~ # bastille template ALL base - [cdn]: + ishmael ~ # bastille template ALL username/base + [proxy01]: 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... + Updating bastillebsd.org 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. + bastillebsd.org 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 @@ -102,23 +108,23 @@ directory names in the `bastille/templates` directory. chsh: user information updated Template Complete. - [poudriere]: + [web01]: 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... + Updating pkg.bastillebsd.org 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... + pkg.bastillebsd.org repository update completed. 499 packages processed. + Updating bastillebsd.org 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. + bastillebsd.org 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 diff --git a/docs/chapters/usage.rst b/docs/chapters/usage.rst index f7e4cf80..0d30155c 100644 --- a/docs/chapters/usage.rst +++ b/docs/chapters/usage.rst @@ -1,32 +1,37 @@ -===== Usage ===== .. code-block:: shell ishmael ~ # bastille -h + Bastille is an open-source system for automating deployment and management + of containerized applications on FreeBSD. + Usage: - bastille command [ALL|glob] [args] - + 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. + bootstrap Bootstrap a FreeBSD release for container base. + cmd Execute arbitrary command on targeted container(s). + console Console into a running container. + cp cp(1) files from host to targeted container(s). + create Create a new container. + destroy Destroy a stopped container or a FreeBSD release. 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). + list List containers (running and stopped). + pkg Manipulate binary packages within targeted container(s). See pkg(8). + restart Restart a running container. + service Manage services within targeted jail(s). + start Start a stopped container. + stop Stop a running container. + sysrc Safely edit rc files within targeted container(s). + template Apply file templates to targeted 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. + update Update container base -pX release. + upgrade Upgrade container release to X.Y-RELEASE. + verify Compare release against a "known good" index. + zfs Manage (get|set) zfs attributes on targeted jail(s). 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 f822839d..a8b3caea 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,9 +12,9 @@ copyright = '2018-2019, Christer Edwards' author = 'Christer Edwards' # The short X.Y version -version = '0.3.20181124' +version = '0.4.20191025' # The full version, including alpha/beta/rc tags -release = '0.3.20181124-beta' +release = '0.4.20191025-beta' # -- General configuration --------------------------------------------------- @@ -67,7 +67,7 @@ man_pages = [ texinfo_documents = [ (master_doc, 'Bastille', 'Bastille Documentation', - author, 'Bastille', 'Bastille is a jail automation framework that allows you to quickly and easily create and manage FreeBSD jails.', + author, 'Bastille', 'Bastille is an open-source system for automating deployment and management of containerized applications on FreeBSD.', 'Miscellaneous'), ] diff --git a/docs/index.rst b/docs/index.rst index 20b3426b..d73a94a0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,6 +17,7 @@ https://docs.bastillebsd.org. chapters/targeting chapters/subcommands/index chapters/template + chapters/jail-config copyright