DEBOPS.MACHINE(5)

NAME
debops.machine - Manage local machine information and MOTD

SYNOPSIS

debops run service/machine [--limit group,host,...] [--diff] [--check] [--tags tag1,tag2,...] [--skip-tags tag1,tag2,...] [<ansible-playbook options>] ...

DESCRIPTION

The debops.machine Ansible role manages basic information about a given host located in the /etc/machine-info configuration file, as well as static and dynamic Message Of The Day (MOTD) shown after login, and the contents of the /etc/issue file displayed on the system console <https://en.wikipedia.org/wiki/System_console>.

GETTING STARTED

  Default configuration

By default, the role will remove an existing /etc/motd file to move the original Debian/Ubuntu MOTD out of the way. This can be controlled using the machine__etc_motd_state variable. The original version of the file is maintained by the base-files package and can be found in the /usr/share/base-files/motd file.

You can use the /etc/motd.tail file to include manual text in the dynamic MOTD. Alternatively, you can put a custom script in the /etc/update-motd.d/ directory.

You can use the debops.resources Ansible role to install multiple custom scripts in the /etc/update-motd.d/ directory at once by copying them from the resources/ subdirectory on the Ansible Controller.

  Ansible local facts

The debops.machine role provides a set of Ansible local facts available in the ansible_local.machine.* hierarchy. They will contain contents of the /etc/machine-info variables, so that they could be used by other Ansible roles when configured.

  Example inventory

The debops.machine role is included by default in the common.yml DebOps playbook; you don't need to add hosts to any Ansible groups to enable it.

  Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.machine role:

---
- name: Manage local machine information
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_all_hosts', 'debops_service_machine' ]
  become: True
  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'
  roles:
    - role: machine
      tags: [ 'role::machine', 'skip::machine' ]

  Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::machine
    Main role tag, should be used in the playbook to execute all of the role tasks as well as role dependencies.

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.

  machine__motd_scripts

This variable is a list which can be used to manage scripts in the /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 dpkg diversion/reversion.

src Optional, conflicts with content. Path to a script which should be installed in the /etc/update-motd.d/ directory with a given name. By default the path is relative to the 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 /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 /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 fortune output, if it's installed:

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:

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

NOTE: Name of this role was based on the /etc/machine-info configuration file, and is loosely connected to the concept of the "Machine" defined in the Site Reliability Engineering <https://landing.google.com/sre/book/chapters/production-environment.html> book.

AUTHOR
Maciej Delmanowski

COPYRIGHT
2014-2024, Maciej Delmanowski, Nick Janetakis, Robin Schneider and others