==================
README for trackfs
==================

Trackfs is a small program that tracks file system changes --
creation, update and removal of fs objects -- of another program
(or group of programs).  It is similar to `installwatch', but works
quite differently:  While installwatch uses LD_PRELOAD to intercept
library functions like open() and unlink(), trackfs runs the child
program(s) with tracing enabled and tracks the system calls they
make.

If course this has an impact on performance: with trackfs, programs run
several times slower.  But since trackfs is not intended for general
use but rather for installation tasks, speed probably doesn't matter
as much as one might think.

On the other hand, there's a significant advantage: trackfs also
works with statically linked binaries. The LD_PRELOAD approach may
miss transactions, but with ptrace() you'll get all of them.

There are two operating modes: With the `-l <logfile>' option,
trackfs will log fs changes to the specified file. All entries have the
(printf-style) format "%c %s\n", with the single character indicating
the kind of change -- c(reate), d(elete), u(pdate) or t(emporary)
-- and the string reporting the full path of the corresponding
object. Note that the logfile is "compressed", that is, multiple
transactions dealing with the same object will be grouped together
and reported as one "resulting" transaction. E.g. if you first
delete a file and then re-create it, an update will be reported.
If a file is first created and then deleted, the path is reported as
temporary instead.

The option `-b <backup-file>' instructs trackfs to backup every file
that is probably going to be modified. In some cases, the backup may
not be necessary -- better safe than sorry -- because the modification
fails, e.g. due to insufficient permissions. You'll have to consult
the log file in order to find out which files were actually modified
and will have to be restored if something failed.

The option `-I <pattern>' instructs trackfs to ignore file names that
match <pattern>. It will not backup those files, nor will it report
them in the logfile. Note that <pattern> is a standard shell pattern,
not a regular expression. It also has the same semantics as in the
shell, that is, "/" is matched only by an explicit "/", and periods
at the beginning of a name are not matched by "?" or "*".

If the command you intend to run under trackfs' control includes
options, you probably have to put the `--' pseudo-option in front
of it:

	trackfs $trackfs_options -- command $command_options $args

This is because getopt() may re-order arguments and options on some
systems (the GNU version does so by default).

I have developed and tested trackfs in a Linux/i386 environment, but
it also works on x86_64 and -- as of version 0.1.0 -- ARM (EABI) Linux
systems. Everything else may require more or less hack^H^H^H^Hporting.

Since trackfs makes use of the ptrace(PTRACE_SETOPTIONS) system
call, it will be hard to port to non-Linux systems, and it won't work
with old (< 2.6.x) kernels either.

If your system supports the new (as of 2012) x32 ABI, i.e., if
<asm/unistd_x32.h> is present, trackfs for x86_64 should handle x32
binaries as well. Please note that you can't compile trackfs itself
in x32 mode. Well, actually, you can, if you disable my safeguards,
but it's unlikely that the program will work. ;)

Comments, suggestions and bug reports are welcome;
please send e-mail to <trackfs@mr511.de>.

Oh, I forgot to tell you how to compile and install trackfs:

	./configure
	make
	make install

Of course, trackfs will track its own installation procedure:
Have a look at "install.log" and/or "backup.cpio" :)

*** Note to Suse 10.1 users (perhaps obsolete):

Trackfs doesn't work correctly on x86_64 systems running the Suse
2.6.16.13-4 kernel. There's a bug in arch/x86_64/kernel/entry.S that
causes syscall_trace_leave() to be called twice, which messes up the
syscall entry/exit detection of the program. Vanilla 2.6.16 or 2.6.17
kernels work fine.

Michael "Tired" Riepe
