Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
While it's not strictly tied to OSTree, let's move https://github.com/cgwalters/rofiles-fuse in here because: - It's *very* useful in concert with OSTree - It's tiny - We can reuse OSTree's test, documentation, etc. infrastructure One thing to consider also is that at some point we could experiment with writing a FUSE filesystem for OSTree. This could internalize a better equivalent of `--link-checkout-speedup`, but on the other hand, the cost of walking filesystem trees for these types of operations is really quite small. But if we did decide to do more FUSE things in OSTree, this is a step towards that too.
- Loading branch information
Showing
9 changed files
with
870 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,104 @@ | ||
| <?xml version='1.0'?> <!--*-nxml-*--> | ||
| <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | ||
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> | ||
|
|
||
| <!-- | ||
| Copyright 2016 Colin Walters <walters@verbum.org> | ||
| This library is free software; you can redistribute it and/or | ||
| modify it under the terms of the GNU Lesser General Public | ||
| License as published by the Free Software Foundation; either | ||
| version 2 of the License, or (at your option) any later version. | ||
| This library is distributed in the hope that it will be useful, | ||
| but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
| MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
| Lesser General Public License for more details. | ||
| You should have received a copy of the GNU Lesser General Public | ||
| License along with this library; if not, write to the | ||
| Free Software Foundation, Inc., 59 Temple Place - Suite 330, | ||
| Boston, MA 02111-1307, USA. | ||
| --> | ||
|
|
||
| <refentry id="ostree"> | ||
|
|
||
| <refentryinfo> | ||
| <title>rofiles-fuse</title> | ||
| <productname>rofiles-fuse</productname> | ||
|
|
||
| <authorgroup> | ||
| <author> | ||
| <contrib>Developer</contrib> | ||
| <firstname>Colin</firstname> | ||
| <surname>Walters</surname> | ||
| <email>walters@verbum.org</email> | ||
| </author> | ||
| </authorgroup> | ||
| </refentryinfo> | ||
|
|
||
| <refmeta> | ||
| <refentrytitle>rofiles-fuse</refentrytitle> | ||
| <manvolnum>1</manvolnum> | ||
| </refmeta> | ||
|
|
||
| <refnamediv> | ||
| <refname>rofiles-fuse</refname> | ||
| <refpurpose>Use FUSE to create a view where directories are writable, files are immutable</refpurpose> | ||
| </refnamediv> | ||
|
|
||
| <refsynopsisdiv> | ||
| <cmdsynopsis> | ||
| <command>rofiles-fuse SRCDIR MNTPOINT</command> | ||
| </cmdsynopsis> | ||
| </refsynopsisdiv> | ||
|
|
||
| <refsect1> | ||
| <title>Description</title> | ||
|
|
||
| <para> | ||
| Creating a checkout from an OSTree repository by default | ||
| uses hard links, which means an in-place mutation to any | ||
| file corrupts the repository and all checkouts. This can be | ||
| problematic if one wishes to run arbitrary programs against | ||
| such a checkout. For example, RPM <literal>%post</literal> | ||
| scripts or equivalent. | ||
| </para> | ||
|
|
||
| <para> | ||
| In the case where one wants to create a tree commit derived | ||
| from other content, using <command>rofiles-fuse</command> in | ||
| concert with <command>ostree commit | ||
| --link-checkout-speedup</command> (or the underlying API) | ||
| can ensure that only new files are checksummed. | ||
| </para> | ||
|
|
||
| </refsect1> | ||
|
|
||
| <refsect1> | ||
| <title>Example: Update an OSTree commit</title> | ||
| <programlisting> | ||
| # Initialize a checkout and mount | ||
| $ ostree --repo=repo checkout somebranch branch-checkout | ||
| $ mkdir mnt | ||
| $ rofiles-fuse branch-checkout mnt | ||
|
|
||
| # Now, arbitrary changes to mnt/ are reflected in branch-checkout | ||
| $ echo somenewcontent > mnt/anewfile | ||
| $ mkdir mnt/anewdir | ||
| $ rm mnt/someoriginalcontent -rf | ||
|
|
||
| # Commit and cleanup | ||
| $ fusermount -u mnt | ||
| $ ostree --repo=repo commit --link-checkout-speedup -b somebranch -s 'Commit new content' --tree=dir=branch-checkout | ||
| $ rm mnt branch-checkout -rf | ||
| </programlisting> | ||
| </refsect1> | ||
|
|
||
| <refsect1> | ||
| <title>See Also</title> | ||
| <para> | ||
| <citerefentry><refentrytitle>ostree</refentrytitle><manvolnum>1</manvolnum></citerefentry> | ||
| </para> | ||
| </refsect1> | ||
| </refentry> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| # Copyright (C) 2016 Colin Walters <walters@verbum.org> | ||
| # | ||
| # This library is free software; you can redistribute it and/or | ||
| # modify it under the terms of the GNU Lesser General Public | ||
| # License as published by the Free Software Foundation; either | ||
| # version 2 of the License, or (at your option) any later version. | ||
| # | ||
| # This library is distributed in the hope that it will be useful, | ||
| # but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
| # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
| # Lesser General Public License for more details. | ||
| # | ||
| # You should have received a copy of the GNU Lesser General Public | ||
| # License along with this library; if not, write to the | ||
| # Free Software Foundation, Inc., 59 Temple Place - Suite 330, | ||
| # Boston, MA 02111-1307, USA. | ||
|
|
||
| bin_PROGRAMS += rofiles-fuse | ||
|
|
||
| rofiles_fuse_SOURCES = src/rofiles-fuse/main.c | ||
|
|
||
| rofiles_fuse_CFLAGS = $(AM_CFLAGS) -D_GNU_SOURCE -D_FILE_OFFSET_BITS=64 $(BUILDOPT_FUSE_CFLAGS) $(OT_INTERNAL_GIO_UNIX_CFLAGS) -I$(srcdir)/libglnx $(NULL) | ||
| rofiles_fuse_LDADD = libglnx.la $(BUILDOPT_FUSE_LIBS) $(OT_INTERNAL_GIO_UNIX_LIBS) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| rofiles-fuse | ||
| ============ | ||
|
|
||
| Create a mountpoint that represents an underlying directory hierarchy, | ||
| but where non-directory inodes cannot have content or xattrs changed. | ||
| Files can still be unlinked, and new ones created. | ||
|
|
||
| This filesystem is designed for OSTree and other systems that create | ||
| "hardlink farms", i.e. filesystem trees deduplicated via hardlinks. | ||
|
|
||
| Normally with hard links, if you change one, you change them all. | ||
|
|
||
| There are two approaches to dealing with that: | ||
| - Copy on write: implemented by BTRFS, overlayfs, and http://linux-vserver.org/util-vserver:Vhashify | ||
| - Make them read-only: what this FUSE mount does | ||
|
|
||
| Usage | ||
| ===== | ||
|
|
||
| Let's say that you have immutable data in `/srv/backups/20150410`, and | ||
| you want to update it with a new version, storing the result in | ||
| `/srv/backups/20150411`. Further assume that all software operating | ||
| on the directory does the "create tempfile and `rename()`" dance | ||
| rather than in-place edits. | ||
|
|
||
| $ mkdir -p /srv/backups/mnt # Ensure we have a mount point | ||
| $ cp -al /srv/backups/20150410 /srv/backups/20150411 | ||
| $ rofiles-fuse /srv/backups/20150411 /srv/backups/mnt | ||
|
|
||
| Now we have a "rofiles" mount at `/srv/backups/mnt`. If we try this: | ||
|
|
||
| $ echo new doc content > /srv/backups/mnt/document | ||
| bash: /srv/backups/mnt/document: Read-only file system | ||
|
|
||
| It failed because the `>` redirection operator will try to truncate | ||
| the existing file. If instead we create `document.tmp` and then | ||
| rename it atomically over the old one, it will work: | ||
|
|
||
| $ echo new doc content > /srv/backups/mnt/document.tmp | ||
| $ mv /srv/backups/mnt/document.tmp /srv/backups/mnt/document | ||
|
|
||
| Let's unmount: | ||
|
|
||
| $ fusermount -u /srv/backups/mnt | ||
|
|
||
| Now we have two directories `/srv/backups/20150410` | ||
| `/srv/backups/20150411` which share all file storage except for the | ||
| new document. |
Oops, something went wrong.