Whole document tree

8. FSinfo

XXX: this chapter should be reviewed by someone knowledgeable with fsinfo.

8.1 FSinfo overview		Introduction to FSinfo.
8.2 Using FSinfo		Basic concepts.
8.3 FSinfo grammar		Language syntax, semantics and examples.
8.4 FSinfo host definitions		Defining a new host.
8.5 FSinfo host attributes		Definable host attributes.
8.6 FSinfo filesystems		Defining locally attached filesystems.
8.7 FSinfo static mounts		Defining additional static mounts.
8.8 Defining an Amd Mount Map in FSinfo
8.9 FSinfo Command Line Options
8.10 Errors produced by FSinfo

8.1 FSinfo overview

FSinfo is a filesystem management tool. It has been designed to work with Amd to help system administrators keep track of the ever increasing filesystem namespace under their control.

The purpose of FSinfo is to generate all the important standard filesystem data files from a single set of input data. Starting with a single data source guarantees that all the generated files are self-consistent. One of the possible output data formats is a set of Amd maps which can be used amongst the set of hosts described in the input data.

FSinfo implements a declarative language. This language is specifically designed for describing filesystem namespace and physical layouts. The basic declaration defines a mounted filesystem including its device name, mount point, and all the volumes and access permissions. FSinfo reads this information and builds an internal map of the entire network of hosts. Using this map, many different data formats can be produced including `/etc/fstab', `/etc/exports', Amd mount maps and `/etc/bootparams'.

8.2 Using FSinfo

The basic strategy when using FSinfo is to gather all the information about all disks on all machines into one set of declarations. For each machine being managed, the following data is required:

• Hostname
• List of all filesystems and, optionally, their mount points.
• Names of volumes stored on each filesystem.
• NFS export information for each volume.
• The list of static filesystem mounts.

The following information can also be entered into the same configuration files so that all data can be kept in one place.

• List of network interfaces
• IP address of each interface
• Hardware address of each interface
• Dumpset to which each filesystem belongs
• and more ...

To generate Amd mount maps, the automount tree must also be defined (see section 8.8 Defining an Amd Mount Map in FSinfo). This will have been designed at the time the volume names were allocated. Some volume names will not be automounted, so FSinfo needs an explicit list of which volumes should be automounted.

Hostnames are required at several places in the FSinfo language. It is important to stick to either fully qualified names or unqualified names. Using a mixture of the two will inevitably result in confusion.

Sometimes volumes need to be referenced which are not defined in the set of hosts being managed with FSinfo. The required action is to add a dummy set of definitions for the host and volume names required. Since the files generated for those particular hosts will not be used on them, the exact values used is not critical.

8.3 FSinfo grammar

FSinfo has a relatively simple grammar. Distinct syntactic constructs exist for each of the different types of data, though they share a common flavor. Several conventions are used in the grammar fragments below.

The notation, list(xxx), indicates a list of zero or more xxx's. The notation, opt(xxx), indicates zero or one xxx. Items in double quotes, eg "host", represent input tokens. Items in angle brackets, eg <hostname>, represent strings in the input. Strings need not be in double quotes, except to differentiate them from reserved words. Quoted strings may include the usual set of C "\" escape sequences with one exception: a backslash-newline-whitespace sequence is squashed into a single space character. To defeat this feature, put a further backslash at the start of the second line.

At the outermost level of the grammar, the input consists of a sequence of host and automount declarations. These declarations are all parsed before they are analyzed. This means they can appear in any order and cyclic host references are possible.

fsinfo : list(fsinfo_attr) ; fsinfo_attr : host | automount ;

8.4 FSinfo host definitions
8.8 Defining an Amd Mount Map in FSinfo

8.4 FSinfo host definitions

A host declaration consists of three parts: a set of machine attribute data, a list of filesystems physically attached to the machine, and a list of additional statically mounted filesystems.

host : "host" host_data list(filesystem) list(mount) ;

Each host must be declared in this way exactly once. Such things as the hardware address, the architecture and operating system types and the cluster name are all specified within the host data.

All the disks the machine has should then be described in the list of filesystems. When describing disks, you can specify what volname the disk/partition should have and all such entries are built up into a dictionary which can then be used for building the automounter maps.

The list of mounts specifies all the filesystems that should be statically mounted on the machine.

8.5 FSinfo host attributes
8.6 FSinfo filesystems
8.7 FSinfo static mounts

8.5 FSinfo host attributes

The host data, host_data, always includes the hostname. In addition, several other host attributes can be given.

host_data : <hostname> | "{" list(host_attrs) "}" <hostname> ; host_attrs : host_attr "=" <string> | netif ; host_attr : "config" | "arch" | "os" | "cluster" ;

The hostname is, typically, the fully qualified hostname of the machine.

Examples:

host dylan.doc.ic.ac.uk host { os = hpux arch = hp300 } dougal.doc.ic.ac.uk

The options that can be given as host attributes are shown below.

8.5.1 netif Option

This defines the set of network interfaces configured on the machine. The interface attributes collected by FSinfo are the IP address, subnet mask and hardware address. Multiple interfaces may be defined for hosts with several interfaces by an entry for each interface. The values given are sanity checked, but are currently unused for anything else.

netif : "netif" "{" list(netif_attrs) "}" ; netif_attrs : netif_attr "=" <string> ; netif_attr : "inaddr" | "netmask" | "hwaddr" ;

Examples:

netif ie0 { inaddr = 129.31.81.37 netmask = 0xfffffe00 hwaddr = "08:00:20:01:a6:a5" } netif ec0 { }

8.5.2 config Option

This option allows you to specify configuration variables for the startup scripts (`rc' scripts). A simple string should immediately follow the keyword.

Example:

config "NFS_SERVER=true" config "ZEPHYR=true"

This option is currently unsupported.

8.5.3 arch Option

This defines the architecture of the machine. For example:

arch = hp300

This is intended to be of use when building architecture specific mountmaps, however, the option is currently unsupported.

8.5.4 os Option

This defines the operating system type of the host. For example:

os = hpux

This information is used when creating the `fstab' files, for example in choosing which format to use for the `fstab' entries within the file.

8.5.5 cluster Option

This is used for specifying in which cluster the machine belongs. For example:

cluster = "theory"

The cluster is intended to be used when generating the automount maps, although it is currently unsupported.

8.6 FSinfo filesystems

The list of physically attached filesystems follows the machine attributes. These should define all the filesystems available from this machine, whether exported or not. In addition to the device name, filesystems have several attributes, such as filesystem type, mount options, and `fsck' pass number which are needed to generate `fstab' entries.

filesystem : "fs" "{" list(fs_data) "}" ; fs_data : fs_data_attr "=" <string> | mount ; fs_data_attr : "fstype" | "opts" | "passno" | "freq" | "dumpset" | "log" ;

Here, <device> is the device name of the disk (for example, `/dev/dsk/2s0'). The device name is used for building the mount maps and for the `fstab' file. The attributes that can be specified are shown in the following section.

The FSinfo configuration file for dylan.doc.ic.ac.uk is listed below.

host dylan.doc.ic.ac.uk fs /dev/dsk/0s0 { fstype = swap } fs /dev/dsk/0s0 { fstype = hfs opts = rw,noquota,grpid passno = 0; freq = 1; mount / { } } fs /dev/dsk/1s0 { fstype = hfs opts = defaults passno = 1; freq = 1; mount /usr { local { exportfs "dougal eden dylan zebedee brian" volname /nfs/hp300/local } } } fs /dev/dsk/2s0 { fstype = hfs opts = defaults passno = 1; freq = 1; mount default { exportfs "toytown_clients hangers_on" volname /home/dylan/dk2 } } fs /dev/dsk/3s0 { fstype = hfs opts = defaults passno = 1; freq = 1; mount default { exportfs "toytown_clients hangers_on" volname /home/dylan/dk3 } } fs /dev/dsk/5s0 { fstype = hfs opts = defaults passno = 1; freq = 1; mount default { exportfs "toytown_clients hangers_on" volname /home/dylan/dk5 } }

8.6.1 fstype Option

This specifies the type of filesystem being declared and will be placed into the `fstab' file as is. The value of this option will be handed to mount as the filesystem type--it should have such values as 4.2, nfs or swap. The value is not examined for correctness.

There is one special case. If the filesystem type is specified as `export' then the filesystem information will not be added to the host's `fstab' information, but it will still be visible on the network. This is useful for defining hosts which contain referenced volumes but which are not under full control of FSinfo.

Example:

fstype = swap

8.6.2 opts Option

This defines any options that should be given to mount(8) in the `fstab' file. For example:

opts = rw,nosuid,grpid

8.6.3 passno Option

This defines the fsck(8) pass number in which to check the filesystem. This value will be placed into the `fstab' file.

Example:

passno = 1

8.6.4 freq Option

This defines the interval (in days) between dumps. The value is placed as is into the `fstab' file.

Example:

freq = 3

8.6.5 mount Option

This defines the mountpoint at which to place the filesystem. If the mountpoint of the filesystem is specified as default, then the filesystem will be mounted in the automounter's tree under its volume name and the mount will automatically be inherited by the automounter.

Following the mountpoint, namespace information for the filesystem may be described. The options that can be given here are exportfs, volname and sel.

The format is:

mount : "mount" vol_tree ; vol_tree : list(vol_tree_attr) ; vol_tree_attr : <string> "{" list(vol_tree_info) vol_tree "}" ; vol_tree_info : "exportfs" <export-data> | "volname" <volname> | "sel" <selector-list> ;

Example:

mount default { exportfs "dylan dougal florence zebedee" volname /vol/andrew }

In the above example, the filesystem currently being declared will have an entry placed into the `exports' file allowing the filesystem to be exported to the machines dylan, dougal, florence and zebedee. The volume name by which the filesystem will be referred to remotely, is `/vol/andrew'. By declaring the mountpoint to be default, the filesystem will be mounted on the local machine in the automounter tree, where Amd will automatically inherit the mount as `/vol/andrew'.

`exportfs'

a string defining which machines the filesystem may be exported to. This is copied, as is, into the `exports' file--no sanity checking is performed on this string.

`volname'

a string which declares the remote name by which to reference the filesystem. The string is entered into a dictionary and allows you to refer to this filesystem in other places by this volume name.

`sel'

a string which is placed into the automounter maps as a selector for the filesystem.

8.6.6 dumpset Option

This provides support for Imperial College's local file backup tools and is not documented further here.

8.6.7 log Option

Specifies the log device for the current filesystem. This is ignored if not required by the particular filesystem type.

8.7 FSinfo static mounts

Each host may also have a number of statically mounted filesystems. For example, the host may be a diskless workstation in which case it will have no fs declarations. In this case the mount declaration is used to determine from where its filesystems will be mounted. In addition to being added to the `fstab' file, this information can also be used to generate a suitable `bootparams' file.

mount : "mount" <volname> list(localinfo) ; localinfo : localinfo_attr <string> ; localinfo_attr : "as" | "from" | "fstype" | "opts" ;

The filesystem specified to be mounted will be searched for in the dictionary of volume names built when scanning the list of hosts' definitions.

The attributes have the following semantics:

`from machine'

mount the filesystem from the machine with the hostname of machine.

`as mountpoint'

mount the filesystem locally as the name given, in case this is different from the advertised volume name of the filesystem.

`opts options'

native mount(8) options.

`fstype type'

type of filesystem to be mounted.

An example:

mount /export/exec/hp300/local as /usr/local

If the mountpoint specified is either `/' or `swap', the machine will be considered to be booting off the net and this will be noted for use in generating a `bootparams' file for the host which owns the filesystems.

8.8 Defining an Amd Mount Map in FSinfo

The maps used by Amd can be constructed from FSinfo by defining all the automount trees. FSinfo takes all the definitions found and builds one map for each top level tree.

The automount tree is usually defined last. A single automount configuration will usually apply to an entire management domain. One automount declaration is needed for each Amd automount point. FSinfo determines whether the automount point is direct (see section 5.19 Direct Automount Filesystem (`direct')) or indirect (see section 5.22 Top-level Filesystem (`toplvl')). Direct automount points are distinguished by the fact that there is no underlying automount_tree.

automount : "automount" opt(auto_opts) automount_tree ; auto_opts : "opts" <mount-options> ; automount_tree : list(automount_attr) ; automount_attr : <string> "=" <volname> | <string> "->" <symlink> | <string> "{" automount_tree "}" ;

If <mount-options> is given, then it is the string to be placed in the maps for Amd for the opts option.

A map is typically a tree of filesystems, for example `home' normally contains a tree of filesystems representing other machines in the network.

A map can either be given as a name representing an already defined volume name, or it can be a tree. A tree is represented by placing braces after the name. For example, to define a tree `/vol', the following map would be defined:

automount /vol { }

Within a tree, the only items that can appear are more maps. For example:

automount /vol { andrew { } X11 { } }

In this case, FSinfo will look for volumes named `/vol/andrew' and `/vol/X11' and a map entry will be generated for each. If the volumes are defined more than once, then FSinfo will generate a series of alternate entries for them in the maps.

Instead of a tree, either a link (name -> destination) or a reference can be specified (name = destination). A link creates a symbolic link to the string specified, without further processing the entry. A reference will examine the destination filesystem and optimize the reference. For example, to create an entry for njw in the `/homes' map, either of the two forms can be used:

automount /homes { njw -> /home/dylan/njw }

or

automount /homes { njw = /home/dylan/njw }

In the first example, when `/homes/njw' is referenced from Amd, a link will be created leading to `/home/dylan/njw' and the automounter will be referenced a second time to resolve this filename. The map entry would be:

njw type:=link;fs:=/home/dylan/njw

In the second example, the destination directory is analyzed and found to be in the filesystem `/home/dylan' which has previously been defined in the maps. Hence the map entry will look like:

njw rhost:=dylan;rfs:=/home/dylan;sublink:=njw

Creating only one symbolic link, and one access to Amd.

8.9 FSinfo Command Line Options

FSinfo is started from the command line by using the command:

fsinfo [options] files ...

The input to FSinfo is a single set of definitions of machines and automount maps. If multiple files are given on the command-line, then the files are concatenated together to form the input source. The files are passed individually through the C pre-processor before being parsed.

Several options define a prefix for the name of an output file. If the prefix is not specified no output of that type is produced. The suffix used will correspond either to the hostname to which a file belongs, or to the type of output if only one file is produced. Dumpsets and the `bootparams' file are in the latter class. To put the output into a subdirectory simply put a `/' at the end of the prefix, making sure that the directory has already been made before running Fsinfo.

8.9.1 -a autodir		Amd automount directory:
8.9.2 -b bootparams		Prefix for bootparams files.
8.9.3 -d dumpsets		Prefix for dumpset data files.
8.9.4 -e exportfs		Prefix for exports files.
8.9.5 -f fstab		Prefix for fstab files.
8.9.6 -h hostname		Local hostname.
8.9.7 -m mount-maps		Prefix for automount maps.
8.9.8 -q		Ultra quiet mode.
8.9.9 -v		Verbose mode.
8.9.11 -I directory		Define new #include directory.
8.9.10 -D name[=defn]		Define macro.
8.9.12 -U name		Undefine macro.

8.9.1 -a autodir

Specifies the directory name in which to place the automounter's mountpoints. This defaults to `/a'. Some sites have the autodir set to be `/amd', and this would be achieved by:

fsinfo -a /amd ...

8.9.2 -b bootparams

This specifies the prefix for the `bootparams' filename. If it is not given, then the file will not be generated. The `bootparams' file will be constructed for the destination machine and will be placed into a file named `bootparams' and prefixed by this string. The file generated contains a list of entries describing each diskless client that can boot from the destination machine.

As an example, to create a `bootparams' file in the directory `generic', the following would be used:

fsinfo -b generic/ ...

8.9.3 -d dumpsets

This specifies the prefix for the `dumpsets' file. If it is not specified, then the file will not be generated. The file will be for the destination machine and will be placed into a filename `dumpsets', prefixed by this string. The `dumpsets' file is for use by Imperial College's local backup system.

For example, to create a `dumpsets' file in the directory `generic', then you would use the following:

fsinfo -d generic/ ...

8.9.4 -e exportfs

Defines the prefix for the `exports' files. If it is not given, then the file will not be generated. For each machine defined in the configuration files as having disks, an `exports' file is constructed and given a filename determined by the name of the machine, prefixed with this string. If a machine is defined as diskless, then no `exports' file will be created for it. The files contain entries for directories on the machine that may be exported to clients.

Example: To create the `exports' files for each diskfull machine and place them into the directory `exports':

fsinfo -e exports/ ...

8.9.5 -f fstab

This defines the prefix for the `fstab' files. The files will only be created if this prefix is defined. For each machine defined in the configuration files, a `fstab' file is created with the filename determined by prefixing this string with the name of the machine. These files contain entries for filesystems and partitions to mount at boot time.

Example, to create the files in the directory `fstabs':

fsinfo -f fstabs/ ...

8.9.6 -h hostname

Defines the hostname of the destination machine to process for. If this is not specified, it defaults to the local machine name, as returned by gethostname(2).

Example:

fsinfo -h dylan.doc.ic.ac.uk ...

8.9.7 -m mount-maps

Defines the prefix for the automounter files. The maps will only be produced if this prefix is defined. The mount maps suitable for the network defined by the configuration files will be placed into files with names calculated by prefixing this string to the name of each map.

For example, to create the automounter maps and place them in the directory `automaps':

fsinfo -m automaps/ ...

8.9.8 -q

Selects quiet mode. FSinfo suppress the "running commentary" and only outputs any error messages which are generated.

8.9.9 -v

Selects verbose mode. When this is activated, the program will display more messages, and display all the information discovered when performing the semantic analysis phase. Each verbose message is output to `stdout' on a line starting with a `#' character.

8.9.10 -D name[=defn]

Defines a symbol name for the preprocessor when reading the configuration files. Equivalent to #define directive.

8.9.11 -I directory

This option is passed into the preprocessor for the configuration files. It specifies directories in which to find include files

8.9.12 -U name

Removes any initial definition of the symbol name. Inverse of the -D option.

8.10 Errors produced by FSinfo

The following table documents the errors and warnings which FSinfo may produce.

" expected

Occurs if an unescaped newline is found in a quoted string.

ambiguous mount: volume is a replicated filesystem

If several filesystems are declared as having the same volume name, they will be considered replicated filesystems. To mount a replicated filesystem statically, a specific host will need to be named, to say which particular copy to try and mount, else this error will result.

can't open filename for writing

Occurs if any errors are encountered when opening an output file.

cannot determine localname since volname volume is not uniquely defined

If a volume is replicated and an attempt is made to mount the filesystem statically without specifying a local mountpoint, FSinfo cannot calculate a mountpoint, as the desired pathname would be ambiguous.

device has duplicate exportfs data

Produced if the `exportfs' option is used multiple times within the same branch of a filesystem definition. For example, if you attempt to set the `exportfs' data at different levels of the mountpoint directory tree.

dump frequency for host:device is non-zero

Occurs if device has its `fstype' declared to be `swap' or `export' and the `dump' option is set to a value greater than zero. Swap devices should not be dumped.

duplicate host hostname!

If a host has more than one definition.

end of file within comment

A comment was unterminated before the end of one of the configuration files.

filename: cannot open for reading

If a file specified on the command line as containing configuration data could not be opened.

filesystem has a volname but no exportfs data

Occurs when a volume name is declared for a file system, but the string specifying what machines the filesystem can be exported to is missing.

fs field "field-name" already set

Occurs when multiple definitions are given for one of the attributes of a host's filesystem.

host field "field-name" already set

If duplicate definitions are given for any of the fields with a host definition.

host:device has more than one mount point

Occurs if the mount option for a host's filesystem specifies multiple trees at which to place the mountpoint.

host:device has no mount point

Occurs if the `mount' option is not specified for a host's filesystem.

host:device needs field "field-name"

Occurs when a filesystem is missing a required field. field-name could be one of `fstype', `opts', `passno' or `mount'.

host:mount field specified for swap partition

Occurs if a mountpoint is given for a filesystem whose type is declared to be `swap'.

malformed IP dotted quad: address

If the Internet address of an interface is incorrectly specified. An Internet address definition is handled to inet_addr(3N) to see if it can cope. If not, then this message will be displayed.

malformed netmask: netmask

If the netmask cannot be decoded as though it were a hexadecimal number, then this message will be displayed. It will typically be caused by incorrect characters in the netmask value.

mount field "field-name" already set

Occurs when a static mount has multiple definitions of the same field.

mount tree field "field-name" already set

Occurs when the field-name is defined more than once during the definition of a filesystems mountpoint.

netif field field-name already set

Occurs if you attempt to define an attribute of an interface more than once.

network booting requires both root and swap areas

Occurs if a machine has mount declarations for either the root partition or the swap area, but not both. You cannot define a machine to only partially boot via the network.

no disk mounts on hostname

If there are no static mounts, nor local disk mounts specified for a machine, this message will be displayed.

no volname given for host:device

Occurs when a filesystem is defined to be mounted on `default', but no volume name is given for the file system, then the mountpoint cannot be determined.

not allowed '/' in a directory name

Occurs when a pathname with multiple directory elements is specified as the name for an automounter tree. A tree should only have one name at each level.

pass number for host:device is non-zero

Occurs if device has its `fstype' declared to be `swap' or `export' and the fsck(8) pass number is set. Swap devices should not be fsck'd. See section 8.6.1 fstype Option.

sub-directory directory of directory-tree starts with '/'

Within the filesystem specification for a host, if an element directory of the mountpoint begins with a `/' and it is not the start of the tree.

sub-directory of directory-tree is named "default"

`default' is a keyword used to specify if a mountpoint should be automatically calculated by FSinfo. If you attempt to specify a directory name as this, it will use the filename of `default' but will produce this warning.

unknown \ sequence

Occurs if an unknown escape sequence is found inside a string. Within a string, you can give the standard C escape sequences for strings, such as newlines and tab characters.

unknown directory attribute

If an unknown keyword is found while reading the definition of a host's filesystem mount option.

unknown filesystem attribute

Occurs if an unrecognized keyword is used when defining a host's filesystems.

unknown host attribute

Occurs if an unrecognized keyword is used when defining a host.

unknown mount attribute

Occurs if an unrecognized keyword is found while parsing the list of static mounts.

unknown volname volume automounted [ on name ]

Occurs if volume is used in a definition of an automount map but the volume name has not been declared during the host filesystem definitions.

volname volume is unknown

Occurs if an attempt is made to mount or reference a volume name which has not been declared during the host filesystem definitions.

volname volume not exported from machine

Occurs if you attempt to mount the volume volume from a machine which has not declared itself to have such a filesystem available.