<!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>
</BODY>
</HTML>
