Whole document tree

5. Filesystem Types

To mount a volume, Amd must be told the type of filesystem to be used. Each filesystem type typically requires additional information such as the fileserver name for NFS.

From the point of view of Amd, a filesystem is anything that can resolve an incoming name lookup. An important feature is support for multiple filesystem types. Some of these filesystems are implemented in the local kernel and some on remote fileservers, whilst the others are implemented internally by Amd.

The two common filesystem types are UFS and NFS. Four other user accessible filesystems (`link', `program', `auto' and `direct') are also implemented internally by Amd and these are described below. There are two additional filesystem types internal to Amd which are not directly accessible to the user (`inherit' and `error'). Their use is described since they may still have an effect visible to the user.

5.1 Network Filesystem (`nfs')		A single NFS filesystem.
5.2 Network Host Filesystem (`host')		NFS mount a host's entire export tree.
5.3 Network Filesystem Group (`nfsx')		An atomic group of NFS filesystems.
5.4 Unix Filesystem (`ufs', `xfs', or `efs')		Native disk filesystem.
5.5 Caching Filesystem (`cachefs')		Caching from remote server filesystem.
5.6 CD-ROM Filesystem (`cdfs')		ISO9660 CD ROM.
5.7 Loopback Filesystem (`lofs')		Local loopback-mount filesystem.
5.8 Memory/RAM Filesystem (`mfs')		A memory or RAM-based filesystem.
5.9 Null Filesystem (`nullfs')		4.4BSD's loopback-mount filesystem.
5.10 Floppy Filesystem (`pcfs')		MS-DOS Floppy filesystem.
5.11 Translucent Filesystem (`tfs')		The directory merging filesystem.
5.12 Shared Memory+Swap Filesystem (`tmpfs')		Sun's tmpfs filesystem.
5.13 User ID Mapping Filesystem (`umapfs')		4.4BSD's umapfs filesystem.
5.14 Program Filesystem (`program')		Generic Program mounts.
5.15 Symbolic Link Filesystem (`link')		Local link.
5.16 Symbolic Link Filesystem II (`linkx')		Local link referencing existing filesystem.
5.17 NFS-Link Filesystem (`nfsl')		Link if path exists, NFS otherwise.
5.18 Automount Filesystem (`auto')
5.19 Direct Automount Filesystem (`direct')
5.20 Union Filesystem (`union')
5.21 Error Filesystem (`error')
5.22 Top-level Filesystem (`toplvl')
5.24 Autofs Filesystem (`autofs')		Sun's kernel-based automounter filesystem.
5.23 Root Filesystem (`root')
5.25 Inheritance Filesystem (`inherit')

5.1 Network Filesystem (`nfs')

The nfs (`type:=nfs') filesystem type provides access to Sun's NFS.

The following options must be specified:

rhost

the remote fileserver. This must be an entry in the hosts database. IP addresses are not accepted. The default value is taken from the local host name (${host}) if no other value is specified.

rfs

the remote filesystem. If no value is specified for this option, an internal default of ${path} is used.

NFS mounts require a two stage process. First, the file handle of the remote file system must be obtained from the server. Then a mount system call must be done on the local system. Amd keeps a cache of file handles for remote file systems. The cache entries have a lifetime of a few minutes.

If a required file handle is not in the cache, Amd sends a request to the remote server to obtain it. Amd does not wait for a response; it notes that one of the locations needs retrying, but continues with any remaining locations. When the file handle becomes available, and assuming none of the other locations was successfully mounted, Amd will retry the mount. This mechanism allows several NFS filesystems to be mounted in parallel. The first one which responds with a valid file handle will be used.

An NFS entry might be:

jsp host!=charm;type:=nfs;rhost:=charm;rfs:=/home/charm;sublink:=jsp

The mount system call and any unmount attempts are always done in a new task to avoid the possibility of blocking Amd.

5.2 Network Host Filesystem (`host')

The host (`type:=host') filesystem allows access to the entire export tree of an NFS server. The implementation is layered above the `nfs' implementation so keep-alives work in the same way. The only option which needs to be specified is `rhost' which is the name of the fileserver to mount.

The `host' filesystem type works by querying the mount daemon on the given fileserver to obtain its export list. Amd then obtains filehandles for each of the exported filesystems. Any errors at this stage cause that particular filesystem to be ignored. Finally each filesystem is mounted. Again, errors are logged but ignored. One common reason for mounts to fail is that the mount point does not exist. Although Amd attempts to automatically create the mount point, it may be on a remote filesystem to which Amd does not have write permission.

When an attempt to unmount a `host' filesystem mount fails, Amd remounts any filesystems which had successfully been unmounted. To do this Amd queries the mount daemon again and obtains a fresh copy of the export list. Amd then tries to mount any exported filesystems which are not currently mounted.

Sun's automounter provides a special `-hosts' map. To achieve the same effect with Amd requires two steps. First a mount map must be created as follows:

* type:=host;rhost:=${key};fs:=${autodir}/${rhost}/root

and then start Amd with the following command

amd /net net.map

where `net.map' is the name of map described above. Note that the value of ${fs} is overridden in the map. This is done to avoid a clash between the mount tree and any other filesystem already mounted from the same fileserver.

If different mount options are needed for different hosts then additional entries can be added to the map, for example

host2 opts:=ro,nosuid,soft

would soft mount `host2' read-only.

5.3 Network Filesystem Group (`nfsx')

The nfsx (`type:=nfsx') filesystem allows a group of filesystems to be mounted from a single NFS server. The implementation is layered above the `nfs' implementation so keep-alives work in the same way.

The options are the same as for the `nfs' filesystem with one difference.

The following options should be specified:

rhost

the remote fileserver. The default value is taken from the local host name (${host}) if no other value is specified.

rfs

is a list of filesystems to mount, and must be specified. The list is in the form of a comma separated strings.

For example:

pub type:=nfsx;rhost:=gould;\ rfs:=/public,/,graphics,usenet;fs:=${autodir}/${rhost}/root

The first string defines the root of the tree, and is applied as a prefix to the remaining members of the list which define the individual filesystems. The first string is not used as a filesystem name. A parallel operation is used to determine the local mount points to ensure a consistent layout of a tree of mounts.

Here, the three filesystems, `/public', `/public/graphics' and `/public/usenet', would be mounted.

A local mount point, ${fs}, must be specified. The default local mount point will not work correctly in the general case. A suggestion is to use `fs:=${autodir}/${rhost}/root'.

5.4 Unix Filesystem (`ufs', `xfs', or `efs')

The ufs (`type:=ufs') filesystem type provides access to the system's standard disk filesystem--usually a derivative of the Berkeley Fast Filesystem.

The following option must be specified:

dev

the block special device to be mounted.

A UFS entry might be:

jsp host==charm;type:=ufs;dev:=/dev/sd0d;sublink:=jsp

UFS is the default Unix disk-based file system, which Am-utils picks up during the autoconfiguration phase. Some systems have more than one type, such as IRIX, that comes with EFS (Extent File System) and XFS (Extended File System). In those cases, you may explicitly set the file system type, by using entries such:

ez1 type:=efs;dev:=/dev/xd0a ez2 type:=xfs;dev:=/dev/sd3c

5.5 Caching Filesystem (`cachefs')

The cachefs (`type:=cachefs') filesystem caches files from one location onto another, presumably providing faster access. It is particularly useful to cache from a larger and remote (slower) NFS partition to a smaller and local (faster) UFS directory.

The following options must be specified:

cachedir

the directory where the cache is stored.

rfs

the path name to the "back file system" to be cached from.

fs

the "front file system" mount point to the cached files, where Amd will set a symbolic link pointing to.

A CacheFS entry for, say, the `/import' Amd mount point, might be:

copt type:=cachefs;cachedir:=/cache;rfs:=/import/opt;fs:=/n/import/copt

Access to the pathname `/import/copt' will follow a symbolic link to `/n/import/copt'. The latter is the mount point for a caching file system, that caches from `/import/opt' to `/cache'.

Caveats:

1. This file system is currently only implemented for Solaris 2.x!
2. Before being used for the first time, the cache directory must be initialized with `cfsadmin -c cachedir'. See the manual page for cfsadmin(1M) for more information.
3. The "back file system" mounted must be a complete file system, not a subdirectory thereof; otherwise you will get an error "Invalid Argument".
4. If Amd aborts abnormally, the state of the cache may be inconsistent, requiring running the command `fsck -F cachefs cachedir'. Otherwise you will get the error "No Space Left on Device".

5.6 CD-ROM Filesystem (`cdfs')

The cdfs (`type:=cdfs') filesystem mounts a CD-ROM with an ISO9660 format filesystem on it.

The following option must be specified:

dev

the block special device to be mounted.

Some operating systems will fail to mount read-only CDs unless the `ro' option is specified. A cdfs entry might be:

cdfs os==sunos4;type:=cdfs;dev:=/dev/sr0 \ os==sunos5;addopts:=ro;type:=cdfs;dev:=/dev/dsk/c0t6d0s2

5.7 Loopback Filesystem (`lofs')

The lofs (`type:=lofs') filesystem is also called the loopback filesystem. It mounts a local directory on another, thus providing mount-time binding to another location (unlike symbolic links).

The loopback filesystem is particularly useful within the context of a chroot-ed directory (via chroot(2)), to provide access to directories otherwise inaccessible.

The following option must be specified:

rfs

the pathname to be mounted on top of ${fs}.

Usually, the FTP server runs in a chroot-ed environment, for security reasons. In this example, lofs is used to provide a subdirectory within a user's home directory, also available for public ftp.

lofs type:=lofs;rfs:=/home/ezk/myftpdir;fs:=/usr/ftp/pub/ezk

5.8 Memory/RAM Filesystem (`mfs')

The mfs (`type:=mfs') filesystem is available in 4.4BSD, Linux, and other systems. It creates a filesystem in a portion of the system's memory, thus providing very fast file (volatile) access.

XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET!

5.9 Null Filesystem (`nullfs')

The nullfs (`type:=nullfs') filesystem is available from 4.4BSD, and is very similar to the loopback filesystem, lofs.

XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET!

5.10 Floppy Filesystem (`pcfs')

The pcfs (`type:=pcfs') filesystem mounts a floppy previously formatted for the MS-DOS format.

The following option must be specified:

dev

the block special device to be mounted.

A pcfs entry might be:

pcfs os==sunos4;type:=pcfs;dev:=/dev/fd0 \ os==sunos5;type:=pcfs;dev:=/dev/diskette

5.11 Translucent Filesystem (`tfs')

The tfs (`type:=tfs') filesystem is an older version of the 4.4BSD unionfs.

XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET!

5.12 Shared Memory+Swap Filesystem (`tmpfs')

The tmpfs (`type:=tmpfs') filesystem shares memory between a the swap device and the rest of the system. It is generally used to provide a fast access `/tmp' directory, one that uses memory that is otherwise unused. This filesystem is available in SunOS 4.x and 5.x.

XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET!

5.13 User ID Mapping Filesystem (`umapfs')

The umapfs (`type:=umapfs') filesystem maps User IDs of file ownership, and is available from 4.4BSD.

XXX: THIS FILESYSTEM IS NOT IMPLEMENTED YET!

5.14 Program Filesystem (`program')

The program (`type:=program') filesystem type allows a program to be run whenever a mount or unmount is required. This allows easy addition of support for other filesystem types, such as MIT's Remote Virtual Disk (RVD) which has a programmatic interface via the commands `rvdmount' and `rvdunmount'.

The following options must be specified:

mount

the program which will perform the mount.

unmount

the program which will perform the unmount.

The exit code from these two programs is interpreted as a Unix error code. As usual, exit code zero indicates success. To execute the program Amd splits the string on whitespace to create an array of substrings. Single quotes `'' can be used to quote whitespace if that is required in an argument. There is no way to escape or change the quote character.

To run the program `rvdmount' with a host name and filesystem as arguments would be specified by `fs:=${autodir}${path};mount:="/etc/rvdmount rvdmount fserver ${fs}"'.

The first element in the array is taken as the pathname of the program to execute. The other members of the array form the argument vector to be passed to the program, including argument zero. This means that the split string must have at least two elements. The program is directly executed by Amd, not via a shell. This means that scripts must begin with a #! interpreter specification.

If a filesystem type is to be heavily used, it may be worthwhile adding a new filesystem type into Amd, but for most uses the program filesystem should suffice.

When the program is run, standard input and standard error are inherited from the current values used by Amd. Standard output is a duplicate of standard error. The value specified with the -l command line option has no effect on standard error.

5.15 Symbolic Link Filesystem (`link')

Each filesystem type creates a symbolic link to point from the volume name to the physical mount point. The `link' filesystem does the same without any other side effects. This allows any part of the machines name space to be accessed via Amd.

One common use for the symlink filesystem is `/homes' which can be made to contain an entry for each user which points to their (auto-mounted) home directory. Although this may seem rather expensive, it provides a great deal of administrative flexibility.

The following option must be defined:

fs

The value of fs option specifies the destination of the link, as modified by the sublink option. If sublink is non-null, it is appended to ${fs}/ and the resulting string is used as the target.

The `link' filesystem can be thought of as identical to the `ufs' filesystem but without actually mounting anything.

An example entry might be:

jsp host==charm;type:=link;fs:=/home/charm;sublink:=jsp

which would return a symbolic link pointing to `/home/charm/jsp'.

5.16 Symbolic Link Filesystem II (`linkx')

The linkx (`type:=linkx') filesystem type is identical to `link' with the exception that the target of the link must exist. Existence is checked with the lstat(2) system call.

The `linkx' filesystem type is particularly useful for wildcard map entries. In this case, a list of possible targets can be given and Amd will choose the first one which exists on the local machine.

5.17 NFS-Link Filesystem (`nfsl')

The nfsl (`type:=nfsl') filesystem type is a combination of two others: `link' and `nfs'. If the local host name is equal to the value of ${rhost}, or if the target pathname listed in ${fs} exists, `nfsl' will behave exactly as `type:=link', and refer to the target as a symbolic link. If the local host name is not equal to the value of ${rhost}, or if the target of the link does not exist, Amd will treat it as `type:=nfs', and will mount a remote pathname for it.

The `nfsl' filesystem type is particularly useful as a shorthand for the more cumbersome and yet one of the most popular Amd entries. For example, you can simplify all map entries that look like:

zing -fs:=/n/shekel/u/zing \ host!=shekel;type:=nfs;rhost:=shekel;rfs:=${fs} \ host==shekel;type:=link

or

zing -fs:=/n/shekel/u/zing \ exists(${fs});type:=link \ !exists(${fs});type:=nfs;rhost:=shekel;rfs:=${fs}

into a shorter form

zing type:=nfsl;fs:=/n/shekel/u/zing;rhost:=shekel;rfs:=${fs}

Not just does it make the maps smaller and simpler, but it avoids possible mistakes that often happen when forgetting to set up the two entries (one for `type:=nfs' and the other for `type:=link') necessary to perform transparent mounts of existing or remote mounts.

5.18 Automount Filesystem (`auto')

The auto (`type:=auto') filesystem type creates a new automount point below an existing automount point. Top-level automount points appear as system mount points. An automount mount point can also appear as a sub-directory of an existing automount point. This allows some additional structure to be added, for example to mimic the mount tree of another machine.

The following options may be specified:

cache

specifies whether the data in this mount-map should be cached. The default value is `none', in which case no caching is done in order to conserve memory.

However, better performance and reliability can be obtained by caching some or all of a mount-map.

If the cache option specifies `all', the entire map is enumerated when the mount point is created.

If the cache option specifies `inc', caching is done incrementally as and when data is required. Some map types do not support cache mode `all', in which case `inc' is used whenever `all' is requested.

Caching can be entirely disabled by using cache mode `none'.

If the cache option specifies `regexp' then the entire map will be enumerated and each key will be treated as an egrep-style regular expression. The order in which a cached map is searched does not correspond to the ordering in the source map so the regular expressions should be mutually exclusive to avoid confusion.

Each mount map type has a default cache type, usually `inc', which can be selected by specifying `mapdefault'.

The cache mode for a mount map can only be selected on the command line. Starting Amd with the command:

amd /homes hesiod.homes -cache:=inc

will cause `/homes' to be automounted using the Hesiod name server with local incremental caching of all successfully resolved names.

All cached data is forgotten whenever Amd receives a `SIGHUP' signal and, if cache `all' mode was selected, the cache will be reloaded. This can be used to inform Amd that a map has been updated. In addition, whenever a cache lookup fails and Amd needs to examine a map, the map's modify time is examined. If the cache is out of date with respect to the map then it is flushed as if a `SIGHUP' had been received.

An additional option (`sync') may be specified to force Amd to check the map's modify time whenever a cached entry is being used. For example, an incremental, synchronized cache would be created by the following command:

amd /homes hesiod.homes -cache:=inc,sync

fs

specifies the name of the mount map to use for the new mount point.

Arguably this should have been specified with the ${rfs} option but we are now stuck with it due to historical accident.

pref

alters the name that is looked up in the mount map. If ${pref}, the prefix, is non-null then it is prepended to the name requested by the kernel before the map is searched.

opts

Normally, `auto' style maps are not browsable even if you turn on directory browsability (see section 6.4.1 browsable_dirs Parameter). To enable browsing entries in `auto' maps, specify `opts:=browsable' in the description of this map.

The server `dylan.doc.ic.ac.uk' has two user disks: `/dev/dsk/2s0' and `/dev/dsk/5s0'. These are accessed as `/home/dylan/dk2' and `/home/dylan/dk5' respectively. Since `/home' is already an automount point, this naming is achieved with the following map entries:

dylan type:=auto;fs:=${map};pref:=${key}/ dylan/dk2 type:=ufs;dev:=/dev/dsk/2s0 dylan/dk5 type:=ufs;dev:=/dev/dsk/5s0

5.19 Direct Automount Filesystem (`direct')

The direct (`type:=direct') filesystem is almost identical to the automount filesystem. Instead of appearing to be a directory of mount points, it appears as a symbolic link to a mounted filesystem. The mount is done at the time the link is accessed. See section 5.18 Automount Filesystem (`auto'), for a list of required options.

Direct automount points are created by specifying the `direct' filesystem type on the command line:

amd ... /usr/man auto.direct -type:=direct

where `auto.direct' would contain an entry such as:

usr/man -type:=nfs;rfs:=/usr/man \ rhost:=man-server1 rhost:=man-server2

In this example, `man-server1' and `man-server2' are file servers which export copies of the manual pages. Note that the key which is looked up is the name of the automount point without the leading `/'.

5.20 Union Filesystem (`union')

The union (`type:=union') filesystem type allows the contents of several directories to be merged and made visible in a single directory. This can be used to overcome one of the major limitations of the Unix mount mechanism which only allows complete directories to be mounted.

For example, supposing `/tmp' and `/var/tmp' were to be merged into a new directory called `/mtmp', with files in `/var/tmp' taking precedence. The following command could be used to achieve this effect:

amd ... /mtmp union:/tmp:/var/tmp -type:=union

Currently, the unioned directories must not be automounted. That would cause a deadlock. This seriously limits the current usefulness of this filesystem type and the problem will be addressed in a future release of Amd.

Files created in the union directory are actually created in the last named directory. This is done by creating a wildcard entry which points to the correct directory. The wildcard entry is visible if the union directory is listed, so allowing you to see which directory has priority.

The files visible in the union directory are computed at the time Amd is started, and are not kept up-to-date with respect to the underlying directories. Similarly, if a link is removed, for example with the `rm' command, it will be lost forever.

5.21 Error Filesystem (`error')

The error (`type:=error') filesystem type is used internally as a catch-all in the case where none of the other filesystems was selected, or some other error occurred. Lookups and mounts always fail with "No such file or directory". All other operations trivially succeed.

The error filesystem is not directly accessible.

5.22 Top-level Filesystem (`toplvl')

The toplvl (`type:=toplvl') filesystems is derived from the `auto' filesystem and is used to mount the top-level automount nodes. Requests of this type are automatically generated from the command line arguments.

5.23 Root Filesystem (`root')

The root (`type:=root') filesystem type acts as an internal placeholder onto which Amd can pin `toplvl' mounts. Only one node of this type need ever exist and one is created automatically during startup. The effect of having more than one root node is undefined.

The root filesystem is not directly accessible.

5.24 Autofs Filesystem (`autofs')

The autofs (`type:=autofs') filesystem uses Sun's kernel-based automounter supporting filesystem for Amd's mount points. Hence it is another type of top level filesystem.

The autofs filesystem is not directly accessible from Amd maps, but only from the `amd.conf' file (see section 6.4.4 mount_type Parameter).

Note that Autofs support is still very early. See the distribution file `README.autofs' for detail of what works and what does not.

5.25 Inheritance Filesystem (`inherit')

The inheritance (`type:=inherit') filesystem is not directly accessible. Instead, internal mount nodes of this type are automatically generated when Amd is started with the -r option. At this time the system mount table is scanned to locate any filesystems which are already mounted. If any reference to these filesystems is made through Amd then instead of attempting to mount it, Amd simulates the mount and inherits the filesystem. This allows a new version of Amd to be installed on a live system simply by killing the old daemon with `SIGTERM' and starting the new one.

This filesystem type is not generally visible externally, but it is possible that the output from `amq -m' may list `inherit' as the filesystem type. This happens when an inherit operation cannot be completed for some reason, usually because a fileserver is down.