# -*- text -*-
# This file is README.autofs
# am-utils-6.1
# Erez Zadok <ezk@cs.columbia.edu> a.k.a. "The Lord of Darkness"
#
# modified by
# Ion Badulescu <ib42@cs.columbia.edu> a.k.a. "The Autofs Master"

** General notes about the autofs support in am-utils

The autofs code in am-utils is late-beta quality for Linux, beta quality for
Solaris 2.[678] and non-working for all the other systems.

* Caveats:

- [this applies mostly to Solaris/Irix] Amd acts as *both*
/usr/lib/autofs/automountd and /usr/sbin/automount.  There's no way to
distinguish between the two.  When amd starts, it first registers itself as
an autofs server (automountd's job), then parses its own maps, and decides
which autofs-type mounts to make (automount's job).  After the autofs mounts
are made, amd listens for requests from the kernel-based autofs, and acts
upon them. Since there can be only one autofs listener on a system, this
means that automountd and amd cannot run at the same time; nor can two amd's
run at the same time if they are both using autofs mounts.

- Linux support is available and fairly stable. Solaris 2.[678] support is
newer and less tested, but seems pretty stable as well. Solaris 2.5.1
support is further away. Irix autofs support will probably be very easy once
we get Solaris 2.5.1 to work, as they use the same protocol and almost
identical data structures. Not sure about HP-UX, but I'd guess it's similar
to some Solaris version.

- Killing amd can become a problem if there are active mounts. Since mounts
are done "in place", we can't just unmount our mount points and go away. For
now, amd simply tells the kernel it's dying; we need to think this further.
It would be nice to "take over" the old mountpoints, there is support for
this in Solaris (due to is RPC nature) and is easy to add to Linux.

* Solaris:

- Amd w/ autofs mounts will fight over the listener port with Sun's
  automounterd, so running both simultaneously is a really bad idea.

- Browsable_dirs is possible and implemented for Solaris 2.6+.

- Direct mounts are implemented and work correctly.

- Symlinks work, but are inefficient. The kernel seems to time them out
  immediately after receiving them, so each access to a symlink causes a
  call to userspace. Needless to say, this negates the whole point of using
  autofs. Automountd seems to always use lofs mounts instead of symlinks,
  maybe we should do the same?

- Restarting autofs mounts is possible, but not implemented.

* Linux:

- Amd should work fine even when the Linux automounter is running, the
  mechanism being used prevents any kind of (evil) interaction between them.

- Browsing is unavailable if autofs support is used, due to limitations in
  the kernel-daemon protocol used by Linux 2.2 and 2.4. Only already-mounted
  nodes will appear in the autofs directory, and this is implemented entirely
  in the kernel.

- Toplvl and auto maps certainly support autofs mounting, that's what I am
  testing with.

- Host maps are supported with autofs4 (in Linux 2.3+). You need to add
  something like "alias autofs=autofs4" in /etc/modules.conf.

- Direct maps cannot be supported since there is no kernel support for them;
  we might be able to get something eventually, but don't hold your breath.
  If anything, we may do it using a regular NFS direct map and bind-mount on
  top of it.

- Inherit doesn't make much sense because we can't restart a hung autofs
  mount point, due to kernel limitations. This needs to be fixed in the
  Linux kernel; it's not particularly difficult, we might provide a patch at
  some point.

- Link and nfs types work; the others should work, but are not tested.

- Link (and lofs) mounts will use the new bind-mount support in Linux
  2.4+. No more symlinks! And /bin/pwd works great too.

* amd.conf requirements:

To tell amd to use an autofs-style mount point and mounts for a map, add

	mount_type = autofs

either to the global section, or to the sections of the individual maps you
selected. Mixing autofs and normal amd mount points in the same amd.conf
file *does* work.

* Map changes:

No changes are necessary. If a map is marked as autofs in amd.conf, mounts
are done "in place" and the "fs" parameter is simply ignored.

* Todo:

We are looking for volunteers to improve the autofs code!

(1) These fixes are needed:

- when the mount type is 'link', transparently translate it into a loopback
file system mount (lofs), that would mount in place, rather than supply a
symlink, at least on systems whose autofs doesn't support symlinks. Linux
does support symlinks, Solaris 2.6+ does too, 2.5.1 probably doesn't and
neither does Irix. Moreover, Sun's automountd always uses lofs for symlinks,
even on 2.6+, because symlinks are not cached in the kernel and thus are not
particularly efficient. [already done for Linux 2.4+ using bind mounts]

- complain if certain incompatible options (autofs and ...) are used. Direct
maps on Linux are one such case of incompatible options.

- if amd is killed or dies, the autofs mounts will remain intact as required
(your system is _not_ hung, yay!).  However, if you restart amd, it will not
correctly 'restart' the autofs mounts as the Sun automounter does.  Rather,
it might cause another mount to happen, which leaves your /etc/mnttab
cluttered with older mounts entries which cannot be unmounted. It might also
just pretend everything is ok, when in fact it isn't.

(2) Code expansion:

- [Solaris only] implement the sockets version of amu_get_autofs_address()
and create_autofs_service(), in conf/transp/transp_sockets.c. Not sure if
it's necessary, Solaris it still biased towards TLI/STREAMS in userspace.

- [Linux only] support kernel-based expirations

(3) Testing and porting to other systems:

- nothing has been tested on Irix, which reportedly has a similar
functioning autofs to Solaris 2.5.1. Given that Solaris 2.5.1 support is not
there yet, Irix won't work either.

- support for Linux autofs is fairly stable, we need testers!

- support for Solaris 2.6+ is pretty stable, so we need testers for it, too!

- did not test any version of Solaris on x86. Should work, but you have been
  warned. Testers are welcome.
