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 master/slave mode that shares 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 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 thread (or child process) of apcupsd (default configuration). We recommend option 3 unless you have specific reasons to do otherwise.
This is probably the simplest way to run the network information server. To do so, you simply modify the NETSERVER directive in /etc/apcupsd/apcupsd.conf to be on, and then stop and restart apcupsd. It will automatically create the server thread (or 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. In addition, since apcupsd is running at root level, all threads or any child process will do so also. That being said, most of us prefer to run the server this way.
With apcupsd version 3.8.2 and later, you may enable the TCP Libwrap subroutines to add additional security. In this case, access to the network server will be controlled by the statements you put in /etc/hosts.allow.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. Note, running in this manner works only if you are using the old forking code and have pthreads explicitly turned off. The pthreads version of apcupsd does not support the shared memory calls that are necessary for apcnisd to access the internal state of apcupsd.
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 3551/tcp
This defines the port number (3551) 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 NETSERVER 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 NETSERVER, you must stop and restart apcupsd for the configuration change to be effective.
Finally, you must restart INETD for it to listen on port 3551. 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 3551, INETD will automatically invoke apcnisd.
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 NETSERVER 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.