Prev |  | Next

## 2. Network UPS Tools Overview

### 2.1. 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.

### 2.2. NUT and the ecosystem

NUT comes pre-packaged for many operating systems and embedded in storage, automation or virtualization appliances, and is also often shipped as the software companion by several UPS vendors. Of course, it is quite normal and supported to build your own — whether for an operating system which lacks it yet, or for an older distribution which lacks the current NUT version; whether to take advantage of new features or to troubleshoot a new UPS deployment with a debugger in hand.

Given its core position at the heart of your systems' lifecycle, we make it a point to have current NUT building and running anywhere, especially where older releases did work before (including "abandonware" like the servers and OSes from the turn of millennium): if those boxes are still alive and in need of power protection, they should be able to get it.

### Tip

If you like how the NUT project helps protect your systems from power outages, please consider sponsoring or at least "starring" it on GitHub at https://github.com/networkupstools/nut/ - these stars are among metrics which the larger potential sponsors consider when choosing how to help FOSS projects. Keeping the lights shining in such a large non-regression build matrix is a big undertaking!

See acknowledgements of organizations which help with NUT CI and other daily operations for an overview of the shared effort.

As a FOSS project, for over a quarter of a century we welcome contributions of both core code (drivers and other features), build recipes and other integration elements to make it work on your favourite system, documentation revisions to make it more accessible to newcomers, as well as hardware vendor cooperation with first-hand driver and protocol submissions, and just about anything else you can think of.

#### NUT Support Policy

The Network UPS Tools project is a community-made open-source effort, primarily made and maintained by people donating their spare time.

The support channels are likewise open, with preferred ones being the NUT project issue tracker on GitHub and the NUT Users mailing list, as detailed at https://networkupstools.org/support.html page.

Please keep in mind that any help is provided by community members just like yourself, as a best effort, and subject to their availability and experience. It is expected that you have read the Frequently Asked Questions, looked at the NUT wiki, and have a good grasp about the three-layer design and programs involved in a running deployment of NUT, for a discussion to be constructive and efficient.

Be patient, polite, and prepare to learn and provide information about your NUT deployment (version, configuration, OS…) and the device, to collect logs, and to answer any follow-up questions about your situation.

Finally, note that NUT is packaged and delivered by packaging into numerous operating systems, appliances and monitoring projects, and may be bundled with third-party GUI clients. It may be wise of end-users to identify such cases and ask for help on the most-relevant forum (or several, including the NUT support channels). It is important to highlight that the NUT project releases have for a long time been essentially snapshots of better-tested code, and we do not normally issue patches to "hot-fix" any older releases.

Any improvements of NUT itself are made in the current code base, same as any other feature development, so to receive desired fixes on your system (and/or to check that they do solve your particular issue), expect to be asked to build the recent development iteration from GitHub or work with your appliance vendor to get a software upgrade.

Over time, downstream OS packaging or other integrations which use NUT, may issue patches as new package revisions, or new baseline versions of NUT, according to their release policies. It is not uncommon for distributions, especially "stable" flavours, to be a few years behind upstream projects.

### 2.3. Installing

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

### 2.4. Upgrading

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

### 2.5. Configuring and using

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

### 2.6. 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.

### 2.7. 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.

### 2.8. 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.

### 2.9. 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 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 online.

If your driver has vanished, see the FAQ and 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 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 usbhid-ups(8) man page for more information.

- The `nutdrv_qx` driver supports the Megatec / Q1 protocol that is used in many brands (Blazer, Energy Sistem, Fenton Technologies, Mustek, Voltronic Power and many others).

  See the nutdrv_qx(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 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 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 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 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 NUT outlets management and PDU notes chapter to learn more about when to use this feature.

### 2.10. 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`.

### 2.11. 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: a "primary" or "secondary".

#### Primary

The monitored UPS possibly supplies power to this system running `upsmon`, but more importantly — this system can manage the UPS (typically, this instance of `upsmon` runs on the same system as the `upsd` and driver(s)): it is capable and responsible for shutting it down when the battery is depleted (or in another approach, lingering to deplete it or to tell the UPS to reboot its load after too much time has elapsed and this system is still alive — meaning wall power returned at a "wrong" moment).

The shutdown of this (primary) system itself, as well as eventually an UPS shutdown, occurs after any secondary systems ordered to shut down first have disconnected, or a critical urgency threshold was passed.

If your UPS is plugged directly into a system’s serial or USB port, the `upsmon` process on that system should define its relation to that UPS as a primary. It may be more complicated for higher-end UPSes with a shared network management capability (typically via SNMP) or several serial/USB ports that can be used simultaneously, and depends on what vendors and drivers implement. Setups with several competing primaries (for redundancy) are technically possible, if each one runs its own full stack of NUT, but results can be random (currently NUT does not provide a way to coordinate several entities managing the same device).

For a typical home user, there’s one computer connected to one UPS. That means you would run on the same computer the whole NUT stack — a suitable driver, `upsd`, and `upsmon` in primary mode.

#### Secondary

The monitored UPS may supply power to the system running `upsmon` (or alternatively, it may be a monitoring station with zero PSUs fed by that UPS), but more importantly, this system can’t manage the UPS — e.g. shut it down directly (through a locally running NUT driver).

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

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

#### Additional Information

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

- The upsmon(8) man page
- Typical setups for big servers
- Configuring automatic UPS shutdowns chapter
- The stock `upsmon.conf` that comes with the package

### 2.12. 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 upsc(8) man page and 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 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 upsd.users(5).

### 2.13. 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.zlib.net/

#### 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.

### 2.14. Version Numbering

The version numbers historically worked 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 such stable tree designated 2.6. The development trees were 1.1, 1.3, 1.5, 2.1 and 2.3. Since the 2.4 release, there is no real separate development branch anymore since the code is available through a revision control system (namely, Git — or actually Subversion back then), development happens in feature branches that are eventually merged into the main trunk, and its snapshots become published releases. As a result, subsequent versions (2.7 and 2.8) were released without regard for even/odd values of the minor version component.

Since 2.7 line of releases, sources are tracked in Git revision control system, with the project ecosystem being hosted on GitHub, and any code improvements or other contributions merged through common pull request approach and custom NUT CI testing on multiple platforms.

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.

Since NUT v2.8.2 or so, development iterations have additional version components, to account for the amount of commits on the main branch (`master`) since the last known Git tag, and amount of commits on the developed feature branch that are unique to it compared to main branch. This allows for a reasonably growing version of stable baseline and local development, so that experimental packages can be installed as upgrades (or well-exposed downgrades).

While the NUT releases retain the semantic versioning three-component standard, interim builds (trunk snapshots and development branches) can expose a much more complex structure with the amount of commits in the trunk since last release, and amount of commits on the branch unique to it (not in the trunk). Additional data may include overall amount of commits in the current build since last release, and the git commit has identifier of the built code base.

More details can be seen in `docs/nut-versioning.adoc` file in the NUT source code base.

### 2.15. Backwards and Forwards Compatibility

The network protocol for the current version of NUT should be backwards-compatible all the way back to version 1.4. A newer client should fail gracefully when querying an older server.

If you need more details about cross-compatibility of older NUT releases (1.x vs. 2.x), please see the Project history chapter.

### 2.16. Support / Help / etc.

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

### 2.17. Hacking / Development Info

Additional documentation can be found in:

- the Developer Guide,
- the Packager Guide.

### 2.18. Acknowledgements / Contributions

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

We would like to highlight some organizations which provide continuous support to the NUT project (and many other FOSS projects) on technological and organizational sides, such as helping keep the donations transparent, NUT CI farm afloat, and public resources visible. Thanks for keeping the clocks ticking, day and night:

| The "NetworkUPSTools" organization on GitHub arranges a lot of things, including source code hosting for NUT itself and several related projects, team management, projects, issue and pull request discussions, sponsorship, nut-website rendering and hosting, some automated actions, and more…
| The Jenkins CI project and its huge plugin ecosystem provides the technological foundation for the largest island of the self-hosted NUT CI farm. There is a fair amount of cross-pollination between the upstream project and community, and the development done originally for the NUT CI farm. See more at Jenkins is the way to build multi-platform NUT article.
| The DigitalOcean droplets allow us to host NUT CI farm Jenkins controller and the build agents for multiple operating systems. They are essentially virtual machines where the multi-platform NUT CI farm with a jenkins-dynamatrix setup runs to arrange builds in numerous operating environments and a lot of toolkit versions and implementations. Some workers running on NUT community members' machines can also dial in to provide an example of their favourite platforms. Literally hundreds of NUT builds run for each iteration, to make sure NUT can always build and work everywhere. This allows us to ensure that NUT remains portable across two decades' worth of operating systems, compilers, script interpreters, tools and third-party dependencies.
| The several variants of OBS NUT packaging project hosted on the openSUSE Build Service (OBS) allow us to propose reference packaging recipes for a number of Linux distributions, as well as to test NUT PR and stable branch iterations on those across several CPU architectures not available elsewhere.
| The CircleCI NUT pipeline allows us to test NUT CI builds on MacOS.
| The AppVeyor NUT pipeline allows us to test NUT CI builds on Windows (and publish preview tarballs with binaries).
| Fosshost used to provide virtual machines where the multi-platform NUT CI farm ran, following up from a take on multi-platform builds with Travis CI while it was free for FOSS projects. In turn, DigitalOcean helped us move on from there after the Fosshost project went defunct.
| Gandi.Net ultimately took up the costs of NUT DNS hosting, which they have provided commercially for years before that.
| https://opencollective.com/networkupstools allows us to arrange monetary donations and spending, with public transparency of everything that happens.

Prev |  | Next
| Home |