Name: How to use access controls
File: access.txt
Date: 12 July 1999

With the introduction of access controls, steps can be taken to keep the
whole world from pounding on your ups server.  These controls should be
used in addition to appropriate firewalling measures for total protection.

ACLs
====

Access control lists define a group of addresses.  They should be listed
one per line in the upsd.conf file with the following format:

ACL <aclname> <ip block>

The ip block must include the network address and the netmask
information.  This can be either CIDR format (/nn) or the traditional
n.n.n.n format.  

These examples show both forms.  Pick one you like and stick with it.

To create an entry for localhost:

	ACL localhost 127.0.0.1/32
	ACL localhost 127.0.0.1/255.255.255.255

Perhaps you have a traditional class C and want to list it:

	ACL mynet 206.253.95.0/24
	ACL mynet 206.253.95.0/255.255.255.0

Or maybe you want to cover _everything_:

	ACL all 0.0.0.0/0
	ACL all 0.0.0.0/0.0.0.0

Once you've defined your IP blocks, use them as access controls.

Access Controls
===============

These switch access on and off based on ACLs.  This way, you can say that
a certain group can do anything while another has limited access and
everyone else gets nothing at all.

The format:

ACCESS <action> <level> <aclname> [<password>]

action can be:
 - grant - allow this for the group <aclname>
 -  deny - refuse this for <aclname> and send an error message
 -  drop - like drop, but with no error message sent - silent failure

level can be:
 -    base - basic commands, no info retrieval (later: TCP connections)
 - monitor - base + information retrieval (read-only)
 -   login - base + monitor + login for (future) shutdown sync
 - manager - base + monitor + (future) variable setting
 -     all - match any level

aclname is one of the ACLs you defined earlier.

The password is used in conjunction with logins.  If you set a password on
an access line, any client matched by the corresponding ACL must have 
that password set.  This is only used for "login" level access right now.

Example:
 - localhost gets manager powers
 - another local system gets login powers so it can shutdown (future...)
 - local net systems may monitor to run things like asapm-ups and multimon
 - an abuser is silently dropped
 - everyone not yet covered is denied nicely

ACL localhost 127.0.0.1/32
ACL otherbox 10.16.1.1/32
ACL localnet 10.16.1.0/24
ACL abuser 192.168.255.128/32
ACL all 0.0.0.0/0

ACCESS grant localhost manager magicpass
ACCESS grant otherbox login anotherpass
ACCESS grant localnet monitor
ACCESS drop all abuser 
ACCESS deny all all

Access controls should go from most specific to least specific.  Note that
"otherbox" is technically a member of "localnet", but we want it to have
more permissions so it occurs first.  The first match is the one that is
used for 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.  So, if you want the whole world to have access, add an
explicit allow for it.  Think of it as a big repeating "if-then-else"
structure.
