src/packaging/Debian/README.Debian

   1                             OpenAFS for Debian
   2
   3 Introduction
   4
   5   For an OpenAFS client system, install openafs-client and a kernel
   6   module.  See README.modules for information on how to build the kernel
   7   module for your system.  Then, read /etc/openafs/afs.conf to understand
   8   the client configuration options.  The openafs-client package will
   9   attempt to guess at a good cache configuration based on the size of your
  10   cache, but you may want to tune it further.  There are also other
  11   options configured in that file you may want to consider.
  12
  13   FAM does not work correctly with AFS except for directories that are
  14   world-readable since it does not run in the user's security context and
  15   therefore doesn't have the user's AFS tokens.  If you are using FAM,
  16   you'll encounter errors from file managers such as Nautilus that use it
  17   if you browse restricted AFS directories.  Instead of FAM, install
  18   gamin, which runs in the user's security context and works correctly
  19   with AFS.
  20
  21   For information on how to set up an OpenAFS server, read README.servers.
  22   You will want the openafs-fileserver package for a file server and,
  23   additionally, the openafs-dbserver package for a database server.
  24
  25 Documentation
  26
  27   For the complete OpenAFS manual, install openafs-doc.  This is the same
  28   documentation as found at <http://www.openafs.org/>, and is
  29   unfortunately outdated in several respects, but it's the best that we
  30   have at present.
  31
  32   If want to set up a new cell, read README.servers and then look at the
  33   example session in configuration-transcript.txt.gz in this directory.
  34   The procedure outlined in these two files is much simpler and more
  35   secure than the one in the OpenAFS documentation, but the OpenAFS
  36   documentation provides useful background.
  37
  38 Build Options
  39
  40   The OpenAFS file server has been built with --enable-demand-attach-fs,
  41   which enables a new method of handling volume attachment.  Volumes will
  42   be attached only when needed, and the file server will persist state to
  43   disk when shutting down for faster restarts.  This file server mode is
  44   experimental and should not yet be used for production data.  Please
  45   report any bugs you encounter.
  46
  47   The OpenAFS servers have been built with --enable-supergroups, which
  48   permits nesting of PTS groups.  Be aware that the PT database created by
  49   these packages is not compatible with servers not built with
  50   --enable-supergroups if nested PTS groups are used.  In other words, if
  51   you need the openafs-dbserver package to interoperate with ptservers
  52   that aren't built with this option, don't use this capability.
  53
  54   The OpenAFS client and kernel module have been built with
  55   --enable-disconnected, which enables experimental support for
  56   disconnected operations.  This support is still experimental and known
  57   to have problems, but should not interfere with normal use of AFS.  If
  58   you want to experiment with it, see fs help discon.
  59
  60 Changes Relative to Stock OpenAFS
  61
  62   Long-time AFS users may be confused by the directory layout.  The files
  63   that normally go in /usr/vice/etc go in /etc/openafs.  The cache should
  64   be mounted on /var/cache/openafs.  The server files have been moved
  65   around even more; see README.servers for the details.
  66
  67   The OpenAFS kernel module is named openafs, not libafs, to better match
  68   normal Linux kernel module naming standards.  The Debian source package
  69   only builds one kernel module that matches the kernel source tree it is
  70   built against and does not attempt to build separate SMP and non-SMP
  71   modules against the same tree.  Doing so does not work on all platforms.
  72   To distinguish between an SMP and a non-SMP kernel module package, use
  73   --append_to_version; see README.modules for more information.
  74
  75   The AFS up utility is installed as afs-up, since the standard name is
  76   rather generic.
  77
  78   The libopenafs-dev package only includes static libraries and there are
  79   no shared library packages.  The shared libraries built by AFS are not
  80   compatible with Debian policy.  They do not have a stable ABI or an
  81   appropriate SONAME.
  82
  83   kaserver is not included.  New AFS cells should use Kerberos v5 rather
  84   than the old K4-based kaserver KDC.
  85
  86 Debugging and Bug Reporting
  87
  88   The current OpenAFS installation process installs fileserver and
  89   volserver unstripped, since backtraces and other debugging information
  90   for those binaries are necessary to track down file server problems.
  91   For the Debian packages, the fileserver and volserver binaries in the
  92   openafs-fileserver package are stripped, but the debugging information
  93   is available in the openafs-dbg package, which can be installed
  94   separately.  If it is installed, gdb will find that debugging
  95   information automatically.
  96
  97   Eventually the openafs-dbg package will contain debugging information
  98   for all OpenAFS binaries.
  99
 100   When reporting a bug in the OpenAFS client, please include your exact
 101   kernel version and architecture (reportbug will do this for you).  Also,
 102   if the client caused a kernel oops or BUG, be sure to include the
 103   complete kernel output, including the lines before the oops.  That's
 104   where the OpenAFS error message, if any, will be.
 105
 106   When reporting a bug in the OpenAFS file server, please include
 107   backtrace information from a core dump, if any.  If the file server is
 108   deadlocked, you can capture a core dump using the gcore script that
 109   comes with the gdb package.  The file server is threaded, so use the
 110   command "thread apply all backtrace" in gdb to get a complete backtrace.
 111   It's also often useful to have the output of rxdebug <server> 7000 at
 112   the time of the problem and the FileLog from the file server.  You can
 113   increase the logging level of the file server with kill -TSTP (and reset
 114   it to 0 with kill -HUP).
 115
 116   You can report any bug in OpenAFS against the Debian package with
 117   reportbug and the OpenAFS package maintainers will forward the bug
 118   upstream as necessary.  If you do want to report a bug directly
 119   upstream, see http://www.openafs.org/ for bug reporting instructions.
 120
 121 PAM Authentication
 122
 123   Any new OpenAFS cell is strongly encouraged to use Kerberos v5 for
 124   authentication.  If you want PAM to automatically obtain AFS credentials
 125   and you are using Kerberos v5, you will want to install the libpam-krb5
 126   and libpam-afs-session packages and then put something like the
 127   following in /etc/pam.d/common-auth:
 128
 129       auth    [success=ok default=1]  pam_krb5.so ignore_root
 130       auth    [default=done]          pam_afs_session.so
 131       auth    required                pam_unix.so nullok_secure try_first_pass
 132
 133   and something like the following in /etc/pam.d/common-session:
 134
 135       session optional        pam_krb5.so ignore_root
 136       session optional        pam_afs_session.so
 137       session required        pam_unix.so
 138
 139   You'll probably also want the following in /etc/pam.d/common-account:
 140
 141       account required        pam_krb5.so ignore_root
 142       account required        pam_unix.so
 143
 144   There are, of course, many variations depending on what different
 145   mechanism you want to use and how you want to handle fallbacks.
 146
 147   If you are still using Kerberos v4 and the OpenAFS kaserver (or a KDC
 148   that understands the same protocol) for authentication, you can instead
 149   use the libpam-openafs-kaserver package and a configuration like:
 150
 151       auth    sufficient      pam_afs.so ignore_root
 152       auth    required        pam_unix.so nullok_secure try_first_pass
 153
 154   in /etc/pam.d/common-auth and:
 155
 156       session optional        pam_afs.so
 157       session required        pam_unix.so
 158
 159   in /etc/pam.d/common-session.  Use pam_afs.krb.so instead of pam_afs.so
 160   if you also want the PAM module to acquire a ticket cache for you.  If
 161   using this configuration with sshd, you may need to disable privilege
 162   separation to get everything working properly.  I've had mixed results
 163   with that.  Obviously, converting to Kerberos v5 authentication is
 164   strongly preferred.
 165
 166   If you are using the kaserver as your KDC, you may also want to install
 167   the openafs-kpasswd package to get the administrative utilities for
 168   managing those Kerberos accounts.
 169
 170  -- Russ Allbery <rra@debian.org>, Tue,  6 Apr 2010 15:04:42 -0700