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?


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.

  • What's the default include/exclude list (empty so nothing is included, I think)? If you include /a, exclude /a/b and include /a/b/c, is /a/b/c watched? Does including a directory always include its contents? – Gilles May 25 '11 at 22:32
  • @Gilles It doesn't know anything about directories, it just takes the complete absolute path and matches it against the regular expression. So <include extension="/a" uid="*" action=".*" retname=".*" /> is going to match every operation that operates on a file whose path contains /a -- it could even be /foo/abc/bar. You probably want to anchor them all with ^ and $, but then you need to include the entire path for it to match – Michael Mrozek May 25 '11 at 22:37
  • @Gilles Not having any rules is actually a special case, so I'll add it to the answer – Michael Mrozek May 25 '11 at 22:38

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.