Merge pull request #960 from BastilleBSD/doc-fixes-more

docs: Clarify convert

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

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
 

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
 -----------------

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