rewritefs.1

.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "REWRITEFS" "1" "January 2020" "" ""
.
.SH "NAME"
\fBrewritefs\fR \- mod_rewrite\-like FUSE filesystem
.
.SH "Description"
\fBrewritefs\fR is a FUSE filesystem similar to web servers mod_rewrite\. It can change the name of accessed files on\-the\-fly\.
.
.P
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:
.
.P
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\.
.
.SH "Dependencies"
fuse3 & pcre\. That\'s all\.
.
.P
To use contexts, you need /proc/(pid)/cmdline\. But don\'t use contexts if you can avoid it !
.
.SH "Installation"
.
.nf

make && sudo make install
.
.fi
.
.SH "Configuration"
For a complete description of the configuration syntax format, see below\.
.
.P
Make sure that \fBuser_allow_other\fR is enabled in \fB/etc/fuse\.conf\fR\.
.
.SS "Example 1"
The following example demonstrates how one can get the program to do what libetc does :
.
.IP "" 4
.
.nf

m#^(?!\e\.)# \.
m#^\e\.(cache|config|local)# \.
m#^\e\.# \.config/
.
.fi
.
.IP "" 0
.
.P
That is, all dotfiles will be put in \fB\.config/\fR (without the leading dot), excepting \fB\.cache\fR and \fB\.local\fR\.
.
.SS "Example 2"
This example show how to use contexts ; it is like the former, but ignore the rewrite rules for busybox:
.
.IP "" 4
.
.nf

m#^(?!\e\.)# \.
m#^\e\.(cache|config|local)# \.
\- /^\eS*busybox/
/^/ \.
\- //
m#^\e\.# \.config/
.
.fi
.
.IP "" 0
.
.SH "Usage"
Once you have written your configuration file, you use \fBrewritefs\fR to mount the "rewritten" filesystem, for example :
.
.IP "" 4
.
.nf

rewritefs \-o config=/mnt/home/me/\.config/rewritefs /mnt/home/me /home/me
.
.fi
.
.IP "" 0
.
.P
Then, accessing to files in /home/me will follow rules defined in your config file\.
.
.SS "Directory auto\-creation"
When using backreferences of in rules of the form…
.
.IP "" 4
.
.nf

/(\.+) \- (\.+)/ \e1/\e2
.
.fi
.
.IP "" 0
.
.P
…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 \fB\-o autocreate\fR\. This option will cause rewritefs to automatically create all non\-existing parent directories when a path is being rewritten\.
.
.P
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\.
.
.SH "Using rewritefs with mount(8) or fstab(5)"
.
.nf

rewritefs /mnt/home/me /home/me \-o config=/mnt/home/me/\.config/rewritefs,allow_other
.
.fi
.
.P
allow_other and default_permissions is here to allow standards users to access the filesystem with standard permissions\.
.
.P
So, you can use the fstab entry:
.
.IP "" 4
.
.nf

/mnt/home/me /home/me fuse\.rewritefs config=/mnt/home/me/\.config/rewritefs,allow_other 0 0
.
.fi
.
.IP "" 0
.
.P
See \fBmount\.fuse(8)\fR for all FUSE options\.
.
.SH "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\.
.
.P
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:
.
.IP "" 4
.
.nf

<volume fstype="fuse" path="rewritefs##/mnt/home/%(USER)" mountpoint="~"
     options="config=/mnt/home/%(USER)/\.config/rewritefs,allow_other" />
.
.fi
.
.IP "" 0
.
.P
You can add user="me" to limit this to yourself (but think to create symlinks for other users !)
.
.P
Don\'t forget to activate pam_mount in your pam configuration too\. This is distribution\-dependent ; you have to refer to the corresponding documentation\.
.
.SH "FAQ"
\fBQ:\fR I installed rewritefs with the default config, and now \fBls\fR returns me something like that :
.
.IP "" 4
.
.nf

ls: cannot access /home/user/\.vimrc: No such file or directory
ls: cannot access /home/user/\.zshrc: No such file or directory
d????????? ? ? ? ? ? \.ssh/
.
.fi
.
.IP "" 0
.
.P
\fBShort answer:\fR You have to manually move \fB\.vimrc\fR, \fBzshrc\fR, \fB\.ssh/\fR inside \fB\.config\fR before using \fBrewritefs\fR\.
.
.P
\fBLong answer:\fR If \fB\.ssh\fR is translated (by the rules you gave to rewritefs) into \fB\.config/ssh\fR, and that you didn’t renamed \fB\.ssh\fR into \fB\.config/ssh\fR yourself (i\.e\. that \fB\.ssh\fR still exists and \fB\.config/ssh\fR doesn’t exists on the original filesystem), that’s the intended behavior\.
.
.P
Rewritefs does not rewrite \fBreaddir()\fR, since it would need "backwards" rewriting (and that’s not technically possible, since the rules are defined using regular expressions)\. \fBls\fR calls \fBreaddir()\fR, which returns \fB\.ssh\fR\. \fBls\fR then tries to call \fBstat("\.ssh")\fR to find metadata (permissions, mtime and so on), which is rewritten into \fBstat("\.config/ssh")\fR which does not exists, hence this error\.
.
.SH "Configuration syntax format"
.
.SS "Regular expressions"
The Regexp syntax is similar to Perl\. Recognized flags are : \fBi\fR, \fBx\fR, \fBu\fR and \fBg\fR\. Example of valid regexps are:
.
.IP "" 4
.
.nf

/foo/i
m/fOo/u
m/dev\e/null/
m|tata|
m|This\esis
    \esan\esextended
    \esregexep|x
.
.fi
.
.IP "" 0
.
.P
Note that m{foo} is not recognized ; you must use m{foo{
.
.P
\fBi\fR and \fBx\fR has the same meaning than in Perl\. \fBu\fR means "use utf\-8" (both for pattern and input string)\.
.
.P
The \fBg\fR flag is described in the "Rewrite rule" section\.
.
.SS "Command line match"
Syntax: \fB\-\fR \fIREGEXP\fR
.
.P
Limit the following rules to programs matching REGEXP (comparing with the content of /proc/(pid)/cmdline, replacing null characters with spaces)
.
.SS "Rewrite rule"
Syntax: \fIREGEXP\fR \fIrewritten\-path\fR
.
.P
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:
.
.IP "" 4
.
.nf

/fo/ ba
.
.fi
.
.IP "" 0
.
.P
accessing to foo will be translated into bao\. Warning, if you don\'t start your regexp with \fB^\fR, "information" will be rewritten into "inbamation" !
.
.P
If rewritten\-path is \fB\.\fR, it means "don\'t rewrite anything"\.
.
.P
\&\. and \.\. will never be proposed to be translated\.
.
.P
You can access captured groups as backreferences (\fB\e1\fR, \fB\e2\fR, …)\.
.
.P
A regular expression can be written in more than one line, in particular in conjunction with the \fBx\fR flag\.
.
.P
The \fBg\fR flag indicates that the substition is global, and not limited to the first match\. Consider this simple rule:
.
.IP "" 4
.
.nf

/:/ \-
.
.fi
.
.IP "" 0
.
.P
Applied to \fBA:B:C\fR, the rewritten path will be \fBA\-B:C\fR\. With the \fBg\fR flag, the rewritten path will be \fBA\-B\-C\fR\.
.
.SS "Comment"
A line starting with "#"
.
.SS "Performances"
Some rules to keep the overhead smallest possible :
.
.IP "\(bu" 4
use the fast pruning technique described in config\.example
.
.IP "\(bu" 4
avoid using contexts whenever you can
.
.IP "\(bu" 4
avoid using backreferences in your regexp (\e1)
.
.IP "\(bu" 4
avoid using backreferences in your rewritten path\. You can generally avoid them by using lookarounds\.
.
.IP "" 0
.
.P
For example, instead of writing:
.
.IP "" 4
.
.nf

/\e\.(gtk\-bookmarks|mysql_history)/ \.cache/\e1
.
.fi
.
.IP "" 0
.
.P
you can write the more efficient:
.
.IP "" 4
.
.nf

/\e\.(?=gtk\-bookmarks|mysql_history)/ \.cache/
.
.fi
.
.IP "" 0
.
.P
I urge you to read "Mastering regular expressions" if you want to make rules substantially different from the example\.