Ansible Role: NUT

Installs and configures NUT (Nework UPS tools) on Debian based systems, while allowing for advanced NUT user configuration.
Also supports installing NUT from source tags to gain access to more up-to-date versions if the system's package manager does not provide them.

Key Features:

• Set nut_state to either install or remove NUT
• Allow for advanced NUT user configuration with detailed permission management
• Install NUT from a specific source tag instead of package manager in case the package manager provided version is too old
• Switch between specific versions installed from source
• Switch between installation from package manager and source (or vice versa)

Dependencies:

• ansible.utils

Install dependencies with

ansible-galaxy install -r requirements.yml

Compatibility:
This role is tested with

• Debian 11 Bullseye
• Debian 12 Bookworm
• Ubuntu 22.04 LTS Jammy Jellyfish
• Ubuntu 24.04 LTS Noble Numbat

By default, the role will check for a compatible operating system and version (any of the above). To disable that check, set the role variable nut_verify_os to false.

Caution

When using this role on an unsupported operating system and installing NUT from source, the variable __nut_apt_source must be set to whatever URL to use in sources.list for a deb-src entry.

Installing from Source

By default the role will install NUT using the package manager. If the system's package manager comes with an older NUT package, it is possible to install NUT from source. The role will automatically install all build dependencies, check out the desired source version, compile and install NUT from source.
It is also possible to use this role for updating NUT installed from source to a newer version (or downgrade to an older version). It is not a 'real' upgrade, but the old version is uninstalled before the new version is installed. The role supports switching between NUT installed by package manager and installed from source (and vice versa).

The following variables control installation from source:

Variable	Description
nut_install_from_source	Flag indicating whether to install NUT from source or not. All the variables below have no effect if not set to true. Default: false
nut_source_repository	The URL to the Git Repository to compile NUT from. Default: https://github.com/networkupstools/nut.git
nut_source_tag	The Git Tag to check out before compiling NUT. Can be a branch name as well. Default: v2.8.2
nut_drivers	A list of NUT driver names to compile NUT. For a list fo valid drivers refer to the Drivers section in the generic manual for unified NUT drivers Example: nut_drivers: - snmp-ups - netxml-ups

Role Variables

Available variables are listed below, along with default values (see defaults/main.yml).

nut_mode

nut_mode: standalone

The NUT MODE setting in nut.conf.
Allowed values in this role are standalone, netserver or netclient.

nut_managed_config

nut_managed_config: true

If this is set to false, none of the following options will have any effect, that is any and all changes under /etc/nut/ will be your responsibility. This is often desirable when you have complex configurations.

nut_users

This role allows for configuring different NUT users with specific actions and instcmds. These only have effect if nut_mode is set to either netserver or standalone.
The minimal user configuration looks like this:

nut_users:
  - name: monitor
    password: Whatever
    role: secondary

A full user configuration might look like this:

nut_users:
  - name: monitor
    password: Changeme
    role: secondary
  - name: admin
    password: uNro<FQ.eav:fyc^.,>,b29/4Dts=9
    role: primary
    actions:
      - fsd
      - set
    instcmds:
      - all

Explanation for all possible attributes:

Attribute	Description
name	Name for the NUT user Mandatory
password	The user's password Mandatory
role	Either the user type filed of the MONITOR directive in upsmon.conf and/or the upsmon directive in upsd.users. Allowed vlaues are primary and secondary Mandatory
actions	Used to set allowed actions for the user in upsd.users Only effective effect if nut_mode is either netserver or standalone Optional
instcmds	Used to set allowed instant commands for the user in upsd.users Only effective effect if nut_mode is either netserver or standalone Optional

nut_ups

The nut_ups variable is a list of UPS definitions the NUT installation knows of. Depening on nut_mode, the minimal set of attributes differs.

For nut_mode = netclient, the minimal UPS configuration looks like this:

nut_ups:
  - name: UPS
    monitoruser: monitor

For nut_mode = netserver or nut_mode = standalone, the minimal UPS configuration looks like this:

nut_ups:
  - name: UPS
    monitoruser: monitor
    driver: usbhid-ups
    device: auto

The full configuration for nut_ups with all possible attributes looks like this:

nut_ups:
  - name: UPS
    monitoruser: monitor
    driver: usbhid-ups
    device: auto
    description: Some descriptive information
    monitorhost: localhost
    powervalue: 1
    extra: |
      maxretry = 10
      retrydelay = 1

Explanation for all possible attributes:

Attribute	Description
name	An arbitrary string that must identify univocally the UPS Mandatory
monitoruser	The NUT user to use for monitoring this UPS. Must reference an existing user defined in nut_users. Mandatory
driver	Depends on your hardware and must be one of the available NUT driver. Be sure the NUT version installed on your server has that specific driver available Mandatory for nut_mode set to netserver or standalone
device	Port where the UPS is listening (typically an USB port or a serial device). It is translated to the port directive in ups.conf Mandatory for nut_mode set to netserver or standalone
description	An arbitrary string used for debugging and reporting purposes Optional
monitorhost	The host that UPS can be monitored with. Is used as the host in the MONITOR directive in upsmon.conf. Optional, default: localhost
powervalue	The number of power supplies that the UPS feeds on this system. Is used as powervalue in the MONITOR directive in upsmon.conf. Optional, default: 1
powervalue	extra | Optional multiline text to be inserted verbatim in the global section of the relevant configuration file Optional

Misc Variables

All these variables are optional:

Variable	Description
nut_enable_service	Flag indicating whether to start the services appropriate for the installed nut_packages after configuration. Default: true
nut_upssched_cmdscript_content	Contents of a custom upssched-cmd script.
nut_upssched_cmdscript	Path on the Ansible host to a custom upssched-cmd script. Sets the CMDSCRIPT directive in upssched.conf. If nut_upssched_cmdscript_content is not empty, the contents of that variable will be stored under this path.
nut_upssched_pipefn	Sets the PIPEFN directive in upssched.conf. Default: /run/nut/upssched/upssched.pipe
nut_upssched_lockfn	Sets the LOCKFN directive in upssched.conf. Default: /run/nut/upssched/upssched.lock
nut_upssched_at_commands	Define AT directives for upssched.conf. Example: nut_upssched_at_commands: - notifytype: ONBATT upsname: * command: START-TIMER commbad 30
nut_upsmon_notify	Define custom NOTIFYMSG and NOTIFYFLAG directives for upsmon.conf. Example: nut_upsmon_notify: - name: ONLINE msg: UPS %s on line power flag: SYSLOG+WALL+EXEC - name: ONBATT msg: UPS %s on battery flag: SYSLOG+WALL+EXEC
nut_upsmon_notifycmd_content	Contents of a custom upsmon notification script.
nut_upsmon_notifycmd	Path to a custom notification script. Sets the NOTIFYCMD directive in upsmon.conf. If nut_upsmon_notifycmd_content is not empty, the contents of that variable will be stored under that path.
nut_ups_extra	Additional content to append to the ups.conf file
nut_upsd_extra	Additional content to append to the upsd.conf file
nut_upsmon_extra	Additional content to append to the upsmon.conf file
nut_verify_os	Flag indicating whether to check for a known compatible operating system and version. Set to false to use the role on untested operating systems. Default: true

Example Playbook

- hosts: all
  gather_facts: true
  roles:
  - role: salvoxia.nut
    nut_users:
      - name: monitor
        password: changeme
        role: secondary
    nut_ups:
      - name: riello
        monitoruser: monitor
        driver: riello_usb
        device: /dev/ups
        description: iPlug 800

For more examples, please see molecule/*/converge.yml and molecule/*/prepare.yml.

Cheat Sheet

Run a Docker container with systemd:

sudo docker run --tmpfs /tmp --tmpfs /run -v /sys/fs/cgroup:/sys/fs/cgroup:rw --cgroupns=host --privileged --name sysd --rm geerlingguy/docker-debian11-ansible

License

MIT

Author Information

This role was created in 2016 by Nicola Fontana ([email protected]).
This fork is modified and maintained by Salvoxia ([email protected]).