doc/README.mtab

   1 The afpd.mtab file
   2
   3    This file usually lives in /etc/atalk/afpd.mtab, and contains
   4 information describing each mounted partition that should be accessible
   5 via afpd, in a format similar to /etc/mtab or /etc/fstab, one entry per
   6 line.  Each entry consists of three values: an integer index, a disk
   7 device, and the mount point for that disk device, separated by arbitrary
   8 amounts of whitespace.  Here is an example, created automatically by the
   9 afpd-mtab.pl script from the list of mounted partitions in /etc/mtab
  10 [this works on Linux, YMMV]:
  11
  12         rgr> ./afpd-mtab.pl < /etc/mtab
  13         # afpd.mtab, generated by afpd-mtab.pl on Mon Apr  9 18:15:15 EDT 2001
  14          1 /dev/hda8  /
  15          2 /dev/hda12 /var
  16          3 /dev/hda11 /usr
  17          4 /dev/hda10 /usr/local
  18          5 /dev/hda9  /home
  19         rgr>
  20
  21 The index values must be small positive integers, and must be unique to
  22 each device.  They need not be dense; in fact, if a partition is ever
  23 retired, a gap should be left so that dangling aliases do not point to
  24 files on a different device.  The index 0 is reserved.  The mount point
  25 is not actually used currently, thought it is useful for reference
  26 purposes; in any case, it must be present.
  27
  28 How afpd.mtab is used
  29
  30    The index values are used in constructing 32-bit unique directory
  31 identifiers (DIDs), which the client uses to make aliases to netatalk
  32 shares.  Because of these aliases, it is important that DIDs be
  33
  34    1.  Unique, to be sure that the client and server are really talking
  35 about the same directories; and
  36
  37    2.  Persistent indefinitely despite server restarts & reboots, so
  38 that aliases don't become stale.
  39
  40 In Unix, files can be uniquely and persistently identified by (device,
  41 inode) pairs, where devices are identified by a pair of (major, minor)
  42 device numbers.  But because the Apple File Protocol only allocates 32
  43 bits for the whole DID value, and the Unix device address space is
  44 generally huge but usually very sparse, afpd must go through some
  45 contortions to compress (major, minor, inode) triples into 32 bits.  The
  46 inode value is dense and therefore not compressible, but the device
  47 space is that used in a given installation can usually be compressed
  48 into 2 to 4 bits.  While this compression could be done on the fly, by
  49 picking an arbitrary encoding at startup, that would fail persistence
  50 requirement, especially when restarting after adding new disks to the
  51 system.  Hence the introduction of the afpd.mtab file for the sake of
  52 persistence.
  53
  54    Upon reading this file at startup, afpd arranges to use just enough
  55 bits for the device subfield to encode all devices in the afpd.mtab
  56 file, leaving the rest for the inode.  If 4 bits are required for the
  57 device, allowing indices from 1 through 15, then 28 are left for the
  58 inode, leaving room for 256Mi files on each device.  On an ext2 file
  59 system made with default options, where there are about 3.9 blocks per
  60 inode, that allows partitions of nearly a terabyte.  By the time
  61 netatalk needs to deal with such partitions, AFP will probably be
  62 obsolete.  If you are unlucky enough to be ahead of the curve, then you
  63 probably have lots of large files to store (e.g. sound, images, video),
  64 and you should consider raising the blocks-per-inode ratio anyway.
  65
  66    Note that afpd *only* reads the afpd.mtab file at startup, so to get
  67 it to recognize a new partition, one must (1) restart afpd, and (2)
  68 notify all clients that they need to close and reopen their server
  69 connections before they access the new volume.
  70
  71 Maintaining afpd.mtab
  72
  73    It is expected that once afpd.mtab is created initially, possibly
  74 using the afpd-mtab.pl script provided, it will then be maintained by
  75 hand so as to preserve the mapping where possible.  For example,
  76 repartitioning may cause some of the partition numbers and hence the
  77 device names to change, but the underlying inode->file mapping is the
  78 same, so the association of index to mount point should be maintained.
  79 On the other hand, if the contents of a partition are moved to another
  80 partition, the inode numbers will all change (unless steps can be taken
  81 to preserve them).  In that case, best practice would be to "retire" the
  82 old index and choose a new one; otherwise, aliases will appear to be
  83 remapped at random, possibly with catastrophic results.
  84