readme: Rename README to INSTALL
authorMichael Meffie <mmeffie@sinenomine.net>
Mon, 31 Mar 2014 18:03:58 +0000 (14:03 -0400)
committerJeffrey Altman <jaltman@your-file-system.com>
Tue, 18 Aug 2015 02:11:07 +0000 (22:11 -0400)
Create a new top level README to introduce OpenAFS.

Move the old README to a file called INSTALL for information about
building and installing OpenAFS on various platforms.

Change-Id: Id8853de73f669a6d5497cafd65a1e98b309c6efc
Reviewed-on: http://gerrit.openafs.org/10976
Tested-by: BuildBot <buildbot@rampaginggeek.com>
Reviewed-by: Jeffrey Altman <jaltman@your-file-system.com>

INSTALL [new file with mode: 0644]
README

diff --git a/INSTALL b/INSTALL
new file mode 100644 (file)
index 0000000..f4bdf64
--- /dev/null
+++ b/INSTALL
@@ -0,0 +1,557 @@
+Copyright 2000, International Business Machines Corporation and others.
+All Rights Reserved.
+
+This software has been released under the terms of the IBM Public
+License.  For details, see the LICENSE file in the top-level
+directory or online at http://www.openafs.org/dl/license10.html
+
+Short instructions for sites upgrading from a previous version of AFS:
+% ./configure --enable-transarc-paths
+% make
+% make dest
+
+will create a Transarc-style dest tree in ${SYS_NAME}/dest where
+${SYS_NAME} is the AFS sysname of the system you built for.
+This assumes if you're building for Linux that your kernel source is
+in /usr/src/linux.
+
+Otherwise, please read on.
+
+Building OpenAFS on UNIX and Linux
+----------------------------------
+
+A  Configuring
+
+   Uncompress the source into a directory of your choice. A directory
+   in afs space is also valid. In the directory that you uncompressed the
+   source in, you will only have an src/ directory.
+
+   1. Pick a system to build for, and note its default AFS sys_name.
+      A directory will be automatically created for binaries to be written
+      into with this name when you build.
+
+      alpha_dux40, alpha_dux50, alpha_dux51 (client does not work)
+      alpha_linux26
+      alpha_nbsd15, alpha_nbsd16
+      amd64_fbsd_80, amd64_fbsd_81, amd64_fbsd_82, amd64_fbsd_83,
+         amd64_fbsd_84, amd64_fbsd_90, amd64_fbsd_91, amd64_fbsd_92,
+         amd64_fbsd_93, amd64_fbsd_100, amd64_fbsd_101
+      amd64_linux26
+      amd64_nbsd20, amd64_nbsd30, amd64_nbsd40
+      arm_linux26
+      hp_ux11i, hp_ux110, hp_ux1123 (See notes below for information on
+         getting missing header)
+      hp_ux102 (Client port possible, but db servers and utilities work)
+      i386_fbsd_80, i386_fbsd_81, i386_fbsd_82, i386_fbsd_83,
+         i386_fbsd_84, i386_fbsd_90, i386_fbsd_91, i386_fbsd_92,
+         i386_fbsd_93, i386_fbsd_100, i386_fbsd_101
+      i386_linux26
+      i386_nbsd15, i386_nbsd16, i386_nbsd20, i386_nbsd21, i386_nbsd30,
+         i386_nbsd40
+      i386_obsd31, i386_obsd32, i386_obsd33, i386_obsd34, i386_obsd35,
+         i386_obsd36, i386_obsd37, i386_obsd38, i386_obsd39, i386_obsd40,
+         i386_obsd41
+      i386_umlinux26
+      ia64_hpux1122, ia64_hpux1123
+      ia64_linux26
+      ppc64_linux26
+      ppc_darwin_12, ppc_darwin_13, ppc_darwin_14, ppc_darwin_60,
+         ppc_darwin_70, ppc_darwin_80, ppc_darwin_90
+      ppc_linux26
+      ppc_nbsd16, ppc_nbsd20
+      rs_aix42, rs_aix51, rs_aix52, rs_aix53, rs_aix61
+      s390_linux26
+      s390x_linux26
+      sgi_62, sgi_63, sgi_64, sgi_65 (file server not tested)
+      sparc64_linux26
+      sun4x_58, sun4x_59, sun4x_510, sun4x_511
+         (logging UFS not supported for mixed-use partitions containing
+         client cache)
+      sunx86_58, sunx86_59, sunx86_510, sunx86_511
+         (logging UFS not supported for mixed-use partitions containing
+         client cache)
+      x86_darwin_80, x86_darwin90
+
+   2. Using configure in the top level directory, configure for your
+      AFS system type, providing the necessary flags:
+
+      % ./configure --with-afs-sysname=sun4x_58 --enable-transarc-paths
+
+      If you do not have the "configure" script, or if you modify the
+      source files, you can re-create it by running regen.sh.  You will
+      need autoconf to do this.
+
+      For some systems you need also provide the path in which your kernel
+      headers for your configured kernel can be found.  See the
+      system-specific Notes sections below for details.  If you want to
+      build only the user-space programs and servers and not the kernel
+      module, specify the --disable-kernel-module option on the
+      ./configure command line.
+
+      All binaries, except for the 'fileserver' and 'volserver'
+      executables and their 'da' variants, are stripped of their symbol
+      table information by default.  To enable a debugging build, specify
+      the --enable-debug option on the ./configure command line.  This
+      builds with debugging compiler options and disables stripping of
+      binaries.
+
+      You can also use different combinations of --enable-debug and
+      --enable (or --disable)-strip-binaries for finer control.  One can,
+      for example, compile binaries for debug and strip them anyway.
+      Alternatively, one can compile without debug and force the binaries
+      to not be stripped.  Note that these combinations are not
+      necessarily useful.
+
+      The binaries noted above, 'fileserver' and 'volserver' and their
+      'da' variants, will never be stripped, regardless of any options
+      given to configure.
+
+   There are two modes for directory path handling: "Transarc mode" and
+   "default mode":
+
+   - In Transarc mode, we retain compatibility with Transarc/IBM AFS tools
+     by putting client configuration files in /usr/vice/etc, and server
+     files in /usr/afs under the traditional directory layout.
+   - In default mode, files are located in standardized locations, usually
+     under $(prefix), which defaults to /usr/local.
+   - Client programs, libraries, and related files always go in standard
+     directories under $(prefix).  This rule covers things that would go
+     into $(bindir), $(includedir), $(libdir), $(mandir), and $(sbindir).
+   - Other files get located in the following places:
+
+    Directory     Transarc Mode              Default Mode
+    ============  =========================  ==============================
+    viceetcdir    /usr/vice/etc              $(sysconfdir)/openafs
+    afssrvdir     /usr/afs/bin (servers)     $(libexecdir)/openafs
+    afsconfdir    /usr/afs/etc               $(sysconfdir)/openafs/server
+    afslocaldir   /usr/afs/local             $(localstatedir)/openafs
+    afsdbdir      /usr/afs/db                $(localstatedir)/openafs/db
+    afslogdir     /usr/afs/logs              $(localstatedir)/openafs/logs
+    afsbosconfig  $(afslocaldir)/BosConfig   $(afsconfdir)/BosConfig
+    afsbosserver  $(afsbindir)/bosserver     $(sbindir)/bosserver
+
+   In default mode, you can change all of the variables named above that
+   do not start with "afs" by passing the flags with the same name to
+   configure.  For example, if you want to install the server binaries in
+   /usr/local/lib/openafs instead of /usr/local/libexec/openafs, pass the
+   --libexecdir=/usr/local/lib flag to configure.
+
+   For additional options, see section I below.
+
+B  Building
+
+   1. Now, you can build OpenAFS.
+
+      % make
+
+   2. Install your build using either "make install" to install
+      into the current system (you will need to be root, and files
+      will be placed as appropriate for Transarc or standard paths),
+      "make install DESTDIR=/some/path" to install into an alternate
+      directory tree, or if you configured with --enable-transarc-paths
+      make dest to create a complete binary tree in the dest directory
+      under the directory named for the sys_name you built for,
+      e.g. sun4x_57/dest or i386_linux26/dest
+
+   3. As appropriate you can clean up or, if you're using Linux, build for
+      another kernel version.
+
+      To clean up:
+
+      % make clean
+
+C  Problems
+
+   If you have a problem building this source, you may want to visit
+   http://www.openafs.org/ to see if any problems have been reported
+   or to find out how to get more help.
+
+   Mailing lists have been set up to help; More details can be found
+   on the openafs.org site.
+
+D  Linux Notes
+
+   With current Linux versions, the /lib/modules/`uname -r`/source symlink
+   will be used to locate the kernel headers, but you will need to have
+   the headers and build system for your kernel installed in order to
+   build the kernel module.  These are usually found in a separate package
+   from the kernel, often called something like linux-headers-<version>.
+
+   For older Linux systems, you may also need to provide the path in which
+   your kernel headers for your configured kernel can be found. This
+   should be the path of the directory containing a child directory named
+   "include". So if your version file were
+   /usr/src/linux/include/linux/version.h you would run:
+
+   % ./configure --with-afs-sysname=i386_linux26 \
+       --with-linux-kernel-headers=/usr/src/linux
+
+   Currently you can build for only one Linux kernel at a time, and the
+   version is extracted from the kernel headers in the root you specify.
+
+   To build for another Linux kernel version, determine the sysname for
+   the system type as defined in step A1 for the other kernel version and
+   then run:
+
+      % ./configure --with-afs-sysname=<sysname> \
+          --with-linux-kernel-headers=/usr/src/linux-3.19-i686
+      % make
+
+   Your build tree will now include an additional kernel module for your
+   additional kernel headers. Be aware that if the kernel version string
+   which UTS_RELEASE is defined to in include/linux/version.h matches the
+   last kernel you built for, the previous kernel module will be
+   overwritten.
+
+   The Linux 2.4 series (and older) are no longer supported. The OpenAFS 1.6
+   series of releases are the last ones supporting those old kernels and in
+   particular their LinuxThreads.
+
+E  HP-UX 11.0 Notes
+
+   HP-UX 11.0 requires a header called vfs_vm.h which HP has provided on
+   their web site.  Go to http://www.hp.com/dspp, choose Software
+   downloads from the side menu, and select Software: HP operating systems
+   and then Operating systems: HP-UX from the select boxes.  The last
+   select box will have an option for downloading vfs_vm.h.
+
+F  OpenBSD Notes
+
+   If you need to run regen.sh to make the configure script, you should
+   first install autoconf-2.59, then setenv AUTOCONF_VERSION 2.59.
+
+   You need kernel source installed to build OpenAFS.  Use the
+   --with-bsd-kernel-headers= configure option if your kernel source is
+   not in /usr/src/sys.
+
+   src/packaging/OpenBSD/buildpkg.sh will make a tar file for installing
+   the client.  There is no server package, but I am told that "make
+   install" will put server binaries in /usr/afs.
+
+   Your kernel may panic when you try to shutdown after running the
+   OpenAFS client.  To prevent this, change the "dangling vnode" panic in
+   sys/kern/vfs_syscalls.c to a printf and build a new kernel.
+
+   You can't run arla and OpenAFS at the same time.
+
+G  FreeBSD Notes
+
+   The FreeBSD client supports FreeBSD 8.x and later, but does not receive
+   regular testing on versions older than FreeBSD 9.x at this time.  Only
+   the amd64 and i386 architectures are supported, but it should not be
+   hard to port to other processors if they are already supported under
+   another operating system.
+
+   You need kernel source installed to build OpenAFS.  Use the
+   --with-bsd-kernel-headers= configure option if your kernel source is
+   not in /usr/src/sys.
+
+   You also need access to your kernel build directory for the opt_global.h
+   include file.  Use the --with-bsd-kernel-build= configure option if your
+   kernel build is not GENERIC in the standard place. If
+   /usr/src/sys/${CPUARCH}/compile/GENERIC does not point to
+   /usr/obj/usr/src/sys/GENERIC you may need to resolve that and retry the
+   build.
+
+H  AIX notes
+
+   Make sure that your default build environment is 32bit, ie.
+   the OBJECT_MODE environment variable is either unset or set to "32".
+
+   Verify this before doing configure and make. For example, assuming
+   ksh/bash:
+
+   % export OBJECT_MODE=32
+
+   To build aklog (in order to be able to get tokens from your Kerberos v5
+   ticket), you will need Kerberos libraries.  On AIX 6.1, the IBM
+   Kerberos v5 libraries are in the packages krb5.client.rte and
+   krb5.toolkit.adt on the Expansion Pack.
+
+I  Other configure options
+
+   AFS has a ton of other optional features that must be enabled using
+   configure options.  Here is a summary:
+
+   --enable-bigendian
+   --enable-littleendian
+       These configure options are normally not required and should not be
+       given.  They're only needed if the OpenAFS build system cannot
+       determine the endianness of your system, in which case configure
+       will abort and say to use one of these options.
+
+   --enable-bitmap-later
+       Speeds the startup of the fileserver by deferring reading volume
+       bitmaps until necessary.  Demand attach is a better solution to the
+       same problem.
+
+   --enable-checking
+       Enable compiler warnings when building with GCC and turn compiler
+       warnings into errors so that new warnings will cause compilation
+       failures.  If you are developing patches to contribute to OpenAFS,
+       please build OpenAFS with this flag enabled.  Warning-free code is
+       a requirement for all new submissions to OpenAFS.
+
+   --enable-debug
+   --enable-debug-kernel
+   --enable-debug-lwp
+   --enable-debug-pam
+       Compile the userspace code (for --enable-debug) or the code named
+       by the option with debugging information.  If --enable-debug is
+       given, also do not strip binaries when installing them.
+
+   --enable-linux-d_splice_alias-extra-iput
+       Work around a kernel memory leak present in a few Linux kernels.
+       The only affected mainline kernels are 3.17 to 3.17.2, but this
+       switch will also be required should a distribution backport commit
+       908790fa3b779d37365e6b28e3aa0f6e833020c3 or commit
+       95ad5c291313b66a98a44dc92b57e0b37c1dd589 but not the fix in commit
+       51486b900ee92856b977eacfc5bfbe6565028070 from the linux-stable repo
+       (git.kernel.org/cgit/linux/kernel/git/stable/linux-stable.git) or
+       the corresponding changes on other branches. This is impossible to
+       detect automatically. Without this switch, the openafs module will
+       build and work even with affected kernels. But it will leak kernel
+       memory, leading to performance degradation and eventually system
+       failure due to memory exhaustion.
+
+   --enable-linux-syscall-probing
+       OpenAFS now uses keyrings to manage PAGs by default on Linux, which
+       does not require hooking into the system call table.  On older
+       versions of Linux without keyring support, OpenAFS uses groups to
+       manage PAGs and probes for the system call table to hook into it to
+       preserve that group information.  Normally, which method to use is
+       detected automatically, and if keyring support is present, support
+       for system call table probing is not compiled in.  Use this
+       configure option to force inclusion of the system call table
+       probing code even if the kernel appears to support keyrings.
+
+   --enable-namei-fileserver
+       Forces the namei fileserver on platforms (like Solaris 8 and 9)
+       where the inode fileserver is the default.
+
+   --enable-pthreaded-ubik
+       Enable the threaded version of Ubik and install the threaded
+       versions of Ubik servers.  See README.PTHREADED_UBIK for more
+       information.  (EXPERIMENTAL)
+
+   --enable-redhat-buildsys
+       Enable compilation of the kernel module for the Red Hat build
+       system kernel.  Use this configure flag when building kernel
+       modules for Red Hat Linux systems.
+
+   --enable-reduced-depends
+       Try to minimize the shared library dependencies encoded in the
+       binaries.  This omits from the link line all the libraries included
+       solely because the Kerberos libraries depend on them and instead
+       links the programs only against libraries whose APIs are called
+       directly.  This will only work with shared Kerberos libraries and
+       will only work on platforms where shared libraries properly encode
+       their own dependencies (such as Linux).  It is intended primarily
+       for building packages for Linux distributions to avoid encoding
+       unnecessary shared library dependencies that make shared library
+       migrations more difficult.  If none of the above made any sense to
+       you, don't bother with this flag.
+
+   --enable-supergroups
+       Enables support of nested groups in the ptserver.  WARNING: Once
+       you make use of this option by nesting one group inside another,
+       the resulting PTS database cannot be correctly and safely used by a
+       ptserver built without this option.  If some of your ptservers were
+       built with this option and some without this option, you will
+       probably corrupt your PTS database.
+
+   --enable-tivoli-tsm
+       Build with the Tivoli TSM API libraries for butc support of the
+       Tivoli backup system.
+
+   --enable-transarc-paths
+       As discussed in A2 above, build for the traditional paths used by
+       the Transarc and IBM AFS distributions instead of the more typical
+       open source /usr/local paths.  Passing this option to configure and
+       then running make dest will generate, in the dest directory, the
+       set of files and directory layout matching a Transarc or IBM AFS
+       tape distribution.
+
+   --enable-warnings
+       Enable compilation warnings when built with GCC.  This is similar
+       to --enable-checking, but new warnings will only be displayed, not
+       cause a build failure.
+
+   It's also possible to disable some standard features.  None of these
+   options are normally needed, but they may be useful in unusual
+   circumstances:
+
+   --disable-kernel-module
+       Even if kernel headers are found, do not attempt to build the
+       kernel module.  On Linux, if you provide this flag, you'll also
+       need to provide --with-afs-sysname, since OpenAFS cannot determine
+       the correct sysname automatically without the kernel headers.
+
+   --disable-optimize
+   --disable-optimize-kernel
+   --disable-optimize-lwp
+   --disable-optimize-pam
+       Disable optimization for the given portion of the OpenAFS code.
+       Usually used either for debugging to avoid code optimization making
+       it harder to use a debugger, or to work around bugs in the compiler
+       optimizers or in the OpenAFS code.
+
+   --disable-pam
+       Do not build the AFS PAM modules.  Normally building them is
+       harmless, but the PAM modules that come with OpenAFS are deprecated
+       and should not be used unless you're still using the OpenAFS
+       kaserver (which is itself deprecated and should not be used).
+
+   --disable-strip-binaries
+       Disable stripping of binaries on installation.  You probably want
+       to use --enable-debug instead of this flag to also inclusion of
+       debugging information.
+
+   --disable-unix-sockets
+       Disable use of UNIX domain sockets for fssync.  A TCP connection to
+       localhost will be used instead.
+
+   You may need to pass one or more of the following options to specify
+   paths and locations of files needed by the OpenAFS build process or
+   additional information required by the build process:
+
+   --with-afs-sysname=SYSNAME
+       Specifies the AFS sysname of the target system is SYSNAME.
+       Normally this is determined automatically from the build
+       architecture plus additional information (such as, on Linux, from
+       the kernel headers).  The SYSNAME should be one of the options
+       listed in A2.
+
+   --with-gssapi=DIR
+   --with-gssapi-include=DIR
+   --with-gssapi-lib=DIR
+   --with-krb5[=DIR]
+   --with-krb5-include=DIR
+   --with-krb5-lib=DIR
+       Normally, OpenAFS will automatically build with Kerberos support if
+       Kerberos is found during the build.  If your Kerberos libraries are
+       in an unusual location, however, you may need to pass one or more
+       of these flags.  --with-krb5 forces building with Kerberos support
+       if given and will cause configure to fail if Kerberos is not found.
+       You may optionally specify the root path to your Kerberos
+       installation as an argument to --with-krb5.
+
+       If you have a krb5-config script, it's used to find the flags to
+       build with Kerberos.  If you have no krb5-config script, you can
+       specify the location to the include files with --with-krb5-include
+       and the libraries with --with-krb5-lib.  You may need to do this if
+       Autoconf can't figure out whether to use lib, lib32, or lib64 on
+       your platform.
+
+       --with-gssapi is similar, except for the GSS-API libraries instead
+       of the Kerberos libraries.  If you have to manually set the
+       location of the Kerberos libraries, you may need to do the same
+       thing for the GSS-API libraries.
+
+   --with-libintl=DIR
+   --with-libintl-include=DIR
+   --with-libintl-lib=DIR
+       Specifies the install location of the libintl library, used for
+       internationalization, or separately specifies the location of the
+       header files and libraries.  By default, the default system library
+       paths will be searched.  This library is not required on many
+       platforms.
+
+   --with-roken=PATH
+   --with-roken=internal
+       Specifies the install location of the libroken library.  Specify
+       "internal" to use the embedded libroken library that comes with
+       OpenAFS (the default).  This option is primarily useful for
+       building against a system libroken library if you have one.
+
+   --with-linux-kernel-build=PATH
+   --with-linux-kernel-headers=PATH
+   --with-bsd-kernel-build=PATH
+   --with-bsd-kernel-headers=PATH
+       Specifies the path to the kernel headers and build system.  See the
+       information above for Linux and *BSD systems.
+
+   --with-linux-kernel-packaging
+       Tells the OpenAFS kernel module build system to use conventions
+       appropriate for building modules to include in Linux kernel module
+       packages.  Primarily, this renames the kernel module to openafs.ko
+       rather than libafs-<VERSION>.ko, which is easier to handle in Linux
+       distribution init scripts.
+
+   --with-docbook2pdf=PROGRAM
+       Specifies the program used to convert the DocBook manuals to PDF.
+       Supported choices are fop, dblatex, and docbook2pdf.  By default,
+       the user's path is searched for those programs in that order, and
+       the first one found is used.
+
+   --with-docbook-stylesheets=PATH
+       The location of the DocBook style sheets, used to convert the
+       DocBook manuals to other formats.  By default, a set of likely
+       paths are searched.
+
+   --with-html-xsl=PATH
+       Specifies the XSLT style sheet to convert DocBook manuals into
+       HTML.  The default is html/chunk.xsl.  You may wish to use
+       html/docbook.xsml instead.
+
+   --with-xslt-processor=PROGRAM
+       Specifies the XSLT processor to use to convert the DocBook manuals
+       into HTML.  Supported choices are libxslt, saxon, xalan-j, and
+       xsltproc.  By default, the user's path is searched for those
+       programs in that order, and the first one found is used.
+
+   There are also some environment variables that you can set to control
+   aspects of the build.  They can be set either on the configure command
+   line (preferred) or in the environment.
+
+   CC
+       The C compiler to use.  Be aware that this is overridden on some
+       architectures that require a specific compiler be used to build the
+       kernel module.
+
+   CFLAGS
+       Additional flags to pass to the C compiler.
+
+   CPP
+       The C preprocessor to use.  Defaults to cpp if found, otherwise
+       $CC -E.
+
+   CPPFLAGS
+       Additional flags to pass to the C preprocessor or compiler.  This
+       is where to put -I options to add paths to the include file search.
+
+   FUSE_CFLAGS
+       Compiler flags required for building applications that use FUSE.
+
+   FUSE_LIBS
+       Libraries required for linking applications that use FUSE.
+
+   KRB5_CONFIG
+       To specify a particular krb5-config script to use, either set the
+       KRB5_CONFIG environment variable or pass it to configure like:
+
+           ./configure KRB5_CONFIG=/path/to/krb5-config
+
+       To not use krb5-config and force library probing even if there is a
+       krb5-config script on your path, set KRB5_CONFIG to a nonexistent
+       path:
+
+           ./configure KRB5_CONFIG=/nonexistent
+
+   LDFLAGS
+       Additional flags to pass to the linker.  This is where to put -L
+       options to add paths to the library search.
+
+   LIBS
+       Additional libraries to link all userspace programs with.
+
+   PKG_CONFIG
+       The path to the pkg-config utility.  Currently, this is only used
+       to locate the flags for building the FUSE version of afsd.
+
+   YACC
+       The yacc implementation to use.  Defaults to bison, byacc, or yacc,
+       whichever is found first.
+
+   YFLAGS
+       Additional flags to pass to yacc.
diff --git a/README b/README
index f4bdf64..7084112 100644 (file)
--- a/README
+++ b/README
-Copyright 2000, International Business Machines Corporation and others.
-All Rights Reserved.
 
-This software has been released under the terms of the IBM Public
-License.  For details, see the LICENSE file in the top-level
-directory or online at http://www.openafs.org/dl/license10.html
+AFS is a distributed file system that enables users to share and
+access all of the files stored in a network of computers as easily as
+they access the files stored on their local machines. The file system is
+called distributed for this exact reason: files can reside on many
+different machines, but are available to users on every machine.
 
-Short instructions for sites upgrading from a previous version of AFS:
-% ./configure --enable-transarc-paths
-% make
-% make dest
+OpenAFS 1.0 was originally released by IBM under the terms of the
+IBM Public License 1.0 (IPL10).  For details on IPL10 see the LICENSE
+file in this directory.  The current OpenAFS distribution is licensed
+under a combination of the IPL10 and many other licenses as granted by
+the relevant copyright holders.  The LICENSE file in this directory
+contains more details, thought not a comprehensive statement.
 
-will create a Transarc-style dest tree in ${SYS_NAME}/dest where
-${SYS_NAME} is the AFS sysname of the system you built for.
-This assumes if you're building for Linux that your kernel source is
-in /usr/src/linux.
+See INSTALL for information about building and installing OpenAFS
+on various platforms.
 
-Otherwise, please read on.
+See CODING for developer information and guidelines.
 
-Building OpenAFS on UNIX and Linux
-----------------------------------
+See NEWS for recent changes to OpenAFS.
 
-A  Configuring
-
-   Uncompress the source into a directory of your choice. A directory
-   in afs space is also valid. In the directory that you uncompressed the
-   source in, you will only have an src/ directory.
-
-   1. Pick a system to build for, and note its default AFS sys_name.
-      A directory will be automatically created for binaries to be written
-      into with this name when you build.
-
-      alpha_dux40, alpha_dux50, alpha_dux51 (client does not work)
-      alpha_linux26
-      alpha_nbsd15, alpha_nbsd16
-      amd64_fbsd_80, amd64_fbsd_81, amd64_fbsd_82, amd64_fbsd_83,
-         amd64_fbsd_84, amd64_fbsd_90, amd64_fbsd_91, amd64_fbsd_92,
-         amd64_fbsd_93, amd64_fbsd_100, amd64_fbsd_101
-      amd64_linux26
-      amd64_nbsd20, amd64_nbsd30, amd64_nbsd40
-      arm_linux26
-      hp_ux11i, hp_ux110, hp_ux1123 (See notes below for information on
-         getting missing header)
-      hp_ux102 (Client port possible, but db servers and utilities work)
-      i386_fbsd_80, i386_fbsd_81, i386_fbsd_82, i386_fbsd_83,
-         i386_fbsd_84, i386_fbsd_90, i386_fbsd_91, i386_fbsd_92,
-         i386_fbsd_93, i386_fbsd_100, i386_fbsd_101
-      i386_linux26
-      i386_nbsd15, i386_nbsd16, i386_nbsd20, i386_nbsd21, i386_nbsd30,
-         i386_nbsd40
-      i386_obsd31, i386_obsd32, i386_obsd33, i386_obsd34, i386_obsd35,
-         i386_obsd36, i386_obsd37, i386_obsd38, i386_obsd39, i386_obsd40,
-         i386_obsd41
-      i386_umlinux26
-      ia64_hpux1122, ia64_hpux1123
-      ia64_linux26
-      ppc64_linux26
-      ppc_darwin_12, ppc_darwin_13, ppc_darwin_14, ppc_darwin_60,
-         ppc_darwin_70, ppc_darwin_80, ppc_darwin_90
-      ppc_linux26
-      ppc_nbsd16, ppc_nbsd20
-      rs_aix42, rs_aix51, rs_aix52, rs_aix53, rs_aix61
-      s390_linux26
-      s390x_linux26
-      sgi_62, sgi_63, sgi_64, sgi_65 (file server not tested)
-      sparc64_linux26
-      sun4x_58, sun4x_59, sun4x_510, sun4x_511
-         (logging UFS not supported for mixed-use partitions containing
-         client cache)
-      sunx86_58, sunx86_59, sunx86_510, sunx86_511
-         (logging UFS not supported for mixed-use partitions containing
-         client cache)
-      x86_darwin_80, x86_darwin90
-
-   2. Using configure in the top level directory, configure for your
-      AFS system type, providing the necessary flags:
-
-      % ./configure --with-afs-sysname=sun4x_58 --enable-transarc-paths
-
-      If you do not have the "configure" script, or if you modify the
-      source files, you can re-create it by running regen.sh.  You will
-      need autoconf to do this.
-
-      For some systems you need also provide the path in which your kernel
-      headers for your configured kernel can be found.  See the
-      system-specific Notes sections below for details.  If you want to
-      build only the user-space programs and servers and not the kernel
-      module, specify the --disable-kernel-module option on the
-      ./configure command line.
-
-      All binaries, except for the 'fileserver' and 'volserver'
-      executables and their 'da' variants, are stripped of their symbol
-      table information by default.  To enable a debugging build, specify
-      the --enable-debug option on the ./configure command line.  This
-      builds with debugging compiler options and disables stripping of
-      binaries.
-
-      You can also use different combinations of --enable-debug and
-      --enable (or --disable)-strip-binaries for finer control.  One can,
-      for example, compile binaries for debug and strip them anyway.
-      Alternatively, one can compile without debug and force the binaries
-      to not be stripped.  Note that these combinations are not
-      necessarily useful.
-
-      The binaries noted above, 'fileserver' and 'volserver' and their
-      'da' variants, will never be stripped, regardless of any options
-      given to configure.
-
-   There are two modes for directory path handling: "Transarc mode" and
-   "default mode":
-
-   - In Transarc mode, we retain compatibility with Transarc/IBM AFS tools
-     by putting client configuration files in /usr/vice/etc, and server
-     files in /usr/afs under the traditional directory layout.
-   - In default mode, files are located in standardized locations, usually
-     under $(prefix), which defaults to /usr/local.
-   - Client programs, libraries, and related files always go in standard
-     directories under $(prefix).  This rule covers things that would go
-     into $(bindir), $(includedir), $(libdir), $(mandir), and $(sbindir).
-   - Other files get located in the following places:
-
-    Directory     Transarc Mode              Default Mode
-    ============  =========================  ==============================
-    viceetcdir    /usr/vice/etc              $(sysconfdir)/openafs
-    afssrvdir     /usr/afs/bin (servers)     $(libexecdir)/openafs
-    afsconfdir    /usr/afs/etc               $(sysconfdir)/openafs/server
-    afslocaldir   /usr/afs/local             $(localstatedir)/openafs
-    afsdbdir      /usr/afs/db                $(localstatedir)/openafs/db
-    afslogdir     /usr/afs/logs              $(localstatedir)/openafs/logs
-    afsbosconfig  $(afslocaldir)/BosConfig   $(afsconfdir)/BosConfig
-    afsbosserver  $(afsbindir)/bosserver     $(sbindir)/bosserver
-
-   In default mode, you can change all of the variables named above that
-   do not start with "afs" by passing the flags with the same name to
-   configure.  For example, if you want to install the server binaries in
-   /usr/local/lib/openafs instead of /usr/local/libexec/openafs, pass the
-   --libexecdir=/usr/local/lib flag to configure.
-
-   For additional options, see section I below.
-
-B  Building
-
-   1. Now, you can build OpenAFS.
-
-      % make
-
-   2. Install your build using either "make install" to install
-      into the current system (you will need to be root, and files
-      will be placed as appropriate for Transarc or standard paths),
-      "make install DESTDIR=/some/path" to install into an alternate
-      directory tree, or if you configured with --enable-transarc-paths
-      make dest to create a complete binary tree in the dest directory
-      under the directory named for the sys_name you built for,
-      e.g. sun4x_57/dest or i386_linux26/dest
-
-   3. As appropriate you can clean up or, if you're using Linux, build for
-      another kernel version.
-
-      To clean up:
-
-      % make clean
-
-C  Problems
-
-   If you have a problem building this source, you may want to visit
-   http://www.openafs.org/ to see if any problems have been reported
-   or to find out how to get more help.
-
-   Mailing lists have been set up to help; More details can be found
-   on the openafs.org site.
-
-D  Linux Notes
-
-   With current Linux versions, the /lib/modules/`uname -r`/source symlink
-   will be used to locate the kernel headers, but you will need to have
-   the headers and build system for your kernel installed in order to
-   build the kernel module.  These are usually found in a separate package
-   from the kernel, often called something like linux-headers-<version>.
-
-   For older Linux systems, you may also need to provide the path in which
-   your kernel headers for your configured kernel can be found. This
-   should be the path of the directory containing a child directory named
-   "include". So if your version file were
-   /usr/src/linux/include/linux/version.h you would run:
-
-   % ./configure --with-afs-sysname=i386_linux26 \
-       --with-linux-kernel-headers=/usr/src/linux
-
-   Currently you can build for only one Linux kernel at a time, and the
-   version is extracted from the kernel headers in the root you specify.
-
-   To build for another Linux kernel version, determine the sysname for
-   the system type as defined in step A1 for the other kernel version and
-   then run:
-
-      % ./configure --with-afs-sysname=<sysname> \
-          --with-linux-kernel-headers=/usr/src/linux-3.19-i686
-      % make
-
-   Your build tree will now include an additional kernel module for your
-   additional kernel headers. Be aware that if the kernel version string
-   which UTS_RELEASE is defined to in include/linux/version.h matches the
-   last kernel you built for, the previous kernel module will be
-   overwritten.
-
-   The Linux 2.4 series (and older) are no longer supported. The OpenAFS 1.6
-   series of releases are the last ones supporting those old kernels and in
-   particular their LinuxThreads.
-
-E  HP-UX 11.0 Notes
-
-   HP-UX 11.0 requires a header called vfs_vm.h which HP has provided on
-   their web site.  Go to http://www.hp.com/dspp, choose Software
-   downloads from the side menu, and select Software: HP operating systems
-   and then Operating systems: HP-UX from the select boxes.  The last
-   select box will have an option for downloading vfs_vm.h.
-
-F  OpenBSD Notes
-
-   If you need to run regen.sh to make the configure script, you should
-   first install autoconf-2.59, then setenv AUTOCONF_VERSION 2.59.
-
-   You need kernel source installed to build OpenAFS.  Use the
-   --with-bsd-kernel-headers= configure option if your kernel source is
-   not in /usr/src/sys.
-
-   src/packaging/OpenBSD/buildpkg.sh will make a tar file for installing
-   the client.  There is no server package, but I am told that "make
-   install" will put server binaries in /usr/afs.
-
-   Your kernel may panic when you try to shutdown after running the
-   OpenAFS client.  To prevent this, change the "dangling vnode" panic in
-   sys/kern/vfs_syscalls.c to a printf and build a new kernel.
-
-   You can't run arla and OpenAFS at the same time.
-
-G  FreeBSD Notes
-
-   The FreeBSD client supports FreeBSD 8.x and later, but does not receive
-   regular testing on versions older than FreeBSD 9.x at this time.  Only
-   the amd64 and i386 architectures are supported, but it should not be
-   hard to port to other processors if they are already supported under
-   another operating system.
-
-   You need kernel source installed to build OpenAFS.  Use the
-   --with-bsd-kernel-headers= configure option if your kernel source is
-   not in /usr/src/sys.
-
-   You also need access to your kernel build directory for the opt_global.h
-   include file.  Use the --with-bsd-kernel-build= configure option if your
-   kernel build is not GENERIC in the standard place. If
-   /usr/src/sys/${CPUARCH}/compile/GENERIC does not point to
-   /usr/obj/usr/src/sys/GENERIC you may need to resolve that and retry the
-   build.
-
-H  AIX notes
-
-   Make sure that your default build environment is 32bit, ie.
-   the OBJECT_MODE environment variable is either unset or set to "32".
-
-   Verify this before doing configure and make. For example, assuming
-   ksh/bash:
-
-   % export OBJECT_MODE=32
-
-   To build aklog (in order to be able to get tokens from your Kerberos v5
-   ticket), you will need Kerberos libraries.  On AIX 6.1, the IBM
-   Kerberos v5 libraries are in the packages krb5.client.rte and
-   krb5.toolkit.adt on the Expansion Pack.
-
-I  Other configure options
-
-   AFS has a ton of other optional features that must be enabled using
-   configure options.  Here is a summary:
-
-   --enable-bigendian
-   --enable-littleendian
-       These configure options are normally not required and should not be
-       given.  They're only needed if the OpenAFS build system cannot
-       determine the endianness of your system, in which case configure
-       will abort and say to use one of these options.
-
-   --enable-bitmap-later
-       Speeds the startup of the fileserver by deferring reading volume
-       bitmaps until necessary.  Demand attach is a better solution to the
-       same problem.
-
-   --enable-checking
-       Enable compiler warnings when building with GCC and turn compiler
-       warnings into errors so that new warnings will cause compilation
-       failures.  If you are developing patches to contribute to OpenAFS,
-       please build OpenAFS with this flag enabled.  Warning-free code is
-       a requirement for all new submissions to OpenAFS.
-
-   --enable-debug
-   --enable-debug-kernel
-   --enable-debug-lwp
-   --enable-debug-pam
-       Compile the userspace code (for --enable-debug) or the code named
-       by the option with debugging information.  If --enable-debug is
-       given, also do not strip binaries when installing them.
-
-   --enable-linux-d_splice_alias-extra-iput
-       Work around a kernel memory leak present in a few Linux kernels.
-       The only affected mainline kernels are 3.17 to 3.17.2, but this
-       switch will also be required should a distribution backport commit
-       908790fa3b779d37365e6b28e3aa0f6e833020c3 or commit
-       95ad5c291313b66a98a44dc92b57e0b37c1dd589 but not the fix in commit
-       51486b900ee92856b977eacfc5bfbe6565028070 from the linux-stable repo
-       (git.kernel.org/cgit/linux/kernel/git/stable/linux-stable.git) or
-       the corresponding changes on other branches. This is impossible to
-       detect automatically. Without this switch, the openafs module will
-       build and work even with affected kernels. But it will leak kernel
-       memory, leading to performance degradation and eventually system
-       failure due to memory exhaustion.
-
-   --enable-linux-syscall-probing
-       OpenAFS now uses keyrings to manage PAGs by default on Linux, which
-       does not require hooking into the system call table.  On older
-       versions of Linux without keyring support, OpenAFS uses groups to
-       manage PAGs and probes for the system call table to hook into it to
-       preserve that group information.  Normally, which method to use is
-       detected automatically, and if keyring support is present, support
-       for system call table probing is not compiled in.  Use this
-       configure option to force inclusion of the system call table
-       probing code even if the kernel appears to support keyrings.
-
-   --enable-namei-fileserver
-       Forces the namei fileserver on platforms (like Solaris 8 and 9)
-       where the inode fileserver is the default.
-
-   --enable-pthreaded-ubik
-       Enable the threaded version of Ubik and install the threaded
-       versions of Ubik servers.  See README.PTHREADED_UBIK for more
-       information.  (EXPERIMENTAL)
-
-   --enable-redhat-buildsys
-       Enable compilation of the kernel module for the Red Hat build
-       system kernel.  Use this configure flag when building kernel
-       modules for Red Hat Linux systems.
-
-   --enable-reduced-depends
-       Try to minimize the shared library dependencies encoded in the
-       binaries.  This omits from the link line all the libraries included
-       solely because the Kerberos libraries depend on them and instead
-       links the programs only against libraries whose APIs are called
-       directly.  This will only work with shared Kerberos libraries and
-       will only work on platforms where shared libraries properly encode
-       their own dependencies (such as Linux).  It is intended primarily
-       for building packages for Linux distributions to avoid encoding
-       unnecessary shared library dependencies that make shared library
-       migrations more difficult.  If none of the above made any sense to
-       you, don't bother with this flag.
-
-   --enable-supergroups
-       Enables support of nested groups in the ptserver.  WARNING: Once
-       you make use of this option by nesting one group inside another,
-       the resulting PTS database cannot be correctly and safely used by a
-       ptserver built without this option.  If some of your ptservers were
-       built with this option and some without this option, you will
-       probably corrupt your PTS database.
-
-   --enable-tivoli-tsm
-       Build with the Tivoli TSM API libraries for butc support of the
-       Tivoli backup system.
-
-   --enable-transarc-paths
-       As discussed in A2 above, build for the traditional paths used by
-       the Transarc and IBM AFS distributions instead of the more typical
-       open source /usr/local paths.  Passing this option to configure and
-       then running make dest will generate, in the dest directory, the
-       set of files and directory layout matching a Transarc or IBM AFS
-       tape distribution.
-
-   --enable-warnings
-       Enable compilation warnings when built with GCC.  This is similar
-       to --enable-checking, but new warnings will only be displayed, not
-       cause a build failure.
-
-   It's also possible to disable some standard features.  None of these
-   options are normally needed, but they may be useful in unusual
-   circumstances:
-
-   --disable-kernel-module
-       Even if kernel headers are found, do not attempt to build the
-       kernel module.  On Linux, if you provide this flag, you'll also
-       need to provide --with-afs-sysname, since OpenAFS cannot determine
-       the correct sysname automatically without the kernel headers.
-
-   --disable-optimize
-   --disable-optimize-kernel
-   --disable-optimize-lwp
-   --disable-optimize-pam
-       Disable optimization for the given portion of the OpenAFS code.
-       Usually used either for debugging to avoid code optimization making
-       it harder to use a debugger, or to work around bugs in the compiler
-       optimizers or in the OpenAFS code.
-
-   --disable-pam
-       Do not build the AFS PAM modules.  Normally building them is
-       harmless, but the PAM modules that come with OpenAFS are deprecated
-       and should not be used unless you're still using the OpenAFS
-       kaserver (which is itself deprecated and should not be used).
-
-   --disable-strip-binaries
-       Disable stripping of binaries on installation.  You probably want
-       to use --enable-debug instead of this flag to also inclusion of
-       debugging information.
-
-   --disable-unix-sockets
-       Disable use of UNIX domain sockets for fssync.  A TCP connection to
-       localhost will be used instead.
-
-   You may need to pass one or more of the following options to specify
-   paths and locations of files needed by the OpenAFS build process or
-   additional information required by the build process:
-
-   --with-afs-sysname=SYSNAME
-       Specifies the AFS sysname of the target system is SYSNAME.
-       Normally this is determined automatically from the build
-       architecture plus additional information (such as, on Linux, from
-       the kernel headers).  The SYSNAME should be one of the options
-       listed in A2.
-
-   --with-gssapi=DIR
-   --with-gssapi-include=DIR
-   --with-gssapi-lib=DIR
-   --with-krb5[=DIR]
-   --with-krb5-include=DIR
-   --with-krb5-lib=DIR
-       Normally, OpenAFS will automatically build with Kerberos support if
-       Kerberos is found during the build.  If your Kerberos libraries are
-       in an unusual location, however, you may need to pass one or more
-       of these flags.  --with-krb5 forces building with Kerberos support
-       if given and will cause configure to fail if Kerberos is not found.
-       You may optionally specify the root path to your Kerberos
-       installation as an argument to --with-krb5.
-
-       If you have a krb5-config script, it's used to find the flags to
-       build with Kerberos.  If you have no krb5-config script, you can
-       specify the location to the include files with --with-krb5-include
-       and the libraries with --with-krb5-lib.  You may need to do this if
-       Autoconf can't figure out whether to use lib, lib32, or lib64 on
-       your platform.
-
-       --with-gssapi is similar, except for the GSS-API libraries instead
-       of the Kerberos libraries.  If you have to manually set the
-       location of the Kerberos libraries, you may need to do the same
-       thing for the GSS-API libraries.
-
-   --with-libintl=DIR
-   --with-libintl-include=DIR
-   --with-libintl-lib=DIR
-       Specifies the install location of the libintl library, used for
-       internationalization, or separately specifies the location of the
-       header files and libraries.  By default, the default system library
-       paths will be searched.  This library is not required on many
-       platforms.
-
-   --with-roken=PATH
-   --with-roken=internal
-       Specifies the install location of the libroken library.  Specify
-       "internal" to use the embedded libroken library that comes with
-       OpenAFS (the default).  This option is primarily useful for
-       building against a system libroken library if you have one.
-
-   --with-linux-kernel-build=PATH
-   --with-linux-kernel-headers=PATH
-   --with-bsd-kernel-build=PATH
-   --with-bsd-kernel-headers=PATH
-       Specifies the path to the kernel headers and build system.  See the
-       information above for Linux and *BSD systems.
-
-   --with-linux-kernel-packaging
-       Tells the OpenAFS kernel module build system to use conventions
-       appropriate for building modules to include in Linux kernel module
-       packages.  Primarily, this renames the kernel module to openafs.ko
-       rather than libafs-<VERSION>.ko, which is easier to handle in Linux
-       distribution init scripts.
-
-   --with-docbook2pdf=PROGRAM
-       Specifies the program used to convert the DocBook manuals to PDF.
-       Supported choices are fop, dblatex, and docbook2pdf.  By default,
-       the user's path is searched for those programs in that order, and
-       the first one found is used.
-
-   --with-docbook-stylesheets=PATH
-       The location of the DocBook style sheets, used to convert the
-       DocBook manuals to other formats.  By default, a set of likely
-       paths are searched.
-
-   --with-html-xsl=PATH
-       Specifies the XSLT style sheet to convert DocBook manuals into
-       HTML.  The default is html/chunk.xsl.  You may wish to use
-       html/docbook.xsml instead.
-
-   --with-xslt-processor=PROGRAM
-       Specifies the XSLT processor to use to convert the DocBook manuals
-       into HTML.  Supported choices are libxslt, saxon, xalan-j, and
-       xsltproc.  By default, the user's path is searched for those
-       programs in that order, and the first one found is used.
-
-   There are also some environment variables that you can set to control
-   aspects of the build.  They can be set either on the configure command
-   line (preferred) or in the environment.
-
-   CC
-       The C compiler to use.  Be aware that this is overridden on some
-       architectures that require a specific compiler be used to build the
-       kernel module.
-
-   CFLAGS
-       Additional flags to pass to the C compiler.
-
-   CPP
-       The C preprocessor to use.  Defaults to cpp if found, otherwise
-       $CC -E.
-
-   CPPFLAGS
-       Additional flags to pass to the C preprocessor or compiler.  This
-       is where to put -I options to add paths to the include file search.
-
-   FUSE_CFLAGS
-       Compiler flags required for building applications that use FUSE.
-
-   FUSE_LIBS
-       Libraries required for linking applications that use FUSE.
-
-   KRB5_CONFIG
-       To specify a particular krb5-config script to use, either set the
-       KRB5_CONFIG environment variable or pass it to configure like:
-
-           ./configure KRB5_CONFIG=/path/to/krb5-config
-
-       To not use krb5-config and force library probing even if there is a
-       krb5-config script on your path, set KRB5_CONFIG to a nonexistent
-       path:
-
-           ./configure KRB5_CONFIG=/nonexistent
-
-   LDFLAGS
-       Additional flags to pass to the linker.  This is where to put -L
-       options to add paths to the library search.
-
-   LIBS
-       Additional libraries to link all userspace programs with.
-
-   PKG_CONFIG
-       The path to the pkg-config utility.  Currently, this is only used
-       to locate the flags for building the FUSE version of afsd.
-
-   YACC
-       The yacc implementation to use.  Defaults to bison, byacc, or yacc,
-       whichever is found first.
-
-   YFLAGS
-       Additional flags to pass to yacc.