lagertonne/nut
1
0
Fork 0
Code Issues Pull requests Projects Releases 2 Wiki Activity

Imported Upstream version 2.6.0

Browse source
This commit is contained in:
arnaud.quette@free.fr 2011-01-26 10:35:08 +01:00
parent 26fb71b504
commit 459aaf9392
510 changed files with 40508 additions and 18859 deletions
Download patch file Download diff file Expand all files Collapse all files

822
docs/FAQ
View file

@ -1,822 +0,0 @@
Desc: Frequently Asked Questions
File: FAQ
Date: 20 January 2006
Auth: Russell Kroll <rkroll@exploits.org>
Arnaud Quette <aquette.dev@gmail.com>
-----------------------------------------------------------------------------
Q: I just upgraded, and ...
A: You have read UPGRADING in the base directory of the distribution,
right? If not, go read it now, then come back to this file if your
question wasn't answered in there.
-----------------------------------------------------------------------------
Q: upsstats says "Error: can't open template file (upsstats.html)".
How do I fix this?
A: Go into your configuration path (/usr/local/ups/etc by default) and
copy the sample template files over to their real names. The sample
template files are installed with 'make install-cgi-conf' and can
also be found inside the source distribution in the conf directory.
-----------------------------------------------------------------------------
Q: upsmon fails the login and says "username required" now.
A: Go read the UPGRADING file again.
-----------------------------------------------------------------------------
Q: My 1.4 CGI programs won't talk to my 2.0 upsd. What should I do?
A: Upgrade the CGI programs to 2.0. While 1.4 was intended as a
compatibility tree that used the new protocol by default, the CGI
programs were not upgraded at the same time. The 1.4 versions
still use the old REQ protocol, and your 2.0 upsd expects GET.
-----------------------------------------------------------------------------
Q: I just upgraded from 1.2 and upsmon now fails to start, saying
"Fatal error: insufficient power configured!". Why?
A: You didn't read the top of the error, where upsmon says that it
ignored the invalid MONITOR line because UPS directives now require
a UPS name. It also means you didn't see the same warning in
UPGRADING.
At least you saw this in the FAQ before asking the list.
-----------------------------------------------------------------------------
Q: My UPS driver now says it's "broken", and won't start. What now?
Q: My favorite UPS driver disappeared after an upgrade. What now?
A: Drivers are occasionally removed from the tree if they are no longer
receiving maintenance, or sometimes renamed to better reflect their
hardware support scope or replaced by a more generic driver.
There have been several architectural changes to the driver code
in recent times, and drivers which were not converted by someone
are eventually dropped.
This is called progress. We do this in order to avoid a situation
where someone believes that a driver is being maintained when it is
actually rotting slowly in the tree. It also keeps the tree free of
old compatibility hacks for code that nobody actually uses anyway.
To get a driver back into current releases, you need to convert it
yourself or get someone to do it for you. This is not difficult.
The hardest part of any driver is decoding the protocol, and that's
already been done in the old version.
-----------------------------------------------------------------------------
Q: I just upgraded and now I can't talk to older versions.
A: Version 2.0 can't communicate with anything before 1.4 due to the
protocol changes. Version 1.4 can communicate with both 2.0 and
most older versions since it was a transitional release and has
compatibility code for both protocols.
-----------------------------------------------------------------------------
Q: My UPS driver program won't work. I'm starting it as root, and root
owns the device, so what's the problem?
A: The drivers drop root privileges long before the serial port is
opened. You'll need to change the permissions on that port so that
their new user id can access it. Normally this is "nobody", but it
may be changed at compile-time by using configure --with-user.
Read the error message. If you have a permissions mismatch, then
you'll see something like this:
Network UPS Tools - APC Smart protocol driver 0.60 (1.1.7)
This program is currently running as youruid (UID 1234)
/dev/ttyS2 is owned by user root (UID 0), mode 0600
Change the port name, or fix the permissions or ownership
of /dev/ttyS2 and try again.
Unable to open /dev/ttyS2: Permission denied
Now is a good time to point out that using "nobody" is a bad idea,
since it's a hack for NFS access. You should create a new role
account (perhaps called "ups" or "nut"), and use that instead.
Also, scroll down to the "security domains" question to see an
even better way of restricting privileged operations. Neither the
drivers nor upsd ever need root powers, and that answer tells you
how to make it work.
A: You can also specify a user with "user=" in the global part of
ups.conf. Just define it before any of your [sections]:
user = nut
[myups]
driver = mge-shut
port = /dev/ttyS0
-----------------------------------------------------------------------------
Q: upsc, upsstats, and the other clients say "access denied". The device
communication port (serial, USB or network) permissions are fine, so what
gives?
A: In this case, "access denied" means the access to upsd, not the device
communication port. You're being denied since the system has no
permission to speak to upsd according to the access controls.
There can be various reasons. To fix it, check:
- the LISTEN directive in upsd.conf. It should allow your local or remote
access method,
- your firewall rules. Port 3493/tcp must be opened to incoming connexions,
- your tcp-wrappers configuration (hosts.allow and hosts.deny).
Refer to the upsd(8) and upsd.conf(5) manpages for more information.
-----------------------------------------------------------------------------
Q: I have an APC Smart-UPS connected with a grey APC cable and it won't
work. The Back-UPS type in the genericups driver works but then I
don't get to use all the nifty features in there. Why doesn't the
right driver work?
A: The problem lies in your choice of cable. APC's grey cables
generally only do "dumb" signalling - very basic yes/no info about
the battery and line status. While that is sufficient to detect a
low battery condition while on battery, you miss out on all the
goodies that you paid for.
Note that the 940-0095B happens to be a grey cable, but it is actually
a dual mode cable and can be used in smart mode. If you have
this cable, you need to edit your ups.conf to look like this:
[myups]
driver = apcsmart
port = /dev/whatever
cable = 940-0095B
All other grey cables from APC are assumed to be "dumb".
If your grey cable isn't the 940-0095B, the solution is to dump that
cable and find one that supports APC's "smart" signalling. Typically
these come with the UPS and are black. If your smart cable has
wandered off, one can be built rather easily with some connectors and
cable - there's no fancy wiring or resistors.
See this URL for a handy diagram:
http://random.networkupstools.org/cables/940-0024C.jpg
There is also a text version of that diagram in the docs/cables
directory of the NUT source distribution. Either one should allow
you to build a good clone of APC's 940-0024C cable.
There are simpler solutions involving 3 wires that work just fine
too, but Powerchute won't find the loopback DTR-DCD and RTS-CTS and
will be annoyed. If you don't ever plan to use Powerchute, 3 wires
(RxD, TxD, GND) are sufficient.
It should also be noted that the genericups driver has no way to
detect the UPS, so it will fire up quite happily if it can open the
serial port. Merely having it start up is not necessarily an
indication of success. You should start it and then check the
status with upsc or similar to be sure that it's reading the
hardware properly.
-----------------------------------------------------------------------------
Q: Why does configure fail to find gd?
A: Recent versions of gd should be detected automatically through the
gdlib-config script. Note that gd 2.0.5 through 2.0.7 have an
unusable script, so upgrade to the newest version if you have one
of those installed.
If you're stuck with an older version of gd, you can use it if you
specify the flags manually. Look in gd's Makefile for "LIBS=",
then use that value when you call configure:
./configure --with-gd-libs="<whatever>" --with-cgi
If you don't have gd's Makefile available for some reason, you're
in for a lot of trial and error.
-----------------------------------------------------------------------------
Q: Why PNG? You used to generate GIF bars with upsimage back in 1998
or 1999...
A: http://www.burnallgifs.org/
-----------------------------------------------------------------------------
Q: Why doesn't upsd implement the functionality of upsmon? I have to
run THREE programs to monitor my UPS!
A: I try to follow the "tool for the job" philosophy. It may mean
more programs running, but the flexibility you get is usually
worth it.
Yes, the machine with the UPS attached will generally have 3
processes (driver, upsd, upsmon) running, but this design allows a
much bigger setup. Imagine a data room with a bunch of machines
all drawing power from the same UPS. The rest of them just run
upsmon.
Besides, if upsmon were rolled into upsd, upsd would get even
bigger than it is now. You'd have one less process, but the
RAM consumption would be pretty close to now.
See data-room.txt for more configuration ideas and explanations.
A: If this really bothers you, roll up your sleeves and use the
sockdebug code to write a "upsmon" type program that sits on top of
the state sockets. It won't work over the network, but it means
you don't need upsd. It also means only one host can monitor the
UPS.
This is also a good option to consider if you can't use networked
monitoring code for security or safety reasons.
See ideas.txt for more on this and other related topics.
-----------------------------------------------------------------------------
Q: Why isn't upssched part of upsmon?
A: Most users will never have any reason to use upssched. It's
complicated, and getting it right for your situation can be tricky.
Having it live in a separate program saves resources and lets most
people avoid it completely.
-----------------------------------------------------------------------------
Q: Why doesn't upsmon send a SIGPWR signal to init so it can deal with
power events?
A: New versions of the init man page taken from the sysvinit package
are saying that usage of SIGPWR is discouraged, since /dev/initctl
control channel is the preferred way of communication.
A: The name of the game is portability. Not everyone's init handles
that kind of signalling gracefully. What's more, some admins
might want to do things differently even if they have that kind of
init running.
So, to be compatible, upsmon just invokes a shell command. If you
want to use init's SIGPWR stuff, just put the right "kill" line in
a shell script and make upsmon call it. Everyone wins.
-----------------------------------------------------------------------------
Q: Why can't upsset read my upsset.passwd file?
A: You have an old version of upsset installed, since the current
version doesn't use that file. Install a new version and then try
it again.
Be sure to secure your CGI directory as instructed in the
upsset.conf.
-----------------------------------------------------------------------------
Q: Why won't bestups talk to my Best Fortress UPS?
A: There are at least two different protocols being used for hardware
with very similar names. The bestups driver tends to support the
units built around the newer "PhoenixTec" protocol.
Previous releases of this software included a driver called
bestfortress which supported the older Best hardware. See the
earlier entries about updating old drivers which have been removed
from the tree.
-----------------------------------------------------------------------------
Q: What's this about "data stale"?
A: It means your UPS driver hasn't updated things in a little while.
upsd refuses to serve up data that isn't fresh, so you get the
errors about staleness.
If this happens to you, make sure your driver is still running.
Also look at the syslog. Sometimes the driver loses the connection
to the UPS, and that will also make the data go stale.
Note: some very slow machines have trouble keeping up with the
serial ports during periods of extreme load. My old 486 used to
flip between "stale" and "OK" while running backups.
If this happens a lot, you might consider cranking up DEADTIME
in the upsmon.conf to suppress some of the warnings for shorter
intervals. Use caution when adjusting this number, since it
directly affects how long you run on battery without knowing
what's going on with the UPS.
Note: some drivers occasionally need more time to update than the
default value of MAXAGE (in upsd.conf) allows. As a result, they
are temporarily marked stale even though everything is fine. This
can happen with MGE Ellipse equipment - see the mge-shut man page.
In such cases, you can raise the value of MAXAGE to avoid these
warnings; try a value like 25 or 30.
-----------------------------------------------------------------------------
Q: Why do the client programs say "Driver not connected" when I try
to run them?
A: This means that upsd can't connect to the driver for some reason.
Your ups.conf entry might be wrong, or the driver might not be
running. Maybe your state path is not configured properly.
Check your syslog. upsd will complain regularly if it can't
connect to a driver, and it should say why it can't connect.
Note: if you jumped in with both feet and didn't follow the INSTALL
document, you probably started upsd by itself. You have to run
'upsdrvctl start' to start the drivers after configuring ups.conf.
-----------------------------------------------------------------------------
Q: Everything works perfectly during the shutdown, and the UPS comes
back on, but my system stays off. What's happening?
A: Assuming you don't have the problem in the next question, then you
probably have an ATX motherboard, have APM or ACPI enabled in your
kernel (assuming Linux here), and are reaching the 'halt' at the
bottom of your shutdown scripts.
Your machine obeys and shuts down, and stays down, since it
remembers the 'last state' when the UPS restarts.
One solution is to change your shutdown scripts so you never reach
that point. You *want* the system to die without reaching the
part where the kernel tells it to shut down. A possible script
might look like this:
# other shutdown stuff here (mount -o remount,ro ...)
if (test -f /etc/killpower)
then
/usr/local/ups/bin/upsdrvctl shutdown
sleep 600 # this should never return
# uh oh, we never got shut down! (power race?)
reboot
fi
halt -p
The other solution is to change your BIOS setting to "always power
on" instead of "last state", assuming that's possible.
-----------------------------------------------------------------------------
Q: My system has an ATX power supply. It will power off just fine, but
it doesn't turn back on. What can I do to fix this?
A: This depends on how clueful your motherboard manufacturer is, and
isn't a matter of the OS. You have to do one of the following
things depending on what's supported:
- Set a jumper on the motherboard that means "return after outage"
- Set something in the BIOS that says "power up after power failure"
- Try using something (like a capacitor) across the power button
to "push" it for you - this might not work if it needs a delay
- Hack the cable between the power supply and the motherboard to fool
it into powering up whenever line power is present
- Teach a monkey to watch the machine and press the power button
when the outage is over.
This might work, but it creates high produce bills.
If you can't use one of the first two options, give the board to
an enemy. Let them worry about it.
-----------------------------------------------------------------------------
Q: My PowerMac G4 won't power back up by itself (into Linux) after the
UPS shuts down. What can I do about this?
A: This is about the same situation as the ATX question above, only
worse. Earlier Macs apparently supported a hack where you could
cat some magic characters at /dev/adb to enable "server mode".
This would instruct the system to reboot while unattended.
From Usenet post <6boftzxz51.fsf@ecc-office.sp.cs.cmu.edu>:
# Send packet over the ADB bus to the PowerMac CUDA chip
# telling it to reboot automatically when power is restored
# after a power failure.
cat /etc/local/autoboot.adb > /dev/adb
autoboot.adb contains these three bytes (in hex): 01 13 01
Unfortunately, the hardware has evolved and there is no good
equivalent for this hack on today's systems.
If you find out how to do this, please send me some mail, since
this affects one of my systems and my stop-gap solution is getting
cranky.
Note: this question has been in the FAQ for over a year and
there's still no answer. Let me guess: everyone who runs a server
on Mac hardware has a team of trained monkeys, and feeds them
by growing bananas in the tropical environment formed by waste heat
from the equipment.
The rest of us are still waiting for the answer. Booting into the
Mac OS to frob the "file server" panel is not an acceptable
solution.
A: If you're on OS X, this is relatively simple to fix. Go to system
preferences, click on energy saver, click on the options tab, check
"Restart automatically after a power failure".
If you're on some other OS, hope they've figured out how to duplicate
the above in a non-simian manner.
-----------------------------------------------------------------------------
Q: I want to keep the drivers and upsd in their own security domains.
How can this be accomplished?
A: Using a few role accounts and a common group, you can limit access
to resources such as the serial port(s) leading to the UPS
hardware.
This is just an example. Change the values to suit your systems.
Create a user called 'nutdev' and another called 'nutsrv'. Put
them both in a group called 'nut'.
Change the owner of any serial ports that will be used to nutdev,
and set the mode to 0600. Then change the ownership of your state
directory (usually /var/state/ups) to nutdev.nut.
For my development system this yields the following /dev entries:
0 crw------- 1 nutdev tty 4, 64 Sep 3 17:11 /dev/ttyS0
0 crw------- 1 nutdev tty 4, 65 Sep 3 17:11 /dev/ttyS1
Switch to root, then start the drivers:
# /usr/local/ups/bin/upsdrvctl -u nutdev start
The listing for /var/state/ups then looks like this:
4 drwxrwx--- 2 nutdev nut 4096 Aug 20 18:37 .
4 drwxr-xr-x 4 root root 4096 May 14 21:20 ..
4 srw-rw---- 1 nutdev nut 0 Sep 3 17:10 apcsmart-ttyS0
4 srw-rw---- 1 nutdev nut 0 Sep 3 17:10 megatec-ttyS1
You may have to remove old socket or state files first if you are
changing to this security scheme from an older version. The drivers
will create new files with the right owners and modes.
Note that /var/state/ups is group writable since upsd will
place the upsd.pid file here.
You may have to change the groups of upsd.conf and upsd.users to
make them readable. These files should not be owned by nutsrv,
since someone could compromise the daemon and change the config
files. Instead, put nutsrv in a group ("nut" in this example), then
make the files owned by root.nut, with mode 0640.
Once the config files are ready, start upsd:
# /usr/local/ups/sbin/upsd -u nutsrv
Check your syslog to be sure everything's happy, then be sure to
update your startup scripts so it uses this procedure on your next
boot.
If you like this, you'll probably also find the chroot process to
be useful and interesting. See chroot.txt for more details.
-----------------------------------------------------------------------------
Q: What's the point of that 'security domains' concept above?
A: The point is limiting your losses. If someone should happen to
break into upsd in that environment, they should only gain access
to that one user account. Direct access to the serial device is
not possible, since that is owned by another user.
There is also the possibility of running the drivers and upsd in a
chroot jail. See the chroot.txt provided in the source
distribution for an example implementation.
Why give would-be vandals any sort of help?
Put it this way - I *wrote* good chunks of this stuff, and I still
run the programs this way locally. You should definitely consider
using this technique.
-----------------------------------------------------------------------------
Q: How can I make upsmon shut down my system after some fixed interval?
A: You probably don't want to do this, since it doesn't maximize your
runtime on battery. Assuming you have a good reason for it (see
the next entry), then look at upssched.txt or the upssched man
page for some ideas.
-----------------------------------------------------------------------------
Q: Why doesn't upsmon shut down my system? I pulled the plug and nothing
happened.
A: Wait. upsmon doesn't consider a UPS to be critical until it's both
'on battery' and 'low battery' at the same time. This is by design.
Nearly every UPS supports the notion of detecting the low battery
all by itself. When the voltage drops below a certain point, it
_will_ let you know about it.
If your system has a really complicated shutdown procedure, you
might need to shut down before the UPS raises the low battery flag.
For most users, however, the default behavior is adequate.
Ask yourself this: why buy a nice big UPS with the matching battery
and corresponding runtime and then shutdown early? If anything, I'd
rather have a few more minutes running on battery during which the
power might return. Once the power's back, it's business as usual
with no visible interruption in service.
If you purposely shut down early, you guarantee an interruption in
service by bringing down the box.
See upssched.txt for information on how you can shutdown early if
this is what you really want to do.
-----------------------------------------------------------------------------
Q: The CGI programs report "access to that host is not authorized" -
what's going on?
A: Those programs need to see a host in your hosts.conf before they
will attempt communications. This keeps people from feeding it
random "host=" settings, which would annoy others with outgoing
connection attempts from your system.
If your hosts.conf turns out to be configured correctly with
MONITOR entries and all that, check the permissions. Your web
server may be running the CGI programs as a user that can't read
the file.
If you run your web server in a chroot jail, make sure the programs
can still read hosts.conf. You may have to copy it into the jail
for this to work. If you do that, make sure it's not writable by
any of the user accounts which run inside the jail.
-----------------------------------------------------------------------------
Q: upsd is running, so why can't I connect to it?
A: Assuming you haven't changed the TCP port number on the command line
or at compile-time, then you probably have some sort of firewall
blocking the connection.
upsd listens on TCP port 3493 by default.
-----------------------------------------------------------------------------
Q: How do you make upsmon reload the config file?
Q: How do you make upsd reload the config file?
A: Either find the pid of the background process and send it a SIGHUP,
or just start it again with '-c reload'.
If you send the signals yourself instead of using -c, be sure you
hit the right process. There are usually two upsmons, and you
should only send signals to one of them. To be safe, read the pid
file.
-----------------------------------------------------------------------------
Q: I just bought a new WhizBang UPS that has a USB connector. How do
I monitor it?
A: There are several driver to support USB models.
- usbhid-ups supports various manufacturers complying to the HID standard,
- tripplite_usb supports various Tripp-Lite units,
- bcmxcp_usb supports various Powerware units.
Refer to the "driver-name" (8) manpage for more information.
-----------------------------------------------------------------------------
Q: What is this usbhid-ups (formerly newhidups) about?
A: The basic USB UPS support was done until NUT 2.2 using hidups. To allow
a wider support accross platforms for USB/HID compliant devices,
usbhid-ups driver uses libusb (which is available for a wide range of
operating systems) and libhid (currently, a modified internal version
of it).
As of NUT 2.2, usbhid-ups completely replaces the legacy hidups driver
and provide support for various manufacturers. At that time, it will
be renamed to usbhid-ups.
usbhid-ups is built automatically if possible (libusb development files
need to be installed) and installed by the "make install" command.
-----------------------------------------------------------------------------
Q: Why doesn't my package work?
Q: I can't run this because there's no package for it. Why isn't this
in a package yet?
A: Sorry, can't help you there. All official releases are source code
and are posted on http://www.networkupstools.org/ along with PGP
signatures for verification.
This means all packages have been built by a third party. If you
have an issue that's related to packaging, you will need to seek
help with whoever built it for you.
-----------------------------------------------------------------------------
Q: Why are there two copies of upsmon running?
A: It's not really two complete copies if your OS forks efficiently.
By default, upsmon runs most of the grunt work as an unprivileged
user and keeps a stub process around with root powers that can
only shut down the system when necessary. This should make it much
harder to gain root in the event a hole is ever discovered in
upsmon.
If this really bothers you and you like running lots of code as
root, start upsmon with -p and it will go back to being one big
process. This is not recommended, so don't blame me if something
bad happens in this mode.
-----------------------------------------------------------------------------
Q: I have <some problem> with <some old version> ...
A: Get the latest stable release, and see if it still happens. If it
goes away, it means someone else reported it and got it fixed a
long time ago.
If that doesn't work, try the latest development version.
If your problem is STILL there, then contact the mailing lists.
Hint: check the release date on the version you have. If it's more
than about 6 months old, there's probably a newer stable tree
version out there.
-----------------------------------------------------------------------------
Q: Do you have to use a serial connection to monitor the UPS?
What about direct network connections (SNMP or otherwise)?
A: No. NUT currently support USB communication through usbhid-ups,
tripplite_usb and bcmxcp_usb, and SNMP communication through snmp-ups.
Any time there is a gap in features, it's usually because the
group of people who own that hardware and the group of people who
write code don't overlap. The fix is to make them overlap -
turn an owner into a developer or vice-versa.
-----------------------------------------------------------------------------
Q: What happened to the patch I sent?
A: If a release goes by and your patch hasn't been included, it was
probably dropped. There can be a lot of patches waiting for
inclusion at some points, and occasionally some have to be
rejected.
Design issues or severe coding style problems can be the reason
for this. I try to point out what the problems are, but there are
limits. See developers.txt for some pointers on submitting
patches.
Sometimes patches are put on hold due to a feature freeze. If it
doesn't show up once the new version opens up, send it again.
-----------------------------------------------------------------------------
Q: I'm not much of a programmer. How can I help?
A: There's always work to be done outside of the realm of code bashing.
Documentation might not always be so clear. A user's perspective
is sometimes needed to appreciate this. Bug reports on a project's
documentation are just as valuable as those for the actual source.
Fielding questions on the mailing lists is also helpful. This
lets other people to focus on coding issues while allowing the
original poster to get some information at the same time. It's
quite a relief to open that mailbox and find that someone else
has already handled it successfully.
-----------------------------------------------------------------------------
Q: I replaced the battery in my APC Smart-UPS and now it thinks the
battery is low all the time. How do you fix this?
Q: My APC UPS keeps reporting "OL LB", even after it's been charging
for many hours. What can I do about this?
A: This happened to me, and some other people too. The combination of
our experiences should prove useful to you.
First, you need to realize that the UPS apparently stores data about
the battery, load, and runtime. After replacing the battery, it
needs to be clued in to the new situation. If the traditional
runtime calibration doesn't work, you have to try something a
little more drastic.
You need to *completely* drain the UPS while it has a good ground.
This means you can't just pull the plug. You also have to
disconnect it from the computer so this software won't shut it
down.
The easiest way to do this is to first unplug your computer(s) from
it, and plug in a token load like a lamp. Also, move the UPS to a
power strip that doesn't switch the ground line or an outlet that
you can switch off at your panel.
Once the UPS is up at 100% charge (this is important), disconnect
the power. It _must_ remain connected to the ground, or the
results may not be accurate. Ignore the sounds it makes, and go
away until it's done. Don't do anything to the front panel while
this is happening.
After all of this, put things back the way they should be and let
it charge up. You should find that it again gives reasonable
values and behavior, as it was when it was new.
Thanks to Matthew Dharm for helping me nail down this procedure.
-----------------------------------------------------------------------------
Q: multimon.cgi seems to be stuck at an old version, even though I
just installed a new one.
A: multimon was removed during the 1.1 development cycle. upsstats
now does everything it used to do, and then some. You should just
delete those files and start using upsstats directly.
-----------------------------------------------------------------------------
Q: OK, I switched to upsstats. Now it's giving me Celsius. I like
Fahrenheit. Where's the config file to switch it back?
A: Temperature scales are handled by the template files, so edit your
upsstats.html and change it from TEMPC to TEMPF.
-----------------------------------------------------------------------------
Q: Why is the mailing list ignoring me?
A: You probably asked a question that's answered in this FAQ or
somewhere else in the documentation and nobody wants to quote it
for you.
Convincing the other subscribers that you've actually read down this
far might be useful. You might mention "queequeg" for better results.
This URL may also be helpful:
http://www.catb.org/~esr/faqs/smart-questions.html
-----------------------------------------------------------------------------
Q: I found some information about another kind of UPS protocol you
don't support yet, but I don't know what to do with it. Can you
help?
A: If you're not a programmer, you can still help others by making
that protocol available. You might host the document somewhere and
send the URL to one of the mailing lists.
-----------------------------------------------------------------------------
Q: How can you answer questions to situations that nobody's encountered
yet? Isn't this a frequently asked questions file?
A: Magic.
A: It's both that and a frequently *anticipated* questions file, too.
The idea is to write it up in here so that nobody asks the mailing
list when it finally does get released.
-----------------------------------------------------------------------------

735
docs/FAQ.txt Normal file
View file

@ -0,0 +1,735 @@
ifndef::external_title[]
NUT Frequently Asked Questions
==============================
endif::external_title[]
== I just upgraded, and ...
You have read link:UPGRADING[UPGRADING] in the base directory of the distribution,
right?
If not, go read it now, then come back to this file if your
question wasn't answered in there.
== upsstats says 'Error: can't open template file (upsstats.html)'.
Go into your configuration path (/usr/local/ups/etc by default) and
copy the sample template files over to their real names. The sample
template files are installed with 'make install' and can
also be found inside the source distribution in the conf directory.
== upsmon fails the login and says 'username required' now.
Go read the link:UPGRADING[UPGRADING] file again.
== My UPS driver now says it's 'broken', and won't start. What now?
Or a variation like...
== My favorite UPS driver disappeared after an upgrade. What now?
Drivers are occasionally removed from the tree if they are no longer
receiving maintenance, or sometimes renamed to better reflect their
hardware support scope or replaced by a more generic driver.
There have been several architectural changes to the driver code
in recent times, and drivers which were not converted by someone
are eventually dropped.
This is called progress. We do this in order to avoid a situation
where someone believes that a driver is being maintained when it is
actually rotting slowly in the tree. It also keeps the tree free of
old compatibility hacks for code that nobody actually uses anyway.
To get a driver back into current releases, you need to convert it
yourself or get someone to do it for you. This is not difficult.
The hardest part of any driver is decoding the protocol, and that's
already been done in the old version.
== My UPS driver program won't work. I'm starting it as root, and root owns the device, so what's the problem?
*Answer 1*
The drivers drop root privileges long before the serial port is
opened. You'll need to change the permissions on that port so that
their new user id can access it. Normally this is "nobody", but it
may be changed at compile-time by using configure --with-user.
Read the error message. If you have a permissions mismatch, then
you'll see something like this:
Network UPS Tools - APC Smart protocol driver 0.60 (1.1.7)
This program is currently running as youruid (UID 1234)
/dev/ttyS2 is owned by user root (UID 0), mode 0600
Change the port name, or fix the permissions or ownership
of /dev/ttyS2 and try again.
Unable to open /dev/ttyS2: Permission denied
Now is a good time to point out that using "nobody" is a bad idea,
since it's a hack for NFS access. You should create a new role
account (perhaps called "ups" or "nut"), and use that instead.
Also, scroll down to the "security domains" question to see an
even better way of restricting privileged operations. Neither the
drivers nor upsd ever need root powers, and that answer tells you
how to make it work.
*Answer 2*
You can also specify a user with "user=" in the global part of
ups.conf. Just define it before any of your [sections]:
user = nut
[myups]
driver = mge-shut
port = /dev/ttyS0
== upsc, upsstats, and the other clients say 'access denied'. The device communication port (serial, USB or network) permissions are fine, so what gives?
In this case, "access denied" means the access to upsd, not the device
communication port. You're being denied since the system has no
permission to speak to upsd according to the access controls.
There can be various reasons. To fix it, check:
- the LISTEN directive in upsd.conf. It should allow your local or remote
access method,
- your firewall rules. Port 3493/tcp must be opened to incoming connexions,
- your tcp-wrappers configuration (hosts.allow and hosts.deny).
Refer to the upsd(8) and upsd.conf(5) manpages for more information.
== I have an APC Smart-UPS connected with a grey APC serial cable and it won't work.
The Back-UPS type in the genericups driver works but then I don't get to use
all the nifty features in there. Why doesn't the right driver work?
The problem lies in your choice of cable. APC's grey cables
generally only do "dumb" signalling - very basic yes/no info about
the battery and line status. While that is sufficient to detect a
low battery condition while on battery, you miss out on all the
goodies that you paid for.
Note that the 940-0095B happens to be a grey cable, but it is actually
a dual mode cable and can be used in smart mode. If you have
this cable, you need to edit your ups.conf to look like this:
[myups]
driver = apcsmart
port = /dev/whatever
cable = 940-0095B
All other grey cables from APC are assumed to be "dumb".
If your grey cable isn't the 940-0095B, the solution is to dump that
cable and find one that supports APC's "smart" signalling. Typically
these come with the UPS and are black. If your smart cable has
wandered off, one can be built rather easily with some connectors and
cable - there's no fancy wiring or resistors.
See this URL for a handy diagram: http://www.networkupstools.org/cables/940-0024C.jpg
There is also a text version of that diagram in the docs/cables
directory of the NUT source distribution. Either one should allow
you to build a good clone of APC's 940-0024C cable.
There are simpler solutions involving 3 wires that work just fine
too, but Powerchute won't find the loopback DTR-DCD and RTS-CTS and
will be annoyed. If you don't ever plan to use Powerchute, 3 wires
(RxD, TxD, GND) are sufficient.
It should also be noted that the genericups driver has no way to
detect the UPS, so it will fire up quite happily if it can open the
serial port. Merely having it start up is not necessarily an
indication of success. You should start it and then check the
status with upsc or similar to be sure that it's reading the
hardware properly.
== Why doesn't upsd implement the functionality of upsmon? I have to run THREE programs to monitor my UPS!
*Answer 1*
I try to follow the "tool for the job" philosophy. It may mean
more programs running, but the flexibility you get is usually
worth it.
Yes, the machine with the UPS attached will generally have 3
processes (driver, upsd, upsmon) running, but this design allows a
much bigger setup. Imagine a data room with a bunch of machines
all drawing power from the same UPS. The rest of them just run
upsmon.
Besides, if upsmon were rolled into upsd, upsd would get even
bigger than it is now. You'd have one less process, but the
RAM consumption would be pretty close to now.
See data-room.txt for more configuration ideas and explanations.
*Answer 2*
If this really bothers you, roll up your sleeves and use the
sockdebug code to write a "upsmon" type program that sits on top of
the state sockets. It won't work over the network, but it means
you don't need upsd. It also means only one host can monitor the
UPS.
This is also a good option to consider if you can't use networked
monitoring code for security or safety reasons.
See ideas.txt for more on this and other related topics.
== Why isn't upssched part of upsmon?
Most users will never have any reason to use upssched. It's
complicated, and getting it right for your situation can be tricky.
Having it live in a separate program saves resources and lets most
people avoid it completely.
It is also coherent with the answer to the previous question.
== Why doesn't upsmon send a SIGPWR signal to init so it can deal with power events?
*Answer 1*
New versions of the init man page taken from the sysvinit package
are saying that usage of SIGPWR is discouraged, since /dev/initctl
control channel is the preferred way of communication.
*Answer 2*
The name of the game is portability. Not everyone's init handles
that kind of signalling gracefully. What's more, some admins
might want to do things differently even if they have that kind of
init running.
So, to be compatible, upsmon just invokes a shell command. If you
want to use init's SIGPWR stuff, just put the right "kill" line in
a shell script and make upsmon call it. Everyone wins.
== Why won't bestups talk to my Best Fortress UPS?
There are at least two different protocols being used for hardware
with very similar names. The bestups driver tends to support the
units built around the newer "PhoenixTec" protocol.
Previous releases of this software included a driver called
bestfortress which supported the older Best hardware. See the
earlier entries about updating old drivers which have been removed
from the tree.
== What's this about 'data stale'?
It means your UPS driver hasn't updated things in a little while.
upsd refuses to serve up data that isn't fresh, so you get the
errors about staleness.
If this happens to you, make sure your driver is still running.
Also look at the syslog. Sometimes the driver loses the connection
to the UPS, and that will also make the data go stale.
Note: some very slow machines have trouble keeping up with the
serial ports during periods of extreme load. My old 486 used to
flip between "stale" and "OK" while running backups.
If this happens a lot, you might consider cranking up DEADTIME
in the upsmon.conf to suppress some of the warnings for shorter
intervals. Use caution when adjusting this number, since it
directly affects how long you run on battery without knowing
what's going on with the UPS.
Note: some drivers occasionally need more time to update than the
default value of MAXAGE (in upsd.conf) allows. As a result, they
are temporarily marked stale even though everything is fine. This
can happen with MGE Ellipse equipment - see the mge-shut man page.
In such cases, you can raise the value of MAXAGE to avoid these
warnings; try a value like 25 or 30.
== Why do the client programs say 'Driver not connected' when I try to run them?
This means that upsd can't connect to the driver for some reason.
Your ups.conf entry might be wrong, or the driver might not be
running. Maybe your state path is not configured properly.
Check your syslog. upsd will complain regularly if it can't
connect to a driver, and it should say why it can't connect.
Note: if you jumped in with both feet and didn't follow the INSTALL
document, you probably started upsd by itself. You have to run
'upsdrvctl start' to start the drivers after configuring ups.conf.
== Everything works perfectly during the shutdown, and the UPS comes back on, but my system stays off. What's happening?
Assuming you don't have the problem in the next question, then you
probably have an ATX motherboard, have APM or ACPI enabled in your
kernel (assuming Linux here), and are reaching the 'halt' at the
bottom of your shutdown scripts.
Your machine obeys and shuts down, and stays down, since it
remembers the 'last state' when the UPS restarts.
One solution is to change your shutdown scripts so you never reach
that point. You *want* the system to die without reaching the
part where the kernel tells it to shut down. A possible script
might look like this:
# other shutdown stuff here (mount -o remount,ro ...)
if (test -f /etc/killpower)
then
/usr/local/ups/bin/upsdrvctl shutdown
sleep 600 # this should never return
# uh oh, we never got shut down! (power race?)
reboot
fi
halt -p
The other solution is to change your BIOS setting to "always power
on" instead of "last state", assuming that's possible.
== My system has an ATX power supply. It will power off just fine, but it doesn't turn back on. What can I do to fix this?
This depends on how clueful your motherboard manufacturer is, and
isn't a matter of the OS. You have to do one of the following
things depending on what's supported:
- Set a jumper on the motherboard that means "return after outage"
- Set something in the BIOS that says "power up after power failure"
- Try using something (like a capacitor) across the power button
to "push" it for you - this might not work if it needs a delay
- Hack the cable between the power supply and the motherboard to fool
it into powering up whenever line power is present
- Teach a monkey to watch the machine and press the power button
when the outage is over.
This might work, but it creates high produce bills.
If you can't use one of the first two options, give the board to
an enemy. Let them worry about it.
== My PowerMac G4 won't power back up by itself (into Linux) after the UPS shuts down. What can I do about this?
*Answer 1*
This is about the same situation as the ATX question above, only
worse. Earlier Macs apparently supported a hack where you could
cat some magic characters at /dev/adb to enable "server mode".
This would instruct the system to reboot while unattended.
From Usenet post <6boftzxz51.fsf@ecc-office.sp.cs.cmu.edu>:
# Send packet over the ADB bus to the PowerMac CUDA chip
# telling it to reboot automatically when power is restored
# after a power failure.
cat /etc/local/autoboot.adb > /dev/adb
autoboot.adb contains these three bytes (in hex): 01 13 01
Unfortunately, the hardware has evolved and there is no good
equivalent for this hack on today's systems.
If you find out how to do this, please send me some mail, since
this affects one of my systems and my stop-gap solution is getting
cranky.
Note: this question has been in the FAQ for over a year and
there's still no answer. Let me guess: everyone who runs a server
on Mac hardware has a team of trained monkeys, and feeds them
by growing bananas in the tropical environment formed by waste heat
from the equipment.
The rest of us are still waiting for the answer. Booting into the
Mac OS to frob the "file server" panel is not an acceptable
solution.
*Answer 2*
If you're on OS X, this is relatively simple to fix. Go to system
preferences, click on energy saver, click on the options tab, check
"Restart automatically after a power failure".
If you're on some other OS, hope they've figured out how to duplicate
the above in a non-simian manner.
== I want to keep the drivers and upsd in their own security domains. How can this be accomplished?
Using a few role accounts and a common group, you can limit access
to resources such as the serial port(s) leading to the UPS
hardware.
This is just an example. Change the values to suit your systems.
- Create a user called 'nutdev' and another called 'nutsrv'. Put
them both in a group called 'nut'.
- Change the owner of any serial ports that will be used to nutdev,
and set the mode to 0600. Then change the ownership of your state
directory (usually /var/state/ups) to nutdev.nut.
For my development system this yields the following /dev entries:
0 crw------- 1 nutdev tty 4, 64 Sep 3 17:11 /dev/ttyS0
0 crw------- 1 nutdev tty 4, 65 Sep 3 17:11 /dev/ttyS1
- Switch to root, then start the drivers:
# /usr/local/ups/bin/upsdrvctl -u nutdev start
- The listing for /var/state/ups then looks like this:
4 drwxrwx--- 2 nutdev nut 4096 Aug 20 18:37 .
4 drwxr-xr-x 4 root root 4096 May 14 21:20 ..
4 srw-rw---- 1 nutdev nut 0 Sep 3 17:10 apcsmart-ups1
4 srw-rw---- 1 nutdev nut 0 Sep 3 17:10 blazer_ser-ups2
You may have to remove old socket or state files first if you are
changing to this security scheme from an older version. The drivers
will create new files with the right owners and modes.
Note that /var/state/ups is group writable since upsd will
place the upsd.pid file here.
You may have to change the groups of upsd.conf and upsd.users to
make them readable. These files should not be owned by nutsrv,
since someone could compromise the daemon and change the config
files. Instead, put nutsrv in a group ("nut" in this example), then
make the files owned by root.nut, with mode 0640.
Once the config files are ready, start upsd:
# /usr/local/ups/sbin/upsd -u nutsrv
Check your syslog to be sure everything's happy, then be sure to
update your startup scripts so it uses this procedure on your next
boot.
If you like this, you'll probably also find the chroot process to
be useful and interesting. See security.txt for more details.
== What's the point of that 'security domains' concept above?
The point is limiting your losses. If someone should happen to
break into upsd in that environment, they should only gain access
to that one user account. Direct access to the serial device is
not possible, since that is owned by another user.
There is also the possibility of running the drivers and upsd in a
chroot jail. See the chroot.txt provided in the source
distribution for an example implementation.
Why give would-be vandals any sort of help?
Put it this way - I *wrote* good chunks of this stuff, and I still
run the programs this way locally. You should definitely consider
using this technique.
== How can I make upsmon shut down my system after some fixed interval?
You probably don't want to do this, since it doesn't maximize your
runtime on battery. Assuming you have a good reason for it (see
the next entry), then look at scheduling.txt or the upssched(8) man
page for some ideas.
/////////////////////////////////////////////////////////////////
TODO: figure out how to link to the upssched man page above.
/////////////////////////////////////////////////////////////////
== Why doesn't upsmon shut down my system? I pulled the plug and nothing happened.
Wait. upsmon doesn't consider a UPS to be critical until it's both
'on battery' and 'low battery' at the same time. This is by design.
Nearly every UPS supports the notion of detecting the low battery
all by itself. When the voltage drops below a certain point, it
_will_ let you know about it.
If your system has a really complicated shutdown procedure, you
might need to shut down before the UPS raises the low battery flag.
For most users, however, the default behavior is adequate.
Ask yourself this: why buy a nice big UPS with the matching battery
and corresponding runtime and then shutdown early? If anything, I'd
rather have a few more minutes running on battery during which the
power might return. Once the power's back, it's business as usual
with no visible interruption in service.
If you purposely shut down early, you guarantee an interruption in
service by bringing down the box.
See upssched.txt for information on how you can shutdown early if
this is what you really want to do.
== The CGI programs report 'access to that host is not authorized' - what's going on?
Those programs need to see a host in your hosts.conf before they
will attempt communications. This keeps people from feeding it
random "host=" settings, which would annoy others with outgoing
connection attempts from your system.
If your hosts.conf turns out to be configured correctly with
MONITOR entries and all that, check the permissions. Your web
server may be running the CGI programs as a user that can't read
the file.
If you run your web server in a chroot jail, make sure the programs
can still read hosts.conf. You may have to copy it into the jail
for this to work. If you do that, make sure it's not writable by
any of the user accounts which run inside the jail.
== upsd is running, so why can't I connect to it?
Assuming you haven't changed the TCP port number on the command line
or at compile-time, then you probably have some sort of firewall
blocking the connection.
upsd listens on TCP port 3493 by default.
== How do you make upsmon reload the config file?
Or a variation like...
== How do you make upsd reload the config file?
Either find the pid of the background process and send it a SIGHUP,
or just start it again with '-c reload'.
If you send the signals yourself instead of using -c, be sure you
hit the right process. There are usually two upsmons, and you
should only send signals to one of them. To be safe, read the pid
file.
== I just bought a new WhizBang UPS that has a USB connector. How do I monitor it?
There are several driver to support USB models.
- usbhid-ups supports various manufacturers complying to the HID standard,
- tripplite_usb supports various Tripp-Lite units,
- bcmxcp_usb supports various Powerware units,
- blazer_usb supports various manufacturers that use the Megatec / Q1 protocol.
Refer to the 'driver-name' (8) manpage for more information.
== What is this usbhid-ups (formerly newhidups) about?
The basic USB UPS support was done until NUT 2.2 using hidups. To allow
a wider support accross platforms for USB/HID compliant devices,
usbhid-ups driver uses libusb (which is available for a wide range of
operating systems) and libhid (currently, a modified internal version
of it).
As of NUT 2.2, usbhid-ups completely replaces the legacy hidups driver
and provide support for various manufacturers. At that time, it will
be renamed to usbhid-ups.
usbhid-ups is built automatically if possible (libusb development files
need to be installed) and installed by the "make install" command.
== Why doesn't my package work?
Or a variation like...
== I can't run this because there's no package for it. Why isn't this in a package yet?
Sorry, can't help you there. All official releases are source code
and are posted on http://www.networkupstools.org/ along with PGP
signatures for verification.
This means all packages have been built by a third party. If you
have an issue that's related to packaging, you will need to seek
help with whoever built it for you.
== Why are there two copies of upsmon running?
It's not really two complete copies if your OS forks efficiently.
By default, upsmon runs most of the grunt work as an unprivileged
user and keeps a stub process around with root powers that can
only shut down the system when necessary. This should make it much
harder to gain root in the event a hole is ever discovered in
upsmon.
If this really bothers you and you like running lots of code as
root, start upsmon with -p and it will go back to being one big
process. This is not recommended, so don't blame us if something
bad happens in this mode.
== I have 'some problem' with 'some old version' ...
Get the latest stable release, and see if it still happens. If it
goes away, it means someone else reported it and got it fixed a
long time ago.
If that doesn't work, try the latest development version.
If your problem is STILL there, then contact the mailing lists.
NOTE: check the release date on the version you have. If it's more
than about 6 months old, there's probably a newer stable tree
version out there.
== Do I have to use a serial connection to monitor the UPS? What about direct network connections (SNMP or otherwise)?
No. NUT currently support USB communication through several drivers,
and also SNMP and XML/HTTP (Eaton and MGE) communications.
Since NUT is very extensible, support for a new communication bus can be added
easily.
Any time there is a gap in features, it's usually because the
group of people who own that hardware and the group of people who
write code don't overlap. The fix is to make them overlap -
turn an owner into a developer or vice-versa.
== What happened to the patch I sent?
If a release goes by and your patch hasn't been included, it was
probably dropped. There can be a lot of patches waiting for
inclusion at some points, and occasionally some have to be
rejected.
Design issues or severe coding style problems can be the reason
for this. I try to point out what the problems are, but there are
limits. See developers.txt for some pointers on submitting
patches.
Sometimes patches are put on hold due to a feature freeze. If it
doesn't show up once the new version opens up, send it again.
== I'm not much of a programmer. How can I help?
There's always work to be done outside of the realm of code bashing.
Documentation might not always be so clear. A user's perspective
is sometimes needed to appreciate this. Bug reports on a project's
documentation are just as valuable as those for the actual source.
Fielding questions on the mailing lists is also helpful. This
lets other people to focus on coding issues while allowing the
original poster to get some information at the same time. It's
quite a relief to open that mailbox and find that someone else
has already handled it successfully.
== I replaced the battery in my APC Smart-UPS and now it thinks the battery is low all the time. How do you fix this?
Or a variation like...
== My APC UPS keeps reporting 'OL LB', even after it's been charging for many hours. What can I do about this?
This happened to me, and some other people too. The combination of
our experiences should prove useful to you.
First, you need to realize that the UPS apparently stores data about
the battery, load, and runtime. After replacing the battery, it
needs to be clued in to the new situation. If the traditional
runtime calibration doesn't work, you have to try something a
little more drastic.
You need to *completely* drain the UPS while it has a good ground.
This means you can't just pull the plug. You also have to
disconnect it from the computer so this software won't shut it
down.
The easiest way to do this is to first unplug your computer(s) from
it, and plug in a token load like a lamp. Also, move the UPS to a
power strip that doesn't switch the ground line or an outlet that
you can switch off at your panel.
Once the UPS is up at 100% charge (this is important), disconnect
the power. It _must_ remain connected to the ground, or the
results may not be accurate. Ignore the sounds it makes, and go
away until it's done. Don't do anything to the front panel while
this is happening.
After all of this, put things back the way they should be and let
it charge up. You should find that it again gives reasonable
values and behavior, as it was when it was new.
Thanks to Matthew Dharm for helping us nail down this procedure.
== upsstats returns temperatures in Celsius. I like Fahrenheit. Where's the config file to switch it back?
Temperature scales are handled by the template files, so edit your
upsstats.html and change it from TEMPC to TEMPF.
== Why is the mailing list ignoring me?
You probably asked a question that's answered in this FAQ or
somewhere else in the documentation and nobody wants to quote it
for you.
Convincing the other subscribers that you've actually read down this
far might be useful. You might mention "queequeg" for better results.
This URL may also be helpful:
http://www.catb.org/~esr/faqs/smart-questions.html
== I found some information about another kind of UPS protocol you don't support yet, but I don't know what to do with it. Can you help?
If you're not a programmer, you can still help others by making
that protocol available. You might host the document somewhere and
send the URL to one of the mailing lists.
== How can you answer questions to situations that nobody's encountered yet? Isn't this a frequently asked questions file?
*Answer 1*
It's a kind of Magic.
*Answer 2*
It's both that and a frequently *anticipated* questions file, too.
The idea is to write it up in here so that nobody asks the mailing
list when it finally does get released.
== My UPS powers up immediately after a power failure instead of waiting for the batteries to recharge!
You can rig up a little hack to handle this issue in software.
Essentially, you need to test for the POWERDOWNFLAG in your *startup* scripts
while the filesystems are still read-only. If it's there, you know your last
shutdown was caused by a power failure and the UPS battery is probably still
quite weak.
In this situation, your best bet is to sleep it off. Pausing in your startup
script to let the batteries recharge with the filesystems in a safe state is
recommended. This way, if the power goes out again, you won't face a situation
where there's not enough battery capacity left for upsmon to do its thing.
Exactly how long to wait is a function of your UPS hardware, and will require
careful testing.
If this is too evil for you, buy another kind of UPS that will either wait for a
minimum amount of charge, a minimum amount of time, or both.
== I'm facing a power race
Or a variation like...
== The power came back during the shutdown, but before the UPS power off. Now the UPS does not reboot, and my computer stays off. How can I fix that?
There is a situation where the power may return during the shutdown process.
This is known as a race. Here's how we handle it.
"Smart" UPSes typically handle this by using a command that forces the UPS to
power the load off and back on. This way, you are assured that the systems will
restart even if the power returns at the worst possible moment.
Contact closure units (ala genericups), on the other hand, have the potential
for a race when feeding multiple systems. This is due to the design of most
contact closure UPSes. Typically, the "kill power" line only functions when
running on battery. As a result, if the line power returns during the shutdown
process, there is no way to power down the load.
The workaround is to force your systems to reboot after some interval. This way,
they won't be stuck in the halted state with the UPS running on line power.
Implement this by modifying your shutdown script like this:
if (test -f /etc/killpower)
then
/usr/local/ups/bin/upsdrvctl shutdown
sleep 120
# uh oh, we never got shut down! (power race?)
reboot
fi

113
docs/Makefile.am
View file

@ -1,13 +1,108 @@
# nothing to build here, but still need a Makefile to define which
# files to distribute
SHARED_DEPS = nut-names.txt asciidoc.conf
EXTRA_DIST = acpi.txt big-servers.txt chroot.txt \
commands.txt config-files.txt configure.txt contact-closure.txt \
data-room.txt design.txt developers.txt FAQ hid-subdrivers.txt \
ideas.txt macros.txt megatec.txt new-drivers.txt new-names.txt \
nut-hal.txt osd-notify.txt \
pager.txt powersaving.txt protocol.txt README shutdown.txt snmp.txt \
sock-protocol.txt ssl.txt upssched.txt cables/apc-rs500-serial.txt \
IMAGE_FILES = images/asciidoc.png \
images/eaton-logo.png \
images/nut_layering.png \
images/note.png \
images/warning.png \
images/blue-arrow.png \
images/simple.png \
images/advanced.png \
images/bigbox.png \
images/bizarre.png \
images/old-cgi.png
USER_MANUAL_DEPS = acknowledgements.txt cables.txt config-notes.txt \
configure.txt download.txt documentation.txt features.txt history.txt \
outlets.txt scheduling.txt security.txt support.txt user-manual.txt \
stable-hcl.txt
DEVELOPER_GUIDE_DEPS = contact-closure.txt design.txt developers.txt \
developer-guide.txt hid-subdrivers.txt macros.txt \
new-clients.txt new-drivers.txt net-protocol.txt sock-protocol.txt
CABLES_DEPS = cables/apc-rs500-serial.txt \
cables/apc.txt cables/ge-imv-victron.txt cables/imv.txt \
cables/mgeups.txt cables/powerware.txt cables/repotec.txt \
cables/sms.txt
CABLES_IMAGES = images/cables/73-0724.png images/cables/940-0024C.jpg \
images/cables/belkin-f6cx-rkm-xu-cable.jpg images/cables/Lansafecable.jpg \
images/cables/mac-940-0024C.png images/cables/mge-66049.png \
images/cables/mge-db9-rj12.jpg images/cables/mge-db9-rj45.jpg \
images/cables/SOLA-330.png
EXTRA_DIST = $(SHARED_DEPS) $(USER_MANUAL_DEPS) $(DEVELOPER_GUIDE_DEPS) \
$(CABLES_DEPS) FAQ.txt nut-hal.txt nut-qa.txt packager-guide.txt snmp.txt \
$(IMAGE_FILES) $(CABLES_IMAGES) docinfo.xml
ASCIIDOC_HTML_SINGLE = user-manual.html \
developer-guide.html \
packager-guide.html \
FAQ.html
ASCIIDOC_HTML_CHUNKED = user-manual.chunked \
developer-guide.chunked \
packager-guide.chunked \
FAQ.html
ASCIIDOC_PDF = user-manual.pdf \
developer-guide.pdf \
packager-guide.pdf \
FAQ.pdf
# Force build in ./ and man/ before website
SUBDIRS = . man website
SUFFIXES = .txt .html .pdf
all: doc
doc: @DOC_BUILD_LIST@
pdf: $(ASCIIDOC_PDF)
# also build the HTML manpages with these targets
html-single: $(ASCIIDOC_HTML_SINGLE)
html-chunked: $(ASCIIDOC_HTML_CHUNKED)
if HAVE_ASCIIDOC
website: html-chunked pdf
else !HAVE_ASCIIDOC
website:
@echo "Not building website documentation since 'asciidoc' was not found."
endif !HAVE_ASCIIDOC
clean-local:
rm -rf *.pdf *.html *.chunked docbook-xsl.css
### TODO: automatic dependency generation
FULL_USER_MANUAL_DEPS = $(USER_MANUAL_DEPS) $(SHARED_DEPS) ../README \
../INSTALL cables.txt ../UPGRADING ../TODO
FULL_DEVELOPER_GUIDE_DEPS = $(DEVELOPER_GUIDE_DEPS) $(SHARED_DEPS) \
../scripts/augeas/README
user-manual.html user-manual.chunked user-manual.pdf: $(FULL_USER_MANUAL_DEPS)
developer-guide.html developer-guide.chunked developer-guide.pdf: $(FULL_DEVELOPER_GUIDE_DEPS)
packager-guide.html packager-guide.chunked packager-guide.pdf: packager-guide.txt asciidoc.conf
# Note: without the "-v", asciidoc (circa 8.6.2) sometimes hangs when
# generating the chunked HTML. In this case, export the environment
# variable ASCIIDOC_VERBOSE to "-v", ie:
# $ ASCIIDOC_VERBOSE=-v make
A2X_COMMON_OPTS = $(ASCIIDOC_VERBOSE) --attribute icons \
--attribute localdate=`TZ=UTC date +%Y-%m-%d` \
--attribute localtime=`TZ=UTC date +%H:%M:%S` \
--attribute iconsdir=$(srcdir)/images \
--attribute=badges \
--attribute=external_title \
-a toc -a numbered --destination-dir=.
.txt.html:
$(A2X) $(A2X_COMMON_OPTS) --attribute=xhtml11_format --format=xhtml $<
.txt.chunked:
$(A2X) $(A2X_COMMON_OPTS) --attribute=chunked_format --format=chunked $<
.txt.pdf: docinfo.xml
$(A2X) $(A2X_COMMON_OPTS) --attribute=pdf_format --format=pdf -a docinfo1 $<
.PHONY: html html-single pdf website

418
docs/Makefile.in
View file

@ -1,4 +1,4 @@
# Makefile.in generated by automake 1.11 from Makefile.am.
# Makefile.in generated by automake 1.11.1 from Makefile.am.
# @configure_input@
# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
@ -14,9 +14,6 @@
# PARTICULAR PURPOSE.
@SET_MAKE@
# nothing to build here, but still need a Makefile to define which
# files to distribute
VPATH = @srcdir@
pkgdatadir = $(datadir)/@PACKAGE@
pkgincludedir = $(includedir)/@PACKAGE@
@ -38,14 +35,15 @@ build_triplet = @build@
host_triplet = @host@
target_triplet = @target@
subdir = docs
DIST_COMMON = README $(srcdir)/Makefile.am $(srcdir)/Makefile.in
DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in
ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
am__aclocal_m4_deps = $(top_srcdir)/m4/ax_create_stdint_h.m4 \
am__aclocal_m4_deps = $(top_srcdir)/m4/ax_compare_version.m4 \
$(top_srcdir)/m4/ax_create_stdint_h.m4 \
$(top_srcdir)/m4/libtool.m4 $(top_srcdir)/m4/ltoptions.m4 \
$(top_srcdir)/m4/ltsugar.m4 $(top_srcdir)/m4/ltversion.m4 \
$(top_srcdir)/m4/lt~obsolete.m4 \
$(top_srcdir)/m4/nut_arg_with.m4 \
$(top_srcdir)/m4/nut_check_ipv6.m4 \
$(top_srcdir)/m4/nut_check_asciidoc.m4 \
$(top_srcdir)/m4/nut_check_libgd.m4 \
$(top_srcdir)/m4/nut_check_libhal.m4 \
$(top_srcdir)/m4/nut_check_libneon.m4 \
@ -55,6 +53,7 @@ am__aclocal_m4_deps = $(top_srcdir)/m4/ax_create_stdint_h.m4 \
$(top_srcdir)/m4/nut_check_libusb.m4 \
$(top_srcdir)/m4/nut_check_libwrap.m4 \
$(top_srcdir)/m4/nut_check_os.m4 \
$(top_srcdir)/m4/nut_config_libhal.m4 \
$(top_srcdir)/m4/nut_report_feature.m4 \
$(top_srcdir)/m4/nut_type_socklen_t.m4 \
$(top_srcdir)/configure.in
@ -66,10 +65,52 @@ CONFIG_CLEAN_FILES =
CONFIG_CLEAN_VPATH_FILES =
SOURCES =
DIST_SOURCES =
RECURSIVE_TARGETS = all-recursive check-recursive dvi-recursive \
html-recursive info-recursive install-data-recursive \
install-dvi-recursive install-exec-recursive \
install-html-recursive install-info-recursive \
install-pdf-recursive install-ps-recursive install-recursive \
installcheck-recursive installdirs-recursive pdf-recursive \
ps-recursive uninstall-recursive
RECURSIVE_CLEAN_TARGETS = mostlyclean-recursive clean-recursive \
distclean-recursive maintainer-clean-recursive
AM_RECURSIVE_TARGETS = $(RECURSIVE_TARGETS:-recursive=) \
$(RECURSIVE_CLEAN_TARGETS:-recursive=) tags TAGS ctags CTAGS \
distdir
ETAGS = etags
CTAGS = ctags
DIST_SUBDIRS = $(SUBDIRS)
DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
am__relativize = \
dir0=`pwd`; \
sed_first='s,^\([^/]*\)/.*$$,\1,'; \
sed_rest='s,^[^/]*/*,,'; \
sed_last='s,^.*/\([^/]*\)$$,\1,'; \
sed_butlast='s,/*[^/]*$$,,'; \
while test -n "$$dir1"; do \
first=`echo "$$dir1" | sed -e "$$sed_first"`; \
if test "$$first" != "."; then \
if test "$$first" = ".."; then \
dir2=`echo "$$dir0" | sed -e "$$sed_last"`/"$$dir2"; \
dir0=`echo "$$dir0" | sed -e "$$sed_butlast"`; \
else \
first2=`echo "$$dir2" | sed -e "$$sed_first"`; \
if test "$$first2" = "$$first"; then \
dir2=`echo "$$dir2" | sed -e "$$sed_rest"`; \
else \
dir2="../$$dir2"; \
fi; \
dir0="$$dir0"/"$$first"; \
fi; \
fi; \
dir1=`echo "$$dir1" | sed -e "$$sed_rest"`; \
done; \
reldir="$$dir2"
A2X = @A2X@
ACLOCAL = @ACLOCAL@
AMTAR = @AMTAR@
AR = @AR@
ASCIIDOC = @ASCIIDOC@
AUTOCONF = @AUTOCONF@
AUTOHEADER = @AUTOHEADER@
AUTOMAKE = @AUTOMAKE@
@ -82,8 +123,10 @@ CONFPATH = @CONFPATH@
CPP = @CPP@
CPPFLAGS = @CPPFLAGS@
CYGPATH_W = @CYGPATH_W@
DBLATEX = @DBLATEX@
DEFS = @DEFS@
DEPDIR = @DEPDIR@
DOC_BUILD_LIST = @DOC_BUILD_LIST@
DRIVER_BUILD_LIST = @DRIVER_BUILD_LIST@
DRIVER_INSTALL_TARGET = @DRIVER_INSTALL_TARGET@
DRIVER_MAN_LIST = @DRIVER_MAN_LIST@
@ -100,7 +143,6 @@ HAL_CALLOUTS_PATH = @HAL_CALLOUTS_PATH@
HAL_DEVICE_MATCH_KEY = @HAL_DEVICE_MATCH_KEY@
HAL_FDI_PATH = @HAL_FDI_PATH@
HAL_USER = @HAL_USER@
HAVE_GLIB_2_14 = @HAVE_GLIB_2_14@
INSTALL = @INSTALL@
INSTALL_DATA = @INSTALL_DATA@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
@ -111,22 +153,22 @@ LDFLAGS = @LDFLAGS@
LIBGD_CFLAGS = @LIBGD_CFLAGS@
LIBGD_LDFLAGS = @LIBGD_LDFLAGS@
LIBHAL_CFLAGS = @LIBHAL_CFLAGS@
LIBHAL_LDFLAGS = @LIBHAL_LDFLAGS@
LIBHAL_LIBS = @LIBHAL_LIBS@
LIBNEON_CFLAGS = @LIBNEON_CFLAGS@
LIBNEON_LDFLAGS = @LIBNEON_LDFLAGS@
LIBNEON_LIBS = @LIBNEON_LIBS@
LIBNETSNMP_CFLAGS = @LIBNETSNMP_CFLAGS@
LIBNETSNMP_LDFLAGS = @LIBNETSNMP_LDFLAGS@
LIBNETSNMP_LIBS = @LIBNETSNMP_LIBS@
LIBOBJS = @LIBOBJS@
LIBPOWERMAN_CFLAGS = @LIBPOWERMAN_CFLAGS@
LIBPOWERMAN_LDFLAGS = @LIBPOWERMAN_LDFLAGS@
LIBPOWERMAN_LIBS = @LIBPOWERMAN_LIBS@
LIBS = @LIBS@
LIBSSL_CFLAGS = @LIBSSL_CFLAGS@
LIBSSL_LDFLAGS = @LIBSSL_LDFLAGS@
LIBSSL_LIBS = @LIBSSL_LIBS@
LIBTOOL = @LIBTOOL@
LIBUSB_CFLAGS = @LIBUSB_CFLAGS@
LIBUSB_LDFLAGS = @LIBUSB_LDFLAGS@
LIBUSB_LIBS = @LIBUSB_LIBS@
LIBWRAP_CFLAGS = @LIBWRAP_CFLAGS@
LIBWRAP_LDFLAGS = @LIBWRAP_LDFLAGS@
LIBWRAP_LIBS = @LIBWRAP_LIBS@
LIPO = @LIPO@
LN_S = @LN_S@
LTLIBOBJS = @LTLIBOBJS@
@ -222,20 +264,87 @@ top_build_prefix = @top_build_prefix@
top_builddir = @top_builddir@
top_srcdir = @top_srcdir@
udevdir = @udevdir@
EXTRA_DIST = acpi.txt big-servers.txt chroot.txt \
commands.txt config-files.txt configure.txt contact-closure.txt \
data-room.txt design.txt developers.txt FAQ hid-subdrivers.txt \
ideas.txt macros.txt megatec.txt new-drivers.txt new-names.txt \
nut-hal.txt osd-notify.txt \
pager.txt powersaving.txt protocol.txt README shutdown.txt snmp.txt \
sock-protocol.txt ssl.txt upssched.txt cables/apc-rs500-serial.txt \
SHARED_DEPS = nut-names.txt asciidoc.conf
IMAGE_FILES = images/asciidoc.png \
images/eaton-logo.png \
images/nut_layering.png \
images/note.png \
images/warning.png \
images/blue-arrow.png \
images/simple.png \
images/advanced.png \
images/bigbox.png \
images/bizarre.png \
images/old-cgi.png
USER_MANUAL_DEPS = acknowledgements.txt cables.txt config-notes.txt \
configure.txt download.txt documentation.txt features.txt history.txt \
outlets.txt scheduling.txt security.txt support.txt user-manual.txt \
stable-hcl.txt
DEVELOPER_GUIDE_DEPS = contact-closure.txt design.txt developers.txt \
developer-guide.txt hid-subdrivers.txt macros.txt \
new-clients.txt new-drivers.txt net-protocol.txt sock-protocol.txt
CABLES_DEPS = cables/apc-rs500-serial.txt \
cables/apc.txt cables/ge-imv-victron.txt cables/imv.txt \
cables/mgeups.txt cables/powerware.txt cables/repotec.txt \
cables/sms.txt
all: all-am
CABLES_IMAGES = images/cables/73-0724.png images/cables/940-0024C.jpg \
images/cables/belkin-f6cx-rkm-xu-cable.jpg images/cables/Lansafecable.jpg \
images/cables/mac-940-0024C.png images/cables/mge-66049.png \
images/cables/mge-db9-rj12.jpg images/cables/mge-db9-rj45.jpg \
images/cables/SOLA-330.png
EXTRA_DIST = $(SHARED_DEPS) $(USER_MANUAL_DEPS) $(DEVELOPER_GUIDE_DEPS) \
$(CABLES_DEPS) FAQ.txt nut-hal.txt nut-qa.txt packager-guide.txt snmp.txt \
$(IMAGE_FILES) $(CABLES_IMAGES) docinfo.xml
ASCIIDOC_HTML_SINGLE = user-manual.html \
developer-guide.html \
packager-guide.html \
FAQ.html
ASCIIDOC_HTML_CHUNKED = user-manual.chunked \
developer-guide.chunked \
packager-guide.chunked \
FAQ.html
ASCIIDOC_PDF = user-manual.pdf \
developer-guide.pdf \
packager-guide.pdf \
FAQ.pdf
# Force build in ./ and man/ before website
SUBDIRS = . man website
SUFFIXES = .txt .html .pdf
### TODO: automatic dependency generation
FULL_USER_MANUAL_DEPS = $(USER_MANUAL_DEPS) $(SHARED_DEPS) ../README \
../INSTALL cables.txt ../UPGRADING ../TODO
FULL_DEVELOPER_GUIDE_DEPS = $(DEVELOPER_GUIDE_DEPS) $(SHARED_DEPS) \
../scripts/augeas/README
# Note: without the "-v", asciidoc (circa 8.6.2) sometimes hangs when
# generating the chunked HTML. In this case, export the environment
# variable ASCIIDOC_VERBOSE to "-v", ie:
# $ ASCIIDOC_VERBOSE=-v make
A2X_COMMON_OPTS = $(ASCIIDOC_VERBOSE) --attribute icons \
--attribute localdate=`TZ=UTC date +%Y-%m-%d` \
--attribute localtime=`TZ=UTC date +%H:%M:%S` \
--attribute iconsdir=$(srcdir)/images \
--attribute=badges \
--attribute=external_title \
-a toc -a numbered --destination-dir=.
all: all-recursive
.SUFFIXES:
.SUFFIXES: .txt .html .pdf .chunked
$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps)
@for dep in $?; do \
case '$(am__configure_deps)' in \
@ -272,12 +381,141 @@ mostlyclean-libtool:
clean-libtool:
-rm -rf .libs _libs
# This directory's subdirectories are mostly independent; you can cd
# into them and run `make' without going through this Makefile.
# To change the values of `make' variables: instead of editing Makefiles,
# (1) if the variable is set in `config.status', edit `config.status'
# (which will cause the Makefiles to be regenerated when you run `make');
# (2) otherwise, pass the desired values on the `make' command line.
$(RECURSIVE_TARGETS):
@fail= failcom='exit 1'; \
for f in x $$MAKEFLAGS; do \
case $$f in \
*=* | --[!k]*);; \
*k*) failcom='fail=yes';; \
esac; \
done; \
dot_seen=no; \
target=`echo $@ | sed s/-recursive//`; \
list='$(SUBDIRS)'; for subdir in $$list; do \
echo "Making $$target in $$subdir"; \
if test "$$subdir" = "."; then \
dot_seen=yes; \
local_target="$$target-am"; \
else \
local_target="$$target"; \
fi; \
($(am__cd) $$subdir && $(MAKE) $(AM_MAKEFLAGS) $$local_target) \
|| eval $$failcom; \
done; \
if test "$$dot_seen" = "no"; then \
$(MAKE) $(AM_MAKEFLAGS) "$$target-am" || exit 1; \
fi; test -z "$$fail"
$(RECURSIVE_CLEAN_TARGETS):
@fail= failcom='exit 1'; \
for f in x $$MAKEFLAGS; do \
case $$f in \
*=* | --[!k]*);; \
*k*) failcom='fail=yes';; \
esac; \
done; \
dot_seen=no; \
case "$@" in \
distclean-* | maintainer-clean-*) list='$(DIST_SUBDIRS)' ;; \
*) list='$(SUBDIRS)' ;; \
esac; \
rev=''; for subdir in $$list; do \
if test "$$subdir" = "."; then :; else \
rev="$$subdir $$rev"; \
fi; \
done; \
rev="$$rev ."; \
target=`echo $@ | sed s/-recursive//`; \
for subdir in $$rev; do \
echo "Making $$target in $$subdir"; \
if test "$$subdir" = "."; then \
local_target="$$target-am"; \
else \
local_target="$$target"; \
fi; \
($(am__cd) $$subdir && $(MAKE) $(AM_MAKEFLAGS) $$local_target) \
|| eval $$failcom; \
done && test -z "$$fail"
tags-recursive:
list='$(SUBDIRS)'; for subdir in $$list; do \
test "$$subdir" = . || ($(am__cd) $$subdir && $(MAKE) $(AM_MAKEFLAGS) tags); \
done
ctags-recursive:
list='$(SUBDIRS)'; for subdir in $$list; do \
test "$$subdir" = . || ($(am__cd) $$subdir && $(MAKE) $(AM_MAKEFLAGS) ctags); \
done
ID: $(HEADERS) $(SOURCES) $(LISP) $(TAGS_FILES)
list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \
unique=`for i in $$list; do \
if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \
done | \
$(AWK) '{ files[$$0] = 1; nonempty = 1; } \
END { if (nonempty) { for (i in files) print i; }; }'`; \
mkid -fID $$unique
tags: TAGS
TAGS:
TAGS: tags-recursive $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \
$(TAGS_FILES) $(LISP)
set x; \
here=`pwd`; \
if ($(ETAGS) --etags-include --version) >/dev/null 2>&1; then \
include_option=--etags-include; \
empty_fix=.; \
else \
include_option=--include; \
empty_fix=; \
fi; \
list='$(SUBDIRS)'; for subdir in $$list; do \
if test "$$subdir" = .; then :; else \
test ! -f $$subdir/TAGS || \
set "$$@" "$$include_option=$$here/$$subdir/TAGS"; \
fi; \
done; \
list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \
unique=`for i in $$list; do \
if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \
done | \
$(AWK) '{ files[$$0] = 1; nonempty = 1; } \
END { if (nonempty) { for (i in files) print i; }; }'`; \
shift; \
if test -z "$(ETAGS_ARGS)$$*$$unique"; then :; else \
test -n "$$unique" || unique=$$empty_fix; \
if test $$# -gt 0; then \
$(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \
"$$@" $$unique; \
else \
$(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \
$$unique; \
fi; \
fi
ctags: CTAGS
CTAGS:
CTAGS: ctags-recursive $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \
$(TAGS_FILES) $(LISP)
list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \
unique=`for i in $$list; do \
if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \
done | \
$(AWK) '{ files[$$0] = 1; nonempty = 1; } \
END { if (nonempty) { for (i in files) print i; }; }'`; \
test -z "$(CTAGS_ARGS)$$unique" \
|| $(CTAGS) $(CTAGSFLAGS) $(AM_CTAGSFLAGS) $(CTAGS_ARGS) \
$$unique
GTAGS:
here=`$(am__cd) $(top_builddir) && pwd` \
&& $(am__cd) $(top_srcdir) \
&& gtags -i $(GTAGS_ARGS) "$$here"
distclean-tags:
-rm -f TAGS ID GTAGS GRTAGS GSYMS GPATH tags
distdir: $(DISTFILES)
@srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \
@ -309,19 +547,48 @@ distdir: $(DISTFILES)
|| exit 1; \
fi; \
done
@list='$(DIST_SUBDIRS)'; for subdir in $$list; do \
if test "$$subdir" = .; then :; else \
test -d "$(distdir)/$$subdir" \
|| $(MKDIR_P) "$(distdir)/$$subdir" \
|| exit 1; \
fi; \
done
@list='$(DIST_SUBDIRS)'; for subdir in $$list; do \
if test "$$subdir" = .; then :; else \
dir1=$$subdir; dir2="$(distdir)/$$subdir"; \
$(am__relativize); \
new_distdir=$$reldir; \
dir1=$$subdir; dir2="$(top_distdir)"; \
$(am__relativize); \
new_top_distdir=$$reldir; \
echo " (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) top_distdir="$$new_top_distdir" distdir="$$new_distdir" \\"; \
echo " am__remove_distdir=: am__skip_length_check=: am__skip_mode_fix=: distdir)"; \
($(am__cd) $$subdir && \
$(MAKE) $(AM_MAKEFLAGS) \
top_distdir="$$new_top_distdir" \
distdir="$$new_distdir" \
am__remove_distdir=: \
am__skip_length_check=: \
am__skip_mode_fix=: \
distdir) \
|| exit 1; \
fi; \
done
check-am: all-am
check: check-am
check: check-recursive
all-am: Makefile
installdirs:
install: install-am
install-exec: install-exec-am
install-data: install-data-am
uninstall: uninstall-am
installdirs: installdirs-recursive
installdirs-am:
install: install-recursive
install-exec: install-exec-recursive
install-data: install-data-recursive
uninstall: uninstall-recursive
install-am: all-am
@$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
installcheck: installcheck-am
installcheck: installcheck-recursive
install-strip:
$(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \
@ -338,86 +605,119 @@ distclean-generic:
maintainer-clean-generic:
@echo "This command is intended for maintainers to use"
@echo "it deletes files that may require special tools to rebuild."
clean: clean-am
clean: clean-recursive
clean-am: clean-generic clean-libtool mostlyclean-am
clean-am: clean-generic clean-libtool clean-local mostlyclean-am
distclean: distclean-am
distclean: distclean-recursive
-rm -f Makefile
distclean-am: clean-am distclean-generic
distclean-am: clean-am distclean-generic distclean-tags
dvi: dvi-am
dvi: dvi-recursive
dvi-am:
html: html-am
html: html-recursive
html-am:
info: info-am
info: info-recursive
info-am:
install-data-am:
install-dvi: install-dvi-am
install-dvi: install-dvi-recursive
install-dvi-am:
install-exec-am:
install-html: install-html-am
install-html: install-html-recursive
install-html-am:
install-info: install-info-am
install-info: install-info-recursive
install-info-am:
install-man:
install-pdf: install-pdf-am
install-pdf: install-pdf-recursive
install-pdf-am:
install-ps: install-ps-am
install-ps: install-ps-recursive
install-ps-am:
installcheck-am:
maintainer-clean: maintainer-clean-am
maintainer-clean: maintainer-clean-recursive
-rm -f Makefile
maintainer-clean-am: distclean-am maintainer-clean-generic
mostlyclean: mostlyclean-am
mostlyclean: mostlyclean-recursive
mostlyclean-am: mostlyclean-generic mostlyclean-libtool
pdf: pdf-am
pdf-am:
ps: ps-am
ps: ps-recursive
ps-am:
uninstall-am:
.MAKE: install-am install-strip
.MAKE: $(RECURSIVE_CLEAN_TARGETS) $(RECURSIVE_TARGETS) ctags-recursive \
install-am install-strip tags-recursive
.PHONY: all all-am check check-am clean clean-generic clean-libtool \
distclean distclean-generic distclean-libtool distdir dvi \
dvi-am html html-am info info-am install install-am \
install-data install-data-am install-dvi install-dvi-am \
install-exec install-exec-am install-html install-html-am \
install-info install-info-am install-man install-pdf \
install-pdf-am install-ps install-ps-am install-strip \
installcheck installcheck-am installdirs maintainer-clean \
.PHONY: $(RECURSIVE_CLEAN_TARGETS) $(RECURSIVE_TARGETS) CTAGS GTAGS \
all all-am check check-am clean clean-generic clean-libtool \
clean-local ctags ctags-recursive distclean distclean-generic \
distclean-libtool distclean-tags distdir dvi dvi-am html \
html-am info info-am install install-am install-data \
install-data-am install-dvi install-dvi-am install-exec \
install-exec-am install-html install-html-am install-info \
install-info-am install-man install-pdf install-pdf-am \
install-ps install-ps-am install-strip installcheck \
installcheck-am installdirs installdirs-am maintainer-clean \
maintainer-clean-generic mostlyclean mostlyclean-generic \
mostlyclean-libtool pdf pdf-am ps ps-am uninstall uninstall-am
mostlyclean-libtool pdf pdf-am ps ps-am tags tags-recursive \
uninstall uninstall-am
all: doc
doc: @DOC_BUILD_LIST@
pdf: $(ASCIIDOC_PDF)
# also build the HTML manpages with these targets
html-single: $(ASCIIDOC_HTML_SINGLE)
html-chunked: $(ASCIIDOC_HTML_CHUNKED)
@HAVE_ASCIIDOC_TRUE@website: html-chunked pdf
@HAVE_ASCIIDOC_FALSE@website:
@HAVE_ASCIIDOC_FALSE@ @echo "Not building website documentation since 'asciidoc' was not found."
clean-local:
rm -rf *.pdf *.html *.chunked docbook-xsl.css
user-manual.html user-manual.chunked user-manual.pdf: $(FULL_USER_MANUAL_DEPS)
developer-guide.html developer-guide.chunked developer-guide.pdf: $(FULL_DEVELOPER_GUIDE_DEPS)
packager-guide.html packager-guide.chunked packager-guide.pdf: packager-guide.txt asciidoc.conf
.txt.html:
$(A2X) $(A2X_COMMON_OPTS) --attribute=xhtml11_format --format=xhtml $<
.txt.chunked:
$(A2X) $(A2X_COMMON_OPTS) --attribute=chunked_format --format=chunked $<
.txt.pdf: docinfo.xml
$(A2X) $(A2X_COMMON_OPTS) --attribute=pdf_format --format=pdf -a docinfo1 $<
.PHONY: html html-single pdf website
# Tell versions [3.59,3.63) of GNU make to not export all variables.
# Otherwise a system limit (for SysV at least) may be exceeded.
.NOEXPORT:

9
docs/README
View file

@ -1,9 +0,0 @@
When creating files in here, use the following 4 headers:
Desc: A brief description of the document
File: The filename (this is for tracking which one is the original)
Date: The date of last modification
Auth: The author, i.e. "First Last <foo@example.com>".
Note: anything in the form <.*@.*> will be removed when converted to HTML
to reduce the number of e-mail addresses harvested from the web servers.

150
docs/acknowledgements.txt Normal file
View file

@ -0,0 +1,150 @@
ifndef::external_title[]
Acknowledgements
================
endif::external_title[]
This project is the result of years of work by many individuals and companies.
Many people have written or tweaked the software; the drivers, clients, server
and documentation have all received valuable attention from numerous sources.
Many of them are listed within the source code, AUTHORS file, release notes, and
mailing list archives, but some prefer to be anonymous.
This software would not be possible without their help.
The NUT Team
------------
Active members
~~~~~~~~~~~~~~
- Arnaud Quette: project leader (since 2005), Debian packager and jack of all trades
- Arjen de Korte: senior lieutenant
- Charles Lepple: senior lieutenant
- Kjell Claesson: senior developer
- Alexander Gordeev: junior developer
- David Goncalves: Python developer
- Eric S. Raymond: Documentation consultant
- Oden Eriksson: Mandriva packager
- Stanislav Brabec: Novell / Suse packager
- Michal Hlavinka: Redhat packager
Retired members
~~~~~~~~~~~~~~~
- Russell Kroll: Founder, and project leader from 1996 to 2005
- Peter Selinger: senior lieutenant
- Carlos Rodrigues: author of the "megatec" drivers, removing the numerous
drivers for Megatec / Q1 protocol. These drivers have now been replaced by
blazer_ser and blazer_usb
- Niels Baggesen: ported and heavily extended upscode2 to NUT 2.0 driver model
- Niklas Edmundsson: has worked on 3-phase support, and upscode2 updates
- Martin Loyer: has worked a bit on mge-utalk
- Jonathan Dion: MGE internship (summer 2006), who has worked on configuration
- Doug Reynolds: has worked on CyberPower support (powerpanel driver)
- Jon Gough: has worked on porting the megatec driver to USB (megatec_usb)
- Dominique Lallement: Consultant (chairman of the USB/HID PDC Forum)
- Julius Malkiewicz: junior developer
- Tomas Smetana: former Redhat packager (2007-2008)
[[Eaton]]
Our main supporter: Eaton
-------------------------
Through the acquisition of MGE Office Protection Systems (a carve out of
the MGE UPS SYSTEMS small systems, up to 10 KVA), Eaton has been supporting
NUT, and more generally the Free/Libre Opensource Software Community
since around 2002.
This support includes the following actions:
- providing extensive technical documents (Eaton protocols library),
- providing units to developers of NUT and related projects,
- hosting the networkupstools.org webserver,
- providing artwork,
- promoting NUT in general.
For more detailed information on Eaton's Opensource commitment, please refer to
link:http://opensource.eaton.com[Eaton Opensource website].
Supporting manufacturers
------------------------
UPS manufacturers
~~~~~~~~~~~~~~~~~
- link:http://powerquality.eaton.com[Eaton], our main supporter, as presented in
the <<Eaton,above section>>.
- link:http://www.gamatronic.com[Gamatronic], through Nadav Moskovitch, has
revived the 'sec' driver (as gamatronic), and expanded a bit genericups for its
UPSs with alarm interface.
- link:http://www.microdowell.com[Microdowell], through Elio Corbolante, has
created the 'microdowell' driver to support the Enterprise Nxx/Bxx serial devices.
They also proposes NUT as an alternative to its software for
link:http://www.microdowell.com/fra/download.html[Linux / Unix].
- link:http://pcmups.com.tw[Powercom], through Alexey Morozov, has provided
link:ups-protocol.html[extensive information] on its USB/HID devices, along
with development units.
Appliances manufacturers
~~~~~~~~~~~~~~~~~~~~~~~~
- link:http://www.opengear.com[OpenGear] has worked with NUT's leader to
successfully develop and integrate PDU support. Opengear, through Scott Burns,
and Robert Waldie, has submitted several patches.
Other contributors
------------------
- Pavel Korensky's original apcd provided the inspiration for pursuing APC's
smart protocol in 1996
- Eric Lawson provided scans of the OneAC protocol
- John Marley used OCR software to transform the SEC protocol scans into a HTML
document
- Chris McKinnon scanned and converted the Fortress protocol documentation
- Tank provided documentation on the Belkin/Delta protocol
- Potrans provided a Fenton PowerPal 600 (P series) for development of the
safenet driver.
Older entries (before 2005)
---------------------------
- MGE UPS SYSTEMS was the previous NUT sponsor. They provided protocols
information, many units for development of NUT-related projects.
Several drivers such as mge-utalk, mge-shut, snmp-ups, hidups, and usbhid-ups
are the result of this collaboration, in addition to the WMNut, MGE HID Parser
the libhid projects, ... through Arnaud.
All the MGE supporters have now gone with Eaton (through MGE Office
Protection Systems), which is the new NUT sponsor.
- Fenton Technologies contributed a PowerPal 660 to the project. Their open
stance and quick responses to technical inquiries were appreciated for
making the development of the fentonups driver possible.
Fenton has since been acquired by link:http://www.metapo.com[Metapo].
- Bo Kersey of link:http://www.vircio.com[VirCIO] provided a Best Power Fortress
750 to facilitate the bestups driver.
- Invensys Energy Systems provided the SOLA/Best "Phoenixtec" protocol
document. SOLA has since been acquired by Eaton.
- PowerKinetics technical support provided documentation on their MiniCOL
protocol, which is archived in the NUT protocol library.
PowerKinetics was acquired by the link:http://www.jst.cc[JST Group] in June 2003.
- link:http://www.cyberpowersystems.com[Cyber Power Systems] contributed a
700AVR model for testing and development of the cyberpower driver.
- link:http://www.liebert.com[Liebert Corporation] supplied serial test boxes
and a UPStation GXT2 with the Web/SNMP card for development of the liebert
driver and expansion of the existing snmp-ups driver.
Liebert has since been acquired by link:http://www.emerson.com[Emerson].
NOTE: If a company or individual isn't listed here, then we probably don't have
enough information about the situation. Developers are requested to report vendor
contributions to the NUT team so this list may reflect their help.
If we have left you out, send us some mail.

32
docs/acpi.txt
View file

@ -1,32 +0,0 @@
Desc: Equivalence between ACPI and NUT variable naming
File: acpi.txt
Date: 30 September 2005
Auth: Arnaud Quette <aquette.dev@gmail.com>
This document presents an equivalence table between ACPI data
and NUT variable naming.
+-------------------------------------------------------+---------------------------------------+
|PowerSummary.CapacityMode | percent | +-------------------------------------------------------+---------------------------------------+
|PowerSummary.DesignCapacity | 100 | +-------------------------------------------------------+---------------------------------------+
|PowerSummary.FullChargeCapacity | 100 | +-------------------------------------------------------+---------------------------------------+
|PowerSummary.Rechargeable | true / yes / 1 | +-------------------------------------------------------+---------------------------------------+
|PowerSummary.ConfigVoltage | output.voltage.nominal | +-------------------------------------------------------+---------------------------------------+
|PowerSummary.WarningCapacityLimit | ? battery.charge.low | +-------------------------------------------------------+---------------------------------------+
|PowerSummary.RemainingCapacityLimit | battery.charge.low | +-------------------------------------------------------+---------------------------------------+
|PowerSummary.CapacityGranularity1 | ? | +-------------------------------------------------------+---------------------------------------+
|PowerSummary.CapacityGranularity2 | ? | +-------------------------------------------------------+---------------------------------------+
|PowerSummary.iProduct | ups.model | +-------------------------------------------------------+---------------------------------------+
|PowerSummary.iSerialNumber | ups.serial | +-------------------------------------------------------+---------------------------------------+
|PowerSummary.iDeviceChemistry | battery.type | +-------------------------------------------------------+---------------------------------------+
|PowerSummary.iOEMInformation | ? | +-------------------------------------------------------+---------------------------------------+
|PowerSummary.Discharging | ups.status = DISCHRG | +-------------------------------------------------------+---------------------------------------+
|PowerSummary.Charging | ups.status = CHRG | +-------------------------------------------------------+---------------------------------------+
|PowerSummary.BelowRemainingCapacityLimit | ups.status = LB | +-------------------------------------------------------+---------------------------------------+
|PowerSummary.Current | ? output.current | +-------------------------------------------------------+---------------------------------------+
|PowerSummary.RemainingCapacity | battery.charge | +-------------------------------------------------------+---------------------------------------+
|PowerSummary.Voltage | output.voltage | +-------------------------------------------------------+---------------------------------------+
|PowerSummary.RemainingCapacityLimit | battery.charge.low | +-------------------------------------------------------+---------------------------------------+
| PowerSummary.ACPresent | ups.status = OL |
+-------------------------------------------------------+---------------------------------------+

55
docs/asciidoc.conf Normal file
View file

@ -0,0 +1,55 @@
## NUT macros: linkman, linkdoc
#
# Usage: linkman:command[manpage-section]
# This macro allows to handle variable manpage location, depending on the
# document type
#
# Note, {0} is the manpage section, while {target} is the command.
#
# Example: linkman:ups.conf[5]
#
# Show NUT link as: <command>(<section>); if section is defined, else just show
# the command.
#
################################################################################
#
# Usage: linkdoc:document[display title,[anchor]]
# This macro allows to handle variable NUT documentation location, depending
# on the document type
#
# Note, {1} is the display title, {2} is the optional anchor name,
# {0} is the whole set of args ({1}...{n}) and {target} is the
# base document name.
# Example:
# linkdoc:user-manual[user manual,NUT_Security]
# linkdoc:developer-guide[developer guide,_status_data]
[macros]
(?su)[\\]?(?P<name>linkman):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
(?su)[\\]?(?P<name>linkdoc):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
ifdef::basebackend-docbook[]
ifdef::xhtml11_format[]
[linkman-inlinemacro]
<ulink url="man/{target}.html">{target}{0?({0})}</ulink>
[linkdoc-inlinemacro]
<ulink url="{target}.html{2?#{2}}">{1}</ulink>
endif::xhtml11_format[]
# FIXME: linkdoc does not support 'anchor'
ifdef::chunked_format[]
[linkman-inlinemacro]
<ulink url="../man/{target}.html">{target}{0?({0})}</ulink>
[linkdoc-inlinemacro]
<ulink url="../{target}.chunked/index.html">{1}</ulink>
endif::chunked_format[]
# PDF output points online versions
# FIXME: linkdoc does not support 'anchor'
ifdef::pdf_format[]
[linkman-inlinemacro]
<ulink url="http://www.networkupstools.org/docs/man/{target}.html">{target}{0?({0})}</ulink>
[linkdoc-inlinemacro]
<ulink url="{target}.pdf">{1}</ulink>
endif::pdf_format[]
endif::basebackend-docbook[]

68
docs/big-servers.txt
View file

@ -1,68 +0,0 @@
Desc: Typical setups for big servers
File: big-servers.txt
Date: 14 March 2004
Auth: Russell Kroll <rkroll@exploits.org>
By using multiple MONITOR statements in upsmon.conf, you can configure
an environment where a large machine with redundant power monitors
multiple separate UPSes. For the examples in this document, I will use
a HP NetServer LH4 in the stock configuration with 3 of the 4 power
supplies installed.
Compared to some systems, the LH4 is unusual because it has common power
cords for multiple power supplies. One cord feeds two supplies. As a
result, each UPS drives two of the power supplies, so losing that UPS
affects both at the same time.
For our examples, UPS "Alpha" is connected to the cord that drives the
two power supplies, and ups "Beta" is connected to the other with just a
single power supply.
Since the server needs two supplies to stay alive, we can lose "Beta" at
any time, but losing "Alpha" is a showstopper. We make a note of them
when configuring upsmon:
MONITOR ups-alpha@myhost 2 monuser mypass master
MONITOR ups-beta@myhost 1 monuser mypass master
MINSUPPLIES 2
With that configuration, upsmon will only shut down when Alpha reaches
a critical (on battery + low battery) condition, since Beta by itself
is not enough to keep the system running. Beta, on the other hand,
can go up and down as much as it wants and nothing will happen as long
as the other one keeps working.
The MINSUPPLIES line tells upsmon that we need at least 2 power supplies
to be receiving power from a good UPS (on line or on battery, just not
on battery and low battery).
Adding redundancy
=================
The above example assumed the stock hardware configuration. Let's say
we have successfully cajoled the boss into providing the money for a
fourth power supply. Now both power cords run two power supplies, and
the system is maxed out in terms of redundancy.
The upsmon.conf must be updated to reflect this:
MONITOR ups-alpha@myhost 2 monuser mypass master
MONITOR ups-beta@myhost 2 monuser mypass master
MINSUPPLIES 2
Beta is now driving two power supplies, so we upgrade its power value.
This means that either Alpha *or* Beta can totally shut down and the
server will be able to keep running.
As an added bonus, this means you can move a running server from one UPS
to another without bringing it down since the minimum power will be
provided at all times.
Other configurations
====================
There are a lot of ways to handle this and they all come down to how many
power supplies, power cords and independent UPS connections you have. A
system with a 1:1 cord:supply ratio has more wires stuffed behind it, but
it's much easier to move things around since any given UPS drives a smaller
percentage of the overall power.

120
docs/cables.txt Normal file
View file

@ -0,0 +1,120 @@
ifdef::website[]
Cables
======
endif::website[]
APC
---
940-0024C clone
~~~~~~~~~~~~~~~
*From D. Stimits*
image::images/cables/940-0024C.jpg[APCC 940-0024C clone diagram]
NOTE: The original 940-0024C diagram was contributed by Steve Draper.
940-0024C clone for Macs
~~~~~~~~~~~~~~~~~~~~~~~~
*From Miguel Howard*
image::images/cables/mac-940-0024C.png[APCC 940-0024C clone cable for Macs]
Belkin
------
OmniGuard F6C***-RKM
~~~~~~~~~~~~~~~~~~~~
*From "Daniel"*
A straight-through RS-232 cable (with pins 2-7 connected through) should work
with the following models:
- F6C110-RKM-2U
- F6C150-RKM-2U
- F6C230-RKM-2U
- F6C320-RKM-3U
image::images/cables/belkin-f6cx-rkm-xu-cable.jpg[Belkin OmniGuard F6C***-RKM cable]
Eaton
-----
Documents in this section are provided courtesy of Eaton.
MGE Office Protection Systems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The two first cables also applies to MGE UPS SYSTEMS.
DB9-DB9 cable (ref 66049)
^^^^^^^^^^^^^^^^^^^^^^^^^
This is the standard serial cable, used on most units.
image::images/cables/mge-66049.png[DB9-DB9 cable]
DB9-RJ45 cable
^^^^^^^^^^^^^^
This cable is used on the more recent models, including Ellipse MAX, Protection
Station, ...
image::images/cables/mge-db9-rj45.jpg[DB9-RJ45 cable]
DB9-RJ12 cable
^^^^^^^^^^^^^^
This cable is used on some older Ellipse models.
image::images/cables/mge-db9-rj12.jpg[DB9-RJ12 cable]
Powerware LanSafe
~~~~~~~~~~~~~~~~~
image::images/cables/Lansafecable.jpg[Powerware LanSafe cable]
SOLA-330
~~~~~~~~
Just uses a normal serial cable, with pin 1-1 through to 9-9.
image::images/cables/SOLA-330.png[SOLA-330 cable]
HP - Compaq
-----------
Older Compaq UPS Family
~~~~~~~~~~~~~~~~~~~~~~~
This cable can be used with the following models:
T700, T1000, T1500, T1500j, T700h, T1000h, T1500h, R1500, R1500j,
R1500h, T2000, T2000j, T2400h, T2400h-NA, R3000 / R3000j, R3000h,
R3000h-International, R3000h-NA, R6000h-NA, R6000i, R6000j.
UPS PC 9 pin connector
1 --------- 3
2 --------- 2
4 -\
4 --------- 5 |
6 -/
6 --------- 7
Contributed by Kjell Claesson and Arnaud Quette.
Tripp-Lite
----------
*From Tripp-Lite, via Bryan Kolodziej*
This cable (black 73-0844 cable) is used on various models, using the "Lan 2.2 interface"
and the genericups driver (upstype=5).
image::images/cables/73-0724.png[73-0724 cable]

2
docs/cables/ge-imv-victron.txt
View file

@ -10,7 +10,7 @@ Data cable 1 for UPS:
Driver: victronups (newvictronups)
UPS PC 9 pin [2~connector
UPS PC 9 pin connector
1 --------- 3
2 --------- 2
5 --------- 5 GND

2
docs/cables/sms.txt
View file

@ -13,4 +13,4 @@ FEMEA DB9 MACHO DB9
- This cable is working with Manager III 1300 VA and 650 VA, SMS Ups's
- Jump in computer side pins 4/8 and conect to pin 1 in UPS side
- Use megatec driver from Nut Package
- Use NUT blazer_ser driver

110
docs/chroot.txt
View file

@ -1,110 +0,0 @@
Desc: chrooting and other forms of paranoia
File: chroot.txt
Date: 24 August 2003
Auth: Russell Kroll <rkroll@exploits.org>
It has been possible to run the drivers and upsd in a chrooted jail for
some time, but it involved a number of evil hacks. The 1.3 series adds
much saner chroot behavior, using BIND 9 as an inspiration.
The old way involved creating an entire tree, complete with libraries, a
shell (!), and many auxiliary files. This was hard to maintain and
could have become an interesting playground for an intruder. The new
way is minimal, and leaves little in the way of usable materials within
the jail.
This document assumes that you already have created at least one user
account for the software to use. If you're still letting it fall back
on "nobody", stop right here and go figure that out first. It also
assumes that you have everything else configured and running happily all
by itself.
Essentially, you need to create your configuration directory and state
path in their own little world, plus a special device or two.
For the purposes of this example, the chroot jail is /chroot/nut. The
programs have been built with the default prefix, so they are using
/usr/local/ups. First, create the confpath and bring over a few files.
mkdir -p /chroot/nut/usr/local/ups/etc
cd /chroot/nut/usr/local/ups/etc
cp -a /usr/local/ups/etc/upsd.users .
cp -a /usr/local/ups/etc/upsd.conf .
cp -a /usr/local/ups/etc/ups.conf .
I'm using 'cp -a' to maintain the permissions on those files.
Now bring over your state path, maintaining the same permissions as
before.
mkdir -p /chroot/nut/var/state
cp -a /var/state/ups /chroot/nut/var/state
Next we must put /etc/localtime inside the jail, or you may get very
strange readings in your syslog. You'll know you have this problem if
upsd shows up as UTC in the syslog while the rest of the system doesn't.
mkdir -p /chroot/nut/etc
cp /etc/localtime /chroot/nut/etc
Note that this is not "cp -a", since we want to copy the *content*, not
the symlink that it may be on some systems.
Finally, create a tiny bit of /dev so the programs can enter the
background properly - they redirect fds into the bit bucket to make sure
nothing else grabs 0-2.
mkdir -p /chroot/nut/dev
cp -a /dev/null /chroot/nut/dev
Try to start your driver(s) and make sure everything fires up as before.
upsdrvctl -r /chroot/nut -u nutdev start
Once your drivers are running properly, try starting upsd.
upsd -r /chroot/nut -u nutsrv
Check your syslog. If nothing is complaining, try running clients like
upsc and upsmon. If they seem happy, then you're done.
symlinks
--------
After you do this, you will have two copies of many things, like the
confpath and the state path. I recommend deleting the 'real'
/var/state/ups, replacing it with a symlink to
/chroot/nut/var/state/ups. That will let other programs reference the
.pid files without a lot of hassle.
You can also do this with your confpath and point /usr/local/ups/etc at
/chroot/nut/usr/local/ups/etc unless you're worried about something
hurting the files inside that directory. In that case, you should
maintain a 'master' copy and push it into the chroot path after
making changes.
upsdrvctl itself does not chroot, so the ups.conf still needs to be in
the usual confpath.
upsmon
------
This has not yet been applied to upsmon, since it can be quite
complicated when there are notifiers that need to be run. One
possibility would be for upsmon to have three instances:
- privileged root parent that listens for a shutdown command
- unprivileged child that listens for notify events
- unprivileged chrooted child that does network I/O
This one is messy, and may not happen for some time, if ever.
Config files
------------
You may now set chroot= and user= in the global section of ups.conf.
upsd chroots before opening any config files, so there is no way to
add support for that in upsd.conf at the present time.

62
docs/commands.txt
View file

@ -1,62 +0,0 @@
Desc: Commands sent to the UPS drivers
File: commands.txt
Date: 9 January 2004
Auth: Russell Kroll <rkroll@exploits.org>
upsd can call drivers to store values in read/write variables and to kick
off instant commands. This is how you register handlers for those events.
The driver core (drivers/main.c) has a structure called upsh. You
should populate it with function pointers in your upsdrv_initinfo()
function. Right now, there are only two possibilities:
- setvar = setting UPS variables (SET VAR protocol command)
- instcmd = instant UPS commands (INSTCMD protocol command)
SET
---
If your driver's function for handling variable set events is called
my_ups_set(), then you'd do this to add the pointer:
upsh.setvar = my_ups_set;
my_ups_set() will receive two parameters:
const char * - the variable being changed
const char * - the new value
You should return either STAT_SET_HANDLED if your driver recognizes the
command, or STAT_SET_UNKNOWN if it doesn't. Other possibilities will be
added at some point in the future.
INSTCMD
-------
This works just like the set process, with slightly different values
arriving from the server.
upsh.instcmd = my_ups_cmd;
Your function will receive two args:
const char * - the command name
const char * - (reserved)
You should return either STAT_INSTCMD_HANDLED or STAT_INSTCMD_UNKNOWN
depending on whether your driver can handle the requested command.
Notes
-----
Use strcasecmp. The command names arriving from upsd should be treated
without regards to case.
Responses
---------
Drivers will eventually be expected to send responses to commands.
Right now, there is no channel to get these back through upsd to
the client, so this is not implemented.
This will probably be implemented with a polling scheme in the clients.

64
docs/config-files.txt
View file

@ -1,64 +0,0 @@
Desc: Details about the configuration files
File: config-files.txt
Date: 30 April 2003
Auth: Russell Kroll <rkroll@exploits.org>
All configuration files within this package are parsed with a common
state machine, which means they all can use a number of extras described
in this file.
First, most of the programs use an uppercase word to declare a
configuration directive. This may be something like MONITOR, NOTIFYCMD,
or ACCESS. The case does matter here. "monitor" won't be recognized.
Next, the parser does not care about whitespace between words. If you
like to indent things with tabs or spaces, feel free to do it here.
If you need to set a value to something containing spaces, it has to be
contained within "quotes" to keep the parser from splitting up the line.
That is, you want to use something like this:
SHUTDOWNCMD "/sbin/shutdown -h +0"
Without the quotes, it would only see the first word on the line.
OK, so let's say you really need to embed that kind of quote within your
configuration directive for some reason. You can do that too.
NOTIFYCMD "/bin/notifyme -foo -bar \"hi there\" -baz"
In other words, \ can be used to escape the ".
Finally, for the situation where you need to put the \ character into your
string, you just escape it.
NOTIFYCMD "/bin/notifyme c:\\dos\\style\\path"
The \ can actually be used to escape any character, but you only really
need it for \, ", and # as they have special meanings to the parser.
# is the comment character. Anything after an unescaped # is ignored.
Something like this...
identity = my#1ups
... will actually turn into "identity = my", since the # stops the
parsing. If you really need to have a # in your configuration, then
escape it.
identity = my\#1ups
Much better.
Line spanning
=============
You can put a backslash at the end of the line to join it to the next
one. This creates one virtual line that is composed of more than one
physical line.
Also, if you leave the "" quote container open before a newline, it will
keep scanning until it reaches another one. If you see bizarre behavior
in your configuration files, check for an unintentional instance of
quotes spanning multiple lines.

798
docs/config-notes.txt Normal file
View file

@ -0,0 +1,798 @@
Configuration notes
===================
This chapter describe most of the configuration and use aspects of NUT,
including establishing communication with the device and configuring safe
shutdowns when the UPS battery runs out of power.
There are many programs and <<Features,features>> in this
package. You should check out the <<Overview,NUT Overview>>
and other accompanying documentation to see how it all works.
NOTE: NUT does not currently provide proper graphical configuration tools.
However, there is now support for linkdoc:developer-guide[Augeas,augeas_user].
Details about the configuration files
-------------------------------------
Generalities
~~~~~~~~~~~~
All configuration files within this package are parsed with a common
state machine, which means they all can use a number of extras described here.
First, most of the programs use an uppercase word to declare a
configuration directive. This may be something like MONITOR, NOTIFYCMD,
or ACCESS. The case does matter here. "monitor" won't be recognized.
Next, the parser does not care about whitespace between words. If you
like to indent things with tabs or spaces, feel free to do it here.
If you need to set a value to something containing spaces, it has to be
contained within "quotes" to keep the parser from splitting up the line.
That is, you want to use something like this:
SHUTDOWNCMD "/sbin/shutdown -h +0"
Without the quotes, it would only see the first word on the line.
OK, so let's say you really need to embed that kind of quote within your
configuration directive for some reason. You can do that too.
NOTIFYCMD "/bin/notifyme -foo -bar \"hi there\" -baz"
In other words, \ can be used to escape the ".
Finally, for the situation where you need to put the \ character into your
string, you just escape it.
NOTIFYCMD "/bin/notifyme c:\\dos\\style\\path"
The \ can actually be used to escape any character, but you only really
need it for \, ", and # as they have special meanings to the parser.
# is the comment character. Anything after an unescaped # is ignored.
Something like this...
identity = my#1ups
... will actually turn into "identity = my", since the # stops the
parsing. If you really need to have a # in your configuration, then
escape it.
identity = my\#1ups
Much better.
Line spanning
~~~~~~~~~~~~~
You can put a backslash at the end of the line to join it to the next
one. This creates one virtual line that is composed of more than one
physical line.
Also, if you leave the "" quote container open before a newline, it will
keep scanning until it reaches another one. If you see bizarre behavior
in your configuration files, check for an unintentional instance of
quotes spanning multiple lines.
Basic configuration
-------------------
This chapter describe the base configuration to establish communication with
the device.
This will be sufficient for PDU. But for UPS and SCD, you will also need to
configure <<UPS_shutdown,automatic shutdowns for low battery events>>.
image:images/simple.png[]
[[Driver_configuration]]
Driver configuration
~~~~~~~~~~~~~~~~~~~~
Create one section per UPS in /usr/local/ups/etc/ups.conf
To find out which driver to use, check the <<HCL,Hardware Compatibility List>>,
or data/driver.list.
Once you have picked a driver, create a section for your UPS in
ups.conf. You must supply values for "driver" and "port".
Some drivers may require other flags or settings. The "desc" value
is optional, but is recommended to provide a better description of
what your UPS is supporting.
A typical device without any extra settings looks like this:
[mydevice]
driver = mydriver
port = /dev/ttyS1
desc = "Workstation"
NOTE: USB drivers (usbhid-ups, bcmxcp_usb, tripplite_usb, blazer_usb and
richcomm_usb) are special cases and ignore the 'port' value.
You must still set this value, but it does not matter what you set
it to; a common and good practice is to set 'port' to *auto*, but you can
put whatever you like. If you only own one UBS UPS, the driver will
find it automatically. If you own more than one, refer to the driver's
manual page for more information on matching a specific device.
References: linkman:ups.conf[5],
linkman:nutupsdrv[8],
linkman:bcmxcp_usb[8],
linkman:blazer[8],
linkman:richcomm_usb[8],
linkman:tripplite_usb[8],
linkman:usbhid-ups[8]
[[Starting_drivers]]
Starting the driver(s)
~~~~~~~~~~~~~~~~~~~~~~
Start the driver(s) for your hardware:
/usr/local/ups/bin/upsdrvctl start
Make sure the driver doesn't report any errors. It should show a
few details about the hardware and then enter the background. You
should get back to the command prompt a few seconds later. For
reference, a successful start of the `usbhid-ups` driver looks like this:
# /usr/local/ups/bin/upsdrvctl start
Network UPS Tools - Generic HID driver 0.34 (2.4.1)
USB communication driver 0.31
Using subdriver: MGE HID 1.12
Detected EATON - Ellipse MAX 1100 [ADKK22008]
If the driver doesn't start cleanly, make sure you have picked the
right one for your hardware. You might need to try other drivers
by changing the "driver=" value in ups.conf.
Be sure to check the driver's man page to see if it needs any extra
settings in ups.conf to detect your hardware.
If it says "can't bind /var/state/ups/..." or similar, then your
state path probably isn't writable by the driver. Check the
<<StatePath,permissions and mode on that directory>>.
After making changes, try the <<Ownership, Ownership and permissions>> step again.
References: man pages: linkman:nutupsdrv[8], linkman:upsdrvctl[8]
Data server configuration (upsd)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Configure upsd, which serves data from the drivers to the clients.
First, edit upsd.conf to allow access to your client systems. By
default, upsd will only listen to localhost port 3493/tcp. If you want
to connect to it from other machines, you must specify each interface you
want upsd to listen on for connections, optionally with a port number.
LISTEN 127.0.0.1 3493
LISTEN ::1 3493
NOTE: Refer to the NUT user manual <<NUT_Security,security chapter>> for
information on how to access and secure upsd clients connections.
Next, create upsd.users. For now, this can be an empty file.
You can come back and add more to it later when it's time to
configure upsmon or run one of the management tools.
Do not make either file world-readable, since they both hold
access control data and passwords. They just need to be readable by
the user you created in the preparation process.
The suggested configuration is to chown it to root, chgrp it to the
group you created, then make it readable by the group.
chown root:nut upsd.conf upsd.users
chmod 0640 upsd.conf upsd.users
References: man pages: linkman:upsd.conf[5],
linkman:upsd.users[5],
linkman:upsd[8]
[[Starting_upsd]]
Starting the data server
~~~~~~~~~~~~~~~~~~~~~~~~
Start the network data server:
/usr/local/ups/sbin/upsd
Make sure it is able to connect to the driver(s) on your system.
A successful run looks like this:
# /usr/local/ups/sbin/upsd
Network UPS Tools upsd 2.4.1
listening on 127.0.0.1 port 3493
listening on ::1 port 3493
Connected to UPS [eaton]: usbhid-ups-eaton
upsd prints dots while it waits for the driver to respond. Your
system may print more or less depending on how many drivers you
have and how fast they are.
NOTE: if upsd says that it can't connect to a UPS or that the data
is stale, then your ups.conf is not configured correctly, or you
have a driver that isn't working properly. You must fix this before
going on to the next step.
Reference: man page: linkman:upsd[8]
Check the UPS data
~~~~~~~~~~~~~~~~~~
Status data
^^^^^^^^^^^
Make sure that the UPS is providing good status data.
/usr/local/ups/bin/upsc myupsname@localhost ups.status
You should see just one line in response:
OL
OL means your system is running on line power. If it says something
else (like OB - on battery, or LB - low battery), your driver was
probably misconfigured during the <<Driver_configuration, Driver configuration>>
step. If you reconfigure the driver, use 'upsdrvctl stop' to stop it, then
start it again as shown in the <<Starting_drivers, Starting driver(s)>> step.
Reference: man page: linkman:upsc[8]
All data
^^^^^^^^
Look at all of the status data which is being monitored.
/usr/local/ups/bin/upsc myupsname@localhost
What happens now depends on the kind of device and driver you have.
In the list, you should see ups.status with the same value you got
above. A sample run on a UPS (Eaton Ellipse MAX 1100) looks like this:
battery.charge: 100
battery.charge.low: 20
battery.runtime: 2525
battery.type: PbAc
device.mfr: EATON
device.model: Ellipse MAX 1100
device.serial: ADKK22008
device.type: ups
driver.name: usbhid-ups
driver.parameter.pollfreq: 30
driver.parameter.pollinterval: 2
driver.parameter.port: auto
driver.version: 2.4.1-1988:1990M
driver.version.data: MGE HID 1.12
driver.version.internal: 0.34
input.sensitivity: normal
input.transfer.boost.low: 185
input.transfer.high: 285
input.transfer.low: 165
input.transfer.trim.high: 265
input.voltage.extended: no
outlet.1.desc: PowerShare Outlet 1
outlet.1.id: 2
outlet.1.status: on
outlet.1.switchable: no
outlet.desc: Main Outlet
outlet.id: 1
outlet.switchable: no
output.frequency.nominal: 50
output.voltage: 230.0
output.voltage.nominal: 230
ups.beeper.status: enabled
ups.delay.shutdown: 20
ups.delay.start: 30
ups.firmware: 5102AH
ups.load: 0
ups.mfr: EATON
ups.model: Ellipse MAX 1100
ups.power.nominal: 1100
ups.productid: ffff
ups.serial: ADKK22008
ups.status: OL CHRG
ups.timer.shutdown: -1
ups.timer.start: -1
ups.vendorid: 0463
Reference: man page: linkman:upsc[8],
<<nut-names,NUT command and variable naming scheme>>
Startup scripts
~~~~~~~~~~~~~~~
NOTE: This step is not need if you installed from packages.
Edit your startup scripts, and make sure upsdrvctl and upsd are run every time
your system starts.
[[UPS_shutdown]]
Configuring automatic shutdowns for low battery events
------------------------------------------------------
The whole point of UPS software is to bring down the OS cleanly when you
run out of battery power. Everything else is roughly eye candy.
To make sure your system shuts down properly, you will need to perform some
additional configuration and run upsmon. Here are the basics.
[[Shutdown_design]]
Shutdown design
~~~~~~~~~~~~~~~
When your UPS batteries get low, the operating system needs to be brought
down cleanly. Also, the UPS load should be turned off so that all devices
that are attached to it are forcibly rebooted.
Here are the steps that occur when a critical power event happens:
1. The UPS goes on battery
2. The UPS reaches low battery (a "critical" UPS)
3. The upsmon master notices and sets "FSD" - the "forced shutdown"
flag to tell all slave systems that it will soon power down the load.
+
(If you have no slaves, skip to step 6)
4. upsmon slave systems see "FSD" and:
- generate a NOTIFY_SHUTDOWN event
- wait FINALDELAY seconds - typically 5
- call their SHUTDOWNCMD
- disconnect from upsd
5. The upsmon master system waits up to HOSTSYNC seconds (typically 15)
for the slaves to disconnect from upsd. If any are connected after
this time, upsmon stops waiting and proceeds with the shutdown
process.
6. The upsmon master:
- generates a NOTIFY_SHUTDOWN event
- waits FINALDELAY seconds - typically 5
- creates the POWERDOWNFLAG file - usually /etc/killpower
- calls the SHUTDOWNCMD
7. On most systems, init takes over, kills your processes, syncs and
unmounts some filesystems, and remounts some read-only.
8. init then runs your shutdown script. This checks for the
POWERDOWNFLAG, finds it, and tells the UPS driver(s) to power off
the load.
9. The system loses power.
10. Time passes. The power returns, and the UPS switches back on.
11. All systems reboot and go back to work.
How you set it up
~~~~~~~~~~~~~~~~~
[[NUT_user_creation]]
NUT user creation
^^^^^^^^^^^^^^^^^
Create a upsd user for upsmon to use while monitoring this UPS.
Edit upsd.users and create a new section. upsmon will connect
to upsd and use this user name (in brackets) and password to
authenticate. This example is for a user called "monuser":
[monuser]
password = mypass
upsmon master
# or upsmon slave
References: linkman:upsd[8], linkman:upsd.users[5]
Reloading the data server
^^^^^^^^^^^^^^^^^^^^^^^^^
Reload upsd. Depending on your configuration, you may be able to
do this without stopping upsd:
/usr/local/ups/sbin/upsd -c reload
If that doesn't work (check the syslog), just restart it:
/usr/local/ups/sbin/upsd -c stop
/usr/local/ups/sbin/upsd
NOTE: if you want to make reloading work later, see the entry in the
link:FAQ.html[FAQ] about starting upsd as a different user.
Power Off flag file
^^^^^^^^^^^^^^^^^^^
Set the POWERDOWNFLAG location for upsmon.
In upsmon.conf, add a POWERDOWNFLAG directive with a filename.
upsmon will create this file when the UPS needs to be powered off
during a power failure when low battery is reached.
We will test for the presence of this file in a later step.
POWERDOWNFLAG /etc/killpower
References: man pages: linkman:upsmon[8],
linkman:upsmon.conf[5]
Securing upsmon.conf
^^^^^^^^^^^^^^^^^^^^
The recommended setting is to have it owned by root:nut, then make it readable
by the group and not world. This file contains passwords that could be used by
an attacker to start a shutdown, so keep it secure.
chown root:nut upsmon.conf
chmod 0640 upsmon.conf
This step has been placed early in the process so you secure this file before
adding sensitive data in the next step.
Create a MONITOR directive for upsmon
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Edit upsmon.conf and create a MONITOR line with the UPS definition
(<upsname>@<hostname>), username and password from the <<NUT_user_creation, NUT user creation>>
step, and the master or slave setting.
If it's the master (i.e., it's connected to this UPS directly):
MONITOR myupsname@mybox 1 monuser mypass master
If it's just monitoring this UPS over the network, and some other system is the
master:
MONITOR myupsname@mybox 1 monuser mypass slave
The number "1" here is the power value. This should always be set to 1 unless
you have a very special (read: expensive) system with redundant power supplies.
In such cases, refer to the User Manual:
- <<BigServers,typical setups for big servers>>,
- <<DataRoom,typical setups for data rooms>>.
References: linkman:upsmon[8], linkman:upsmon.conf[5]
Define a SHUTDOWNCMD for upsmon
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Still in upsmon.conf, add a directive that tells upsmon how to shut down your
system. This example seems to work on most systems:
SHUTDOWNCMD "/sbin/shutdown -h +0"
Notice the presence of "quotes" here to keep it together.
If your system has special needs, you may want to set this to a script which
does local shutdown tasks before calling init.
Start upsmon
^^^^^^^^^^^^
/usr/local/ups/sbin/upsmon
If it complains about something, then check your configuration.
Checking upsmon
^^^^^^^^^^^^^^^
Look for messages in the syslog to indicate success. It should look something
like this:
May 29 01:11:27 mybox upsmon[102]: Startup successful
May 29 01:11:28 mybox upsd[100]: Client monuser@192.168.50.1
logged into UPS [myupsname]
Any errors seen here are probably due to an error in the config files of either
`upsmon` or `upsd`. You should fix them before continuing.
Startup scripts
^^^^^^^^^^^^^^^
NOTE: This step is not need if you installed from packages.
Edit your startup scripts, and add a call to `upsmon`.
Make sure `upsmon` starts when your system comes up. Do it after `upsdrvctl`
and `upsd`, or it will complain about not being able to contact the server.
You may delete the POWERDOWNFLAG in the startup scripts, but it is not
necessary. `upsmon` will clear that file for you when it starts.
NOTE: Init script examples are provide in the 'scripts' directory of
the NUT source tree, and in the various <<_binary_packages,packages>>
that exist.
Shutdown scripts
^^^^^^^^^^^^^^^^
NOTE: This step is not need if you installed from packages.
Edit your shutdown scripts, and add `upsdrvctl shutdown`.
You should configure your system to power down the UPS after the filesystems are
remounted read-only. Have it look for the presence of the POWERDOWNFLAG (from
linkman:upsmon.conf[5]), using this as an example:
--------------------------------------------------------------------------------
if (test -f /etc/killpower)
then
echo "Killing the power, bye!"
/usr/local/ups/bin/upsdrvctl shutdown
sleep 120
# uh oh... the UPS power-off failed
# you probably want to reboot here so you don't get stuck!
# *** see also the section on power races in the FAQ! ***
fi
--------------------------------------------------------------------------------
[WARNING]
================================================================================
- Be careful that upsdrvctl command will probably power off your machine.
Don't use it unless your system is ready to be halted by force.
If you run RAID, read the <<_raid_warning,RAID warning>> below!
- Make sure the filesystem(s) containing upsdrvctl, ups.conf and your UPS
driver(s) are mounted (possibly in read-only mode) when the system gets to this
point. Otherwise it won't be able to figure out what to do.
================================================================================
[[Testing_shutdowns]]
Testing shutdowns
^^^^^^^^^^^^^^^^^
UPS equipment varies from manufacturer to manufacturer and even within
model lines. You should test the shutdown sequence on your systems before
leaving them unattended. A successful sequence is one where the OS halts
before the battery runs out, and the system restarts when power returns.
The first step is to see how upsdrvctl will behave without actually turning off
power. To do so, use the '-t' argument:
/usr/local/ups/bin/upsdrvctl -t shutdown
It will display the sequence without actually calling the drivers.
You can finally test a forced shutdown sequence (FSD) using:
/usr/local/ups/sbin/upsmon -c fsd
This will execute a full shutdown sequence, as presented in
<<Shutdown_design,Shutdown design>>, starting from the 3rd step.
If everything works correctly, the computer will be forcibly powered
off, may remain off for a few seconds to a few minutes (depending on
the driver and UPS type), then will power on again.
If your UPS just sits there and never resets the load, you are vulnerable
to a power race and should add the "reboot after timeout" hack at the very
least.
Also refer to the section on power races in the link:FAQ.html[FAQ].
Using suspend to disk
~~~~~~~~~~~~~~~~~~~~~
Support for suspend to RAM and suspend to disk has been available in
the Linux kernel for a while now. For obvious reasons, suspending to
RAM isn't particularly useful when the UPS battery is getting low,
but suspend to disk may be an interesting concept.
This approach minimizes the amount of disruption which would be caused
by an extended outage. The UPS goes on battery, then reaches low
battery, and the system takes a snapshot of itself and halts. Then it
is turned off and waits for the power to return.
Once the power is back, the system reboots, pulls the snapshot back in,
and keeps going from there. If the user happened to be away when it
happened, they may return and have no idea that their system actually
shut down completely in the middle.
In order for this to work, you need to shutdown NUT (UPS driver, upsd
server and upsmon client) in the suspend script and start them again in
the resume script. Don't try to keep them running. The upsd server
will latch the FSD state (so it won't be useable after resuming) and so
will the upsmon client. Some drivers may work after resuming, but many
don't and some UPS'es will require re-initialization, so it's best not
to keep this running either.
After stopping driver, server and client you'll have to send the UPS
the command to shutdown only if the POWERDOWNFLAG is present. Note
that most likely you'll have to allow for a grace period after sending
'upsdrvctl shutdown' since the system will still have to take a
snapshot of itself after that. Not all drivers support this, so before
going down this road, make sure that the one you're using does.
RAID warning
~~~~~~~~~~~~
If you run any sort of RAID equipment, make sure your arrays are either halted
(if possible) or switched to "read-only" mode. Otherwise you may suffer a long
resync once the system comes back up.
The kernel may not ever run its final shutdown procedure, so you must take care
of all array shutdowns in userspace before upsdrvctl runs.
If you use software RAID (md) on Linux, get mdadm and try using
'mdadm --readonly' to put your arrays in a safe state. This has to
happen after your shutdown scripts have remounted the filesystems.
On hardware RAID or other kernels, you have to do some detective work. It may
be necessary to contact the vendor or the author of your driver to find out
how to put the array in a state where a power loss won't leave it "dirty".
Our understanding is that most if not all RAID devices on Linux will be fine
unless there are pending writes. Make sure your filesystems are remounted
read-only and you should be covered.
[[DataRoom]]
Typical setups for enterprise networks and data rooms
-----------------------------------------------------
The split nature of this UPS monitoring software allows a wide variety of
power connections. This chapter will help you identify how things should
be configured using some general descriptions.
There are two main elements:
1. There's a UPS attached to a communication (serial, USB or network) port on
this system.
2. This system depends on a UPS for power.
You can play "mix and match" with those two to arrive at these descriptions
for individual hosts:
- A: 1 but not 2
- B: 2 but not 1
- C: 1 and 2
A small to medium sized data room usually has one C and a bunch of Bs.
This means that there's a system (type C) hooked to the UPS which depends
on it for power. There are also some other systems in there (type B)
which depend on that same UPS for power, but aren't directly connected to
it.
Larger data rooms or those with multiple UPSes may have several "clusters"
of the "single C, many Bs" depending on how it's all wired.
Finally, there's a special case. Type A systems are connected to a UPS's
serial port, but don't depend on it for power. This usually happens when
a UPS is physically close to a box and can reach the serial port, but
the wiring is such that it doesn't actually feed it.
Once you identify a system's type, use this list to decide which of the
programs need to be run for monitoring:
- A: driver and upsd
- B: upsmon (as slave)
- C: driver, upsd, and upsmon (as master)
To further complicate things, you can have a system that is hooked to
multiple UPSes, but only depends on one for power. This particular
situation makes it an "A" relative to one UPS, and a "C" relative to the
other. The software can handle this - you just have to tell it what to do.
NOTE: NUT can also serve as a data proxy to increase the number of clients,
or share the communication load between several upsd instances.
image:images/advanced.png[]
If you are running large server-class systems that have more than one
power feed, see the next section for information on how to handle it
properly.
[[BigServers]]
Typical setups for big servers with UPS redundancy
--------------------------------------------------
By using multiple MONITOR statements in upsmon.conf, you can configure an
environment where a large machine with redundant power monitors multiple
separate UPSes.
image:images/bigbox.png[]
Example configuration
~~~~~~~~~~~~~~~~~~~~~
For the examples in this section, we will use a server with four power supplies
installed.
Two UPS, 'Alpha' and 'Beta', are each driving two of the power supplies.
This means that either 'Alpha' *or* 'Beta' can totally shut down and the
server will be able to keep running.
The upsmon.conf configuration that reflect this is the following:
MONITOR ups-alpha@myhost 2 monuser mypass master
MONITOR ups-beta@myhost 2 monuser mypass master
MINSUPPLIES 2
With that configuration, upsmon will only shut down when both UPS reaches
a critical (on battery + low battery) condition, since 'Alpha' and 'Beta'
provide the same power value.
As an added bonus, this means you can move a running server from one UPS
to another (for maintenance purpose for example) without bringing it down since
the minimum power will be provided at all times.
The MINSUPPLIES line tells upsmon that we need at least 2 power supplies
to be receiving power from a good UPS (on line or on battery, just not
on battery and low battery).
NOTE: we could have used a 'Power Value' of 1 for both UPS, and MINSUPPLIES
set to 1 too. These values are purely arbitrary, so you are free to use your
own rules. Here, we have linked these values to the number of power supplies
that each UPS is feeding (2).
Multiple UPS shutdowns ordering
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you have multiple UPSes connected to your system, chances are that you
need to shut them down in a specific order. The goal is to shut down
everything but the one keeping upsmon alive at first, then you do that one
last.
To set the order in which your UPSes receive the shutdown commands, define
the 'sdorder' value in your ups.conf.
[bigone]
driver = usbhid-ups
port = auto
sdorder = 2
[littleguy]
driver = mge-shut
port = /dev/ttyS0
sdorder = 1
[misc]
driver = blazer_ser
port = /dev/ttyS1
sdorder = 0
The order runs from 0 to the highest number available. So, for this
configuration, the order of shutdowns would be 'misc', 'littleguy', and then
'bigone'.
NOTE: If you have a UPS that shouldn't be shutdown when running 'upsdrvctl
shutdown', set the *sdorder* to *-1*.
Other redundancy configurations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are a lot of ways to handle redundancy and they all come down to how many
power supplies, power cords and independent UPS connections you have. A
system with a 1:1 cord:supply ratio has more wires stuffed behind it, but
it's much easier to move things around since any given UPS drives a smaller
percentage of the overall power.
More information can be found in the linkdoc:user-manual[NUT user manual],
and the various link:man/index.html[user manual pages].

462
docs/configure.txt
View file

@ -1,327 +1,345 @@
Desc: Configure options
File: configure.txt
Date: 24 December 2008
Auth: Russell Kroll <rkroll@exploits.org>
Auth: Peter Selinger <selinger@sourceforge.net>
Auth: Arnaud Quette <aquette.dev@gmail.com>
ifdef::website[]
Configure options
=================
endif::website[]
There are a few options that can be given to configure to tweak compiles.
There are a few options that can be given to configure to tweak compiles.
See also "./configure --help" for a current and complete listing.
Contents:
=========
Driver selection
----------------
1. Driver selection
2. Optional features
3. Other configuration options
4. Installation directories
5. Directories used by NUT at run-time
6. Things the compiler might need to find
--with-serial
1. Driver selection:
====================
Build and install the serial drivers (default: yes)
--with-serial
--with-usb
Build and install the serial drivers (default: yes)
Build and install the USB drivers (default: auto-detect)
Note that you need to install the libusb development package or files.
--with-usb
--with-snmp
Build and install the USB drivers (default: auto-detect)
Note that you need to install the libusb development package or files.
Build and install the SNMP drivers (default: auto-detect)
Note that you need to install libsnmp development package or files.
--with-snmp
--with-neon
Build and install the SNMP drivers (default: auto-detect)
Note that you need to install libsnmp development package or files.
Build and install the XML drivers (default: auto-detect)
Note that you need to install neon development package or files.
--with-neon
--with-drivers=<driver>,<driver>,...
Build and install the XML drivers (default: auto-detect)
Note that you need to install neon development package or files.
Specify exactly which driver or drivers to build and install (this
works for serial, usb, and snmp drivers, and overrides the
preceding three options).
--with-drivers=<driver>,<driver>,...
As of the time of this writing (2010), there are 46 UPS drivers
available. Most users will only need one, a few will need two or
three, and very few people will need all of them.
Specify exactly which driver or drivers to build and install (this
works for serial, usb, and snmp drivers, and overrides the
preceding three options).
As of the time of this writing (2006), there are 47 UPS drivers
available. Most users will only need one, a few will need two or
three, and very few people will need all of them.
To save time during the compile and disk space later on, you can
use this option to just build and install a subset of the drivers.
To select apcsmart and usbhid-ups, you'd do this:
To save time during the compile and disk space later on, you can
use this option to just build and install a subset of the drivers.
To select mge-shut and usbhid-ups, you'd do this:
--with-drivers=apcsmart,usbhid-ups
If you need to build more drivers later on, you will need to rerun
configure with a different list. To make it build all of the
drivers from scratch again, run 'make clean' before starting.
If you need to build more drivers later on, you will need to rerun
configure with a different list. To make it build all of the
drivers from scratch again, run 'make clean' before starting.
2. Optional features:
=====================
--with-doc=<output-format(s)> (default: no)
--with-cgi (default: no)
Build and install NUT documentation file(s).
The possible values are "html-single" for single page HTML, "html-chunked"
for multi pages HTML, "pdf" for a PDF file or "auto" to build all the
possible previous documentation formats.
Verbose output can be enabled using: ASCIIDOC_VERBOSE=-v make
Build and install the optional CGI programs, HTML files, and sample
CGI configuration files. This is not enabled by default, as they
are only useful on web servers. See data/html/README for additional
information on how to set up CGI programs.
This feature requires AsciiDoc 8.6.3 (http://www.methods.co.nz/asciidoc).
--with-lib (default: no)
Build and install the upsclient library and header files.
Optional features
-----------------
--with-all (no default)
--with-cgi (default: no)
Build and install all of the above (the serial, USB, and SNMP
drivers, the CGI programs and HTML files, and the upsclient
library).
Build and install the optional CGI programs, HTML files, and sample
CGI configuration files. This is not enabled by default, as they
are only useful on web servers. See data/html/README for additional
information on how to set up CGI programs.
--with-ssl (default: auto-detect)
--with-lib (default: no)
Enable SSL development code. Read docs/ssl.txt for instructions on
SSL support.
Build and install the upsclient library and header files.
--with-wrap (default: auto-detect)
--with-all (no default)
Enable libwrap (tcp-wrappers) support. Refer to upsd man page for
more information.
Build and install all of the above (the serial, USB, and SNMP
drivers, the CGI programs and HTML files, and the upsclient
library).
--with-ipv6 (default: auto-detect)
--with-ssl (default: auto-detect)
Enable IPv6 support.
Enable SSL development code. Read the section "Configuring SSL" in
docs/security.txt for instructions on SSL support.
--with-hal (default: no)
--with-wrap (default: auto-detect)
Build and install Hardware Abstraction Layer support.
If you own a USB unit, only protect your local system and run the
Gnome or KDE desktop, this will enable a full Plug & Play usage.
See docs/nut-hal.txt for additional information on how to set up
and use HAL support.
Enable libwrap (tcp-wrappers) support. Refer to upsd man page for
more information.
--with-powerman (default: auto-detect)
--with-ipv6 (default: auto-detect)
Build and install Powerman PDU client driver.
This allows to interact with the Powerman daemon, and the numerous
Power Distribution Units (PDU) supported by the project.
Enable IPv6 support.
3. Other configuration options:
===============================
--with-hal (default: no)
--with-port=PORT
Build and install Hardware Abstraction Layer support.
If you own a USB unit, only protect your local system and run the
Gnome or KDE desktop, this will enable a full Plug & Play usage.
See docs/nut-hal.txt for additional information on how to set up
and use HAL support.
--with-powerman (default: auto-detect)
Change the TCP port used by the network code. Default is 3493.
Build and install Powerman PDU client driver.
This allows to interact with the Powerman daemon, and the numerous
Power Distribution Units (PDU) supported by the project.
Ancient versions of upsd used port 3305. NUT 2.0 and up use a
substantially different network protocol and are not able to
communicate with anything older than the 1.4 series.
If you have to monitor a mixed environment, use the last 1.4 version,
as it contains compatibility code for both the old "REQ" and the new
"GET" versions of the protocol.
Other configuration options
---------------------------
--with-user=<username>
--with-group=<groupname>
--with-port=PORT
Programs started as root will setuid() to <username> for somewhat
safer operation. You can override this with -u <user> in several
programs, including upsdrvctl (and all drivers by extension), upsd,
and upsmon. The "user" directive in ups.conf overrides this at run
time for the drivers.
Change the TCP port used by the network code. Default is 3493.
Note: upsmon does not totally drop root because it may need to
initiate a shutdown. There is always at least a stub process
remaining with root powers. The network code runs in another
(separate) process as the new user.
Ancient versions of upsd used port 3305. NUT 2.0 and up use a
substantially different network protocol and are not able to
communicate with anything older than the 1.4 series.
The <groupname> is used for the permissions of some files,
particularly the hotplugging rules for USB. The idea is that the
device files for any UPS devices should be readable and writable by
members of that group.
If you have to monitor a mixed environment, use the last 1.4 version,
as it contains compatibility code for both the old "REQ" and the new
"GET" versions of the protocol.
The default value for both the username and groupname is "nobody".
This was done since it's slightly better than staying around as
root. Running things as nobody is not a good idea, since it's a
hack for NFS access. You should create at least one separate user
for this software.
--with-user=<username>
--with-group=<groupname>
If you use one of the --with-user and --with-group options, then
you have to use the other one too.
Programs started as root will setuid() to <username> for somewhat
safer operation. You can override this with -u <user> in several
programs, including upsdrvctl (and all drivers by extension), upsd,
and upsmon. The "user" directive in ups.conf overrides this at run
time for the drivers.
See the INSTALL document and the FAQ for more on this topic.
NOTE: upsmon does not totally drop root because it may need to
initiate a shutdown. There is always at least a stub process
remaining with root powers. The network code runs in another
(separate) process as the new user.
--with-logfacility=FACILITY
The <groupname> is used for the permissions of some files,
particularly the hotplugging rules for USB. The idea is that the
device files for any UPS devices should be readable and writable by
members of that group.
Change the facility used when writing to the log file. Read the man
page for openlog to get some idea of what's available on your system.
Default is LOG_DAEMON.
The default value for both the username and groupname is "nobody".
This was done since it's slightly better than staying around as
root. Running things as nobody is not a good idea, since it's a
hack for NFS access. You should create at least one separate user
for this software.
4. Installation directories:
============================
If you use one of the --with-user and --with-group options, then
you have to use the other one too.
--prefix=PATH
See the INSTALL document and the FAQ for more on this topic.
This is a fairly standard option with GNU autoconf, and it sets the
base path for most of the other install directories. The default
is /usr/local/ups, which puts everything but the state sockets in one
easy place.
--with-logfacility=FACILITY
If you like having things to be at more of a "system" level, setting
the prefix to /usr/local or even /usr might be better.
Change the facility used when writing to the log file. Read the man
page for openlog to get some idea of what's available on your system.
Default is LOG_DAEMON.
--exec_prefix=PATH
This sets the base path for architecture dependent files. By
default, it is the same as <prefix>.
Installation directories
------------------------
--sysconfdir=PATH
--prefix=PATH
Changes the location where NUT's configuration files are stored.
By default this path is <prefix>/etc. Setting this to /etc or
/etc/ups might be useful.
This is a fairly standard option with GNU autoconf, and it sets the
base path for most of the other install directories. The default
is /usr/local/ups, which puts everything but the state sockets in one
easy place.
The NUT_CONFPATH environment variable overrides this at run time.
If you like having things to be at more of a "system" level, setting
the prefix to /usr/local or even /usr might be better.
--bindir=PATH
--sbindir=PATH
--exec_prefix=PATH
Where executable files will be installed. Files that are normally
executed by root (upsd, upsmon, upssched) go to sbindir, all others
to bindir. The defaults are <exec_prefix>/bin and <exec_prefix>/sbin.
This sets the base path for architecture dependent files. By
default, it is the same as <prefix>.
--datadir=PATH
--sysconfdir=PATH
Change the data directory, i.e., where architecture independent
read-only data is installed. By default this is <prefix>/share,
i.e., /usr/local/ups/share. At the moment, this directory only
holds two files - the optional cmdvartab and driver.list.
Changes the location where NUT's configuration files are stored.
By default this path is <prefix>/etc. Setting this to /etc or
/etc/ups might be useful.
--mandir=PATH
The NUT_CONFPATH environment variable overrides this at run time.
Sets the base directories for the man pages. The default is
<prefix>/man, i.e., /usr/local/ups/man.
--bindir=PATH
--sbindir=PATH
--includedir=PATH
Where executable files will be installed. Files that are normally
executed by root (upsd, upsmon, upssched) go to sbindir, all others
to bindir. The defaults are <exec_prefix>/bin and <exec_prefix>/sbin.
Sets the path for include files to be installed when --with-lib is
selected. For example, upsclient.h is installed here. The default
is <prefix>/include.
--datadir=PATH
--libdir=PATH
Change the data directory, i.e., where architecture independent
read-only data is installed. By default this is <prefix>/share,
i.e., /usr/local/ups/share. At the moment, this directory only
holds two files - the optional cmdvartab and driver.list.
Sets the installation path for libraries. This is just the
upsclient library for now. The default is <exec_prefix>/lib.
--mandir=PATH
--with-drvpath=PATH
Sets the base directories for the man pages. The default is
<prefix>/man, i.e., /usr/local/ups/man.
The UPS drivers will be installed to this path. By default they
install to "<exec_prefix>/bin", i.e., /usr/local/ups/bin.
--includedir=PATH
The "driverpath" global directive in the ups.conf file overrides this
at run time.
Sets the path for include files to be installed when --with-lib is
selected. For example, upsclient.h is installed here. The default
is <prefix>/include.
--with-cgipath=PATH
--libdir=PATH
The CGI programs will be installed to this path. By default, they
install to "<exec_prefix>/cgi-bin", which is usually /usr/local/ups/cgi-bin.
Sets the installation path for libraries. This is just the
upsclient library for now. The default is <exec_prefix>/lib.
If you set the prefix to something like /usr, you should set the
cgipath to something else, because /usr/cgi-bin is pretty ugly and
non-standard.
--with-drvpath=PATH
The CGI programs are not built or installed by default. Use
"./configure --with-cgi" to request that they are built and
installed.
The UPS drivers will be installed to this path. By default they
install to "<exec_prefix>/bin", i.e., /usr/local/ups/bin.
--with-htmlpath=PATH
The "driverpath" global directive in the ups.conf file overrides this
at run time.
HTML files will be installed to this path. By default, this is
"<prefix>/html". Note that HTML files are only installed if
--with-cgi is selected.
--with-cgipath=PATH
--with-pkgconfig-dir=PATH
The CGI programs will be installed to this path. By default, they
install to "<exec_prefix>/cgi-bin", which is usually /usr/local/ups/cgi-bin.
Where to install pkg-config *.pc files. This option only has an
effect if --with-lib is selected, and causes a pkg-config file to
be installed in the named location. The default is
<exec_prefix>/pkgconfig.
If you set the prefix to something like /usr, you should set the
cgipath to something else, because /usr/cgi-bin is pretty ugly and
non-standard.
Use --without-pkgconfig-dir to disable this feature altogether.
The CGI programs are not built or installed by default. Use
"./configure --with-cgi" to request that they are built and
installed.
--with-hotplug-dir=PATH
--with-htmlpath=PATH
Where to install Linux 2.4 hotplugging rules. The default is
/etc/hotplug, if that directory exists, and not to install it
otherwise. Note that this installation directory is not a
subdirectory of <prefix> by default. When installing NUT as a
non-root user, you may have to override this option.
HTML files will be installed to this path. By default, this is
"<prefix>/html". Note that HTML files are only installed if
--with-cgi is selected.
Use --without-hotplug-dir to disable this feature altogether.
--with-pkgconfig-dir=PATH
--with-udev-dir=PATH
Where to install pkg-config *.pc files. This option only has an
effect if --with-lib is selected, and causes a pkg-config file to
be installed in the named location. The default is
<exec_prefix>/pkgconfig.
Where to install Linux 2.6 hotplugging rules, for kernels that have
the "udev" mechanism. The default is /etc/udev, if that directory
exists, and not to install it otherwise. Note that this
installation directory is not a subdirectory of <prefix> by
default. When installing NUT as a non-root user, you may have to
override this option.
Use --without-pkgconfig-dir to disable this feature altogether.
Use --without-udev-dir to disable this feature altogether.
--with-hotplug-dir=PATH
5. Directories used by NUT at run-time:
=======================================
Where to install Linux 2.4 hotplugging rules. The default is
/etc/hotplug, if that directory exists, and not to install it
otherwise. Note that this installation directory is not a
subdirectory of <prefix> by default. When installing NUT as a
non-root user, you may have to override this option.
--with-pidpath=PATH
Use --without-hotplug-dir to disable this feature altogether.
Changes the directory where pid files are stored. By default this is
/var/run. Certain programs like upsmon will leave files here.
--with-udev-dir=PATH
--with-altpidpath=PATH
Where to install Linux 2.6 hotplugging rules, for kernels that have
the "udev" mechanism. The default is /etc/udev, if that directory
exists, and not to install it otherwise. Note that this
installation directory is not a subdirectory of <prefix> by
default. When installing NUT as a non-root user, you may have to
override this option.
Programs that normally don't have root powers, like the drivers and
upsd, write their pid files here. By default this is whatever the
statepath is, as those programs should be able to write there.
Use --without-udev-dir to disable this feature altogether.
--with-statepath=PATH
Change the default location of the state sockets created by the
drivers.
Directories used by NUT at run-time
-----------------------------------
The NUT_STATEPATH environment variable overrides this at run time.
--with-pidpath=PATH
Default is /var/state/ups.
Changes the directory where pid files are stored. By default this is
/var/run. Certain programs like upsmon will leave files here.
6. Things the compiler might need to find:
==========================================
--with-altpidpath=PATH
--with-gd-includes="-I/foo/bar"
Programs that normally don't have root powers, like the drivers and
upsd, write their pid files here. By default this is whatever the
statepath is, as those programs should be able to write there.
If you installed gd in some place where your C preprocessor can't
find the header files, use this switch to add additional -I flags.
--with-statepath=PATH
--with-gd-libs="-L/foo/bar -labcd -lxyz"
Change the default location of the state sockets created by the
drivers.
If your copy of gd isn't linking properly, use this to give the
proper -L and -l flags to make it work. See LIBS= in gd's Makefile.
The NUT_STATEPATH environment variable overrides this at run time.
Note: the --with-gd switches are not necessary if you have gd 2.0.8
or higher installed properly. The gdlib-config script will be
detected and used by default in that situation.
Default is /var/state/ups.
--with-ssl-includes, --with-usb-includes, --with-snmp-includes,
--with-neon-includes, --with-powerman-includes="-I/foo/bar"
If your system doesn't have pkg-config and support for any of the
above libraries isn't found (but you know it is installed), you must
specify the compiler flags that are needed.
Things the compiler might need to find
--------------------------------------
--with-ssl-libs, --with-usb-libs, --with-snmp-libs,
--with-neon-libs, --with-powerman-libs="-L/foo/bar -labcd -lxyz"
--with-gd-includes="-I/foo/bar"
If your system doesn't have pkg-config and support for any of the
above libraries isn't found (but you know it is installed), you must
specify the linker flags that are needed.
If you installed gd in some place where your C preprocessor can't
find the header files, use this switch to add additional -I flags.
--with-gd-libs="-L/foo/bar -labcd -lxyz"
If your copy of gd isn't linking properly, use this to give the
proper -L and -l flags to make it work. See LIBS= in gd's Makefile.
NOTE: the --with-gd switches are not necessary if you have gd 2.0.8
or higher installed properly. The gdlib-config script will be
detected and used by default in that situation.
--with-ssl-includes, --with-usb-includes, --with-snmp-includes,
--with-neon-includes, --with-powerman-includes="-I/foo/bar"
If your system doesn't have pkg-config and support for any of the above
libraries isn't found (but you know it is installed), you must specify the
compiler flags that are needed.
--with-ssl-libs, --with-usb-libs, --with-snmp-libs,
--with-neon-libs, --with-powerman-libs="-L/foo/bar -labcd -lxyz"
If your system doesn't have pkg-config and support for any of the above
libraries isn't found (but you know it is installed), you must specify the
linker flags that are needed.
HAL addons (deprecated)
-----------------------
--with-hal-includes="-DDBUS_API_SUBJECT_TO_CHANGE -I/usr/include/hal \
-I/usr/include/dbus-1.0 -I/usr/lib/dbus-1.0/include"
--with-hal-libs="-lhal -ldbus-1 -lpthread"
--with-hal-user="haldaemon"
--with-hal-device-match-key="info.bus"
--with-hal-callouts-path="${libdir}/hal"
--with-hal-fdi-path="${datarootdir}/hal/fdi/information/20thirdparty"
If system doesn't have pkg-config or it fails to provides hints for some of the
settings that are needed to set it up properly and the build in defaults are
not right, you can specify the right variables here.

33
docs/contact-closure.txt
View file

@ -1,13 +1,11 @@
Desc: Contact closure hardware
File: contact-closure.txt
Date: 14 March 2004
Auth: Russell Kroll <rkroll@exploits.org>
Contact closure hardware information
------------------------------------
This is a collection of notes that apply to contact closure UPS
hardware, specifically those monitored by the genericups driver.
Definitions
-----------
~~~~~~~~~~~
"Contact closure" refers to a situation where one line is connected to
another inside UPS hardware to indicate some sort of situation. These
@ -25,7 +23,7 @@ not require cable power. These signals just appear on the right lines
without any special configuration on the PC side.
Bad levels
----------
~~~~~~~~~~
Some evil cabling and UPS equipment uses the transmit or receive lines
as their reference points for these signals. This is not sufficient to
@ -34,7 +32,7 @@ reading certain signals on your system, make sure your UPS isn't trying
to do this.
Signals
-------
~~~~~~~
Unlike their smarter cousins, this kind of UPS can only give you very
simple yes/no answers. Due to the limited number of serial port lines
@ -53,7 +51,7 @@ a way that it only works when running on battery. Most hardware or
cabling will ignore the shutdown signal when running on line power.
New genericups types
--------------------
~~~~~~~~~~~~~~~~~~~~
If none of the existing types in the genericups driver work completely,
make a note of which ones (if any) manage to work partially. This can
@ -76,15 +74,15 @@ When editing the genericups.h, the values have the following meanings:
Outgoing lines:
line_norm = what to set to make the line "normal" - i.e. cable power
line_sd = what to set to make the UPS shut down the load
- line_norm = what to set to make the line "normal" - i.e. cable power
- line_sd = what to set to make the UPS shut down the load
Incoming lines:
line_ol = flag that appears for on line / on battery
val_ol = value of that flag when the UPS is on battery
line_bl = flag that appears for low battery / battery OK
val_bl = value of that flag when the battery is low
- line_ol = flag that appears for on line / on battery
- val_ol = value of that flag when the UPS is on battery
- line_bl = flag that appears for low battery / battery OK
- val_bl = value of that flag when the battery is low
This may seem a bit confusing to have two variables per value that
we want to read, but here's how it works. If you set line_ol to
@ -95,14 +93,15 @@ the result will be 0.
So, if line_ol = foo, then val_ol can only be foo or 0.
As a general case, if line_ol == val_ol, then the value you're reading
As a general case, if 'line_ol == val_ol', then the value you're reading
is active high. Otherwise, it's active low. Check out the guts of
upsdrv_updateinfo() to see how it really works.
Custom definitions
------------------
~~~~~~~~~~~~~~~~~~
Late in the 1.3 cycle, a feature was merged which allows you to create
custom monitoring settings without editing the model table. Just set
upstype to something close, then use settings in ups.conf to adjust the
rest. See the genericups man page for more details.
rest. See the linkman:genericups[8] man page for more
details.

54
docs/data-room.txt
View file

@ -1,54 +0,0 @@
Desc: Typical setups for data rooms
File: data-room.txt
Date: 27 May 2002
Auth: Russell Kroll <rkroll@exploits.org>
The split nature of this UPS monitoring software allows a wide variety of
power connections. This document will help you identify how things should
be configured using some general descriptions.
There are two main elements:
1. There's a UPS attached to a serial port on this system.
2. This system depends on a UPS for power.
You can play "mix and match" with those two to arrive at these descriptions
for individual hosts:
A: 1 but not 2
B: 2 but not 1
C: 1 and 2
A small to medium sized data room usually has one C and a bunch of Bs.
This means that there's a system (type C) hooked to the UPS which depends
on it for power. There are also some other systems in there (type B)
which depend on that same UPS for power, but aren't directly connected to
it.
Larger data rooms or those with multiple UPSes may have several "clusters"
of the "single C, many Bs" depending on how it's all wired.
Finally, there's a special case. Type A systems are connected to a UPS's
serial port, but don't depend on it for power. This usually happens when
a UPS is physically close to a box and can reach the serial port, but
the wiring is such that it doesn't actually feed it.
Once you identify a system's type, use this list to decide which of the
programs need to be run for monitoring:
A: driver and upsd
B: upsmon (as slave)
C: driver, upsd, and upsmon (as master)
To further complicate things, you can have a system that is hooked to
multiple UPSes, but only depends on one for power. This particular
situation makes it an "A" relative to one UPS, and a "C" relative to the
other. The software can handle this - you just have to tell it what to
do.
Multi-power supply boxes
========================
If you are running large server-class systems that have more than one
power feed, see big-servers.txt for information on how to handle it
properly.

40
docs/design.txt
View file

@ -1,34 +1,21 @@
Desc: Network UPS Tools design document
File: design.txt
Date: 14 March 2004
Auth: Russell Kroll <rkroll@exploits.org>
NUT design document
===================
This software is designed around a layered scheme with drivers, a
server and clients. These layers communicate with text-based
protocols for easier maintenance and diagnostics.
The layering
============
------------
CLIENTS: upsmon, upsc, upsrw, upsstats, upsset, etc. (via upsclient)
< network: TCP sockets, typically on port 3493 >
image:images/nut_layering.png[NUT layering]
SERVER: upsd
< Unix domain sockets with text-based messages >
DRIVERS: apcsmart, bestups, powercom, etc.
< serial communications, SNMP, USB, etc. >
EQUIPMENT: Smart-UPS 700, Fenton PowerPal 660, etc. (actual UPS hardware)
How information gets around
===========================
---------------------------
From the equipment
------------------
~~~~~~~~~~~~~~~~~~
DRIVERS talk to the EQUIPMENT and receive updates. For most hardware this
is polled (DRIVER asks EQUIPMENT about a variable), but forced updates are
@ -36,7 +23,7 @@ also possible. The exact method is not important, as it is abstracted
by the driver.
From the driver
---------------
~~~~~~~~~~~~~~~
The core of all DRIVERS maintains internal storage for every variable
that is known along with the auxiliary data for those variables. It
@ -55,7 +42,7 @@ It continues to listen on the socket for additional updates.
This protocol is documented in sock-protocol.txt.
From the server
---------------
~~~~~~~~~~~~~~~
The SERVER's internal storage maintains a complete copy of the data
which is in the DRIVER, so it is capable of answering any request
@ -66,7 +53,7 @@ requested data if it is available.
The format for requests from the CLIENT is documented in protocol.txt.
Instant commands
================
----------------
Instant commands is the term given to a set of actions that result in
something happening to the UPS. Some of the common ones are
@ -86,7 +73,7 @@ timing issues. Remember that upsd services clients in a round-robin
fashion, so all queries must be lightweight and speedy.
Setting variables
=================
-----------------
Some variables in the DRIVER or EQUIPMENT can be changed, and carry the
FLAG_RW flag. Upon receiving a SET command from the CLIENT, the SERVER
@ -102,7 +89,7 @@ command's completion from the DRIVER. This, too, is planned for a future
release.
Example data path
=================
-----------------
Here's the path a piece of data might take through this architecture.
The event is a UPS going on battery, and the final result is a pager
@ -171,13 +158,12 @@ This scenario requires some configuration, obviously:
CMDSCRIPT /path/to/upssched-cmd
8. upssched-cmd knows what to do with "upsonbatt" as its first argument
9. upssched-cmd knows what to do with "upsonbatt" as its first argument
(A quick case..esac construct, see the examples)
==============================================================================
History
=======
-------
The oldest versions of this software (1998) had no separation between
the driver and the network server and only supported the latest APC

115
docs/developer-guide.txt Normal file
View file

@ -0,0 +1,115 @@
:titles.underlines: "__","==","--","~~","^^"
Network UPS Tools Developer Guide
_________________________________
:Author: Russell_Kroll,_Arnaud_Quette,_Charles_Lepple_and_Peter_Selinger
:Author Initials: RK, AQ, CL & PS
Introduction
============
NUT is both a powerful toolkit and framework that provides support for Power
Devices, such as Uninterruptible Power Supplies, Power Distribution Units
and Solar Controllers.
This document intend to describe how NUT is designed, and the way to
develop new device drivers and client applications.
[[design]]
include::design.txt[]
[[developers]]
include::developers.txt[]
[[new-drivers]]
include::new-drivers.txt[]
[[sock-protocol]]
include::sock-protocol.txt[]
[[augeas]]
include::../scripts/augeas/README[]
[[new-clients]]
include::new-clients.txt[]
[[net-protocol]]
include::net-protocol.txt[]
[[dev-tools]]
NUT developers tools
====================
NUT provides several tools for clients and core developers, and QA people.
Device simulation
-----------------
The dummy-ups driver propose a simulation mode, also known as 'Dummy Mode'.
This mode allows to simulate any kind of devices, even non existing ones.
Using this method, you can either replay a real life sequence,
<<dev-recording,recorded from an actual device>>, or directly interact
through upsrw or by editing the device file.
For more information, refer to linkman:dummy-ups[8]
manual page.
[[dev-recording]]
Device recording
----------------
To complete dummy-ups, NUT provides a device recorder script called
'device-recorder.sh' and located in the 'tools/' directory of the
NUT source tree.
This script uses 'upsc' to record device information, and stores
these in a differential fashion every 5 seconds (by default).
Its usage is the following:
Usage: dummy-recorder.sh <device-name> [output-file] [interval]
For example, to record information from the device 'myups' every 10 seconds:
tools/device-recorder.sh myups@localhost myups.seq 10
NUT core development and maintenance
====================================
This section is intended to people who want to develop new core features,
or to do some maintenance.
include::macros.txt[]
[[roadmap]]
include::../TODO[]
[[nut-names]]
Appendix A: NUT command and variable naming scheme
==================================================
include::nut-names.txt[]

325
docs/developers.txt
View file

@ -1,16 +1,14 @@
Desc: Information for developers
File: developers.txt
Date: 18 February 2004
Auth: Russell Kroll <rkroll@exploits.org>
Information for developers
==========================
This document is intended to explain some of the more useful things
within the tree and provide a standard for working on the code.
General stuff - common subdirectory
===================================
-----------------------------------
String handling
---------------
~~~~~~~~~~~~~~~
Use snprintf. It's even provided with a compatibility module if the
target host doesn't have it natively.
@ -24,7 +22,7 @@ that allows you to append to char * with a format string and all the usual
string length checking of snprintf.
Error reporting
---------------
~~~~~~~~~~~~~~~
Don't call syslog() directly. Use upslog_with_errno() and upslogx().
They may write to the syslog, stderr, or both as appropriate. This
@ -38,21 +36,21 @@ fatal_with_errno and fatalx work the same way, but they
exit(EXIT_FAILURE) afterwards. Don't call exit() directly.
Debugging information
---------------------
~~~~~~~~~~~~~~~~~~~~~
upsdebug_with_errno(), upsdebugx() and upsdebug_hex() use the
global nut_debug_level so you don't have to mess around with
printfs yourself. Use them.
Memory allocation
-----------------
~~~~~~~~~~~~~~~~~
xmalloc, xcalloc, xrealloc and xstrdup all check the results of the base
calls before continuing, so you don't have to. Don't use the raw calls
directly.
Config file parsing
-------------------
~~~~~~~~~~~~~~~~~~~
The configuration parser, called parseconf, is now up to its fourth
major version. It has multiple entry points, and can handle many
@ -67,7 +65,7 @@ Escaping special characters and quoting multiple-word elements is all
handled by the state machine. Using the same code for all config files
avoids code duplication.
Note: this does not apply to drivers. Driver authors should use the
NOTE: this does not apply to drivers. Driver authors should use the
upsdrv_makevartable() scheme to pick up values from ups.conf. Drivers
should not have their own config files.
@ -78,56 +76,63 @@ under normal circumstances. This technique might be used to add more
hardware support to a driver without recompiling.
<time.h> vs. <sys/time.h>
-------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~
This is already handled by autoconf, so just include "timehead.h" and you
will get the right headers on every system.
UPS drivers - main.c
====================
Device drivers - main.c
-----------------------
The UPS drivers use main.c as their core. The only exception is
dummycons, which only looks like a driver by using the same dstate
function calls.
The device drivers use main.c as their core. The only exceptions are the
HAL-based drivers, which use the same dstate function calls while integrating
with the DBUS event loop.
To write a new driver, you create a file with a series of support
functions that will be called by main. These all have names that start
with "upsdrv_", and they will be called at different times by main
with `upsdrv_`, and they will be called at different times by main
depending on what needs to happen.
See new-drivers.txt for information on writing drivers, and also refer
to the skeletal driver in skel.c.
See the <<new-drivers,driver documentation>> for information on writing
drivers, and also refer to the skeletal driver in skel.c.
Portability
===========
-----------
Avoid things that will break on other systems. All the world is not an
x86 Linux box.
There are still older systems out there that don't do C++ style comments.
That means you have to comment /* like this */, and // this is right out.
--------------------------------------
/* Comments look like this. */
// Not like this.
--------------------------------------
Newer versions of gcc allow you to declare a variable inside a function
somewhat like the way C++ operates, like this:
function do_stuff(void)
{
check_something();
--------------------------------------------------------------------------------
function do_stuff(void)
{
check_something();
int a;
int a;
a = do_something_else();
}
a = do_something_else();
}
--------------------------------------------------------------------------------
While this will compile and run on these newer versions, it will fail
miserably for anyone on an older system. That means you must not use
it. gcc only warns about this with -pedantic.
Coding style
============
------------
This is how I do things.
This is how we do things:
--------------------------------------------------------------------------------
int open_subspace(char *ship, int privacy)
{
if (!privacy)
@ -138,8 +143,7 @@ int open_subspace(char *ship, int privacy)
return secure_channel(ship);
}
(The example that used to be in this file wasn't particularly clear)
--------------------------------------------------------------------------------
The basic idea is that I try to group things into functions, and then
find ways to drop out of them when we can't go any further. There's
@ -159,7 +163,7 @@ easier to read, and it enables tools (such as indent and emacs) to
display the source code correctly.
Indenting with tabs vs. spaces
------------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Another thing to notice is that the indenting happens with tabs instead
of spaces. This lets everyone have their personal tab-width setting
@ -180,7 +184,7 @@ kernel - Documentation/CodingStyle. He's done a far better job of
explaining this.
Line breaks
-----------
~~~~~~~~~~~
It is better to have lines that are longer than 80 characters than to
wrap lines in random places. This makes it easier to work with tools
@ -193,13 +197,17 @@ long when there is a better alternative (see the note on
pretentiousVariableNamingSchemes above). Certainly there should not
be more than one statement per line. Please do not use
if (condition) break;
--------------------------------------------------------------------------------
if (condition) break;
--------------------------------------------------------------------------------
but use the following:
if (condition) {
break;
}
--------------------------------------------------------------------------------
if (condition) {
break;
}
--------------------------------------------------------------------------------
Miscellaneous coding style tools
--------------------------------
@ -207,12 +215,12 @@ Miscellaneous coding style tools
You can go a long way towards converting your source code to the NUT
coding style by piping it through the following command:
indent -kr -i8 -T FILE -l1000 -nhnl
indent -kr -i8 -T FILE -l1000 -nhnl
This next command does a reasonable job of converting most C++ style
comments (but not URLs and DOCTYPE strings):
sed 's#\(^\|[ \t]\)//[ \t]*\(.*\)[ \t]*#/* \2 */#'
sed 's#\(^\|[ \t]\)//[ \t]*\(.*\)[ \t]*#/* \2 */#'
Emacs users can adjust how tabs are displayed. For example, it is
possible to set a tab stop to be 3 spaces, rather than the usual 8.
@ -222,25 +230,27 @@ rendered on screen). It is even possible to set this on a
per-directory basis, by putting something like this into your .emacs
file:
;; NUT style
--------------------------------------------------------------------------------
;; NUT style
(defun nut-c-mode ()
"C mode with adjusted defaults for use with the NUT sources."
(interactive)
(c-mode)
(c-set-style "K&R")
(setq c-basic-offset 3) ;; 3 spaces C-indentation
(setq tab-width 3)) ;; 3 spaces per tab
(defun nut-c-mode ()
"C mode with adjusted defaults for use with the NUT sources."
(interactive)
(c-mode)
(c-set-style "K&R")
(setq c-basic-offset 3) ;; 3 spaces C-indentation
(setq tab-width 3)) ;; 3 spaces per tab
;; apply NUT style to all C source files in all subdirectories of nut/
;; apply NUT style to all C source files in all subdirectories of nut/
(setq auto-mode-alist (cons '(".*/nut/.*\\.[ch]$". nut-c-mode)
auto-mode-alist))
(setq auto-mode-alist (cons '(".*/nut/.*\\.[ch]$". nut-c-mode)
auto-mode-alist))
--------------------------------------------------------------------------------
Finishing touches
-----------------
~~~~~~~~~~~~~~~~~
I like code that uses const and static liberally. If you don't need to
We like code that uses const and static liberally. If you don't need to
expose a function or global variable to the outside world, static is
your friend. If nobody should edit the contents of some buffer that's
behind a pointer, const keeps them honest.
@ -250,25 +260,23 @@ find implementation flaws. Functions that attempt to modify a constant
or access something outside their scope will throw a warning or even
fail to compile in some cases. This is what we want.
Spaghetti
---------
If you use a goto, expect me to drop it when my head stops spinning.
It gives me flashbacks to the BASIC code I wrote on the 8 bit systems of
the 80s. I've tried to clean up my act, and you should make the effort
Spaghetti
~~~~~~~~~
If you use a goto, expect us to drop it when our head stops spinning.
It gives us flashbacks to the very old code we wrote.
We've tried to clean up our act, and you should make the effort
as well.
I'm not making a blanket statement about gotos, since everything
We're not making a blanket statement about gotos, since everything
probably has at least one good use. There are a few cases where a goto
is more efficient than any other approach, but you probably won't
encounter them in this software.
encounter them very often in this software.
Hint: there *was* a good use of a goto in upsd until the 1.3 series. At
this point we are back to zero gotos since that code was replaced by
another technique that doesn't need it.
Legacy code
-----------
~~~~~~~~~~~
There are parts of the source tree that do not yet conform to these
specs. Part of this is due to the fact that the coding style has been
@ -278,74 +286,94 @@ since then. Don't worry - it'll get cleaned up the next time something
in the vicinity gets a visit.
Memory leak checking
--------------------
~~~~~~~~~~~~~~~~~~~~
I can't say enough good things about valgrind. If you do anything with
We can't say enough good things about valgrind. If you do anything with
dynamic memory in your code, you need to use this. Just compile with -g
and start the program inside valgrind. Run it through the suspected
area and then exit cleanly. valgrind will tell you if you've done
anything dodgy like freeing regions twice, reading uninitialized memory,
or if you've leaked memory anywhere.
http://valgrind.kde.org/
For more information, refer to the link:http://valgrind.kde.org[Valgrind]
project.
Conclusion
----------
~~~~~~~~~~
The summary: please be kind to my eyes. There's a lot of stuff in here.
The summary: please be kind to our eyes. There's a lot of stuff in here,
and many people have put a lot of time and energy to improve it.
Submitting patches
==================
------------------
Patches that arrive in unified format (diff -u) as plain text with no
HTML, no attachments and a brief summary at the top are the easiest to
handle. They show the context, explain what's going on, and get saved as
one message. Everything stays together until it's time to merge.
Patches that arrive in unified format (diff -u) as plain text attachments with
no HTML and a brief summary at the top are the easiest to handle.
Patches that arrive as attachments have to be moved around as separate
files - the body of the message is one, and the patch is in another.
This is not my preferred mode of operation.
If a patch is sent to the nut-upsdev mailing list, it stands a better chance of
being seen immediately. However, it is likely to be dropped if any issues
cannot be resolved quickly. If your code might not work for others, or if it is
a large change, your best bet is to submit a
link:https://alioth.debian.org/tracker/?atid=411544&group_id=30602&func=browse[ticket on Alioth].
When sending patches to the lists, be sure to add me as an explicit
recipient to make sure it is considered for merging. A patch which only
goes to a list is generally treated as a RFC and is relatively low
priority.
This allows us to track the patches over a longer period of time, and it is
less likely that a patch will fall through the cracks. Posting a reminder to
the developers (via the nut-upsdev list) about a patch on the tracker is fair
game.
If your mailer is brain dead and rewrites tabs into spaces, wraps your
patch body, or anything else like that, just attach the patch. I'd
rather deal with an attachment instead of a patch that has tab damage,
rewrapped lines, or worse.
Patch cohesion
==============
--------------
Patches should have some kind of unifying element. One patch set is one
message, and it should all touch similar things. If you have to edit 6
files to add support for neutrino detection in UPS hardware, that's
fine.
However, sending one huge patch that does massive separate changes
all over the tree is not recommended. That kind of patch has to be
split up and evaluated separately, assuming I care enough to do that
However, sending one huge patch that does massive separate changes all over
the tree is not recommended. That kind of patch has to be split up and
evaluated separately, assuming the core developers care enough to do that
instead of just dropping it.
If you have to make big changes in lots of places, send multiple
patches - one per item.
Man pages
=========
The completion touch: manual pages and device entry in HCL
----------------------------------------------------------
If you change something that involves an argument to a program or
configuration file parsing, the man page is probably now out of date.
If you don't update it, I have to, and I have enough to do as it is.
If you don't update it, we have to, and we have enough to do as it is.
If you write a new driver, send in the man page when you send me the
source code for your driver. Otherwise, I will be forced to write a
If you write a new driver, send in the man page when you send us the
source code for your driver. Otherwise, we will be forced to write a
skeletal man page that will probably miss many of the finer points of
the driver and hardware.
The same remark goes for device entries: if you add support for new models,
remember to also complete the hardware compatibility list, present
in data/driver.list.in. This will be used to generate both textual, static
HTML and dynamic searchable HTML for the website.
Source code management
----------------------
We currently use a Subversion (SVN) repository hosted at Alioth to track
changes to the NUT source code. To obtain permission to commit to the SVN
repository, you must be prepared to spend a fair amount of time contributing to
the NUT codebase. For occasional contributions over time, you may wish to
investigate one of the <<_distributed_scm_systems,distributed SCM tools>>
listed below.
Anonymous SVN checkouts are possible:
svn co svn://svn.debian.org/nut/trunk nut-svn-readonly
If you change a file in the SVN working copy, you can use `svn diff` to
generate a patch to send to the nut-upsdev mailing list.
Repository etiquette and quality assurance
==========================================
------------------------------------------
Please keep the SVN trunk in working condition at all times. The trunk
may be used to generate daily tarballs, and should not contain broken
@ -353,22 +381,103 @@ code if possible. If you need to commit incremental changes that leave
the system in a broken state, please do so in a separate branch and
merge the changes back to the trunk once they are complete.
Before committing, please remember to:
Before committing, please remember to run "make distcheck-light". This checks
that the Makefiles are not broken, that all the relevant files are distributed,
and that there are no compilation or installation errors.
* update the ChangeLog, if appropriate. Dates are listed in UTC
("date --utc").
* run "make distcheck-light". This checks that the Makefiles are not
broken, that all the relevant files are distributed, and that there
are no compilation or installation errors.
Running "make distcheck-light" is especially important if you have
added or removed files, or updated configure.in or some Makefile.am.
Remember: simply adding a file to SVN does not mean it will be
distributed. To distribute a file, you must update the corresponding
Makefile.am.
Running "make distcheck-light" is especially important if you have added or
removed files, or updated configure.in or some Makefile.am. Remember: simply
adding a file to SVN does not mean it will be distributed. To distribute a
file, you must update the corresponding Makefile.am.
There is also "make distcheck", which runs an even stricter set of
tests, but will not work unless you have all the optional libraries
and features installed.
Distributed SCM systems
-----------------------
Git and Mercurial (Hg) are two popular distributed SCM tools which provide a
bridge to a SVN repository. This makes it possible for a new developer to stay
synchronized with the latest changes to NUT, while keeping a local version
history of their changes before they are merged by the core NUT developers.
A complete introduction to either Git or Mercurial is beyond the scope of this
document, but many others have written excellent tutorials on both the DSCM
tools, and their SVN interfaces.
Git and SVN
~~~~~~~~~~~
The `git svn` tool synchronizes a Git repository with a
link:http://www.kernel.org/pub/software/scm/git/docs/git-svn.html[SVN repository].
In many cases, NUT developers will not need access to the entire repository
history - a snapshot starting at the most recent revision will work nicely:
git svn clone --revision HEAD svn://svn.debian.org/nut/trunk nut-git
From the resulting nut-git directory, you may use all of the Git commands to
record your changes, and even create new branches for working on different
aspects of the code.
Git offers a little more flexibility than the `svn update` command. You may
fetch other developers' changes from SVN into your repository, but hold off on
actually combining them with your branch until you have compared the two
branches (for instance, with `gitk --all`).
To import the new SVN revisions, simply run the following command from any
directory under your Git checkout (`nut-git` in the example above). Note that
this only changes the history stored in your repository - it does not touch
your checked-out files.
git svn fetch
Initially, the Git `master` branch tracks the SVN `trunk`. The `git svn`
command updates the `remotes/trunk` reference every time you run `git svn
fetch`, but it does not adjust the `master` branch automatically. To update
your master branch with new SVN revisions, you can run the following commands:
git checkout master
git svn fetch # (optional; this gets commits other than on your current branch)
git svn rebase
You may create as many branches as you like in your local Git repository. When
using `git svn`, the preferred way to combine your changes with SVN changes is
to use `git rebase` on your local branch. This re-applies your branch's changes
to the new SVN changes, much as though your branch were a series of patches.
--------------------------------------------------------------------------------
git checkout master
git branch my-new-feature
git checkout my-new-feature
# Hack away
git add changed-file.c
git commit
# Someone committed something to SVN. Fetch it.
git svn fetch
git rebase remotes/trunk
--------------------------------------------------------------------------------
You are encouraged to use `git rebase -i` on your private Git branches to
separate your changes into <<_patch_cohesion,logical changes>>.
From there, you can generate patches for the Tracker, or the nut-upsdev list.
If you are new to Git, but are familiar with SVN, the
link:http://git-scm.com/course/svn.html[following link] may be of use.
Mercurial and SVN
~~~~~~~~~~~~~~~~~
Synchronizing a Mercurial repository against the NUT SVN repository should be
similar in spirit to the Git method discussed above.
link:http://mercurial.selenic.com/wiki/WorkingWithSubversion[This wiki page]
discusses your options.
We would welcome any feedback about this process on the nut-upsdev mailing list.

10
docs/docinfo.xml Normal file
View file

@ -0,0 +1,10 @@
<revhistory>
<revision>
<revnumber>2.6.0</revnumber>
<date>2011-01-14</date>
<authorinitials></authorinitials>
<revremark>
First release of AsciiDoc documentation for Network UPS Tools (NUT).
</revremark>
</revision>
</revhistory>

70
docs/documentation.txt Normal file
View file

@ -0,0 +1,70 @@
ifdef::website[]
Documentation
=============
endif::website[]
User Documentation
------------------
ifdef::website[]
- FAQ - Frequently Asked Questions (link:docs/FAQ.html[online]) (link:docs/FAQ.pdf[PDF])
- NUT User Manual (link:docs/user-manual.chunked/index.html[online]) (link:docs/user-manual.pdf[PDF])
- Cables information (link:cables.html[online]) (link:cables.pdf[PDF])
- link:docs/man/index.html#User_man[User manual pages]
endif::website[]
ifndef::website[]
- link:../FAQ.html[FAQ - Frequently Asked Questions]
- linkdoc:user-manual[NUT user manual]
- <<Cables_information,Cables information>>
- link:../man/index.html#User_man[User manual pages]
endif::website[]
Developer Documentation
-----------------------
ifdef::website[]
- NUT Developer Guide (link:docs/developer-guide.chunked/index.html[online]) (link:docs/developer-guide.pdf[PDF])
- NUT Packager Guide (link:docs/packager-guide.chunked/index.html[online]) (link:docs/packager-guide.pdf[PDF])
- link:ups-protocols.html[UPS protocols library]
- link:docs/man/index.html#Developer_man[Developer manual pages]
- link:nut-qa.html[NUT Quality Assurance]
endif::website[]
ifndef::website[]
- linkdoc:developer-guide[NUT Developer Guide]
- linkdoc:packager-guide[NUT Packager Guide]
- link:ups-protocols.html[UPS protocols library]
- link:../man/index.html#Developer_man[Developer manual pages]
- link:nut-qa.html[NUT Quality Assurance]
endif::website[]
Offsite Links
-------------
[[general_powerdev_info]]
These are general information about UPS and PDU.
- link:http://tldp.org/HOWTO/UPS-HOWTO/[UPS HOWTO] (The Linux Documentation Project)
- link:http://en.wikipedia.org/wiki/Uninterruptible_power_supply[UPS on Wikipedia]
- link:http://en.wikipedia.org/wiki/Power_distribution_unit[PDU on Wikipedia]
- link:http://www.pcguide.com/ref/power/ext/ups/over.htm[UPS on The PC Guide]
These are writeups by users of the software.
- link:http://www.dimat.unina2.it/LCS/MonitoraggioUpsNutUbuntu10-eng.htm[Deploying NUT on an Ubuntu 10.04 cluster] '(Stefano Angelone)'
- link:http://blog.shadypixel.com/monitoring-a-ups-with-nut-on-debian-or-ubuntu-linux[Monitoring a UPS with nut on Debian or Ubuntu Linux] '(Avery Fay)'
- link:http://linux.developpez.com/cours/upsusb/[Installation et gestion d'un UPS USB en réseau sous linux] '(Olivier Van Hoof, french)'
- link:http://boxster.ghz.cc/projects/nut/wiki/NutOnMacOSX[Network UPS Tools (NUT) on Mac OS X (10.4.10)] '(Andy Poush)'
- link:http://www.llondel.org/ups.shtml[Interfacing a Contact-Closure UPS to Mac OS X and Linux] '(David Hough)'
- link:http://fedoranews.org/contributors/kazutoshi_morioka/nut/[How to use UPS with nut on RedHat / Fedora Core] '(Kazutoshi Morioka)'
- link:http://people.freebsd.org/~thierry/nut_FreeBSD_HowTo.txt[FreeBSD installation procedure] '(Thierry Thomas, from FreeBSD)'
- link:http://www.usebox.net/jjm/ups-obsd/[Gestionando un SAI desde OpenBSD con NUT] '(Juan J. Martinez, spanish)'
- link:http://forums.gentoo.org/viewtopic-p-2663684.html[HOWTO: MGE Ellipse 300 on gentoo] '(nielchiano)'
- link:http://deschis.blogspot.com/2006/07/cum-se-configureaz-un-ups-apollo-seria.html[Cum se configurează un UPS Apollo seria 1000F pe Linux] '(deschis, Romanian)'
- link:http://buffalo.nas-central.org/wiki/Install_a_UPS_%28nut%29[Install a UPS (nut) on a Buffalo NAS] '(various authors)'
- link:http://blog.pointbre.com/2903/nutnetwork-ups-tool-korean-guidebook.html[NUT Korean GuideBook] '(PointBre)'
News articles and Press releases
--------------------------------
- link:http://www.crn.com/white-box/199000818?pgno=1[Linux UPS Without Tears] '(A. Lizard)'
- link:http://networking.earthweb.com/netsysm/article.php/10954_3295841_1[Graceful UPS shutdowns on Linux] '(Carla Schroder)'

117
docs/download.txt Normal file
View file

@ -0,0 +1,117 @@
Download information
====================
This section presents the different methods to download NUT.
Source code
-----------
[NOTE]
================================================================================
You should always use PGP/GPG to verify the signatures before using any source code.
You can use the
ifdef::website[]
link:docs/user-manual.chunked/ar01s09.html#verifySourceSig[following procedure]
endif::website[]
ifndef::website[]
- Else, you can read the <<verifySourceSig,following procedure>>.
endif::website[]
to do so.
================================================================================
Stable tree: 2.6
~~~~~~~~~~~~~~~~
link:http://www.networkupstools.org/source/2.6/nut-2.6.0.tar.gz[nut-2.6.0.tar.gz]
link:http://www.networkupstools.org/source/2.6/nut-2.6.0.tar.gz.sig[signature]
link:http://www.networkupstools.org/source/2.6/new-2.6.0.txt[release notes]
link:http://www.networkupstools.org/source/2.6/ChangeLog[ChangeLog]
You can also browse the link:http://www.networkupstools.org/source/2.6/[stable source directory].
Testing tree: 2.6.x-pre
~~~~~~~~~~~~~~~~~~~~~~~
There is currently no testing release.
Development tree: 2.7
~~~~~~~~~~~~~~~~~~~~~
Code repository
^^^^^^^^^^^^^^^
The development tree is available through a Subversion repository hosted on the
link:http://alioth.debian.org/[Debian Alioth server].
To retrieve the current development tree, use the following command:
$ svn co svn://svn.debian.org/nut/trunk
To generate the build scripts, you must call, from the 'trunk' directory:
$ ./autogen.sh
Then refer to the
ifdef::website[]
link:docs/user-manual.chunked/index.html[NUT user manual]
endif::website[]
ifndef::website[]
linkdoc:user-manual[NUT user manual]
endif::website[]
for more information.
NOTE: Users that need the latest developments to support new devices *must*
use <<Snapshots,snapshots>>.
Browse code
^^^^^^^^^^^
You can also browse the code with link:http://svn.debian.org/wsvn/nut/trunk/?rev=0&sc=0[WebSvn].
Or through the link:http://boxster.ghz.cc/projects/nut[Trac mirror],
kindly hosted and maintained by Charles Lepple.
[[Snapshots]]
Snapshots
^^^^^^^^^
The latest Subversion developments are available through link:http://buildbot.networkupstools.org/public/nut/waterfall?branch=trunk&builder=Debian-etch-x86&reload=none[snapshots on the Buildbot].
Look for the latest *[tarball]* link on the top of the page.
Older versions
~~~~~~~~~~~~~~
link:http://www.networkupstools.org/source/[Browse source directory]
Binary packages
---------------
NOTE: The only official releases from this project are source code.
NUT is already available in the following systems:
- Linux:
link:http://aur.archlinux.org/packages.php?ID=5379[Arch Linux],
link:http://packages.debian.org/nut[Debian],
link:http://packages.gentoo.org/package/sys-power/nut[Gentoo Linux],
Mandriva,
link:https://admin.fedoraproject.org/pkgdb/acls/name/nut[Red Hat / Fedora],
link:http://software.opensuse.org/search[Novell Suse / openSUSE],
link:https://forum.openwrt.org/viewtopic.php?id=26269[OpenWrt]
link:http://packages.ubuntu.com/nut[Ubuntu].
- BSD systems:
link:http://www.FreeBSD.org/cgi/ports.cgi?query=^nut-&amp;stype=name[FreeBSD],
link:ftp://ftp.netbsd.org/pub/NetBSD/packages/pkgsrc/sysutils/ups-nut/README.html[NetBSD],
link:http://www.openbsd.org/cgi-bin/cvsweb/ports/sysutils/nut/[OpenBSD].
- Mac OS X:
link:http://pdb.finkproject.org/pdb/package.php/nut[Fink],
link:http://trac.macports.org/browser/trunk/dports/sysutils/nut/Portfile[MacPorts]
- Windows (client side only):
link:http://csociety.ecn.purdue.edu/~delpha/winnut/[WinNUT]

239
docs/features.txt Normal file
View file

@ -0,0 +1,239 @@
Features
========
NUT provides many features, and is always improving.
Thus this list may lag behind the current code.
Features frequently appear during the development cycles, so be sure to look at
the link:http://www.networkupstools.org/download.html[release notes and change logs]
to see the latest additions.
////////////////////////////////////////////////////////////////////////////////
*FIXME* statement that NUT is *the* de facto standard on Opensource system.
all Linux distributors have standardized the Power Devices support using NUT.
More and more appliances manufacturers are bundling NUT...
=> add an Appendix NUT Device Integration in the User Manual
////////////////////////////////////////////////////////////////////////////////
Multiple manufacturer and device support
----------------------------------------
- Monitors many UPS, PDU and SCD models from more than 100 manufacturers with a
unified interface (link:stable-hcl.html[Hardware Compatibility List]).
- Various communication types are supported with the same common interface:
* serial,
* USB,
* network (SNMP, Eaton / MGE XML/HTTP).
Multiple architecture support
-----------------------------
- Cross-platform - different flavors of Unix can be managed together with a
common set of tools, even crossing architectures.
- This software has been reported to run on Linux distributions, the BSDs, Apple's
OS X, Solaris, IRIX, HP/UX, Tru64 Unix, and AIX.
- Windows users may be able to build it directly with Cygwin.
There is also a port of the client-side monitoring to Windows called WinNUT.
- Your system will probably run it too. You just need a good C compiler and
possibly some more packages to gain access to the serial ports.
Other features, such as USB / SNMP / whatever, will also need extra software
installed.
Layered and modular design with multiple processes
--------------------------------------------------
- Three layers: drivers, server, clients.
- Drivers run on the same host as the server, and clients communicate with the
server over the network.
- This means clients can monitor any UPS anywhere as long as there is a network
path between them.
WARNING: Be sure to plug your network's physical hardware (switches, hubs,
routers, bridges, ...) into the UPS!
////////////////////////////////////////////////////////////////////////////////
*FIXME* to be removed?
- This has also allowed us to create easily the Power Management integration.
=== Power Management integration ===
- Thanks to its modular design, NUT can feed data to the FreeDesktop Hardware Abstraction Layer (HAL).[[BR]]
This allow a seemless integration of USB UPSs, at a small cost (around 200 Kb), reusing the standard Power Management GUIs and providing to users a full Plug & Play system.
- The added bonus is that this is the best Power Management existing, surpassing the one that exist on Windows and Mac OS, both in terms of devices supported and of features.
////////////////////////////////////////////////////////////////////////////////
Redundancy support - Hot swap/high availability power supplies
--------------------------------------------------------------
- upsmon can handle high-end servers which receive power from multiple UPSes
simultaneously.
- upsmon won't initiate a shutdown until the total power situation across all
source UPSes becomes critical (on battery and low battery).
- You can lose a UPS completely as long as you still have at least the minimum
number of sources available. The minimum value is configurable.
Security and access control
---------------------------
- Manager functions are granted with per-user granularity. The admin can have
full powers, while the admin's helper can only do specific non-destructive tasks
such as a battery test.
- The drivers, server, and monitoring client (upsmon) can all run as separate
user IDs if this is desired for privilege separation.
- Only one tiny part of one program has root powers.
upsmon starts as root and forks an unprivileged process which does the actual
monitoring over the network.
They remain connected over a pipe. When a shutdown is necessary, a single
character is sent to the privileged process. It then calls the predefined
shutdown command. In any other case, the privileged process exits.
This was inspired by the auth mechanism in Solar Designer's excellent popa3d.
- The drivers and network server may be run in a chroot jail for further
security benefits. This is supported directly since version 1.4 and beyond with
the 'chroot=' configuration directive.
- IP-based access control relies on the local firewall and
link:http://en.wikipedia.org/wiki/TCP_Wrapper[TCP Wrapper].
- SSL is available as a build option ("--with-ssl").
It encrypts sessions with upsd and can also be used to authenticate servers.
Web-based monitoring
--------------------
- Comes stock with CGI-based web interface tools for UPS monitoring and
management, including graphical status displays.
- Custom status web pages may be generated with the CGI programs, since they use
templates to create the pages. This allows you to have status pages which fit
the look and feel of the rest of your site.
Free software
-------------
- That's free beer and free speech. Licensed under the GNU General Public
License version 2 or later.
- Know your systems - all source code is available for inspection, so there are
no mysteries or secrets in your critical monitoring tools.
UPS management and control
--------------------------
- Writable variables may be edited on higher end equipment for local customizations
- Status monitoring can generate notifications (email/pager/SMS/...) on alert conditions
- Alert notices may be dampened to only trigger after a condition persists. This
avoids the usual pager meltdown when something happens and no delay is used.
- Maintenance actions such as battery runtime calibration are available where
supported by the UPS hardware.
- Power statistics can be logged in custom formats for later retrieval and analysis
- All drivers are started and stopped with one common program. Starting one is
as easy as starting ten: 'upsdrvctl start'.
- Shutdowns and other procedures may be tested without stressing actual UPS
hardware by simulating status values with the dummy-ups pseudo-driver. Anything
which can happen in a driver can be replicated with dummy-ups.
Monitoring diagrams
-------------------
These are the most common situations for monitoring UPS hardware. Other ways are
possible, but they are mostly variants on these four.
NOTE: these examples show serial communications for simplicity, but USB or SNMP
or any other monitoring is also possible.
"Simple" configuration
~~~~~~~~~~~~~~~~~~~~~~
image:images/simple.png[]
One UPS, one computer. This is also known as "Standalone" configuration.
This is the configuration that most users will use. You need at least a driver,
upsd, and upsmon running.
"Advanced" configuration
~~~~~~~~~~~~~~~~~~~~~~~~
image:images/advanced.png[]
One UPS, multiple computers. Only one of them can actually talk to the UPS
directly. That's where the network comes in. The Master system runs the driver,
upsd, and upsmon in master mode. The Slave systems only run upsmon in slave mode.
This is useful when you have a very large UPS that's capable of running multiple
systems simultaneously. There is no longer the need to buy a bunch of individual
UPSes or "sharing" hardware, since this software will handle the sharing for you.
////////////////////////////////////////////////////////////////////////////////
*FIXME* remainder
=== One UPS, many clients ===
- Multiple systems may monitor a single UPS using only their network connections - no special "UPS sharing" hardware is required.
- "Slave and master" monitoring design synchronizes shutdowns so that slaves can bring down their operating systems cleanly before the master switches off the power.
=== Many UPSes, many clients ===
- Each upsd process can serve status data for multiple UPSes to many clients.
- Each upsmon process can monitor multiple UPSes for status data.
////////////////////////////////////////////////////////////////////////////////
"Big Box" configuration
~~~~~~~~~~~~~~~~~~~~~~~
image:images/bigbox.png[]
Some systems have multiple power supplies and cords. You typically find this on
high-end servers that allow hot-swap and other fun features. In this case, you
run multiple drivers (one per UPS), a single upsd, and a single upsmon (as
master for both UPS 1 and UPS 2)
This software understands that some of these servers can also run with some of
the supplies gone. For this reason, every UPS is assigned a "power value" - the
quantity of power supplies that it feeds on a system.
The total available "power value" is compared to the minimum that is required
for that hardware. For example, if you have 3 power supplies and 3 UPSes, but
only 2 supplies must be running at any given moment, the minimum would be 2.
This means that you can safely lose any one UPS and the software will handle it
properly by remaining online.
"Bizarre" configuration
~~~~~~~~~~~~~~~~~~~~~~~
image:images/bizarre.png[]
You can even have a UPS that has the serial port connected to a system that it's
not feeding. Sometimes a PC will be close to a UPS that needs to be monitored,
so it's drafted to supply a serial port for the purpose. This PC may in fact be
getting power from some other UPS. This is not a problem.
The first system ("mixed") is a Master for UPS 1, but is only monitoring UPS 2.
The other systems are Slaves of UPS 2.
Image credits
-------------
Thanks to Luc Descotils and Arnaud Quette at Eaton for providing shiny
cleaned-up graphics.

110
docs/hid-subdrivers.txt
View file

@ -1,10 +1,8 @@
Desc: How to make a new subdriver to support another USB/HID UPS
File: hid-subdrivers.txt
Date: 08 January 2007
Auth: Peter Selinger <selinger@users.sourceforge.net>
How to make a new subdriver to support another USB/HID UPS
----------------------------------------------------------
Overall concept
===============
~~~~~~~~~~~~~~~
USB (Universal Serial Port) devices can be divided into several
different classes (audio, imaging, mass storage etc). Almost all UPS
@ -15,7 +13,7 @@ for reading and writing information (such as x/y coordinates and
button states, in case of a mouse, or voltages and status information,
in case of a UPS).
The Nut "usbhid-ups" driver is a meta-driver that handles all HID UPS
The NUT "usbhid-ups" driver is a meta-driver that handles all HID UPS
devices. It consists of a core driver that handles most of the work of
talking to the USB hardware, and several sub-drivers to handle
specific UPS manufacturers (MGE, APC, and Belkin are currently
@ -31,7 +29,7 @@ add support for such a device, read new-drivers.txt and see the
tripplite_usb driver for inspiration.
HID Usage Tree
==============
~~~~~~~~~~~~~~
From the point of view of writing a HID subdriver, a HID device
consists of a bunch of variables. Some variables (such as the current
@ -44,14 +42,17 @@ for a typical APC device. Variable components are separated by ".".
Typical values for each variable are also shown for illustrative
purposes.
UPS.Battery.Voltage 11.4 V
UPS.Battery.ConfigVoltage 12 V
UPS.Input.Voltage 117 V
UPS.Input.ConfigVoltage 120 V
UPS.AudibleAlarmControl 2 (=enabled)
UPS.PresentStatus.Charging 1 (=yes)
UPS.PresentStatus.Discharging 0 (=no)
UPS.PresentStatus.ACPresent 1 (=yes)
[width="35%"]
|================================================
|UPS.Battery.Voltage | 11.4 V
|UPS.Battery.ConfigVoltage | 12 V
|UPS.Input.Voltage | 117 V
|UPS.Input.ConfigVoltage | 120 V
|UPS.AudibleAlarmControl | 2 (=enabled)
|UPS.PresentStatus.Charging | 1 (=yes)
|UPS.PresentStatus.Discharging | 0 (=no)
|UPS.PresentStatus.ACPresent | 1 (=yes)
|================================================
As you can see, variables that describe the battery status might be
grouped together under "Battery", variables that describe the input
@ -78,10 +79,11 @@ strings, but as numbers (called "usages" in HID terminology). These
numbers are defined in the "HID Usage Tables", available from
http://www.usb.org/developers/hidpage/. The standard usages for UPS
devices are defined in a document called "Usage Tables for HID Power
Devices".
Devices" (the Power Device Class [PDC] specification).
For example,
For example:
--------------------------------------------------------------------------------
0x00840010 = UPS
0x00840012 = Battery
0x00840030 = Voltage
@ -89,25 +91,28 @@ For example,
0x0084001a = Input
0x0084005a = AudibleAlarmControl
0x00840002 = PresentStatus
0x00850044 = Charging
0x00850044 = Charging
0x00850045 = Discharging
0x008500d0 = ACPresent
--------------------------------------------------------------------------------
Thus, the above usage tree is internally represented as
Thus, the above usage tree is internally represented as:
00840010.00840012.00840030
00840010.00840012.00840040
00840010.0084001a.00840030
00840010.0084001a.00840040
00840010.0084005a
00840010.00840002.00850044
00840010.00840002.00850045
00840010.00840002.008500d0
--------------------------------------------------------------------------------
00840010.00840012.00840030
00840010.00840012.00840040
00840010.0084001a.00840030
00840010.0084001a.00840040
00840010.0084005a
00840010.00840002.00850044
00840010.00840002.00850045
00840010.00840002.008500d0
--------------------------------------------------------------------------------
To make matters worse, most manufacturers define their own additional
usages, even in cases where standard usages could have been used. for
example Belkin defines 00860040 = ConfigVoltage (which is incidentally
a violation of the USB specification, as 00860040 is reserved for
example Belkin defines `00860040` = ConfigVoltage (which is incidentally
a violation of the USB PDC specification, as `00860040` is reserved for
future use).
Thus, subdrivers generally need to provide:
@ -120,8 +125,9 @@ such as custom implementations of specific instant commands (load.off,
shutdown.restart), and conversions of manufacturer specific data
formats.
Writing a subdriver
===================
~~~~~~~~~~~~~~~~~~~
In preparation for writing a subdriver for a device that is currently
unsupported, run usbhid-ups with the following command line:
@ -143,7 +149,7 @@ CUSTOMIZATION below).
Use the script as follows:
scripts/subdriver/path-to-subdriver.sh < /tmp/info
scripts/subdriver/path-to-subdriver.sh < /tmp/info
where /tmp/info is the file where you previously saved the debugging
information.
@ -168,16 +174,22 @@ attempts to monitor some UPS variables. To make this driver useful,
you must examine the NUT variables of the form "unmapped.*" in the
hid_info_t data structure, and map them to actual NUT variables and
instant commands. There are currently no step-by-step instructions for
how to do this. Please look at the files
how to do this. Please look at the files to see how the currently implemented
subdrivers are written.:
mge-hid.c/h
apc-hid.c/h
belkin-hid.c/h
- apc-hid.c/h
- belkin-hid.c/h
- cps-hid.c/h
- explore-hid.c/h
- libhid.c/h
- liebert-hid.c/h
- mge-hid.c/h
- powercom-hid.c/h
- tripplite-hid.c/h
to see how the currently implemented subdrivers are written.
Shutting down the UPS
=====================
~~~~~~~~~~~~~~~~~~~~~
It is desireable to support shutting down the UPS. Usually (for
devices that follow the HID Power Device Class specification), this
@ -191,31 +203,31 @@ commands to the UPS in response to sending one NUT command to the
driver, this is handled by the driver. In order to make this work,
you need to define the following four NUT values:
ups.delay.start (variable, R/W)
ups.delay.shutdown (variable, R/W)
load.off.delay (command)
load.on.delay (command)
ups.delay.start (variable, R/W)
ups.delay.shutdown (variable, R/W)
load.off.delay (command)
load.on.delay (command)
If the UPS supports it, the following variables can be used to show
the countdown to start/shutdown:
ups.timer.start (variable, R/O)
ups.timer.shutdown (variable, R/O)
ups.timer.start (variable, R/O)
ups.timer.shutdown (variable, R/O)
The 'load.on' and 'load.off' commands will be defined implicitly by
The `load.on` and `load.off` commands will be defined implicitly by
the driver (using a delay value of '0'). Define these commands
yourself, if your UPS requires a different value to switch on/off
the load without delay.
Note that the driver expects the 'load.off.delay' and 'load.on.delay'
Note that the driver expects the `load.off.delay` and `load.on.delay`
to follow the HID Power Device Class specification, which means that
the 'load.on.delay' command should NOT switch on the load in the
the `load.on.delay` command should NOT switch on the load in the
absence of mains power. If your UPS switches on the load regardless of
the mains status, DO NOT define this command. You probably want to
define the 'shutdown.return' and/or 'shutdown.stayoff' commands in
define the `shutdown.return` and/or `shutdown.stayoff` commands in
that case. Commands defined in the subdriver will take precedence over
the ones that are composed in the driver.
When running the driver with the '-k' flag, it will first attempt to
send a 'shutdown.return' command and if that fails, will fallback to
'shutdown.reboot'.
send a `shutdown.return` command and if that fails, will fallback to
`shutdown.reboot`.

335
docs/history.txt Normal file
View file

@ -0,0 +1,335 @@
ifdef::website[]
Project history
===============
endif::website[]
This page is an attempt to document how everything came together.
The Network UPS Tools team would like to warmly thank Russell Kroll.
Russell initially started this project, maintaining and improving it for
over 8 years (1996 - mid 2005).
Prototypes and experiments
--------------------------
May 1996: early status hacks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
APC's Powerchute was running on kadets.d20.co.edu (a BSD/OS box) with
SCO binary emulation. Early test versions ran in cron, pulled status
from the log files and wrote them to a .plan file. You could see the
results by fingering `pwrchute@kadets.d20.co.edu` while it lasted:
------------------------------------------------------------------------
Last login Sat May 11 21:33 (MDT) on ttyp0 from intrepid.rmi.net
Plan:
Welcome to the UPS monitor service at kadets.d20.co.edu.
The Smart-UPS attached to kadets generated a report at 14:24:01 on 05/17/96.
During the measured period, the following data points were taken:
Voltage ranged from 115.0 VAC to 116.3 VAC.
The UPS generated 116.3 VAC at 60.00 Hz.
The battery level was at 27.60 volts.
The load placed on the UPS was 024.9 percent.
UPS temperature was measured at 045.0 degrees Celsius.
Measurements are taken every 10 minutes by the upsd daemon.
This report is generated by a script written by Russell Kroll<rkroll@kadets>.
Modified for compatibility with the BSD/OS cron daemon by Neil Schroeder
------------------------------------------------------------------------
This same status data could also be seen with a web browser, since we
had rigged up a CGI wrapper script which called finger.
January 1997: initial protocol tests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Initial tests with a freestanding non-daemon program provided a few
basic status registers from the UPS. The 940-0024C cable was not yet
understood, so this happened over the [attachment:apcevilhack.jpg evil
two-wire serial hack].
------------------------------------------------------------------------
Communicating with SMART-UPS 700 S/N WS9643050926 [10/17/96]
Input voltage range: 117.6 VAC - 118.9 VAC
Load is 010.9% of capacity, battery is charged to 100.0% of capacity
------------------------------------------------------------------------
Note that today's apcsmart driver still displays the serial number when
it starts, since it is derived from this original code.
September 1997: first client/server code
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The first split daemon/client code was written. upsd spoke directly to
the UPS (APC Smart models only) and communicated with upsc by sending
binary structures in UDP datagrams.
The first CGI interface existed, but it was all implemented with shell
scripts. The main script would call upsc to retrieve status values. Then
it would cat a template file through sed to plug them into the page.
image::images/old-cgi.png[Old CGI screenshot]
upsstats actually has since returned to using templates, despite having
a period in the middle when it used hardcoded HTML.
The images were also created with shell scripts. Each script would call
upsc to get the right value (utility, upsload, battcap). It then took
the value, plugged it into a command file with sed, and passed that into
'fly', a program which used an interpreted language to create images.
fly actually uses gd, just like upsimage does today.
This code later evolved into Smart UPS Tools 0.10.
Smart UPS Tools
---------------
March 1998: first public release
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Version 0.10 was released on March 10, 1998. It used the same design as
the pre-release prototype. This made expansion difficult as the binary
structure used for network communications would break any time a new
variable was added. Due to byte-ordering and struct alignment issues,
the code usually couldn't talk over the network to a system with a
different architecture. It was also hopelessly bound to one type of UPS
hardware.
Five more releases followed with this design followed. The last was
0.34, released October 27, 1998.
June 1999: Redesigned, rewritten
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Following a long period of inactivity and two months of prerelease
testing versions, 0.40.0 was released on June 5, 1999. It featured a
complete redesign and rewrite of all of the code. The layering was now
in three pieces, with the single driver (smartups) separate from the
server (upsd).
Clients remained separate as before and still used UDP to talk to the
server, but they now used a text-based protocol instead of the brittle
binary structs. A typical request like "REQ UTILITY" would be answered
with "ANS UTILITY 120.0".
The ups-trust425-625 driver appeared shortly after the release of
0.40.0, marking the first expansion beyond APC hardware.
Over the months that followed, the backupspro driver would be forked
from the smartups driver to handle the APC Back-UPS Pro line. Then the
backups driver was written to handle the APC Back-UPS contact-closure
models. These drivers would later be renamed and recombined, with
smartups and backupspro becoming apcsmart, and backups became genericups.
The drivers stored status data in an array. At first, they passed this data to
upsd by saving it to a file. upsd would reread this file every few seconds to
keep a copy for itself. This was later expanded to allow shared memory mode,
where only a stub would remain on the disk. The drivers and server then passed
data through the shared memory space.
upsd picked up the ability to monitor multiple drivers on the system, and the
"upsname@hostname" scheme was born. Access controls were added, and then the
network code was expanded to allow TCP communications, which at this point were
on port 3305.
Network UPS Tools
-----------------
September 1999: new name, new URL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Several visitors to the web page and subscribers to the mailing lists provided
suggestions to rename the project. The old name no longer accurately described
it, and it was perilously close to APC's "Smart-UPS" trademark. Rather than risk
problems in the future, the name was changed. Kern Sibbald provided the winner:
Network UPS Tools, which captures the essence of the project and makes for great
short tarball filenames: nut-x.y.z.tar.gz.
The new name was first applied to 0.42.0, released October 31, 1999. This is
also when the web pages moved from the old `http://www.exploits.org/~rkroll/smartupstools/`
URL to the replacement at `http://www.exploits.org/nut/` to coincide with the
name change.
More drivers were written and the hardware support continued to grow. upsmon
picked up the concepts of "master" and "slave", and could now handle
environments where multiple systems get power from a single UPS. Manager mode
was added to allow changing the value of read/write variables in certain UPS
models.
June 2001: common driver core
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Up to this point, all of the drivers compiled into freestanding programs, each
providing their own implementation of main(). This meant they all had to check
the incoming arguments and act uniformly. Unfortunately, not all of the programs
behaved the same way, and it was hard to document and use consistently. It also
meant that startup scripts had to be edited depending on what kind of hardware
was attached.
Starting in 0.45.0, released June 11, 2001, there was a new common core for all drivers called main.c. It provided the main function and called back to the upsdrv_* functions provided by the hardware-specific part of the drivers. This allowed driver authors to focus on the UPS hardware without worrying about the housekeeping stuff that needs to happen.
This new design provided an obvious way to configure drivers from one file, and ups.conf was born. This eventually spawned upsdrvctl, and now all drivers based on this common core could be started or stopped with one command. Startup scripts now could contain "upsdrvctl start", and it didn't matter what kind of hardware or how many UPSes you had on one system.
Interestingly, at the end of this month, Arnaud Quette entered the UPS world, as a subcontractor of the now defunct MGE UPS SYSTEMS.
This marks the start of a future successful collaboration.
May 2002: casting off old drivers, IANA port, towards 1.0
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
During the 0.45.x series, both the old standalone drivers and the ones which had been converted to the common core were released together. Before the release of 0.50.0 on May 24, 2002, all of the old drivers were removed. While this shrank the list of supported hardware, it set the precedent for removing code which isn't receiving regular maintenance. The assumption is that the code will be brought back up to date by someone if they actually need it. Otherwise, it's just dead weight in the tree.
This change meant that all drivers could be controlled with upsdrvctl and ups.conf, allowing the documentation to be greatly simplified. There was no longer any reason to say "do this, unless you have this driver, then do this".
IANA granted an official port number to the project, and the network code switched to port 3493. It had previously been on 3305 which is assigned to odette-ftp. 3305 was probably picked in 1997 because it was the fifth project to spawn from some common UDP server code.
After 0.50.1, the 0.99 tree was created to provide a tree which would receive nothing but bug fixes in preparation for the release of 1.0. As it turned out, very few things required fixing, and there were only three releases in this tree.
Leaving 0.x territory
---------------------
August 2002: first stable tree: NUT 1.0.0
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
After nearly 5 years of having a 0.x version number, 1.0.0 was released on August 19, 2002. This milestone meant that all of the base features that you would expect to find were intact: good hardware support, a network server with security controls, and system shutdowns that worked.
The design was showing signs of wear from the rapid expansion, but this was intentionally ignored for the moment. The focus was on getting a good version out that would provide a reasonable base while the design issues could be addressed in the future, and I'm confident that we succeeded.
November 2002: second stable tree: NUT 1.2.0
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
One day after the release of 1.0.0, 1.1.0 started the new development tree. During that development cycle, the CGI programs were rewritten to use templates instead of hard-coded HTML, thus bringing back the flexibility of the original unreleased prototype from 5 years before. multimon was removed from the tree, as the new upsstats could do both jobs by loading different templates.
A new client library called upsclient was created, and it replaced upsfetch. This new library only supported TCP connections, and used an opaque context struct to keep state for each connection. As a result, client programs could now do things that used multiple connections without any conflicts. This was done primarily to allow OpenSSL support, but there were other benefits from the redesign.
upsd and the clients could now use OpenSSL for basic authentication and encryption, but this was not included by default. This was provided as a bonus feature for those users who cared to read about it and enable the option, as the initial setup was complex.
After the 1.1 tree was frozen and deemed complete, it became the second stable tree with the release of 1.2.0 on November 5, 2002.
April 2003: new naming scheme, better driver glue, and an overhauled protocol
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Following an extended period with no development tree, 1.3.0 got things moving again on April 13, 2003. The focus of this tree was to rewrite the driver-server communication layer and replace the static naming scheme for variables and commands.
Up to this point, all variables had names like STATUS, UTILITY, and OUTVOLT. They had been created as drivers were added to the tree, and there was little consistency. For example, it probably should have been INVOLT and OUTVOLT, but there was no OUTVOLT originally, so UTILITY was all we had. This same pattern repeated with ACFREQ - is it incoming or outgoing? - and many more.
To solve this problem, all variables and commands were renamed to a hierarchical scheme that had obvious grouping. STATUS became ups.status. UTILITY turned into input.voltage, and OUTVOLT is output.voltage. ACFREQ is input.frequency, and the new output.frequency is also now supported. Every other variable or command was renamed in this fashion.
These variables had been shared between the drivers and upsd as values. That is, for each name like STATUS, there was a #define somewhere in the tree with an INFO_ prefix that gave it a number. INFO_STATUS was 0x0006, INFO_UTILITY was 0x0004, and so on, with each name having a matching number. This number was stored in an int within a structure which was part of the array that was either written to disk or shared memory.
That structure had several restrictions on expansion and was dropped as the data sharing method between the drivers and the server. It was replaced by a new system of text-based messages over Unix domain sockets. Drivers now accepted a short list of commands from upsd, and would push out updates asynchronously. upsd no longer had to poll the state files or shared memory. It could just select all of the driver and client fds and act on events.
At the same time, the network protocol on port 3493 was overhauled to take advantage of the new naming scheme. The existing "REQ STATUS@su700", "ANS STATUS@su700 OL" scheme was showing signs of age, and it really only supported the UPS name (@su700) as an afterthought. The new protocol would now use commands like GET and LIST, leading to exchanges like "GET VAR su700 ups.status" and "VAR su700 ups.status OL". The responses contain enough data to stand alone, so clients can now handle them asynchronously.
July 2003: third stable tree: NUT 1.4.0
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
On July 25, 2003, 1.4.0 was released. It contained support for both the old "REQ" style protocol (with names like STATUS), and the new "GET" style protocol (with names like ups.status). This tree is provided to bridge the gap between all of the old releases and the upcoming 2.0.
2.0 will be released without support for the old REQ/STATUS protocol. The hope is that client authors and those who have implemented their own monitoring software will use the 1.4 cycle to change to the new protocol. The 1.4 releases contain a lot of compatibility code to make sure both work at the same time.
July 2003: pushing towards 2.0
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1.5.0 forked from 1.4.0 and was released on July 29, 2003. The first changes were to throw out anything which was providing compatibilty with the older versions of the software. This means that 1.5 and the eventual 2.0 will not talk to anything older than 1.4.
This tree continues to evolve with new serial routines for the drivers which are intended to replace the aging upscommon code which dates back to the early 0.x releases. The original routines would call alarm and read in a tight loop while fetching characters. The new functions are much cleaner, and wait for data with select. This makes for much cleaner code and easier strace/ktrace logs, since the number of syscalls has been greatly reduced.
There has also been a push to make sure the data from the UPS is well-formed and is actually usable before sending updates out to upsd. This started during 1.3 as drivers were adapted to use the dstate functions and the new variable/command names. Some drivers which were not converted to the new naming scheme or didn't do sanity checks on the incoming UPS data from the serial port were dropped from the tree.
This tree was released as 2.0.0.
networkupstools.org
-------------------
November 2003: a new URL
~~~~~~~~~~~~~~~~~~~~~~~~
The bandwidth demands of a project like this have slowly been forcing me to offload certain parts to other servers. The download links have pointed offsite for many months, and other large things like certain UPS protocols have followed. As the traffic grows, it's clear that having the project attached to exploits.org is not going to work.
The solution was to register a new domain and set up mirrors. There are two initial web servers, with more on the way. The main project URL has changed from `http://www.exploits.org/nut/` to http://www.networkupstools.org. The actual content is hosted on various mirrors which are updated regularly with rsync, so the days of dribbling bits through my DSL should be over.
This is also when all of the web pages were redesigned to have a simpler look with fewer links on the left side. The old web pages used to have 30 or more links on the top page, and most of them vanished when you dropped down one level. The links are now constant on the entire site, and the old links now live in their own groups in separate directories.
Second major version
--------------------
March 2004: NUT 2.0.0
~~~~~~~~~~~~~~~~~~~~~
NUT 2.0.0 arrived on March 23, 2004. The jump to version 2 shows the difference
in the protocols and naming that happened during the 1.3 and 1.5 development
series. 2.0 no longer ships with backwards compatibility code, so it's smaller
and cleaner than 1.4.
The change of leadership
------------------------
February 2005: NUT 2.0.1
~~~~~~~~~~~~~~~~~~~~~~~~
The year 2004 was marked by a release slowdown, since Russell was busy with
personal subjects. But the patches queue was still growing quickly.
At that time, the development process was still centralized. There was no
revision control system (like the current Subversion repository), nor trackers
to interact with NUT development.
Russell was receiving all the patches and requests, and doing all the work on
his own, including releases.
Russell was more and more thinking about giving the project leadership to
Arnaud Quette, which finally happened with the 2.0.1 release in February 2005.
This marked a new era for NUT...
First, Arnaud aimed at opening up the development by creating a project on the
http://www.debian.org/[Debian] http://alioth.debian.org/projects/nut/[Alioth Forge].
This allowed to build the team of hackers that Russell dreamed about.
It also allows to ensure NUT's continuation, whatever happens to
the leader. And that would most of all boost the projects contributions.
////////////////////////////////////////////////////////////////////////
*sandbox*
TO BE COMPLETED + ADD A LINK TO IDEA / FUTURE
link on the team + history
mention:
- MGE supporting officially,
- USB / SNMP / XML drivers (first non serial drivers),
- Power Management (HAL) bridging,
- PDU support,
- perl / python support...
- client history and evolution (wmnut: 01/01/2002)
release history
<LI>July 7, 2008: Client activity: new client <A HREF="http://www.lestat.st/informatique/projets/nut-monitor-en">NUT-Monitor</A>
<LI>June 27, 2008: Client activity: new Python class <A HREF="http://www.lestat.st/informatique/projets/pynut-en">PyNUT</A>
<LI>June 19, 2008: Client activity: <A HREF="http://www.knut.noveradsl.cz/knutclient/">KNutClient 0.9.4</A>
<LI>May 7, 2008: 2.2.2 released
<LI>December 21, 2007: 2.2.1 released
<LI>August 31, 2007: Client activity: <A HREF="http://rudd-o.com/projects/ups-monitor/">UPS Monitor</A> link update
<LI>August 31, 2007: Client activity: <A HREF="http://sourceforge.net/projects/winnutclient/">Windows NUT client 1.5.0</A>
<LI>July 5, 2007: 2.2.0 released
<LI>June 5, 2007: Client activity: <A HREF="http://collectd.org/">collectd NUT plugin</A>
<LI>April 10, 2007: Client activity: <A HREF="http://www.knut.noveradsl.cz/knutclient/">KNutClient 0.9.3</A>
<LI>January 15, 2007: 2.0.5 released
<LI>January 8, 2007: Client activity: <A HREF="http://sourceforge.net/projects/winnutclient/">Windows NUT client</A>
<!-- LI>July 27, 2006: 2.0.4 released
<LI>February 7, 2006: 2.0.3 released
<LI>June 27, 2005: 2.0.2 released
<LI>June 15, 2005: new <A HREF="lists/index.html">mailing lists</A> ready on <A HREF="http://alioth.debian.org/mail/?group_id=30602">Alioth</A>
<LI>April 15, 2005: new development infrastructure ready on <A HREF="http://alioth.debian.org/projects/nut/">Alioth</A>
<LI>March 15, 2005: Client activity: first beta of MGE <A HREF="http://www.mgeups.com/products/pdt230/software/sp97/solpaclinux.htm">Personal Solution Pac</A>
<LI>March 11, 2005: Client activity: <A HREF="http://www.amautacorp.com/staff/Rudd-O/projects/pages/ups-front">UPS Monitor</A> 0.8 released
<LI>February 24, 2005: 2.0.1 released
Note: use the NEWS file!
////////////////////////////////////////////////////////////////////////

85
docs/ideas.txt
View file

@ -1,85 +0,0 @@
Desc: Ideas for future expansion and features
File: ideas.txt
Date: 20 October 2003
Auth: Russell Kroll <rkroll@exploits.org>
Here are some ideas that have come up over the years but haven't
been implemented yet. This may be a good place to start if you're
looking for a rainy day hacking project.
Non-network "upsmon"
====================
Some systems don't want a daemon listening to the network. This can be
for security reasons, or perhaps because the system has been squashed
down and doesn't have TCP/IP available. For these situations you could
run a driver and program that sits on top of the driver socket to do
local monitoring.
This also makes monitoring extremely easy to automate - you don't need
to worry about usernames, passwords or firewalling. Just start a driver
and drop this program on top of it.
- Parse ups.conf and open the state socket for a driver
- Send DUMPALL and enter a select loop
- Parse SETINFOs that change ups.status
- When you get OB LB, shut down
Completely unprivileged upsmon
==============================
upsmon currently retains root in a forked process so it can call the
shutdown command. The only reason it needs root on most systems is that
only privileged users can signal init or send a message on /dev/initctl.
In the case of systems running sysvinit (Slackware, others?), upsmon
could just open /dev/initctl while it has root and then drop it
completely. When it's time to shut down, fire a control structure at
init across the lingering socket and tell it to enter runlevel 0.
This has been shown to work in local tests, but it's not portable. It
could only be offered as an option for those systems which run that
flavor of init. It also needs to be tested to see what happens to
the lingering fd over time, such as when init restarts after an upgrade.
For other systems, there is always the possibility of having a suid
program which does nothing but prod init into starting a shutdown. Lock
down the group access so only upsmon's unprivileged user can access it,
and make that your SHUTDOWNCMD. Then it could drop root completely.
Chrooted upsmon
===============
upsmon could run the network monitoring part in a chroot jail if it had
a pipe to another process running outside for NOTIFY dispatches. Such a
pipe would have to be constructed extremely carefully so an attacker
could not compromise it from the jailed process.
A state machine with a tightly defined sequence could do this safely.
All it has to do is dispatch the UPS name and event type.
[start] [type] [length] <name> [stop]
Monitor program with interpreted language
=========================================
Once in awhile, I get requests for a way to shut down based on the UPS
temperature, or ambient humidity, or at a certain battery charge level,
or any number of things other than an "OB LB" status. It should be
obvious that adding a way to monitor all of that in upsmon would bloat
upsmon for all those people who really don't need anything like that.
A separate program that interprets a list of rules and uses it to
monitor the UPS equipment is the way to solve this. If you have a
condition that needs to be tested, add a rule.
Some of the tools that such a language would need include simple
greater-than/less-than testing (if battery.charge < 20), equivalence
testing (if ups.model = "SMART-UPS 700"), and some way to set and clear
timers.
Due to the expected size and limited audience for such a program, it
might have to be distributed separately.

BIN
docs/images/advanced.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 31 KiB

BIN
docs/images/asciidoc.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 1.8 KiB

BIN
docs/images/bigbox.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 17 KiB

BIN
docs/images/bizarre.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 33 KiB

BIN
docs/images/blue-arrow.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 562 B

BIN
docs/images/cables/73-0724.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 1.9 KiB

BIN
docs/images/cables/940-0024C.jpg Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 15 KiB

BIN
docs/images/cables/Lansafecable.jpg Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 52 KiB

BIN
docs/images/cables/SOLA-330.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 5.4 KiB

BIN
docs/images/cables/belkin-f6cx-rkm-xu-cable.jpg Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 17 KiB

BIN
docs/images/cables/mac-940-0024C.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 12 KiB

BIN
docs/images/cables/mge-66049.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 6.6 KiB

BIN
docs/images/cables/mge-db9-rj12.jpg Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 21 KiB

BIN
docs/images/cables/mge-db9-rj45.jpg Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 17 KiB

BIN
docs/images/eaton-logo.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 7.8 KiB

BIN
docs/images/note.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 2.4 KiB

BIN
docs/images/nut_layering.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 82 KiB

BIN
docs/images/old-cgi.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 8.5 KiB

BIN
docs/images/simple.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 9.9 KiB

BIN
docs/images/warning.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 3.1 KiB

114
docs/macros.txt
View file

@ -1,66 +1,72 @@
Desc: NUT-specific autoconf macros
File: macros.txt
Date: 27 December 2006
Auth: Peter Selinger <selinger@users.sourceforge.net>
NUT-specific autoconf macros
----------------------------
The following NUT-specific autoconf macros are defined in the m4/
directory.
- Macro: NUT_TYPE_SOCKLEN_T
- Macro: NUT_TYPE_UINT8_T
- Macro: NUT_TYPE_UINT16_T
Check for the corresponding type in the system header files, and
#define a replacement if necessary.
- NUT_TYPE_SOCKLEN_T
- NUT_TYPE_UINT8_T
- NUT_TYPE_UINT16_T
- Macro: NUT_CHECK_LIBGD
- Macro: NUT_CHECK_LIBHAL
- Macro: NUT_CHECK_LIBNEON
- Macro: NUT_CHECK_LIBNETSNMP
- Macro: NUT_CHECK_LIBPOWERMAN
- Macro: NUT_CHECK_LIBSSL
- Macro: NUT_CHECK_LIBUSB
- Macro: NUT_CHECK_LIBWRAP
Determine the compiler flags for the corresponding library. On
success, set nut_have_libxxx="yes" and set LIBXXX_CFLAGS and
LIBXXX_LDFLAGS. On failure, set nut_have_libxxx="no". This macro
can be run multiple times, but will do the checking only once.
Here "xxx" should of course be replaced by the respective library name.
Check for the corresponding type in the system header files, and
#define a replacement if necessary.
The checks for each library grow organically to compensate for
various bugs in the libraries, pkg-config, etc. This is why we have
a separate macro for each library.
- NUT_CHECK_LIBGD
- NUT_CHECK_LIBHAL
- NUT_CHECK_LIBNEON
- NUT_CHECK_LIBNETSNMP
- NUT_CHECK_LIBPOWERMAN
- NUT_CHECK_LIBSSL
- NUT_CHECK_LIBUSB
- NUT_CHECK_LIBWRAP
- Macro: NUT_CHECK_IPV6
Check for various features required to compile the IPv6 support.
dnl Check for various features required for IPv6 support. Define a
preprocessor symbol for each individual feature (HAVE_GETADDRINFO,
HAVE_FREEADDRINFO, HAVE_STRUCT_ADDRINFO, HAVE_SOCKADDR_STORAGE,
SOCKADDR_IN6, IN6_ADDR, HAVE_IN6_IS_ADDR_V4MAPPED,
HAVE_AI_ADDRCONFIG). Also set the shell variable nut_have_ipv6=yes
if all the required features are present. Set nut_have_ipv6=no
otherwise.
Determine the compiler flags for the corresponding library. On
success, set nut_have_libxxx="yes" and set LIBXXX_CFLAGS and
LIBXXX_LDFLAGS. On failure, set nut_have_libxxx="no". This macro
can be run multiple times, but will do the checking only once.
Here "xxx" should of course be replaced by the respective library name.
- Macro: NUT_CHECK_OS
Check for the exact system name and type.
This was only used in the past to determine the packaging rule to be used
through the OS_NAME variable, but may be useful for other purposes in the
future.
The checks for each library grow organically to compensate for
various bugs in the libraries, pkg-config, etc. This is why we have
a separate macro for each library.
- Macro: NUT_REPORT_FEATURE(FEATURE, VALUE)
Schedule a line for the end-of-configuration feature summary. The
FEATURE is a descriptive string such that the sentence "Checking
whether to FEATURE" makes sense, and VALUE describes the decision
taken (typically yes or no). The feature is also reported to the
terminal.
- NUT_CHECK_IPV6
- Macro: NUT_REPORT(FEATURE, VALUE)
Schedule a line for the end-of-configuration feature summary, without
printing anything to the terminal immediately.
Check for various features required to compile the IPv6 support.
dnl Check for various features required for IPv6 support. Define a
preprocessor symbol for each individual feature (HAVE_GETADDRINFO,
HAVE_FREEADDRINFO, HAVE_STRUCT_ADDRINFO, HAVE_SOCKADDR_STORAGE,
SOCKADDR_IN6, IN6_ADDR, HAVE_IN6_IS_ADDR_V4MAPPED,
HAVE_AI_ADDRCONFIG). Also set the shell variable nut_have_ipv6=yes
if all the required features are present. Set nut_have_ipv6=no
otherwise.
- Macro: NUT_PRINT_FEATURE_REPORT
Print out a list of the features that have been reported by
previous NUT_REPORT_FEATURE macro calls.
- NUT_CHECK_OS
- Macro: NUT_ARG_WITH(FEATURE, DESCRIPTION, DEFAULT)
Declare a simple --with-FEATURE option with the given DESCRIPTION
and DEFAULT. Sets the variable nut_with_FEATURE.
Check for the exact system name and type.
This was only used in the past to determine the packaging rule to be used
through the OS_NAME variable, but may be useful for other purposes in the
future.
- NUT_REPORT_FEATURE(FEATURE, VALUE)
Schedule a line for the end-of-configuration feature summary. The
FEATURE is a descriptive string such that the sentence "Checking
whether to FEATURE" makes sense, and VALUE describes the decision
taken (typically yes or no). The feature is also reported to the
terminal.
- NUT_REPORT(FEATURE, VALUE)
Schedule a line for the end-of-configuration feature summary, without
printing anything to the terminal immediately.
- NUT_PRINT_FEATURE_REPORT
Print out a list of the features that have been reported by
previous NUT_REPORT_FEATURE macro calls.
- NUT_ARG_WITH(FEATURE, DESCRIPTION, DEFAULT)
Declare a simple --with-FEATURE option with the given DESCRIPTION
and DEFAULT. Sets the variable nut_with_FEATURE.

452
docs/man/Makefile.am Normal file
View file

@ -0,0 +1,452 @@
# Network UPS Tools: man
#
# Notes:
# - sources (.txt) and groff formats are both distributed,
# - only sources are versioned ; groff files are generated at worst
# during 'make dist'
# - HTML files are built upon request, if AsciiDoc is available,
# - groff update will only happen if AsciiDoc is available too,
# - all this can probably (and hopefully) by improved, but I've not
# found a way to do pattern replacement on the fly for target deps!
# - Ref: http://www.gnu.org/software/hello/manual/automake/Man-pages.html
# Base configuration and client manpages, always installed
SRC_CONF_PAGES = \
nut.conf.txt \
ups.conf.txt \
upsd.conf.txt \
upsd.users.txt \
upsmon.conf.txt \
upssched.conf.txt
MAN_CONF_PAGES = \
nut.conf.5 \
ups.conf.5 \
upsd.conf.5 \
upsd.users.5 \
upsmon.conf.5 \
upssched.conf.5
man5_MANS = $(MAN_CONF_PAGES)
HTML_CONF_MANS = \
nut.conf.html \
ups.conf.html \
upsd.conf.html \
upsd.users.html \
upsmon.conf.html \
upssched.conf.html
SRC_CLIENT_PAGES = \
nutupsdrv.txt \
upsc.txt \
upscmd.txt \
upsd.txt \
upsdrvctl.txt \
upslog.txt \
upsmon.txt \
upsrw.txt \
upssched.txt
MAN_CLIENT_PAGES = \
nutupsdrv.8 \
upsc.8 \
upscmd.8 \
upsd.8 \
upsdrvctl.8 \
upslog.8 \
upsmon.8 \
upsrw.8 \
upssched.8
man8_MANS = $(MAN_CLIENT_PAGES)
HTML_CLIENT_MANS = \
nutupsdrv.html \
upsc.html \
upscmd.html \
upsd.html \
upsdrvctl.html \
upslog.html \
upsmon.html \
upsrw.html \
upssched.html
# CGI (--with-cgi) related manpages
SRC_CGI_PAGES = \
hosts.conf.txt \
upsset.conf.txt \
upsstats.html.txt \
upsset.cgi.txt \
upsstats.cgi.txt \
upsimage.cgi.txt
MAN5_CGI_PAGES = \
hosts.conf.5 \
upsset.conf.5 \
upsstats.html.5
MAN8_CGI_PAGES = \
upsset.cgi.8 \
upsstats.cgi.8 \
upsimage.cgi.8
if WITH_CGI
man5_MANS += $(MAN5_CGI_PAGES)
man8_MANS += $(MAN8_CGI_PAGES)
endif
HTML_CGI_MANS = \
hosts.conf.html \
upsset.conf.html \
upsstats.html.html \
upsset.cgi.html \
upsstats.cgi.html \
upsimage.cgi.html
# Development (--with-dev) related manpages
SRC_DEV_PAGES = \
upsclient.txt \
upscli_connect.txt \
upscli_disconnect.txt \
upscli_fd.txt \
upscli_get.txt \
upscli_list_next.txt \
upscli_list_start.txt \
upscli_readline.txt \
upscli_sendline.txt \
upscli_splitaddr.txt \
upscli_splitname.txt \
upscli_ssl.txt \
upscli_strerror.txt \
upscli_upserror.txt \
libupsclient-config.txt \
skel.txt
MAN3_DEV_PAGES = \
upsclient.3 \
upscli_connect.3 \
upscli_disconnect.3 \
upscli_fd.3 \
upscli_get.3 \
upscli_list_next.3 \
upscli_list_start.3 \
upscli_readline.3 \
upscli_sendline.3 \
upscli_splitaddr.3 \
upscli_splitname.3 \
upscli_ssl.3 \
upscli_strerror.3 \
upscli_upserror.3
MAN1_DEV_PAGES = \
libupsclient-config.1
if WITH_DEV
man3_MANS = $(MAN3_DEV_PAGES)
if !WITH_PKG_CONFIG
man1_MANS = $(MAN1_DEV_PAGES)
endif
# WITH_DEV
endif
HTML_DEV_MANS = \
upsclient.html \
upscli_connect.html \
upscli_disconnect.html \
upscli_fd.html \
upscli_get.html \
upscli_list_next.html \
upscli_list_start.html \
upscli_readline.html \
upscli_sendline.html \
upscli_splitaddr.html \
upscli_splitname.html \
upscli_ssl.html \
upscli_strerror.html \
upscli_upserror.html \
libupsclient-config.html \
skel.html
# Drivers related manpages
# (--with-drivers=...)
if SOME_DRIVERS
man8_MANS += $(DRIVER_MAN_LIST)
else
# (--with-serial)
SRC_SERIAL_PAGES = \
apcsmart.txt \
bcmxcp.txt \
belkin.txt \
belkinunv.txt \
bestfortress.txt \
bestuferrups.txt \
bestups.txt \
bestfcom.txt \
blazer.txt \
clone.txt \
dummy-ups.txt \
etapro.txt \
everups.txt \
gamatronic.txt \
genericups.txt \
isbmex.txt \
ivtscd.txt \
liebert.txt \
liebert-esp2.txt \
masterguard.txt \
metasys.txt \
mge-shut.txt \
mge-utalk.txt \
oneac.txt \
microdowell.txt \
optiups.txt \
powercom.txt \
powerpanel.txt \
rhino.txt \
safenet.txt \
solis.txt \
tripplite.txt \
tripplitesu.txt \
upscode2.txt \
victronups.txt
MAN_SERIAL_PAGES = \
apcsmart.8 \
bcmxcp.8 \
belkin.8 \
belkinunv.8 \
bestfortress.8 \
bestuferrups.8 \
bestups.8 \
bestfcom.8 \
blazer.8 \
clone.8 \
dummy-ups.8 \
etapro.8 \
everups.8 \
gamatronic.8 \
genericups.8 \
isbmex.8 \
ivtscd.8 \
liebert.8 \
liebert-esp2.8 \
masterguard.8 \
metasys.8 \
mge-shut.8 \
mge-utalk.8 \
oneac.8 \
microdowell.8 \
optiups.8 \
powercom.8 \
powerpanel.8 \
rhino.8 \
safenet.8 \
solis.8 \
tripplite.8 \
tripplitesu.8 \
upscode2.8 \
victronups.8
if WITH_SERIAL
man8_MANS += $(MAN_SERIAL_PAGES)
endif
HTML_SERIAL_MANS = \
apcsmart.html \
bcmxcp.html \
belkin.html \
belkinunv.html \
bestfortress.html \
bestuferrups.html \
bestups.html \
bestfcom.html \
blazer.html \
clone.html \
dummy-ups.html \
etapro.html \
everups.html \
gamatronic.html \
genericups.html \
isbmex.html \
ivtscd.html \
liebert.html \
liebert-esp2.html \
masterguard.html \
metasys.html \
mge-shut.html \
mge-utalk.html \
oneac.html \
microdowell.html \
optiups.html \
powercom.html \
powerpanel.html \
rhino.html \
safenet.html \
solis.html \
tripplite.html \
tripplitesu.html \
upscode2.html \
victronups.html
# (--with-snmp)
SRC_SNMP_PAGES = snmp-ups.txt
MAN_SNMP_PAGES = snmp-ups.8
if WITH_SNMP
man8_MANS += $(MAN_SNMP_PAGES)
endif
HTML_SNMP_MANS = snmp-ups.html
# (--with-usb)
SRC_USB_LIBUSB_PAGES = \
bcmxcp_usb.txt \
richcomm_usb.txt \
tripplite_usb.txt \
usbhid-ups.txt
MAN_USB_LIBUSB_PAGES = \
bcmxcp_usb.8 \
richcomm_usb.8 \
tripplite_usb.8 \
usbhid-ups.8
if WITH_USB
man8_MANS += $(MAN_USB_LIBUSB_PAGES)
endif
HTML_USB_LIBUSB_MANS = \
bcmxcp_usb.html \
richcomm_usb.html \
tripplite_usb.html \
usbhid-ups.html
# (--with-neon)
SRC_NETXML_PAGES = netxml-ups.txt
MAN_NETXML_PAGES = netxml-ups.8
if WITH_NEONXML
man8_MANS += $(MAN_NETXML_PAGES)
endif
HTML_NETXML_MANS = netxml-ups.html
# (--with-powerman)
SRC_POWERMAN_PAGES = powerman-pdu.txt
MAN_POWERMAN_PAGES = powerman-pdu.8
if WITH_LIBPOWERMAN
man8_MANS += $(MAN_POWERMAN_PAGES)
endif
HTML_POWERMAN_MANS = powerman-pdu.html
# SOME_DRIVERS
endif
MAN_MANS = \
$(MAN_CONF_PAGES) \
$(MAN_CLIENT_PAGES) \
$(MAN5_CGI_PAGES) \
$(MAN8_CGI_PAGES) \
$(MAN1_DEV_PAGES) \
$(MAN3_DEV_PAGES) \
$(MAN_SERIAL_PAGES) \
$(MAN_SNMP_PAGES) \
$(MAN_USB_LIBUSB_PAGES) \
$(MAN_NETXML_PAGES) \
$(MAN_POWERMAN_PAGES)
# distribute everything, even those not installed by default
# Note that 'dist' target requires AsciiDoc!
EXTRA_DIST = \
$(SRC_CONF_PAGES) \
$(SRC_CLIENT_PAGES) \
$(SRC_CGI_PAGES) \
$(SRC_DEV_PAGES) \
$(SRC_SERIAL_PAGES) \
$(SRC_SNMP_PAGES) \
$(SRC_USB_LIBUSB_PAGES) \
$(SRC_NETXML_PAGES) \
$(SRC_POWERMAN_PAGES) \
$(MAN_MANS) \
asciidoc.conf
HTML_MANS = \
$(HTML_CONF_MANS) \
$(HTML_CLIENT_MANS) \
$(HTML_CGI_MANS) \
$(HTML_DEV_MANS) \
$(HTML_SERIAL_MANS) \
$(HTML_SNMP_MANS) \
$(HTML_USB_LIBUSB_MANS) \
$(HTML_NETXML_MANS) \
$(HTML_POWERMAN_MANS)
all:
man-index.html: index.html
cp -f $< $@
html-man: $(HTML_MANS) man-index.html
CLEANFILES = *.xml *.html
SUFFIXES = .txt .html .1 .3 .5 .8
if HAVE_ASCIIDOC
.txt.html:
$(ASCIIDOC) --backend=xhtml11 \
--attribute localdate=`TZ=UTC date +%Y-%m-%d` \
--attribute localtime=`TZ=UTC date +%H:%M:%S` \
-o $@ $<
### The --destination-dir flag doesn't seem to affect the intermediate .xml file.
### Hence, the copying dance below.
A2X_MANPAGE_OPTS = -f manpage --attribute nutversion="@PACKAGE_VERSION@"
.txt.1:
test -f `basename $<` || cp -p $< .
$(A2X) $(A2X_MANPAGE_OPTS) `basename $<`
.txt.3:
test -f `basename $<` || cp -p $< .
$(A2X) $(A2X_MANPAGE_OPTS) `basename $<`
.txt.5:
test -f `basename $<` || cp -p $< .
$(A2X) $(A2X_MANPAGE_OPTS) `basename $<`
.txt.8:
test -f `basename $<` || cp -p $< .
$(A2X) $(A2X_MANPAGE_OPTS) `basename $<`
else !HAVE_ASCIIDOC
.txt.html:
@echo "Not (re)building $@ manual page, since 'asciidoc' was not found."
.txt.1:
@echo "Using existing $@ manual page, since 'asciidoc' was not found."
.txt.3:
@echo "Using existing $@ manual page, since 'asciidoc' was not found."
.txt.5:
@echo "Using existing $@ manual page, since 'asciidoc' was not found."
.txt.8:
@echo "Using existing $@ manual page, since 'asciidoc' was not found."
endif !HAVE_ASCIIDOC

1019
docs/man/Makefile.in Normal file
View file

File diff suppressed because it is too large Load diff

124
docs/man/apcsmart.8 Normal file
View file

@ -0,0 +1,124 @@
'\" t
.\" Title: apcsmart
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 12/24/2010
.\" Manual: NUT Manual
.\" Source: Network UPS Tools
.\" Language: English
.\"
.TH "APCSMART" "8" "12/24/2010" "Network UPS Tools" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
apcsmart \- Driver for American Power Conversion Smart Protocol UPS equipment
.SH "SYNOPSIS"
.sp
\fBapcsmart\fR \-h
.sp
\fBapcsmart\fR \-a \fIUPS_NAME\fR [\fIOPTIONS\fR]
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
This man page only documents the hardware\-specific features of the apcsmart driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
.sp .5v
.RE
.SH "SUPPORTED HARDWARE"
.sp
apcsmart should recognize all recent APC models that use a serial protocol at 2400 bps\&. This is primarily the Smart\-UPS, Matrix\-UPS and Back\-UPS Pro lines\&.
.sp
The driver attempts to support every bell and whistle of the APC reporting interface, whether or not this is strictly sensible\&.
.sp
Some older hardware may only report a handful of variables\&. This is usually not a bug\(emthey just don\(cqt support anything else\&.
.SH "CABLING"
.sp
This driver expects to see a 940\-0024C cable or a clone by default\&. You can switch to the 940\-0095B dual\-mode cable support with the cable= definition described below\&.
.sp
If your 940\-0024C cable is broken or missing, use this diagram to build a clone:
.sp
http://www\&.networkupstools\&.org/cables/940\-0024C\&.jpg
.SH "EXTRA ARGUMENTS"
.sp
This driver supports the following optional settings in the \fBups.conf\fR(5):
.PP
\fBcable=940\-0095B\fR
.RS 4
Configure the serial port for the APC 940\-0095B dual\-mode cable\&.
.RE
.PP
\fBsdtype=\fR\fInum\fR
.RS 4
Use shutdown type
\fInum\fR, according to this table:
.PP
0
.RS 4
soft shutdown or powerdown, depending on battery status
.RE
.PP
1
.RS 4
soft shutdown followed by powerdown
.RE
.PP
2
.RS 4
instant power off
.RE
.PP
3
.RS 4
power off with grace period
.RE
.PP
4
.RS 4
"force OB" hack method for CS 350
.RE
.RE
.sp
Modes 0 and 1 will power up the load when power returns\&. Modes 2 and 3 will keep the load turned off when the power returns\&.
.sp
Mode 4 exploits an oddity in the CS 350 models since they only seem to support the S command, but then only when running on battery\&. As a result, the driver will force the UPS to go on battery if necessary before sending the shutdown command\&. This ensures that the load gets reset\&.
.SH "BUGS"
.sp
Some older APC UPS models return bogus data in the status register during a front panel test\&. This is usually detected and discarded, but some other unexpected values have occasionally slipped through\&.
.sp
APC UPS models with both USB and serial ports require a power cycle when switching from USB communication to serial, and perhaps vice versa\&.
.SH "AUTHOR"
.sp
Nigel Metheringham <Nigel\&.Metheringham@Intechnology\&.co\&.uk> (drawing heavily on the original apcsmart driver by Russell Kroll)\&. This driver was called newapc for a time and was renamed in the 1\&.5 series\&.
.SH "SEE ALSO"
.SS "The core driver:"
.sp
\fBnutupsdrv\fR(8)
.SS "Internet resources:"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/

101
docs/man/apcsmart.txt Normal file
View file

@ -0,0 +1,101 @@
APCSMART(8)
===========
NAME
----
apcsmart - Driver for American Power Conversion Smart Protocol UPS equipment
SYNOPSIS
--------
*apcsmart* -h
*apcsmart* -a 'UPS_NAME' ['OPTIONS']
NOTE: This man page only documents the hardware-specific features of the
apcsmart driver. For information about the core driver, see
linkman:nutupsdrv[8].
SUPPORTED HARDWARE
------------------
apcsmart should recognize all recent APC models that use a serial
protocol at 2400 bps. This is primarily the Smart-UPS, Matrix-UPS and
Back-UPS Pro lines.
The driver attempts to support every bell and whistle of the APC
reporting interface, whether or not this is strictly sensible.
Some older hardware may only report a handful of variables. This is
usually not a bug--they just don't support anything else.
CABLING
-------
This driver expects to see a 940-0024C cable or a clone by default. You
can switch to the 940-0095B dual-mode cable support with the `cable=`
definition described below.
If your 940-0024C cable is broken or missing, use this diagram to build
a clone:
http://www.networkupstools.org/cables/940-0024C.jpg
EXTRA ARGUMENTS
---------------
This driver supports the following optional settings in the
linkman:ups.conf[5]:
*cable=940-0095B*::
Configure the serial port for the APC 940-0095B dual-mode cable.
*sdtype=*'num'::
Use shutdown type 'num', according to this table:
0;; soft shutdown or powerdown, depending on battery status
1;; soft shutdown followed by powerdown
2;; instant power off
3;; power off with grace period
4;; "force OB" hack method for CS 350
Modes 0 and 1 will power up the load when power returns. Modes 2 and 3
will keep the load turned off when the power returns.
Mode 4 exploits an oddity in the CS 350 models since they only seem to
support the S command, but then only when running on battery. As a
result, the driver will force the UPS to go on battery if necessary
before sending the shutdown command. This ensures that the load gets
reset.
BUGS
----
Some older APC UPS models return bogus data in the status register during
a front panel test. This is usually detected and discarded, but some
other unexpected values have occasionally slipped through.
APC UPS models with both USB and serial ports require a power cycle when
switching from USB communication to serial, and perhaps vice versa.
AUTHOR
------
Nigel Metheringham <Nigel.Metheringham@Intechnology.co.uk> (drawing
heavily on the original apcsmart driver by Russell Kroll). This driver
was called newapc for a time and was renamed in the 1.5 series.
SEE ALSO
--------
The core driver:
~~~~~~~~~~~~~~~~
linkman:nutupsdrv[8]
Internet resources:
~~~~~~~~~~~~~~~~~~~
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/

46
docs/man/asciidoc.conf Normal file
View file

@ -0,0 +1,46 @@
## Borrowed from 'linkgit' in the Git distribution.
## linkman: macro
#
# Usage: linkman:command[manpage-section]
#
# Note, {0} is the manpage section, while {target} is the command.
#
# Show NUT link as: <command>(<section>); if section is defined, else just show
# the command.
[macros]
(?su)[\\]?(?P<name>linkman):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
ifdef::backend-docbook[]
[linkman-inlinemacro]
{0%{target}}
{0#<citerefentry>}
{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
{0#</citerefentry>}
endif::backend-docbook[]
ifdef::backend-xhtml11[]
[linkman-inlinemacro]
<a href="{target}.html">{target}{0?({0})}</a>
endif::backend-xhtml11[]
# Meta info for a2x manpage conversion:
ifdef::doctype-manpage[]
ifdef::backend-docbook[]
[header]
template::[header-declarations]
<refentry>
<refmeta>
<refentrytitle>{mantitle}</refentrytitle>
<manvolnum>{manvolnum}</manvolnum>
<refmiscinfo class="source">Network UPS Tools</refmiscinfo>
<refmiscinfo class="version">{nut_version}</refmiscinfo>
<refmiscinfo class="manual">NUT Manual</refmiscinfo>
</refmeta>
<refnamediv>
<refname>{manname}</refname>
<refpurpose>{manpurpose}</refpurpose>
</refnamediv>
endif::backend-docbook[]
endif::doctype-manpage[]

130
docs/man/bcmxcp.8 Normal file
View file

@ -0,0 +1,130 @@
'\" t
.\" Title: bcmxcp
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 12/24/2010
.\" Manual: NUT Manual
.\" Source: Network UPS Tools
.\" Language: English
.\"
.TH "BCMXCP" "8" "12/24/2010" "Network UPS Tools" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
bcmxcp \- Driver for UPSes supporting the serial BCM/XCP protocol
.SH "NOTE"
.sp
This man page only documents the hardware\-specific features of the bcmxcp driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
.SH "SUPPORTED HARDWARE"
.sp
This driver should recognize all serial BCM/XCP\-compatible UPSes\&. It has been developed and tested on Powerware PW5115 and PW9120 hardware\&. If your UPS has a USB connection, you may also consult the \fBbcmxcp_usb\fR(8) driver documentation\&.
.SH "EXTRA ARGUMENTS"
.sp
This driver supports the following optional settings in the \fBups.conf\fR(5)\&.
.PP
\fBshutdown_delay=\fR\fIdelay\fR
.RS 4
The number of seconds that the UPS should wait between receiving the shutdown command (upsdrvctl shutdown) and actually shutting off\&.
.RE
.PP
\fBbaud_rate=\fR\fIrate\fR
.RS 4
Communication speed for the UPS\&. If this is set to 9600, it tries to connect to the UPS at 9600bps\&. If it fails to communicate, it will go into baud\-hunting\&. It starts at 1200 and goes up to 19200\&. If it succeeds, it tell you the speed it connected with\&. If not included in the config, it defaults to baud\-hunting\&.
.RE
.SH "DEFAULT VALUES FOR THE EXTRA ARGUMENTS"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBshutdown_delay =\fR
\fI120\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBbaud_rate =\fR
\fInone\fR
.RE
.SH "INSTANT COMMANDS"
.sp
This driver supports the following Instant Commands:
.PP
\fBshutdown\&.return\fR
.RS 4
Turn off the load and return when power is back\&.
.RE
.PP
\fBshutdown\&.stayoff\fR
.RS 4
Turn off the load and remain off\&.
.RE
.PP
\fBtest\&.battery\&.start\fR
.RS 4
Start a battery test\&.
.RE
.PP
\fBoutlet\&.n\&.shutdown\&.return\fR
.RS 4
Turn off the load on outlet
\fIn\fR
and return when power is back\&. (\fIn\fR
is the outlet number reported by the upsc command)
.RE
.SH "TODO LIST"
.PP
Report UPS statistics informations
.RS 4
BCM/XCP supports reporting of UPS statistics data\&.
.RE
.PP
Change settings
.RS 4
Access the config register to change settings\&.
.RE
.SH "BUGS"
.sp
None known\&.
.SH "AUTHOR"
.sp
Tore Ørpetveit <tore@orpetveit\&.net>
.SH "SEE ALSO"
.SS "The core driver:"
.sp
\fBnutupsdrv\fR(8)
.SS "The USB BCM/XCP driver:"
.sp
\fBbcmxcp_usb\fR(8)
.SS "Internet resources:"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/

88
docs/man/bcmxcp.txt Normal file
View file

@ -0,0 +1,88 @@
BCMXCP(8)
=========
NAME
----
bcmxcp - Driver for UPSes supporting the serial BCM/XCP protocol
NOTE
----
This man page only documents the hardware-specific features of the
bcmxcp driver. For information about the core driver, see
linkman:nutupsdrv[8].
SUPPORTED HARDWARE
------------------
This driver should recognize all serial BCM/XCP-compatible UPSes. It has
been developed and tested on Powerware PW5115 and PW9120 hardware. If your UPS
has a USB connection, you may also consult the linkman:bcmxcp_usb[8] driver
documentation.
EXTRA ARGUMENTS
---------------
This driver supports the following optional settings in the
linkman:ups.conf[5].
*shutdown_delay=*'delay'::
The number of seconds that the UPS should wait between receiving the
shutdown command (`upsdrvctl shutdown`) and actually shutting off.
*baud_rate=*'rate'::
Communication speed for the UPS. If this is set to 9600, it tries to connect
to the UPS at 9600bps. If it fails to communicate, it will go into baud-hunting.
It starts at 1200 and goes up to 19200. If it succeeds, it tell you the speed it
connected with. If not included in the config, it defaults to baud-hunting.
DEFAULT VALUES FOR THE EXTRA ARGUMENTS
--------------------------------------
- *shutdown_delay =* '120'
- *baud_rate =* 'none'
INSTANT COMMANDS
----------------
This driver supports the following Instant Commands:
*shutdown.return*::
Turn off the load and return when power is back.
*shutdown.stayoff*::
Turn off the load and remain off.
*test.battery.start*::
Start a battery test.
*outlet.n.shutdown.return*::
Turn off the load on outlet 'n' and return when power is back.
('n' is the outlet number reported by the upsc command)
TODO LIST
---------
Report UPS statistics informations::
BCM/XCP supports reporting of UPS statistics data.
Change settings::
Access the config register to change settings.
BUGS
----
None known.
AUTHOR
------
Tore Ørpetveit <tore@orpetveit.net>
SEE ALSO
--------
The core driver:
~~~~~~~~~~~~~~~~
linkman:nutupsdrv[8]
The USB BCM/XCP driver:
~~~~~~~~~~~~~~~~~~~~~~~
linkman:bcmxcp_usb[8]
Internet resources:
~~~~~~~~~~~~~~~~~~~
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/

114
docs/man/bcmxcp_usb.8 Normal file
View file

@ -0,0 +1,114 @@
'\" t
.\" Title: bcmxcp_usb
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 12/24/2010
.\" Manual: NUT Manual
.\" Source: Network UPS Tools
.\" Language: English
.\"
.TH "BCMXCP_USB" "8" "12/24/2010" "Network UPS Tools" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
bcmxcp_usb \- Experimental driver for UPSes supporting the BCM/XCP protocol over USB
.SH "NOTE"
.sp
This man page only documents the hardware\-specific features of the bcmxcp_usb driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&. This driver is a variant of the serial driver bcmxcp and uses the same core code\&.
.SH "SUPPORTED HARDWARE"
.sp
This driver should recognize all BCM/XCP\-compatible UPSes that are connected via USB\&. It has been developed and tested on Powerware PW3501 hardware\&. It also has been tested on PW5110 hardware\&.
.SH "EXTRA ARGUMENTS"
.sp
This driver supports the following optional settings in the \fBups.conf\fR(5)\&.
.PP
\fBshutdown_delay=\fR\fIdelay\fR
.RS 4
The number of seconds that the UPS should wait between receiving the shutdown command and actually shutting off\&.
.RE
.SH "DEFAULT VALUES FOR THE EXTRA ARGUMENTS"
.sp
\fBshutdown_delay =\fR\fI120\fR
.SH "INSTANT COMMANDS"
.sp
This driver supports the following Instant Commands:
.PP
\fBshutdown\&.return\fR
.RS 4
Turn off the load and return when power is back\&.
.RE
.PP
\fBshutdown\&.stayoff\fR
.RS 4
Turn off the load and remain off\&.
.RE
.PP
\fBtest\&.battery\&.start\fR
.RS 4
Start a battery test\&.
.RE
.SH "TODO LIST"
.PP
\fBReport UPS alarm status\fR
.RS 4
BCM/XCP supports reporting a wide range of UPS alarm conditions\&.
.RE
.PP
\fBReport UPS statistics informations\fR
.RS 4
BCM/XCP supports reporting of UPS statistics data\&.
.RE
.SH "EXPERIMENTAL DRIVER"
.sp
This driver has been tagged experimental, even if it has been reported to be stable\&. Thus it is not suitable for production systems and it is not built by default\&. This is mainly due to the fact that it is a new driver\&.
.SH "INSTALLATION"
.sp
This driver is not built by default\&. You can build it by using "configure \-\-with\-usb=yes"\&. Note that it will also install other USB drivers\&.
.sp
You also need to install manually the hotplug files (libhidups and libhid\&.usermap), generally in etc/hotplug/usb/, to address the permission settings problem\&. Lastly note that the libhidups file must have execution flag set (ie using chmod +x \&...)\&.
.SH "IMPLEMENTATION"
.sp
bcmxcp_usb only supports 1 UPS at this time\&. You can put the "auto" value for port in ups\&.conf, i\&.e\&.:
.sp
.if n \{\
.RS 4
.\}
.nf
[pw3105]
driver = bcmxcp_usb
port = auto
.fi
.if n \{\
.RE
.\}
.SH "KNOWN ISSUES AND BUGS"
.SS ""Got EPERM: Operation not permitted upon driver startup""
.sp
You have forgotten to install the hotplug files, as explained in the INSTALLATION section above\&. Don\(cqt forget to restart hotplug so that it applies these changes\&.
.SH "AUTHOR"
.sp
Tore Ørpetveit <tore@orpetveit\&.net>, Wolfgang Ocker <weo@weo1\&.de>
.SH "SEE ALSO"
.SS "The core driver:"
.sp
\fBnutupsdrv\fR(8)
.SS "Internet resources:"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/

107
docs/man/bcmxcp_usb.txt Normal file
View file

@ -0,0 +1,107 @@
BCMXCP_USB(8)
=============
NAME
----
bcmxcp_usb - Experimental driver for UPSes supporting the BCM/XCP protocol over USB
NOTE
----
This man page only documents the hardware-specific features of the
bcmxcp_usb driver. For information about the core driver, see
linkman:nutupsdrv[8].
This driver is a variant of the serial driver bcmxcp and uses the same core code.
SUPPORTED HARDWARE
------------------
This driver should recognize all BCM/XCP-compatible UPSes that are connected
via USB. It has been developed and tested on Powerware PW3501 hardware. It also has
been tested on PW5110 hardware.
EXTRA ARGUMENTS
---------------
This driver supports the following optional settings in the
linkman:ups.conf[5].
*shutdown_delay=*'delay'::
The number of seconds that the UPS should wait between receiving the
shutdown command and actually shutting off.
DEFAULT VALUES FOR THE EXTRA ARGUMENTS
--------------------------------------
*shutdown_delay =*'120'
INSTANT COMMANDS
----------------
This driver supports the following Instant Commands:
*shutdown.return*::
Turn off the load and return when power is back.
*shutdown.stayoff*::
Turn off the load and remain off.
*test.battery.start*::
Start a battery test.
TODO LIST
---------
*Report UPS alarm status*::
BCM/XCP supports reporting a wide range of UPS alarm conditions.
*Report UPS statistics informations*::
BCM/XCP supports reporting of UPS statistics data.
EXPERIMENTAL DRIVER
-------------------
This driver has been tagged experimental, even if it has been reported
to be stable. Thus it is not suitable for production systems and it is
not built by default. This is mainly due to the fact that it is a
new driver.
INSTALLATION
------------
This driver is not built by default. You can build it by using
"configure --with-usb=yes". Note that it will also install other USB
drivers.
You also need to install manually the hotplug files (libhidups and
libhid.usermap), generally in etc/hotplug/usb/, to address the
permission settings problem. Lastly note that the libhidups file
must have execution flag set (ie using chmod +x ...).
IMPLEMENTATION
--------------
bcmxcp_usb only supports 1 UPS at this time. You can put the
"auto" value for port in `ups.conf`, i.e.:
[pw3105]
driver = bcmxcp_usb
port = auto
KNOWN ISSUES AND BUGS
---------------------
"Got EPERM: Operation not permitted upon driver startup"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You have forgotten to install the hotplug files, as explained
in the INSTALLATION section above. Don't forget to restart
hotplug so that it applies these changes.
AUTHOR
------
Tore Ørpetveit <tore@orpetveit.net>,
Wolfgang Ocker <weo@weo1.de>
SEE ALSO
--------
The core driver:
~~~~~~~~~~~~~~~~
linkman:nutupsdrv[8]
Internet resources:
~~~~~~~~~~~~~~~~~~~
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/

68
docs/man/belkin.8 Normal file
View file

@ -0,0 +1,68 @@
'\" t
.\" Title: belkin
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 12/24/2010
.\" Manual: NUT Manual
.\" Source: Network UPS Tools
.\" Language: English
.\"
.TH "BELKIN" "8" "12/24/2010" "Network UPS Tools" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
belkin \- Driver for Belkin serial UPS equipment
.SH "NOTE"
.sp
This man page only documents the hardware\-specific features of the belkin driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
.SH "SUPPORTED HARDWARE"
.sp
The \fBbelkin\fR driver is known to support the Regulator Pro 525 (F6C525\-SER)\&. Other similar models such as the 425 and 625 should also work\&.
.sp
The Trust UPS and older Belkin units are not supported\&.
.SH "EXTRA ARGUMENTS"
.sp
This driver does not support any extra settings in the \fBups.conf\fR(5)\&.
.SH "BUGS"
.sp
There are dragons lurking within the protocol to this UPS\&. I have one that essentially behaves like a glorified power strip due to some invasive probing on my part\&. Don\(cqt mess with it directly\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
the driver doesn\(cqt go anywhere near these character sequences, so it won\(cqt zap your UPS\&. I only mention this here as yet another reminder of the perils of closed hardware\&.
.sp .5v
.RE
.SH "SEE ALSO"
.SS "The core driver:"
.sp
\fBnutupsdrv\fR(8)
.SS "Internet resources:"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/

49
docs/man/belkin.txt Normal file
View file

@ -0,0 +1,49 @@
BELKIN(8)
=========
NAME
----
belkin - Driver for Belkin serial UPS equipment
NOTE
----
This man page only documents the hardware-specific features of the
belkin driver. For information about the core driver, see
linkman:nutupsdrv[8].
SUPPORTED HARDWARE
------------------
The *belkin* driver is known to support the Regulator Pro 525 (F6C525-SER).
Other similar models such as the 425 and 625 should also work.
The Trust UPS and older Belkin units are not supported.
EXTRA ARGUMENTS
---------------
This driver does not support any extra settings in the
linkman:ups.conf[5].
BUGS
----
There are dragons lurking within the protocol to this UPS. I have one
that essentially behaves like a glorified power strip due to some
invasive probing on my part. Don't mess with it directly.
NOTE: the driver doesn't go anywhere near these character sequences,
so it won't zap your UPS. I only mention this here as yet another
reminder of the perils of closed hardware.
SEE ALSO
--------
The core driver:
~~~~~~~~~~~~~~~~
linkman:nutupsdrv[8]
Internet resources:
~~~~~~~~~~~~~~~~~~~
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/

352
docs/man/belkinunv.8 Normal file
View file

@ -0,0 +1,352 @@
'\" t
.\" Title: belkinunv
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 12/24/2010
.\" Manual: NUT Manual
.\" Source: Network UPS Tools
.\" Language: English
.\"
.TH "BELKINUNV" "8" "12/24/2010" "Network UPS Tools" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
belkinunv \- Driver for Belkin "Universal UPS" and compatible
.SH "NOTE"
.sp
This man page only documents the hardware\-specific features of the belkin driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
.SH "SUPPORTED HARDWARE"
.sp
The belkinunv driver is known to work with the Belkin Universal UPS models F6C800\-UNV and F6C120\-UNV, and is expected to work with other Belkin Universal UPS models\&. The driver only supports serial communication, not USB\&.
.sp
The Trust UPS and older Belkin units are not supported by this driver, and neither are the Belkin Home Office models (F6H500\-SER and so forth)\&. However, some Belkin models, such as the Regulator Pro, are supported by the \fBbelkin\fR(8) driver, and the Home Office models are supported using the \fBgenericups\fR(8) driver with upstype=7\&.
.SH "SOFT SHUTDOWN WORKAROUND"
.sp
One problem with the Belkin Universal UPS is that it cannot enter a soft shutdown (shut down the load until AC power returns) unless the batteries are completely depleted\&. Thus, one cannot just shut off the UPS after operating system shutdown; it will not come back on when the power comes back on\&. Therefore, the belkinunv driver should never be used with the \fB\-k\fR option\&. Instead, the \fB\-x wait\fR option is provided as a workaround\&.
.sp
When called with the \fB\-x wait\fR option, \fBbelkinunv\fR behaves as a standalone program (i\&.e\&., it does not fork into the background)\&. It performs one simple task: it connects to the UPS, waits for AC power to return, and then exits with status 0\&.
.sp
This is meant to be used in a shutdown script as follows: during a shutdown, after all filesystems have been remounted read\-only, and just before the system would normally be halted: check /etc/killpower (or similar) to see if this shutdown was caused by \fBupsmon\fR(8), and if yes, call \fBbelkinunv \-x wait\fR\&. If AC power comes back on, \fBbelkinunv\fR exits, and things should be arranged so that the system reboots in this case\&. If AC power does not come back on, the UPS will eventually run out of batteries, kill the computer\(cqs power supply, and go into soft shutdown mode, which means everything will reboot properly when the power returns\&. In either case, a deadlock is avoided\&.
.sp
In addition, if an optional integer argument is given to the \fB\-x wait\fR option, this causes \fBbelkinunv\fR to wait not only for AC power to be present, but also for the battery charge to reach the given level\&. I use this as part of my startup scripts, to ensure that the batteries are sufficiently charged before the computer continues booting\&. This should be put very early in the startup script, before any filesystems are mounted read/write, and before any filesystem checks are performed\&.
.sp
Several other \fB\-x\fR options are provided to fine\-tune this behavior\&. See the options below for detailed descriptions\&. See the examples below for examples of how to use \fBbelkinunv\fR in shutdown and startup scripts\&.
.SH "OPTIONS"
.sp
See also \fBnutupsdrv\fR(8) for generic options\&. Never use the \fB\-k\fR option with this driver; it does not work properly\&.
.PP
\fB\-x wait\fR[=\fIlevel\fR]
.RS 4
When this option is used,
\fBbelkinunv\fR
does not fork into the background, but behaves as a standalone program\&. It connects to the UPS and waits until AC power is present\&. If
\fIlevel\fR
is specified, it also waits until the battery charge reaches at least the given level in percent\&. Then, and only then,
\fBbelkinunv\fR
exits\&. In addition, while
\fBbelkinunv\fR
runs in this mode, it displays a status line with information on the UPS status and battery level\&. This is intended for use in the computer\(cqs shutdown and startup scripts, as described under
Soft Shutdown Workaround
above\&.
.RE
.PP
\fB\-x nohang\fR
.RS 4
This option only has an effect when used in conjunction with the
\fB\-x wait\fR
option\&. It causes
\fBbelkinunv\fR
to exit if a connection with the UPS cannot be established or is lost, instead of retrying forever, which is the default behavior\&. The
\fB\-x nohang\fR
option should be used in a startup script, to ensure the computer remains bootable even if the UPS has been disconnected during the power failure (for instance, you attached your computer to a generator, carried it to a neighbor\(cqs house, or whatever)\&.
.RE
.PP
\fB\-x flash\fR
.RS 4
This option only has an effect when used in conjunction with the
\fB\-x wait\fR
option\&. It causes the UPS load to be shut off for a short time ("flashed") just after the AC power has returned and the requested battery level (if any) has been attained\&. This is useful if slaves are attached to this UPS; the flash will cause all of them to reboot\&. Note that, due to the design of the Belkin UPS hardware, the load shutdown lasts ca\&. 1\(em2 minutes; a shorter flash cannot be performed reliably\&. Also, the computers will reboot at the scheduled time, on battery power if necessary, even if AC power fails again in the meantime\&. This should not be a problem, as your startup scripts can catch this situation\&.
.RE
.PP
\fB\-x silent\fR
.RS 4
This option only has an effect when used in conjunction with the
\fB\-x wait\fR
option\&. It suppresses the status line which
\fBbelkinunv\fR
would normally print\&.
.RE
.PP
\fB\-x dumbterm\fR
.RS 4
This option only has an effect when used in conjunction with the
\fB\-x wait\fR
option\&. It changes the way in which
\fBbelkinunv\fR
prints its status line\&. Normally, terminal control sequences are used to overwrite the same line with new status information, each time the status is updated\&. This may not work on all terminals\&. If the
\fB\-x dumbterm\fR
option is given, each status update is written on a new line\&.
.RE
.SH "VARIABLES"
.PP
\fBbattery\&.charge\fR, \fBbattery\&.runtime\fR
.RS 4
not supported by all hardware\&.
.RE
.PP
\fBbattery\&.voltage\fR, \fBbattery\&.voltage\&.nominal\fR, \fBdriver\&.version\&.internal\fR, \fBinput\&.frequency\fR, \fBinput\&.frequency\&.nominal\fR
.RS 4
e\&.g\&. 60 for 60Hz
.RE
.PP
\fBinput\&.sensitivity\fR
.RS 4
writable: normal/medium/low
.RE
.PP
\fBinput\&.transfer\&.high\fR
.RS 4
writable: high transfer voltage point in V
.RE
.PP
\fBinput\&.transfer\&.low\fR
.RS 4
writable: low transfer voltage point in V
.RE
.PP
\fBinput\&.voltage\fR, \fBinput\&.voltage\&.maximum\fR, \fBinput\&.voltage\&.minimum\fR, \fBinput\&.voltage\&.nominal\fR, \fBoutput\&.frequency\fR, \fBoutput\&.voltage\fR, \fBups\&.beeper\&.status\fR
.RS 4
writable\&. Values: enabled/disabled/muted\&. This variable controls the state of the panel beeper\&. Enabled means sound when the alarm is present, disabled means never sound, and muted means the sound is temporarily disabled until the alarm would normally stop sounding\&. In the muted state, the beeper is automatically turned back on at the next event (AC failure, battery test, etc)\&. Also, the beeper can\(cqt be turned off during a critical event (low battery)\&. Note that not all UPS models support the "disabled" state\&.
.RE
.PP
\fBups\&.firmware\fR, \fBups\&.load\fR, \fBups\&.model\fR, \fBups\&.power\&.nominal\fR
.RS 4
e\&.g\&. 800 for an 800VA system
.RE
.PP
\fBups\&.status\fR
.RS 4
a list of flags; see the
status flags
below\&.
.RE
.PP
\fBups\&.temperature\fR
.RS 4
not supported by all hardware\&.
.RE
.PP
\fBups\&.test\&.result\fR, \fBups\&.delay\&.restart\fR
.RS 4
time to restart (read only)
.RE
.PP
\fBups\&.delay\&.shutdown\fR
.RS 4
time to shutdown (read only)\&. This is always a multiple of 60 seconds\&.
.RE
.PP
\fBups\&.type\fR
.RS 4
ONLINE/OFFLINE/LINEINT\&. This describes the basic layout of this UPS (for GUI clients which want to draw an animated picture of power flow)\&. An offline UPS has a direct connection from AC input to AC output, and also a connection from AC input to the battery, and from the battery to AC output\&. An online UPS lacks the direct connection from AC input to AC output, whereas a line interactive UPS lacks the connection from AC input to the battery\&.
.RE
.SH "COMMANDS"
.PP
\fBbeeper\&.enable, beeper\&.disable, beeper\&.mute\fR
.RS 4
Enable, disable or mute the panel beeper\&. Note that if the beeper is muted, it is automatically turned back on at the next event (AC failure, battery test, etc)\&. Also, the beeper can\(cqt be turned muted during a critical event (low battery)\&.
.RE
.PP
\fBreset\&.input\&.minmax\fR
.RS 4
Reset the variables
\fBinput\&.voltage\&.minimum\fR
and
\fBinput\&.voltage\&.maximum\fR\&.
.RE
.PP
\fBshutdown\&.reboot\fR
.RS 4
Shut down load immediately for about 1\(em2 minutes\&.
.RE
.PP
\fBshutdown\&.reboot\&.graceful\fR
.RS 4
After 40 second delay, shut down load for about 1\(em2 minutes\&.
.RE
.PP
\fBshutdown\&.stayoff\fR
.RS 4
Shut down load immediately and stay off\&. The only way it can be turned back on is by manually pressing the front panel button\&.
.RE
.PP
\fBtest\&.battery\&.start, test\&.battery\&.stop\fR
.RS 4
Start/stop 10 second battery test\&.
.RE
.PP
\fBtest\&.failure\&.start, test\&.failure\&.stop\fR
.RS 4
Start/stop "deep" battery test\&.
.RE
.SH "STATUS FLAGS"
.PP
\fBOB\fR
.RS 4
load is on battery, including during tests
.RE
.PP
\fBOFF\fR
.RS 4
load is off
.RE
.PP
\fBOL\fR
.RS 4
load is online
.RE
.PP
\fBACFAIL\fR
.RS 4
AC failure\&. Note that this refers to the AC input, and thus it is not the same as "OB"\&. An AC failure can occur at any time, for instance, during a battery test, or when the UPS load is off\&.
.RE
.PP
\fBOVER\fR
.RS 4
overload
.RE
.PP
\fBOVERHEAT\fR
.RS 4
overheat
.RE
.PP
\fBCOMMFAULT\fR
.RS 4
UPS fault
.RE
.PP
\fBLB\fR
.RS 4
low battery
.RE
.PP
\fBCHRG\fR
.RS 4
charging
.RE
.PP
\fBDEPLETED\fR
.RS 4
the battery is depleted\&. When the UPS raises this flag, it simultaneously switches off the load\&.
.RE
.PP
\fBRB\fR
.RS 4
replace battery
.RE
.SH "EXAMPLES"
.sp
Here is an example for how \fBbelkinunv\fR should be used in a computer\(cqs shutdown script\&. These commands should go in the very last part of the shutdown script, after all file systems have been mounted read\-only, and just before the computer halts\&. Note that \fBbelkinunv\fR must be installed in a directory which is still readable at that point\&.
.sp
.if n \{\
.RS 4
.\}
.nf
# NEAR END OF SHUTDOWN SCRIPT:
# if shutdown was caused by UPS, perform Belkin UPS workaround\&.
if [ \-f /etc/killpower ] ; then
echo "Waiting for AC power, or for UPS batteries to run out\&.\&.\&."
/usr/bin/belkinunv \-x wait /dev/ttyS1
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
# we get here if the power came back on\&. Reboot\&.
echo "Power is back\&. Rebooting\&.\&.\&."
reboot
fi
.fi
.if n \{\
.RE
.\}
.sp
And here is an example of how to use \fBbelkinunv\fR in the startup script\&. These commands should go near the beginning of the startup script, before any file systems are mounted read/write, and before any file system integrity checks are done\&.
.sp
.if n \{\
.RS 4
.\}
.nf
# NEAR BEGINNING OF STARTUP SCRIPT:
# if we are recovering from a power failure, wait for the UPS to
# charge to a comfortable level before writing anything to disk
if [ \-f /etc/killpower ] ; then
echo "Waiting for UPS battery charge to reach 60%\&.\&.\&."
/usr/bin/belkinunv \-x wait=60 \-x nohang /dev/ttyS1
fi
.fi
.if n \{\
.RE
.\}
.SH "EXIT STATUS"
.sp
When used normally, \fBbelkinunv\fR forks into the background and its diagnostics are the same as for all NUT drivers, see \fBnutupsdrv\fR(8)\&.
.sp
When used with the \fB\-x wait\fR option, the exit status is normally \fB0\fR\&. If the \fB\-x nohang\fR option has also been specified, an exit status of \fB1\fR indicates that communication with the UPS was lost\&. If the \fB\-x flash\fR option has been specified, an exit status of \fB2\fR indicates that the timed shutdown has failed\&.
.SH "EXTRA ARGUMENTS"
.sp
This driver does not support any extra settings in \fBups.conf\fR(5)\&.
.SH "SEE ALSO"
.SS "The core driver:"
.sp
\fBnutupsdrv\fR(8)
.SS "Internet resources:"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The NUT (Network UPS Tools) home page:
http://www\&.networkupstools\&.org/
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The documentation for the protocol used by this UPS:
belkin\-universal\-ups\&.html
.RE
.SH "AUTHOR"
.sp
Peter Selinger <selinger@users\&.sourceforge\&.net>

344
docs/man/belkinunv.txt Normal file
View file

@ -0,0 +1,344 @@
BELKINUNV(8)
============
NAME
----
belkinunv - Driver for Belkin "Universal UPS" and compatible
NOTE
----
This man page only documents the hardware-specific features of the
belkin driver. For information about the core driver, see
linkman:nutupsdrv[8].
SUPPORTED HARDWARE
------------------
The belkinunv driver is known to work with the Belkin Universal UPS
models F6C800-UNV and F6C120-UNV, and is expected to work with other
Belkin Universal UPS models. The driver only supports serial
communication, not USB.
The Trust UPS and older Belkin units are not supported by this driver,
and neither are the Belkin Home Office models (F6H500-SER and so
forth). However, some Belkin models, such as the Regulator Pro, are
supported by the linkman:belkin[8] driver, and the Home Office models
are supported using the linkman:genericups[8] driver with
`upstype=7`.
SOFT SHUTDOWN WORKAROUND
------------------------
One problem with the Belkin Universal UPS is that it cannot enter a
soft shutdown (shut down the load until AC power returns) unless the
batteries are completely depleted. Thus, one cannot just shut off the
UPS after operating system shutdown; it will not come back on when the
power comes back on. Therefore, the belkinunv driver should never be
used with the *-k* option. Instead, the *-x wait* option is
provided as a workaround.
When called with the *-x wait* option, *belkinunv* behaves as
a standalone program (i.e., it does not fork into the background). It
performs one simple task: it connects to the UPS, waits for AC power
to return, and then exits with status 0.
This is meant to be used in a shutdown script as follows: during a
shutdown, after all filesystems have been remounted read-only, and
just before the system would normally be halted: check /etc/killpower
(or similar) to see if this shutdown was caused by linkman:upsmon[8],
and if yes, call *belkinunv -x wait*. If AC power comes back on,
*belkinunv* exits, and things should be arranged so that the
system reboots in this case. If AC power does not come back on, the
UPS will eventually run out of batteries, kill the computer's power
supply, and go into soft shutdown mode, which means everything will
reboot properly when the power returns. In either case, a deadlock is
avoided.
In addition, if an optional integer argument is given to the *-x wait*
option, this causes *belkinunv* to wait not only for AC power to be present,
but also for the battery charge to reach the given level. I use this as part of
my startup scripts, to ensure that the batteries are sufficiently charged
before the computer continues booting. This should be put very early in the
startup script, before any filesystems are mounted read/write, and before any
filesystem checks are performed.
Several other *-x* options are provided to fine-tune this
behavior. See the <<_options,options>> below for detailed descriptions. See the
<<_examples,examples>>
below for examples of how to use *belkinunv* in shutdown and
startup scripts.
OPTIONS
-------
See also linkman:nutupsdrv[8] for generic options. Never use the
*-k* option with this driver; it does not work properly.
*-x wait*[='level']::
When this option is used, *belkinunv* does not fork into the
background, but behaves as a standalone program. It connects to the UPS and
waits until AC power is present. If 'level' is specified, it also
waits until the battery charge reaches at least the given level in
percent. Then, and only then, *belkinunv* exits. In addition,
while *belkinunv* runs in this mode, it displays a status line
with information on the UPS status and battery level. This is intended
for use in the computer's shutdown and startup scripts, as described
under <<_soft_shutdown_workaround,Soft Shutdown Workaround>> above.
*-x nohang*::
This option only has an effect when used in conjunction with the *-x wait*
option. It causes *belkinunv* to exit if a connection with
the UPS cannot be established or is lost, instead of retrying forever,
which is the default behavior. The *-x nohang* option should be
used in a startup
script, to ensure the computer remains bootable even if the UPS has
been disconnected during the power failure (for instance, you attached
your computer to a generator, carried it to a neighbor's house, or
whatever).
*-x flash*::
This option only has an effect when used in conjunction with the *-x wait*
option. It causes the UPS load to be shut off for a short time
("flashed") just after the AC power has returned and the requested
battery level (if any) has been attained. This is useful if slaves are
attached to this UPS; the flash will cause all of them to reboot. Note
that, due to the design of the Belkin UPS hardware, the load shutdown lasts
ca. 1--2 minutes; a shorter flash cannot be performed reliably. Also,
the computers will reboot at the scheduled time, on battery power if
necessary, even if AC power fails again in the meantime. This should
not be a problem, as your startup scripts can catch this situation.
*-x silent*::
This option only has an effect when used in conjunction with the *-x wait*
option. It suppresses the status line which *belkinunv*
would normally print.
*-x dumbterm*::
This option only has an effect when used in conjunction with the *-x wait*
option. It changes the way in which *belkinunv* prints its
status line. Normally, terminal control sequences are used to
overwrite the same line with new status information, each time the
status is updated. This may not work on all terminals. If the *-x dumbterm*
option is given, each status update is written on a new
line.
VARIABLES
---------
*battery.charge*::
*battery.runtime*::
not supported by all hardware.
*battery.voltage*::
*battery.voltage.nominal*::
*driver.version.internal*::
*input.frequency*::
*input.frequency.nominal*::
e.g. 60 for 60Hz
*input.sensitivity*::
writable: normal/medium/low
*input.transfer.high*::
writable: high transfer voltage point in V
*input.transfer.low*::
writable: low transfer voltage point in V
*input.voltage*::
*input.voltage.maximum*::
*input.voltage.minimum*::
*input.voltage.nominal*::
*output.frequency*::
*output.voltage*::
*ups.beeper.status*::
writable. Values: enabled/disabled/muted. This variable controls the
state of the panel beeper. Enabled means sound when the alarm is
present, disabled means never sound, and muted means the sound is
temporarily disabled until the alarm would normally stop sounding. In
the muted state, the beeper is automatically turned back on at the
next event (AC failure, battery test, etc). Also, the beeper can't be
turned off during a critical event (low battery). Note that not all
UPS models support the "disabled" state.
*ups.firmware*::
*ups.load*::
*ups.model*::
*ups.power.nominal*::
e.g. 800 for an 800VA system
*ups.status*::
a list of flags; see the <<_status_flags,status flags>> below.
*ups.temperature*::
not supported by all hardware.
*ups.test.result*::
*ups.delay.restart*::
time to restart (read only)
*ups.delay.shutdown*::
time to shutdown (read only). This is always a multiple of 60 seconds.
*ups.type*::
ONLINE/OFFLINE/LINEINT. This describes the basic layout of this UPS
(for GUI clients which want to draw an animated picture of power
flow). An offline UPS has a direct connection from AC input to AC
output, and also a connection from AC input to the battery, and from
the battery to AC output. An online UPS lacks the direct connection
from AC input to AC output, whereas a line interactive UPS lacks the
connection from AC input to the battery.
COMMANDS
--------
*beeper.enable, beeper.disable, beeper.mute*::
Enable, disable or mute the panel beeper. Note that if the beeper is
muted, it is automatically turned back on at the next event (AC failure,
battery test, etc). Also, the beeper can't be turned muted during a
critical event (low battery).
*reset.input.minmax*::
Reset the variables *input.voltage.minimum* and
*input.voltage.maximum*.
*shutdown.reboot*::
Shut down load immediately for about 1--2 minutes.
*shutdown.reboot.graceful*::
After 40 second delay, shut down load for about 1--2 minutes.
*shutdown.stayoff*::
Shut down load immediately and stay off. The only way it can be turned
back on is by manually pressing the front panel button.
*test.battery.start, test.battery.stop*::
Start/stop 10 second battery test.
*test.failure.start, test.failure.stop*::
Start/stop "deep" battery test.
STATUS FLAGS
------------
*OB*::
load is on battery, including during tests
*OFF*::
load is off
*OL*::
load is online
*ACFAIL*::
AC failure. Note that this refers to the AC input, and thus it is not
the same as "OB". An AC failure can occur at any time, for instance,
during a battery test, or when the UPS load is off.
*OVER*::
overload
*OVERHEAT*::
overheat
*COMMFAULT*::
UPS fault
*LB*::
low battery
*CHRG*::
charging
*DEPLETED*::
the battery is depleted. When the UPS raises this flag, it
simultaneously switches off the load.
*RB*::
replace battery
EXAMPLES
--------
Here is an example for how *belkinunv* should be used in a
computer's shutdown script. These commands should go in the very last
part of the shutdown script, after all file systems have been mounted
read-only, and just before the computer halts. Note that
*belkinunv* must be installed in a directory which is still
readable at that point.
# NEAR END OF SHUTDOWN SCRIPT:
# if shutdown was caused by UPS, perform Belkin UPS workaround.
if [ -f /etc/killpower ] ; then
echo "Waiting for AC power, or for UPS batteries to run out..."
/usr/bin/belkinunv -x wait /dev/ttyS1
# we get here if the power came back on. Reboot.
echo "Power is back. Rebooting..."
reboot
fi
And here is an example of how to use *belkinunv* in the startup
script. These commands should go near the beginning of the startup
script, before any file systems are mounted read/write, and before any
file system integrity checks are done.
# NEAR BEGINNING OF STARTUP SCRIPT:
# if we are recovering from a power failure, wait for the UPS to
# charge to a comfortable level before writing anything to disk
if [ -f /etc/killpower ] ; then
echo "Waiting for UPS battery charge to reach 60%..."
/usr/bin/belkinunv -x wait=60 -x nohang /dev/ttyS1
fi
EXIT STATUS
-----------
When used normally, *belkinunv* forks into the background and its
diagnostics are the same as for all NUT drivers, see
linkman:nutupsdrv[8].
When used with the *-x wait* option, the exit status is normally
*0*. If the *-x nohang* option has also been specified, an exit
status of *1* indicates that communication with the UPS was lost. If the
*-x flash* option has been specified, an exit status of *2*
indicates that the timed shutdown has failed.
EXTRA ARGUMENTS
---------------
This driver does not support any extra settings in linkman:ups.conf[5].
SEE ALSO
--------
The core driver:
~~~~~~~~~~~~~~~~
linkman:nutupsdrv[8]
Internet resources:
~~~~~~~~~~~~~~~~~~~
- The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
- The documentation for the protocol used by this UPS:
link:http://www.mscs.dal.ca/~selinger/ups/belkin-universal-ups.html[belkin-universal-ups.html]
AUTHOR
------
Peter Selinger <selinger@users.sourceforge.net>

56
docs/man/bestfcom.8 Normal file
View file

@ -0,0 +1,56 @@
'\" t
.\" Title: bestfcom
.\" Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 12/24/2010
.\" Manual: NUT Manual
.\" Source: Network UPS Tools
.\" Language: English
.\"
.TH "BESTFCOM" "8" "12/24/2010" "Network UPS Tools" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
bestfcom \- Driver for Best Power Fortress/Ferrups
.SH "NOTE"
.sp
This man page only documents the hardware\-specific features of the bestfcom driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
.SH "SUPPORTED HARDWARE"
.sp
Best Power Fortress/Ferrups implementing the Fortress UPS Protocol (f\-command set)\&.
.SH "EXTRA ARGUMENTS"
.sp
This driver does not support any extra settings in the \fBups.conf\fR(5)\&.
.SH "AUTHORS"
.sp
Kent Polk (bestfcom)
.sp
Andreas Wrede, John Stone (bestuferrups)
.sp
Grant Taylor (bestfort)
.sp
Russell Kroll (bestups)
.SH "SEE ALSO"
.SS "The core driver:"
.sp
\fBnutupsdrv\fR(8)
.SS "Internet resources:"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/

45
docs/man/bestfcom.txt Normal file
View file

@ -0,0 +1,45 @@
BESTFCOM(8)
===========
NAME
----
bestfcom - Driver for Best Power Fortress/Ferrups
NOTE
----
This man page only documents the hardware-specific features of the
bestfcom driver. For information about the core driver, see
linkman:nutupsdrv[8].
SUPPORTED HARDWARE
------------------
Best Power Fortress/Ferrups implementing the Fortress UPS Protocol
(f-command set).
EXTRA ARGUMENTS
---------------
This driver does not support any extra settings in the
linkman:ups.conf[5].
AUTHORS
-------
Kent Polk (bestfcom)
Andreas Wrede, John Stone (bestuferrups)
Grant Taylor (bestfort)
Russell Kroll (bestups)
SEE ALSO
--------
The core driver:
~~~~~~~~~~~~~~~~
linkman:nutupsdrv[8]
Internet resources:
~~~~~~~~~~~~~~~~~~~
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/

65
docs/man/bestfortress.8 Normal file
View file

@ -0,0 +1,65 @@
'\" t
.\" Title: bestfortress
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 12/24/2010
.\" Manual: NUT Manual
.\" Source: Network UPS Tools
.\" Language: English
.\"
.TH "BESTFORTRESS" "8" "12/24/2010" "Network UPS Tools" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
bestfortress \- Driver for old Best Fortress UPS equipment
.SH "NOTE"
.sp
This man page only documents the hardware\-specific features of the bestfortress driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
.SH "SUPPORTED HARDWARE"
.sp
This driver supports old Best Fortress UPS equipment using a serial connection\&.
.SH "EXTRA ARGUMENTS"
.sp
This driver supports the following optional settings in the \fBups.conf\fR(5):
.PP
\fBbaudrate\fR=\fInum\fR
.RS 4
Set the speed of the serial connection \- 1200, 2400, 4800 or 9600\&.
.RE
.PP
\fBmax_load\fR=\fIVA\fR
.RS 4
Set the full\-scale value of the
\fBups\&.load\fR
variable\&.
.RE
.SH "AUTHOR"
.sp
Holger Dietze <holger\&.dietze@advis\&.de>, Stuart D\&. Gathman <stuart@bmsi\&.com>
.SH "SEE ALSO"
.SS "The core driver:"
.sp
\fBnutupsdrv\fR(8)
.SS "The newer Best Power drivers:"
.sp
\fBbestups\fR(8), \fBbestuferrups\fR(8), \fBbestfcom\fR(8)
.SS "Internet resources:"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/

49
docs/man/bestfortress.txt Normal file
View file

@ -0,0 +1,49 @@
BESTFORTRESS(8)
===============
NAME
----
bestfortress - Driver for old Best Fortress UPS equipment
NOTE
----
This man page only documents the hardware-specific features of the
bestfortress driver. For information about the core driver, see
linkman:nutupsdrv[8].
SUPPORTED HARDWARE
------------------
This driver supports old Best Fortress UPS equipment using a serial connection.
EXTRA ARGUMENTS
---------------
This driver supports the following optional settings in the
linkman:ups.conf[5]:
*baudrate*='num'::
Set the speed of the serial connection - 1200, 2400, 4800 or 9600.
*max_load*='VA'::
Set the full-scale value of the *ups.load* variable.
AUTHOR
------
Holger Dietze <holger.dietze@advis.de>,
Stuart D. Gathman <stuart@bmsi.com>
SEE ALSO
--------
The core driver:
~~~~~~~~~~~~~~~~
linkman:nutupsdrv[8]
The newer Best Power drivers:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
linkman:bestups[8], linkman:bestuferrups[8], linkman:bestfcom[8]
Internet resources:
~~~~~~~~~~~~~~~~~~~
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/

54
docs/man/bestuferrups.8 Normal file
View file

@ -0,0 +1,54 @@
'\" t
.\" Title: bestuferrups
.\" Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 12/24/2010
.\" Manual: NUT Manual
.\" Source: Network UPS Tools
.\" Language: English
.\"
.TH "BESTUFERRUPS" "8" "12/24/2010" "Network UPS Tools" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
bestuferrups \- Driver for Best Power Micro\-Ferrups
.SH "NOTE"
.sp
This man page only documents the hardware\-specific features of the bestuferrups driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
.SH "SUPPORTED HARDWARE"
.sp
Best Power Micro\-Ferrups ME3100, probably other similar models too\&.
.SH "EXTRA ARGUMENTS"
.sp
This driver does not support any extra settings in the \fBups.conf\fR(5)\&.
.SH "AUTHORS"
.sp
Andreas Wrede, John Stone (bestuferrups)
.sp
Grant Taylor (bestfort)
.sp
Russell Kroll (bestups)
.SH "SEE ALSO"
.SS "The core driver:"
.sp
\fBnutupsdrv\fR(8)
.SS "Internet resources:"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/

42
docs/man/bestuferrups.txt Normal file
View file

@ -0,0 +1,42 @@
BESTUFERRUPS(8)
===============
NAME
----
bestuferrups - Driver for Best Power Micro-Ferrups
NOTE
----
This man page only documents the hardware-specific features of the
bestuferrups driver. For information about the core driver, see
linkman:nutupsdrv[8].
SUPPORTED HARDWARE
------------------
Best Power Micro-Ferrups ME3100, probably other similar models too.
EXTRA ARGUMENTS
---------------
This driver does not support any extra settings in the
linkman:ups.conf[5].
AUTHORS
-------
Andreas Wrede, John Stone (bestuferrups)
Grant Taylor (bestfort)
Russell Kroll (bestups)
SEE ALSO
--------
The core driver:
~~~~~~~~~~~~~~~~
linkman:nutupsdrv[8]
Internet resources:
~~~~~~~~~~~~~~~~~~~
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/

105
docs/man/bestups.8 Normal file
View file

@ -0,0 +1,105 @@
'\" t
.\" Title: bestups
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 12/24/2010
.\" Manual: NUT Manual
.\" Source: Network UPS Tools
.\" Language: English
.\"
.TH "BESTUPS" "8" "12/24/2010" "Network UPS Tools" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
bestups \- Driver for Best Power / SOLA (Phoenixtec protocol) UPS equipment
.SH "NOTE"
.sp
This man page only documents the hardware\-specific features of the bestups driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
.SH "SUPPORTED HARDWARE"
.sp
\fBbestups\fR was designed to monitor Best Power UPS hardware like the Fortress, Fortress Telecom, Axxium Rackmount and Patriot Pro\&. It also recognizes and supports SOLA units such as the 325, 520 and 620\&. In addition, the Best 610 is supported using the \(oqID\(cq option\&.
.sp
Other UPS hardware using the Phoenixtec protocol should also work, but they will generate a warning since their battery information is not known\&.
.sp
This driver does not support some older Best/SOLA units\&.
.SH "EXTRA ARGUMENTS"
.sp
This driver supports the following optional settings in the \fBups.conf\fR(5):
.PP
\fBnombattvolt=\fR\fInum\fR
.RS 4
Override the battery float voltage which is normally determined by asking the hardware\&. This is useful if your UPS constantly reports
battery\&.charge
values just below 100% even when it\(cqs completely charged\&.
.sp
If you have this problem, set this to whatever
battery\&.voltage
reports when the UPS is known to be completely charged with a good battery\&.
.sp
The author\(cqs Best Fortress 750 uses
nombattvolt=27\&.4\&.
.RE
.PP
\fBbattvoltmult=\fR\fInum\fR
.RS 4
Multiply the reported battery voltage by this number\&. Some devices report only a fraction of the total battery voltage\&.
.sp
For example, the SOLA 610 700VA UPS (with a 24V battery) reports the single cell voltage (about 2\&.27V when fully charged)\&. In this particular case you can set
battvoltmult = 12
in
\fBups.conf\fR(8)
to fix this\&.
.RE
.PP
\fBID=\fR\fIstring\fR
.RS 4
Set the Identification response string\&. This should only be used with hardware that supports the Phoenixtec protocol status inquiry commands, but not the "ID" command, such as the Best/SOLA 610\&. Format of the ID string is: AAA,BBBB,CCC,DDD,EE\&.E,FF\&.F
.sp
AAA is the three\-character identification for the UPS model\&.
.sp
BBBB is the output power in VA (volt amperes)\&. B is an integer number ranging from 0 to 9\&.
.sp
CCC is the Nominal Input Voltage\&. C is an integer number ranging from 0 to 9\&. The unit is Volts AC\&.
.sp
DDD is the Nominal Output Voltage\&. D is an integer number ranging from 0 to 9\&. The unit is Volts AC\&.
.sp
EE\&.E is the Battery Voltage that will cause the UPS to shut itself off\&. E is an integer number ranging from 0 to 9\&. Then unit is Volts DC and a decimal point is present\&.
.sp
FF\&.F or FFF\&.F is the Battery Voltage at full charge\&. F is an integer number ranging from 0 to 9\&. Then unit is Volts DC\&. Typically, for 700VA, 1KVA and 1\&.5KVA units, the format is FF\&.F\&. For 2KVA and 3KVA units, the format is FFF\&.F\&.
.sp
Example: a Best 610 1\&.5KVA unit would use the string "610,1500,120,120,10\&.0,48\&.0"\&.
.RE
.SH "BUGS"
.sp
The battery charge percentage value (in battery\&.charge) is derived from the voltage data that the UPS returns, since the UPS doesn\(cqt return that value directly\&. On some hardware, the charge will remain at 100% for a long time and then drops quickly shortly before the battery runs out\&. You can confirm from the battery\&.voltage readings that this is a problem with the UPS and not this driver\&.
.sp
Similarly, the float from the charger in some models forces the battery charge percentage back up to 100% immedately after the UPS goes back on\-line, so you can\(cqt tell when it is really recharged\&.
.sp
Finally, some models give one value for the battery\(cqs nominal voltage and yet actually have a nominal voltage slightly below that\&. This leads to things such as the perpetual 98\&.7% charge on the author\(cqs Fortress 750, even when it\(cqs been charging for weeks\&. You can use nombattvolt= in \fBups.conf\fR(8) to fix this\&.
.SH "AUTHOR"
.sp
Russell Kroll, Jason White
.SH "SEE ALSO"
.SS "The core driver:"
.sp
\fBnutupsdrv\fR(8)
.SS "Internet resources:"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/

117
docs/man/bestups.txt Normal file
View file

@ -0,0 +1,117 @@
BESTUPS(8)
==========
NAME
----
bestups - Driver for Best Power / SOLA (Phoenixtec protocol) UPS equipment
NOTE
----
This man page only documents the hardware-specific features of the
bestups driver. For information about the core driver, see
linkman:nutupsdrv[8].
SUPPORTED HARDWARE
------------------
*bestups* was designed to monitor Best Power UPS hardware like the Fortress,
Fortress Telecom, Axxium Rackmount and Patriot Pro. It also recognizes
and supports SOLA units such as the 325, 520 and 620. In addition, the
Best 610 is supported using the `ID' option.
Other UPS hardware using the Phoenixtec protocol should also work, but
they will generate a warning since their battery information is not known.
This driver does not support some older Best/SOLA units.
EXTRA ARGUMENTS
---------------
This driver supports the following optional settings in the
linkman:ups.conf[5]:
*nombattvolt=*'num'::
Override the battery float voltage which is normally determined by
asking the hardware. This is useful if your UPS constantly reports
`battery.charge` values just below 100% even when it's completely charged.
+
If you have this problem, set this to whatever `battery.voltage` reports
when the UPS is known to be completely charged with a good battery.
+
The author's Best Fortress 750 uses `nombattvolt=27.4`.
*battvoltmult=*'num'::
Multiply the reported battery voltage by this number. Some devices
report only a fraction of the total battery voltage.
+
For example, the SOLA 610 700VA UPS (with a 24V battery) reports the
single cell voltage (about 2.27V when fully charged). In this particular
case you can set `battvoltmult = 12` in linkman:ups.conf[8] to fix this.
*ID=*'string'::
Set the Identification response string. This should only be used
with hardware that supports the Phoenixtec protocol status inquiry
commands, but not the "ID" command, such as the Best/SOLA 610. Format
of the ID string is: AAA,BBBB,CCC,DDD,EE.E,FF.F
+
AAA is the three-character identification for the UPS model.
+
BBBB is the output power in VA (volt amperes). B is an integer number
ranging from 0 to 9.
+
CCC is the Nominal Input Voltage. C is an integer number ranging from 0
to 9. The unit is Volts AC.
+
DDD is the Nominal Output Voltage. D is an integer number ranging from 0
to 9. The unit is Volts AC.
+
EE.E is the Battery Voltage that will cause the UPS to shut itself off.
E is an integer number ranging from 0 to 9. Then unit is Volts DC and a
decimal point is present.
+
FF.F or FFF.F is the Battery Voltage at full charge. F is an integer
number ranging from 0 to 9. Then unit is Volts DC. Typically, for 700VA,
1KVA and 1.5KVA units, the format is FF.F. For 2KVA and 3KVA units, the
format is FFF.F.
+
Example: a Best 610 1.5KVA unit would use the string
"610,1500,120,120,10.0,48.0".
BUGS
----
The battery charge percentage value (in `battery.charge`) is derived from
the voltage data that the UPS returns, since the UPS doesn't return that
value directly. On some hardware, the charge will remain at 100% for a
long time and then drops quickly shortly before the battery runs out.
You can confirm from the `battery.voltage` readings that this is a problem
with the UPS and not this driver.
Similarly, the float from the charger in some models forces the battery
charge percentage back up to 100% immedately after the UPS goes back
on-line, so you can't tell when it is really recharged.
Finally, some models give one value for the battery's nominal voltage and
yet actually have a nominal voltage slightly below that. This leads to
things such as the perpetual 98.7% charge on the author's Fortress 750,
even when it's been charging for weeks. You can use `nombattvolt=` in
linkman:ups.conf[8] to fix this.
AUTHOR
------
Russell Kroll, Jason White
SEE ALSO
--------
The core driver:
~~~~~~~~~~~~~~~~
linkman:nutupsdrv[8]
Internet resources:
~~~~~~~~~~~~~~~~~~~
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/

313
docs/man/blazer.8 Normal file
View file

@ -0,0 +1,313 @@
'\" t
.\" Title: blazer
.\" Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 12/24/2010
.\" Manual: NUT Manual
.\" Source: Network UPS Tools
.\" Language: English
.\"
.TH "BLAZER" "8" "12/24/2010" "Network UPS Tools" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
blazer \- Driver for Megatec/Q1 protocol serial (blazer_ser) and USB (blazer_usb) based UPS equipment
.SH "NOTE"
.sp
This man page only documents the hardware\-specific features of the blazer driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
.SH "SUPPORTED HARDWARE"
.sp
The blazer driver is known to work with various UPSes from Blazer, Energy Sistem, Fenton Technologies, Mustek and many others\&. The NUT compatibility table lists all the known supported models\&. Keep in mind, however, that other models not listed there may also be supported, but haven\(cqt been tested\&.
.sp
All devices with a serial interface (use the \fBblazer_ser\fR driver) and many with a USB interface (use the \fBblazer_usb\fR driver) are supported\&.
.SH "EXTRA ARGUMENTS"
.sp
You may need to override or provide defaults for some values, depending on the make and model of your UPS\&. The following are the ones that most likely will need changing (see \fBups.conf\fR(5)):
.PP
\fBdefault\&.battery\&.voltage\&.high =\fR \fIvalue\fR
.RS 4
Maximum battery voltage that is reached after about 12 to 24 hours charging\&. If you want the driver to report a guesstimated
\fBbattery\&.charge\fR, you need to specify this (see
BATTERY CHARGE)\&.
.RE
.PP
\fBdefault\&.battery\&.voltage\&.low =\fR \fIvalue\fR
.RS 4
Minimum battery voltage just before the UPS automatically shuts down\&. If you want the driver to report a guesstimated
\fBbattery\&.charge\fR, you need to specify this (see
BATTERY CHARGE)\&.
.RE
.PP
\fBdefault\&.battery\&.voltage\&.nominal =\fR \fIvalue\fR, \fBoverride\&.battery\&.voltage\&.nominal =\fR \fIvalue\fR
.RS 4
Some devices show a wrong nominal battery voltage (or none at all), so you may need to override or set a default value\&.
.RE
.PP
\fBoverride\&.battery\&.packs =\fR \fIvalue\fR
.RS 4
Some devices report a part of the total battery voltage\&. For instance, if
\fBbattery\&.voltage\&.nominal\fR
is 24 V, but it reports a
\fBbattery\&.voltage\fR
of around 2 V, the number of
\fBbattery\&.packs\fR
to correct this reading would be 12\&. The driver will attempt to detect this automatically, but if this fails somehow, you may want to override this value\&.
.RE
.PP
\fBondelay =\fR \fIvalue\fR
.RS 4
Time to wait before switching on the UPS (minutes)\&. Note that a value below 3 minutes, may cause earlier firmware versions to not switch on automatically, so it defaults to 3 minutes\&.
.RE
.PP
\fBoffdelay =\fR \fIvalue\fR
.RS 4
Time to wait before shutting down the UPS (seconds)\&. This value is truncated to units of 6 seconds (less than 60 seconds) or 60 seconds (more than 60 seconds)\&. Defaults to 30 seconds\&.
.RE
.PP
\fBnorating\fR
.RS 4
Some UPSes will lock up if you attempt to read rating information from them\&. Setting this flag will make the driver skip this step\&.
.RE
.PP
\fBnovendor\fR
.RS 4
Some UPSes will lock up if you attempt to read vendor information from them\&. Setting this flag will make the driver skip this step\&.
.RE
.PP
\fBruntimecal =\fR \fIvalue,value,value,value\fR
.RS 4
Parameter used in the (optional) runtime estimation\&. This takes two runtimes at different loads\&. Typically, this uses the runtime at full load and the runtime at half load\&. For instance, if your UPS has a rated runtime of 240 seconds at full load and 720 seconds at half load, you would enter
.sp
.if n \{\
.RS 4
.\}
.nf
runtimecal = 270,100,720,50
.fi
.if n \{\
.RE
.\}
.sp
The first load should always be higher than the second\&. If you have values available for loads other than 100 and 50 % respectively, you can use those too, but keep them spaced apart as far as reasonably possible\&. Just don\(cqt get too close to no load (prediction of runtime depends more on idle load for the battery then)\&.
.RE
.PP
\fBchargetime =\fR \fIvalue\fR
.RS 4
The time needed to fully recharge the battery after being fully discharged\&. If not specified, the driver defaults to 43200 seconds (12 hours)\&. Only used if
\fBruntimecal\fR
is also specified\&.
.RE
.PP
\fBidleload =\fR \fIvalue\fR
.RS 4
Minimum battery load used by the driver to estimate the runtime\&. If not specified, the driver defaults to 10%\&. Only used if
\fBruntimecal\fR
is also specified\&.
.RE
.SH "SERIAL INTERFACE ONLY"
.PP
\fBcablepower =\fR \fIstring\fR
.RS 4
By default the driver will set DTR and clear RTS (\fInormal\fR)\&. If you find that your UPS isn\(cqt detected or the communication with the UPS is unreliable, you may try if clear DTR and set RTS (\fIreverse\fR), set DTR and RTS (\fIboth\fR) or clear DTR and RTS (\fInone\fR) improves this situation\&.
.RE
.SH "USB INTERFACE ONLY"
.PP
\fBvendorid =\fR \fIregex\fR, \fBproductid =\fR \fIregex\fR, \fBvendor =\fR \fIregex\fR, \fBproduct =\fR \fIregex\fR, \fBserial =\fR \fIregex\fR
.RS 4
Select a specific UPS, in case there is more than one connected via USB\&. Each option specifies an extended regular expression (see
\fBregex(7)\fR) that must match the UPS\(cqs entire vendor/product/serial string (minus any surrounding whitespace), or the whole 4\-digit hexadecimal code for vendorid and productid\&. Try
\fB\-DD\fR
for finding out the strings to match\&.
.RE
.sp
Examples:
.sp
.if n \{\
.RS 4
.\}
.nf
\-x vendor="Foo\&.Corporation\&.*"
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\-x vendorid=051d # (APC)
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\-x product="\&.*(Smart|Back)\-?UPS\&.*"
.fi
.if n \{\
.RE
.\}
.PP
\fBbus =\fR \fIregex\fR
.RS 4
Select a UPS on a specific USB bus or group of busses\&. The argument is a regular expression that must match the bus name where the UPS is connected (e\&.g\&. bus="002", bus="00[2\-3]")\&.
.RE
.PP
\fBsubdriver =\fR \fIstring\fR
.RS 4
Select a serial\-over\-USB subdriver to use\&. You have a choice between
\fBphoenix\fR,
\fBippon\fR,
\fBcypress\fR, and
\fBkrauler\fR\&. When using this option, it is mandatory to also specify the
\fBvendorid\fR
and
\fBproductid\fR\&.
.RE
.SH "UPS COMMANDS"
.sp
This driver supports some instant commands (see \fBupscmd\fR(8)):
.PP
\fBbeeper\&.toggle\fR
.RS 4
Toggle the UPS beeper\&. (Not available on some hardware\&.)
.RE
.PP
\fBload\&.on\fR
.RS 4
Turn on the load immediately\&.
.RE
.PP
\fBload\&.off\fR
.RS 4
Turn off the load immediately (see
KNOWN PROBLEMS)\&.
.RE
.PP
\fBshutdown\&.return\fR [\fIvalue\fR]
.RS 4
Turn off the load and return when power is back\&. Uses the timers defined by
\fBondelay\fR
and
\fBoffdelay\fR\&.
.RE
.PP
\fBshutdown\&.stayoff\fR [\fIvalue\fR]
.RS 4
Turn off the load and remain off (see
KNOWN PROBLEMS)\&. Uses the timer defined by
\fBoffdelay\fR\&.
.RE
.PP
\fBshutdown\&.stop\fR
.RS 4
Stop a shutdown in progress\&.
.RE
.PP
\fBtest\&.battery\&.start\&.deep\fR
.RS 4
Perform a long battery test (Not available on some hardware\&.)
.RE
.PP
\fBtest\&.battery\&.start\&.quick\fR
.RS 4
Perform a (10 second) battery test\&.
.RE
.PP
\fBtest\&.battery\&.start\fR \fIvalue\fR
.RS 4
Perform a battery test for the duration of
\fIvalue\fR
seconds (truncated to units of 60 seconds)\&.
.RE
.PP
\fBtest\&.battery\&.stop\fR
.RS 4
Stop a running battery test (not available on some hardware\&.)
.RE
.SH "BATTERY CHARGE"
.sp
Due to popular demand, this driver will report a guesstimated \fBbattery\&.charge\fR and optionally \fBbattery\&.runtime\fR, provided you specified a couple of the EXTRA ARGUMENTS listed above\&.
.sp
If you specify both \fBbattery\&.voltage\&.high\fR and \fBbattery\&.voltage\&.low\fR in \fBups.conf\fR(5), but don\(cqt enter \fBruntimecal\fR, it will guesstimate the state of charge by looking at the battery voltage alone\&. This is not reliable under load, as this only gives reasonably accurate readings if you disconnect the load, let the battery rest for a couple of minutes and then measure the open cell voltage\&. This just isn\(cqt practical if the power went out and the UPS is providing power for your systems\&.
.sp
.if n \{\
.RS 4
.\}
.nf
battery\&.voltage \- battery\&.voltage\&.low
battery\&.charge = \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- x 100 %
battery\&.voltage\&.high \- battery\&.voltage\&.low
.fi
.if n \{\
.RE
.\}
.sp
There is a way to get better readings without disconnecting the load but this requires to keep track on how much (and how fast) current is going in\- and out of the battery\&. If you specified the \fBruntimecal\fR, the driver will attempt to do this\&. Note however, that this heavily relies on the values you enter and that the UPS must be able to report the load as well\&. There are quite a couple of devices that report 0 % (or any other fixed value) at all times, in which case this obviously doesn\(cqt work\&.
.sp
The driver also has no way of determining the degradation of the battery capacity over time, so you\(cqll have to deal with this yourself (by adjusting the values in \fBruntimecal\fR)\&. Also note that the driver guesses the initial state of charge based on the battery voltage, so this may be less than 100 %, even when you are certain that they are full\&. There is just no way to reliably measure this between 0 and 100 % full charge\&.
.sp
This is better than nothing (but not by much)\&. If any of the above calculations is giving you incorrect readings, you are the one that put in the values in \fBups.conf\fR(5), so don\(cqt complain with the author\&. If you need something better, buy a UPS that reports \fBbattery\&.charge\fR and \fBbattery\&.runtime\fR all by itself without the help of a NUT driver\&.
.SH "NOTES FOR THE PREVIOUS USER OF MEGATEC DRIVERS"
.sp
The blazer drivers having replaced the megatec ones, some configuration changes may be required by users switching to blazer\&.
.sp
Part of this, the following megatec options, in ups\&.conf, have to be changed:
.PP
\fBbattvolts\fR
.RS 4
You need to use
\fIdefault\&.battery\&.voltage\&.high\fR
and
\fIdefault\&.battery\&.voltage\&.low\fR
.RE
.PP
\fBdtr and rts\fR
.RS 4
You need to use
\fIcablepower\fR
.RE
.PP
\fBignoreoff\fR
.RS 4
This parameter can simply be discarded, since it was a wrong understanding of the specification\&.
.RE
.SH "KNOWN PROBLEMS"
.sp
Some UPS commands aren\(cqt supported by all models\&. In most cases, the driver will send a message to the system log when the user tries to execute an unsupported command\&. Unfortunately, some models don\(cqt even provide a way for the driver to check for this, so the unsupported commands will silently fail\&.
.sp
Both the \fBload\&.off\fR and \fBshutdown\&.stayoff\fR instant commands are meant to turn the load off indefinitely\&. However, some UPS models don\(cqt allow this\&.
.sp
Some models report a bogus value for the beeper status (will always be \fIenabled\fR or \fIdisabled\fR)\&. So, the \fBbeeper\&.toggle\fR command may appear to have no effect in the status reported by the driver when, in fact, it is working fine\&.
.sp
The temperature and load value is known to be bogus in some models\&.
.SH "AUTHORS"
.sp
Arjen de Korte <adkorte\-guest at alioth\&.debian\&.org>, Alexander Gordeev <lasaine at lvk\&.cs\&.msu\&.su>
.SH "SEE ALSO"
.sp
\fBnutupsdrv\fR(8), \fBupsc\fR(8), \fBupscmd\fR(8), \fBupsrw\fR(8)
.SS "Internet Resources:"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/

295
docs/man/blazer.txt Normal file
View file

@ -0,0 +1,295 @@
BLAZER(8)
=========
NAME
----
blazer - Driver for Megatec/Q1 protocol serial (blazer_ser) and USB (blazer_usb) based UPS equipment
NOTE
----
This man page only documents the hardware-specific features of the
blazer driver. For information about the core driver, see
linkman:nutupsdrv[8].
SUPPORTED HARDWARE
------------------
The blazer driver is known to work with various UPSes from Blazer, Energy
Sistem, Fenton Technologies, Mustek and many others. The NUT compatibility
table lists all the known supported models. Keep in mind, however, that
other models not listed there may also be supported, but haven't been tested.
All devices with a serial interface (use the *blazer_ser* driver) and
many with a USB interface (use the *blazer_usb* driver) are supported.
EXTRA ARGUMENTS
---------------
You may need to override or provide defaults for some values, depending on
the make and model of your UPS. The following are the ones that most likely
will need changing (see linkman:ups.conf[5]):
*default.battery.voltage.high =* 'value'::
Maximum battery voltage that is reached after about 12 to 24 hours charging.
If you want the driver to report a guesstimated *battery.charge*, you need
to specify this (see <<_battery_charge,BATTERY CHARGE>>).
*default.battery.voltage.low =* 'value'::
Minimum battery voltage just before the UPS automatically shuts down.
If you want the driver to report a guesstimated *battery.charge*, you need
to specify this (see <<_battery_charge,BATTERY CHARGE>>).
*default.battery.voltage.nominal =* 'value'::
*override.battery.voltage.nominal =* 'value'::
Some devices show a wrong nominal battery voltage (or none at all), so you may
need to override or set a default value.
*override.battery.packs =* 'value'::
Some devices report a part of the total battery voltage. For instance, if
*battery.voltage.nominal* is 24 V, but it reports a *battery.voltage*
of around 2 V, the number of *battery.packs* to correct this reading would
be 12. The driver will attempt to detect this automatically, but if this fails
somehow, you may want to override this value.
*ondelay =* 'value'::
Time to wait before switching on the UPS (minutes). Note that a value below 3
minutes, may cause earlier firmware versions to not switch on automatically,
so it defaults to 3 minutes.
*offdelay =* 'value'::
Time to wait before shutting down the UPS (seconds). This value is truncated
to units of 6 seconds (less than 60 seconds) or 60 seconds (more than 60
seconds). Defaults to 30 seconds.
*norating*::
Some UPSes will lock up if you attempt to read rating information from them.
Setting this flag will make the driver skip this step.
*novendor*::
Some UPSes will lock up if you attempt to read vendor information from them.
Setting this flag will make the driver skip this step.
*runtimecal =* 'value,value,value,value'::
Parameter used in the (optional) runtime estimation. This takes two runtimes
at different loads. Typically, this uses the runtime at full load and the
runtime at half load. For instance, if your UPS has a rated runtime of 240
seconds at full load and 720 seconds at half load, you would enter
+
runtimecal = 270,100,720,50
+
The first load should always be higher than the second. If you have values
available for loads other than 100 and 50 % respectively, you can use those
too, but keep them spaced apart as far as reasonably possible. Just don't
get too close to no load (prediction of runtime depends more on idle load for
the battery then).
*chargetime =* 'value'::
The time needed to fully recharge the battery after being fully discharged. If
not specified, the driver defaults to 43200 seconds (12 hours). Only used if
*runtimecal* is also specified.
*idleload =* 'value'::
Minimum battery load used by the driver to estimate the runtime. If not
specified, the driver defaults to 10%. Only used if *runtimecal* is also
specified.
SERIAL INTERFACE ONLY
---------------------
*cablepower =* 'string'::
By default the driver will set DTR and clear RTS ('normal'). If you find that
your UPS isn't detected or the communication with the UPS is unreliable, you may
try if clear DTR and set RTS ('reverse'), set DTR and RTS ('both') or
clear DTR and RTS ('none') improves this situation.
USB INTERFACE ONLY
------------------
*vendorid =* 'regex'::
*productid =* 'regex'::
*vendor =* 'regex'::
*product =* 'regex'::
*serial =* 'regex'::
Select a specific UPS, in case there is more than one connected via
USB. Each option specifies an extended regular expression (see
*regex(7)*) that must match the UPS's entire vendor/product/serial
string (minus any surrounding whitespace), or the whole 4-digit
hexadecimal code for vendorid and productid. Try *-DD* for
finding out the strings to match.
Examples:
-x vendor="Foo.Corporation.*"
-x vendorid=051d # (APC)
-x product=".*(Smart|Back)-?UPS.*"
*bus =* 'regex'::
Select a UPS on a specific USB bus or group of busses. The argument is
a regular expression that must match the bus name where the UPS is
connected (e.g. bus="002", bus="00[2-3]").
*subdriver =* 'string'::
Select a serial-over-USB subdriver to use. You have a choice between *phoenix*,
*ippon*, *cypress*, and *krauler*. When using this option, it is mandatory to also
specify the *vendorid* and *productid*.
UPS COMMANDS
------------
This driver supports some instant commands (see linkman:upscmd[8]):
*beeper.toggle*::
Toggle the UPS beeper. (Not available on some hardware.)
*load.on*::
Turn on the load immediately.
*load.off*::
Turn off the load immediately (see <<_known_problems,KNOWN PROBLEMS>>).
*shutdown.return* ['value']::
Turn off the load and return when power is back. Uses the timers defined by
*ondelay* and *offdelay*.
*shutdown.stayoff* ['value']::
Turn off the load and remain off (see <<_known_problems,KNOWN PROBLEMS>>). Uses
the timer defined by *offdelay*.
*shutdown.stop*::
Stop a shutdown in progress.
*test.battery.start.deep*::
Perform a long battery test (Not available on some hardware.)
*test.battery.start.quick*::
Perform a (10 second) battery test.
*test.battery.start* 'value'::
Perform a battery test for the duration of 'value' seconds (truncated to units of
60 seconds).
*test.battery.stop*::
Stop a running battery test (not available on some hardware.)
BATTERY CHARGE
--------------
Due to popular demand, this driver will report a guesstimated *battery.charge*
and optionally *battery.runtime*, provided you specified a couple of the
<<_extra_arguments,EXTRA ARGUMENTS>> listed above.
If you specify both *battery.voltage.high* and *battery.voltage.low* in
linkman:ups.conf[5], but don't enter *runtimecal*, it will guesstimate the state
of charge by looking at the battery voltage alone. This is not reliable under load,
as this only gives reasonably accurate readings if you disconnect the load, let the
battery rest for a couple of minutes and then measure the open cell voltage. This
just isn't practical if the power went out and the UPS is providing power for your
systems.
battery.voltage - battery.voltage.low
battery.charge = ------------------------------------------ x 100 %
battery.voltage.high - battery.voltage.low
There is a way to get better readings without disconnecting the load but this
requires to keep track on how much (and how fast) current is going in- and out of
the battery. If you specified the *runtimecal*, the driver will attempt to do
this. Note however, that this heavily relies on the values you enter and that the
UPS must be able to report the load as well. There are quite a couple of devices
that report 0 % (or any other fixed value) at all times, in which case this
obviously doesn't work.
The driver also has no way of determining the degradation of the battery capacity
over time, so you'll have to deal with this yourself (by adjusting the values
in *runtimecal*). Also note that the driver guesses the initial state of charge
based on the battery voltage, so this may be less than 100 %, even when you are
certain that they are full. There is just no way to reliably measure this between
0 and 100 % full charge.
This is better than nothing (but not by much). If any of the above calculations is
giving you incorrect readings, you are the one that put in the values in
linkman:ups.conf[5], so don't complain with the author. If you need something better,
buy a UPS that reports *battery.charge* and *battery.runtime* all by itself
without the help of a NUT driver.
NOTES FOR THE PREVIOUS USER OF MEGATEC DRIVERS
----------------------------------------------
The blazer drivers having replaced the megatec ones, some configuration
changes may be required by users switching to blazer.
Part of this, the following megatec options, in ups.conf, have to be changed:
*battvolts*::
You need to use 'default.battery.voltage.high' and 'default.battery.voltage.low'
*dtr and rts*::
You need to use 'cablepower'
*ignoreoff*::
This parameter can simply be discarded, since it was a wrong understanding
of the specification.
KNOWN PROBLEMS
--------------
Some UPS commands aren't supported by all models. In most cases, the driver
will send a message to the system log when the user tries to execute an
unsupported command. Unfortunately, some models don't even provide a way for
the driver to check for this, so the unsupported commands will silently
fail.
Both the *load.off* and *shutdown.stayoff* instant commands are meant to
turn the load off indefinitely. However, some UPS models don't allow this.
Some models report a bogus value for the beeper status (will always be 'enabled'
or 'disabled'). So, the *beeper.toggle* command may appear to have no effect
in the status reported by the driver when, in fact, it is working fine.
The temperature and load value is known to be bogus in some models.
AUTHORS
-------
Arjen de Korte <adkorte-guest at alioth.debian.org>,
Alexander Gordeev <lasaine at lvk.cs.msu.su>
SEE ALSO
--------
linkman:nutupsdrv[8], linkman:upsc[8], linkman:upscmd[8], linkman:upsrw[8]
Internet Resources:
~~~~~~~~~~~~~~~~~~~
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/

135
docs/man/clone.8 Normal file
View file

@ -0,0 +1,135 @@
'\" t
.\" Title: clone
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 12/24/2010
.\" Manual: NUT Manual
.\" Source: Network UPS Tools
.\" Language: English
.\"
.TH "CLONE" "8" "12/24/2010" "Network UPS Tools" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
clone \- UPS driver clone
.SH "NOTE"
.sp
This man page only documents the specific features of the clone driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
.SH "DESCRIPTION"
.sp
This driver, which sits on top of another driver socket, allows users to group clients to a particular outlet of a device and deal with this output as if it was a normal UPS\&.
.SH "EXTRA ARGUMENTS"
.sp
This driver supports the following settings:
.PP
\fBload\&.off\fR=\fIcommand\fR
.RS 4
Recommended\&. Set the command on the "real" UPS driver that will be used to switch off the outlet\&. You need both
\fBload\&.off\fR
and
\fBload\&.on\fR
in order to power cycle the outlet\&. Otherwise, shutting down the clients powered by an outlet is a one way street (see
IMPORTANT)\&.
.RE
.PP
\fBload\&.on\fR=\fIcommand\fR
.RS 4
Recommended\&. Set the command on the "real" UPS driver that will be used to switch on the outlet\&. You need both
\fBload\&.off\fR
and
\fBload\&.on\fR
in order to power cycle the outlet\&. Otherwise, shutting down the clients powered by an outlet is a one way street (see
IMPORTANT)\&.
.RE
.PP
\fBload\&.status\fR=\fIvalue\fR
.RS 4
Recommended\&. Set the variable on the "real" UPS driver that will be used to indicate the outlet status (i\&.e\&. on/off)\&. If not specified, the clone driver will attempt to keep track of the outlet status, but this is less reliable\&.
.RE
.PP
\fBoffdelay\fR=\fInum\fR
.RS 4
Set the timer (in seconds) before the outlet is turned off after the shutdown condition (OB LB) for this outlet is met or a command to shutdown was issued\&. Defaults to 120 seconds\&.
.RE
.PP
\fBondelay\fR=\fInum\fR
.RS 4
Set the timer (in seconds) for the outlet to switch on in case the power returns after the oulet has been switched off\&. Defaults to 30 seconds\&.
.RE
.PP
\fBmincharge\fR=\fIvalue\fR
.RS 4
Set the remaining battery level when the clone UPS switches to LB (percent)\&.
.RE
.PP
\fBminruntime\fR=\fIvalue\fR
.RS 4
Set the remaining battery runtime when the clone UPS switches to LB (seconds)\&.
.RE
.SH "IMPLEMENTATION"
.sp
The port specification in the \fBups.conf\fR(5) reference the driver socket that the "real" UPS driver is using\&. For example:
.sp
.if n \{\
.RS 4
.\}
.nf
[realups]
driver = usbhid\-ups
port = auto
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
[clone\-outlet\-1]
driver = clone
port = usbhid\-ups\-realups
load\&.on = outlet\&.1\&.load\&.on
load\&.off = outlet\&.1\&.load\&.off
load\&.status = outlet\&.1\&.status
[\&.\&.\&.]
.fi
.if n \{\
.RE
.\}
.SH "IMPORTANT"
.sp
Unlike a real UPS, you should \fBnot\fR configure a upsmon master for this driver\&. When a upsmon master sees the OB LB flags and tells the upsd server it is OK to initiate the shutdown sequence, the server will latch the FSD status and it will not be possible to restart the systems connected without restarting the upsd server\&.
.sp
This will be a problem if the power returns after the clone UPS initiated the shutdown sequence on it\(cqs outlet, but returns before the real UPS begins shutting down\&. The solution is in the clone driver, that will insert the FSD flag if needed without the help of a upsmon master\&.
.SH "CAVEATS"
.sp
The clone UPS will follow the status on the real UPS driver\&. You can only make the clone UPS shutdown earlier than the real UPS driver, not later\&. If the real UPS driver initiates a shutdown, the clone UPS driver will immediately follow\&.
.sp
Be aware that the commands to shutdown/restart an outlet on the real UPS drivers are not affected, so if you tell the real UPS driver to shutdown the outlet of the clone UPS driver, your clients will lose power without warning\&.
.SH "AUTHOR"
.sp
Arjen de Korte <adkorte\-guest@alioth\&.debian\&.org>
.SH "SEE ALSO"
.sp
\fBupscmd\fR(1), \fBupsrw\fR(1), \fBups.conf\fR(5), \fBnutupsdrv\fR(8)
.SS "Internet Resources:"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/

115
docs/man/clone.txt Normal file
View file

@ -0,0 +1,115 @@
CLONE(8)
========
NAME
----
clone - UPS driver clone
NOTE
----
This man page only documents the specific features of the
clone driver. For information about the core driver, see
linkman:nutupsdrv[8].
DESCRIPTION
-----------
This driver, which sits on top of another driver socket, allows users to group
clients to a particular outlet of a device and deal with this output as if it
was a normal UPS.
EXTRA ARGUMENTS
---------------
This driver supports the following settings:
*load.off*='command'::
Recommended. Set the command on the "real" UPS driver that will be used to
switch off the outlet. You need both *load.off* and *load.on* in
order to power cycle the outlet. Otherwise, shutting down the clients
powered by an outlet is a one way street (see <<_important,IMPORTANT>>).
*load.on*='command'::
Recommended. Set the command on the "real" UPS driver that will be used to
switch on the outlet. You need both *load.off* and *load.on* in
order to power cycle the outlet. Otherwise, shutting down the clients
powered by an outlet is a one way street (see <<_important,IMPORTANT>>).
*load.status*='value'::
Recommended. Set the variable on the "real" UPS driver that will be used
to indicate the outlet status (i.e. on/off). If not specified, the clone
driver will attempt to keep track of the outlet status, but this is less
reliable.
*offdelay*='num'::
Set the timer (in seconds) before the outlet is turned off after the
shutdown condition (+OB LB+) for this outlet is met or a command to shutdown
was issued. Defaults to 120 seconds.
*ondelay*='num'::
Set the timer (in seconds) for the outlet to switch on in case the power
returns after the oulet has been switched off. Defaults to 30 seconds.
*mincharge*='value'::
Set the remaining battery level when the clone UPS switches to LB
(percent).
*minruntime*='value'::
Set the remaining battery runtime when the clone UPS switches to LB
(seconds).
IMPLEMENTATION
--------------
The port specification in the linkman:ups.conf[5] reference the driver
socket that the "real" UPS driver is using. For example:
[realups]
driver = usbhid-ups
port = auto
[clone-outlet-1]
driver = clone
port = usbhid-ups-realups
load.on = outlet.1.load.on
load.off = outlet.1.load.off
load.status = outlet.1.status
[...]
IMPORTANT
---------
Unlike a real UPS, you should *not* configure a upsmon master for this
driver. When a upsmon master sees the OB LB flags and tells the upsd server
it is OK to initiate the shutdown sequence, the server will latch the FSD
status and it will not be possible to restart the systems connected without
restarting the upsd server.
This will be a problem if the power returns after the clone UPS initiated
the shutdown sequence on it's outlet, but returns before the real UPS begins
shutting down. The solution is in the clone driver, that will insert the
FSD flag if needed without the help of a upsmon master.
CAVEATS
-------
The clone UPS will follow the status on the real UPS driver. You can only
make the clone UPS shutdown earlier than the real UPS driver, not later.
If the real UPS driver initiates a shutdown, the clone UPS driver will
immediately follow.
Be aware that the commands to shutdown/restart an outlet on the real UPS
drivers are not affected, so if you tell the real UPS driver to shutdown
the outlet of the clone UPS driver, your clients will lose power without
warning.
AUTHOR
------
Arjen de Korte <adkorte-guest@alioth.debian.org>
SEE ALSO
--------
linkman:upscmd[1],
linkman:upsrw[1],
linkman:ups.conf[5],
linkman:nutupsdrv[8]
Internet Resources:
~~~~~~~~~~~~~~~~~~~
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/

145
docs/man/dummy-ups.8 Normal file
View file

@ -0,0 +1,145 @@
'\" t
.\" Title: dummy-ups
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 12/24/2010
.\" Manual: NUT Manual
.\" Source: Network UPS Tools
.\" Language: English
.\"
.TH "DUMMY\-UPS" "8" "12/24/2010" "Network UPS Tools" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
dummy-ups \- Driver for multi\-purpose UPS emulation
.SH "NOTE"
.sp
This man page only documents the specific features of the dummy\-ups driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
.SH "DESCRIPTION"
.sp
This program is a multi\-purpose UPS emulation tool\&. Its behavior depends on the running mode:
.SS "Dummy Mode"
.sp
\fBdummy\-ups\fR looks like a standard device driver to \fBupsd\fR(8) and allows to change any value for testing purposes\&. It is both interactive, controllable through the \fBupsrw\fR(1) and \fBupscmd\fR(1) commands (or equivalent graphical tool), and batchable through script files\&. It can be configured, launched and used as any other real driver\&. This mode is mostly useful for development and testing purposes\&.
.SS "Repeater Mode"
.sp
\fBdummy\-ups\fR acts as a NUT client, simply forwarding data\&. This can be useful for supervision purposes\&. This can also allow some load sharing between several UPS instances, using a point\-to\-point communication with the UPS\&.
.SH "IMPLEMENTATION"
.sp
The port specification depends on the running mode, and allows the driver to select the right mode\&.
.SS "Dummy Mode"
.sp
Port is a definition file name for \fBdummy\-ups\fR\&. This can either be an absolute or a relative path name\&. In the latter case the NUT sysconfig directory (ie /etc/nut, /usr/local/ups/etc, \&...) is prepended\&.
.sp
For instance:
.sp
.if n \{\
.RS 4
.\}
.nf
[dummy]
driver = dummy\-ups
port = evolution500\&.dev
desc = "dummy\-ups in dummy mode"
.fi
.if n \{\
.RE
.\}
.sp
This file is generally named "something\&.dev"\&. It contains a list of all valid data and associated values, and has the same format as an \fBupsc\fR(8) dump (<varname>: <value>)\&. So you can easilly create definition files from an existing UPS using "upsc > file\&.dev"\&. It can also be empty, in which case only a basic set of data is available: device\&.\fB, driver\&.\fR, ups\&.mfr, ups\&.model, ups\&.status
.sp
Samples definition files are available in the "data" directory of the nut source tree, and generally in the sysconfig directory of your system distribution\&.
.sp
Since \fBdummy\-ups\fR will loop on reading this file, you can dynamically modify it to interact with the driver\&. This will avoid message spam into your system log files, if you are using NUT default configuration\&.
.sp
You can also use the "TIMER <seconds>" instruction to create scheduled events sequences\&. For example, the following sequence will loop on switching ups\&.status between "OL", "OB" and "OB LB" every minute:
.sp
.if n \{\
.RS 4
.\}
.nf
ups\&.status: OL
TIMER 60
ups\&.status: OB
TIMER 60
ups\&.status: LB
TIMER 60
.fi
.if n \{\
.RE
.\}
.sp
It is wise to end the script with a TIMER\&. Otherwise dummy\-ups will directly go back to the beginning of the file\&.
.SS "Repeater Mode"
.sp
Port is the name of a remote UPS, using the NUT form, ie:
.sp
.if n \{\
.RS 4
.\}
.nf
<upsname>[@<hostname>[:<port>]]
.fi
.if n \{\
.RE
.\}
.sp
For instance:
.sp
.if n \{\
.RS 4
.\}
.nf
[repeater]
driver = dummy\-ups
port = ups@hostname
desc = "dummy\-ups in repeater mode"
.fi
.if n \{\
.RE
.\}
.SH "INTERACTION"
.sp
Once the driver is loaded in dummy mode, you can change any variables, except those of the driver\&.* and server\&.* collections\&. You can do this by either editing the definition file, or use the \fBupsrw\fR(1) and \fBupscmd\fR(1) commands\&.
.sp
Note that in simulation mode, new variables can be added on the fly, by adding these to the definition file\&. Conversely, if you need to remove variable (such as transient ones, like ups\&.alarm), simply update these by setting an empty value\&. As a result, they will get removed from the data\&.
.sp
In repeater mode, the driver acts according to the capabilities of the UPS, and so support the same instant commands and settable values\&.
.SH "BACKGROUND"
.sp
This driver was written in one evening to replace the previous dummycons testing driver\&. It was too limited and required to work from a terminal to interact\&.
.sp
\fBdummy\-ups\fR is useful for NUT client development, and other testing purpose\&.
.sp
It also helps the NUT Quality Assurance effort, by automating some tests on the NUT framework\&.
.sp
It now offers a repeater mode\&. This will help in building the Meta UPS approach, which allows to build a virtual device, composed of several other devices (either UPS, PDUs)\&.
.SH "BUGS"
.sp
Instant commands are not yet supported in Dummy Mode, and data need name/value checking enforcement, as well as boundaries or enumeration definition\&.
.SH "AUTHOR"
.sp
Arnaud Quette
.SH "SEE ALSO"
.sp
\fBupscmd\fR(1), \fBupsrw\fR(1), \fBups.conf\fR(5), \fBnutupsdrv\fR(8)
.SS "Internet Resources:"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/

149
docs/man/dummy-ups.txt Normal file
View file

@ -0,0 +1,149 @@
DUMMY-UPS(8)
============
NAME
----
dummy-ups - Driver for multi-purpose UPS emulation
NOTE
----
This man page only documents the specific features of the
dummy-ups driver. For information about the core driver, see
linkman:nutupsdrv[8].
DESCRIPTION
-----------
This program is a multi-purpose UPS emulation tool.
Its behavior depends on the running mode:
Dummy Mode
~~~~~~~~~~
*dummy-ups* looks like a standard device driver to linkman:upsd[8] and
allows to change any value for testing purposes. It is both interactive,
controllable through the linkman:upsrw[1] and linkman:upscmd[1] commands (or
equivalent graphical tool), and batchable through script files. It can be
configured, launched and used as any other real driver. This mode is mostly
useful for development and testing purposes.
Repeater Mode
~~~~~~~~~~~~~
*dummy-ups* acts as a NUT client, simply forwarding data. This can be useful
for supervision purposes. This can also allow some load sharing between several
UPS instances, using a point-to-point communication with the UPS.
IMPLEMENTATION
--------------
The port specification depends on the running mode, and allows the driver to
select the right mode.
Dummy Mode
~~~~~~~~~~
Port is a definition file name for *dummy-ups*. This can either
be an absolute or a relative path name. In the latter case the NUT
sysconfig directory (ie /etc/nut, /usr/local/ups/etc, ...) is prepended.
For instance:
[dummy]
driver = dummy-ups
port = evolution500.dev
desc = "dummy-ups in dummy mode"
This file is generally named "something.dev". It contains a list of all
valid data and associated values, and has the same format as an linkman:upsc[8]
dump (<varname>: <value>). So you can easilly create definition
files from an existing UPS using "upsc > file.dev".
It can also be empty, in which case only a basic set of data is available:
device.*, driver.*, ups.mfr, ups.model, ups.status
Samples definition files are available in the "data" directory of the nut source
tree, and generally in the sysconfig directory of your system distribution.
Since *dummy-ups* will loop on reading this file, you can dynamically modify
it to interact with the driver. This will avoid message spam into your
system log files, if you are using NUT default configuration.
You can also use the "TIMER <seconds>" instruction to create scheduled events
sequences. For example, the following sequence will loop on switching ups.status
between "OL", "OB" and "OB LB" every minute:
ups.status: OL
TIMER 60
ups.status: OB
TIMER 60
ups.status: LB
TIMER 60
It is wise to end the script with a TIMER. Otherwise dummy-ups will directly
go back to the beginning of the file.
Repeater Mode
~~~~~~~~~~~~~
Port is the name of a remote UPS, using the NUT form, ie:
<upsname>[@<hostname>[:<port>]]
For instance:
[repeater]
driver = dummy-ups
port = ups@hostname
desc = "dummy-ups in repeater mode"
INTERACTION
-----------
Once the driver is loaded in dummy mode, you can change any variables, except
those of the driver.* and server.* collections.
You can do this by either editing the definition file, or use the
linkman:upsrw[1] and linkman:upscmd[1] commands.
Note that in simulation mode, new variables can be added on the fly, by
adding these to the definition file. Conversely, if you need to remove
variable (such as transient ones, like ups.alarm), simply update these
by setting an empty value. As a result, they will get removed from the data.
In repeater mode, the driver acts according to the capabilities of the UPS, and
so support the same instant commands and settable values.
BACKGROUND
----------
This driver was written in one evening to replace the previous dummycons
testing driver. It was too limited and required to work from a terminal to
interact.
*dummy-ups* is useful for NUT client development, and other testing purpose.
It also helps the NUT Quality Assurance effort, by automating some tests on the
NUT framework.
It now offers a repeater mode. This will help in building the Meta UPS approach,
which allows to build a virtual device, composed of several other devices
(either UPS, PDUs).
BUGS
----
Instant commands are not yet supported in Dummy Mode, and data need name/value
checking enforcement, as well as boundaries or enumeration definition.
AUTHOR
------
Arnaud Quette
SEE ALSO
--------
linkman:upscmd[1],
linkman:upsrw[1],
linkman:ups.conf[5],
linkman:nutupsdrv[8]
Internet Resources:
~~~~~~~~~~~~~~~~~~~
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/

50
docs/man/etapro.8 Normal file
View file

@ -0,0 +1,50 @@
'\" t
.\" Title: etapro
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 12/24/2010
.\" Manual: NUT Manual
.\" Source: Network UPS Tools
.\" Language: English
.\"
.TH "ETAPRO" "8" "12/24/2010" "Network UPS Tools" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
etapro \- Driver for ETA UPS equipment
.SH "NOTE"
.sp
This man page only documents the hardware\-specific features of the etapro driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
.SH "SUPPORTED HARDWARE"
.sp
This driver supports ETA UPS equipment with the "PRO" option for smart mode\&.
.SH "EXTRA ARGUMENTS"
.sp
This driver does not support any extra settings in the \fBups.conf\fR(5)\&.
.SH "AUTHOR"
.sp
Marek Michalkiewicz <marekm@amelek\&.gda\&.pl>
.SH "SEE ALSO"
.SS "The core driver:"
.sp
\fBnutupsdrv\fR(8)
.SS "Internet resources:"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/

35
docs/man/etapro.txt Normal file
View file

@ -0,0 +1,35 @@
ETAPRO(8)
=========
NAME
----
etapro - Driver for ETA UPS equipment
NOTE
----
This man page only documents the hardware-specific features of the
etapro driver. For information about the core driver, see
linkman:nutupsdrv[8].
SUPPORTED HARDWARE
------------------
This driver supports ETA UPS equipment with the "PRO" option for smart mode.
EXTRA ARGUMENTS
---------------
This driver does not support any extra settings in the
linkman:ups.conf[5].
AUTHOR
------
Marek Michalkiewicz <marekm@amelek.gda.pl>
SEE ALSO
--------
The core driver:
~~~~~~~~~~~~~~~~
linkman:nutupsdrv[8]
Internet resources:
~~~~~~~~~~~~~~~~~~~
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/

53
docs/man/everups.8 Normal file
View file

@ -0,0 +1,53 @@
'\" t
.\" Title: everups
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 12/24/2010
.\" Manual: NUT Manual
.\" Source: Network UPS Tools
.\" Language: English
.\"
.TH "EVERUPS" "8" "12/24/2010" "Network UPS Tools" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
everups \- Driver for Ever UPS models
.SH "NOTE"
.sp
This man page only documents the hardware\-specific features of the everups driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
.SH "SUPPORTED HARDWARE"
.sp
This driver should recognize the NET *\-DPC and AP *\-PRO models\&.
.SH "EXTRA ARGUMENTS"
.sp
This driver does not support any extra settings in the \fBups.conf\fR(5)\&.
.SH "BUGS"
.sp
This UPS can only switch off the load if it\(cqs running on battery\&. This means you may be vulnerable to power races if your shutdown scripts don\(cqt sleep and force a reboot\&.
.SH "AUTHOR"
.sp
Bartek Szady <bszx@bszxdomain\&.edu\&.eu\&.org>
.SH "SEE ALSO"
.SS "The core driver:"
.sp
\fBnutupsdrv\fR(8)
.SS "Internet resources:"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/

44
docs/man/everups.txt Normal file
View file

@ -0,0 +1,44 @@
EVERUPS(8)
==========
NAME
----
everups - Driver for Ever UPS models
NOTE
----
This man page only documents the hardware-specific features of the
everups driver. For information about the core driver, see
linkman:nutupsdrv[8].
SUPPORTED HARDWARE
------------------
This driver should recognize the NET *-DPC and AP *-PRO models.
EXTRA ARGUMENTS
---------------
This driver does not support any extra settings in the
linkman:ups.conf[5].
BUGS
----
This UPS can only switch off the load if it's running on battery. This
means you may be vulnerable to power races if your shutdown scripts
don't sleep and force a reboot.
AUTHOR
------
Bartek Szady <bszx@bszxdomain.edu.eu.org>
SEE ALSO
--------
The core driver:
~~~~~~~~~~~~~~~~
linkman:nutupsdrv[8]
Internet resources:
~~~~~~~~~~~~~~~~~~~
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/

50
docs/man/gamatronic.8 Normal file
View file

@ -0,0 +1,50 @@
'\" t
.\" Title: gamatronic
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 12/24/2010
.\" Manual: NUT Manual
.\" Source: Network UPS Tools
.\" Language: English
.\"
.TH "GAMATRONIC" "8" "12/24/2010" "Network UPS Tools" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
gamatronic \- Driver for Gamatronic UPS equipment
.SH "NOTE"
.sp
This man page only documents the hardware\-specific features of the gamatronic driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
.SH "SUPPORTED HARDWARE"
.sp
Various \- Rebuilt to work with Gamatronic UPS Units, but should recognize any UPS that speaks the SEC protocol at 1200\-19200 bps\&.
.SH "EXTRA ARGUMENTS"
.sp
This driver does not support any extra settings in the \fBups.conf\fR(5)\&.
.SH "AUTHOR"
.sp
Nadav Moskovitch <blutz@walla\&.com>
.SH "SEE ALSO"
.SS "The core driver"
.sp
\fBnutupsdrv\fR(8)
.SS "Internet resources"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/

38
docs/man/gamatronic.txt Normal file
View file

@ -0,0 +1,38 @@
GAMATRONIC(8)
=============
NAME
----
gamatronic - Driver for Gamatronic UPS equipment
NOTE
----
This man page only documents the hardware-specific features of the
gamatronic driver. For information about the core driver, see
linkman:nutupsdrv[8].
SUPPORTED HARDWARE
------------------
Various - Rebuilt to work with Gamatronic UPS Units, but should recognize any
UPS that speaks the SEC protocol at 1200-19200 bps.
EXTRA ARGUMENTS
---------------
This driver does not support any extra settings in the
linkman:ups.conf[5].
AUTHOR
------
Nadav Moskovitch <blutz@walla.com>
SEE ALSO
--------
The core driver
~~~~~~~~~~~~~~~
linkman:nutupsdrv[8]
Internet resources
~~~~~~~~~~~~~~~~~~
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/

593
docs/man/genericups.8 Normal file
View file

@ -0,0 +1,593 @@
'\" t
.\" Title: genericups
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 12/24/2010
.\" Manual: NUT Manual
.\" Source: Network UPS Tools
.\" Language: English
.\"
.TH "GENERICUPS" "8" "12/24/2010" "Network UPS Tools" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
genericups \- Driver for contact\-closure UPS equipment
.SH "NOTE"
.sp
This man page only documents the specific features of the genericups driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
.SH "SUPPORTED HARDWARE"
.sp
This driver supports hardware from many different manufacturers as it only uses the very simplest of signaling schemes\&. Contact closure refers to a kind of interface where basic high/low signals are provided to indicate status\&. This kind of UPS can only report line power and battery status\&.
.sp
This means that you will only get the essentials in ups\&.status: OL, OB, and LB\&. Anything else requires a smarter UPS\&.
.SH "CABLING"
.sp
Cabling is different for every kind of UPS\&. See the table below for information on what is known to work with a given UPS type\&.
.SH "EXTRA ARGUMENTS"
.sp
This driver supports the following settings in the \fBups.conf\fR(5):
.PP
upstype=\fItype\fR
.RS 4
Required\&. Configures the driver for a specific kind of UPS\&. See the
UPS Types
section below for more information on which entries are available\&.
.RE
.PP
mfr=\fIstring\fR
.RS 4
Optional\&. The very nature of a generic UPS driver sometimes means that the stock manufacturer data has no relation to the actual hardware that is attached\&. With the
mfr
setting, you can change the value that is seen by clients that monitor this UPS\&.
.RE
.PP
model=\fIstring\fR
.RS 4
Optional\&. This is like
mfr
above, but it overrides the model string instead\&.
.RE
.PP
serial=\fIstring\fR
.RS 4
Optional\&. This is like
mfr
above and intended to record the identification string of the UPS\&. It is titled "serial" because usually this string is referred to as the serial number\&.
.RE
.PP
sdtime=\fIvalue\fR
.RS 4
Optional\&. The driver will sleep for this many seconds after setting the shutdown signal\&. This is necessary for some hardware which requires a sustained level to activate the shutdown sequence\&.
.sp
The default behavior of the driver is to exit immediately\&. If this doesn\(cqt reliably trigger a shutdown in your UPS hardware, use this setting to give it more time to react\&.
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
very large values for sdtime may create warnings from upsdrvctl if it gets tired of waiting for the driver to return\&.
.sp .5v
.RE
.SH "CUSTOM CONFIGURATIONS"
.sp
You may override the values for CP, OL, LB, and SD by defining them in the \fBups.conf\fR(5) after the upstype setting\&.
.sp
For example, to set the cable power to DTR and the low battery value to DCD, it would look like this:
.sp
.if n \{\
.RS 4
.\}
.nf
CP = DTR
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
LB = DCD
.fi
.if n \{\
.RE
.\}
.sp
Recognized values for input lines are CTS, DCD, and RNG\&. Recognized values for output lines are DTR, RTS, and ST\&. See below for more about what these signals mean\&.
.sp
These values may be negated for active low signals\&. That is, "LB=\-DCD" recognizes a low battery condition when DCD is not held high\&.
.SH "TYPE INFORMATION"
.sp
The essence of a UPS definition in this driver is how it uses the serial lines that are available\&. These are the abbreviations you will see below:
.PP
OL
.RS 4
On line (no power failure) (opposite of OB \- on battery)
.RE
.PP
LB
.RS 4
Low battery
.RE
.PP
SD
.RS 4
Shutdown load
.RE
.PP
CP
.RS 4
Cable power (must be present for cable to have valid reading)
.RE
.PP
CTS
.RS 4
Clear to Send\&. Received from the UPS\&.
.RE
.PP
RTS
.RS 4
Ready to Send\&. Sent by the PC\&.
.RE
.PP
DCD
.RS 4
Data Carrier Detect\&. Received from the UPS\&.
.RE
.PP
RNG
.RS 4
Ring indicate\&. Received from the UPS\&.
.RE
.PP
DTR
.RS 4
Data Terminal Ready\&. Sent by the PC\&.
.RE
.PP
ST
.RS 4
Send a BREAK on the transmit data line
.RE
.sp
A "\-" in front of a signal name (like \-RNG) means that the indicated condition is signaled with an active low signal\&. For example, [LB=\-RNG] means the battery is low when the ring indicate line goes low, and that the battery is OK when that line is held high\&.
.SH "UPS TYPES"
.sp
0 = UPSonic LAN Saver 600
.sp
.if n \{\
.RS 4
.\}
.nf
[CP=DTR+RTS] [OL=\-CTS] [LB=DCD] [SD=DTR]
.fi
.if n \{\
.RE
.\}
.sp
1 = APC Back\-UPS/Back\-UPS Pro/Smart\-UPS with 940\-0095A/C cable
.sp
.if n \{\
.RS 4
.\}
.nf
[CP=DTR] [OL=\-RNG] [LB=DCD] [SD=RTS]
.fi
.if n \{\
.RE
.\}
.sp
2 = APC Back\-UPS/Back\-UPS Pro/Smart\-UPS with 940\-0020B cable
.sp
.if n \{\
.RS 4
.\}
.nf
[CP=RTS] [OL=\-CTS] [LB=DCD] [SD=DTR+RTS]
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
Type 2 has also been reported to work with the 940\-0020C cable\&.
.fi
.if n \{\
.RE
.\}
.sp
3 = PowerTech Comp1000 with DTR cable power
.sp
.if n \{\
.RS 4
.\}
.nf
[CP=DTR] [OL=CTS] [LB=DCD] [SD=DTR+RTS]
.fi
.if n \{\
.RE
.\}
.sp
4 = Generic RUPS Model
.sp
.if n \{\
.RS 4
.\}
.nf
[CP=RTS] [OL=CTS] [LB=\-DCD] [SD=\-RTS]
.fi
.if n \{\
.RE
.\}
.sp
5 = Tripp Lite UPS with Lan2\&.2 interface (black 73\-0844 cable)
.sp
.if n \{\
.RS 4
.\}
.nf
[CP=DTR] [OL=CTS] [LB=\-DCD] [SD=DTR+RTS]
.fi
.if n \{\
.RE
.\}
.sp
6 = Best Patriot with INT51 cable
.sp
.if n \{\
.RS 4
.\}
.nf
[CP=DTR] [OL=CTS] [LB=\-DCD] [SD=RTS]
.fi
.if n \{\
.RE
.\}
.sp
7 = CyberPower Power99 Also Upsonic Power Guardian PG\-500, Belkin Belkin Home Office, F6H350\-SER, F6H500\-SER, F6H650\-SER
.sp
.if n \{\
.RS 4
.\}
.nf
[CP=RTS] [OL=CTS] [LB=\-DCD] [SD=DTR]
.fi
.if n \{\
.RE
.\}
.sp
8 = Nitram Elite 500
.sp
.if n \{\
.RS 4
.\}
.nf
[CP=DTR] [OL=CTS] [LB=\-DCD] [SD=???]
.fi
.if n \{\
.RE
.\}
.sp
9 = APC Back\-UPS/Back\-UPS Pro/Smart\-UPS with 940\-0023A cable
.sp
.if n \{\
.RS 4
.\}
.nf
[CP=none] [OL=\-DCD] [LB=CTS] [SD=RTS]
.fi
.if n \{\
.RE
.\}
.sp
10 = Victron Lite with crack cable
.sp
.if n \{\
.RS 4
.\}
.nf
[CP=RTS] [OL=CTS] [LB=\-DCD] [SD=DTR]
.fi
.if n \{\
.RE
.\}
.sp
11 = Powerware 3115
.sp
.if n \{\
.RS 4
.\}
.nf
[CP=DTR] [OL=\-CTS] [LB=\-DCD] [SD=ST]
.fi
.if n \{\
.RE
.\}
.sp
12 = APC Back\-UPS Office with 940\-0119A cable
.sp
.if n \{\
.RS 4
.\}
.nf
[CP=RTS] [OL=\-CTS] [LB=DCD] [SD=DTR]
.fi
.if n \{\
.RE
.\}
.sp
13 = RPT Repoteck RPT\-800A/RPT\-162A
.sp
.if n \{\
.RS 4
.\}
.nf
[CP=DTR+RTS] [OL=DCD] [LB=\-CTS] [SD=ST]
.fi
.if n \{\
.RE
.\}
.sp
14 = Online P\-series
.sp
.if n \{\
.RS 4
.\}
.nf
[CP=DTR] [OL=DCD] [LB=\-CTS] [SD=RTS]
.fi
.if n \{\
.RE
.\}
.sp
15 = Powerware 5119, 5125
.sp
.if n \{\
.RS 4
.\}
.nf
[CP=DTR] [OL=CTS] [LB=\-DCD] [SD=ST]
.fi
.if n \{\
.RE
.\}
.sp
16 = Nitram Elite 2002
.sp
.if n \{\
.RS 4
.\}
.nf
[CP=DTR+RTS] [OL=CTS] [LB=\-DCD] [SD=???]
.fi
.if n \{\
.RE
.\}
.sp
17 = PowerKinetics 9001
.sp
.if n \{\
.RS 4
.\}
.nf
[CP=DTR] [OL=CTS] [LB=\-DCD] [SD=???]
.fi
.if n \{\
.RE
.\}
.sp
18 = TrippLite Omni 450LAN with Martin\(cqs cabling
.sp
.if n \{\
.RS 4
.\}
.nf
[CP=DTR] [OL=CTS] [LB=DCD] [SD=none]
.fi
.if n \{\
.RE
.\}
.sp
19 = Fideltronic Ares Series
.sp
.if n \{\
.RS 4
.\}
.nf
[CP=DTR] [OL=CTS] [LB=\-DCD] [SD=RTS]
.fi
.if n \{\
.RE
.\}
.sp
20 = Powerware 5119 RM
.sp
.if n \{\
.RS 4
.\}
.nf
[CP=DTR] [OL=\-CTS] [LB=DCD] [SD=ST]
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
Check docs/cables/powerware\&.txt
.fi
.if n \{\
.RE
.\}
.sp
21 = Generic RUPS 2000 (Megatec M2501 cable)
.sp
.if n \{\
.RS 4
.\}
.nf
[CP=RTS] [OL=CTS] [LB=\-DCD] [SD=RTS+DTR]
.fi
.if n \{\
.RE
.\}
.sp
22 = Gamatronic All models with alarm interface (also CyberPower SL series)
.sp
.if n \{\
.RS 4
.\}
.nf
[CP=RTS] [OL=CTS] [LB=\-DCD] [SD=DTR]
.fi
.if n \{\
.RE
.\}
.SH "SIMILAR MODELS"
.sp
Many different UPS companies make models with similar interfaces\&. The RUPS cable seems to be especially popular in the "power strip" variety of UPS found in office supply stores\&. If your UPS works with an entry in the table above, but the model or manufacturer information don\(cqt match, don\(cqt despair\&. You can fix that easily by using the mfr and model variables documented above in your \fBups.conf\fR(5)\&.
.SH "TESTING COMPATIBILITY"
.sp
If your UPS isn\(cqt listed above, you can try going through the list until you find one that works\&. There is a lot of cable and interface reuse in the UPS world, and you may find a match\&.
.sp
To do this, first make sure nothing important is plugged into the outlets on the UPS, as you may inadvertently switch it off\&. Definitely make sure that the computer you\(cqre using is not plugged into that UPS\&. Plug in something small like a lamp so you know when power is being supplied to the outlets\&.
.sp
Now, you can either attempt to make an educated guess based on the documentation your manufacturer has provided (if any), or just start going down the list\&.
.SS "Step 1"
.sp
Pick a driver to try from the list (genericups \-h) and go to step 2\&.
.SS "Step 2"
.sp
Start the driver with the type you want to try \-
.sp
.if n \{\
.RS 4
.\}
.nf
genericups \-x upstype=n /dev/port
.fi
.if n \{\
.RE
.\}
.sp
Let upsd sync up (watch the syslog), and then run upsc to see what it found\&. If the STATUS is right (should be OL for on line), continue to Step 3, otherwise go back to step 1\&.
.sp
Alternatively, you can run genericups in debug mode \-
.sp
.if n \{\
.RS 4
.\}
.nf
genericups \-DDDDD \-x upstype=n /dev/port
.fi
.if n \{\
.RE
.\}
.sp
In this mode it will be running in the foreground and continuously display the line and battery status of the UPS\&.
.SS "Step 3"
.sp
Disconnect the UPS from the wall/mains power\&. This is easiest if you have a switched outlet in between it and the wall, but you can also just pull the plug to test\&. The lamp should stay lit, and the status should switch to "OB"\&. If the lamp went out or the status didn\(cqt go to "OB" within about 15 seconds, go to Step 1\&. Otherwise, continue to Step 4\&.
.SS "Step 4"
.sp
At this point, we know that OL and OB work\&. If nothing else beyond this point works, you at least know what your OL/OB value should be\&.
.sp
Wait for the UPS to start complaining about a low battery\&. Depending on the size of your UPS battery and the lamp\(cqs bulb, this could take awhile\&. It should start complaining audibly at some point\&. When this happens, STATUS should show "OB LB" within 15 seconds\&. If not, go to Step 1, otherwise continue to Step 5\&.
.SS "Step 5"
.sp
So far: OL works, OB works, and LB works\&.
.sp
With the UPS running on battery, run the genericups driver with the \-k switch to shut it down\&.
.sp
.if n \{\
.RS 4
.\}
.nf
genericups \-x upstype=n \-k /dev/port
.fi
.if n \{\
.RE
.\}
.sp
If the UPS turns off the lamp, you\(cqre done\&. At this point, you have verified that the shutdown sequence actually does what you want\&. You can start using the genericups driver with this type number for normal operations\&.
.sp
You should use your findings to add a section to your ups\&.conf\&. Here is a quick example:
.sp
.if n \{\
.RS 4
.\}
.nf
[myups]
driver = genericups
port = /dev/ttyS0
upstype = 1
.fi
.if n \{\
.RE
.\}
.sp
Change the port and upstype values to match your system\&.
.SH "NEW SUPPORT"
.sp
If the above testing sequence fails, you will probably need to create a new entry to support your hardware\&. All UPS types are determined from the table in the genericups\&.h file in the source tree\&.
.sp
On a standard 9 pin serial port, there are 6 lines that are used as the standard "high/low" signal levels\&. 4 of them are incoming (to the PC, from the UPS), and the other 2 are outgoing (to the UPS, from the PC)\&. The other 3 are the receive/transmit lines and the ground\&.
.sp
Be aware that many manufacturers remap pins within the cable\&. If you have any doubts, a quick check with a multimeter should confirm whether the cable is straight\-through or not\&. Another thing to keep in mind is that some cables have electronics in them to do special things\&. Some have resistors and transistors on board to change behavior depending on what\(cqs being supplied by the PC\&.
.SH "SPECIFIC MODEL NOTES"
.sp
These have been contributed by users of this driver\&.
.sp
The Centralion CL series may power down the load if the driver starts up with the UPS running on battery as the default line settings contain the shutdown sequence\&. \- Neil Muller
.sp
The Tripp\-Lite Internet Office 700 must be used with the black 73\-0844 cable instead of the gray 73\-0743 cable\&. This entry should work with any of their models with the Lan 2\&.2 interface \- see the sticker by the DB9 connector on the UPS\&. \- Stephen Brown
.sp
Type 5 should work with the Tripp\-Lite Lan 2\&.1 interface and the 73\-0724 cable\&. This was tested with the OmniSmart 675 PNP on Red Hat 7\&.2\&. \- Q Giese
.sp
Types 7 and 10 should both work with the PhoenixTec A1000\&.
.SH "BUGS"
.sp
There is no way to reliably detect a contact\-closure UPS\&. This means the driver will start up happily even if no UPS is detected\&. It also means that if the connection between the UPS and computer is interrupted, you may not be able to sense this in software\&.
.sp
Most contact\-closure UPSes will not power down the load if the line power is present\&. This can create a race when using slave \fBupsmon\fR(8) systems\&. See the \fBupsmon\fR(8) man page for more information\&.
.sp
The solution to both of these problems is to upgrade to a smart protocol UPS of some kind that allows detection and proper load cycling on command\&.
.SH "SEE ALSO"
.SS "The core driver"
.sp
\fBnutupsdrv\fR(8)
.SS "Internet resources"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/

381
docs/man/genericups.txt Normal file
View file

@ -0,0 +1,381 @@
GENERICUPS(8)
=============
NAME
----
genericups - Driver for contact-closure UPS equipment
NOTE
----
This man page only documents the specific features of the genericups
driver. For information about the core driver, see linkman:nutupsdrv[8].
SUPPORTED HARDWARE
------------------
This driver supports hardware from many different manufacturers as it only
uses the very simplest of signaling schemes. Contact closure refers to a
kind of interface where basic high/low signals are provided to indicate
status. This kind of UPS can only report line power and battery status.
This means that you will only get the essentials in ups.status: OL, OB,
and LB. Anything else requires a smarter UPS.
CABLING
-------
Cabling is different for every kind of UPS. See the table below for
information on what is known to work with a given UPS type.
EXTRA ARGUMENTS
---------------
This driver supports the following settings in the linkman:ups.conf[5]:
upstype='type'::
Required. Configures the driver for a specific kind of UPS. See the
<<_ups_types,UPS Types>> section below for more information on which entries
are available.
mfr='string'::
Optional. The very nature of a generic UPS driver sometimes means that
the stock manufacturer data has no relation to the actual hardware that is
attached. With the `mfr` setting, you can change the value that is seen by
clients that monitor this UPS.
model='string'::
Optional. This is like `mfr` above, but it overrides the model string
instead.
serial='string'::
Optional. This is like `mfr` above and intended to record the identification
string of the UPS. It is titled "serial" because usually this string is
referred to as the serial number.
sdtime='value'::
Optional. The driver will sleep for this many seconds after setting the
shutdown signal. This is necessary for some hardware which requires a
sustained level to activate the shutdown sequence.
+
The default behavior of the driver is to exit immediately. If this
doesn't reliably trigger a shutdown in your UPS hardware, use this
setting to give it more time to react.
NOTE: very large values for +sdtime+ may create warnings from upsdrvctl if
it gets tired of waiting for the driver to return.
CUSTOM CONFIGURATIONS
---------------------
You may override the values for CP, OL, LB, and SD by defining them in
the linkman:ups.conf[5] after the upstype setting.
For example, to set the cable power to DTR and the low battery value to
DCD, it would look like this:
CP = DTR
LB = DCD
Recognized values for input lines are CTS, DCD, and RNG. Recognized
values for output lines are DTR, RTS, and ST. See below for more about
what these signals mean.
These values may be negated for active low signals. That is, "LB=-DCD"
recognizes a low battery condition when DCD is not held high.
TYPE INFORMATION
----------------
The essence of a UPS definition in this driver is how it uses the serial
lines that are available. These are the abbreviations you will see below:
OL:: On line (no power failure) (opposite of OB - on battery)
LB:: Low battery
SD:: Shutdown load
CP:: Cable power (must be present for cable to have valid reading)
CTS:: Clear to Send. Received from the UPS.
RTS:: Ready to Send. Sent by the PC.
DCD:: Data Carrier Detect. Received from the UPS.
RNG:: Ring indicate. Received from the UPS.
DTR:: Data Terminal Ready. Sent by the PC.
ST:: Send a BREAK on the transmit data line
A "-" in front of a signal name (like -RNG) means that the indicated
condition is signaled with an active low signal. For example, [LB=-RNG]
means the battery is low when the ring indicate line goes low, and that
the battery is OK when that line is held high.
UPS TYPES
---------
0 = UPSonic LAN Saver 600
[CP=DTR+RTS] [OL=-CTS] [LB=DCD] [SD=DTR]
1 = APC Back-UPS/Back-UPS Pro/Smart-UPS with 940-0095A/C cable
[CP=DTR] [OL=-RNG] [LB=DCD] [SD=RTS]
2 = APC Back-UPS/Back-UPS Pro/Smart-UPS with 940-0020B cable
[CP=RTS] [OL=-CTS] [LB=DCD] [SD=DTR+RTS]
Type 2 has also been reported to work with the 940-0020C cable.
3 = PowerTech Comp1000 with DTR cable power
[CP=DTR] [OL=CTS] [LB=DCD] [SD=DTR+RTS]
4 = Generic RUPS Model
[CP=RTS] [OL=CTS] [LB=-DCD] [SD=-RTS]
5 = Tripp Lite UPS with Lan2.2 interface (black 73-0844 cable)
[CP=DTR] [OL=CTS] [LB=-DCD] [SD=DTR+RTS]
6 = Best Patriot with INT51 cable
[CP=DTR] [OL=CTS] [LB=-DCD] [SD=RTS]
7 = CyberPower Power99
Also Upsonic Power Guardian PG-500, Belkin Belkin Home Office,
F6H350-SER, F6H500-SER, F6H650-SER
[CP=RTS] [OL=CTS] [LB=-DCD] [SD=DTR]
8 = Nitram Elite 500
[CP=DTR] [OL=CTS] [LB=-DCD] [SD=???]
9 = APC Back-UPS/Back-UPS Pro/Smart-UPS with 940-0023A cable
[CP=none] [OL=-DCD] [LB=CTS] [SD=RTS]
10 = Victron Lite with crack cable
[CP=RTS] [OL=CTS] [LB=-DCD] [SD=DTR]
11 = Powerware 3115
[CP=DTR] [OL=-CTS] [LB=-DCD] [SD=ST]
12 = APC Back-UPS Office with 940-0119A cable
[CP=RTS] [OL=-CTS] [LB=DCD] [SD=DTR]
13 = RPT Repoteck RPT-800A/RPT-162A
[CP=DTR+RTS] [OL=DCD] [LB=-CTS] [SD=ST]
14 = Online P-series
[CP=DTR] [OL=DCD] [LB=-CTS] [SD=RTS]
15 = Powerware 5119, 5125
[CP=DTR] [OL=CTS] [LB=-DCD] [SD=ST]
16 = Nitram Elite 2002
[CP=DTR+RTS] [OL=CTS] [LB=-DCD] [SD=???]
17 = PowerKinetics 9001
[CP=DTR] [OL=CTS] [LB=-DCD] [SD=???]
18 = TrippLite Omni 450LAN with Martin's cabling
[CP=DTR] [OL=CTS] [LB=DCD] [SD=none]
19 = Fideltronic Ares Series
[CP=DTR] [OL=CTS] [LB=-DCD] [SD=RTS]
20 = Powerware 5119 RM
[CP=DTR] [OL=-CTS] [LB=DCD] [SD=ST]
Check docs/cables/powerware.txt
21 = Generic RUPS 2000 (Megatec M2501 cable)
[CP=RTS] [OL=CTS] [LB=-DCD] [SD=RTS+DTR]
22 = Gamatronic All models with alarm interface
(also CyberPower SL series)
[CP=RTS] [OL=CTS] [LB=-DCD] [SD=DTR]
SIMILAR MODELS
--------------
Many different UPS companies make models with similar interfaces. The
RUPS cable seems to be especially popular in the "power strip" variety of
UPS found in office supply stores. If your UPS works with an entry in the
table above, but the model or manufacturer information don't match,
don't despair. You can fix that easily by using the mfr and model
variables documented above in your linkman:ups.conf[5].
TESTING COMPATIBILITY
---------------------
If your UPS isn't listed above, you can try going through the list until
you find one that works. There is a lot of cable and interface reuse in
the UPS world, and you may find a match.
To do this, first make sure nothing important is plugged into the
outlets on the UPS, as you may inadvertently switch it off. Definitely
make sure that the computer you're using is not plugged into that UPS.
Plug in something small like a lamp so you know when power is being
supplied to the outlets.
Now, you can either attempt to make an educated guess based on the
documentation your manufacturer has provided (if any), or just start
going down the list.
Step 1
~~~~~~
Pick a driver to try from the list (genericups -h) and go to step 2.
Step 2
~~~~~~
Start the driver with the type you want to try -
genericups -x upstype=n /dev/port
Let upsd sync up (watch the syslog), and then run upsc to see what it
found. If the STATUS is right (should be OL for on line), continue to
<<_step_3,Step 3>>, otherwise go back to step 1.
Alternatively, you can run genericups in debug mode -
genericups -DDDDD -x upstype=n /dev/port
In this mode it will be running in the foreground and continuously
display the line and battery status of the UPS.
Step 3
~~~~~~
Disconnect the UPS from the wall/mains power. This is easiest if you
have a switched outlet in between it and the wall, but you can also just
pull the plug to test. The lamp should stay lit, and the status should
switch to "OB". If the lamp went out or the status didn't go to "OB"
within about 15 seconds, go to <<_step_1,Step 1>>. Otherwise, continue
to <<_step_4,Step 4>>.
Step 4
~~~~~~
At this point, we know that OL and OB work. If nothing else beyond
this point works, you at least know what your OL/OB value should be.
Wait for the UPS to start complaining about a low battery. Depending on
the size of your UPS battery and the lamp's bulb, this could take
awhile. It should start complaining audibly at some point. When this
happens, STATUS should show "OB LB" within 15 seconds. If not, go to
<<_step_1,Step 1>>, otherwise continue to <<_step_5,Step 5>>.
Step 5
~~~~~~
So far: OL works, OB works, and LB works.
With the UPS running on battery, run the genericups driver with the -k
switch to shut it down.
genericups -x upstype=n -k /dev/port
If the UPS turns off the lamp, you're done. At this point, you have
verified that the shutdown sequence actually does what you want. You
can start using the genericups driver with this type number for normal
operations.
You should use your findings to add a section to your ups.conf.
Here is a quick example:
[myups]
driver = genericups
port = /dev/ttyS0
upstype = 1
Change the port and upstype values to match your system.
NEW SUPPORT
-----------
If the above testing sequence fails, you will probably need to create a
new entry to support your hardware. All UPS types are determined from the
table in the genericups.h file in the source tree.
On a standard 9 pin serial port, there are 6 lines that are used as the
standard "high/low" signal levels. 4 of them are incoming (to the PC,
from the UPS), and the other 2 are outgoing (to the UPS, from the PC).
The other 3 are the receive/transmit lines and the ground.
Be aware that many manufacturers remap pins within the cable. If you have
any doubts, a quick check with a multimeter should confirm whether the
cable is straight-through or not. Another thing to keep in mind is that
some cables have electronics in them to do special things. Some have
resistors and transistors on board to change behavior depending on what's
being supplied by the PC.
SPECIFIC MODEL NOTES
--------------------
These have been contributed by users of this driver.
The Centralion CL series may power down the load if the driver starts up
with the UPS running on battery as the default line settings contain the
shutdown sequence. - Neil Muller
The Tripp-Lite Internet Office 700 must be used with the black 73-0844
cable instead of the gray 73-0743 cable. This entry should work with any
of their models with the Lan 2.2 interface - see the sticker by the DB9
connector on the UPS. - Stephen Brown
Type 5 should work with the Tripp-Lite Lan 2.1 interface and the 73-0724
cable. This was tested with the OmniSmart 675 PNP on Red Hat 7.2. - Q
Giese
Types 7 and 10 should both work with the PhoenixTec A1000.
BUGS
----
There is no way to reliably detect a contact-closure UPS. This means the
driver will start up happily even if no UPS is detected. It also means
that if the connection between the UPS and computer is interrupted, you
may not be able to sense this in software.
Most contact-closure UPSes will not power down the load if the line power
is present. This can create a race when using slave linkman:upsmon[8]
systems. See the linkman:upsmon[8] man page for more information.
The solution to both of these problems is to upgrade to a smart protocol
UPS of some kind that allows detection and proper load cycling on command.
SEE ALSO
--------
The core driver
~~~~~~~~~~~~~~~
linkman:nutupsdrv[8]
Internet resources
~~~~~~~~~~~~~~~~~~
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/

61
docs/man/hosts.conf.5 Normal file
View file

@ -0,0 +1,61 @@
'\" t
.\" Title: hosts.conf
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 12/24/2010
.\" Manual: NUT Manual
.\" Source: Network UPS Tools
.\" Language: English
.\"
.TH "HOSTS\&.CONF" "5" "12/24/2010" "Network UPS Tools" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
hosts.conf \- Access control for Network UPS Tools CGI programs
.SH "DESCRIPTION"
.sp
The CGI programs (\fBupsset.cgi\fR(8), \fBupsstats.cgi\fR(8), \fBupsimage.cgi\fR(8)) use this file to determine if they are allowed to talk to a host\&. This keeps random visitors from using your web server to annoy others by creating outgoing connections\&.
.SH "DIRECTIVES"
.PP
\fBMONITOR\fR \fIups\fR \fIdescription\fR
.RS 4
The
\fIups\fR
element is in the form
upsname[@hostname[:port]]\&. To allow connections to a UPS called "snoopy" on a system called "doghouse" that runs upsd on port 7877, it would look like this:
.sp
.if n \{\
.RS 4
.\}
.nf
MONITOR snoopy@doghouse:7877 "Joe Cool"
.fi
.if n \{\
.RE
.\}
.sp
The description must be one element, so if it has spaces, then it must be wrapped with quotes as shown above\&. The default hostname is "localhost"\&.
.RE
.SH "SEE ALSO"
.sp
\fBupsset.cgi\fR(8), \fBupsstats.cgi\fR(8), \fBupsimage.cgi\fR(8)
.SS "Internet resources:"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/

39
docs/man/hosts.conf.txt Normal file
View file

@ -0,0 +1,39 @@
HOSTS.CONF(5)
=============
NAME
----
hosts.conf - Access control for Network UPS Tools CGI programs
DESCRIPTION
-----------
The CGI programs (linkman:upsset.cgi[8], linkman:upsstats.cgi[8],
linkman:upsimage.cgi[8]) use this file to determine if they are allowed to
talk to a host. This keeps random visitors from using your web server
to annoy others by creating outgoing connections.
DIRECTIVES
----------
*MONITOR* 'ups' 'description'::
The 'ups' element is in the form `upsname[@hostname[:port]]`.
To allow connections to a UPS called "snoopy" on a system called
"doghouse" that runs upsd on port 7877, it would look like this:
MONITOR snoopy@doghouse:7877 "Joe Cool"
+
The description must be one element, so if it has spaces, then it must
be wrapped with quotes as shown above. The default hostname is
"localhost".
SEE ALSO
--------
linkman:upsset.cgi[8], linkman:upsstats.cgi[8], linkman:upsimage.cgi[8]
Internet resources:
~~~~~~~~~~~~~~~~~~~
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/

50
docs/man/isbmex.8 Normal file
View file

@ -0,0 +1,50 @@
'\" t
.\" Title: isbmex
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 12/24/2010
.\" Manual: NUT Manual
.\" Source: Network UPS Tools
.\" Language: English
.\"
.TH "ISBMEX" "8" "12/24/2010" "Network UPS Tools" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
isbmex \- Driver for ISBMEX UPS equipment
.SH "NOTE"
.sp
This man page only documents the hardware\-specific features of the isbmex driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
.SH "SUPPORTED HARDWARE"
.sp
This driver supports SOLA/BASIC Mexico ISBMEX protocol UPS equipment\&.
.SH "EXTRA ARGUMENTS"
.sp
This driver does not support any extra settings in the \fBups.conf\fR(5)\&.
.SH "AUTHOR"
.sp
Edscott Wilson Garcia <edscott@imp\&.mx>
.SH "SEE ALSO"
.SS "The core driver:"
.sp
\fBnutupsdrv\fR(8)
.SS "Internet resources:"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/

39
docs/man/isbmex.txt Normal file
View file

@ -0,0 +1,39 @@
ISBMEX(8)
=========
NAME
----
isbmex - Driver for ISBMEX UPS equipment
NOTE
----
This man page only documents the hardware-specific features of the
isbmex driver. For information about the core driver, see
linkman:nutupsdrv[8].
SUPPORTED HARDWARE
------------------
This driver supports SOLA/BASIC Mexico ISBMEX protocol UPS equipment.
EXTRA ARGUMENTS
---------------
This driver does not support any extra settings in the
linkman:ups.conf[5].
AUTHOR
------
Edscott Wilson Garcia <edscott@imp.mx>
SEE ALSO
--------
The core driver:
~~~~~~~~~~~~~~~~
linkman:nutupsdrv[8]
Internet resources:
~~~~~~~~~~~~~~~~~~~
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/

50
docs/man/ivtscd.8 Normal file
View file

@ -0,0 +1,50 @@
'\" t
.\" Title: ivtscd
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 12/24/2010
.\" Manual: NUT Manual
.\" Source: Network UPS Tools
.\" Language: English
.\"
.TH "IVTSCD" "8" "12/24/2010" "Network UPS Tools" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ivtscd \- driver for the IVT Solar Controller Device
.SH "NOTE"
.sp
This man page only documents the hardware\-specific features of the \fBivtscd\fR driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
.SH "DESCRIPTION"
.sp
This driver allows to access the IVT SCD\-series devices\&.
.SH "EXTRA ARGUMENTS"
.sp
This driver does not support any extra argument\&.
.SH "AUTHOR"
.sp
Arjen de Korte <adkorte\-guest@alioth\&.debian\&.org>
.SH "SEE ALSO"
.SS "The core driver:"
.sp
\fBnutupsdrv\fR(8)
.SS "Internet resources:"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/

34
docs/man/ivtscd.txt Normal file
View file

@ -0,0 +1,34 @@
IVTSCD(8)
=========
NAME
----
ivtscd - driver for the IVT Solar Controller Device
NOTE
----
This man page only documents the hardware-specific features of the
*ivtscd* driver. For information about the core driver, see
linkman:nutupsdrv[8].
DESCRIPTION
-----------
This driver allows to access the IVT SCD-series devices.
EXTRA ARGUMENTS
---------------
This driver does not support any extra argument.
AUTHOR
------
Arjen de Korte <adkorte-guest@alioth.debian.org>
SEE ALSO
--------
The core driver:
~~~~~~~~~~~~~~~~
linkman:nutupsdrv[8]
Internet resources:
~~~~~~~~~~~~~~~~~~~
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/

70
docs/man/libupsclient-config.1 Normal file
View file

@ -0,0 +1,70 @@
'\" t
.\" Title: libupsclient-config
.\" Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 12/24/2010
.\" Manual: NUT Manual
.\" Source: Network UPS Tools
.\" Language: English
.\"
.TH "LIBUPSCLIENT\-CONFIG" "1" "12/24/2010" "Network UPS Tools" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
libupsclient-config \- script to get information about the installed version of libupsclient
.SH "SYNOPSIS"
.sp
\fBlibupsclient\-config\fR [\-\-version] [\-\-libs] [\-\-cflags]
.SH "DESCRIPTION"
.sp
\fBlibupsclient\-config\fR is a tool that is used to determine the compiler and linker flags that should be used to compile and link programs that use \fBlibupsclient\fR from the Network UPS Tools project\&.
.SH "OPTIONS"
.sp
\fBlibupsclient\-config\fR accepts the following options:
.PP
\fB\-\-version\fR
.RS 4
Print the currently installed version of
\fBlibupsclient\fR
on the standard output\&.
.RE
.PP
\fB\-\-libs\fR
.RS 4
Print the linker flags that are necessary to link a
\fBlibupsclient\fR
program\&.
.RE
.PP
\fB\-\-cflags\fR
.RS 4
Print the compiler flags that are necessary to compile a
\fBlibupsclient\fR
program\&.
.RE
.SH "AUTHORS"
.sp
This manual page was written by Arnaud Quette <aquette\&.dev@gmail\&.com>\&.
.SH "SEE ALSO"
.sp
\fBupsclient\fR(3)
.SS "Internet resources:"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/

46
docs/man/libupsclient-config.txt Normal file
View file

@ -0,0 +1,46 @@
LIBUPSCLIENT-CONFIG(1)
======================
NAME
----
libupsclient-config - script to get information about the installed version of libupsclient
SYNOPSIS
--------
*libupsclient-config* [--version] [--libs] [--cflags]
DESCRIPTION
-----------
*libupsclient-config* is a tool that is used to determine the compiler and
linker flags that should be used to compile and link programs that use
*libupsclient* from the Network UPS Tools project.
OPTIONS
-------
*libupsclient-config* accepts the following options:
*--version*::
Print the currently installed version of *libupsclient* on the standard output.
*--libs*::
Print the linker flags that are necessary to link a *libupsclient* program.
*--cflags*::
Print the compiler flags that are necessary to compile a *libupsclient* program.
AUTHORS
-------
This manual page was written by Arnaud Quette <aquette.dev@gmail.com>.
SEE ALSO
--------
linkman:upsclient[3]
Internet resources:
~~~~~~~~~~~~~~~~~~~
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/

55
docs/man/liebert-esp2.8 Normal file
View file

@ -0,0 +1,55 @@
'\" t
.\" Title: liebert-esp2
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 12/24/2010
.\" Manual: NUT Manual
.\" Source: Network UPS Tools
.\" Language: English
.\"
.TH "LIEBERT\-ESP2" "8" "12/24/2010" "Network UPS Tools" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
liebert-esp2 \- Driver for Liebert UPS, using the ESP\-II serial protocol
.SH "NOTE"
.sp
This man page only documents the hardware\-specific features of the liebert\-esp2 driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
.SH "SUPPORTED HARDWARE"
.sp
This is an experimental driver\&. You have been warned\&.
.SH "EXTRA ARGUMENTS"
.sp
This driver supports the following optional settings in \fBups.conf\fR(5):
.PP
\fBbaudrate=\fR\fInum\fR
.RS 4
Set the speed of the serial connection \- 1200, 2400 (default), 4800, 9600 or 19200\&.
.RE
.SH "AUTHOR"
.sp
Richard Gregory <R\&.Gregory at liverpool\&.ac\&.uk>, Arjen de Korte <adkorte\-guest at alioth\&.debian\&.org>
.SH "SEE ALSO"
.SS "The core driver:"
.sp
\fBnutupsdrv\fR(8)
.SS "Internet resources:"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/

40
docs/man/liebert-esp2.txt Normal file
View file

@ -0,0 +1,40 @@
LIEBERT-ESP2(8)
==============
NAME
----
liebert-esp2 - Driver for Liebert UPS, using the ESP-II serial protocol
NOTE
----
This man page only documents the hardware-specific features of the
liebert-esp2 driver. For information about the core driver, see
linkman:nutupsdrv[8].
SUPPORTED HARDWARE
------------------
This is an experimental driver. You have been warned.
EXTRA ARGUMENTS
---------------
This driver supports the following optional settings in linkman:ups.conf[5]:
*baudrate=*'num'::
Set the speed of the serial connection - 1200, 2400 (default), 4800, 9600 or 19200.
AUTHOR
------
Richard Gregory <R.Gregory at liverpool.ac.uk>, Arjen de Korte <adkorte-guest at alioth.debian.org>
SEE ALSO
--------
The core driver:
~~~~~~~~~~~~~~~~
linkman:nutupsdrv[8]
Internet resources:
~~~~~~~~~~~~~~~~~~~
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/

52
docs/man/liebert.8 Normal file
View file

@ -0,0 +1,52 @@
'\" t
.\" Title: liebert
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 12/24/2010
.\" Manual: NUT Manual
.\" Source: Network UPS Tools
.\" Language: English
.\"
.TH "LIEBERT" "8" "12/24/2010" "Network UPS Tools" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
liebert \- Driver for Liebert contact\-closure UPS equipment
.SH "NOTE"
.sp
This man page only documents the hardware\-specific features of the liebert driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
.SH "SUPPORTED HARDWARE"
.sp
This driver supports some Liebert UPS equipment with a contact\-closure interface\&. This includes the UPStation GXT2 with their contact\-closure cable\&. The smart mode ("Multilink") cable is not supported by this driver\&.
.SH "EXTRA ARGUMENTS"
.sp
This driver does not support any extra settings in the \fBups.conf\fR(5)\&.
.SH "BUGS"
.sp
This driver does not yet support shutdowns by raising DTR\&. Be aware that shutdowns are not possible with the stock contact\-closure cable\&. You may have to build another cable with DTR connected through to the UPS for it to work\&.
.sp
There is no way for this driver to detect the hardware or cable\&. It will start up successfully even if no UPS is present\&. This is a fundamental limitation of any contact\-closure driver\&.
.SH "SEE ALSO"
.SS "The core driver:"
.sp
\fBnutupsdrv\fR(8)
.SS "Internet resources:"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/

49
docs/man/liebert.txt Normal file
View file

@ -0,0 +1,49 @@
LIEBERT(8)
==========
NAME
----
liebert - Driver for Liebert contact-closure UPS equipment
NOTE
----
This man page only documents the hardware-specific features of the
liebert driver. For information about the core driver, see
linkman:nutupsdrv[8].
SUPPORTED HARDWARE
------------------
This driver supports some Liebert UPS equipment with a contact-closure
interface. This includes the UPStation GXT2 with their contact-closure
cable. The smart mode ("Multilink") cable is not supported by this
driver.
EXTRA ARGUMENTS
---------------
This driver does not support any extra settings in the
linkman:ups.conf[5].
BUGS
----
This driver does not yet support shutdowns by raising DTR. Be aware
that shutdowns are not possible with the stock contact-closure cable.
You may have to build another cable with DTR connected through to the
UPS for it to work.
There is no way for this driver to detect the hardware or cable. It
will start up successfully even if no UPS is present. This is a
fundamental limitation of any contact-closure driver.
SEE ALSO
--------
The core driver:
~~~~~~~~~~~~~~~~
linkman:nutupsdrv[8]
Internet resources:
~~~~~~~~~~~~~~~~~~~
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/

53
docs/man/masterguard.8 Normal file
View file

@ -0,0 +1,53 @@
'\" t
.\" Title: masterguard
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 12/24/2010
.\" Manual: NUT Manual
.\" Source: Network UPS Tools
.\" Language: English
.\"
.TH "MASTERGUARD" "8" "12/24/2010" "Network UPS Tools" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
masterguard \- Driver for Masterguard UPS equipment
.SH "NOTE"
.sp
This man page only documents the hardware\-specific features of the masterguard driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
.SH "SUPPORTED HARDWARE"
.sp
This driver supports Masterguard UPS equipment\&.
.SH "EXTRA ARGUMENTS"
.PP
\fBCS\fR
.RS 4
Cancel the shutdown procedure\&.
.RE
.SH "AUTHOR"
.sp
Michael Spanier <mail@michael\-spanier\&.de>
.SH "SEE ALSO"
.SS "The core driver:"
.sp
\fBnutupsdrv\fR(8)
.SS "Internet resources:"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/

37
docs/man/masterguard.txt Normal file
View file

@ -0,0 +1,37 @@
MASTERGUARD(8)
==============
NAME
----
masterguard - Driver for Masterguard UPS equipment
NOTE
----
This man page only documents the hardware-specific features of the
masterguard driver. For information about the core driver, see
linkman:nutupsdrv[8].
SUPPORTED HARDWARE
------------------
This driver supports Masterguard UPS equipment.
EXTRA ARGUMENTS
---------------
*CS*::
Cancel the shutdown procedure.
AUTHOR
------
Michael Spanier <mail@michael-spanier.de>
SEE ALSO
--------
The core driver:
~~~~~~~~~~~~~~~~
linkman:nutupsdrv[8]
Internet resources:
~~~~~~~~~~~~~~~~~~~
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/

137
docs/man/metasys.8 Normal file
View file

@ -0,0 +1,137 @@
'\" t
.\" Title: metasys
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 12/24/2010
.\" Manual: NUT Manual
.\" Source: Network UPS Tools
.\" Language: English
.\"
.TH "METASYS" "8" "12/24/2010" "Network UPS Tools" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
metasys \- Driver for Meta System UPS equipment
.SH "NOTE"
.sp
This man page only documents the hardware\-specific features of the metasys driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
.SH "SUPPORTED HARDWARE"
.sp
The \fBmetasys\fR driver was written with the "Meta System UPS Protocol Rev\&.1\&.12" kindly supplied from Meta System\&.
.sp
The driver should support all the common features of the ups models:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
HF Line (/2) 1\-8 boards
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
HF Millennium (810, 820)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
HF TOP Line (910, 920, 930, 940, 950, 970, 980)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
ECO Network (750, 1000, 1050, 1500, 1800, 2000, 2100, 2500, 3000)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
ECO (305, 308, 311, 511, 516, 519, 522, SX, SXI)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
ally HF (800, 1000, 1250, 1600, 2000, 2500)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Megaline (1250, 2500, 3750, 5000, 6250, 7500, 8750, 10000)
.RE
.SH "CABLING"
.sp
The needed cable is a standard pin\-to\-pin serial cable with at least pins 2, 3, and 5 (on DB9 connector) connected\&.
.SH "EXTRA ARGUMENTS"
.sp
This driver supports no extra arguments from \fBups.conf\fR(5)\&.
.SH "BUGS"
.sp
This driver has been tested on Meta System HF Millennium 820 and ally HF 1000 only\&.
.sp
Any informations about the use of the driver with the other listed UPS are really welcome\&.
.SH "AUTHOR"
.sp
Fabio Di Niro <blaxwan@users\&.sourceforge\&.net>
.SH "SEE ALSO"
.SS "The core driver:"
.sp
\fBnutupsdrv\fR(8)
.SS "Internet resources:"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/

Some files were not shown because too many files have changed in this diff Show more