--- /dev/null
+ OpenAFS for Debian
+
+Introduction
+
+ For an OpenAFS client system, install openafs-client and a kernel
+ module. See README.modules for information on how to build the kernel
+ module for your system. Then, read /etc/openafs/afs.conf to understand
+ the client configuration options. The openafs-client package will
+ attempt to guess at a good cache configuration based on the size of your
+ cache, but you may want to tune it further. There are also other
+ options configured in that file you may want to consider.
+
+ FAM does not work correctly with AFS except for directories that are
+ world-readable since it does not run in the user's security context and
+ therefore doesn't have the user's AFS tokens. If you are using FAM,
+ you'll encounter errors from file managers such as Nautilus that use it
+ if you browse restricted AFS directories. Instead of FAM, install
+ gamin, which runs in the user's security context and works correctly
+ with AFS.
+
+ For information on how to set up an OpenAFS server, read README.servers.
+ You will want the openafs-fileserver package for a file server and,
+ additionally, the openafs-dbserver package for a database server.
+
+Documentation
+
+ For the complete OpenAFS manual, install openafs-doc. This is the same
+ documentation as found at <http://www.openafs.org/>, and is
+ unfortunately outdated in several respects, but it's the best that we
+ have at present.
+
+ If want to set up a new cell, read README.servers and then look at the
+ example session in configuration-transcript.txt.gz in this directory.
+ The procedure outlined in these two files is much simpler and more
+ secure than the one in the OpenAFS documentation, but the OpenAFS
+ documentation provides useful background.
+
+Build Options
+
+ The OpenAFS file server has been built with --enable-demand-attach-fs,
+ which enables a new method of handling volume attachment. Volumes will
+ be attached only when needed, and the file server will persist state to
+ disk when shutting down for faster restarts. This file server mode is
+ experimental and should not yet be used for production data. Please
+ report any bugs you encounter.
+
+ The OpenAFS servers have been built with --enable-supergroups, which
+ permits nesting of PTS groups. Be aware that the PT database created by
+ these packages is not compatible with servers not built with
+ --enable-supergroups if nested PTS groups are used. In other words, if
+ you need the openafs-dbserver package to interoperate with ptservers
+ that aren't built with this option, don't use this capability.
+
+ The OpenAFS client and kernel module have been built with
+ --enable-disconnected, which enables experimental support for
+ disconnected operations. This support is still experimental and known
+ to have problems, but should not interfere with normal use of AFS. If
+ you want to experiment with it, see fs help discon.
+
+Changes Relative to Stock OpenAFS
+
+ Long-time AFS users may be confused by the directory layout. The files
+ that normally go in /usr/vice/etc go in /etc/openafs. The cache should
+ be mounted on /var/cache/openafs. The server files have been moved
+ around even more; see README.servers for the details.
+
+ The OpenAFS kernel module is named openafs, not libafs, to better match
+ normal Linux kernel module naming standards. The Debian source package
+ only builds one kernel module that matches the kernel source tree it is
+ built against and does not attempt to build separate SMP and non-SMP
+ modules against the same tree. Doing so does not work on all platforms.
+ To distinguish between an SMP and a non-SMP kernel module package, use
+ --append_to_version; see README.modules for more information.
+
+ The AFS up utility is installed as afs-up, since the standard name is
+ rather generic.
+
+ The libopenafs-dev package only includes static libraries and there are
+ no shared library packages. The shared libraries built by AFS are not
+ compatible with Debian policy. They do not have a stable ABI or an
+ appropriate SONAME.
+
+ kaserver is not included. New AFS cells should use Kerberos v5 rather
+ than the old K4-based kaserver KDC.
+
+Debugging and Bug Reporting
+
+ The current OpenAFS installation process installs fileserver and
+ volserver unstripped, since backtraces and other debugging information
+ for those binaries are necessary to track down file server problems.
+ For the Debian packages, the fileserver and volserver binaries in the
+ openafs-fileserver package are stripped, but the debugging information
+ is available in the openafs-dbg package, which can be installed
+ separately. If it is installed, gdb will find that debugging
+ information automatically.
+
+ Eventually the openafs-dbg package will contain debugging information
+ for all OpenAFS binaries.
+
+ When reporting a bug in the OpenAFS client, please include your exact
+ kernel version and architecture (reportbug will do this for you). Also,
+ if the client caused a kernel oops or BUG, be sure to include the
+ complete kernel output, including the lines before the oops. That's
+ where the OpenAFS error message, if any, will be.
+
+ When reporting a bug in the OpenAFS file server, please include
+ backtrace information from a core dump, if any. If the file server is
+ deadlocked, you can capture a core dump using the gcore script that
+ comes with the gdb package. The file server is threaded, so use the
+ command "thread apply all backtrace" in gdb to get a complete backtrace.
+ It's also often useful to have the output of rxdebug <server> 7000 at
+ the time of the problem and the FileLog from the file server. You can
+ increase the logging level of the file server with kill -TSTP (and reset
+ it to 0 with kill -HUP).
+
+ You can report any bug in OpenAFS against the Debian package with
+ reportbug and the OpenAFS package maintainers will forward the bug
+ upstream as necessary. If you do want to report a bug directly
+ upstream, see http://www.openafs.org/ for bug reporting instructions.
+
+PAM Authentication
+
+ Any new OpenAFS cell is strongly encouraged to use Kerberos v5 for
+ authentication. If you want PAM to automatically obtain AFS credentials
+ and you are using Kerberos v5, you will want to install the libpam-krb5
+ and libpam-afs-session packages and then put something like the
+ following in /etc/pam.d/common-auth:
+
+ auth [success=ok default=1] pam_krb5.so ignore_root
+ auth [default=done] pam_afs_session.so
+ auth required pam_unix.so nullok_secure try_first_pass
+
+ and something like the following in /etc/pam.d/common-session:
+
+ session optional pam_krb5.so ignore_root
+ session optional pam_afs_session.so
+ session required pam_unix.so
+
+ You'll probably also want the following in /etc/pam.d/common-account:
+
+ account required pam_krb5.so ignore_root
+ account required pam_unix.so
+
+ There are, of course, many variations depending on what different
+ mechanism you want to use and how you want to handle fallbacks.
+
+ If you are still using Kerberos v4 and the OpenAFS kaserver (or a KDC
+ that understands the same protocol) for authentication, you can instead
+ use the libpam-openafs-kaserver package and a configuration like:
+
+ auth sufficient pam_afs.so ignore_root
+ auth required pam_unix.so nullok_secure try_first_pass
+
+ in /etc/pam.d/common-auth and:
+
+ session optional pam_afs.so
+ session required pam_unix.so
+
+ in /etc/pam.d/common-session. Use pam_afs.krb.so instead of pam_afs.so
+ if you also want the PAM module to acquire a ticket cache for you. If
+ using this configuration with sshd, you may need to disable privilege
+ separation to get everything working properly. I've had mixed results
+ with that. Obviously, converting to Kerberos v5 authentication is
+ strongly preferred.
+
+ If you are using the kaserver as your KDC, you may also want to install
+ the openafs-kpasswd package to get the administrative utilities for
+ managing those Kerberos accounts.
+
+ -- Russ Allbery <rra@debian.org>, Tue, 6 Apr 2010 15:04:42 -0700