rewritefs(1) -- mod_rewrite-like FUSE filesystem

Description

rewritefs is a FUSE filesystem similar to web servers mod_rewrite. It can change the name of accessed files on-the-fly.

The short story: I needed a tool to manage my dotfiles. I forked Luc Dufrene's libetc [http://ordiluc.net/fs/libetc/] after it seemed unmaintained. Here is its description:

On my system I had way too much dotfiles:

% ls -d ~/.* | wc -l 421

For easier maintenance I wrote libetc. It is a LD_PRELOAD-able shared library that intercepts file operations: if a program tries to open a dotfile in $HOME, it is redirected to $XDG_CONFIG_HOME (as defined by freedesktop: http://standards.freedesktop.org/basedir-spec/basedir-spec-0.6.html).

You can then store all your config files in $XDG_CONFIG_HOME instead of using zillions dotfiles in $HOME. If $XDG_CONFIG_HOME is not defined the dotfiles are stored in $HOME/.config/

Unfortunately, I eventually run into LD_PRELOAD problems (mainly with programs using dlopen like VirtualBox and screen). So I decided to rewrite it using FUSE, and make it more generic.

Dependencies

fuse3 & pcre. That's all.

To use contexts, you need /proc/(pid)/cmdline. But don't use contexts if you can avoid it !

Installation

make && sudo make install

Configuration

For a complete description of the configuration syntax format, see below.

Make sure that user_allow_other is enabled in /etc/fuse.conf.

Example 1

The following example demonstrates how one can get the program to do what libetc does :

m#^(?!\.)# .
m#^\.(cache|config|local)# .
m#^\.# .config/

That is, all dotfiles will be put in .config/ (without the leading dot), excepting .cache and .local.

Example 2

This example show how to use contexts ; it is like the former, but ignore the rewrite rules for busybox:

m#^(?!\.)# .
m#^\.(cache|config|local)# .
- /^\S*busybox/
/^/ .
- //
m#^\.# .config/

Usage

Once you have written your configuration file, you use rewritefs to mount the "rewritten" filesystem, for example :

rewritefs -o config=/mnt/home/me/.config/rewritefs /mnt/home/me /home/me

Then, accessing to files in /home/me will follow rules defined in your config file.

Directory auto-creation

When using backreferences of in rules of the form…

/(.+) - (.+)/ \1/\2

…it is possible that the directory into which an operation is being redirected does not exist yet. To support such rules, rewritefs may be invoked with the option -o autocreate. This option will cause rewritefs to automatically create all non-existing parent directories when a path is being rewritten.

Note that, due to FUSE limitations, the parent directories will be created using the umask with which rewritefs has been invoked, instead of the umask of the process requesting accessing the file.

Using rewritefs with mount(8) or fstab(5)

rewritefs /mnt/home/me /home/me -o config=/mnt/home/me/.config/rewritefs,allow_other

allow_other and default_permissions is here to allow standards users to access the filesystem with standard permissions.

So, you can use the fstab entry:

/mnt/home/me /home/me fuse.rewritefs config=/mnt/home/me/.config/rewritefs,allow_other 0 0

See mount.fuse(8) for all FUSE options.

Using rewritefs with pam_mount(8)

Let's suppose that you want to use rewritefs to replace libetc (it's its primary goal, after all). You need to mount the rewritefs on your home when you login. This can be achieved with pam_mount.

Let's say you have your raw home dirs in /mnt/home/$USER. Then, to use rewritefs on /home/$USER with configuration file stored at /mnt/home/$USER/.config/rewritefs, you need to add this to pam_mount.xml:

<volume fstype="fuse" path="rewritefs##/mnt/home/%(USER)" mountpoint="~"
     options="config=/mnt/home/%(USER)/.config/rewritefs,allow_other" />

You can add user="me" to limit this to yourself (but think to create symlinks for other users !)

Don't forget to activate pam_mount in your pam configuration too. This is distribution-dependent ; you have to refer to the corresponding documentation.

Caveat Emptor

Using both the original and the rewritten filesystem at the same time is possible, but it is not advised. For example, while file locking works fine both in the original and the rewritten filesystem, two exclusives lock may be obtained on the same file: one on the original file, another on the rewritten file.

FAQ

Q: I installed rewritefs with the default config, and now ls returns me something like that :

ls: cannot access /home/user/.vimrc: No such file or directory
ls: cannot access /home/user/.zshrc: No such file or directory
d????????? ? ? ? ? ? .ssh/

Short answer: You have to manually move .vimrc, zshrc, .ssh/ inside .config before using rewritefs.

Long answer: If .ssh is translated (by the rules you gave to rewritefs) into .config/ssh, and that you didn’t renamed .ssh into .config/ssh yourself (i.e. that .ssh still exists and .config/ssh doesn’t exists on the original filesystem), that’s the intended behavior.

Rewritefs does not rewrite readdir(), since it would need "backwards" rewriting (and that’s not technically possible, since the rules are defined using regular expressions). ls calls readdir(), which returns .ssh. ls then tries to call stat(".ssh") to find metadata (permissions, mtime and so on), which is rewritten into stat(".config/ssh") which does not exists, hence this error.

Configuration syntax format

Regular expressions

The Regexp syntax is similar to Perl. Recognized flags are : i, x, u and g. Example of valid regexps are:

/foo/i
m/fOo/u
m/dev\/null/
m|tata|
m|This\sis
    \san\sextended
    \sregexep|x

Note that m{foo} is not recognized ; you must use m{foo{

i and x has the same meaning than in Perl. u means "use utf-8" (both for pattern and input string).

The g flag is described in the "Rewrite rule" section.

Command line match

Syntax: - REGEXP

Limit the following rules to programs matching REGEXP (comparing with the content of /proc/(pid)/cmdline, replacing null characters with spaces)

Rewrite rule

Syntax: REGEXP rewritten-path

A file matching REGEXP will be rewritten to rewritten-path. To be more accurate, the matched data will be replaced by rewritten-path in the filename. For example, with this rule:

/fo/ ba

accessing to foo will be translated into bao. Warning, if you don't start your regexp with ^, "information" will be rewritten into "inbamation" !

If rewritten-path is ., it means "don't rewrite anything".

. and .. will never be proposed to be translated.

You can access captured groups as backreferences (\1, \2, …).

A regular expression can be written in more than one line, in particular in conjunction with the x flag.

The g flag indicates that the substition is global, and not limited to the first match. Consider this simple rule:

/:/ -

Applied to A:B:C, the rewritten path will be A-B:C. With the g flag, the rewritten path will be A-B-C.

Comment

A line starting with "#"

Performances

Some rules to keep the overhead smallest possible :

• use the fast pruning technique described in config.example
• avoid using contexts whenever you can
• avoid using backreferences in your regexp (\1)
• avoid using backreferences in your rewritten path. You can generally avoid them by using lookarounds.

For example, instead of writing:

/\.(gtk-bookmarks|mysql_history)/ .cache/\1

you can write the more efficient:

/\.(?=gtk-bookmarks|mysql_history)/ .cache/

I urge you to read "Mastering regular expressions" if you want to make rules substantially different from the example.