unionfs merges several directories and directory trees
into one.
You may look at it as looking from above into a stack
of transparent layers, each representing a directory
tree in a different place. Equally named files among
the different layers stack in the same column, the
topmost of them thus hiding those with the same name in
lower layers.
In unionfs terminology, the whole stack is called a
union, with the layers which make up the stack being
called branches. You can add and remove branches on the
fly, and give them read and write attributes. There's
more about it - have a look at
the project's homepage for details.
unionfs has reached a level of maturity good enough
that it is included in various distributions. You can
check a not-so-small list of projects using it at the
above homepage address.
The Nokia770 implementation seems to do equally well.
There's still some risk (as with any system software),
that everything might happen, including bricking your
Nokia770 or turning it into a flying
saucer1, though I
wouldn't exactly expect that. Anyway ... you've been
warned.
For now, let's focus on our trusted Nokia770 and the
(less trusted) set of utilities I've done that make up
mmc-unionfs. They are meant to be simple enough to be
used without much knowledge while not preventing you
from any additional tweaks you might want to apply.
In our 770's hardware, we have two kinds of flash
memory: the fixed one on the 770's mainboard and the one
you're adding by inserting an MMC flash card.
Now if we stack MMC memory on top of,
say. the /var/lib/install or even the
entire /usr tree (having mounted the MMC branch
read/write and the internal flash branch read-only),
their capacity increases by that of the MMC and we can
do whatever we want within those trees without actually
having to touch anything in the built in flash at all.
Even deleting a file which resides in internal flash
memory works this way: if you try to delete a file on a
layer which lacks the 'writable' attribute, an entry is
made into the topmost writable layer above it in a way
which in every respect looks from above (the unified
view) like an empty space, but isn't. If you remove the
upper layer (the branch which carries the 'whiteout' in
unionfs speak), the original file will reappear.
Re-insert your upper branch and it will be gone again.
Modifying files on a read-only branch works as you'd
expect: the data is read from the read-only branch but
on the first write, the data is copied up and the
modification is done to the read-write branch, thus
shadowing from now on the read-only version. All
subsequent accesses will be from and to the read-write
branch. This is known as 'copyup'.
The default structure built up by mmc-unionfs does just
that: It mounts the MMC read-write on top of freely
selectable subtrees of the root fs on the internal
flash, which are left read-only. You aren't constrained
to stay with this setup, however.
I think you've got the basic idea. You can use your
MMC space as if it were part of the internal memory
without having to do nasty things like scattering
symbolic links pointing to places on the MMC all over
your root file system.
You can have several MMCs with several Nokia
'personalities', like one crammed full of utilities and
E-Books for working, and one which leaves more space for
your music, games, photos and other entertainment. Shut
down, put in another MMC, switch on, and your Nokia770
might look very different from a user's perspective.
You may modify whatever parts of the root fs you like
(but keep in mind that running programs may have a very
distinct feeling about this topic if you change their
files by starting a union while they're running - see
below for a short discussion).
If you're checking a new program and the Nokia refuses
to work with the modified set for whatever reason,
simply switch it off, remove the MMC so you're back at
your basic setup, and switch it on again. Re-insert the
MMC, modify the erroneous file on the MMC , remount the
branch on the fly with the mmc-unionfs utility, and
you're ready to test the new setup again.
To run it, you have to prepare your MMC, install the
mmc-union<whatever-version>.deb package
and run (as root) the setup utility. But first take a
glance at the CAVEATS section
below.
Then let's start with -
You have to partition your MMC so it has at least 2
partitions. mmc-unionfs should use an ext2 partition
(it could be done on VFAT, but that wouldn't be very
useful due to its restrictions). The first partition
(/dev/mmcblk0p1) cannot be used for mmc-unionfs
as it is ignored (VFAT, and reserved for the 770's
standard software).
So insert your MMC into a linux box to prepare it. For
an example, I'm usually using three partitions as
follows:
- the first one is the usual VFAT partition for data
storage and data exchange with other computers. It
is rather small on my MMCs, because I don't expect
to have to put much data on it (128...256 MB for a
1G MMC). You might want to use more storage if you
do data exchange with Windows PCs by swapping cards.
- the second one is swap space (24 MB for now - hope
this will change soon).
- the third one is ext2 and occupies the card's
rest. mmc-unionfs doesn't need exclusive access to
it, so it is open to anything you want to put on it.
I'm using it also for general data storage and
exchange, music, e-books, photos and the like.
There are drivers and utilities for Windows which
allow reading/writing ext2/3, but I don't know
much about them. I'm doing most transfers over
the network anyway so the file system doesn't
really matter and using ext2 for the main part of
the MMC has never bitten at me. You might
consider KNOPPIX or another live Linux
distribution on CD/DVD if you don't have a Linux
box at hand.
Use a program like fdisk on GNU/Linux to do
the partitioning (don't forget to set the type code for
the VFAT partition (6) - on the others (83 for swap and
82 for ext2) it won't hurt much if you forget it).
Then use mkfs.vfat for putting a file system
onto the VFAT partition, mkswap to prepare the
swap partition (if any), and
mkfs.ext2 for initializing the ext2 file system.
All of the following steps may also be done on the
Nokia 770 (the above of course too if you have the
necessary software installed).
Now mount the ext2 partition. (If you have more than
one of them, they will later be tried by mmc-unionfs in
ascending order, starting at partition 2, until a
successful mmc-unionfs mount can be made.) Put a
directory named mmc-union it.
cd into it to define your branches there.
That's actually quite simple. Say we want to install
two unions. The first one should
extend /home/user, and the second one
/var/lib/install. Then all you have to do is
to create two empty directories
within mmc-union with the
names #home#user and
#var#lib#install. They will later be filled
with new content during normal use. I'm sure you've got
the point in naming the directories: use the absolute
path name of the tree you want to extend, then simply
replace all slashes ('/') by hash marks
('#'). But take care of their rights:
(#home#user should be owned by user:users
(29999:29999) (chown 100:29999 will do the
job), /var/lib/install belongs to install:users
(100:29999)).
Hash marks (
#) are rarely used in file names.
That's why I've chosen them. But there's a reason why
they are seldom used: They introduce comments in the
shell command language if at the start of a word.
When typing them in, you'll have to put a backslash in
front of the first hash character in order to remove
this special meaning. For the above example, you
actually type in (with all characters as shown below):
mkdir \#home#user \#var#lib#install
mkdir '#home#user' '#var#lib#install'
mkdir "#home#user" "#var#lib#install"
As a side note: the busybox sh (the
Nokia's built-in shell) won't get TAB expansion
right if you hit TAB immediately after a hash
character which is preceded by a backslash.
If one of your original directories contains a hash
mark, insert a literal backslash into the directory
name just before the hash mark in question. You get
it there by typing two backslash characters at the
mkdir shell command line or by quoting as above.
Take some care about the unions you're creating.
It won't do any good if you mount new branches on
top of directories which carry crucial up-to-date
information for processes already running. Let's
take
/var/run for an example. Many processes
put some identification data like their PID there
when they're running and remove it when done.
Mounting the MMC over them will seem to work well at
first - but while reading old data from internal
flash, new and modified data will now be written
onto the MMC. Next time the MMC branch gets
inserted (either during booting or manually), the
old data (including whiteouts) from the MMC will be
there again, possibly masking new content, and thus
indicating running conditions that don't exist any
more.
As a rule of thumb: don't include anything
below /var but
above /var/lib/install. Be careful
about /etc, and about including any other
standard directory in / -
and never ever
include /lib except you definitely know
what you're doing. Don't care
about /var/lib/install and user's home
directories - they should always
work. /tmp is safe only when the union
gets automatically mounted during boot. And
finally, if things go wrong, shut down, remove the
MMC and you are where you've been before.
Now we're done with the MMC. Partitioning and
putting a few directories onto it - that's all. Let's
move on to the
You must be able to gain root access later. (Have a
look at
the Maemo Wiki's HOWTO if you don't know
about this. But keep in mind that mmc-unionfs is work
in progress - and if you don't know how to get root
access, it's probably better to wait for a while until
things have settled more.)
First, install (as usual) the .deb package from the
link on top of this page. This
won't change much, it will just install some files into
/var/lib/install/usr/share/mmc-unionfs,
including a setup script.
Start a shell now, either from remote (ssh) or
by running osso-xterm. Gain root access (by whatever
means you've implemented:
login, sudo sh, su, gainroot).
Make sure the MMC we've prepared above is in place (it need not be
mounted). Now cd to
/var/lib/install/usr/share/mmc-unionfs/setup
and run
./setup
This puts the files into your root file system, then
does some cleanup.
If all seems well, type
mmc-unionfs setup
mmc-unionfs mount
If you get a 'command not found' message, you
should either type in the full path
(/sbin/mmc-unionfs) or make sure /sbin
is in your $PATH by editing .profile
in your home directory.
To see the result, run
df -h
and check for lines starting in 'union+'. You
should now see the unions you've defined showing up with
plenty of room in them. Play around, test.
When you're sure you want to have your unions always
installed during the boot process, type:
mmc-unionfs boot-enable
That's it - you're done.
By the way, you should have a look at the following
commands:
mmc-unionfs --help
mmc-unionfs status
and also at the more general unionfs utility commads,
especially if you're looking for a way to do a more
complex setup, delete and add branches on the fly, and
so on:
unionctl --help
uniondbg --help
If you later decide to change what directory trees are
included in your unions, just
- umount all your unions ('mmc-unionfs umount')
- do whatever you want to the MMC branches (the
directoriy names with the hash marks in the name
within the mmc-unionfs directory on your flash card)
- run 'mmc-unionfs setup', and
- then mount again by issuing
'mmc-unionfs mount'.
