The Network UPS Tools repository
C Shell M4 Python C++ Perl Other
Clone or download
jimklimov and aquette Use target for drivers in Linux systemd (updated) and SMF instances f…
…or drivers in new Solaris-like systems (and bring AIX initscript into better shape) (#330)

* Use target for drivers in systemd

This allows much better granularity and better monitoring in case of
multiple UPSes.

* nut-driver.target improvements suggested by @peterhoeg in PR#229

* systemd units dependencies revised and commented

* nut-driver-enumerator.sh initial commit

* nut-driver@.service.in : integrate comments from @peterhoeg about extending unit requirements

* WIP : initial integration of nut-driver-enumerator.sh/service into makefiles etc.

* nut-driver-enumerator.sh renamed into nut-driver-enumerator.sh.in as it has processable templates in code

* nut-driver-enumerator.sh.in : add its own config-file support to set the variables used inside (if not via command-line env)

* nut-driver-enumerator.sh.in : fix up the copyright header

* Subject: Fix systemd service file for Debian
From: Laurent Bigonville <bigon@debian.org>
Forwarded: not-needed

* nut-driver-enumerator.sh.in : complete the Solaris SMF support in the helper script

* EXTRA_DIST the scripts/systemd/nut-driver.target (non-templated) file

* nut-driver-enumerator.sh.in : updated comments (esp. about usage and exit-codes) and runtime messages

* nut-driver-enumerator.service.in : define an actual service payload

* nut-driver-enumerator.sh.in : refactor the logic of MAIN PROGRAM into smaller routines for readability

* nut-driver-enumerator.sh.in : introduce routines to help define custom dependencies of particular drivers on other services

* nut-driver-enumerator.sh.in : allow custom NUT_CONF_DIR from envvar, to facilitate testing

* nut-server.service.in : typo fix in comments

* nut-driver-enumerator.sh.in : support the concept of localhost networking dependencies, and define vars with lists of services to depend on

* nut-driver-enumerator.sh.in : use proper FMRI:instance separator for SMF

* nut-driver-enumerator.sh.in : added variables for dependency type on third-party service units

* nut-driver-enumerator.sh.in : change upsconf_getDriverMedia() output from tab-separated to multiline; add upsconf_getMedia() and upsconf_debug() and upslist_debug()

* nut-driver-enumerator.sh.in : refactor with upsconf_getValue() and cached pre-cooked ups.conf data; infrastructure to configure service dependencies when adding the service instance

* Remove hardcoded dependencies on udev and network from provided systemd units; add comments about extending via drop-in files and that nut-driver-enumerator will do this for nut-drivers

* nutshutdown.in : mark executable

* nut-driver-enumerator.sh.in : complete the systemd drop-in support for custom dependencies for a driver

* nut-driver-enumerator.sh.in : complete the SMF drop-in support for custom dependencies for a driver

* nut-driver-enumerator.sh.in : comment-away upslist_debug() in default runs

* WIP Adding Solaris SMF manifests for NUT

* Sanitize Solaris SVR4 packaging rules

* Sanitize Solaris packaging scripts some more

* Add configure options for Solaris packaging variants

* Sanitize Solaris packaging scripts some more - consider DESTDIR for installation root

* Turn solaris preproto.pl into a template so it uses proper (configured) user/group strings

* Makefile.am : ensure there is a DESTDIR set before packaging

* Makefile.am : use $(MAKE) $(AM_MAKEFLAGS) instead of explicit "make" (mostly in packaging recipe)

* makelocal.sh : commented and revised

* Solaris/Makefile.am : put generated SVR4 package into builddir (not srcdir that may be readonly) to match other OS recipes

* Makefile.am : ensure the DESTDIR is used for packaging purposes (when calling sub-makes)

* Solaris/pkginfo.in : ARCH is CPU_TYPE, not OS_NAME

* GitIgnore built Solaris/NUT*.local.gz product

* GitIgnore built systemd files

* GitIgnore _install_pkgprotodir

* Makefile.am : ensure only the custom DESTDIR is used for packaging purposes

* Makefile.am : convert the big packaging "if" into "case"; link steps with "&&"; retain DESTDIR if Solaris packaging fails; ensure the correct custom DESTDIR is absent before packaging (and after Solaris packaging)

* Solaris/Makefile.am : Revise recipe-names and comments for Solaris packaging variants

* Solaris/Makefile.am and *.xml.in : relocate SMF methods and manifests under NUT DATADIR to package compactly

* Solaris-SMF : svc-nut.in svc-nut-client.in : use @RUN_AS_*@ and @PIDPATH@ vars instead of hardcoding

* Solaris/Makefile.am : list helper scripts and installation scripts and data in variables and depend on them in packaging; chmod +x the scripts after copying over to proto area

* GitIgnore config.cache

* Remove Solaris/prepackage.py (unreferenced duplicate of precheck.py)

* Solaris/nut.in : sanitize the default init-script

* Solaris/Makefile.am : put init-scripts under NUT share (DATADIR) to package it compactly; copy to OS dirs in postinstall

* Makefile.am .gitignore etc. relocate successfully built package files to abs_top_builddir

* Change Aix/nut.init to a .in template

* svc-nut.in svc-nut-client.in : consider nut.conf if available

* Solaris/Makefile.am and SVR4 scripts : install augeas lenses as part of NUT package (in DATADIR at least)

* configure.ac : comment about sysconfdir for NUT

* Sanitize Aix/nut.init.in

* More standardization of Solaris initscripts and SMF methods; use LD_LIBRARY_PATH to prefer NUT provided libs in case of conflicts (facilitate bundling with third-party packages)

* Solaris/Makefile.am : add ability to "make check" something here, e.g. validate manifest XMLs

* Solaris SMF XML manifests : fix "dependent" definitions, and add dependencies on required config files

* configure.ac : fix a manually crafted "Checking for" into using AC_MSG routines

* Solaris SVR4 packaging should now take care of SMF service registration/teardown

* Solaris preremove.in postinstall.in : Usage of @datadir@ caused "${prefix}" strings to pop up - define the vars

* Solaris scripts : use lower-cased @datadir@ in templates processed by configure

* Solaris/preremove.in : fix FMRI pattern when removing package

* Solaris/postinstall.in : fix SMF manifest dir

* Solaris/postremove.in : fix verbose RM; wipe the /var/run/nut dir too

* Solaris/preremove.in : fix commands when removing package

* Solaris/postinstall.in : enable SMF services if configs are already available (esp. create nut-driver instances)

* Solaris/preremove.in : fix commands when removing package

* Solaris/postinstall.in : enable SMF services if configs are already available (esp. create nut-driver instances) - verbosity

* Solaris/nut-driver-enumerator.xml.in : use a unique dependency name (avoid conflict in nut-driver instances chain of deps)

* systemd and Solaris : fix up embedded ${prefix} in service files and SMF manifests after generation

* systemd/README : add recent authors

* Define a NUT_DATADIR and NUT_LIBEXECDIR with expanded path values to use in service manifests

* Solaris : packaged service addition/removal more verbose

* nut-driver-enumerator.xml.in nut-driver.xml.in : do not block startup of nut server

* nut.xml.in : do not block startup of nut server due to failed nut-driver-enumerator

* nut-driver-enumerator.sh.in : improve portability by using TAB char as is (not regex \t which gets misinterpreted by some tools)

* nut-driver-enumerator.sh.in : comment the caveats

* nut-driver-enumerator.sh.in : apcsmart is serial only

* nut-driver-enumerator.sh.in : By default, update wrapping of devices into services... but keep the door open to other uses of the script

* nut-driver-enumerator.sh.in : refactor a bit and add externally callable actions

* Introduce upsdrvsvcctl with semantics similar to upsdrvctl, but managing stop/start of SMF or systemd unit instances

* nut-driver-enumerator.sh.in : consider possible difference of device and service instance names

* nut-driver-enumerator.sh.in : refactor md5

* nut-driver-enumerator.xml.in : add REFRESH action and do not die on RESTART

* Mention nut-driver-enumerator and upsdrvsvcctl in (systemd/|Solaris/)README

* upsdrvsvcctl.in : updated comments

* upsdrvsvcctl.in : added a resync option

* Rename Solaris SMF services to match systemd patterns and ease life for sysadmins

* Add systemd nut.target to manage the bundle of NUT services

* config-notes.txt : document the systemd and SMF support in NUT

* nut.dict : update spellchecker

* Solaris/Makefile.am : support copying where attrs can not be preserved

* Solaris postinstall : report if services were not instantly enabled due to missing config files

* upsdrvsvcctl.in : reformat prettily

* nut-driver-enumerator.sh.in : wrap usage()

* nut-driver-enumerator.sh.in : added --list-services-for-devices

* nut-driver@.service.in : comment about aligning timeouts with ups.conf maxstartdelay

* nut.xml.in : Revise comments

* nut-driver-enumerator.sh.in : when amending service unit instance config for systemd, update the Description to state the NUT device section name

* nut-driver-enumerator.sh.in : support common NUT_CONFPATH envvar

* Add upsdrvsvcctl.txt manpage and references to upsdrvsvcctl in other docs

* upsdrvsvcctl.txt manpage : refer to service management system logs

* upsdrvsvcctl : support "list upsname" CLI action to help troubleshooting

* upsdrvsvcctl : add handling for "shutdown" command

* Docs about upsdrvsvcctl - clarify that it may not be preinstalled with non-SMF/non-systemd OS packages

* Pass spellcheck for upsdrvsvcctl doc updates

* Solaris packaging of nut-driver-enumerator.sh : deliver into libexecdir same as in Linux

* Move nut-driver-enumerator.sh.in and upsdrvsvcctl.in into scripts/upsdrvsvcctl to share on par between Linux and Solaris (for starters)

* Use @NUT_LIBEXECDIR@ for nut-driver-enumerator.sh

* Introduce nut-driver-enumerator.path.in for systemd

* nut-driver-enumerator.service.in : be part of nut.target, not common multi-user

* Systemd services : be PartOf=nut.target to propagate service stops

* postinstall.in : use NUT_DATADIR

* nut-monitor.xml.in : depend on nut-server (if locally running)

* nut.xml.in : fix path (use pre-eval-ed version)

* nut-driver-enumerator.sh.in : add a way to print out just an instance suffix name

* nut-driver-enumerator.sh.in : when printing full instance name, do not add stuff if the argument is already a full name

* nut-driver-enumerator.sh.in : implement --get-device-for-service

* nut-driver (systemd/SMF) : use "nut-driver-enumerator.sh --get-device-for-service" for current service instance name

* nut.xml.in : this service is transient

* upsdrvsvcctl.in : fix parameter passing

* upsdrvsvcctl.in : "clear" the SMF service state when stopping/starting, just in case it was failed

* nut-driver-enumerator.sh.in : restart upsd IFF the set of known-device mappings was changed

* Revise and relax some dependencies for Solaris SMF services

* nut-driver-enumerator.sh.in : info messages go to stderr; reply for request only goes to stdout

* nut-driver-enumerator.sh.in : complete the upslist_equals() method

* nut.xml.in : never fail on stop (if component services did not stop, it is their problem)

* Solaris preremove.in SMF : clear sevices before stopping them, just in case

* upsdrvsvcctl.in : post-process clearing of SMF service instances if any have failed

* nut.xml.in : never fail on stop (if component services did not stop, it is their problem)

* Solaris preremove.in SMF : remove nut before services it depends on

* main.c upsdrvctl.c : make debug messages a bit more useful

* Solaris preremove.in SMF : do not block stopping NUT driver services, but follow up with upsdrv(svc)ctl stop of everything

* Solaris preremove.in SMF : sleep after stopping drivers before removing their services

* Solaris preremove.in SMF : force-remove services of drivers

* nut-driver.xml.in : rename a dependency to avoid conflicts

* Solaris nut.xml.in : add a refresh action handler

* Solaris postinstall.in SMF : first use nut-driver-enumerator.sh.in to just register the mappings, no autostarts

* Solaris preremove.in SMF : stop drivers with common method (and use NUT_SBINDIR) before going one by one

* Solaris postinstall.in SMF : start the drivers via upsdrvsvcctl after registering (so the mapping is stable)

* Solaris postinstall.in preremove.in : NUT_SBINDIR => SBINDIR

* Add manpage for nut-driver-enumerator[8]

* Handle EXTRA_DIST of scripts/upsdrvsvcctl/ with their own Makefile

* nut-driver-enumerator.txt : change to be more like other page sources

* Spellcheck nut-driver-enumerator.txt

* Add scripts/upsdrvsvcctl/README

* Update gitignores

* List new manpages upsdrvsvcctl nut-driver-enumerator in index

* Add upsdrvsvcctl do scripts/Makefile.am SUBDIRS

* upsdrvsvcctl.in nut-driver-enumerator.sh.in : Add a way to show configs per device

* nut-driver-enumerator.sh.in : fix upsconf_getValue() to return success if key was found, or report an error if not

* nut-driver-enumerator.sh.in : expose upsconf_getValue() as --show-device-config-value

* nut-driver-enumerator.sh.in : NOTE on top about the choice of simplified shell

* nut-driver-enumerator.sh.in : in upsconf_getSection() stop after printing out the section contents

* nut-driver-enumerator.sh.in : refactor upsconf_getValue() to use upsconf_getSection()

* nut-driver-enumerator.sh.in : update comment in header

* nut-driver-enumerator.service.in : do not fail the systemd unit, it cannot restart

* Fix references for configure.in to point to configure.ac nowadays

* nut-driver-enumerator.sh.in : use fully-pathed SMF svccfg in all parts of code consistently

* nut-driver-enumerator.sh.in : comment about not-detecting reconfigurations of existing sections currently
Latest commit 8b75b03 Aug 14, 2018
Permalink
Failed to load latest commit information.
clients A few small fixes for cleaner codebase and compilations (#466) Aug 28, 2017
common Use target for drivers in Linux systemd (updated) and SMF instances f… Aug 14, 2018
conf Merge branch 'upssched-doc' Apr 6, 2017
data snmp-ups: Add support for Emerson Avocent PM3000 PDU Feb 16, 2018
docs Use target for drivers in Linux systemd (updated) and SMF instances f… Aug 14, 2018
drivers Merge branch 'fix_instcmd_fallback_logging' Mar 12, 2018
include Use target for drivers in Linux systemd (updated) and SMF instances f… Aug 14, 2018
lib Spellchecker : Fix or rephrase issues found by spellchecker, and upda… Jan 20, 2017
m4 m4/nut_check_asciidoc.m4 configure.ac : parametrize the required mini… Jun 26, 2017
scripts Use target for drivers in Linux systemd (updated) and SMF instances f… Aug 14, 2018
server Cppcheck improvements (#405) Apr 4, 2017
tests Improve configure script and recipe for CPPUNIT and C++11 detection Sep 25, 2017
tools nutscanner: get debug level early (for nutscan_init()) and restore op… Jul 31, 2018
.gitignore Use target for drivers in Linux systemd (updated) and SMF instances f… Aug 14, 2018
.travis.yml Change the Travis test-case for NO_PKG_CONFIG==true May 22, 2018
AUTHORS asem: additional documentation Jul 14, 2014
COPYING Merge from trunk ([[SVN:2777]] to HEAD). Jan 19, 2011
INSTALL.nut doc: Update installation instructions for FreeBSD Mar 13, 2018
LICENSE-GPL2 integrate NUT client Python support from David Goncalves. Jan 2, 2009
LICENSE-GPL3 integrate NUT client Python support from David Goncalves. Jan 2, 2009
MAINTAINERS oldmge-shut: final deprecation and removal Apr 4, 2017
Makefile.am Use target for drivers in Linux systemd (updated) and SMF instances f… Aug 14, 2018
NEWS Spellcheck : Fixed typo in Tore O*r*petveit's name Jan 27, 2017
README Use target for drivers in Linux systemd (updated) and SMF instances f… Aug 14, 2018
TODO Spellchecker : Fix or rephrase issues found by spellchecker, and upda… Jan 20, 2017
UPGRADING Spellchecker : Fix or rephrase issues found by spellchecker, and upda… Jan 20, 2017
autogen.sh autogen.sh: minor script fixup Nov 17, 2016
ci_build.sh Change the Travis test-case for NO_PKG_CONFIG==true May 22, 2018
compile Merge from trunk [[SVN:2848]] to [[SVN:3679]] to ssl-nss-port. Jul 18, 2012
configure.ac Use target for drivers in Linux systemd (updated) and SMF instances f… Aug 14, 2018
indent.sh Initial commit of indent.sh helper Jan 21, 2017

README

Network UPS Tools Overview
===========================

Description
-----------

Network UPS Tools is a collection of programs which provide a common
interface for monitoring and administering UPS, PDU and SCD hardware.
It uses a layered approach to connect all of the parts.

Drivers are provided for a wide assortment of equipment.  They
understand the specific language of each device and map it back to a
compatibility layer.  This means both an expensive high end UPS, a simple
"power strip" PDU, or any other power device can be handled transparently with
a uniform management interface.

This information is cached by the network server `upsd`, which then
answers queries from the clients.  upsd contains a number of access
control features to limit the abilities of the clients.  Only authorized
hosts may monitor or control your hardware if you wish.  Since the
notion of monitoring over the network is built into the software, you
can hang many systems off one large UPS, and they will all shut down
together. You can also use NUT to power on, off or cycle your data center
nodes, individually or globally through PDU outlets.

Clients such as `upsmon` check on the status of the hardware and do things
when necessary.  The most important task is shutting down the operating
system cleanly before the UPS runs out of power.  Other programs are
also provided to log information regularly, monitor status through your
web browser, and more.


Installing
----------

If you are installing these programs for the first time, go read the
<<_installation_instructions,installation instructions>>
to find out how to do that.  This document contains more information on what all
of this stuff does.


Upgrading
---------

When upgrading from an older version, always check the
<<Upgrading_notes,upgrading notes>> to see what may have
changed.  Compatibility issues and other changes will be listed there to ease
the process.


Configuring and using
---------------------

Once NUT is installed, refer to the
<<Configuration_notes,configuration notes>> for directions.


Documentation
-------------

This is just an overview of the software.  You should read the man pages,
included example configuration files, and auxiliary documentation for the parts
that you intend to use.


Network Information
-------------------

These programs are designed to share information over the network.  In
the examples below, `localhost` is used as the hostname.  This can also
be an IP address or a fully qualified domain name.  You can specify a
port number if your upsd process runs on another port.

In the case of the program `upsc`, to view the variables on the UPS called
sparky on the `upsd` server running on the local machine, you'd do this:

	/usr/local/ups/bin/upsc sparky@localhost

The default port number is 3493.  You can change this with
"configure --with-port" at compile-time.  To make a client talk to upsd
on a specific port, add it after the hostname with a colon, like this:

	/usr/local/ups/bin/upsc sparky@localhost:1234

This is handy when you have a mixed environment and some of the systems
are on different ports.

The general form for UPS identifiers is this:

	<upsname>[@<hostname>[:<port>]]

Keep this in mind when viewing the examples below.


Manifest
--------

This package is broken down into several categories:

- *drivers*	- These programs talk directly to your UPS hardware.
- *server*	- upsd serves data from the drivers to the network.
- *clients*	- They talk to upsd and do things with the status data.
- *cgi-bin*	- Special class of clients that you can use with your web server.
- *scripts*	- Contains various scripts, like the Perl and Python binding,
integration bits and applications. 

Drivers
-------

These programs provide support for specific UPS models.  They understand
the protocols and port specifications which define status information
and convert it to a form that upsd can understand.

To configure drivers, edit ups.conf.  For this example, we'll have a UPS
called "sparky" that uses the apcsmart driver and is connected to
`/dev/ttyS1`.  That's the second serial port on most Linux-based systems.
The entry in `ups.conf` looks like this:

	[sparky]
		driver = apcsmart
		port = /dev/ttyS1

To start and stop drivers, use upsdrvctl of upsdrvsvcctl (installed on
operating systems with a service management framework supported by NUT).
By default, it will start or stop every UPS in the config file:

	/usr/local/ups/sbin/upsdrvctl start
	/usr/local/ups/sbin/upsdrvctl stop

However, you can also just start or stop one by adding its name:

	/usr/local/ups/sbin/upsdrvctl start sparky
	/usr/local/ups/sbin/upsdrvctl stop sparky

On operating systems with a supported service management framework,
you might wrap your NUT drivers into individual services instances
with:

	/usr/local/ups/sbin/upsdrvsvcctl resync

and then manage those service instances with commands like:

	/usr/local/ups/sbin/upsdrvsvcctl start sparky
	/usr/local/ups/sbin/upsdrvsvcctl stop sparky

To find the driver name for your device, refer to the section below
called "HARDWARE SUPPORT TABLE".

Extra Settings
~~~~~~~~~~~~~~

Some drivers may require additional settings to properly communicate
with your hardware.  If it doesn't detect your UPS by default, check the
driver's man page or help (-h) to see which options are available.

For example, the usbhid-ups driver allows you to use USB serial numbers to
distinguish between units via the "serial" configuration option.  To use this
feature, just add another line to your ups.conf section for that UPS:

	[sparky]
		driver = usbhid-ups
		port = auto
		serial = 1234567890

Hardware Compatibility List
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The <<HCL,Hardware Compatibility List>> is available in the source directory
('nut-X.Y.Z/data/driver.list'), and is generally distributed with packages.
For example, it is available on Debian systems as:

	/usr/share/nut/driver.list

This table is also available link:http://www.networkupstools.org/stable-hcl.html[online].


If your driver has vanished, see the link:FAQ.html[FAQ] and
<<Upgrading_notes,Upgrading notes>>.

Generic Device Drivers
~~~~~~~~~~~~~~~~~~~~~~

NUT provides several generic drivers that support a variety of very similar models.

- The `genericups` driver supports many serial models that use the same basic
principle to communicate with the computer.  This is known as "contact
closure", and basically involves raising or lowering signals to indicate
power status.
+
This type of UPS tends to be cheaper, and only provides the very simplest
data about power and battery status.  Advanced features like battery
charge readings and such require a "smart" UPS and a driver which
supports it.
+
See the linkman:genericups[8] man page for more information.

- The `usbhid-ups` driver attempts to communicate with USB HID Power Device
Class (PDC) UPSes. These units generally implement the same basic protocol,
with minor variations in the exact set of supported attributes. This driver
also applies several correction factors when the UPS firmware reports values
with incorrect scale factors.
+
See the linkman:usbhid-ups[8] man page for more information.

- The `blazer_ser` and `blazer_usb` drivers supports the Megatec / Q1
protocol that is used in many brands (Blazer, Energy Sistem, Fenton
Technologies, Mustek and many others).
+
See the linkman:blazer[8] man page for more information.

- The `snmp-ups` driver handles various SNMP enabled devices, from many
different manufacturers. In SNMP terms, `snmp-ups` is a manager, that
monitors SNMP agents.
+
See the linkman:snmp-ups[8] man page for more information.

- The `powerman-pdu` is a bridge to the PowerMan daemon, thus handling all
PowerMan supported devices. The PowerMan project supports several serial
and networked PDU, along with Blade and IPMI enabled servers.
+
See the linkman:powerman-pdu[8] man page for more
information.

- The `apcupsd-ups` driver is a bridge to the Apcupsd daemon, thus handling
all Apcupsd supported devices. The Apcupsd project supports many serial,
USB and networked APC UPS.
+
See the linkman:apcupsd-ups[8] man page for more information.

UPS Shutdowns
~~~~~~~~~~~~~

upsdrvctl can also shut down (power down) all of your UPS hardware.

WARNING: if you play around with this command, expect your filesystems
to die.  Don't power off your computers unless they're ready for it:

	/usr/local/ups/sbin/upsdrvctl shutdown
	/usr/local/ups/sbin/upsdrvctl shutdown sparky

You should read the <<UPS_shutdown,Configuring automatic UPS shutdowns>>
chapter to learn more about when to use this feature.  If called at the wrong
time, you may cause data loss by turning off a system with a filesystem
mounted read-write.

Power distribution unit management
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

NUT also provides an advanced support for power distribution units.

You should read the <<outlet_management,NUT outlets management and PDU notes>>
chapter to learn more about when to use this feature. 

Network Server
--------------

`upsd` is responsible for passing data from the drivers to the client
programs via the network.  It should be run immediately after `upsdrvctl`
in your system's startup scripts.

`upsd` should be kept running whenever possible, as it is the only source
of status information for the monitoring clients like `upsmon`.


Monitoring client
-----------------

`upsmon` provides the essential feature that you expect to find in UPS
monitoring software: safe shutdowns when the power fails.

In the layered scheme of NUT software, it is a client.  It has this
separate section in the documentation since it is so important.

You configure it by telling it about UPSes that you want to monitor in
upsmon.conf.  Each UPS can be defined as one of two possible types:

Master
~~~~~~

This UPS supplies power to the system running `upsmon`, and this system is also
responsible for shutting it down when the battery is depleted.  This occurs
after any slave systems have disconnected safely.

If your UPS is plugged directly into a system's serial port, the `upsmon`
process on that system should define that UPS as a master.

For a typical home user, there's one computer connected to one UPS.
That means you run a driver, `upsd`, and `upsmon` in master mode.

Slave
~~~~~

This UPS may supply power to the system running `upsmon`, but this system can't
shut it down directly.

Use this mode when you run multiple computers on the same UPS.  Obviously, only
one can be connected to the serial port on the UPS, and that system is the
master.  Everything else is a slave.

For a typical home user, there's one computer connected to one UPS.
That means you run a driver, upsd, and upsmon in master mode.

Additional Information
~~~~~~~~~~~~~~~~~~~~~~

More information on configuring upsmon can be found in these places:

- The linkman:upsmon[8] man page
- <<BigServers,Typical setups for big servers>>
- <<UPS_shutdown,Configuring automatic UPS shutdowns>> chapter
- The stock `upsmon.conf` that comes with the package


Clients
-------

Clients talk to upsd over the network and do useful things with the data
from the drivers.  There are tools for command line access, and a few
special clients which can be run through your web server as CGI
programs.

For more details on specific programs, refer to their man pages.

upsc
~~~~

`upsc` is a simple client that will display the values of variables known
to `upsd` and your UPS drivers.  It will list every variable by default,
or just one if you specify an additional argument.  This can be useful
in shell scripts for monitoring something without writing your own
network code.

`upsc` is a quick way to find out if your driver(s) and upsd are working
together properly.  Just run `upsc <ups>` to see what's going on, i.e.:

	morbo:~$ upsc sparky@localhost
	ambient.humidity: 035.6
	ambient.humidity.alarm.maximum: NO,NO
	ambient.humidity.alarm.minimum: NO,NO
	ambient.temperature: 25.14
	...

If you are interested in writing a simple client that monitors `upsd`,
the source code for `upsc` is a good way to learn about using the
upsclient functions.

See the linkman:upsc[8] man page and
<<nut-names,NUT command and variable naming scheme>> for more information.

upslog
~~~~~~

`upslog` will write status information from `upsd` to a file at set
intervals.  You can use this to generate graphs or reports with other
programs such as `gnuplot`.

upsrw
~~~~~

`upsrw` allows you to display and change the read/write variables in your
UPS hardware.  Not all devices or drivers implement this, so this may
not have any effect on your system.

A driver that supports read/write variables will give results like this:

	$ upsrw sparky@localhost

	( many skipped )

	[ups.test.interval]
	Interval between self tests
	Type: ENUM
	Option: "1209600"
	Option: "604800" SELECTED
	Option: "0"

	( more skipped )

On the other hand, one that doesn't support them won't print anything:

	$ upsrw fenton@gearbox

	( nothing )

`upsrw` requires administrator powers to change settings in the hardware.
Refer to linkman:upsd.users[5] for information on defining
users in `upsd`.

upscmd
~~~~~~

Some UPS hardware and drivers support the notion of an instant command -
a feature such as starting a battery test, or powering off the load.
You can use upscmd to list or invoke instant commands if your
hardware/drivers support them.

Use the -l command to list them, like this:

	$ upscmd -l sparky@localhost
	Instant commands supported on UPS [sparky@localhost]:

	load.on - Turn on the load immediately
	test.panel.start - Start testing the UPS panel
	calibrate.start - Start run time calibration
	calibrate.stop - Stop run time calibration
	...

`upscmd` requires administrator powers to start instant commands.
To define users and passwords in `upsd`, see
linkman:upsd.users[5].


CGI Programs
------------

The CGI programs are clients that run through your web server.  They
allow you to see UPS status and perform certain administrative commands
from any web browser.  Javascript and cookies are not required.

These programs are not installed or compiled by default.  To compile
and install them, first run `configure --with-cgi`, then do `make` and
`make install`.  If you receive errors about "gd" during configure, go
get it and install it before continuing.

You can get the source here:

	http://www.libgd.org/

In the event that you need libpng or zlib in order to compile gd,
they can be found at these URLs:

	http://www.libpng.org/pub/png/pngcode.html

	http://www.gzip.org/zlib/


Access Restrictions
~~~~~~~~~~~~~~~~~~~

The CGI programs use hosts.conf to see if they are allowed to talk to a
host.  This keeps malicious visitors from creating queries from your web
server to random hosts on the Internet.

If you get error messages that say "Access to that host is not
authorized", you're probably missing an entry in your hosts.conf.

upsstats
~~~~~~~~

`upsstats` generates web pages from HTML templates, and plugs in status
information in the right places.  It looks like a distant relative of
APC's old Powerchute interface.  You can use it to monitor several
systems or just focus on one.

It also can generate IMG references to `upsimage`.

upsimage
~~~~~~~~

This is usually called by upsstats via IMG SRC tags to draw either the
utility or outgoing voltage, battery charge percent, or load percent.

upsset
~~~~~~

`upsset` provides several useful administration functions through a web
interface.  You can use `upsset` to kick off instant commands on your UPS
hardware like running a battery test.  You can also use it to change
variables in your UPS that accept user-specified values.

Essentially, `upsset` provides the functions of `upsrw` and `upscmd`, but
with a happy pointy-clicky interface.

`upsset` will not run until you convince it that you have secured your
system.  You *must* secure your CGI path so that random interlopers
can't run this program remotely.  See the `upsset.conf` file.  Once you
have secured the directory, you can enable this program in that
configuration file.  It is not active by default.


Version Numbering
-----------------

The version numbers work like this: if the middle number is odd, it's a
development tree, otherwise it is the stable tree.

The past stable trees were 1.0, 1.2, 1.4, 2.0, 2.2 and 2.4, with the
latest stable tree designated 2.6.  The development trees were 1.1, 1.3,
1.5, 2.1 and 2.3.  As of the 2.4 release, there is no real development
branch anymore since the code is available through a revision control
system (namely Subversion) and snapshots.

Major release jumps are mostly due to large changes to the features
list.  There have also been a number of architectural changes which
may not be noticeable to most users, but which can impact developers.


Backwards and Forwards Compatibility
------------------------------------

The old network code spans a range from about 0.41.1 when TCP support 
was introduced up to the recent 1.4 series.  It used variable names
like STATUS, UTILITY, and LOADPCT.  Many of these names go back to the
earliest prototypes of this software from 1997.  At that point there
was no way to know that so many drivers would come along and introduce 
so many new variables and commands.  The resulting mess grew out of
control over the years.

During the 1.3 development cycle, all variables and instant commands
were renamed to fit into a tree-like structure.  There are major groups,
like input, output and battery.  Members of those groups have been
arranged to make sense - input.voltage and output.voltage compliment
each other.  The old names were UTILITY and OUTVOLT.  The benefits in
this change are obvious.

The 1.4 clients can talk to either type of server, and can handle either
naming scheme.  1.4 servers have a compatibility mode where they can
answer queries for both names, even though the drivers are internally
using the new format.

When 1.4 clients talk to 1.4 or 2.0 (or more recent) servers, they will
use the new names.

Here's a table to make it easier to visualize:

[options="header"]
|=============================================
|                   4+| Server version
| *Client version*    | 1.0 | 1.2 | 1.4 | 2.0+
| 1.0                 | yes | yes | yes | no
| 1.2                 | yes | yes | yes | no
| 1.4                 | yes | yes | yes | yes
| 2.0+                | no  | no  | yes | yes
|=============================================

Version 2.0, and more recent, do not contain backwards compatibility for
the old protocol and variable/command names.  As a result, 2.0 clients can't 
talk to anything older than a 1.4 server.  If you ask a 2.0 client to 
fetch "STATUS", it will fail.  You'll have to ask for "ups.status" 
instead.

Authors of separate monitoring programs should have used the 1.4 series
to write support for the new variables and command names.  Client
software can easily support both versions as long as they like.  If upsd
returns 'ERR UNKNOWN-COMMAND' to a GET request, you need to use REQ.


Support / Help / etc.
---------------------

If you are in need of help, refer to the
<<Support_Request,Support instructions>> in the user manual.


Hacking / Development Info
--------------------------

Additional documentation can be found in:

- the linkdoc:developer-guide[Developer Guide],
- the linkdoc:packager-guide[Packager Guide].


Acknowledgements / Contributions
--------------------------------

The many people who have participated in creating and improving NUT are
listed in the user manual <<Acknowledgements,acknowledgements appendix>>.