148 lines
4.3 KiB
ReStructuredText
148 lines
4.3 KiB
ReStructuredText
===============
|
||
Using Templates
|
||
===============
|
||
|
||
-------
|
||
General
|
||
-------
|
||
|
||
For config file generation, we provide a backend service which can bind
|
||
config.xml data to templates written in Jinja2
|
||
(http://jinja.pocoo.org/docs/dev/).
|
||
|
||
All available templates should be installed at the following location on
|
||
the OPNsense system:
|
||
|
||
#. /usr/local/opnsense/service/templates/
|
||
|
||
|
||
-----------------
|
||
Naming convention
|
||
-----------------
|
||
|
||
All templates should be put into a directory structure containing the
|
||
vendor and package/application name, our sample application is placed
|
||
inside the directory:
|
||
|
||
/usr/local/opnsense/service/templates/*OPNsense/Sample*
|
||
|
||
Template package content
|
||
|
||
Every template directory should contain at least 2 files:
|
||
|
||
#. a content descriptor, containing the actual targets, named +TARGETS
|
||
#. one or more template(s)
|
||
|
||
|
||
-------
|
||
Targets
|
||
-------
|
||
|
||
The +TARGETS file contains the source template name inside the template
|
||
directory and the (dynamic) target filename divided by a colon (:)
|
||
multiple lines may be inserted per file.
|
||
|
||
For example :
|
||
|
||
::
|
||
|
||
example_simple_page.txt:/tmp/template_sample/simple_page.txt
|
||
|
||
Will create a file /tmp/template\_sample/simple\_page.txt using the
|
||
template example\_simple\_page.txt.
|
||
|
||
.. Note::
|
||
|
||
Optionally you can specify which file or files to remove on call of "template cleanup", which can be specified by
|
||
using an extra tag next to the target, such as:
|
||
:code:`example_simple_page.txt:/tmp/template_sample/simple_page.txt:/tmp/template_sample/simple_page.*`
|
||
|
||
By default all targets will be removed when calling cleanup.
|
||
|
||
|
||
|
||
If you want to use information from within the config.xml file as output
|
||
filename, you can use tags to address the content, like [version] to
|
||
input the tag version from the xml file. When generating multiple files
|
||
from 1 template, you can use one wildcard (%) to address a section of
|
||
the config file, for example [interfaces.%.if] loops over the interfaces
|
||
and outputs the value of **if**.
|
||
|
||
-----------------
|
||
Target overwrites
|
||
-----------------
|
||
|
||
Every template package can specify overwrites, which can be used by vendors who implement and maintain their own templates
|
||
for features in OPNsense.
|
||
|
||
Simply add files using the target definition in the **+TARGETS.D** directory of the templates folder using as extension **.TARGET**.
|
||
|
||
For example an overwrite for OPNsense/Sample can use the following name and location
|
||
:code:`/usr/local/opnsense/service/templates/OPNsense/Sample/+TARGETS.D/custom.TARGET`
|
||
|
||
.. Note::
|
||
Be vey careful using this feature, you need to maintain these templates yourself and features may break after upgrades
|
||
of OPNsense.
|
||
|
||
---------
|
||
Templates
|
||
---------
|
||
|
||
For more information of the template language itself, please look at
|
||
http://jinja.pocoo.org/docs/dev/ and the examples installed in
|
||
/usr/local/opnsense/service/templates/OPNsense/Sample.
|
||
|
||
There's one special case when using the template engine, every wildcard
|
||
used for the output file generation is also provided to the template, so
|
||
you are able to determine which filter let to this output.
|
||
|
||
Those filters are stored in the variable TARGET\_FILTERS.
|
||
|
||
.. code-block:: jinja
|
||
|
||
{% if TARGET_FILTERS['interfaces.wan'] %}
|
||
{% endif %}
|
||
|
||
----------
|
||
Test usage
|
||
----------
|
||
|
||
The templates can be rendered via the backend service (configd), to test
|
||
this functionality on a running OPNsense system, use:
|
||
|
||
|
||
::
|
||
|
||
# generate template package
|
||
configctl template reload OPNsense/Sample
|
||
# cleanup files
|
||
configctl template cleanup OPNsense/Sample
|
||
|
||
|
|
||
|
||
-----------------------------
|
||
Python template usage example
|
||
-----------------------------
|
||
|
||
The template system itself is a separate module which is used by
|
||
configd, to use (or test) the system without the daemon, use:
|
||
|
||
.. code-block:: python
|
||
|
||
# import template system and config.xml handling
|
||
from modules import template
|
||
from modules import config
|
||
|
||
# construct a new template object, set root to /tmp/
|
||
tmpl = template.Template(target_root_directory="/tmp/")
|
||
# open the config.xml and bind to template object
|
||
conf = config.Config('/config.xml')
|
||
tmpl.setConfig(conf.get())
|
||
|
||
# generate output for OPNsense/Sample
|
||
generated_filenames = tmpl.generate('OPNsense/Sample')
|
||
|
||
# print results
|
||
for filename in generated_filenames:
|
||
print ('.. generated : %s'%filename)
|