Name: Frequently Asked Questions
File: FAQ
Date: 20 March 2002
Auth: Russell Kroll <rkroll@exploits.org>

-----------------------------------------------------------------------------

 Q: My UPS driver program has started printing a warning that says it 
    will be removed from the tree.  What gives?

 Q: My UPS driver is warning about "old style driver detected", so
    what's the deal?

 A: That driver is old, and nobody has converted it to the new style
    that can use ups.conf and upsdrvctl, so it needs to die.

    Short version: unless someone converts that driver, it will not
    appear in any future releases.  That's called progress.  This is
    being done to get rid of a lot of old compatability hacks in the
    code.

    Long version: main.c (the core of all new/converted drivers) was
    introduced in March 2001 during the 0.45.0-pre development cycle.
    Any driver that hasn't been converted yet probably hasn't been
    maintained in at least a year, and that's dubious all by itself.

    To ensure that your favorite driver remains in the current
    releases, you need to convert it yourself or get someone to do it
    for you.  This isn't very hard - look at skel.c and some of the
    smaller drivers (fentonups, among others) to see how it's done.
    The basic idea is that you rip out main, rename a few functions to
    upsdrv_* where needed, and provide a few new ones to fill out
    the interface.  That's it.  The hard part of decoding the protocol
    has already been done for you in the original driver.

    Even though this will probably cut the number of supported UPSes in
    half, it needs to be done.  If the driver hasn't been touched in a
    year or more, that claim of "support" wasn't exactly stable in the
    first place.

-----------------------------------------------------------------------------

 Q: My UPS driver program (apcsmart, genericups, hidups, sec, etc.) says
    "Unable to open /dev/ttyxx".  I'm starting it as root and root owns
    the device, so why doesn't it work?

 A: The model 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.54 (0.45.0-pre5)
	This program is currently running as rkroll (UID 1000)
	/dev/ttyS2 is owned by user root (UID 0), mode 0660

	Change the port name, or fix the permissions or ownership
	of /dev/ttyS2 and try again.

	Unable to open /dev/ttyS2: Permission denied

    Giving "nobody" access to your raw UPS serial port probably isn't
    the best thing for all systems.  In this case, consider making a 
    new role account called "ups" or similar.

    Better yet, scroll down to the "security domains" question for a
    much better way to restrict privileged operations.  You actually never
    need to start the model drivers or upsd as root, and that answer
    tells you how to do it.

-----------------------------------------------------------------------------

 Q: upsc, multimon, and the other clients give me "access denied".  The
    serial port permissions are fine, so what gives?

 A: Those programs only talk over the network.  That denied message is
    coming over it from upsd.  It's denying them since they don't have
    permission to talk to it according to the access controls.

    The fix is to edit the upsd.conf to allow those hosts to do what they
    need.  Simple read-only clients like upsstats.cgi and upsc only need
    "monitor" level access to work.  upsmon in slave mode needs "login",
    and upsmon in master mode needs (you guessed it) "master".

    If you are getting this error from the programs that request a login
    name or password (upsct2, upscmd, upsset.cgi), then make sure your
    account is properly defined in upsd.users.

    If you're running upsd from version 0.45.3 or newer, then you can
    do 'upsd -c reload' or kill -HUP <pid of upsd> to make it reload
    the config files without restarting the process.

-----------------------------------------------------------------------------

 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 with the apcsmart driver.  If you
    have this cable, you need to start apcsmart with something like this:

	apcsmart -x cable=940-0095B /dev/whatever

    The other solution is to put the "cable = 940-0095B" in your ups.conf
    section for this UPS and let upsdrvctl start it for you.

    The '-x cable' scheme also applies to the newapc driver.

    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.exploits.org/nut/library/940-0024C.jpg

    That should give you a workable 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: configure tells me to go get gd, but I have it installed!  Why isn't it
    finding the one I installed?

 A: Chances are, you have installed gd 1.6 (or higher) which includes PNG
    support and totally eliminates GIF.  But, you don't have the PNG libs
    on your system, so gd didn't compile them in.  So, you need to go get
    libpng, install that, recompile gd, THEN rerun configure.

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

 A: It seems like everyone and their brother has a different place for
    installing the gd includes and libraries.  If your system uses some
    bizarre location for these files, be sure to set the CPPFLAGS and CFLAGS
    accordingly with -L and -I arguments so that the linker and compiler
    can find everything.

-----------------------------------------------------------------------------

 Q: gd can't find zlib.h, so what do I do now?

 A: Go get zlib, install it, then try building gd again.

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

-----------------------------------------------------------------------------

 Q: Now gd can't find png.h, so what do I need this time?

 A: libpng.  Get it, install it, and then start the gd make again...

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

-----------------------------------------------------------------------------

 Q: libpng doesn't seem to have a Makefile, so how do I build it on my
    Linux box?

 A: Besides "RTFM", perhaps you should do copy scripts/makefile.linux to
    Makefile (in the libpng directory) and then try it again.

-----------------------------------------------------------------------------

 Q: OK, I built libpng and gd, so why is configure saying "no (cached)"
    for the gdImagePng detection line?

 A: configure is being a bit too clever for its own good.  rm config.cache
    and try it again.  Then it will figure out how things are set up now.

-----------------------------------------------------------------------------

 Q: My web browser used to be able to show the graphs, but then I upgraded
    NUT and it stopped.  Why?

 A: Some older browsers can't handle PNGs, and upsimage.cgi now uses those 
    exclusively.  You can either upgrade to a version that handles the PNG 
    format or hack the upsimage code to use an older version of gd.

    You really should find a newer browser, as GIF support has been dead
    for quite some time now.

    See http://www.burnallgifs.org/ for more information on this change.

-----------------------------------------------------------------------------

 Q: What about Y2K compliance and this software?

 A: That's pretty much a moot point now, isn't it?

    No problems were reported.

    As for 2038, well, that's another story.

-----------------------------------------------------------------------------

  Q: My upsstats pages now have broken images where the bars used to be,
     and running upsimage.cgi by hand gives me something about libgd.so.0
     not being found.  How do I fix this?

  A: There was at least one version of gd in the past which built shared
     libraries.  Recent versions appear to have dumped configure and have
     a simple build process again.  Try upgrading gd if you want to be
     current.

     If your version is really using shared libraries, run ldconfig or
     its equivalent to rebuild the cache.  Then it should work.

-----------------------------------------------------------------------------

  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
     (model 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.

-----------------------------------------------------------------------------

  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 bestfort talk to my Best Fortress UPS?

  Q: Why won't bestups talk to my Best Fortress UPS?

  A: bestfort handles some older / "traditional" models that tend to be
     black.  bestups is designed around the somewhat newer "PhoenixTec"
     protocol that seems to be associated with beige units.  If one model
     driver doesn't work, try the other one.

-----------------------------------------------------------------------------

  Q: Why do upsc (or any of the client programs) say "no such variable"
     when I try to run them?

  A: Usually this means that upsd has no data available for that UPS.
     Check your ups.conf and make sure that you have defined entries
     that make sense for the driver(s) that you are running.

-----------------------------------------------------------------------------

  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"

     - Hack the cable between the power supply and the motherboard to fool
       it into powering up whenever line power is present

     - Buy a monkey to watch for power outages and press the power button
       when it returns, thus bringing the machine online again.

       This can work, but eventually leads to 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: I want to keep the model 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

     Start the model driver(s) with su, like so:

     # su nutdev -c "/usr/local/ups/bin/apcsmart /dev/ttyS0"
     # su nutdev -c "/usr/local/ups/bin/fentonups /dev/ttyS1"

     The listing for /var/state/ups then looks like this:

     4 drwxr-xr-x   2 nutdev   nut          4096 Aug 20 18:37 .
     4 drwxr-xr-x   4 root     root         4096 May 14 21:20 ..
     4 -rw-r-----   1 nutdev   nut            44 Sep  3 17:10 apcsmart-ttyS0
     4 -rw-r-----   1 nutdev   nut            44 Sep  3 17:10 fentonups-ttyS1

     You may have to remove old state files first if you are changing to
     this security scheme from an older install.  The drivers will create
     new ones with the right ownership and modes.

     You will probably have to change the ownership of upsd.conf and 
     upsd.users since upsd will no longer start as root.  Once you get
     them changed over to being accessible by nutsrv, start upsd:

     # su nutsrv -c "/usr/local/ups/sbin/upsd"

     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.   

     *** Big fat warning: if you use this scheme, you HAVE to use it
         every time you start the programs.  This goes for startup and
         shutdown.  Every time you call upsdrvctl or a driver directly,
         you have to do the "su user -c ..." scheme to make sure it
         starts as the correct user.

         Don't forget to edit your shutdown scripts.  If the driver can't
         open the port, your UPS won't be able to power off at the end
         of the sequence.

     By the way, upsdrvctl will work just fine with this setup, and is
     even easier to use since you only need one line in your start up
     scripts no matter how many UPSes you have or what they are, i.e.:

	su nutdev -c "/usr/local/ups/bin/upsdrvctl start"

     In your shutdown script, you just call it this way:

	su nutdev -c "/usr/local/ups/bin/upsdrvctl shutdown"

-----------------------------------------------------------------------------

  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.

     It also has the nice side effect that the model drivers and upsd
     *never* have root permissions, even when started at boot-time.  Since
     they don't need it, there is no reason to let them have it, even
     briefly.

     There is also the possibility of running the model 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 data to the programs and annoying others via 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.

-----------------------------------------------------------------------------

  Q: Occasionally there are nebulous references to "the big todo list".
     Where can I see it and what's on it?

  A: There is such a file, but it contains lots of things that may never
     come to fruition.  Since I don't like to play the vaporware game, 
     this file stays low-key and away from prying eyes.

     If you want to know what's coming up, watch the release announcements.
     Each one shows the next phase of development plus some general 
     information on the step after that.

-----------------------------------------------------------------------------

  Q: Why does upsd complain about "shmctl failed: permission denied"?

  A: If you're using the 'security domains' startup method with su -c
     (see above), then you always have to start upsd in that way after
     that point.

     Otherwise, upsd starts as root, then switches to whatever was 
     compiled in (typically 'nobody') and that usually doesn't belong
     to the right group, so you can't get to the shared memory struct.

-----------------------------------------------------------------------------

  Q: upsd is running, so why can't I connect to port 3305?

  A: Assuming you haven't changed the port on the command line or at
     compile-time, then you probably have some sort of firewall blocking
     the connection.

     When securing port 3305, remember that upsd runs both TCP and UDP
     listeners.

-----------------------------------------------------------------------------

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

     Note: if signalling upsmon manually, make sure you hit the 
     unprivileged process and not the one running as root.

-----------------------------------------------------------------------------

  Q: I just bought a new WhizBang UPS that has a USB connector.  How do
     I monitor it?

  A: If you're using a very new version of Linux that has hiddev support
     or just happen to have the hiddev patches applied and working, you're
     in luck.  On any other system or an older Linux kernel, there's
     nothing for you just yet.

     CONFIG_USB_HIDDEV has finally appeared as a real configuration
     option in Linux 2.4.13.  Any version after this one (including the
     new 2.5 series) should have it available without any special
     hacks.

     First you need to point configure at your hiddev.h file.  If it
     happens to be in /usr/src/linux/include/linux/hiddev.h, then you
     don't need to do anything.  Otherwise, use --with-linux-hiddev=PATH
     and set it right.

     Then, go into your models directory and do "make hidups".

     Next, run it - "./hidups /dev/usb/hid/hiddev0", or whatever device
     number applies if you have multiple devices like this attached.  If
     you don't have those /dev entries, make them with mknod.  They need
     to be character devices, major 180, minor 96 and up.

     If it finds your UPS, copy the driver to a system directory and
     arrange your startup scripts to bring it up every time.  Then, be
     sure to add an entry to your ups.conf.  This is one of the new
     "common core" drivers, so you can even autostart it with upsdrvctl.

     Remember: this is brand new *experimental* software and is probably
     very broken.  Do us a favor and report successes or failures to
     the mailing lists.

     Developers on other systems (the BSDs in particular) are encouraged
     to pitch in to make this work on their kernel's USB implementation.

-----------------------------------------------------------------------------

  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.  The official releases are strictly
     source code, as posted on http://www.exploits.org/nut/.   If you 
     have an issue related to packaging, you need to talk to 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 to shut down
     the system if necessary.

     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.

-----------------------------------------------------------------------------

  Q: Why does upsmon shut down when my NOTIFYCMD runs for more than
     about 15 seconds?

  A: You're running an old version of upsmon, and you're tripping
     the DEADTIME.  The quickest fix is to upgrade to version 0.45.4 or
     later, since new versions fork before calling out to the NOTIFYCMD.
 
-----------------------------------------------------------------------------

  Q: When I tell upsd to reload the config files with kill -HUP, it
     complains in the syslog that it can't open the upsd.conf.  It
     worked when the program started, so why is it failing now?

  A: Look at who upsd is running as now.  Chances are, it switched to
     "nobody" shortly after it started for safety - it drops root.
     The problem here is that nobody can't open your upsd.conf file.

     If you want the reloading feature to work, the user that upsd
     runs as must be able to open the various config files.  The
     best way to handle this is to create a user just for upsd and
     then assign all of those files to it.  See the "security domains"
     question above for a good way to do this.

     The quick hack solution is to make the upsd.conf file readable
     by nobody, but realize that upsd.conf has passwords in it and 
     you'll be exposing them to the whole world.  Do the right thing
     and make a proper user account instead or just don't use reloads.
     
-----------------------------------------------------------------------------

  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 (-pre) version.

     If your problem is STILL there, then contact the mailing lists.

-----------------------------------------------------------------------------

  Q: Do you have to use a serial connection to monitor the UPS?
     What about direct network connections (SNMP or otherwise)?

  A: Right now, the only driver that doesn't use a serial connection is
     hidups.  It uses a USB connection, and then only on Linux.

     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 -pre version 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.

     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.

     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: 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://tuxedo.org/~esr/faqs/smart-questions.html

-----------------------------------------------------------------------------

  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.  

-----------------------------------------------------------------------------