next up previous contents index
Next: Testing Apcupsd Up: Apcupsd User's Guide Previous: After Installation   Contents   Index

Subsections


Configuration Examples


A Simple USB Configuration

If you have a USB UPS, and you have apcupsd version 3.10.7 (3.10.17a for *BSD) or higher, the essential elements of your apcupsd.conf file should look like the following:

     ## apcupsd.conf v1.1 ##
     UPSCABLE usb
     UPSTYPE usb
     DEVICE
     LOCKFILE /var/lock
     UPSCLASS standalone
     UPSMODE disable

Notice that we have not specified a device. In doing so, apcupsd will try all the well known USB ports. We strongly recommend you use this (empty device address) form unless you have a good reason to do otherwise.

Please use the explicit specifications of a device only if you know exactly what you are doing. In general, it is much easier to let apcupsd find the device itself.

Please see USB Configuration for detailed help on setting up your system to work with a USB UPS.


A Simple Configuration for a SmartUPS

If you have a Smart UPS using the cable supplied by APC, or you build a CUSTOM SMART cable outlined in the cables chapter, a very simple configuration file would look like the following:

     ## apcupsd.conf v1.1 ##
     UPSCABLE smart
     UPSTYPE smartups
     DEVICE /dev/ttyS0
     LOCKFILE /var/lock
     UPSCLASS standalone
     UPSMODE disable

Normally you would have many more configuration directives to completely customize your installation, but this example shows you the minimum required.


A Simple Configuration for a Simple Signaling or Dumb

If you have a simple signaling or dumb UPS such as a BackUPS, you will need to know exactly what cable you have and specify it on the UPSCABLE directive. Please see the list of UPSes versus cables in the beginning of this document for more information. The cable number is normally stamped in the plastic at one end of the cable. If you specify the wrong cable, it is very likely that at the first power failure, your computer will be immediately shutdown. This is an unfortunate consequence of the dumb signaling mode. To avoid this, first replace /etc/apcupsd/apccontrol with safe.apccontrol found in the examples directory, then test until everything works correctly. Once you have the correct cable, be sure to remember to reinstall the correct apccontrol file and test that your computer is correctly shutdown during a power failure.

     ## apcupsd.conf v1.1 ##
     UPSCABLE (number of cable you have)
     UPSTYPE dumb
     DEVICE /dev/ttyS0
     LOCKFILE /var/lock
     UPSCLASS standalone
     UPSMODE disable

If your cable does not have low battery detection, as is the case with some older models, you will also need to define TIMEOUT nnn where you set nn to be the number of seconds on a power failure after which a shutdown is effected.

Normally you would have many more configuration directives to completely customize your installation, but this example shows you the minimum required.


NIS Server/Client Configuration Using the Net Driver

NIS (Network Information Server) mode allows for communication between instances of apcupsd running on different hosts. Only one of those hosts, the server, needs to talk to the UPS directly. The others, clients, optain information about the state of the UPS by querying the server. NIS is not related to Sun's NIS/YP services.

NIS clients and servers require that apcupsd be compiled with the Net Driver --enable-net. This is typically enabled by default.

The NIS server is connected to the UPS and should be configured exactly as a standalone configuration, but with NETSERVER on. In all other respects, the server should be configured in standalone mode. You may also set the NIS server specific options NISIP to restict which IP address of the server which apcupsd listens on. The default, 0.0.0.0, means to list on all of the server host's IP addresses; NISPORT (default 3551) to set which TCP port the server listens on; and EVENTSFILE and EVENTSFILEMAX to provide information about the last few events to clients. You may also need to modify your firewall rules on the server's host to allow traffic to the NISPORT.

For the NIS client computer, you will have a configuration that looks something like what follows. What is important is that you get the information from an ether UPSCABLE with UPSTYPE set as net over the network and you must specify the address of a NIS server using DEVICE. The client apcupsd will then poll the NIS server specified in DEVICE every POLLTIME seconds (formerly NETTIME).

     ## apcupsd.conf v1.1 ##
     UPSCABLE ether
     UPSTYPE net
     LOCKFILE /var/lock
     DEVICE server-network-address:3551
     UPSCLASS standalone
     UPSMODE disable
     POLLTIME 10

The DEVICE is set to server-address:port, where server-address is the fully qualified domain name or IP address of the apcupsd NIS server, and TCP port is the NISPORT that the server is listening on. The default is 3551, but older versions of apcupsd used port 7000.

If you set POLLTIME too large, your slave may not see the change in state of the NIS server before the server has shutdown. Normally, you have at least 30 seconds of grace time between the time the NIS server decides to shutdown and the time it no longer responds. Your slave must poll during this interval.

Any client run using the Net driver will shutdown when its own timers expire or when the NIS server shuts down, whichever occurs first. This means that if you want the slave to shutdown before the server, you need only set BATTERYLEVEL, MINUTES or TIMEOUT on the client for a faster shutdown than the values defined on the NIS server. This can often be useful if the slave is less important than the master and you wish to reduce battery power consumption so that the master can remain up longer during a power outage.

NIS clients work principally by reading the STATFLAG record that is sent by the NIS server (present in the output of apcaccess). The low 16 bits are the standard APC status flag, and the upper 16 bits represent the internal state of apcupsd, so the slave can see when the power fails and know when to shutdown.

It would be possible to have a client also work as a server, but that would increase the delay of information getting from the UPS to the secondary client.

Differences between NIS Client/Server and the old (now removed) Master/Slave modes

The difference between the NIS mode and the removed master/slave mode is that the NIS server has no explicit knowledge of the slaves. The NIS server makes its information available via the net (NIS), and the NIS slaves read it. When the NIS server is going to shutdown, it makes the information available to any NIS slave that polls it, but the NIS server does not explicitly call each NIS slave as is the case in the Master/Slave networking described several sections above.

Think of the difference as push (Master/Slave) vs. pull (NIS-based). In the case of M/S, the master makes all the shutdown decisions and notifies the slaves when they are to shut down or when some other interesting event happens. The slaves just do whatever the master says, whenever the master says to. On the other hand, with the NIS-based network config you basically ``publish'' the UPS status from one server and then your clients view that status and make their own decisions.


PowerChute Network Shutdown Driver (PCNET)

As of 3.14, Apcupsd supports the PowerChute Network Shutdown protocol. This is an alternative to SNMP for use with APC's AP9617 family of network smartslot modules. Note that the older AP9606 modules do not support PCNET.

To enable PCNET support, configure with the --enable-pcnet flag. This is typically enabled by default.

The required apcupsd.conf settings are straightforward:

     ## apcupsd.conf v1.1 ##
     UPSCABLE ether
     UPSTYPE pcnet
     LOCKFILE /var/lock
     DEVICE ipaddr:user:passphrase
     UPSCLASS standalone
     UPSMODE disable

The DEVICE setting specifies the IP address of the UPS as well as the username and authentication passphrase to use. Note that the username and passphrase are not the Web/SNMP login credentials. They are separate settings. The default username on a new card is "apc" and the default passphrase is "admin user phrase". To change the passphrase, log in to the Web UI and go to the UPS tab, then to PowerChute -> Configuration. (This assumes firmware v3.3.1. Other versions may place the setting elsewhere.) The password must be a minimum of 15 characters long. The web UI will silently ignore shorter passwords and does not give an error message. There is no apparent way to change the username.

Note that you may leave DEVICE blank and Apcupsd will accept information from any PCNET UPS on the network, however it will be very insecure since an attacker could easily send packets crafted to cause your server to shut down. Using the ipaddr, user, and passphrase will prevent this behavior.

You may need to take steps to ensure networking stays active during your OS's shutdown sequence in order for the PCNET driver to power off the UPS (the so-called "killpower" operation). On a Linux distro, you can use commands such as...

   chkconfig --level 0 network on
   chkconfig --level 0 iptables on

...to make sure networking stays up.


next up previous contents index
Next: Testing Apcupsd Up: Apcupsd User's Guide Previous: After Installation   Contents   Index
2009-03-11