The Apcupsd Network Information Server

Apcupsd maintains STATUS and EVENTS data concerning the UPS and its operation. This information can be obtained over the network using either apcnetd or apcupsd's internal network information server, which is essentially the same code as apcnisd but compiled into apcupsd. Clients on the network make a connection to the information server and send requests for STATUS, or EVENTS data, which the server then transmits to them.

The information served to the network by this interface should not be confused with sharing a UPS between two or more computers. That code is described in the configuration section of this documentation.

There are three different ways to run the information server daemon depending on your requirements and preferences. It can be run as 1. a standalone program, 2. a standalone program invoked by the inetd daemon, or 3. as a child process of apcupsd (default configuration).

Running the Network Information Server Directly within Apcupsd

This is probably the simplest way to run the network information server. To do so, you simply modify the NETSTATUS directive in /etc/apcupsd/apcupsd.conf to be on, and then stop and restart apcupsd. It will automatically spawn an additional child process named apcnis to handle network clients. In the case where pthreads are enabled, a new thread will be created rather than a child process to handle the network information requests. Note, the above modification should not be necessary if you use the default apcupsd.conf, since it is already turned on.

Although this method is simple, it affords no protection from the outside world accessing your network server unless, like me, you are behind a firewall. In addition, if there is a bug in the network server code, or if a malicious user sends bad data, it may be possible for apcnis to die, in which case, though it is not supposed to, apcupsd may also exit, thus leaving your machine without shutdown protection. That being said, most of us prefer to run the server this way.

Running apcnisd from INETD

This is probably the most secure and most desirable way of running the network information server. Unfortunately, it is a bit more complicated to setup. However, once running, the server remains unexecuted until a connection is attempted, at which point, inetd will invoke apcnisd. Once apcnisd has responded to the client's requests, it will exit. None of the disadvantages of running it standalone apply since apcnisd runs only when a client is requesting data.

An additional advantage of this method of running the network information server is that you can call it with a TCP wrapper and thus use access control lists (ACL) such as hosts.allow. See the man pages for hosts.allow for more details.

To configure apcnisd to run from INETD, you must first put an entry in /etc/services as follows:

apcnisd         7000/tcp

This defines the port number (7000) and the service (TCP) that apcnisd will be using. This statement can go anywhere in the services file. Normally, one adds local changes such as these to the end of the file.

Next, you must modify /etc/inetd.conf to have the following line:

apcnisd stream  tcp     nowait  root    /usr/sbin/tcpd  /sbin/apcnisd -i

If you do not want to run the TCP wrapper, then the line should be entered as follows (not tested):

apcnisd stream  tcp     nowait  root    /sbin/apcnisd -i

Please check that the file locations are correct for your system. Also, note that the -i option is necessary so that apcnisd knows that it was called by INETD. Before restarting INETD, first ensure that the NETSTATUS directive in /etc/apcupsd/apcupsd.conf is set to off. This is necessary to prevent apcupsd from starting a child process that acts as a server. If you change NETSTATUS, you must stop and restart apcupsd for the configuration change to be effective.

Finally, you must restart INETD for it to listen on port 7000. On a RedHat system, you can do so by:

/etc/rc.d/init.d/inet reload

At this point, when a client attempts to make a connection on port 7000, INETD will automatically invoke apcnisd.

Running apcnisd Standalone

This is probably the least desirable of the three ways to run an apcupsd network information server because if apcupsd is stopped, you must also stop apcnisd before you can restart apcupsd. This is because apcnisd, when run standalone, holds the shared memory buffer by which apcnisd and apcupsd communicate. This prevents a new execution of apcupsd from creating it.

To execute apcnisd in standalone mode, first ensure that the NETSTATUS directive in /etc/apcupsd/apcupsd.conf is set to off. This is necessary to prevent apcupsd from starting a child process that acts as a server. Restart apcupsd normally, then:

/sbin/apcnisd

The advantage of running the network information server standalone is that if for some reason, a client causes the network server to crash, it will not affect the operation of apcupsd.