--- /dev/null
+The afpd.mtab file
+
+ This file usually lives in /etc/atalk/afpd.mtab, and contains
+information describing each mounted partition that should be accessible
+via afpd, in a format similar to /etc/mtab or /etc/fstab, one entry per
+line. Each entry consists of three values: an integer index, a disk
+device, and the mount point for that disk device, separated by arbitrary
+amounts of whitespace. Here is an example, created automatically by the
+afpd-mtab.pl script from the list of mounted partitions in /etc/mtab
+[this works on Linux, YMMV]:
+
+ rgr> ./afpd-mtab.pl < /etc/mtab
+ # afpd.mtab, generated by afpd-mtab.pl on Mon Apr 9 18:15:15 EDT 2001
+ 1 /dev/hda8 /
+ 2 /dev/hda12 /var
+ 3 /dev/hda11 /usr
+ 4 /dev/hda10 /usr/local
+ 5 /dev/hda9 /home
+ rgr>
+
+The index values must be small positive integers, and must be unique to
+each device. They need not be dense; in fact, if a partition is ever
+retired, a gap should be left so that dangling aliases do not point to
+files on a different device. The index 0 is reserved. The mount point
+is not actually used currently, thought it is useful for reference
+purposes; in any case, it must be present.
+
+How afpd.mtab is used
+
+ The index values are used in constructing 32-bit unique directory
+identifiers (DIDs), which the client uses to make aliases to netatalk
+shares. Because of these aliases, it is important that DIDs be
+
+ 1. Unique, to be sure that the client and server are really talking
+about the same directories; and
+
+ 2. Persistent indefinitely despite server restarts & reboots, so
+that aliases don't become stale.
+
+In Unix, files can be uniquely and persistently identified by (device,
+inode) pairs, where devices are identified by a pair of (major, minor)
+device numbers. But because the Apple File Protocol only allocates 32
+bits for the whole DID value, and the Unix device address space is
+generally huge but usually very sparse, afpd must go through some
+contortions to compress (major, minor, inode) triples into 32 bits. The
+inode value is dense and therefore not compressible, but the device
+space is that used in a given installation can usually be compressed
+into 2 to 4 bits. While this compression could be done on the fly, by
+picking an arbitrary encoding at startup, that would fail persistence
+requirement, especially when restarting after adding new disks to the
+system. Hence the introduction of the afpd.mtab file for the sake of
+persistence.
+
+ Upon reading this file at startup, afpd arranges to use just enough
+bits for the device subfield to encode all devices in the afpd.mtab
+file, leaving the rest for the inode. If 4 bits are required for the
+device, allowing indices from 1 through 15, then 28 are left for the
+inode, leaving room for 256Mi files on each device. On an ext2 file
+system made with default options, where there are about 3.9 blocks per
+inode, that allows partitions of nearly a terabyte. By the time
+netatalk needs to deal with such partitions, AFP will probably be
+obsolete. If you are unlucky enough to be ahead of the curve, then you
+probably have lots of large files to store (e.g. sound, images, video),
+and you should consider raising the blocks-per-inode ratio anyway.
+
+ Note that afpd *only* reads the afpd.mtab file at startup, so to get
+it to recognize a new partition, one must (1) restart afpd, and (2)
+notify all clients that they need to close and reopen their server
+connections before they access the new volume.
+
+Maintaining afpd.mtab
+
+ It is expected that once afpd.mtab is created initially, possibly
+using the afpd-mtab.pl script provided, it will then be maintained by
+hand so as to preserve the mapping where possible. For example,
+repartitioning may cause some of the partition numbers and hence the
+device names to change, but the underlying inode->file mapping is the
+same, so the association of index to mount point should be maintained.
+On the other hand, if the contents of a partition are moved to another
+partition, the inode numbers will all change (unless steps can be taken
+to preserve them). In that case, best practice would be to "retire" the
+old index and choose a new one; otherwise, aliases will appear to be
+remapped at random, possibly with catastrophic results.
+
--- /dev/null
+About this directory
+
+ This directory contains I hack I wrote to explore a way to fix the
+netatalk persistent DID problem. A survey of the contents:
+
+ README.mtab -- notes for implementors and sysadmins, on why there is
+an extra configuration file, and how to maintain it. If adopted, this
+should become part of the distribution documentation. Much more could
+be said.
+
+ afpd-mtab.pl -- perl script that acts as a filter, turning /etc/mtab
+into an initial afpd.mtab version. (Only tested on RH Linux.)
+
+ afpd.mtab.* -- testing versions produced on my system. "make test"
+tries to produce afpd.mtab automatically; if this doesn't work on your
+configuration, you could try editing one of these to match your
+partition structure.
+
+ parse-mtab.c, parse-mtab.h -- source intended to be integrated into
+the etc/afpd/ code.
+
+ test-parse-mtab.c -- test driver for parse-mtab.c, reads the file and
+produces CNID values for other files and directories given on the
+command line. Change top_srcdir in the makefile and do "make test" in
+order to compile & run this.
+
+Notes:
+
+ * I have only ext2fs partitions on a single local disk, so I haven't
+been able to do very broad testing, even on Linux. This is part of why
+I'm too chicken to try to paste this into the netatalk source. ;-}
+
+ * If there is no entry in the table, I just use the reserved 0 device
+index. This seems like asking for trouble, so a better policy would be
+to make absent devices unavailable (you probably don't want users poking
+around in /var or /usr anyway), but that requires a more global
+implementation.
+
+ * The way it's now written, afpd is expected to fail to start up if
+/etc/atalk/afpd.mtab is not found. That may not be optimal, but even if
+it is, it requires some extra setup instructions.
+
+ * I'm assuming the high order bit need no longer be reserved for the
+file/directory flag, but I have no idea whether that will work. If not,
+it's easy to change.
+
+ * It would be good if, on startup, afpd would warn about partitions
+in the table that have more inodes than can be represented in the
+available number of bits.
+
+ * If partitions were to use a bit encoding that reversed the bits in
+the index (i.e. putting the LSB "first" as written), then the device MSB
+would be adjacent to the inode MSB. That would produce upward-
+compatible DIDs if the number of device bits needed to increase. The
+encoding is precomputed anyway, so it's not a speed concern. Better
+still, by carefully choosing small indices for large-inode devices and
+avoiding intermediate-sized indices, one could effectively set the
+device/inode boundary independently for each device. This would allow a
+sysadmin to come close to using all of the theoretical 32-bit DID-space.
+(Implementation is left as an excercise. ;-)
+
projects / netatalk.git / commitdiff