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   The AFS client cache must be on an ext2 or ext3 partition.  Other file
  14   systems often do not support the semantics required by the AFS kernel
  15   module and will cause afsd to abort (to avoid kernel panics).  In
  16   particular, XFS, ReiserFS, and tmpfs will NOT work.  If you are using
  17   one of those file systems and don't have a spare partition for a
  18   separate file system for the cache, you need to use the -memcache option
  19   to afsd (although this is not always stable) or create a large file with
  20   dd, create an ext2 file system in it with mkfs, and then mount it with
  21   mount -o loop for use as a cache partition.
  22
  23   FAM does not work correctly with AFS except for directories that are
  24   world-readable since it does not run in the user's security context and
  25   therefore doesn't have the user's AFS tokens.  If you are using FAM,
  26   you'll encounter errors from file managers such as Nautilus that use it
  27   if you browse restricted AFS directories.  Instead of FAM, install
  28   gamin, which runs in the user's security context and works correctly
  29   with AFS.
  30
  31   For information on how to set up an OpenAFS server, read README.servers.
  32   You will want the openafs-fileserver package for a file server and,
  33   additionally, the openafs-dbserver package for a database server.
  34
  35 Documentation
  36
  37   For the complete OpenAFS manual, install openafs-doc.  This is the same
  38   documentation as found at <http://www.openafs.org/>, and is
  39   unfortunately outdated in several respects, but it's the best that we
  40   have at present.
  41
  42   If want to set up a new cell, read README.servers and then look at the
  43   example session in configuration-transcript.txt.gz in this directory.
  44   The procedure outlined in these two files is much simpler and more
  45   secure than the one in the OpenAFS documentation, but the OpenAFS
  46   documentation provides useful background.
  47
  48 Build Options
  49
  50   The OpenAFS servers have been built with --enable-supergroups, which
  51   permits nesting of PTS groups.  Be aware that the PT database created by
  52   these packages is not compatible with servers not built with
  53   --enable-supergroups if nested PTS groups are used.  In other words, if
  54   you need the openafs-dbserver package to interoperate with ptservers
  55   that aren't built with this option, don't use this capability.
  56
  57   bosserver is built with --enable-bos-new-config.  If
  58   /etc/openafs/BosConfig.new exists when bosserver starts, it will be
  59   renamed to /etc/openafs/BosConfig before the configuration file is
  60   read.  This allows queuing of changes to the configuration that will
  61   take effect at the next restart.
  62
  63 Changes Relative to Stock OpenAFS
  64
  65   Long-time AFS users may be confused by the directory layout.  The files
  66   that normally go in /usr/vice/etc go in /etc/openafs.  The cache should
  67   be mounted on /var/cache/openafs.  The server files have been moved
  68   around even more; see README.servers for the details.
  69
  70   The OpenAFS kernel module is named openafs, not libafs, to better match
  71   normal Linux kernel module naming standards.  The Debian source package
  72   only builds one kernel module that matches the kernel source tree it is
  73   built against and does not attempt to build separate SMP and non-SMP
  74   modules against the same tree.  Doing so does not work on all platforms.
  75   To distinguish between an SMP and a non-SMP kernel module package, use
  76   --append_to_version; see README.modules for more information.
  77
  78   The OpenAFS servers have been patched to support listing up to four
  79   realms in /etc/openafs/server/krb.conf.  Any realms listed in that file
  80   (all on one line, space-separated) will be treated as local for
  81   authorization decisions (in other words, the relam will be stripped off
  82   and the unqualified principal name checked against AFS ACLs, UserList,
  83   PTS groups, and so forth).  The default OpenAFS server only supports
  84   listing one realm in this file.
  85
  86   The AFS up utility is installed as afs-up, since the standard name is
  87   rather generic.
  88
  89   The libopenafs-dev package only includes static libraries and there are
  90   no shared library packages.  The shared libraries built by AFS are not
  91   compatible with Debian policy.  They do not have a stable ABI or an
  92   appropriate SONAME.
  93
  94   kaserver is not included.  New AFS cells should use Kerberos v5 rather
  95   than the old K4-based kaserver KDC.
  96
  97   The OpenAFS PAM modules have been built with pthreads rather than the
  98   standard LWP AFS libraries for compatibility with a threaded sshd.
  99
 100 Debugging and Bug Reporting
 101
 102   The current OpenAFS installation process installs fileserver and
 103   volserver unstripped, since backtraces and other debugging information
 104   for those binaries are necessary to track down file server problems.
 105   For the Debian packages, the fileserver and volserver binaries in the
 106   openafs-fileserver package are stripped, but the debugging information
 107   is available in the openafs-dbg package, which can be installed
 108   separately.  If it is installed, gdb will find that debugging
 109   information automatically.
 110
 111   Eventually the openafs-dbg package will contain debugging information
 112   for all OpenAFS binaries.  This is pending upstream changes to the stock
 113   OpenAFS installation rules.
 114
 115   When reporting a bug in the OpenAFS client, please include your exact
 116   kernel version and architecture (reportbug will do this for you).  Also,
 117   if the client caused a kernel oops or BUG, be sure to include the
 118   complete kernel output, including the lines before the oops.  That's
 119   where the OpenAFS error message, if any, will be.
 120
 121   When reporting a bug in the OpenAFS file server, please include
 122   backtrace information from a core dump, if any.  If the file server is
 123   deadlocked, you can capture a core dump using the gcore script that
 124   comes with the gdb package.  The file server is threaded, so use the
 125   command "thread apply all backtrace" in gdb to get a complete backtrace.
 126   It's also often useful to have the output of rxdebug <server> 7000 at
 127   the time of the problem and the FileLog from the file server.  You can
 128   increase the logging level of the file server with kill -TSTP (and reset
 129   it to 0 with kill -HUP).
 130
 131   You can report any bug in OpenAFS against the Debian package with
 132   reportbug and the OpenAFS package maintainers will forward the bug
 133   upstream as necessary.  If you do want to report a bug directly
 134   upstream, see http://www.openafs.org/ for bug reporting instructions.
 135
 136 PAM Authentication
 137
 138   Any new OpenAFS cell is strongly encouraged to use Kerberos v5 for
 139   authentication.  If you want PAM to automatically obtain AFS credentials
 140   and you are using Kerberos v5, you will want to install the libpam-krb5
 141   and libpam-openafs-session packages and then put something like the
 142   following in /etc/pam.d/common-auth:
 143
 144       auth    [success=ok default=1]  pam_krb5.so ignore_root
 145       auth    [default=done]          pam_openafs_session.so
 146       auth    required                pam_unix.so nullok_secure try_first_pass
 147
 148   and something like the following in /etc/pam.d/common-session:
 149
 150       session optional        pam_krb5.so ignore_root
 151       session optional        pam_openafs_session.so
 152       session required        pam_unix.so
 153
 154   You'll probably also want the following in /etc/pam.d/common-account:
 155
 156       account required        pam_krb5.so ignore_root
 157       account required        pam_unix.so
 158
 159   There are, of course, many variations depending on what different
 160   mechanism you want to use and how you want to handle fallbacks.
 161
 162   If you are still using Kerberos v4 and the OpenAFS kaserver (or a KDC
 163   that understands the same protocol) for authentication, you can instead
 164   use the libpam-openafs-kaserver package and a configuration like:
 165
 166       auth    sufficient      pam_afs.so ignore_root
 167       auth    required        pam_unix.so nullok_secure try_first_pass
 168
 169   in /etc/pam.d/common-auth and:
 170
 171       session optional        pam_afs.so
 172       session required        pam_unix.so
 173
 174   in /etc/pam.d/common-session.  Use pam_afs.krb.so instead of pam_afs.so
 175   if you also want the PAM module to acquire a ticket cache for you.  If
 176   using this configuration with sshd, you may need to disable privilege
 177   separation to get everything working properly.  I've had mixed results
 178   with that.  Obviously, converting to Kerberos v5 authentication is
 179   strongly preferred.
 180
 181   If you are using the kaserver as your KDC, you may also want to install
 182   the openafs-kpasswd package to get the administrative utilities for
 183   managing those Kerberos accounts.
 184
 185  -- Russ Allbery <rra@debian.org>, Mon, 17 Dec 2007 18:29:42 -0800