====== Uninterruptible Power Supply Monitoring ======

AstLinux now uses the [[http://www.networkupstools.org/|Network UPS Tools]] (NUT) package to monitor [[wp>Uninterruptible_power_supply|Uninterruptible power supplies]] (UPS) via USB and Network connections.

!!Note: AstLinux 1.1.4 or later is required!!

==== Hardware Compatibility ====

The NUT project offers a very nice Hardware Compatibility list via their web site:

[[http://www.networkupstools.org/stable-hcl.html|Hardware Compatibility List]]

AstLinux supports **Connection** types of USB and Network (not Serial).


==== General Configuration ====

Select the Network Tab in the web interface.\\
{{:userdoc:ipv6-tunnel-network-tab.jpg?nolink|Network Tab}}

**Default UPS settings with UPS Monitoring disabled:**

If neither a "UPS Driver" or a "Network NUT ups@host" are defined then UPS Monitoring is disabled, as in the example below.

{{:userdoc:ups-default-config.jpg?nolink|UPS Default Configuration}}

!!Note ->!! By default the "UPS Password" is: ''astlinux''.

\\
**Available UPS device drivers:**

Both USB and Network (SNMP and XML/HTTP) monitoring connections are supported.

{{:userdoc:ups-device-menu.jpg?nolink|UPS Device Menu}}

The "Driver Data" field provides additional data necessary for some some drivers (not USB).

  USB  - ""
  SNMP - IP address or DNS name, eg. 10.10.10.1
  XML  - URL, eg. http://netxml-ups.example.com

\\
**Configure a "master" UPS server using a locally connected UPS via USB:**

If a "UPS Driver" is defined then UPS Monitoring is enabled using the locally connected UPS.  Network services may be enabled using "Network UPS Server" to support remote NUT clients.

{{:userdoc:ups-server-config.jpg?nolink|UPS Server Configuration}}

!!Note ->!! The firewall port on the server, if needed, is 3493/TCP

\\
**Configure as a client to a remote NUT server:**

If "Network NUT ups@host" is defined then UPS Monitoring is enabled using a remote NUT server.

!!Note ->!! A "UPS Driver" can not be defined when acting as a client.  Additionally, the "Network UPS Server" entry will be ignored.

{{:userdoc:ups-client-config.jpg?nolink|UPS Client Configuration}}

\\
**Specify Notify Options:**

Email notifications will be send if "Notify Email Addresses To" contains a valid email address.  Multiple email addresses may be space separated.

{{:userdoc:ups-notify-options.jpg?nolink|UPS Notify Options}}

Finally, the "Kill Power on the UPS after a Powerfail Shutdown" only applies if a "UPS Driver" is defined.  When enabled this option will instruct the UPS to cut power if both on battery and a shutdown is in progress.  Power will be cut approximately 60 seconds after a shutdown.  The idea is when line power is restored the battery will not be totally depleted and the UPS connected device will be power cycled off/on. 
==== Display UPS Status ====

Select the Status Tab in the web interface.\\
{{:userdoc:ups-status-tab.png?nolink|Status Tab}}

{{:userdoc:ups-monitoring-status.jpg?nolink|UPS Monitoring Status}}

==== Compatible Devices ====

The NUT monitoring package is commonly used in commercially available products.  One example is NAS storage devices where a graceful shutdown while on UPS battery power is very desirable.  One example is the Synology Diskstation using DSM 4.2, in this example AstLinux, at IP address 10.10.10.1, is acting as a Network UPS server.

{{:userdoc:ups-diskstation-astlinux.jpg?nolink|Diskstation to AstLinux}}

!!Tip ->!! Be sure to test an automatic shutdown in a controlled environment rather than later scratching your head when something did not work as expected following an actual power loss.

==== CLI Custom Configuration ====

While the web interface offers enough flexibility for most situations, there may be situations where more custom NUT configurations are desired.  This can be done by using the ''/mnt/kd/ups/'' directory.

!!Tip ->!! A working knowledge of NUT is required.

If any of the following files exist, they will be used instead of the automatic rc.conf variable generated versions:

  /mnt/kd/ups/ups.conf
  /mnt/kd/ups/upsd.conf
  /mnt/kd/ups/upsd.users
  /mnt/kd/ups/upsmon.conf

Additionally, in very special situations, the following two files can be added.  The ''upssched.conf'' will also have to reference a ''upssched-cmd'' script similar to ''upsnotify''.

  /mnt/kd/ups/upssched.conf
  /mnt/kd/ups/upsnotify

!!Tip ->!! The directory ''/stat/etc/ups/'' contains the sample templates for the above files as reference.

The ''[master]'' user's password is auto-generated as a random string, which may be accessed by the ''upsd.users'' and ''upsmon.conf'' configuration files using the token: ''@MASTER_PASS@'' .  For example a snippet of a custom ''upsd.users'' could contain:

  [master]
  password = @MASTER_PASS@
  upsmon master

or a snippet of a custom ''upsmon.conf'' could contain:

  MONITOR ups@localhost 1 master @MASTER_PASS@ master

Of course a custom ''upsd.users'' and ''upsmon.conf'' could share a custom ''[master]'' user's password if desired.

==== Windows NUT software ====

!!Warning: !! The latest [[https://networkupstools.org/download.html#_binary_packages|Windows NUT MSI installer]] 2.6.5-6 is broken (missing libraries).

The one from this Pull Request works fine:
https://github.com/networkupstools/nut/pull/455