How to create and use templates
===============================

Templates preserve a configured jail for deployment through ZFS clones.

A stopped basejail can be converted to a template and back again using the
``istemplate`` property. Templates are not started automatically. Converting a
template back to a jail preserves its stored ``host_hostuuid``, tag, snapshots,
and child datasets; it does not give the jail a new identity.

Template tags become ZFS dataset names. Start the tag with a letter, digit or
underscore; use only letters, digits, underscores, periods, colons and hyphens.
A generated timestamp tag contains ``@`` and must first be changed explicitly,
for example with ``iocell set tag=mytemplate UUID``. An unsafe tag is rejected
before changing datasets, metadata, aliases or delegated state. Tags are not
silently rewritten.

**Here is how to create a template with iocell:**

1. Create a new jail ``iocell create tag=mytemplate``
2. Configure the jail's networking
3. Install any package you like and customize jail
4. Once finished with customization stop the jail ``iocell stop UUID | TAG``
5. A good idea is set some notes ``iocell set notes="customized PHP,nginx jail" UUID | TAG``
6. Turn the template property on ``iocell set istemplate=yes UUID|TAG``
7. List your template with ``iocell list -t``

**Here is how to use the created template:**

To create a new jail from this template simply clone it!

1. ``iocell clone TAG-of-mytemplate tag=mynewjail``
2. List new jail ``iocell list``
3. Start jail ``iocell start UUID | TAG``

Done!

**To customize or patch the template:**

Stop it if it was started for maintenance, convert it back with
``iocell set istemplate=no TAG-of-template``, then start the jail as usual.
After maintenance, stop it and convert it to a template again.

Conversion back is refused if the stored UUID is invalid, the template is
running, or its root/data datasets have clones outside the template tree. A failed ZFS rename (for
example, because the original UUID destination is occupied) is reported as an
error without changing the template flags or tag link. The previous ``jailed``
state of the template's ``data`` child dataset is restored if the rename fails;
any failure to restore it is also reported. Forward conversion likewise
renames before changing metadata or aliases, and preserves both ``on`` and
``off`` delegated states. A failed config lookup cannot edit the host's
``/config``.

``iocell clean -t`` includes clones inside the templates tree, but refuses
clones outside it. ZFS dependency protection remains enabled if an outside clone
appears after the preflight check. ``iocell clean -f -t`` prints ZFS's
complete destruction preview for the templates tree and its dependent trees
before destroying them.

A failed metadata or alias update after a successful conversion rename returns
an error; the dataset may already have moved. The final template flag is not
written after that failure.