Default variable details
========================

Some of the ``debops.machine`` default variables have more extensive
configuration than simple strings or lists, here you can find documentation and
examples for them.

.. contents::
   :local:
   :depth: 1


.. _machine__ref_motd_scripts:

machine__motd_scripts
---------------------

This variable is a list which can be used to manage scripts in the
:file:`/etc/update-motd.d/` directory, used to generate the dynamic Message Of
The Day.

Each list entry is a YAML dictionary with specific parameters:

``name``
  Required. Name of a given entry, used as a handle to merge multiple entries
  together. It's also used in an autogenerated filename of the script.

``weight``
  Optional. Modify the base "weight" of a given script to reorder its output in
  the resulting dynamic MOTD. The base weight used by the role is ``0``, you
  can use positive or negative numbers to reorder the scripts. The filename
  format uses 2 digits to define the weight, therefore you should use small
  range of weights, otherwise weird filenames resulting in unwanted order might
  be generated.

``filename``
  Optional. Define a static filename of the script. This filename won't be
  affected by the ``name`` and ``weight`` parameters. It's usually used for
  scripts provided by Debian packages to aid in :command:`dpkg`
  diversion/reversion.

``src``
  Optional, conflicts with ``content``. Path to a script which should be
  installed in the :file:`/etc/update-motd.d/` directory with a given name. By
  default the path is relative to the :file:`files/` directory of the
  ``debops.machine`` Ansible role.

  The script output will be added to the dynamic MOTD. Remember that the script
  is executed with ``root`` privileges!

``content``
  Optional, conflicts with ``src``. YAML text block which contains a script to
  be installed in the :file:`/etc/update-motd.d/` directory with a given name.
  The script can contain Jinja templating which will be evaluated at Ansible
  execution time.

  The script output will be added to the dynamic MOTD. Remember that the script
  is executed with ``root`` privileges!

``divert``
  Optional, boolean. If ``True``, the script managed by this entry will be
  automatically diverted/reverted as necessary. This is useful to move the
  files included in the APT packages aside, so that the package manager can
  still update the packages without issues.

  The diverted scripts will have a ``.disabled`` extension and their output
  will not be included in the dynamic MOTD.

``state``
  Optional. Define the state of a particular script. If multiple list entries
  define a script state, the last one wins. Recognized states:

  - not specified or ``present``: the script will be installed in the
    :file:`/etc/update-motd.d/` directory. If an entry has a ``divert: True``
    parameter, existing script will be diverted.

  - ``absent``: the specified script will be removed. Diverted scripts will be
    reverted to their previous location, but otherwise will not be removed.

  - ``init``: the configuration of a given entry will be "initiated", but
    otherwise the entry will not change anything on the host. This can be used
    to prepare an entry and activate it later conditionally.

  - ``ignore``: the given configuration entry will be ignored by the role. This
    can be used to conditionally activate or skip entries.

  - ``divert``: if a given entry has the ``divert: True`` parameter, the
    specified script will be diverted and effectively disabled. The role will
    not generate a replacement script. This state can be used to disable
    scripts installed by APT packages without providing replacements.

  - ``revert``: if a given entry has the ``divert: True`` parameter, the
    specified script will be reverted to its original state.

Examples
~~~~~~~~

Include a random fortune in the dynamic MOTD using the :command:`fortune`
output, if it's installed:

.. code-block:: yaml

   machine__motd_scripts:

     - name: 'fortune'
       weight: 95
       content: |
         #!/bin/sh
         . /etc/default/locale
         export LANG
         export PATH="/usr/local/games:/usr/games:$PATH"
         if [ -x /usr/games/fortune ] ; then
             /usr/games/fortune -s
         fi
       state: 'present'

Include a random fortune in the dynamic MOTD using a script provided by the
role:

.. code-block:: yaml

   machine__motd_scripts:

     - name: 'fortune'
       weight: 95
       src: 'etc/update-motd.d/fortune'
