diff --git a/docs/chapters/centralized-assets.rst b/docs/chapters/centralized-assets.rst new file mode 100644 index 00000000..40041ef0 --- /dev/null +++ b/docs/chapters/centralized-assets.rst @@ -0,0 +1,80 @@ +Centralized Assets +================== + +Sometimes it is preferable to share applications, libraries, packages or even directories +and files across multiple jails. + +Or perhaps we just want to avoid all the time it takes to create a jail, and manully configure +it with the packages we normally use. + +Bastille offers a number of ways to do the above. + +Templates +--------- + +A template is a predefined file containing instructions to execute on a targeted jail. This +is one of the easiest ways to create a repeatable environment for your Bastille jails. Simply +create your template, the execute it on as many jails as you prefer. + +.. code-block:: shell + + ishmael ~ # bastille template "jail1 jail2" project/template + +See the chapter on templates for details on how to create your own templates. + +Mounting +-------- + +On of the fastest ways to share directories and files across multiple jails is with +the ``bastille mount`` command. + +The following command will mount ``/my/host/directory`` into ``jail1`` and ``jail2`` +at ``/my/jail/directory`` with read and write access. To mount with read only access, +simply use ``ro`` instead of ``rw`` as the option. + +.. code-block:: shell + + ishmael ~ # bastille mount "jail1 jail2" /my/host/directory /my/jail/directory nullfs rw 0 0 + +Cloning +------- + +Bastille allows you to create a full duplicate of your jail using ``bastille clone``. To clone +your jail to a duplicate jail, use the following command. + +.. code-block:: shell + + ishmael ~ # bastille clone myjail mynewjail 10.0.0.3 + +This will create an exact duplicate of ``myjail`` at ``mynewjail``. + +Custom Releases +--------------- + +Bastille allows creating custom releases from jails, then using those releases to create +more jails. + +To start, we must first create our jail. Make sure it is a thick jail, as this process will +not work with any other jail types. + +.. code-block:: shell + + ishmael ~ # bastille create -T myjail 14.2-RELEASE 10.0.0.1 + +Once the jail is up and running, configure it to your liking, then run the followin commmand +to create a custom release based on your jail. + +.. code-block:: shell + + ishmael ~ # bastille convert myjail myrelease + +Once this process completes, you will be able to run the following command to create a jail +base off your newly created release. + +Please note that using this approach is experimental. It will be up to the end user to keep +track of which official FreeBSD release their custom release is based on. The ``osrelease`` +config variable will be set to your custom release name inside the ``jail.conf`` file. + +.. code-block:: shell + + ishmael ~ # bastille create -T --no-validate myjail myrelease 10.0.0.2 diff --git a/docs/chapters/subcommands/convert.rst b/docs/chapters/subcommands/convert.rst index 8a4d6638..c20c4bae 100644 --- a/docs/chapters/subcommands/convert.rst +++ b/docs/chapters/subcommands/convert.rst @@ -1,15 +1,27 @@ convert ======= -Convert a thin jail to a thick jail. +Convert allows converting a thin jail to a thick jail. +It also allows converting a thick jail to a customized release. + +Converting a thin jail to a thick jail requires only the target jail. .. code-block:: shell ishmael ~ # bastille convert azkaban - [azkaban]: - ... -Syntax requires only the target jail to convert. +Converting a thick jail to a custom release requires a target jail as +well as custom release name. + +.. code-block:: shell + + ishmael ~ # bastille convert azkaban myrelease + +This release can then be used to create a thick jail using the ``--no-validate`` flag. + +.. code-block:: shell + + ishmael ~ # bastille create --no-validate customjail myrelease 10.0.0.1 .. code-block:: shell diff --git a/docs/chapters/template.rst b/docs/chapters/template.rst index 73770bb7..cd8bdf33 100644 --- a/docs/chapters/template.rst +++ b/docs/chapters/template.rst @@ -112,19 +112,29 @@ escape it. Escaping it will cause errors. Bootstrapping Templates ----------------------- -The templates for Bastille are all in github and mirror the directory -structure of the ports tree. So, nginx is in the www directory in the -templates just like it is in the FreeBSD ports tree. To bootstrap the -entire set of predefined templates run the following command: +The official templates for Bastille are all on Gthub, and mirror the directory +structure of the ports tree. So, ``nginx`` is in the ``www`` directory in the +templates, just like it is in the FreeBSD ports tree. To bootstrap the +entire set of official predefined templates run the following command: .. code-block:: shell bastille bootstrap https://github.com/bastillebsd/templates -This will install into the /usr/local/bastille/templates directory all the -templates. Now you can use bastille template command to apply the templates. +This will install all official templates into the templates directory at +``/usr/local/bastille/templates``. You can then use the ``bastille template`` +command to apply any of the templates. +.. code-block:: shell + bastille template TARGET www/nginx + +Creating Templates +------------------ + +Templates can be created and placed inside the templates directory in the +``project/template`` format. Alternatively you can run the ``bastille template`` +command from a relative path, making sure it is still in the above format. Template Examples ----------------- diff --git a/docs/index.rst b/docs/index.rst index 96367100..f7db9ff6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,6 +19,7 @@ https://docs.bastillebsd.org. chapters/networking chapters/usage chapters/upgrading + chapters/centralized-assets chapters/subcommands/index chapters/template chapters/jail-config