xref: /nut/
NameDateSize

..16-Mar-201612 KiB

.gitignore10-Mar-2014420

AUTHORS15-Jul-20144.8 KiB

autogen.sh10-Mar-20141.2 KiB

clients/12-Oct-20154 KiB

common/30-Nov-20154 KiB

compile10-Mar-20143.7 KiB

conf/09-Apr-20154 KiB

configure.ac17-Apr-201538.7 KiB

COPYING10-Mar-2014578

data/16-Nov-20154 KiB

docs/16-Nov-20154 KiB

drivers/30-Nov-20154 KiB

include/30-Nov-20154 KiB

INSTALL.nut07-Aug-20159.8 KiB

lib/10-Mar-20144 KiB

LICENSE-GPL210-Mar-201417.6 KiB

LICENSE-GPL310-Mar-201434.2 KiB

m4/10-Aug-20154 KiB

MAINTAINERS10-Mar-20141.7 KiB

Makefile.am10-Sep-20155.1 KiB

NEWS17-Apr-201564.7 KiB

README10-Mar-201418.7 KiB

scripts/14-Jul-20144 KiB

server/30-Nov-20154 KiB

tests/10-Mar-20144 KiB

TODO10-Mar-20144.5 KiB

tools/24-Jun-20154 KiB

UPGRADING17-Apr-201511.1 KiB

README

1Network UPS Tools Overview
2===========================
3
4Description
5-----------
6
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.
10
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.
16
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.
25
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.
31
32
33Installing
34----------
35
36If you are installing these programs for the first time, go read the
37<<_installation_instructions,installation instructions>>
38to find out how to do that.  This document contains more information on what all
39of this stuff does.
40
41
42Upgrading
43---------
44
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
48the process.
49
50
51Configuring and using
52---------------------
53
54Once NUT is installed, refer to the
55<<Configuration_notes,configuration notes>> for directions.
56
57
58Documentation
59-------------
60
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.
64
65
66Network Information
67-------------------
68
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.
73
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:
76
77	/usr/local/ups/bin/upsc sparky@localhost
78
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:
82
83	/usr/local/ups/bin/upsc sparky@localhost:1234
84
85This is handy when you have a mixed environment and some of the systems
86are on different ports.
87
88The general form for UPS identifiers is this:
89
90	<upsname>[@<hostname>[:<port>]]
91
92Keep this in mind when viewing the examples below.
93
94
95Manifest
96--------
97
98This package is broken down into several categories:
99
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. 
106
107Drivers
108-------
109
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.
113
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:
118
119	[sparky]
120		driver = apcsmart
121		port = /dev/ttyS1
122
123To start and stop drivers, use upsdrvctl.  By default, it will start or
124stop every UPS in the config file:
125
126	/usr/local/ups/sbin/upsdrvctl start
127	/usr/local/ups/sbin/upsdrvctl stop
128
129However, you can also just start or stop one by adding its name:
130
131	/usr/local/ups/sbin/upsdrvctl start sparky
132	/usr/local/ups/sbin/upsdrvctl stop sparky
133
134To find the driver name for your device, refer to the section below
135called "HARDWARE SUPPORT TABLE".
136
137Extra Settings
138~~~~~~~~~~~~~~
139
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.
143
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:
147
148	[sparky]
149		driver = usbhid-ups
150		port = auto
151		serial = 1234567890
152
153Hardware Compatibility List
154~~~~~~~~~~~~~~~~~~~~~~~~~~~
155
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:
159
160	/usr/share/nut/driver.list
161
162This table is also available link:http://www.networkupstools.org/stable-hcl.html[online].
163
164
165If your driver has vanished, see the link:FAQ.html[FAQ] and
166<<Upgrading_notes,Upgrading notes>>.
167
168Generic Device Drivers
169~~~~~~~~~~~~~~~~~~~~~~
170
171NUT provides several generic drivers that support a variety of very similar models.
172
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
176power status.
177+
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
181supports it.
182+
183See the linkman:genericups[8] man page for more information.
184
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.
190+
191See the linkman:usbhid-ups[8] man page for more information.
192
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).
196+
197See the linkman:blazer[8] man page for more information.
198
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.
202+
203See the linkman:snmp-ups[8] man page for more information.
204
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.
208+
209See the linkman:powerman-pdu[8] man page for more
210information.
211
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.
215+
216See the linkman:apcupsd-ups[8] man page for more information.
217
218UPS Shutdowns
219~~~~~~~~~~~~~
220
221upsdrvctl can also shut down (power down) all of your UPS hardware.
222
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:
225
226	/usr/local/ups/sbin/upsdrvctl shutdown
227	/usr/local/ups/sbin/upsdrvctl shutdown sparky
228
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
232mounted read-write.
233
234Power distribution unit management
235~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
236
237NUT also provides an advanced support for power distribution units.
238
239You should read the <<Outlets_PDU_notes,Configuring automatic UPS shutdowns>>
240chapter to learn more about when to use this feature. 
241
242Network Server
243--------------
244
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.
248
249`upsd` should be kept running whenever possible, as it is the only source
250of status information for the monitoring clients like `upsmon`.
251
252
253Monitoring client
254-----------------
255
256`upsmon` provides the essential feature that you expect to find in UPS
257monitoring software: safe shutdowns when the power fails.
258
259In the layered scheme of NUT software, it is a client.  It has this
260separate section in the documentation since it is so important.
261
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:
264
265Master
266~~~~~~
267
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.
271
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.
274
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.
277
278Slave
279~~~~~
280
281This UPS may supply power to the system running `upsmon`, but this system can't
282shut it down directly.
283
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.
287
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.
290
291Additional Information
292~~~~~~~~~~~~~~~~~~~~~~
293
294More information on configuring upsmon can be found in these places:
295
296- The linkman:upsmon[8] 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
300
301
302Clients
303-------
304
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
308programs.
309
310For more details on specific programs, refer to their man pages.
311
312upsc
313~~~~
314
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
319network code.
320
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.:
323
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
329	...
330
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
333upsclient functions.
334
335See the linkman:upsc[8] man page and
336<<nut-names,NUT command and variable naming scheme>> for more information.
337
338upslog
339~~~~~~
340
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`.
344
345upsrw
346~~~~~
347
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.
351
352A driver that supports read/write variables will give results like this:
353
354	$ upsrw sparky@localhost
355
356	( many skipped )
357
358	[ups.test.interval]
359	Interval between self tests
360	Type: ENUM
361	Option: "1209600"
362	Option: "604800" SELECTED
363	Option: "0"
364
365	( more skipped )
366
367On the other hand, one that doesn't support them won't print anything:
368
369	$ upsrw fenton@gearbox
370
371	( nothing )
372
373`upsrw` requires administrator powers to change settings in the hardware.
374Refer to linkman:upsd.users[5] for information on defining
375users in `upsd`.
376
377upscmd
378~~~~~~
379
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.
384
385Use the -l command to list them, like this:
386
387	$ upscmd -l sparky@localhost
388	Instant commands supported on UPS [sparky@localhost]:
389
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
394	...
395
396`upscmd` requires administrator powers to start instant commands.
397To define users and passwords in `upsd`, see
398linkman:upsd.users[5].
399
400
401CGI Programs
402------------
403
404The CGI programs are clients that run through your web server.  They
405allow you to see UPS status and perform certain administrative commands
406from any web browser.  Javascript and cookies are not required.
407
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.
412
413You can get the source here:
414
415	http://www.libgd.org/
416
417In the event that you need libpng or zlib in order to compile gd,
418they can be found at these URLs:
419
420	http://www.libpng.org/pub/png/pngcode.html
421
422	http://www.gzip.org/zlib/
423
424
425Access Restrictions
426~~~~~~~~~~~~~~~~~~~
427
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.
431
432If you get error messages that say "Access to that host is not
433authorized", you're probably missing an entry in your hosts.conf.
434
435upsstats
436~~~~~~~~
437
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.
442
443It also can generate IMG references to `upsimage`.
444
445upsimage
446~~~~~~~~
447
448This is usually called by upsstats via IMG SRC tags to draw either the
449utility or outgoing voltage, battery charge percent, or load percent.
450
451upsset
452~~~~~~
453
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.
458
459Essentially, `upsset` provides the functions of `upsrw` and `upscmd`, but
460with a happy pointy-clicky interface.
461
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.
467
468
469Version Numbering
470-----------------
471
472The version numbers work like this: if the middle number is odd, it's a
473development tree, otherwise it is the stable tree.
474
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.
480
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.
484
485
486Backwards and Forwards Compatibility
487------------------------------------
488
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.
496
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.
503
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.
508
509When 1.4 clients talk to 1.4 or 2.0 (or more recent) servers, they will
510use the new names.
511
512Here's a table to make it easier to visualize:
513
514[options="header"]
515|=============================================
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
522|=============================================
523
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" 
528instead.
529
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.
534
535
536Support / Help / etc.
537---------------------
538
539If you are in need of help, refer to the
540<<Support_Request,Support instructions>> in the user manual.
541
542
543Hacking / Development Info
544--------------------------
545
546Additional documentation can be found in:
547
548- the linkdoc:developer-guide[Developer Guide],
549- the linkdoc:packager-guide[Packager Guide].
550
551
552Acknowledgements / Contributions
553--------------------------------
554
555The many people who have participated in creating and improving NUT are
556listed in the user manual <<Acknowledgements,acknowledgements appendix>>.
557