<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>Apcupsd Post Installation Configuration</TITLE>
<meta name="Author" content="Kern Sibbald">
<link rel=stylesheet href="apcupsd-styles.css" type="text/css">
</HEAD>
<BODY>
<H1>Apcupsd Post Installation Configuration</H1>
<p>It may be necessary to change the configuration information in the
file <b>/etc/apcupsd/apcupsd.conf</b> to meet your needs and to
correspond to your configuration. This file is a plain ASCII file and
you can use your favorite editor to change it. However, please
take a careful look at the <a href="install.html">installation chapter</a>
in this document, because many of these directives can be correctly
set during installation using the <b>./configure</b> program. This simplifies the
task of editing the configuration file, and ensures that other
files (CGI) are appropriately modified as well.</p>
<a name="ConfigTypes"></a>
<h2>Three Major Configuration Possibilities for Apcuspd</h2>
There are three major ways of running <b>apcupsd</b> on your
system. The first is a standalone configuration where <b>apcupsd</b>
controls a single UPS, which powers the computer. This is the most
common configuration. The second configuration is a master/slave
configuration, where one UPS powers several computers, each of which
runs a copy of <b>apcupsd</b>. The computer that controls the UPS
is called the master, and the other computers are called slaves.
The master copy of <b>apcupsd</b> communicates with and controls
the slaves via an ethernet connection.
The third configuration (new with version 3.8.3), is where a single
computer controls multiple UPSes. In this case, there are
several copies of <b>apcupsd</b> on the same computer
each controlling a different UPS. One copy of <b>apcupsd</b> will
run in standalone mode, and the other copy or copies will normally
run in master/slave mode.
<p>These three possibilities can be represented by the following
diagrams:</p>
<pre>
Stand Alone Configuration
--------------------- serial port ------
| | <============> | |
| Computer running | | UPS |
| apcupsd in | Power | |
| stand alone | <============= | |
| mode | ------
| |
---------------------
Typical Master/Slave Configuration
--------------------- serial port ------
| | <============> | |
| Computer A running | | UPS |
| apcupsd in | Power | |
| master mode | <============= | |
| | || ------
| | ||
--------------------- ||
| ||
----------------| Ethernet ||
| | ||
| --------------------- ||
| | | ||
| | Computer B running | ||
| | apcupsd in | Power ||
| | slave mode | <=========||
| | | ||
| | | ||
| --------------------- ||
| ||
| ||
----------------- Ethernet ||
| ||
--------------------- ||
| | ||
| Computer C running | ||
| apcupsd in | Power ||
| slave mode | <===========
| |
| |
---------------------
Multi-UPS Configuration
--------------------- serial port ------
| | <============> | |
| Computer A running | Power | UPS |
| two copies of | <============= | |
| apcupsd | ------
| | serial port ------
| | <============> | |
--------------------- | UPS |
| ==== | |
| Ethernet || ------
| ||
--------------------- ||
| | ||
| Computer B running | ||
| apcupsd in | Power ||
| slave mode | <===========
| |
| |
---------------------
</pre>
<p></p>
If you wish to see some simple examples of possible configuration
files, please see the <a href="config-examples.html">Configuration Examples Chapter</a>
of this document.
<p></p>
For more details about the Multi-UPS Configuration, please see the
Chapter entitled <a href="MultiUPS.html">Configuration for Controlling
Multiple UPSes</a> in this manual.
<h2>Configuration Directives</h2>
<p>Configuration directives in <b>/etc/apcupsd/apcupsd.conf</b> are:
</p>
<H3><a name="ConfigGeneral"></a>General Configuration Directives</H3>
In general, each of these directives is required (the DEVICE directive
is ignored for UPSCABLE ether).
<DL>
<dt STYLE="margin-bottom: 0.2in"><a name="UPSTYPE"></a>
UPSTYPE <type of APC UPS you have> </dt><dd> One
of the big problems is understanding what kind of UPS you have and
knowing what cable to use with what UPS. If you received a cable
with your UPS, the cable number is stamped on the side of the
connector (usually in the plastic on both cable ends), and it is
most likely the correct cable for your UPS. <p>In the table below,
we attempt to show what cables are known to work with each UPS.
This information is a bit sketchy and so should not yet be
considered definitive. Any comments or corrections would be
appreciated.</p> The UPSTYPE directive can be defined during
installation by using the <b>--with-upstype=</b> option on the
<b>./configure</b> program.<p></p>
<a name="ModelsSupported"></a>
<table BORDER=5 CELLPADDING=4 CELLSPACING=3>
<tr>
<th><P ALIGN=CENTER><b>Apcupsd UPSTYPE Keyword</b></p>
<th><P ALIGN=CENTER><b>APC Model</b></p>
<th><P ALIGN=CENTER><b>UPS Signaling</b></p>
<th><p align=center><b>Cables Supported</b></p></th>
<th><P ALIGN=CENTER><b>Status</b></p>
</tr>
<tr><td>backups</td><td>BackUPS</td><td>Simple</td><td>*Simple-Custom, 940-0020B, 940-0020C, 940-0119A, 940-0023A</td><td>Supported</td></tr>
<tr><td>backups</td><td>BackUPS Office</td><td>Simple</td><td>940-0119A</td><td>Supported</td></tr>
<tr><td>backups</td><td>BackUPS ES</td><td>Simple</td><td>940-0119A</td><td>Supported (apparently identical to the BackUPS Office)</td></tr>
<tr><td>smartups</td><td>BackUPS CS (serial mode)</td><td>SubSmart</td><td>Smart (*Custom RJ45)</td><td>Supported using the Custom RJ45 cable</td></tr>
<tr><td>usb</td><td>BackUPS CS USB, BackUPS Pro USB</td><td>SubSmart</td><td>USB (using APC cables 940-0127A/B)</td><td>Supported in apcupsd version 3.9.4 and later</td></tr>
<tr><td>backups</td><td>BackUPS CS (serial mode)</td><td>Simple</td><td>940-0128A</td><td>Supported</td></tr>
<tr><td>sharebasic</td><td>ShareUPS Basic Port</td><td>Simple</td><td>940-0020B, 940-0020C, 940-0023A</td><td>Supported</td></tr>
<tr><td>dumb</td><td>All models listed abovet</td><td>Simple</td><td>Cables listed above</td><td>Supported</td></tr>
<tr><td>backupspro</td><td>BackUPS Pro</td><td>SubSmart</td><td>940-0095A</td><td>Supported (note, see newbackupspro)</td></tr>
<tr><td>smartvsups</td><td>SmartUPS VS</td><td>SubSmart</td><td>940-0095A??</td><td>Supported</td></tr>
<tr><td>newbackupspro</td><td>Smarter BackUPS Pro</td><td>SubSmart</td><td>940-0095A</td><td>Supported</td></tr>
<tr><td>backupspropnp</td><td>Smarter BackUPS Pro</td><td>SubSmart</td><td>940-0095A</td><td>Supported</td></tr>
<tr><td>smartups</td><td>SmartUPS, PowerStack 450</td><td>Smart</td><td>*Smart-Custom, 940-0024C</td><td>Supported</td></tr>
<tr><td>apcsmart</td><td>SmartUPS</td><td>Smart</td><td>*Smart-Custom, 940-0024C</td><td>Supported</td></tr>
<tr><td>matrixups</td><td>MatrixUPS</td><td>Smart</td><td>*Smart-Custom, 940-0024C</td><td>Supported</td></tr>
<tr><td>sharesmart</td><td>ShareUPS Advanced Port</td><td>Smart</td><td>*Smart-Custom, 940-0024C</td><td>Unknown status</td></tr>
<tr><td>usb</td><td>SmartUPS USB</td><td>Smart</td><td>USB (using APC cable)</td><td>Supported in apcupsd version 3.9.8 and later</td></tr>
</table>
<p>
* => see the <a href="cables.html">Cables</a> chapter of this manual for
instructions on how to build this cable (Simple-Custom, Smart-Custom, or
Smart-RJ45).
</dd>
<dt><a name="UPSCABLE"></a>UPSCABLE <type of cable you are using>> </dt>
<dd>
[ simple | 940-0020B | 940-0023A ] <BR>[ smart | 940-0024B
| 940-0024C ] <BR>[ 940-1524C | 940-0024G | 940-0095A | 940-0095B |
940-0095C | 940-0119A] <BR>[ ether | usb ]
<p>If you have a Smart or a SubSmart UPS (see table above), and you
build your own cable, build a <b>Smart-Custom</b> cable (see the
<a href="cables.html">Cables Chapter</a> of this manual). If you
have a <b>Simple</b> UPS, build a <b>Simple-Custom</b> cable.
If you have a BackUPS CS with a RJ45 connector, you can buld your own
<b>Custom-RJ45</b> cable.
<p>
The <b>--with-upscable=</b> option can be used on the <p>./configure</p> program
to set this directive during the installation.
</dd>
<dt><a name="DEVICE"></a>DEVICE <name of device> </dt>
<dd> Please specify which device is used for UPS communications (normally
a serial port or a USB port. The
default is platform dependent, and is usually something like /dev/ttyS0.
For USB ports, you may specify a port range specification of the
form <b>/dev/usb/hid/hidev[-0-9]</b>.
Normally, the ./configure program will set an appropriate default value,
otherwise, you may also specify the <b>--with-serial-dev=</b> option on the
<b>./configure</b> program to set this directive during the installation.
</dd>
<dt><a name="LOCKFILE"></a> LOCKFILE <path to lockfile>
</dt>
<DD STYLE="margin-bottom: 0.2in">
By supplying this argument, "apcupsd" tries to create a
lockfile for the serial port in the specified directory. This
is important to keep two programs from reading or writing the serial
port at the same time. Please note that although the directive name
is LOCKFILE, you are actually specifying the lock file path. Apcupsd automatically
appends the name of the device when creating the file. On most systems, this
directive is automatically set by the <b>./configure</b> program. You may
also explicitly set it during the installation process by using the
<b>--with-lock-dir=</b> option on the <b>./configure</b> program.
</dd></DL>
<H3><A NAME="ConfigInfoServer"></A>Configuration Directives Used by the Network Information Server</H3>
None of these directives are required for proper operation of <b>apcupsd</b>.
For the Network Information Server to work, it must be enabled in the
configuration (default) with <b>--enable-nis</b>.
<a name="NETSERVER"></a><dl>
<dt>NETSERVER [on | off]
</dt><dd>
This configuration directive turns the network information
server on or off. If it is on, <b>apcupsd</b> will spawn a
child process that serves STATUS and EVENTS information over the
network. This information is currently used by the Web based
CGI programs. The default is on. In some cases, for added
security, you may want to invoke a separate information server
daemon from the inetd daemon. In that case, <b>NETSERVER</b>
should be <b>off</b>. </dd>
<dt>NISIP <IP-address></dt><dd>
This directive specifies an
IP address on which NIS server will listen for incoming connections.
Default value is 0.0.0.0 that means any incoming request will be
serviced but if you want it to listen to a single subnet you can
set it up to that subnet address, for example 192.168.10.0
Additionally you can listen for a single IP like 192.168.10.1.
You may also use the <b>--with-nisip=</b> option on the
<b>./configure</b> program to set this directive during
the configuration phase.
<p>
This directive does not work on Win32 machines because
inet_ipton() is not implemented there. </dd>
<dt><a name="NISPORT"></a>
NISPORT <port>
</dt><dd>
This configuration directive specifies the port to be used by the
<b>apcupsd</b> Network Information Server. The default is
platform dependent, but typically 3551, which we have received
from IANA as the official <b>apcupsd</b> networking port. If
you change this port, you must manually change the #define
SERV_TCP_PORT in cgi/upsfetch.c and rebuild the CGI programs.
An alternative is to use the <b>--with-nis-port=</b> option on
the <b>./configure</b> program during installation. In this
case, all the appropriate locations will be automatically
changed. </dd>
<dt><a name="EVENTSFILE"></a>
EVENTSFILE <filename>
</dt><DD STYLE="margin-bottom: 0.2in">
If you want the <b>apcupsd</b> network information server to
provide the last 10 events via the network, you must specify a
file where <b>apcupsd</b> will save these events. The default
is: <b>/etc/apcupsd/apcupsd.events</b>. Currently,
<b>apcupsd</b> will save at most the last 50 events.
Periodically (once an hour by default), <b>apcupsd</b> will
check the size of this file. When more than 50 events are
recorded, <b>apcupsd</b> will truncate the file to the most
recent 10 events. Consequently this file will not grow
indefinitely. Although we do not recommend it, you may change
these values by editing apcevents.c and changing the appropriate
defines. Be aware that if you set these values to very large
numbers, <b>apcupsd</b> may make excessive memory demands on the
system during the data access and file truncation operations. <
p>This filename may also be specified at installation time by
using
the <b>--with-log-dir=</b> option on the <b>./configure</b> program.</p>
</dd></DL>
<H3><a name="ConfigPowerFail"></a>Configuration Directives used during Power Failures</H3>
In general, none of these directives are required. However, if you have a simple
signaling (dumb) UPS with a cable that does not support the Low Battery signal,
you must set the TIMOUT directive to force a shutdown. Please see the
<a href="cables.html#CableModes">Simple Signaling features Supported</a> section of
this manual for more details.
<a name="ANNOY"></a><DL>
<dt>ANNOY <time in seconds>
</dt><dd>
Specify the time in seconds between messages requesting
logged in users to get off the system during a power failure.
This timer starts only when the UPS is running on batteries.
The default is 300 seconds (5 minutes). <b>apcupsd</b> sends
the annoy messages by invoking the <b>apccontrol</b> script
with the <b>annoyme</b> argument. The default is to send a
<b>wall</b> message on Unix systems and a <b>popup</b> in
Windows. The value of <b>ANNOYDELAY</b> must be greater than
the value of <b>ANNOY</b> in order to receive annoy messages
(this doesn't make sense, and means that the default values
do not generate annoy messages -- KES).<br> Note that if
<b>NOLOGON</b> is set to <b>disable</b> the annoy messages
will also be disabled.
</dd><dt>
<a name="ANNOYDELAY"></a>
ANNOYDELAY <time in seconds>
</dt><dd>
Specify delay time in seconds before <b>apcupsd</b> begins
requesting logged in users to get off the system during a
power failure. This timer starts only after the UPS is
running on batteries. This timer is reset when the power
returns. The default is 60 seconds. Thus, the first warning
to log off the system occurs after 60 seconds on batteries,
assuming that <b>NOLOGON</b> is not set to <b>disable</b>.
</dd>
<dt><a name="NOLOGON"></a>NOLOGON <specifies when
<b>apcupsd</b> should prevent user logins>
</dt><DD STYLE="margin-bottom: 0.2in">
[ disable | timeout | percent | minutes | always ] are valid types.
</dd><dd>
The type specified allows you
define the point when <b>apcupsd</b> will create the
<b>/etc/nologin</b> file and thus when user logins are
prohibited. Once the <b>/etc/nologin</b> file is created,
normal users are prevented from logging in. Control of when
this file is created is important for allowing systems with
BIG UPSes to run as normally until the system administrator
determines the need for preventing user logins. The feature
also allows the system administrator to hold the
"ANNOY" factor until the <b>/etc/nologin</b> file
is created. The default is <b>always</b> if no
<b>NOLOGON</b> directive is specified.
<p>
As far as I can tell, the only useful types are
<b>disable</b> and <b>always</b> since the diffence in the
time when the logout warning is given and shutdown occurs
for the other types is very short (KES).
</dd>
<dl>
<dt>
disable
</dt><dd>
prevents <b>apcupsd</b> from creating the nologin
file. Consequently, any user can login during a
power failure condition. Also, the ANNOY feature is
disabled so users will not be warned to logoff the
system.
</dd><dt>
timeout
</dt><dd>
specifies that <b>apcupsd</b> should prohibit logins
after the UPS is on batteries for 90% of the time
specified on the <b>TIMEOUT</b> configuration directive.
Note! Normally you don't want to specify a TIMEOUT value,
so this option is probably not too useful (KES).
</dd><dt>percent</dt><dd>
specifies that <b>apcupsd</b> should prohibit logins
when the remaining battery charge percentage reaches
110% or less than the value specified on the
<b>BATTERYLEVEL</b> configuration directive.
Thus if the <b>BATTERYLEVEL</b> is specified as 15,
<b>apcupsd</b> will prohibit logins when the battery charge
drops below 16% (15% X 110% = 16%).
</dd><dt>minutes</dt><dd>
specifies that <b>apcupsd</b> should prohibit logins
when the remaining runtime in minutes reaches
110% or less than the value specified on the
<b>MINUTES</b> configuration directive. Thus if
<b>MINUTES</b> is set to 3, <b>apcupsd</b> will prohibit
logins when the remaining runtime is less than 3 minutes
(3 X 110% = 3).
</dt><dd>
</dd><dt> always </dt><dd>
causes <b>apcupsd</b> to immediately prohibit logins
when a power failure occurs. This will also enable the
ANNOY feature.
</dd>
</dl>
<dt><a name="BATTERYLEVEL"></a>
BATTERYLEVEL <percent of battery>
</dt><dd>
If BATTERYLEVEL is specified, during a power failure, <b>apcupsd</b> will
halt the system when the remaining battery charge falls below the
specified percentage. The default is 5 percent. This directive is ignored
for simple signaling UPSes. To totally disable this counter, set
<b>BATTERYLEVEL -1</b> in your apcupsd.conf file.
</dd>
<dt><a name="MINUTES"></a>
MINUTES <battery runtime in minutes>
</dt><dd>
If MINUTES is specified, during a power failure, <b>apcupsd</b> will
shutdown the system when the remaining runtime on
batteries as internally calculated by the UPS falls below the time
specified. The default is 3. This directive is ignored for simple
signaling UPSes. It should be noted that some UPSes report an
incorrect value for remaining runtime when the battery is fully
charged. This can be checked by examining the <b>TIMELEFT</b> value
as printed in the output of an <b>apcaccess status</b> command.
If the value is zero or otherwise unreasonable, your UPS is probably broken.
In this case, we recommend that you disable this timer by setting
<b>MINUTES -1</b> in your apcupsd.conf file.
</dd>
< dt><a name="TIMEOUT"></a>TIMEOUT <time in seconds>
</dt><DD STYLE="margin-bottom: 0.2in">
After a power failure, <b>apcupsd</b> will halt the system when TIMEOUT seconds
have expired. A value of zero disables this timer.
Normally for all Smart UPS models and dumb UPSes with cables that
support low battery detection, this should be zero so that
the shutdown time will be determined by the battery level and/or
remaining runtime (see above) or in the case of a simple
signaling UPS, when the battery is exhausted. This command is required for dumb UPSes
that do not provide a battery exhausted signal (only testing can determine
this point). For more information, see the <a href="testing.html">testing section</a>
of this manual. This timer can also be useful if you want some slave machines
to shutdown before other machines to conserve battery power. It is
also useful for testing <b>apcupsd</b> because you can force a rapid
shutdown by setting a small value (e.g. 60) and pulling the plug to
the UPS.
</dd><DD STYLE="margin-bottom: 0.2in">
When <b>apcupsd</b> is running in master mode (UPSCLASS netmaster),
and a shutdown condition is determined, <b>apcupsd</b> will notify
each of the slaves to perform a shutdown then <b>apcupsd</b> will
sleep for 30 seconds before issuing the shutdown of its own computer.
If you need the master to wait additional time before shutting down
(to allow for shutdown of slower slaves or of slaves running software
that requires more time to shutdown -- e.g. databases), you can do
so by adding additional sleep() commands to <b>/etc/apcupsd/apccontrol</b>
in each case that causes a shutdown.
</dd><DD STYLE="margin-bottom: 0.2in">
<b>TIMEOUT, BATTERYLEVEL, and MINUTES</b> can be set together
without problems. <b>apcupsd</b> will react to the first case or test that
is valid. Normally SmartUPS users will set <b>TIMEOUT</b> to zero so
that the system is shutdown depending on the percentage battery
charge remaining <b>(BATTERYLEVEL)</b> or the remaining battery
runtime <b>(MINUTES)</b>.
</dd>
<dt><a name="KILLDELAY"></a> KILLDELAY <time in seconds>
</dt><DD STYLE="margin-bottom: 0.2in">
If killdelay is set, <b>apcupsd</b> will continue running after a
shutdown has been requested, and after the specified time in
seconds, <b>apcupsd</b> will attempt to shut off the UPS the power.
This directive should normally be disabled by setting the value to
zero, but on some systems such as Win32 systems <b>apcupsd</b>
cannot regain control after a shutdown to force the UPS to shut off
the power. In this case, with proper consideration for the timing,
the <b>KILLDELAY</b> directive can be useful. Please be aware, if you cause
b>apcupsd</b> to kill the power to your computer too early, the
system and the disks may not have been properly prepared. In addition,
<b>apcupsd</b> must continue running after the shutdown is requested,
and on Unix systems, this is not normally the case as the system will
terminate all processes during the shutdown.
</dd>
</DL>
<H3><a name="ConfigLogging"></a>Configuration Directives used to Control System Logging</H3>
None of these directives are required.
<a name="STATTIME"></a><DL>
<dt>STATTIME <time>
</dt><dd>
This directive supplies the time interval between writes to the STATUS
file. If set to zero, the STATUS file will not be written. Please note
that in a future version of <b>apcupsd</b> the STATUS file code will
disappear since its functionality has been replaced by the Network
Information Server and by <b>apcaccess status</b>, as a consequence,
it is normally disabled by setting it to zero.
</dd><dt>
<a name="STATFILE"></a>
STATFILE <file>
</dt><dd>
This directive specifies the file to be used when writing the STATUS
information. The default is /etc/apcupsd/apcupsd.status
</dd><dt>
<a name="DATATIME"></a>
DATATIME<time>
</dt><dd>
This directives supplies the time interval between writes of
PowerChute&tm; like data information to the log file.
See the <a href="data.html">DATA format specification</a> section
of this manual for additional details.
</dd><dt>
<a name="FACILITY"></a>
FACILITY <log-facility>
</dt><DD STYLE="margin-bottom: 0.2in">
The facility directive can be used to change the system logging class
or facility. The default is <b>DAEMON</b>. This parameter can be
useful if you wish to direct the <b>apcupsd</b> system logging information
to other than your system default files. See the <a href="logging.html">logging section</a>
of this manual for additional details.
</dd></DL>
<a name="UPS_Sharing"></a>
<H3>Configuration Directives for Sharing a UPS</H3>
The following directives apply to the master/slave networking mode of
<b>apcupsd</b> where multiple machines can be powered by the same UPS.
One machine, the master, will have a serial port connection to the UPS, and
the other machines, the slaves, will obtain their information via the network
from the master.
<p>
<b>Note, as of version 3.10.x, the old master/slave code is by default turned off
in the configuration. You must explicitly enable it by including a
<b>--enable-master-slave</b> option on your <b>./configure</b> command
before building the source.
<p>
In addition to the old master/slave code, there is now a new network driver
enabled with <b>--enable-net</b> (default disabled) that can be used to
control a slave from any version of apcupsd running NIS. This is a much
more flexible system of controlling slaves because a slave machine that
also has NIS turned on can thus act as a master for another slave with
<b>--enable-net</b> turned on. With this mode turned on, the slave
obtains the address of the master from the <b>DEVICE</b> directive,
which takes the form <b>hostname[:port]</b> as a consequence, none of
the directives apply for this form of networking. In addition, for this
mode to work, you must specify <b>UPSTYPE net</b> so that the proper
driver is loaded.
<p>
The remainder of this section presents directives that apply
to the old master/slave code that must be enabled by
the <b>enable-master-slave</b> configuration option.
<p>
<a name="UPSCLASS"></a>
<DL>
<dt>UPSCLASS <class of operation></dt>
<DD STYLE="margin-bottom: 0.2in">
[ standalone | shareslave | sharemaster ] and <BR>[ netslave |
netmaster ] are valid types. <BR>[ standalone | netslave | netmaster
] are tested classes. <BR>[ shareslave | sharemaster ] classes are
being tested.
</dd>
<DD STYLE="margin-bottom: 0.2in">
The default is <b>standalone</b> and should be used for all machines
powered by the UPS and having a serial port connection to the UPS,
but where there are no other computers dependent on power from the same
UPS. This is the <b>normal</b> case.
</dd>
<DD STYLE="margin-bottom: 0.2in">
Use <b>netmaster</b>, if and only if you have a serial port
connection to the UPS and there are other machines deriving power
from the same UPS. This is required in all master configuration
files.
</dd>
<DD STYLE="margin-bottom: 0.2in">
Use <b>netslave</b> if and only if you have no serial port
connection to the UPS, but you derive power from it. This is
required in all slave configuration files, and in this case,
you will also have UPSCABLE set to <b>ether</b>.
</dd>
<DD STYLE="margin-bottom: 0.2in">
Use <b>shareslave</b> if and only if you are using a ShareUPS and
connected to a BASIC Port with Simple Signal. This code is not fully
tested.
</dd>
<dd>Use <b>sharemaster</b>, if and only if you are using a ShareUPS and
connected to the ADVANCED Port Smart Signal control. This code
is not fully tested. </dd>
<dt><a name="UPSMODE"></a>UPSMODE [ disable | share | net | sharenet ] are valid types. </dt>
<DD STYLE="margin-bottom: 0.2in">
[ disable | net ] are the only known and tested classes.
</dd>
<DD STYLE="margin-bottom: 0.2in">
[ share | sharenet ] classes are being tested.
<p>For normal standalone operations, you will set <b>UPSMODE</b> to <b>disable</b>
to indicate that you are disabling the master/slave networking.</p>
<p>However, if you are using a single UPS to power several computers and
you have configured master and slave computers, then set
this value to <b>net</b>.</dd>
<dd>Use share for two or seven (2/7) additional simple signal ports
on a SmartAccessories(tm) (internal/external box) for SmartUPSes.
The share and sharenet code is not fully tested.</dd>
<dt><a name="NETTIME"></a>NETTIME <time in seconds> </dt>
<dd>
The interval in seconds that the master uses to send information to slave machines.
This rate is automatically set to 1 second if the UPS goes on batteries and
reset to your specified value when the mains power returns. A typical value might
be 60 seconds.
</dd>
<dt><a name="NETPORT"></a>NETPORT <IP port number>
</dt><DD STYLE="margin-bottom: 0.2in">
This port number is used for communications in the master/slave networking code. Note
that the master and each slave must have the same port number specified
on the NETPORT directive in the configuration file. This port may also be specified
during installation by using the <b>--with-net-port=</b> option on the <b>./configure</b> program.
<p>The NETPORT should not be confused with the port number for the Network Information Server
which is specified with the <b>SERVERPORT</b> configuration directive.</dd>
<dt><a name="MASTER"></a>MASTER <name of the master> for Slave machines. </dt>
<dd>Used in slave configuration files, this is the network name of the
master which is authorized to send commands to this slave. In all
cases (of which I am aware), when you specify a <b>MASTER</b> directive,
you will also specify <b>UPSCABLE ether</b> since your information
about the UPS will come via the network from a master.
<p>The slave machine will be shutdown whichever occurs first: either at the request of the master when
it does a shutdown or when the values you have specified for TIMEOUT,
BATTERYLEVEL, or MINUTES expire (these should work but have not been fully
tested). Consequently, if you want the slaves to begin shutting down before
the master, you can do so by adjusting the values in the configuration file.
If you want the slave to remain up until the master shuts down, you should set
TIMEOUT, BATTERYLEVEL, and MINUTES all to zero.</p>
<p>For proper functioning of the slave, you must specify the
same <b>UPSTYPE</b> in the slave configuration file as is in
the master configuration file.</p>
<p>It should be noted that the master and slaves continue to communicate
over the network even after the master has issued a shutdown command
to the slaves. This is because the master <b>apcupsd</b> continues
to run until it receives the shutdown signal from the system. This is
important to ensure that all the slaves have been properly notified of
the shutdown.</p>
<p>We recommend that the machine names used on the <b>MASTER</b> and <b>SLAVE</b>
directives be put in your <b>/etc/hosts</b> file so that <b>apcupsd</b> will
be able to resolve the machine name during startup and shutdown even if
DNS is not running. Alternatively, you can use IP addresses on the <b>MASTER</b>
and <b>SLAVE</b> directives, but this is less flexible.</dd>
<dt><a name="SLAVE"></a>SLAVE <name of slave(s)> used only in
MASTER configuration files.</dt>
<dd>Used in master configuration files, this is the name of a slave
machine that depends on this master. There can be
a maximum of 20 slaves attached to one master. Thus you can specify
multiple SLAVE directives in a master configuration file. Only one slave
name can be specified per SLAVE directive, thus for multiple slaves,
specify multiple SLAVE directives.
<p>As noted above the master and slaves continue to communicate
over the network even after the master has issued a shutdown command
to the slaves. This is because the master <b>apcupsd</b> continues
to run until it receives the shutdown signal from the system. This is
important to ensure that all the slaves have been properly notified of
the shutdown.</p>
<p>We recommend that the machine names used on the <b>MASTER</b> and <b>SLAVE</b>
directives be put in your <b>/etc/hosts</b> file so that <b>apcupsd</b> will
be able to resolve the machine name during startup and shutdown even if
DNS is not running. Alternatively, you can use IP addresses on the <b>MASTER</b>
and <b>SLAVE</b> directives, but this is less flexible.</dd>
<dt><a name="USERMAGIC"></a>USERMAGIC < user defined magic> used
only in SLAVE configuration files.
</dt>
<DD STYLE="margin-bottom: 0.2in">
The USERMAGIC directive is a sort of password that gives a second
level of identification
security in a slave configuration file. It is a character string
up to 17 characters in length. It should be unique for each slave.
When the slave makes initial contact with the master, this string
is passed to the master. Then on each transmission from the master
to the slave, the string is passed back to the slave, which checks
that it is the correct string before accepting the master's information.
This string should be different for each and every slave on the network.
This directive is not required.
</dd>
</DL>
<H3>Configuration Directives Used to Set the UPS EPROM</H3>
<p>The values specified with the following directives are only used
if the <b>--configure</b> option is specified on the <b>apcupsd</b> command
line, and the UPS is capable of internal EPROM programming. In that
case, <b>apcupsd</b> attempts to set the values into the UPSes EPROM.
</p>
<p>Under normal operations, the values for these parameters specified
in the configuration file are not used. Instead, they are read from
the UPS EPROM by <b>apcupsd</b>. See the <a href="eprom.html">EEPROM programming section</a>
of this manual for further details before attempting to reprogram your EEPROM.
</p> <a name="SENSITIVITY"></a>
<DL>
<dt>SENSITIVITY <sets sensitivity level> </dt>
<DD STYLE="margin-bottom: 0.2in">
(H)igh, (M)edium, (L)ow </dd>
<DD STYLE="margin-bottom: 0.2in">
This value determine how sensitive the UPS is to the mains quality
and voltage fluctuations. The more sensitive it is, the quicker the
UPS will switch to battery power when the mains line quality is bad.
Normally, this should be set to H, but if you find your UPS
switching to batteries frequently, you might want to try a less
sensitive setting, providing that your computer equipment tolerates
the poor quality mains. This value is written to the UPS EPROM when
the configure option is specified. </dd>
<dd>Under normal <b>apcupsd</b> operations (no <b>--configure</b> option),
<b>apcupsd</b> will read the value stored in the UPS and display it in the
STATUS output. </dd>
<dt><a name="WAKEUP"></a>WAKEUP <set wakeup delay></dt>
<dd>The UPS power restart delay value in [0,60,180,300] in seconds after the
UPS has shut down during a power failure. This is to prevent the power
from coming back on too quickly after a power down, and is important
for those who have high rpm drives that need to spindown before
powering them up again. Some older SCSI models are very sensitive to
this problem. Default is zero. This value is written to the UPS
EPROM when the <b>--configure</b> option is specified. Under normal apcupsd
operations (no <b>--configure</b> option), <b>apcupsd</b> will read the value
stored in the UPS and display it in the STATUS output. </dd>
<dt><a name="SLEEP"></a>SLEEP <set sleep delay> </dt>
<dd>The UPS delay or grace period in [20,180,300,600] seconds before the UPS
cuts the power to your equipment. The default is 20 seconds. This
value is written to the UPS EPROM when the <b>--configure</b>
option is specified. Under normal <b>apcupsd</b> operations (no <b>--configure</b>
option), <b>apcupsd</b> will read the value stored in the UPS and display it
in the STATUS output.</dd>
<dt><a name="LOWTRANSFER"></a>LOTRANSFER <lower limit of ups batt. transfer> </dt>
<DD STYLE="margin-bottom: 0.2in">This sets the low line voltage point at which to switch over to
batteries. Different values are permitted
based on the UPS model, classification, and manufacture date.
Use <b>apcaccess eeprom</b> to show you which values are
permitted.
This value is written to the UPS EPROM when the <b>--configure</b>
option is specified.</dd>
<dd>Under normal <b>apcupsd</b> operations (no <b>--configure</b> option), <b>apcupsd</b>
will read the value stored in the UPS and display it in the STATUS
output.</dd>
<dt><a name="HITRANSFER"></a>HITRANSFER <upper limit of ups batt. transfer> </dt>
<DD STYLE="margin-bottom: 0.2in">This sets the high line voltage point to switch over to batteries.</dd>
<DD STYLE="margin-bottom: 0.2in">Different values are permitted
based on the UPS model, classification, and manufacture date.
Use <b>apcaccess eeprom</b> to show you which values are
permitted. This value is written to the UPS EPROM when the <b>--configure</b> option
is specified.</dd>
<dd>Under normal <b>apcupsd</b> operations (no <b>--configure</b> option), <b>apcupsd</b>
will read the value stored in the UPS and display it in the STATUS
output.</dd>
<dt><a name="RETURNCHARGE"></a>RETURNCHARGE <min. batt. charge level> </dt>
<DD STYLE="margin-bottom: 0.2in">This parameter specifies what battery percentage charge is necessary
before the UPS will supply power to your equipment after a power
down. Different values are permitted
based on the UPS model, classification, and manufacture date.
Use <b>apcaccess eeprom</b> to show you which values are
permitted. This value is written to the UPS EPROM when the <b>--configure</b>
option is specified. </dd>
<dd>Under normal <b>apcupsd</b> operations (no <b>--configure</b> option), <b>apcupsd</b>
will read the value stored in the UPS and display it in the STATUS
output.</dd>
<dt><a name="BEEPSTATE"></a>BEEPSTATE <alarm beep state> </dt>
<dd>This parameter tells the UPS when it can sound its audio alarm.
These settings are based on discrete events related to the remaining
capacity of the UPS.</dd>
<dl>
<dt>0</dt>
<dd>immediately upon power failure </dd>
<dt>T</dt>
<dd>power failure + 30 seconds /DD>
<dt>L</dt>
<dd>low battery power </dd>
<dt>N</dt>
<dd>never </dd>
</dl>
<dt><a name="UPSNAME"></a>UPSNAME <string> </dt>
<DD STYLE="margin-bottom: 0.2in">
This is an eight character string.This is the UPS name that will be stored in the UPS
EPROM.</dd>
<DD STYLE="margin-bottom: 0.2in">
This value is written to the UPS EPROM when the --rename-ups option
is specified. Under normal <b>apcupsd</b> operations (no <b>--configure</b>
option), <b>apcupsd</b> will read the value stored in the UPS and display it
in the STATUS output.</dd>
<dt><a name="BATTDATE"></a>BATTDATE <string> </dt>
<DD STYLE="margin-bottom: 0.2in">
This is an eight character string that is the last date the
batteries were changed.</dd>
<DD STYLE="margin-bottom: 0.2in">
This value is written to the UPS EPROM when the --update-battery-date option
is specified. Under normal <b>apcupsd</b> operations (no <b>--configure</b>
option), <b>apcupsd</b> will read the value stored in the UPS and display it
in the STATUS output.</dd>
</DL>
<hr>
<a href="install.html" target="_self"><img src="back.gif" border=0 alt="Back"></a>
<a href="config-examples.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>
