Name: Frequently Asked Questions
File: FAQ
Date: 13 August 2000
Auth: Russell Kroll <rkroll@exploits.org>

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

 Q: My UPS-specific support program (apcsmart, genericups, 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 programs give up root _before_ they open the serial port.  So, you
    should change the permissions on the port around so that their   
    running userid can open it.  Typically this corresponds to the user
    "nobody".  If you use the --with-uid option to configure, it may be
    something else.

    Having a "ups" user that owns the serial port might not be such a bad
    idea...

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

 Q: upsc, multimon, and the other programs 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 things like upsstats and upsc only need "monitor" level
    security while upsmon needs "login" or "master" to be functional.

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

 Q: I have a Smart-UPS connected with the grey APC cable and it won't
    work.  The Back-UPS type in the generic 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, while grey, is actually a dual mode cable
    and can be used with the apcsmart driver in conjunction with the -c
    argument.  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.cdrom.com/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.cdrom.com/pub/infozip/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.cdrom.com/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 copy scripts/makefile.lnx 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 is now gone.

    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: Some versions of gd used shared libraries.  The build process keeps
     going back and forth - autoconf driven vs. normal, shared vs. static - 
     so it's hard to say which version causes this.

     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: This file gets installed by default to have tight permissions -
     owned by root, only accessible by root.  That's both good and bad.
     Good since it keeps random users out, but bad since one of those
     random users is usually your web server.

     If your web server runs as nobody, then change the ownership to
     nobody.  That means anything running with that userid can get to the
     file, so consider the consequences.  Maybe it would be better if
     upsset.cgi was suid (to "ups", perhaps) and then _that_ userid 
     owned the file.

     In any case, it's done this way to make you think about the security
     implications before jumping right into things.

  A: Having upsset make the decisions about users is silly, and fixing that
     is on the long term to-do list.  upsd should know about these things,
     so that all control can be brought down from a single file.

     Consider this a temporary wart.

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

  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 "Phoenix"
     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 lines in the upsd.conf and make sure that the path
     agrees with the location that the model driver is using.

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

  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.

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