Monitoring Your UPS With apcupsd

When apcupsd is run, it first initializes the serial port and tries to determine if there is a UPS connected. Once it finds a UPS, it spawns a number of child processes, each doing a specific task. This is a design decision, due to the number of things that apcupsd must do simultaneously.

The main apcupsd process creates an IPC-shared memory pool and an IPC semaphore, then forks the apcmain task, becoming a dæmon, before exiting. The job of apcmain is to fork all the other asynchronous tasks, wait for child termination, and listen for signals. It acts as a watchdog to avoid zombies or lost signals, and it does so simply by waiting with the wait() system call.

After becoming a dæmon, apcmain forks more processes depending on which configuration has been selected in the configuration file. Figure 2 shows the operations of apcupsd once started. Let's see them in detail.

Figure 2. Startup Actions

If the UPS is local to the computer apcupsd is running on, the first task that is started is apcser. This task listens to the serial port for UPS alerts, and chats with the UPS to gather all the information needed to know the status of the UPS. In this configuration, apcser is the most important process running on the system, because, besides chatting with UPS, it executes all the actions needed to run and shut down, if necessary, the computer safely during power failures. In addition, this task generates the reports that are written to system and private log files for history purposes.

Also, if apcupsd is asked to act as a Network Information Server, it will start apcnis. apcnis is a task that accepts connections from clients on the network and delivers information gathered from the UPS to them.

If the UPS protecting local computer's power utility is managed from a remote computer on the network, instead of starting apcser, the apcmain task will start the apcslv task. apcslv is a slave task that sits on a socket waiting for a connection from an apcupsd remote master. This process is the most important task of a networked apcupsd slave. When the network master sends the UPS' alerts to the slave, apcslv executes the same action routine executed by apcserial. This means that a slave that receives a battery-exhausted alert from its master will shut down the computer to ensure data and hardware safety.

Finally, if the UPS is local and it powers a utility line with other slave computers connected, apcupsd will start apcmst, the master process for network alert. apcmst's task is to send, at defined intervals, the status of the UPS to every slave configured. Also it is very important for the slaves because if the UPS sends alerts to the computer, apcmst bypasses the time-outs and reports them immediately to the slaves. In this way we can make sure that the slaves receive power alerts almost immediately.

It is interesting to note that apcupsd processes communicate with each other through IPC shared memory areas and semaphores. This means that apcupsd will not run on a computer where System V IPC or some equivalent (such as memory mapped files) is not present.

Before running apcupsd it is necessary to configure the dæmon to work as needed with the local hardware configuration and the desired behavior. In a standard installation, the configuration file is in

 /etc/apcupsd/apcupsd.conf

This file is a plain ASCII file that contains all the configuration directives needed by apcupsd.

The directives must be properly configured before apcupsd can operate correctly. With these directives you specify the kind of cable, the model of UPS connected to the computer, the device where the UPS is connected, how to operate on power failures, logging options and much more.

A typical stand-alone configuration includes a computer and a UPS connected to its serial port.

Listing 2

Listing 2 shows a configuration file for a stand-alone SmartUPS connected to the first serial port of the computer. On power failure, apcupsd will shut down the computer when the battery level falls below 5% of full charge or the UPS remaining run-time falls below three minutes, whichever happens first. apcupsd will send messages to user consoles every five minutes sending the first message one minute after the power failure occurs. apcupsd will not disallow user logins during a power failure. UPS events are logged in /etc/apcupsd/apcupsd.events. The UPS status can be read from our CGI interface or from /etc/apcupsd/apcupsd.status, which is updated every minute.