.TH UPSD.CONF 5 "Wed Oct 16 2002" "" "Network UPS Tools (NUT)"
.SH NAME
upsd.conf \- Configuration for Network UPS Tools upsd

.SH DESCRIPTION

upsd uses this file to control access to the server and set some other
miscellaneous configuration values.  This file will contain passwords
for your \fBupsmon\fR(8) clients, so keep it secure.  Ideally, only the
upsd process should be able to read it.

.SH ACCESS CONTROL CONFIGURATION

.IP "ACL \fIname\fR \fInetblock\fR"

Define an Access Control List (ACL) called \fIname\fR that contains the
network \fInetblock\fR.  The netblock can be either the old style, such
as this for a traditional "class C":

	ACL mynet 192.168.50.0/255.255.255.0

Or, you can use new-style "CIDR format":

	ACL mynet 192.168.50.0/24

To just list one host, it would look like one of these:

	ACL mybox 192.168.50.1/255.255.255.255

	ACL mybox 192.168.50.1/32

ACLs are used whenever you need to refer to a network or host, such as
in ACCESS definitions (below) and with "allowfrom" in \fBupsd.users\fR(5).

.IP "ACCESS \fIaction\fR \fIlevel\fR \fIaclname\fR [\fIpassword\fR]"

Define the access to commands at level \fIlevel\fR by clients in the
network defined by ACL \fIaclname\fR, optionally requiring a password
\fIpassword\fR.

The \fIaction\fR can be one of three values:

	grant - allow the clients to perform commands at this level.

	deny - deny the clients access to commands at this level.

	drop - like deny, but don't even respond to their query.

The \fIlevel\fR relates to the complexity of the command.  More
important functions like editing variables inside the UPS require more
privileges than merely checking the status.  Each level includes the
powers of the one before it.  Here are the valid levels:

	base - Allows TCP connections and very simple queries.  Valid
commands are VER and HELP.

	monitor - "base", plus the ability to fetch variables from the
UPS.  Valid commands are LISTRW, LISTVARS, and REQ.

	login - Deprecated.  Implies monitor and base.  This is used
by old versions of upsmon in slave mode.  Newer versions of upsmon
(1.1 and up) that send usernames are granted access in 
\fBupsd.users\fR(5).

	master - Deprecated.  Implies login, monitor and base.  Used by
old versions in master mode.  See login above.

	all - match any level.  This really only should be used for
"drop all all" or similar.  Granting "all" access to any host is not
recommended.

The \fIaclname\fR is just one of your ACL definitions, as explained
above.

The \fIpassword\fR is only used for "login" or "master", and should not
be set for lower access levels.

.SH ACCESS CONTROL EXAMPLES

Here is an example configuration to show some of what is possible.

	- "bigserver" has a UPS attached to a serial port.  It runs the
driver, upsd, and upsmon in master mode.  This definition is
also referenced with an "allowfrom" in \fBupsd.users\fR(8).

	- "workstation" draws from the same UPS as "bigserver", but has
to monitor
it over the network.  It runs upsmon in slave mode.   It is also
referenced with an "allowfrom" in \fBupsd.users\fR(8).

	- "webserver" doesn't get power from this UPS at all, but it
runs the CGI programs so it can make nice status displays.

	- an abuser is silently dropped

	- everyone not yet covered is denied nicely

.IP
.nf
	ACL bigserver 10.20.30.1/32
	ACL workstation 10.20.30.2/32
	ACL webserver 10.20.30.3/32
	ACL abuser 192.168.255.128/32
	ACL all 0.0.0.0/0

	ACCESS grant monitor bigserver
	ACCESS grant monitor workstation
	ACCESS grant monitor webserver
	ACCESS drop all abuser
	ACCESS deny all all
.fi
.LP

.SH ACCESS CONTROL MATCHING

Access controls should go from most specific to least specific.  The
first match with a sufficient access level is the one used when applying
permissions.

Along the same lines, everyone is a member of "all", but we want to
match everything else first so they don't hit the deny at the bottom.

If you don't have a final "all" match at the bottom, it will force one
for you as a deny.  This means that you have to explicitly add an allow
in order to allow the whole world to have access.

Just think of it as a big repeating "if-then-else" structure.

.SH OTHER CONFIGURATION DIRECTIVES

.IP "MAXAGE \fIseconds\fR"

upsd usually allows the data from a driver to go up to 15 seconds
without an update before declaring it "stale".  If your driver can't
reliably update the data that often but is otherwise working, you can
use MAXAGE to make upsd wait longer.  

You should only use this if your driver has difficulties keeping
the data fresh within the normal 15 second interval.  Watch the syslog 
for notifications from upsd about staleness. 

.IP "STATEPATH \fIpath\fR"

Tell upsd to look for the state files in \fIpath\fR rather than the
default that was compiled into the program.

.SH SEE ALSO
\fBupsd\fR(8), \fBnutupsdrv\fR(8), \fBupsd.users\fR(5)

.SS Internet resources:
The NUT (Network UPS Tools) home page: http://www.exploits.org/nut/
   
NUT mailing list archives and information: http://lists.exploits.org/