Supermount README
=================
Running supermount
------------------
To run supermount, compile and install a kernel with the supermount
patches and select "Y" to the question
Supermount removable media support (CONFIG_SUPERMOUNT) [Y/n/?]
when you run "make config". You mount a supermount filesystem with
the normal mount command, using the syntax
mount -t supermount -o <superfs-options>,--,<subfs-options> none <mpt>
or by adding correpsonding line to /etc/fstab
none <mpt> supermount <superfs-options>,--,<subfs-options> 0 0
where
<superfs-options> are the options you want to pass to supermount
itself. These are described below.
<subfs-options> are the options you want supermount to pass to the
dismountable filesystem underneath.
<mpt> is the mount point where you want your removable media to be
mounted.
WARNING: in the above description `none' is literal word. While device
is ignored by supermount itself, using real files in this place (real
device name or mount point directory name) is known to cause problems.
Some programs - fuser is one of them - will try to descend into filesystem
if dev can be statted, thus making supermount to attempt to access media.
This is annoying at best - in the worst case it can take very long time
during startup or shutdown.
Notice that you do not directly specify the block device you are going
to mount on the mount command line. This is because the supermount
filesystem is NOT connected to a block device; rather, supermount is
responsible for connecting a separate filesystem to the block device.
You specify the sub-filesystem and block device name by providing the
<superfs-options> field, where the following options are currently
recognised:
* fs=<filesystem-type> [default is "auto"]
Specify the subfilesystem type. Not every filesystem type has
been tested. If you use `auto', it will try the following filesystems
in order:
"udf"
"iso9660"
"ext2"
"vfat"
"msdos"
It is also possible to give list of types separated by `:', like
fs=ext2:vfat
- or -
fs=udf:iso9660
* dev=<block-device> [no default, mandatory]
Specify the block device on which the subfs is to be mounted.
* tray_lock={always,onwrite,never} [default is "onwrite"]
Specify when supermount is to prevent media removal. `always' means
on every access (it was default in earlier versions), `onwrite' means only
for write access and `never' means never :) `onwrite' and `never' are the
same for ro media like CD-ROM. It is not clear when `never' is actually useful,
it is presented for completeness only.
* debug[=<bitmap>] [default is no debug]
Enable debugging code in the supermount filesystem, if
the debug option was enabled at compile time. By default, debugging
code is compiled into the kernel but is disabled until a debug mount
option is seen. <bitmap> is the combination of debug flags, following
flags are possible:
0x001 - "generic" debug (used by supermount_debug) - default
0x002 - trace dentry.c
0x004 - trace file.c
0x008 - trace filemap.c
0x010 - trace mediactl.c
0x020 - trace namei.c
0x040 - trace subfs.c
0x080 - trace super.c
Trace flags turn on tracing of functions in correpsonding files.
"Generic" debug flag is tested in supermount_debug; for compatibility,
if no flags are specified, this flag is set.
* '--'
All options after the option string '--' will be passed
directly to the subfilesystem when it gets mounted.
Errors
------
In addition to "normal" errors during file operations supermount may
return following error codes:
* No medium found
You attempt to access supermounted filesystem when there is no
medium inserted
* Wrong medium type
(Not really generated by supermount) You attempt to mount CD
without data tracks
* Stale NFS file handle
You attempt to use file handle after medium has been changed.
* No such device or address
(Not really generated by supermount) device specified in
dev=<device> option does not exist. Also some drivers return this
error instead of "No medium found", one example being floppy driver.
* Device or resource busy
(Not really generated by supermount) device is already mounted.
Supermount prevents double mount even if kernel otherwise would make it
possible.
* No such file or directory
(Not really generated by supermount) file name specified by
dev=<device> option does not exist
* Operation not permitted
You attempt to access subfs that is currently disabled
/proc support
-------------
If kernel has been compiled with procfs support, supermount will provide
/proc interface to read subfs status and to control some aspects of subfs.
The following files are created under /proc/fs/supermount:
* version (ro)
Shows supermount version.
* subfs (rw)
Reading this file returns list of all subfs status. One line for
every subfs is returned; the format is
<devname> disabled
- or -
<devname> unmounted
- or -
<devname> mounted readcount writecount
where <devname> is the string passed in `dev=' parameter during mount.
`readcount' is number of current subfs "users" needing ro access; `writecount'
is the number of "users" needing rw mode. It is mostly the number of open
files, but inode operations also add to these counts. Those operations
are normally short-lived to be seen.
Writing this file changes subfs status; the following commands are
suported:
<devname> [disable|enable] [release [force]]
`disable' will disable subfs (i.e. any futher attempt to mount is rejected).
Subfs must be unmounted; use `disable release' or `disable release force' to
unmount and disable at the same time.
`enable' will enable disabled subfs, it has no effect if subfs is already
enabled.
`release' will unmount subfs unless it is busy (opencount > 0). To unmount
busy subfs add `force'; the effect is very much as if media change has been
detected (with the difference that subfs will be cleanly unmounted).
Some basic sanity checks are performed, i.e. it is impossible to specify
both `enable' and `disable' or `force' without `release'.
Internals/Locking
-----------------
THIS SECTION IS PROBABLY INCOMPLETE. CORRECTIONS ARE WELCOME.
Supermount itself is using two locks and relies on two more locking rules
as implemented by kernel.
* supermount_proc_sem
Global mutex used to protect list of sbi during access to
/proc/fs/supermount/subfs
* sbi->sem
Per-filesystem mutex that protects subfs state (mounted/unmounted).
Any changes to subfs state (mounting, unmouting, adding or removing file,
dentry or inode) happen under this mutex.
* inode->i_sem (see Documentation/filesystem/Locking)
Per-inode mutex used by VFS to serialize inode unlink operation.
Supermount relies on the fact that link/unlink for an inode are mutually
locked and thus inode->i_nlink is atomic inside of fs method.
* BKL
Used to protect device usage count. It is changed in open/release
and referenced in ioctl all of which run under BKL. Supermount adds mediactl
and internally wraps it in BKL as well.
Caveats/BUGS
------------
Inode times are believed to be correctly updated; still it is possible that
I missed some point.
If subfs is not yet mounted, find /mnt/cdrom fails with "find: /mnt/cdrom
changed during execution of find". It is unlikely it can be fixed in
supermount; much more simple is to provide wrapper that will check if subfs
is mounted and do simple "touch /mnt/cdrom" if not to make sure it is.
Supermount attempts to check for changed media at every operation and
invalidate and umount old subfs to avoid new media corruption in rw case.
Still it is possible that kernel will write out stale information and
it is outside of supermount control.
By default cdrom driver does not check media type i.e. supermount will
try all configured fs types in turn that may be quite time consuming.
Use sysctl -w dev.cdrom.check_media=1 to enable it. Comments in cdrom.c
indicate that some (non conforming) software may have problems with this
settings. YMMV
atime management does not work for special files. There is no hooks from
VFS into fs to indicate when it gets updated
$Id: supermount.txt,v 1.17.2.1 2003/06/12 07:41:27 bor Exp $
