NETXML-UPS(8)
=============

NAME
----

netxml-ups - Driver for Eaton / MGE Network Management Card / Proxy
(XML/HTTP Protocol) equipment

SYNOPSIS
--------

*netxml-ups* -h

*netxml-ups* -a 'UPS_NAME' ['OPTIONS']

NOTE: This man page only documents the hardware-specific features of the
netxml-ups driver.  For information about the core driver, see
linkman:nutupsdrv[8].

SUPPORTED HARDWARE
------------------

netxml-ups supports all recent Eaton / MGE models which use a Network
Management Card or Proxy (MGE XML/HTTP protocol based). This applies to both
Eaton (previously MGE Office Protection Systems) and to MGE UPS SYSTEMS.
Supported card and proxy models are:

 * NMC Minislot (Ref 66102, firmware EA or newer),
 * SNMP/Web Minislot card (Ref 66244)
 * NMC Transverse (Ref 66074),
 * NMC & Modbus/JBus (Ref 66103),
 * Network Management Proxy,
 * ePDU Monitored (newer version).

Older models, such as SNMP card (Ref 66062 and Ref 66045), use the SNMP
protocol and should use the linkman:snmp-ups[8] driver with the `mibs=mge`
parameter.

EXTRA ARGUMENTS
---------------

This driver supports the following optional settings in the
linkman:ups.conf[5]:

*timeout*='value'::
The timeout for connecting to and reading from the UPS. Defaults to 5 seconds.
Don't change this value unless you know exactly what you're doing.
+
This value *must never* be higher than half the `MAXAGE` value specified in
linkman:upsd.conf[5], otherwise you run the risk that linkman:upsd[8] declares
the driver stale while it is waiting for a connection to timeout.

*subscribe*::
Connect to the NMC in subscribed mode. This allows to receive notifications
and alarms more quickly, beside from the standard polling requests.

*login*='value'::
Set the login value for authenticated mode. This feature also needs the
*password* argument, and allows value settings in the card.
This feature is not used yet.

*password*='value'::
Set the password value, needed with the login for authenticated mode.
This feature is not used yet.

*shutdown_duration*='value'::
Set the shutdown duration of the operating system, in seconds. This
represents the amount of time needed by the system to operate a clean
shutdown. Defaults to 120 seconds.

*shutdown_timer*='value'::
Set the shutdown timer, in seconds. After 'value' seconds running on battery,
the local system will receive a notification to shut down.
Defaults to "none" (disabled).

*do_convert_deci*::
If this flag value is present, the driver assumes you have a very old
MGE networked UPS (or rather an old network management card firmware)
which serves certain measurements spelled 10x too big in the XML markup.
+
Originally such measurements were decimated by the driver -- but this is
wrong for newer, more sane, devices -- so this behavior was deprecated
and is now disabled by default. Enabling this flag in configuration of a
particular driver instance restores the old behavior for those measurements.

IMPLEMENTATION
--------------

The hostname of the networked UPS is specified with the `port` value in
`ups.conf`, i.e.:

	[mgexml]
		driver = netxml-ups
		port = http://netxml-ups.example.com:80

Specifying the method to connect to the UPS (http, https) is mandatory.
If the port is equal to the default for the method specified (80 for http,
443 for https) it may be omitted.

In order not to overload older NMCs by polling them too frequently, it is
recommended to increase the "pollinterval" (see linkman:nutupsdrv[8]) and
linkman:ups.conf[5]) to at least 5 seconds.

KNOWN ISSUES
------------

HTTP(S) proxies
~~~~~~~~~~~~~~~

Don't connect to the UPS through a proxy. Although it would be trivial to add
support for proxies, this is not recommended and don't ask for it. Not only
because it will prevent the driver to make a persistent connection to the UPS,
but also it adds an additional failure mode. If the proxy goes down (for
whatever reason), the driver will no longer be able to reach the UPS.

include::networked_hostnames.txt[]

AUTHORS
-------

Arjen de Korte <adkorte-guest@alioth.debian.org>

SEE ALSO
--------

The core driver:
~~~~~~~~~~~~~~~~

linkman:nutupsdrv[8]

Internet resources:
~~~~~~~~~~~~~~~~~~~

The NUT (Network UPS Tools) home page: https://www.networkupstools.org/
