Second generation ACL blocker notes
12-May-2010

Here are some notes on the second generation ACL blocker.

High level requirements:

ACL blocker communication details

Clients will talk to the ACL blocker via an inet socket on a port on localhost. It is possible to use telnet to interact with the daemon.

The command line clients will be implemented as expect scripts. Initially, Bro will use these scripts. Ultimately, Bro will use the C library interface and keep a connection open to the ACL blocker to save time.

Commands include a cookie (32-bit unsigned value). This cookie is included in response messages from the ACL blocker to allow clients to match return status with requests. The value zero (0) may be used if this feature is not needed.

Commands may be streamed without waiting for status.

ACL blocker interface

Communications with the ACL blocker occurs over a socket. Commands consist of a keyword, a cookie (32-bit unsigned value) and optional arguments. In addition, many commands (e.g. drop) optionally use multi-line text (see below).

Each command issued (eventually) results in a response and may be sent out of order. Responses consist of a raw unix timestamp (seconds and microseconds midnight, January 1, 1970), the cookie value and a status word. Responses can return multi-line text containing error messages, informational messages, comments or other text.

Response timestamps document when the requested action was taken. Note that some routers accept and commit an ACL change to configuration memory but must perform additional processing before the change actually takes effect.

Command and response lines that need to submit or return multi-line text end with a trailing dash ("-") character. Text is then read, stripping leading periods ("."), until a period on a line by itself is read.

When the ACL blocker first receives a connection from a client, it sends an initial message to let the client know it's ready for work. For example:

1024631441.934568 0 acld -
ready for action
.

As with response to a regular client command, a timestamp is displayed. Since there is no cookie value to give back, zero is used.

Unknown commands (and other garbage) may not have comments and their cookies are ignored. Responses will always use a cookie value of zero and may include a comment indicating what the problem was. For example:

junk 554
1078353422.923969 0 unknown-failed -
unknown command "junk"
.

ACL blocker client command summary

Command Arguments
drop
restore
query
cookie addr
cookie addr/netwidth
cookie addr netmask
blockhosthost
restorehosthost
cookie addr1 addr2
querywhitelist cookie addr
cookie addr/netwidth
cookie addr netmask
droptcpport
dropudpport
restoretcpport
restoreudpport
cookie port
droptcpdsthostport
dropudpdsthostport
permittcpdsthostport
permitudpdsthostport
restoretcpdsthostport
restoreudpdsthostport
unpermittcpdsthostport
unpermitudpdsthostport
cookie addr port
addwhitelist
remwhitelist
cookie addr
cookie addr/netwidth
cookie addr netmask
nullzero
nonullzero
cookie addr
cookie addr/netwidth
cookie addr netmask
listacl
compact
cookie acl
listroute
state
reload
help
cookie

ACL blocker client command details

Expect script summary

Command Arguments
drop
restore
addr acl seq
addr/netwidth acl seq
blockhosthost
restorehosthost
addr1 addr2
droptcpport
dropudpport
restoretcpport
restoreudpport
port acl seq
droptcpdsthostport
dropudpdsthostport
permittcpdsthostport
permitudpdsthostport
restoretcpdsthostport
restoreudpdsthostport
unpermittcpdsthostport
unpermitudpdsthostport
addr port acl seq
nonullzero
nullzero
addr
addr/netwidth
login addr cuser cpass1 cpass2 euser epass1 epass2
listacl acl interface
ayt
listroute
logout
sync
 

Expect script details

This is a really low level interface and does not contain features of the higher level interface such as timestamps.

The following expect procedures must be defined before the ACL blocker can support a router:

Implementation details

When the ACL blocker starts up it: