follow-log-directories 1 user commands nosh
follow-log-directories follow cyclog logs
`follow-log-directories` directory

## Description

`follow-log-directories` follows activity in log directories with the aid of a set of cursors. For each cursor, it monitors the referenced log directory and outputs any log data newer than the cursor to its standard output, writing log messages about its own operation to standard error. It saves the new cursor position as it goes, so that if it is terminated and restarted it can resume at the point where it last left off (as long as that position remains somewhere in the referenced log directory).

directory is a directory of cursor directories. Every subdirectory, or symbolic link to a directory, therein whose name does not start with a dot is a cursor directory.

### Cursor directory

A cursor directory is a way of maintaining a position, a cursor, within a rotating log directory (such as, for example, is maintained by cyclog 1). It is non-intrusive and multiple cursors can reference the same log directory.

A cursor directory has a subdirectory, or (more usually in practice) symbolic link to a directory, that is named `main` and a timestamp file named `last`. See cyclog 1 for the format of the log directory denoted by `main/`.

The cursor position is a TAI64N timestamp, in external form, defaulting to zero if the `last` file is not present or does not contain a parseable TAI64N timestamp as its first line. This is the TAI64N timestamp of the last log entry that has been read from the log. All log entries, and log files, that are timestamped then or older are skipped as the cursor advances.

In order to be comparable to the current cursor position, all log lines in the pointed-to log directory must have valid TAI64N timestamps, all (non-current) log files must have valid TAI64N names, and all lines in a single file must be in strictly increasing order. This is always the case for correctly formatted log directories. Erroneous lines without TAI64N timestamps and incorrectly named files are skipped as the cursor advances.

### Security

The only file that the user running `follow-log-directories` needs write access to is the `last` file, which is updated in place without unlinking. (Operating systems guarantee that the write 2 system call works atomically if certain constraints are met; the update of the timestamp in the `last` file fits within those constraints.) This file is created if it does not exist, so ensure that it exists and is (say) zero length if that user has no write access to the enclosing cursor directory. The user running `follow-log-directories` needs no owner access to anything; but of course needs read access to log files and read+execute access to the cursors directory, the individual cursor directories, and the log directories.

## Author

Jonathan de Boyne Pollard