netclient test.yml example is incomplete

averymd commented 2 years ago

This is a really awesome role. Thank you for making it! Looking at the 1.3.0 version of tests/test.yml as examples for setting up a playbook, there are a few things that seem inaccurate/incomplete for the purposes of user documentation and were confusing. I was interested in setting up netclient mode:

# NetClient only mode
- role: ansible-role-nut
  nut_mode: netclient
  nut_user: monitor
  nut_password: Whatever...
  nut_ups: []
  nut_services:
    - nut-monitor

The role seems to have to be ntd.nut now instead of ansible-role-nut. The test.yml says "ansible-role-nut is the uninstalled name of the ntd.nut role", but it's unclear to me what "uninstalled name" means. Maybe this could just use a little verbiage tweak of something like "Use ntd.nut instead of ansible-role-nut if using this in actual playbooks"?
More importantly, if nut_ups is empty, no MONITOR line will generate in upsmon.conf.
It seems like I should only need to give the name of the remote UPS, but ansible will throw an error if a driver isn't also provided.
Setting nut_role to "slave" is probably a pretty common need for client devices, right? (I don't have extensive NUT experience.) If so, that would be nice to have in the example.

My block ended up looking more like this:

- role: ntd.nut
  nut_host: ipaddress
  nut_user: monitor
  nut_password: monitor
  nut_mode: netclient
  nut_role: slave
  nut_ups: 
    - name: ups
      driver: usbhid
      device: na
      description: pfsense UPS
  nut_services:
    - nut-monitor

Given the differences, maybe this complete example is better for the README than the tests file so that the README contains the current "master" example + one client example.

ntd commented 2 years ago

The test.yml says "ansible-role-nut is the uninstalled name of the ntd.nut role", but it's unclear to me what "uninstalled name" means.

The rule name is ntd.nut. ansible-role-nut is the folder name and it is a dirty hack to be able to run tests in Travis on a pristine repository.

More importantly, if nut_ups is empty, no MONITOR line will generate in upsmon.conf.

For 2: do you have a use case where you need a monitor line without an UPS? For 3: do you have a use case where you need to have an UPS without a driver?

In general, if you feel the documentation can be improved I will be happy to merge anything you throw at me.

aleprovencio commented 1 year ago

I have successfully run this role on a server/client scenario, like this:

# server
nut_mode: netserver
nut_role: master
nut_host: 192.168.55.2
nut_user: remoteuser
nut_password: '{{ vault_nut_remoteuser_password }}'
nut_ups:
  - name: APC
    driver: usbhid-ups
    device: auto
    description: BZ1500XLBI-BR
nut_upsd_extra: |
  LISTEN 192.168.55.2 3493
  LISTEN 127.0.0.1 3493
nut_packages:
  - nut
  - nut-server
nut_services:
  - nut-driver
  - nut-monitor
  - nut-server

# clients
nut_mode: netclient
nut_role: slave
nut_host: 192.168.55.2
nut_user: remoteuser
nut_password: '{{ vault_nut_remoteuser_password }}'
nut_ups:
  - name: APC
    driver: usbhid-ups
    device: auto
    description: BZ1500XLBI-BR
nut_packages:
  - nut-client
nut_services:
  - nut-monitor

ntd / ansible-role-nut

netclient test.yml example is incomplete #11