Author: marrs
Date: Wed Apr 25 15:55:29 2012
New Revision: 1330368
URL: http://svn.apache.org/viewvc?rev=1330368&view=rev
Log:
Added initial audit log protocol design.
Added:
ace/site/trunk/content/dev-doc/design/auditlog-protocol.mdtext
Added: ace/site/trunk/content/dev-doc/design/auditlog-protocol.mdtext
URL:
http://svn.apache.org/viewvc/ace/site/trunk/content/dev-doc/design/auditlog-protocol.mdtext?rev=1330368&view=auto
==============================================================================
--- ace/site/trunk/content/dev-doc/design/auditlog-protocol.mdtext (added)
+++ ace/site/trunk/content/dev-doc/design/auditlog-protocol.mdtext Wed Apr 25
15:55:29 2012
@@ -0,0 +1,49 @@
+Title: Audit Log Protocol
+
+Audit logs record life cycle changes on targets. As such, an audit log can be
used to see changes over time and track what is actually on a target. This
design describes the protocol to exchange audit log information.
+
+Each target has an audit log. If the log somehow gets lost on the target, it
will generate a new log with a new unique ID. A log contains entries, where
each entry gets a sequence number.
+
+Protocol
+========
+
+The audit log protocol consists of three commands. The first command can be
used for two parties to exchange information about available audit log entry
sequence numbers. The other two commands allow you to send and receive data.
+
+Querying log information
+========================
+
+This command can be used to exchange information about available audit log
entry sequence numbers. Information is exchanged between either a target and a
(relay) server, or a relay server and a server. You ask the other party what
sequence numbers it has, either for a specific target or for all targets. The
result is a collection of sequence numbers. You can then act on that, sending
the other party the entries it's missing and asking for entries you don't have.
+
+* `GET auditlog/query` - returns a full list of sequence numbers
+* `GET auditlog/query?gwid=myid&logid=2007-07-01` - returns sequence numbers
for a specific target
+* `GET auditlog/query?filter=(vendor='luminis')` - returns sequence numbers
for any target that matches the filter
+
+### About queries
+
+Queries (for log information or entries) come in three forms:
+
+1. Without any filter, you simply get everything.
+2. With a filter on certain keys, all values of specified keys will have to
match.
+3. With an LDAP filter, where you can filter on arbitrary keys and use
compound expressions and pattern matching.
+
+Sending log information
+=======================
+
+By sending log information, you're pushing it to the other party. You will
probably first have figured out, by querying, what data actually needs to be
sent.
+
+* POST auditlog/send - returns status (ok, not ok)
+
+The data gets sent in the following format:
+
+ gwid, logid, seqnr, eventnumber, type (, key, value)*
+
+Data is terminated by '\n' (a new-line).
+
+Receiving log information
+=========================
+
+Here you're asking the other party for data. As part of the request, you can
ask for specific information about one or more targets. If you're not specific,
you will get everything.
+
+* `GET auditlog/receive` - returns list/collection of elements
+* `GET auditlog/receive?gwid=myid` - (see querying)
+* `GET auditlog/receive?filter=(region='asia')` - ...
\ No newline at end of file
