LoggedFS configuration file syntax

Question

What is the syntax of the LoggedFS configuration file?

_{The official documentation only had usage instructions for the loggedfs command and a configuration file example. Ok, it's XML, but what are all the possible tags and attributes and what do they mean?}

Answer 1

I poked through Config.cpp, the file responsible for parsing the configuration. The example configuration actually does a pretty good job of capturing the available options -- there aren't very many

When I refer to "the example output" below, I'm talking about this line (pulled at random from the sample page):

17:29:35 (src/loggedfs.cpp:136) getattr /var/ {SUCCESS} [ pid = 8700 kded [kdeinit] uid = 1000 ]

---

The root tag is <loggedFS>. It has two optional attributes:

• logEnabled is a string -- "true" means it should actually output log info; anything else disables all logging. Defaults to "true", since that's kind of the whole point of the program
• printProcessName is a string -- "true" means the log output will include the process name, anything else means it won't. Defaults to "true". In the example output, kded [kdeinit] is the process name

The only child nodes it cares about are <include> and <exclude>. In the example they group those under <includes> and <excludes> blocks, but those are ignored by the parser (as are any other nodes except <include> and <exclude>).

Naturally, <include> rules cause it to output the log line if they match, while <exclude> lines cause it not to. In the event of overlap, <exclude> overrides <include>. Normally you need at least one <include> rule to match for an event to be logged, but an exception is if there are 0 <include> rules -- then all events are logged, even if there are matching <exclude> lines.

Both <include> and <exclude> take the same attributes:

• extension is a regular expression that is matched against the absolute path of the file that was accessed/modified/whatever (extension is a rather poor name, but I guess that's the common usage). For example, if you touch /mnt/loggedfs/some/file, the regular expression in extension would need to (partial) match /mnt/loggedfs/some/file
• uid is a string that contains either an integer or *. The rule only matches a given operation if the owner of the process that caused the operation has the specified user ID (* naturally means any user ID matches). In the example output, 1000 is the uid
• action is the specific type of operation performed on the filesystem. In the example output, getattr is the action. The possible actions are:
  • access
  • chmod
  • chown
  • getattr
  • link
  • mkdir
  • mkfifo
  • mknod
  • open
  • open-readonly
  • open-readwrite
  • open-writeonly
  • read
  • readdir
  • readlink
  • rename
  • rmdir
  • statfs
  • symlink
  • truncate
  • unlink
  • utime
  • utimens
  • write
• retname is a regular expression. If the return code of the actual filesystem operation performed by LoggedFS is 0, the regular expression is matched against the string SUCCESS. A non-zero return code causes it to match against FAILURE. Those are the only possible values, so most likely you're either going to hardcode SUCCESS, FAILURE, or use .* if you want both. In the example output, SUCCESS is the retname

Unlike with the <loggedFS> attributes, these have no defaults. Also, while the parser will recognize unknown attributes and error out, it does not detect missing attributes, so if you forget an attribute it will use uninitialized memory.