1Network UPS Tools Overview
7Network UPS Tools is a collection of programs which provide a common
8interface for monitoring and administering UPS, PDU and SCD hardware.
9It uses a layered approach to connect all of the parts.
11Drivers are provided for a wide assortment of equipment. They
12understand the specific language of each device and map it back to a
13compatibility layer. This means both an expensive high end UPS, a simple
14"power strip" PDU, or any other power device can be handled transparently with
15a uniform management interface.
17This information is cached by the network server `upsd`, which then
18answers queries from the clients. upsd contains a number of access
19control features to limit the abilities of the clients. Only authorized
20hosts may monitor or control your hardware if you wish. Since the
21notion of monitoring over the network is built into the software, you
22can hang many systems off one large UPS, and they will all shut down
23together. You can also use NUT to power on, off or cycle your data center
24nodes, individually or globally through PDU outlets.
26Clients such as `upsmon` check on the status of the hardware and do things
27when necessary. The most important task is shutting down the operating
28system cleanly before the UPS runs out of power. Other programs are
29also provided to log information regularly, monitor status through your
30web browser, and more.
36If you are installing these programs for the first time, go read the
38to find out how to do that. This document contains more information on what all
39of this stuff does.
45When upgrading from an older version, always check the
46<<Upgrading_notes,upgrading notes>> to see what may have
47changed. Compatibility issues and other changes will be listed there to ease
51Configuring and using
54Once NUT is installed, refer to the
55<<Configuration_notes,configuration notes>> for directions.
61This is just an overview of the software. You should read the man pages,
62included example configuration files, and auxiliary documentation for the parts
63that you intend to use.
69These programs are designed to share information over the network. In
70the examples below, `localhost` is used as the hostname. This can also
71be an IP address or a fully qualified domain name. You can specify a
72port number if your upsd process runs on another port.
74In the case of the program `upsc`, to view the variables on the UPS called
75sparky on the `upsd` server running on the local machine, you'd do this:
77 /usr/local/ups/bin/upsc sparky@localhost
79The default port number is 3493. You can change this with
80"configure --with-port" at compile-time. To make a client talk to upsd
81on a specific port, add it after the hostname with a colon, like this:
83 /usr/local/ups/bin/upsc sparky@localhost:1234
85This is handy when you have a mixed environment and some of the systems
86are on different ports.
88The general form for UPS identifiers is this:
92Keep this in mind when viewing the examples below.
98This package is broken down into several categories:
100- *drivers* - These programs talk directly to your UPS hardware.
101- *server* - upsd serves data from the drivers to the network.
102- *clients* - They talk to upsd and do things with the status data.
103- *cgi-bin* - Special class of clients that you can use with your web server.
104- *scripts* - Contains various scripts, like the Perl and Python binding,
105integration bits and applications.
110These programs provide support for specific UPS models. They understand
111the protocols and port specifications which define status information
112and convert it to a form that upsd can understand.
114To configure drivers, edit ups.conf. For this example, we'll have a UPS
115called "sparky" that uses the apcsmart driver and is connected to
116`/dev/ttyS1`. That's the second serial port on most Linux-based systems.
117The entry in `ups.conf` looks like this:
120 driver = apcsmart
121 port = /dev/ttyS1
123To start and stop drivers, use upsdrvctl. By default, it will start or
124stop every UPS in the config file:
126 /usr/local/ups/sbin/upsdrvctl start
127 /usr/local/ups/sbin/upsdrvctl stop
129However, you can also just start or stop one by adding its name:
131 /usr/local/ups/sbin/upsdrvctl start sparky
132 /usr/local/ups/sbin/upsdrvctl stop sparky
134To find the driver name for your device, refer to the section below
135called "HARDWARE SUPPORT TABLE".
140Some drivers may require additional settings to properly communicate
141with your hardware. If it doesn't detect your UPS by default, check the
142driver's man page or help (-h) to see which options are available.
144For example, the usbhid-ups driver allows you to use USB serial numbers to
145distinguish between units via the "serial" configuration option. To use this
146feature, just add another line to your ups.conf section for that UPS:
149 driver = usbhid-ups
150 port = auto
151 serial = 1234567890
153Hardware Compatibility List
156The <<HCL,Hardware Compatibility List>> is available in the source directory
157('nut-X.Y.Z/data/driver.list'), and is generally distributed with packages.
158For example, it is available on Debian systems as:
162This table is also available link:http://www.networkupstools.org/stable-hcl.html[online].
165If your driver has vanished, see the link:FAQ.html[FAQ] and
168Generic Device Drivers
171NUT provides several generic drivers that support a variety of very similar models.
173- The `genericups` driver supports many serial models that use the same basic
174principle to communicate with the computer. This is known as "contact
175closure", and basically involves raising or lowering signals to indicate
178This type of UPS tends to be cheaper, and only provides the very simplest
179data about power and battery status. Advanced features like battery
180charge readings and such require a "smart" UPS and a driver which
183See the linkman:genericups man page for more information.
185- The `usbhid-ups` driver attempts to communicate with USB HID Power Device
186Class (PDC) UPSes. These units generally implement the same basic protocol,
187with minor variations in the exact set of supported attributes. This driver
188also applies several correction factors when the UPS firmware reports values
189with incorrect scale factors.
191See the linkman:usbhid-ups man page for more information.
193- The `blazer_ser` and `blazer_usb` drivers supports the Megatec / Q1
194protocol that is used in many brands (Blazer, Energy Sistem, Fenton
195Technologies, Mustek and many others).
197See the linkman:blazer man page for more information.
199- The `snmp-ups` driver handles various SNMP enabled devices, from many
200different manufacturers. In SNMP terms, `snmp-ups` is a manager, that
201monitors SNMP agents.
203See the linkman:snmp-ups man page for more information.
205- The `powerman-pdu` is a bridge to the PowerMan daemon, thus handling all
206PowerMan supported devices. The PowerMan project supports several serial
207and networked PDU, along with Blade and IPMI enabled servers.
209See the linkman:powerman-pdu man page for more
212- The `apcupsd-ups` driver is a bridge to the Apcupsd daemon, thus handling
213all Apcupsd supported devices. The Apcupsd project supports many serial,
214USB and networked APC UPS.
216See the linkman:apcupsd-ups man page for more information.
221upsdrvctl can also shut down (power down) all of your UPS hardware.
223WARNING: if you play around with this command, expect your filesystems
224to die. Don't power off your computers unless they're ready for it:
226 /usr/local/ups/sbin/upsdrvctl shutdown
227 /usr/local/ups/sbin/upsdrvctl shutdown sparky
229You should read the <<UPS_shutdown,Configuring automatic UPS shutdowns>>
230chapter to learn more about when to use this feature. If called at the wrong
231time, you may cause data loss by turning off a system with a filesystem
234Power distribution unit management
237NUT also provides an advanced support for power distribution units.
239You should read the <<Outlets_PDU_notes,Configuring automatic UPS shutdowns>>
240chapter to learn more about when to use this feature.
245`upsd` is responsible for passing data from the drivers to the client
246programs via the network. It should be run immediately after `upsdrvctl`
247in your system's startup scripts.
249`upsd` should be kept running whenever possible, as it is the only source
250of status information for the monitoring clients like `upsmon`.
256`upsmon` provides the essential feature that you expect to find in UPS
257monitoring software: safe shutdowns when the power fails.
259In the layered scheme of NUT software, it is a client. It has this
260separate section in the documentation since it is so important.
262You configure it by telling it about UPSes that you want to monitor in
263upsmon.conf. Each UPS can be defined as one of two possible types:
268This UPS supplies power to the system running `upsmon`, and this system is also
269responsible for shutting it down when the battery is depleted. This occurs
270after any slave systems have disconnected safely.
272If your UPS is plugged directly into a system's serial port, the `upsmon`
273process on that system should define that UPS as a master.
275For a typical home user, there's one computer connected to one UPS.
276That means you run a driver, `upsd`, and `upsmon` in master mode.
281This UPS may supply power to the system running `upsmon`, but this system can't
282shut it down directly.
284Use this mode when you run multiple computers on the same UPS. Obviously, only
285one can be connected to the serial port on the UPS, and that system is the
286master. Everything else is a slave.
288For a typical home user, there's one computer connected to one UPS.
289That means you run a driver, upsd, and upsmon in master mode.
294More information on configuring upsmon can be found in these places:
296- The linkman:upsmon man page
297- <<BigServers,Typical setups for big servers>>
298- <<UPS_shutdown,Configuring automatic UPS shutdowns>> chapter
299- The stock `upsmon.conf` that comes with the package
305Clients talk to upsd over the network and do useful things with the data
306from the drivers. There are tools for command line access, and a few
307special clients which can be run through your web server as CGI
310For more details on specific programs, refer to their man pages.
315`upsc` is a simple client that will display the values of variables known
316to `upsd` and your UPS drivers. It will list every variable by default,
317or just one if you specify an additional argument. This can be useful
318in shell scripts for monitoring something without writing your own
321`upsc` is a quick way to find out if your driver(s) and upsd are working
322together properly. Just run `upsc <ups>` to see what's going on, i.e.:
324 morbo:~$ upsc sparky@localhost
325 ambient.humidity: 035.6
326 ambient.humidity.alarm.maximum: NO,NO
327 ambient.humidity.alarm.minimum: NO,NO
328 ambient.temperature: 25.14
331If you are interested in writing a simple client that monitors `upsd`,
332the source code for `upsc` is a good way to learn about using the
335See the linkman:upsc man page and
336<<nut-names,NUT command and variable naming scheme>> for more information.
341`upslog` will write status information from `upsd` to a file at set
342intervals. You can use this to generate graphs or reports with other
343programs such as `gnuplot`.
348`upsrw` allows you to display and change the read/write variables in your
349UPS hardware. Not all devices or drivers implement this, so this may
350not have any effect on your system.
352A driver that supports read/write variables will give results like this:
354 $ upsrw sparky@localhost
356 ( many skipped )
359 Interval between self tests
360 Type: ENUM
361 Option: "1209600"
362 Option: "604800" SELECTED
363 Option: "0"
365 ( more skipped )
367On the other hand, one that doesn't support them won't print anything:
369 $ upsrw fenton@gearbox
371 ( nothing )
373`upsrw` requires administrator powers to change settings in the hardware.
374Refer to linkman:upsd.users for information on defining
375users in `upsd`.
380Some UPS hardware and drivers support the notion of an instant command -
381a feature such as starting a battery test, or powering off the load.
382You can use upscmd to list or invoke instant commands if your
383hardware/drivers support them.
385Use the -l command to list them, like this:
387 $ upscmd -l sparky@localhost
388 Instant commands supported on UPS [sparky@localhost]:
390 load.on - Turn on the load immediately
391 test.panel.start - Start testing the UPS panel
392 calibrate.start - Start run time calibration
393 calibrate.stop - Stop run time calibration
396`upscmd` requires administrator powers to start instant commands.
397To define users and passwords in `upsd`, see
404The CGI programs are clients that run through your web server. They
405allow you to see UPS status and perform certain administrative commands
408These programs are not installed or compiled by default. To compile
409and install them, first run `configure --with-cgi`, then do `make` and
410`make install`. If you receive errors about "gd" during configure, go
411get it and install it before continuing.
413You can get the source here:
417In the event that you need libpng or zlib in order to compile gd,
418they can be found at these URLs:
428The CGI programs use hosts.conf to see if they are allowed to talk to a
429host. This keeps malicious visitors from creating queries from your web
430server to random hosts on the Internet.
432If you get error messages that say "Access to that host is not
433authorized", you're probably missing an entry in your hosts.conf.
438`upsstats` generates web pages from HTML templates, and plugs in status
439information in the right places. It looks like a distant relative of
440APC's old Powerchute interface. You can use it to monitor several
441systems or just focus on one.
443It also can generate IMG references to `upsimage`.
448This is usually called by upsstats via IMG SRC tags to draw either the
449utility or outgoing voltage, battery charge percent, or load percent.
454`upsset` provides several useful administration functions through a web
455interface. You can use `upsset` to kick off instant commands on your UPS
456hardware like running a battery test. You can also use it to change
457variables in your UPS that accept user-specified values.
459Essentially, `upsset` provides the functions of `upsrw` and `upscmd`, but
460with a happy pointy-clicky interface.
462`upsset` will not run until you convince it that you have secured your
463system. You *must* secure your CGI path so that random interlopers
464can't run this program remotely. See the `upsset.conf` file. Once you
465have secured the directory, you can enable this program in that
466configuration file. It is not active by default.
472The version numbers work like this: if the middle number is odd, it's a
473development tree, otherwise it is the stable tree.
475The past stable trees were 1.0, 1.2, 1.4, 2.0, 2.2 and 2.4, with the
476latest stable tree designated 2.6. The development trees were 1.1, 1.3,
4771.5, 2.1 and 2.3. As of the 2.4 release, there is no real development
478branch anymore since the code is available through a revision control
479system (namely Subversion) and snapshots.
481Major release jumps are mostly due to large changes to the features
482list. There have also been a number of architectural changes which
483may not be noticeable to most users, but which can impact developers.
486Backwards and Forwards Compatibility
489The old network code spans a range from about 0.41.1 when TCP support
490was introduced up to the recent 1.4 series. It used variable names
491like STATUS, UTILITY, and LOADPCT. Many of these names go back to the
492earliest prototypes of this software from 1997. At that point there
493was no way to know that so many drivers would come along and introduce
494so many new variables and commands. The resulting mess grew out of
495control over the years.
497During the 1.3 development cycle, all variables and instant commands
498were renamed to fit into a tree-like structure. There are major groups,
499like input, output and battery. Members of those groups have been
500arranged to make sense - input.voltage and output.voltage compliment
501each other. The old names were UTILITY and OUTVOLT. The benefits in
502this change are obvious.
504The 1.4 clients can talk to either type of server, and can handle either
505naming scheme. 1.4 servers have a compatibility mode where they can
506answer queries for both names, even though the drivers are internally
507using the new format.
509When 1.4 clients talk to 1.4 or 2.0 (or more recent) servers, they will
510use the new names.
512Here's a table to make it easier to visualize:
516| 4+| Server version
517| *Client version* | 1.0 | 1.2 | 1.4 | 2.0+
518| 1.0 | yes | yes | yes | no
519| 1.2 | yes | yes | yes | no
520| 1.4 | yes | yes | yes | yes
521| 2.0+ | no | no | yes | yes
524Version 2.0, and more recent, do not contain backwards compatibility for
525the old protocol and variable/command names. As a result, 2.0 clients can't
526talk to anything older than a 1.4 server. If you ask a 2.0 client to
527fetch "STATUS", it will fail. You'll have to ask for "ups.status"
530Authors of separate monitoring programs should have used the 1.4 series
531to write support for the new variables and command names. Client
532software can easily support both versions as long as they like. If upsd
533returns 'ERR UNKNOWN-COMMAND' to a GET request, you need to use REQ.
536Support / Help / etc.
539If you are in need of help, refer to the
540<<Support_Request,Support instructions>> in the user manual.
543Hacking / Development Info
546Additional documentation can be found in:
548- the linkdoc:developer-guide[Developer Guide],
549- the linkdoc:packager-guide[Packager Guide].
552Acknowledgements / Contributions
555The many people who have participated in creating and improving NUT are
556listed in the user manual <<Acknowledgements,acknowledgements appendix>>.