<!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 sharing 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
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 <b>apcupsd</b> (default
configuration).
</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>NETSTATUS</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 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. That being said, most of us prefer to run the server this
way.
</p>
With <b>apcupsd</b> version 3.8.2, 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.
</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 7000/tcp</PRE><p>
This defines the port number (7000) 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>NETSTATUS</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>NETSTATUS</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 7000. 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
7000, 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>NETSTATUS</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>
