Name: How to use access controls
File: access.txt
Date: 29 October 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 deny, but with no error message sent - silent failure

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

aclname is one of the ACLs you defined earlier.

The password is only checked for certain access levels.  If you set a 
password on an access line, any client matched by the corresponding ACL
must have that password set.  This only applies to "login" and up right
now.

Example:

 - "localbox" and  "otherbox" get login powers so they can participate
   in the synchronized shutdown.  

 - "webserver" gets monitor powers so that things like multimon.cgi work.

 - Another network (10.16.2.x) gets monitor powers since there are
   a bunch of workstations running asapm-ups there.

 - an abuser is silently dropped

 - everyone not yet covered is denied nicely

ACL localbox 10.16.1.1/32
ACL otherbox 10.16.1.2/32
ACL webserver 10.16.1.3/32
ACL classroom 10.16.2.0/24
ACL abuser 192.168.255.128/32
ACL all 0.0.0.0/0

ACCESS grant login localbox magicpass
ACCESS grant login otherbox anotherpass
ACCESS grant monitor webserver
ACCESS grant monitor classroom
ACCESS drop all abuser
ACCESS deny all all

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.  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.
