diff --git a/docs/chapters/configuration.rst b/docs/chapters/configuration.rst index 117fb270..24bec646 100644 --- a/docs/chapters/configuration.rst +++ b/docs/chapters/configuration.rst @@ -4,9 +4,10 @@ Configuration Bastille is configured using a default config file located at ``/usr/local/etc/bastille/bastille.conf``. When first installing bastille, you should run ``bastille setup``. This will ask if you want to copy the sample -config file to the above location. The defaults are sensible for UFS, but if you -want to use ZFS, you will have to change a few options. See the chapter on ZFS -Support. +config file to the above location. The defaults are sensible for UFS, but +if you use ZFS, ``bastille setup`` will configure it for you. If you have +multiple zpools, Bastille will ask which one you want to use. See also +:doc:`ZFS Support `. This is the default `bastille.conf` file. @@ -98,28 +99,12 @@ This is the default `bastille.conf` file. bastille_template_clone="default/clone" ## default: "default/clone" bastille_template_thin="default/thin" ## default: "default/thin" bastille_template_vnet="default/vnet" ## default: "default/vnet" - -Notes ------ - -The options here are fairly self-explanitory, but there are some things to note. - -* If you use ZFS, DO NOT create the bastille dataset. You must only create the - parent. Bastille must be allowed to create the ``bastille`` child dataset, or - you will have issues. So, if you want bastille to live at - ``zroot/data/bastille`` you should set ``bastille_zfs_zpool`` to ``zroot`` and - ``bastille_zfs_prefix`` to ``data/bastille`` but you should only create - ``zroot/data`` before running bastille for the first time. - -* Bastille will mount the dataset it creates at ``bastille_prefix`` which - defaults to ``/usr/local/bastille``. So if you want to navigate to your jails, - you will use the ``bastille_prefix`` as the location because this is where the - will be mounted. + bastille_template_vlan="default/vlan" ## default: "default/vlan" Custom Configuration -------------------- -Bastille now supports using a custom config in addition to the default one. This +Bastille supports using a custom config in addition to the default one. This is nice if you have multiple users, or want to store different jails at different locations based on your needs. diff --git a/docs/chapters/getting-started.rst b/docs/chapters/getting-started.rst index beb5a278..d80cbe2c 100644 --- a/docs/chapters/getting-started.rst +++ b/docs/chapters/getting-started.rst @@ -1,84 +1,84 @@ Getting Started =============== -This guide is meant to get you up and running with bastille, and will show you -a number of different options to create and manage your jails. +Bastille has many different options when it comes to creating +and managing jails. This guide is meant to show some basic +setup and configuration options. Setup ----- -The first command a new user should run is the ``bastille setup`` command. This -will attempt to configure the networking, storage, and firewall on your system +The first command a new user should run is ``bastille setup``. This +will configure the networking, storage, and firewall on your system for use with Bastille. -By default the setup command will configure a loopback interface, storage (ZFS if -enabled, otherwise UFS) and the pf firewall if you run it as below without any -options. +By default the ``bastille setup`` will configure a loopback interface, storage (ZFS if +enabled, otherwise UFS) and the ``pf`` firewall. -Alternatively, you can run the ``setup`` command with any of the supported +Alternatively, you can run ``bastille setup OPTION`` command with any of the supported options to configure the selected option by itself. -To see a list of available options and switches, see the ``setup`` subcommand. +To see a list of available options, see the ``setup`` subcommand. .. code-block:: shell ishmael ~ # bastille setup +Now we are ready to bootstrap a release and start creating jails. + Bootstrapping a Release ----------------------- -Then we need to bootstrap a release for bastille to use. We will use -14.2-RELEASE. +To bootstrap a release, run ``bastille bootstrap RELEASE``. .. code-block:: shell ishmael ~ # bastille bootstrap 14.2-RELEASE +This will fetch the necessary components of the specified release, and +enable us to create jails from the downloaded release. + Creating a Jail --------------- -Next we can create our first jail. Bastille can create a few different types of -jails. +There are a few different types of jails we can create, described below. * Thin jails are the default, and are called thin because they use symlinks to the bootstrapped release. They are lightweight and are created quickly. -* Thick jails used the entire release, which is copied into the jail. The jail +* Thick jails use the entire release, which is copied into the jail. The jail then acts like a full BSD install, completely independent of the release. - Created with ``bastille create -T``. + Created with the ``--thick|-T`` option. * Clone jails are essentially clones of the bootstrapped release. Changes to the - release will affect the clone jail. Created with ``bastille create -C``. + release will affect the clone jail. Created with the ``--clone|-C`` option. * Empty jails are just that, empty. These should be used only if you know what - you are doing. Created with ``bastille create -E``. + you are doing. Created with the ``--empty|-E`` option. -* Linux jails are jails that run linux. Created with ``bastille create -L``. +* Linux jails are jails that run linux. Created with the ``--linux|-L`` option. + See :doc:`Linux Jails `. -Only clone, thin, and thick jails can be created with ``-V`` ``-B`` and ``-M``. - -We will focus on thin jails for the guide. +We will focus on thin jails for this guide. Classic/Standard Jail ^^^^^^^^^^^^^^^^^^^^^ .. code-block:: shell - ishmael ~ # bastille create nextcloud 14.2-RELEASE 10.1.1.4/24 vtnet0 + ishmael ~ # bastille create nextcloud 14.2-RELEASE 10.1.1.4/24 -This will create a classic jail and add the IP as an alias to the vtnet0 -interface. This jail will use NAT for its outbound traffic. If you want to run -a webserver of something similar inside it, you will have to redirect traffic -from the host using ``bastille rdr`` +This will create a classic jail, which uses the loopback interface +(created with ``bastille setup``) for outbound connections. -It the IP is reachable within your local subnet, however, then it is not -necessary to redirect the traffic. It will pass in and out normally. +To be able to reach a service inside the jail, use ``bastille rdr``. .. code-block:: shell ishmael ~ # bastille rdr nextcloud tcp 80 80 This will forward traffic from port 80 on the host to port 80 inside the jail. +See also :doc:`rdr `. VNET Jail ^^^^^^^^^ @@ -99,20 +99,3 @@ or The IP used for VNET jails should be an IP reachable inside your local network. You can also specify 0.0.0.0 or DHCP to use DHCP. - -Linux Jail -^^^^^^^^^^ - -Linux jails are still considered experimental, but they seem to work. First we -must bootstrap a linux distro (Linux distros are bootstrapped with the Debian -tool debootstrap). - -.. code-block:: shell - - ishmael ~ # bastille bootstrap bionic - -Then we can create our linux jail using this release. This will take a while... - -.. code-block:: shell - - ishmael ~ # bastille create -L linux_jail bionic 10.1.1.7/24 vtnet0 diff --git a/docs/chapters/installation.rst b/docs/chapters/installation.rst index 69a96891..24a5e703 100644 --- a/docs/chapters/installation.rst +++ b/docs/chapters/installation.rst @@ -1,5 +1,6 @@ Installation ============ + Bastille is available in the official FreeBSD ports tree at ``sysutils/bastille``. Binary packages are available in quarterly and latest repositories. @@ -18,9 +19,6 @@ pkg .. code-block:: shell pkg install bastille - bastille setup - -To install from source (don't worry, no compiling): ports ----- @@ -28,7 +26,6 @@ ports .. code-block:: shell make -C /usr/ports/sysutils/bastille install clean - bastille setup git --- @@ -38,9 +35,8 @@ git git clone https://github.com/BastilleBSD/bastille.git cd bastille make install - bastille setup -This method will install the latest files from GitHub directly onto your +The ``git`` method will install the latest files from GitHub directly onto your system. It is verbose about the files it installs (for later removal), and also has a ``make uninstall`` target. You may need to manually copy the sample config into place before Bastille will run. (ie; diff --git a/docs/chapters/jail-startup-configuration.rst b/docs/chapters/jail-startup-configuration.rst index 42cf2a04..92f58339 100644 --- a/docs/chapters/jail-startup-configuration.rst +++ b/docs/chapters/jail-startup-configuration.rst @@ -11,7 +11,7 @@ the priority option. Jails will start in order starting at the lowest value, and will stop in order starting at the highest value. So, jails with a priority value of 1 will start first, and stop last. -See the chapter on targeting for more info. +See :doc:`Targeting `for more info. Boot ---- diff --git a/docs/chapters/linux-jails.rst b/docs/chapters/linux-jails.rst new file mode 100644 index 00000000..c43b5386 --- /dev/null +++ b/docs/chapters/linux-jails.rst @@ -0,0 +1,2 @@ +Linux Jails +=========== \ No newline at end of file diff --git a/docs/chapters/targeting.rst b/docs/chapters/targeting.rst index 2d5bfe1b..5efa7ab7 100644 --- a/docs/chapters/targeting.rst +++ b/docs/chapters/targeting.rst @@ -2,21 +2,20 @@ Targeting ========= Bastille uses a ``subcommand TARGET ARGS`` syntax, meaning that each command -requires a target. Targets are usually containers, but can also be releases. +requires a target. Targets are usually jails, but can also be releases. -Targeting a container is done by providing the exact jail name, the JID of the -jail, a tag, or by typing the starting few characters of a jail. If more than one -matching jail is found, you will see an error saying so. +Targeting a jail is done by providing the exact jail name, the JID of the +jail, a tag, or by typing the starting few characters of a jail. -If you use a tag as the TARGET, Bastille will target any and all jail(s) that have -the tag assigned. If you have a jail with the same name as the tag you are trying to +If you use a tag as the TARGET, Bastille will target any and all jails that have +that tag assigned. If you have a jail with the same name as the tag you are trying to target, Bastille will target the jail, and not the tag. Targeting a release is done by providing the exact release name. (Note: do not include the ``-pX`` point-release version.) -Bastille includes a pre-defined keyword [ALL|all] to target all running -containers. It is also possible to target multiple jails by grouping them in +Bastille includes a pre-defined keyword of [ALL|all] to target all running +jails. It is also possible to target multiple jails by grouping them in quotes, as seen below. .. code-block:: shell @@ -27,7 +26,7 @@ Priority -------- The priority value determines in what order commands are executed if multiple -jails are targetted, including the ALL target. +jails are targetted, including the [ALL|all] target. It also controls in what order jails are started and stopped on system startup and shutdown. This requires Bastille to be enabled with ``sysrc bastille_enable=YES``. @@ -43,8 +42,8 @@ This value can be changed using ``bastille config TARGET set priority VALUE``. This value will be shown using ``bastille list all``. -Examples: Containers --------------------- +Examples: Jails +--------------- .. code-block:: shell @@ -53,25 +52,25 @@ Examples: Containers +-----------+--------+------------------+-------------------------------------------------------------+ | command | target | args | description | +===========+========+==================+=============================================================+ -| cmd | ALL | 'sockstat -4' | execute `sockstat -4` in ALL containers (ip4 sockets) | +| cmd | ALL | 'sockstat -4' | execute `sockstat -4` in ALL jails (ip4 sockets) | +-----------+--------+-----+------------+-------------------------------------------------------------+ | console | mariadb02 | --- | console (shell) access to mariadb02 | +----+------+--------+-----+------------+-------------------------------------------------------------+ -| pkg | web01 | 'install nginx' | install nginx package in web01 container | +| pkg | web01 | 'install nginx' | install nginx package in web01 jail | +-----------+--------+------------------+-------------------------------------------------------------+ -| pkg | ALL | upgrade | upgrade packages in ALL containers | +| pkg | ALL | upgrade | upgrade packages in ALL jails | +-----------+--------+------------------+-------------------------------------------------------------+ -| pkg | ALL | audit | (CVE) audit packages in ALL containers | +| pkg | ALL | audit | (CVE) audit packages in ALL jails | +-----------+--------+------------------+-------------------------------------------------------------+ -| sysrc | web01 | nginx_enable=YES | execute `sysrc nginx_enable=YES` in web01 container | +| sysrc | web01 | nginx_enable=YES | execute `sysrc nginx_enable=YES` in web01 jail | +-----------+--------+------------------+-------------------------------------------------------------+ -| template | ALL | username/base | apply `username/base` template to ALL containers | +| template | ALL | username/base | apply `username/base` template to ALL jails | +-----------+--------+------------------+-------------------------------------------------------------+ -| start | web02 | --- | start web02 container | +| start | web02 | --- | start web02 jail | +----+------+----+---+------------------+--------------+----------------------------------------------+ -| cp | bastion03 | /tmp/resolv.conf-cf etc/resolv.conf | copy host-path to container-path in bastion03| +| cp | bastion03 | /tmp/resolv.conf-cf etc/resolv.conf | copy host-path to jail-path in bastion03 | +----+------+----+---+---------------------------------+----------------------------------------------+ -| create | folsom | 13.2-RELEASE 10.17.89.10 | create 13.2 container named `folsom` with IP | +| create | folsom | 13.2-RELEASE 10.17.89.10 | create 13.2 jail named `folsom` with IP | +-----------+--------+---------------------------------+----------------------------------------------+ diff --git a/docs/index.rst b/docs/index.rst index 94259782..ac9857bb 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,23 +11,24 @@ https://docs.bastillebsd.org. :maxdepth: 2 :caption: Contents: - chapters/installation - chapters/gettin-gstarted - chapters/configuration - chapters/targeting - chapters/jail-startup-configuration - chapters/networking - chapters/usage chapters/comparing - chapters/upgrading - chapters/centralized-assets - chapters/subcommands/index - chapters/template + chapters/installation + chapters/getting-started + chapters/configuration chapters/jail-config - chapters/zfs-support + chapters/jail-startup-configuration + chapters/targeting + chapters/subcommands/index + chapters/usage + chapters/networking chapters/gcp + chapters/upgrading chapters/migration + chapters/centralized-assets + chapters/template + chapters/linux-jails chapters/pkgbase + chapters/zfs-support copyright