<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<TITLE>The apcupsd Network Information Server</TITLE>
<meta name="Author" content="Kern Sibbald">
<link rel=stylesheet href="apcupsd-styles.css" type="text/css">
</head>
<body>
<h1>The Apcupsd Network Information Server</h1>
<p>Apcupsd maintains STATUS and EVENTS data concerning the UPS and
its operation. This information can be obtained over the network
using either <b>apcnetd</b> or <b>apcupsd</b>'s internal network
information server, which is essentially the same code as <b>apcnisd</b>
but compiled into apcupsd. Clients on the network make a connection
to the information server and send requests for <a href="status.html">STATUS,</A>
or <a href="events.html">EVENTS</A> data, which the server then
transmits to them.
</p>
<p>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 <a href="configure.html#UPS_Sharing">
configuration section </A>of this documentation.
</p>
<p>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 <b>apcupsd</b> (default
configuration). We recommend option 3 unless you have specific reasons
to do otherwise.
</p>
<h2>Running the Network Information Server Directly within Apcupsd</h2>
<p>This is probably the simplest way to run the network information
server. To do so, you simply modify the <b>NETSERVER</b> directive in
<b>/etc/apcupsd/apcupsd.conf</b> to be <b>on</b>, and then <a href="stopping.html">stop</A>
and <a href="invoking.html">restart</a> <b>apcupsd. </b>It will
automatically create the server thread (or spawn an additional child process named <b>apcnis</b>)
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 <b>apcupsd.conf</b>, since
it is already turned on.
</p>
<p>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 <b>apcnis</b> to die, in which case, though it is
not supposed to, <b>apcupsd</b>
may also exit, thus leaving your machine without shutdown
protection. In addition, since <b>apcupsd</b> 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.
</p>
With <b>apcupsd</b> 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
<b>/etc/hosts.allow</b>.
<h2><a name="ApcnetdINETD"></a>Running apcnisd from INETD</h2>
<p>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 <b>apcnisd</b>. Once <b>apcnisd</b> has responded to the
client's requests, it will exit. None of the disadvantages of running
it standalone apply since <b>apcnisd</b> 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 <b>apcupsd</b> does not support the
shared memory calls that are necessary for <b>apcnisd</b> to
access the internal state of <b>apcupsd</b>.
</p>
<p>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 <b>hosts.allow</b>. See
the man pages for <b>hosts.allow</b> for more details.
</p>
<p>To configure <b>apcnisd</b> to run from INETD, you must first put
an entry in <b>/etc/services</b> as follows:
</p>
<PRE STYLE="margin-bottom: 0.2in">apcnisd 3551/tcp</PRE><p>
This defines the port number (3551) and the service (TCP) that
<b>apcnisd</b> 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.
</p>
<p>Next, you must modify <b>/etc/inetd.conf</b> to have the following
line:
</p>
<PRE STYLE="margin-bottom: 0.2in">apcnisd stream tcp nowait root /usr/sbin/tcpd /sbin/apcnisd -i</PRE><p>
If you do not want to run the TCP wrapper, then the line should be
entered as follows (not tested):
</p>
<PRE STYLE="margin-bottom: 0.2in">apcnisd stream tcp nowait root /sbin/apcnisd -i</PRE><p>
Please check that the file locations are correct for your system.
Also, note that the <b>-i </b>option is necessary so that <b>apcnisd</b>
knows that it was called by INETD. Before restarting INETD, first
ensure that the <b>NETSERVER</b> directive in
<b>/etc/apcupsd/apcupsd.conf</b> is set to <b>off</b>. This is
necessary to prevent <b>apcupsd</b> from starting a child process
that acts as a server. If you change <b>NETSERVER</b>, you must <a href="stopping.html">stop</A>
and <a href="invoking.html">restart</A> <b>apcupsd</b><span style="font-weight: medium">
for the configuration change to be effective. </SPAN>
</p>
<p>Finally, you must restart INETD for it to listen on port 3551. On
a RedHat system, you can do so by:
</p>
<P STYLE="margin-left: 0.79in">/etc/rc.d/init.d/inet reload
</p>
<p>At this point, when a client attempts to make a connection on port
3551, INETD will automatically invoke <b>apcnisd</b>.
</p>
<h2>Running apcnisd Standalone</h2>
<p>This is probably the least desirable of the three ways to run an
<b>apcupsd</b> network information server because if <b>apcupsd</b>
is stopped, you must also stop <b>apcnisd</b> before you can restart
<b>apcupsd</b>. This is because <b>apcnisd</b>, when run standalone,
holds the shared memory buffer by which <b>apcnisd</b> and <b>apcupsd</b>
communicate. This prevents a new execution of <b>apcupsd</b> from
creating it.
</p>
<p>To execute <b>apcnisd</b> in standalone mode, first ensure that
the <b>NETSERVER</b> directive in <b>/etc/apcupsd/apcupsd.conf</b> is
set to <b>off</b>. This is necessary to prevent <b>apcupsd</b> from
starting a child process that acts as a server. Restart <b>apcupsd</b>
normally, then:
</p>
<P STYLE="margin-left: 0.79in">/sbin/apcnisd</p>
<p>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 <b>apcupsd</b>.
</p>
<h2><BR><BR>
</h2>
<hr>
<a href="apctest.html" target="_self"><img src="back.gif" border=0 alt="Back"></a>
<a href="bugs.html" target="_self"><img src="next.gif" border=0 alt="Next"></a>
<a href="index.html"><img src="home.gif" border=0 alt="Home"></a>
</body>
</html>
