Merge pull request #3 from Salvoxia/feat/installFromSource

Feature: Install NUT from source

.ansible-lint

@@ -3,3 +3,4 @@ skip_list:
   - 'risky-shell-pipe'
   - 'role-name'
   - 'no-changed-when'
+  - 'var-naming[no-reserved]'

.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+---
+name: Ansible Lint
+'on':
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the codebase.
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.x
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Install test dependencies.
+        run: pip3 install yamllint ansible-lint ansible
+
+      - name: Run yamllint.
+        run: yamllint .
+
+      - name: Run ansible-lint.
+        run: ansible-lint
+
+  molecule:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the codebase.
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Install test dependencies.
+        run: pip3 install ansible molecule molecule-plugins[docker]
+
+      - name: Install role dependencies.
+        run: ansible-galaxy install -r requirements.yml
+
+      - name: Run Molecule tests.
+        run: molecule test --all
+        env:
+          PY_COLORS: '1'
+          ANSIBLE_FORCE_COLOR: '1'

.yamllint

@@ -3,5 +3,13 @@ extends: default
 
 rules:
   line-length:
-    max: 200
+    max: 250
     level: warning
+  comments:
+    min-spaces-from-content: 1
+  comments-indentation: false
+  braces:
+    max-spaces-inside: 1
+  octal-values:
+    forbid-explicit-octal: true
+    forbid-implicit-octal: true

README.md

@@ -4,7 +4,70 @@
 [![Ansible Galaxy Downloads](https://img.shields.io/badge/dynamic/json?color=blueviolet&label=Galaxy%20Downloads&query=%24.download_count&url=https%3A%2F%2Fgalaxy.ansible.com%2Fapi%2Fv1%2Froles%2F39518%2F%3Fformat%3Djson)](https://galaxy.ansible.com/ui/standalone/roles/salvoxia/nut/)
 
 Installs and configures [NUT](http://networkupstools.org/) (Nework UPS
-tools) on Debian based systems.
+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)
+
+## Installing from Source
+
+By default the role will install NUT using the package manager as determined by 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.
+
+The following variables control installation from source:
+<table>
+  <tr>
+    <th>Variable</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td> 
+      
+`nut_install_from_source`
+    </td>
+    <td>
+Flag indicating whether to install NUT from source or not.<br>All the variables below have no effect if not set to `true`.<br>Default: `false`
+    </td>
+  </tr>
+  <tr>
+    <td> 
+      
+`nut_source_repository`
+    </td>
+    <td>
+The URL to the Git Repository to compile NUT from.<br>Default: `https://github.com/networkupstools/nut.git`
+    </td>
+  </tr>
+  <tr>
+    <td> 
+      
+`nut_source_tag`
+    </td>
+    <td>
+The Git Tag to check out before compiling NUT.<br>Can be a branch name as well.<br>Default: `v2.8.2`
+    </td>
+  </tr>
+  <tr>
+    <td> 
+      
+`nut_drivers`
+    </td>
+    <td>
+A list of NUT driver names to compile NUT. <br>For a list fo valid drivers refer to the `Drivers` section in the [generic manual for unified NUT drivers](https://networkupstools.org/docs/man/nutupsdrv.html)<br>Example:
+```yaml
+nut_drivers:
+  - snmp-ups
+  - netxml-ups
+```
+  </td>
+  </tr>
+</table>
 
 ## Role Variables
 
@@ -250,27 +313,11 @@ All these variables are optional:
   <tr>
     <td> 
 
-`nut_services`
-    </td>
-    <td>
-
-List of service names to enable<br>Default:
-```yaml
-nut_services:
-  - nut-driver-enumerator
-  - nut-monitor
-  - nut-server
-```
-  </td>
-  </tr>
-  <tr>
-    <td> 
-
 `nut_enable_service`
     </td>
     <td>
 
-Flag indicating whether to start the services defined in `nut_services` after configuration.<br>Default: `true`
+Flag indicating whether to start the services appropriate for the installed `nut_packages` after configuration.<br>Default: `true`
     </td>
   </tr>
   <tr>
@@ -420,7 +467,12 @@ Additional content to append to the `upsmon.conf` file
 ```
 
 For more examples, please see `tests/test.yml`.
+## Cheat Sheet
 
+Run a Docker container with systemd:
+```bash
+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
 

defaults/main.yml

@@ -2,17 +2,27 @@
 # Whether to start or not the NUT service after the configuration
 nut_enable_service: true
 
+# Indicates whether to install or remove NUT
+nut_state: present
+
+# Flag indicating whether to compile and install NUT from source instead of a package manager
+nut_install_from_source: false
+# Git source repository to use when installing NUT from source
+nut_source_repository: https://github.com/networkupstools/nut.git
+# The Git tag to compile when installing NUT from source
+nut_source_tag: v2.8.2
+# The NUT drivers to configure NUT with when installing from source. This variable only has any effect
+# if nut_install_from_source is set to true.
+nut_drivers: []
+#  - snmp-ups
+#  - netxml-ups
+
 # If this is set to false, none of the following options will have any effect.
 # Any and all changes to /etc/nut/* will be your responsibility.
 nut_managed_config: true
 
 nut_mode: standalone
 
-nut_services:
-  - nut-driver-enumerator
-  - nut-monitor
-  - nut-server
-
 nut_users:
   - name: monitor
     password: changeme

handlers/main.yml

@@ -1,7 +1,8 @@
 ---
 - name: Restart nut
-  ansible.builtin.service:
-    name: "{{ item }}"
-    state: restarted
-  with_items: "{{ nut_services }}"
+  ansible.builtin.include_tasks: "../tasks/restart.yml"
   when: nut_enable_service
+
+- name: Systemctl daemon-reload
+  ansible.builtin.systemd:
+    daemon_reload: true

molecule/dummy-ups.dev

@@ -0,0 +1,41 @@
+ambient.humidity: 0.00
+ambient.temperature: 0.0
+battery.charge: 100.00
+battery.charge.low: 20
+battery.runtime: 11520.00
+battery.runtime.low: 180.00
+battery.voltage: 198.00
+device.mfr: Eaton
+device.model: Eaton 9PX
+device.serial: XXXXXXXXXX
+device.type: ups
+driver.name: snmp-ups
+driver.parameter.pollinterval: 2
+driver.parameter.port: XX.XX.XX.XX
+driver.parameter.synchronous: no
+driver.version: 2.7.4
+driver.version.data: mge MIB 0.5
+driver.version.internal: 0.97
+input.phases: 1.00
+input.transfer.reason: 
+outlet.desc: Main Outlet
+outlet.id: 0
+output.current: 1.00
+output.frequency: 49.00
+output.phases: 1.00
+output.voltage: 230.00
+ups.beeper.status: enabled
+ups.delay.shutdown: 20
+ups.delay.start: 30
+ups.firmware: 02.14.0034
+ups.firmware.aux: JI
+ups.load: 7.00
+ups.mfr: Eaton
+ups.model: Eaton 9PX
+ups.serial: XXXXXXXXXX
+ups.start.auto: yes
+ups.status: OL
+ups.test.result: aborted
+ups.timer.reboot: -1.00
+ups.timer.shutdown: -1.00
+ups.timer.start: -1.00

molecule/dummy-ups2.dev

@@ -0,0 +1,41 @@
+ambient.humidity: 0.00
+ambient.temperature: 0.0
+battery.charge: 100.00
+battery.charge.low: 20
+battery.runtime: 11520.00
+battery.runtime.low: 180.00
+battery.voltage: 198.00
+device.mfr: Eaton
+device.model: Eaton 9PX
+device.serial: XXXXXXXXXX
+device.type: ups
+driver.name: snmp-ups
+driver.parameter.pollinterval: 2
+driver.parameter.port: XX.XX.XX.XX
+driver.parameter.synchronous: no
+driver.version: 2.7.4
+driver.version.data: mge MIB 0.5
+driver.version.internal: 0.97
+input.phases: 1.00
+input.transfer.reason: 
+outlet.desc: Main Outlet
+outlet.id: 0
+output.current: 1.00
+output.frequency: 49.00
+output.phases: 1.00
+output.voltage: 230.00
+ups.beeper.status: enabled
+ups.delay.shutdown: 20
+ups.delay.start: 30
+ups.firmware: 02.14.0034
+ups.firmware.aux: JI
+ups.load: 7.00
+ups.mfr: Eaton
+ups.model: Eaton 9PX
+ups.serial: XXXXXXXXXX
+ups.start.auto: yes
+ups.status: OL
+ups.test.result: aborted
+ups.timer.reboot: -1.00
+ups.timer.shutdown: -1.00
+ups.timer.start: -1.00

molecule/install_from_pkgmgr/converge.yml

@@ -0,0 +1,40 @@
+---
+- name: Converge
+  hosts: all
+  gather_facts: true
+  pre_tasks:
+    - name: Create NUT configuration folder.
+      ansible.builtin.file:
+        path: "/etc/nut"
+        state: directory
+        mode: '0755'
+    - name: Copy dummy-ups.dev file
+      ansible.builtin.copy:
+        src: "../dummy-ups.dev"
+        dest: "/etc/nut/dummy-ups.dev"
+        mode: '0755'
+    - name: Copy dummy-ups2.dev file
+      ansible.builtin.copy:
+        src: "../dummy-ups2.dev"
+        dest: "/etc/nut/dummy-ups2.dev"
+        mode: '0755'
+  roles:
+    - role: salvoxia.nut
+      nut_users:
+        - name: monitor
+          password: changeme
+          role: secondary
+        - name: second_user
+          password: insecure_password
+          role: primary
+      nut_ups:
+        - name: dummy_ups
+          monitoruser: monitor
+          driver: dummy-ups
+          device: /etc/nut/dummy-ups.dev
+          description: "Dummy UPS for testing"
+        - name: dummy_ups2
+          monitoruser: second_user
+          driver: dummy-ups
+          device: /etc/nut/dummy-ups2.dev
+          description: "Dummy UPS 2 for testing"