Templating

bois uses the minijinja templating engine.

It is based on the syntax and behavior of the Jinja2 template engine for Python.

Documentation

Here’re some links to get started with how to write templates with minijinja.

How to use templating in bois

Templating functionality is opt-in in bois. To enable templating for a file, you must enable the template option in its File configuration block.

# bois_config
# template: true
# bois_config

Once this configuration flag is found, bois will treat the whole file as a template. If there’s a vars.yml file in the current host’s directory, it’ll be read and injected into the templating environment. Alternatively, the variables can be defined in the vars field of the host’s config file. Only one of the two may be used, defining both is an error.

For example, consider the following vars.yml file in a host’s directory.

some_secret: "lorem"
some_secret_list:
  - "ipsum"
  - "dolor"
some_secret_dict:
  lorem: sit

These variables can then be used like this:

SECRET={{ some_secret }}

{% for item in some_secret_list %}
# Useless comment: {{ item }}
{% endfor %}

{% if 'lorem' in some_secret_dict %}
OTHER_SECRET={{ some_secret_dict['lorem'] }}
{% endif %}

Which results in the following output:

SECRET=lorem

# Useless comment: ipsum
# Useless comment: dolor

OTHER_SECRET=sit

Pre-defined variables

bois pre-populates the templating environment with a few variables for your convenience:

host: String - The name of the current host.
traits: List<String> - A list with all traits that’re enabled for the host.
USER: String - The name of the user that currently executes bois (from the $USER environment variable).
USER_ID: Integer - The id of the user that currently executes bois.
GROUP_ID: Integer - The group id of the user that currently executes bois.

The following example checks whether the encrypt trait is enabled for the current host. If so, it adds the do_encryption=true flag to the configuration file.

{% if "encrypt" in traits %}
do_encryption=true
{% endif %}

Pre-defined functions

On top of minijinja’s native filters and functions, bois exposes some functions itself. Most of those functions are integrations with password managers, enabling you to inject secrets into your configuration files.

Custom delimiters

It’s possible to set custom delimiters for templating. This is sometimes useful for files that already have a Jinja2-style templating syntax themselves or for other formats that heavily use curly braces like Latex.

To change the syntax from ["{{", "}}", "{%", "%}", "{#", "#}"], the delimiters option can be used:

delimiters:
  block: ["{%", "%}"]
  variable: ["{{", "}}"]
  comment: ["{#", "#}"]

For example, the following is really handy to not interfere with a configuration format that uses # as a comment.
(The syntax highlighting is a bit off, as we’re now using a slightly different syntax. Just imagine the # prefix would be highlighted as well.)

# bois_config
# template: true
# delimiters:
#   block: ["#{%", "%}"]
#   variable: ["#{{", "}}"]
#   comment: ["#{#", "#}"]
# bois_config

...

#{# this is how a template comment now looks like #}

...

important_option=#{{ some_variable }}