Merge pull request #625 from codemeister64/apcupsd-role

Add Apcupsd role

README.md

@@ -18,6 +18,7 @@ If you have a spare domain name you can configure applications to be accessible
 ## Available Applications
 
 * [Airsonic](https://airsonic.github.io/) - catalog and stream music
+* [Apcupsd](http://www.apcupsd.org/) - A daemon for controlling APC UPSes
 * [Bazarr](https://github.com/morpheus65535/bazarr) - companion to Radarr and Sonarr for downloading subtitles
 * [Bitwarden](https://github.com/dani-garcia/vaultwarden) - Password Manger (Technically Vaultwarden, a lightweight implementation in Rust)
 * [Booksonic](https://booksonic.org/) - The selfhosted audiobook server

nas.yml

@@ -57,6 +57,10 @@
       tags:
         - airsonic
 
+    - role: apcupsd
+      tags:
+        - apcupsd
+
     - role: bazarr
       tags:
         - bazarr

roles/apcupsd/defaults/main.yml

@@ -0,0 +1,24 @@
+---
+apcupsd_enabled: false
+
+# directories
+apcupsd_data_directory: "{{ docker_home }}/apcupsd"
+
+# network
+apcupsd_port: "3551"
+
+# specs
+apcupsd_memory: 1g
+
+# docker
+apcupsd_container_name: apcupsd
+
+# ups config
+apcupsd_onbatterydelay: 6
+apcupsd_batterylevel: 5
+apcupsd_minutes: 5
+apcupsd_timeout: 0
+apcupsd_annoy: 300
+apcupsd_annoydelay: 60
+apcupsd_nologon: "disable"
+apcupsd_killdelay: 0

roles/apcupsd/molecule/default/molecule.yml

@@ -0,0 +1,6 @@
+---
+provisioner:
+  inventory:
+    group_vars:
+      all:
+        apcupsd_enabled: true

roles/apcupsd/molecule/default/side_effect.yml

@@ -0,0 +1,10 @@
+---
+- name: Stop
+  hosts: all
+  become: true
+  tasks:
+    - name: "Include {{ lookup('env', 'MOLECULE_PROJECT_DIRECTORY') | basename }} role"
+      include_role:
+        name: "{{ lookup('env', 'MOLECULE_PROJECT_DIRECTORY') | basename }}"
+      vars:
+        apcupsd_enabled: false

roles/apcupsd/molecule/default/verify.yml

@@ -0,0 +1,18 @@
+---
+- name: Verify
+  hosts: all
+  gather_facts: false
+  tasks:
+    - include_vars:
+        file: ../../defaults/main.yml
+
+    - name: Get container state
+      docker_container_info:
+        name: "{{ apcupsd_container_name }}"
+      register: result
+
+    - name: Check Apcupsd is running
+      assert:
+        that:
+          - result.container['State']['Status'] == "running"
+          - result.container['State']['Restarting'] == false

roles/apcupsd/molecule/default/verify_stopped.yml

@@ -0,0 +1,18 @@
+---
+- name: Verify
+  hosts: all
+  gather_facts: false
+  tasks:
+    - include_vars:
+        file: ../../defaults/main.yml
+
+    - name: Try and stop and remove Apcupsd
+      docker_container:
+        name: "{{ apcupsd_container_name }}"
+        state: absent
+      register: result
+
+    - name: Check Apcupsd is stopped
+      assert:
+        that:
+          - not result.changed

roles/apcupsd/tasks/main.yml

@@ -0,0 +1,48 @@
+---
+
+- name: Start Apcupsd
+  block:
+    - name: Create Apcupsd Directories
+      ansible.builtin.file:
+        path: "{{ item }}"
+        state: directory
+      with_items:
+        - "{{ apcupsd_data_directory }}"
+
+    - name: "Check if Apcupsd config exists"
+      ansible.builtin.stat:
+        path: "{{ apcupsd_data_directory }}/apcupsd.conf"
+      register: apcupsd_config_path
+
+    - name: Template Apcupsd config
+      ansible.builtin.template:
+        src: apcupsd.conf
+        dest: "{{ apcupsd_data_directory }}/apcupsd.conf"
+      when: not apcupsd_config_path.stat.exists
+
+    - name: Apcupsd Docker Container
+      community.docker.docker_container:
+        name: "{{ apcupsd_container_name }}"
+        image: gregewing/apcupsd
+        pull: true
+        privileged: true
+        volumes:
+          - "/var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket"
+          - "{{ apcupsd_data_directory }}/apcupsd.conf:/etc/apcupsd/apcupsd.conf"
+        ports:
+          - "{{ apcupsd_port }}:3551"
+        devices:
+          - "{{ apcupsd_device }}:{{ apcupsd_device }}"
+        env:
+          TZ: "{{ ansible_nas_timezone }}"
+        restart_policy: unless-stopped
+        memory: "{{ apcupsd_memory }}"
+  when: apcupsd_enabled is true
+
+- name: Stop Apcupsd
+  block:
+    - name: Stop Apcupsd
+      community.docker.docker_container:
+        name: "{{ apcupsd_container_name }}"
+        state: absent
+  when: apcupsd_enabled is false

roles/apcupsd/templates/apcupsd.conf

@@ -0,0 +1,333 @@
+## apcupsd.conf v1.1 ##
+# 
+#  for apcupsd release 3.14.12 (29 March 2014) - debian
+#
+# "apcupsd" POSIX config file
+
+#
+# ========= General configuration parameters ============
+#
+
+# UPSNAME xxx
+#   Use this to give your UPS a name in log files and such. This
+#   is particulary useful if you have multiple UPSes. This does not
+#   set the EEPROM. It should be 8 characters or less.
+UPSNAME UPS.host.domain
+
+# UPSCABLE <cable>
+#   Defines the type of cable connecting the UPS to your computer.
+#
+#   Possible generic choices for <cable> are:
+#     simple, smart, ether, usb
+#
+#   Or a specific cable model number may be used:
+#     940-0119A, 940-0127A, 940-0128A, 940-0020B,
+#     940-0020C, 940-0023A, 940-0024B, 940-0024C,
+#     940-1524C, 940-0024G, 940-0095A, 940-0095B,
+#     940-0095C, 940-0625A, M-04-02-2000
+#
+UPSCABLE usb
+
+# To get apcupsd to work, in addition to defining the cable
+# above, you must also define a UPSTYPE, which corresponds to
+# the type of UPS you have (see the Description for more details).
+# You must also specify a DEVICE, sometimes referred to as a port.
+# For USB UPSes, please leave the DEVICE directive blank. For
+# other UPS types, you must specify an appropriate port or address.
+#
+# UPSTYPE   DEVICE           Description
+# apcsmart  /dev/tty**       Newer serial character device, appropriate for 
+#                            SmartUPS models using a serial cable (not USB).
+#
+# usb       <BLANK>          Most new UPSes are USB. A blank DEVICE
+#                            setting enables autodetection, which is
+#                            the best choice for most installations.
+#
+# net       hostname:port    Network link to a master apcupsd through apcupsd's 
+#                            Network Information Server. This is used if the
+#                            UPS powering your computer is connected to a 
+#                            different computer for monitoring.
+#
+# snmp      hostname:port:vendor:community
+#                            SNMP network link to an SNMP-enabled UPS device.
+#                            Hostname is the ip address or hostname of the UPS 
+#                            on the network. Vendor can be can be "APC" or 
+#                            "APC_NOTRAP". "APC_NOTRAP" will disable SNMP trap 
+#                            catching; you usually want "APC". Port is usually 
+#                            161. Community is usually "private".
+#
+# netsnmp   hostname:port:vendor:community
+#                            OBSOLETE
+#                            Same as SNMP above but requires use of the 
+#                            net-snmp library. Unless you have a specific need
+#                            for this old driver, you should use 'snmp' instead.
+#
+# dumb      /dev/tty**       Old serial character device for use with 
+#                            simple-signaling UPSes.
+#
+# pcnet     ipaddr:username:passphrase:port
+#                            PowerChute Network Shutdown protocol which can be 
+#                            used as an alternative to SNMP with the AP9617 
+#                            family of smart slot cards. ipaddr is the IP 
+#                            address of the UPS management card. username and 
+#                            passphrase are the credentials for which the card 
+#                            has been configured. port is the port number on 
+#                            which to listen for messages from the UPS, normally 
+#                            3052. If this parameter is empty or missing, the 
+#                            default of 3052 will be used.
+#
+# modbus    /dev/tty**       Serial device for use with newest SmartUPS models
+#                            supporting the MODBUS protocol.
+#
+#UPSTYPE apcsmart
+UPSTYPE usb
+#DEVICE /dev/ttyS0
+
+# POLLTIME <int>
+#   Interval (in seconds) at which apcupsd polls the UPS for status. This
+#   setting applies both to directly-attached UPSes (UPSTYPE apcsmart, usb, 
+#   dumb) and networked UPSes (UPSTYPE net, snmp). Lowering this setting
+#   will improve apcupsd's responsiveness to certain events at the cost of
+#   higher CPU utilization. The default of 60 is appropriate for most
+#   situations.
+#POLLTIME 60
+
+# LOCKFILE <path to lockfile>
+#   Path for device lock file. Not used on Win32.
+LOCKFILE /var/lock
+
+# SCRIPTDIR <path to script directory>
+#   Directory in which apccontrol and event scripts are located.
+SCRIPTDIR /etc/apcupsd
+
+# PWRFAILDIR <path to powerfail directory>
+#   Directory in which to write the powerfail flag file. This file
+#   is created when apcupsd initiates a system shutdown and is
+#   checked in the OS halt scripts to determine if a killpower
+#   (turning off UPS output power) is required.
+PWRFAILDIR /etc/apcupsd
+
+# NOLOGINDIR <path to nologin directory>
+#   Directory in which to write the nologin file. The existence
+#   of this flag file tells the OS to disallow new logins.
+NOLOGINDIR /etc
+
+
+#
+# ======== Configuration parameters used during power failures ==========
+#
+
+# The ONBATTERYDELAY is the time in seconds from when a power failure
+#   is detected until we react to it with an onbattery event.
+#
+#   This means that, apccontrol will be called with the powerout argument
+#   immediately when a power failure is detected.  However, the
+#   onbattery argument is passed to apccontrol only after the 
+#   ONBATTERYDELAY time.  If you don't want to be annoyed by short
+#   powerfailures, make sure that apccontrol powerout does nothing
+#   i.e. comment out the wall.
+ONBATTERYDELAY {{ apcupsd_onbatterydelay }}
+
+# 
+# Note: BATTERYLEVEL, MINUTES, and TIMEOUT work in conjunction, so
+# the first that occurs will cause the initation of a shutdown.
+#
+
+# If during a power failure, the remaining battery percentage
+# (as reported by the UPS) is below or equal to BATTERYLEVEL, 
+# apcupsd will initiate a system shutdown.
+BATTERYLEVEL {{ apcupsd_batterylevel }}
+
+# If during a power failure, the remaining runtime in minutes 
+# (as calculated internally by the UPS) is below or equal to MINUTES,
+# apcupsd, will initiate a system shutdown.
+MINUTES {{ apcupsd_minutes }}
+
+# If during a power failure, the UPS has run on batteries for TIMEOUT
+# many seconds or longer, apcupsd will initiate a system shutdown.
+# A value of 0 disables this timer.
+#
+#  Note, if you have a Smart UPS, you will most likely want to disable
+#    this timer by setting it to zero. That way, you UPS will continue
+#    on batteries until either the % charge remaing drops to or below BATTERYLEVEL,
+#    or the remaining battery runtime drops to or below MINUTES.  Of course,
+#    if you are testing, setting this to 60 causes a quick system shutdown
+#    if you pull the power plug.   
+#  If you have an older dumb UPS, you will want to set this to less than
+#    the time you know you can run on batteries.
+TIMEOUT {{ apcupsd_timeout }}
+
+#  Time in seconds between annoying users to signoff prior to
+#  system shutdown. 0 disables.
+ANNOY {{ apcupsd_annoy }}
+
+# Initial delay after power failure before warning users to get
+# off the system.
+ANNOYDELAY {{ apcupsd_annoydelay }}
+
+# The condition which determines when users are prevented from
+# logging in during a power failure.
+# NOLOGON <string> [ disable | timeout | percent | minutes | always ]
+NOLOGON {{ apcupsd_nologon }}
+
+# If KILLDELAY is non-zero, apcupsd will continue running after a
+# shutdown has been requested, and after the specified time in
+# seconds attempt to kill the power. This is for use on systems
+# where apcupsd cannot regain control after a shutdown.
+# KILLDELAY <seconds>  0 disables
+KILLDELAY {{ apcupsd_killdelay }}
+
+#
+# ==== Configuration statements for Network Information Server ====
+#
+
+# NETSERVER [ on | off ] on enables, off disables the network
+#  information server. If netstatus is on, a network information
+#  server process will be started for serving the STATUS and
+#  EVENT data over the network (used by CGI programs).
+NETSERVER on
+
+# NISIP <dotted notation ip address>
+#  IP address on which NIS server will listen for incoming connections.
+#  This is useful if your server is multi-homed (has more than one
+#  network interface and IP address). Default value is 0.0.0.0 which
+#  means any incoming request will be serviced. Alternatively, you can
+#  configure this setting to any specific IP address of your server and 
+#  NIS will listen for connections only on that interface. Use the
+#  loopback address (127.0.0.1) to accept connections only from the
+#  local machine.
+NISIP 0.0.0.0
+
+# NISPORT <port> default is 3551 as registered with the IANA
+#  port to use for sending STATUS and EVENTS data over the network.
+#  It is not used unless NETSERVER is on. If you change this port,
+#  you will need to change the corresponding value in the cgi directory
+#  and rebuild the cgi programs.
+NISPORT 3551
+
+# If you want the last few EVENTS to be available over the network
+# by the network information server, you must define an EVENTSFILE.
+EVENTSFILE /var/log/apcupsd.events
+
+# EVENTSFILEMAX <kilobytes>
+#  By default, the size of the EVENTSFILE will be not be allowed to exceed
+#  10 kilobytes.  When the file grows beyond this limit, older EVENTS will
+#  be removed from the beginning of the file (first in first out).  The
+#  parameter EVENTSFILEMAX can be set to a different kilobyte value, or set
+#  to zero to allow the EVENTSFILE to grow without limit.
+EVENTSFILEMAX 10
+
+#
+# ========== Configuration statements used if sharing =============
+#            a UPS with more than one machine
+
+#
+# Remaining items are for ShareUPS (APC expansion card) ONLY
+#
+
+# UPSCLASS [ standalone | shareslave | sharemaster ]
+#   Normally standalone unless you share an UPS using an APC ShareUPS
+#   card.
+UPSCLASS standalone
+
+# UPSMODE [ disable | share ]
+#   Normally disable unless you share an UPS using an APC ShareUPS card.
+UPSMODE disable
+
+#
+# ===== Configuration statements to control apcupsd system logging ========
+#
+
+# Time interval in seconds between writing the STATUS file; 0 disables
+STATTIME 0
+
+# Location of STATUS file (written to only if STATTIME is non-zero)
+STATFILE /var/log/apcupsd.status
+
+# LOGSTATS [ on | off ] on enables, off disables
+# Note! This generates a lot of output, so if         
+#       you turn this on, be sure that the
+#       file defined in syslog.conf for LOG_NOTICE is a named pipe.
+#  You probably do not want this on.
+LOGSTATS off
+
+# Time interval in seconds between writing the DATA records to
+#   the log file. 0 disables.
+DATATIME 0
+
+# FACILITY defines the logging facility (class) for logging to syslog. 
+#          If not specified, it defaults to "daemon". This is useful 
+#          if you want to separate the data logged by apcupsd from other
+#          programs.
+#FACILITY DAEMON
+
+#
+# ========== Configuration statements used in updating the UPS EPROM =========
+#
+
+#
+# These statements are used only by apctest when choosing "Set EEPROM with conf
+# file values" from the EEPROM menu. THESE STATEMENTS HAVE NO EFFECT ON APCUPSD.
+#
+
+# UPS name, max 8 characters 
+#UPSNAME UPS_IDEN
+
+# Battery date - 8 characters
+#BATTDATE mm/dd/yy
+
+# Sensitivity to line voltage quality (H cause faster transfer to batteries)  
+# SENSITIVITY H M L        (default = H)
+#SENSITIVITY H
+
+# UPS delay after power return (seconds)
+# WAKEUP 000 060 180 300   (default = 0)
+#WAKEUP 60
+
+# UPS Grace period after request to power off (seconds)
+# SLEEP 020 180 300 600    (default = 20)
+#SLEEP 180
+
+# Low line voltage causing transfer to batteries
+# The permitted values depend on your model as defined by last letter 
+#  of FIRMWARE or APCMODEL. Some representative values are:
+#    D 106 103 100 097
+#    M 177 172 168 182
+#    A 092 090 088 086
+#    I 208 204 200 196     (default = 0 => not valid)
+#LOTRANSFER  208
+
+# High line voltage causing transfer to batteries
+# The permitted values depend on your model as defined by last letter 
+#  of FIRMWARE or APCMODEL. Some representative values are:
+#    D 127 130 133 136
+#    M 229 234 239 224
+#    A 108 110 112 114
+#    I 253 257 261 265     (default = 0 => not valid)
+#HITRANSFER 253
+
+# Battery charge needed to restore power
+# RETURNCHARGE 00 15 50 90 (default = 15)
+#RETURNCHARGE 15
+
+# Alarm delay 
+# 0 = zero delay after pwr fail, T = power fail + 30 sec, L = low battery, N = never
+# BEEPSTATE 0 T L N        (default = 0)
+#BEEPSTATE T
+
+# Low battery warning delay in minutes
+# LOWBATT 02 05 07 10      (default = 02)
+#LOWBATT 2
+
+# UPS Output voltage when running on batteries
+# The permitted values depend on your model as defined by last letter 
+#  of FIRMWARE or APCMODEL. Some representative values are:
+#    D 115
+#    M 208
+#    A 100
+#    I 230 240 220 225     (default = 0 => not valid)
+#OUTPUTVOLTS 230
+
+# Self test interval in hours 336=2 weeks, 168=1 week, ON=at power on
+# SELFTEST 336 168 ON OFF  (default = 336)
+#SELFTEST 336

website/docs/applications/system-tools/apcupsd.md

@@ -0,0 +1,25 @@
+---
+title: "Apcupsd"
+---
+
+Homepage: [http://www.apcupsd.org/](http://www.apcupsd.org/)
+
+A daemon that manages and monitors a Connected APC UPS Device, which has the ability to gracefully shut down the host computer in the event of a power outage.
+
+## Usage
+
+1. Set `apcupsd_enabled: true` in your `inventories/<your_inventory>/nas.yml` file
+2. Set `apcupsd_device` variable to connected UPS device path (e.g `apcupsd_device: "/dev/usb/hiddev0"`) in your `inventories/<your_inventory>/nas.yml` file.
+
+In addition, the following parameters can be overridden  in your `inventories/<your_inventory>/nas.yml` file:
+
+* `apcupsd_onbatterydelay` - the time in seconds from when a power failure is detected until we react to it with an onbattery event
+* `apcupsd_batterylevel` - if during a power failure, the remaining battery percentage is below or equal to BATTERYLEVEL, apcupsd will initiate a system shutdown
+* `apcupsd_minutes` - if during a power failure, the remaining runtime in minutes is below or equal to MINUTES, apcupsd, will initiate a system shutdown
+* `apcupsd_timeout` - if during a power failure, the UPS has run on batteries for TIMEOUT many seconds or longer, apcupsd will initiate a system shutdown. A value of 0 disables this timer
+* `apcupsd_annoy` - time in seconds between annoying users to signoff prior to system shutdown. 0 disables
+* `apcupsd_annoydelay` - initial delay after power failure before warning users to get off the system
+* `apcupsd_nologon` - the condition which determines when users are prevented from logging in during a power failure. Possible values: [`disable` | `timeout` | `percent` | `minutes` | `always`]
+* `apcupsd_killdelay` - if KILLDELAY is non-zero, apcupsd will continue running after a shutdown has been requested, and after the specified time in seconds attempt to kill the power. This is for use on systems where apcupsd cannot regain control after a shutdown
+
+Apcupsd's exposed netserver default port is 3551, which can be used to collect UPS events and data.