try to support modern FreeBSD. After Robert Watson <rwatson@FreeBSD.org> and Alec...

[arla.git] / INSTALL

Id: INSTALL,v 1.93 2002/09/07 10:41:43 lha Exp $ ($Name$)

* Building arla

Arla is configured with autoconf.  Start the configuration process by
typing:

- `./configure' in the source directory, or
- `SRCDIR/configure' in the directory where you want to build arla.
  (we recommend you to build somewhere else like in /var/tmp/arlaobj
   because that way it is easier to start over. That requires a
   make command that understands VPATH, for example gnu make)

If you want to install somewhere different from the default
`/usr/arla' give `--prefix=PATH' as an argument to configure.  Note
that if you change your prefix from the default your kerberos
libraries may have problems that your kerberos/afs libraries are
unable to find what cell you belong to.

Note that the kernel module is fairly specific to a particular version
of the OS kernel, so you should make sure that you have built Arla for
the same version that are you are running on.

There are also some arla-specific arguments to configure (see 
configure --help for full list):

Optional Features:
  --enable-smp            compile for SMP (for Linux and FreeBSD)
  --enable-kld            build kld modules (only FreeBSD 3.0)
  --disable-nnpfs          build arla w/o nnpfs
  --enable-knfs           make afs nfs-mountable
  --disable-mmap          don't use mmap
  --disable-dynamic-afs   don't use loaded AFS library with AIX

Optional Packages:
  --with-x                use the X Window System
  --with-pthreads=dir       compile liblwp as pthreads wrapper using pthreads in dir
  --with-sys=dir          use dir as your kernel source code directory
                          default $default_sys
  --without-lwp-redzone   don't use redzone for (asm)lwp
  --with-arlacachedir=dir use dir as cachedir instead of \$prefix/cache
  --with-arlaconffile=file use file for configuration instead of \$prefix/etc/arla.conf
  --with-milkopart=dir    location of milko partitions (default /)
  --with-readline=dir     use readline in dir
  --with-readline-lib=dir use readline libraries in dir
  --with-readline-include=dir
                          use readline headers in dir
  --with-readline-config=path
                          config program for readline
  --with-sl=dir           make with sl in dir
  --with-sl-include=dir   make with sl headers in dir
  --with-sl-lib=dir       make with sl lib in dir
  --with-roken=dir        make with roken in dir
  --with-roken-include=dir make with roken headers in dir
  --with-roken-lib=dir    make with roken lib in dir
  --without-ipv6          do not enable IPv6 support
  --with-krb5=dir         use kerberos 5 in dir
  --with-krb5-include=dir use kerberos 5 headers in dir
  --with-krb5-lib=dir     use kerberos 5 libraries in dir
  --with-krbafs=dir       use libkrbafs (from mit, extracted from kth-krb) in dir

By default configure will use gcc if it finds it.  If you want to use
a specific compiler or some special options you can specify that when
running configure.

If you change CFLAGS you might also have to set KERNEL_CFLAGS. The
reason for having different variables is that lots of times totally
different compilation environment are required (64-bit and 32-bit on
linux/sparcv9 and MacOS for example).

Type:

  env CC=my-compiler CFLAGS='magic-flags' ./configure

If there's no kernel support for your operating system, configure will
print a warning to that effect and only the user-level stuff will be
configured.

Solaris 2.7, 2.8 (or Solaris 7, 8):

On Solaris 2.7, 2.8 the kernel itself can be either 32 bit or 64 bit.
The nnpfs kernel module needs to be of the same type as the kernel.  You
can find out what type of kernel you have from `dmesg'.  It should say
something like:

If it says:

   SunOS Release 5.7 Version Generic [UNIX(R) System V Release 4.0]

that means it's a 32 bit kernel, but if it says:

   SunOS Release 5.7 Version Generic 64-bit [UNIX(R) System V Release 4.0]

then it's 64 bit.

To build a 32 bit arla you don't need to do anything special.  If you
however want a 64 bit one the magic incarnation of configure is:

env CC='cc -xarch=v9' AS='as -xarch=v9' configure sparc64-sun-solaris2.7

Once configure has completed, just run `make'.

Solaris does not have an memcpy function in the kernel and gcc can
sometimes generate calls to this function.  If you get unresolved
symbol errors on memcpy, either compile with Sun's compiler or define
memcpy in terms of bcopy.

Mac OS X/Darwin:

The platforms we have tested are Mac OS X 10.2. You must install the
Developer Tools CD before you can compile Arla.

There is documentation to configure the native kerberos in Mac OS X provided by MIT here: <http://web.mit.edu/macdev/Development/MITKerberos/Common/Documentation/preferences.html>

If you choose to use the native Kerberos stuff you'll need krbafs, see
the README where to find it.

Linux:

RedHat ships in the 7.0 release a gcc that can't compile the linux
kernel. To remedy this problem they also ship a kgcc that should be
used to compile the linux kernel and kernel modules. When running
configure on such a computer, please set KERNEL_CC to kgcc. Example:

  env KERNEL_CC=kgcc ./configure --argument-to-configure-if-any

If you are running a kernel that isn't the kernel symlinked/unpacked
to/in /usr/src/linux you will need to use --with-sys=dir
option (see <http://www.pathname.com/fhs/2.0/fhs-6.1.6.html>).
Without it will not work, either you will get error when doing
insmod or strange error when accessing files in /afs.

You need to have run make config (or make xconfig or make menuconfig)
and make dep before you run arla's configure. This since
header files (like linux/version.h) need to have right datestamp to 
please make.

Issues with the Linux 2.6.x kernel versions

To build nnpfs, the arla build process needs to make some symlinks in
the kernel source directories. Because of this, you must have a fully
configured kernel source tree and it must be writable in some places.
This is due to changes how the 2.6 kernel series are built. 

Issues with some Linux glibc versions

Some Linux distributions ship with a glibc that uses pthreads in a way
which makes arlad break (as in segmentation fault at strange places)
because of conflicts with arlas lwp. If you encounter this try some
of these alternatives: Compile arlad with another glibc version (for
exemple on another distribution) or try the --with-ptherads configure
option.

{Net,Free,Open}BSD:

You will need the kernel source installed in /usr/src/sys.

NetBSD

NetBSD 1.5 include kth-krb and heimdal and due to that arla and
kth-krb uses a common library (libroken) there might be some
collisions you should run configure like this:

configure \
        --with-roken=yes \
        --with-roken-include=/usr/include/krb5 \
        --with-roken-lib=/usr/lib

Tru64 Unix (aka Digital Unix (aka OSF/1)):

We recommend building with Digital's cc, since that's what the rest of
the kernel is built with.  We suggest using env CC='cc -std1' configure.

* Installing arla

Run `make install'.  It will create and populate these directories:

/usr/arla/bin           all user binaries
/usr/arla/sbin          arla-cli and the startarla script
/usr/arla/libexec       the arlad
/usr/arla/cache         the cached files will be stored here
                        (core-dumps from arlad as well)
/usr/arla/etc           configuration files:
                        ThisCell, CellServDB, arla.conf
/usr/arla/lib           random libraries

If you're already part of an AFS cell, modify /usr/arla/etc/ThisCell
and make sure your cell is mentioned in /usr/arla/etc/CellServDB.  If
you don't have a cell you'll still be able to run as a client in the
cell `stacken.kth.se' and access all cells listed in CellServDB.

* Services

Everything works fine even if your /etc/services is not updated, but
you might not get netstat, tcpdump, and other programs might not print
the symbolic names.  To make all of this work, add the
contents of SRCDIR/conf/services to /etc/services.

  cat SRCDIR/conf/services >> /etc/services

* Starting arla

To start Arla just run `/usr/arla/sbin/startarla'.  (On Linux there is
also a rc.d-based script, see below).

Here are some detailed quirks for some operating systems and
instructions as to what to try when startarla does not give you
full and complete satisfaction.

Linux:

  Linux gives you a wide choice of filesystems to place the cache
  partition on. We have verified that ext2 and ext3 work to be
  used as /usr/arla/cache. We have experienced problems with
  reiserfs. These might or might not be fixed today. You have
  been warned. As the arla cache is rebuild on boot anyway, ext2
  is a good choice as cache partition for speed.

  Use the script /usr/arla/sbin/startarla to start Arla.  There's also
  a SysV-based init script called arla.init you can install into
  /etc/rc.d (or where your init files are located).

  If you are using Linux 2.2 and libc4, libc5 or glibc 2.0,
  (or programs that use these version of libc, such as Matlab)
  you may want to enable the getcwd syscall, which works much better
  than the old way of doing getcwd. In order to do this, follow
  these steps:

  1. Copy /usr/arla/lib/libgetcwd.so.X (where X is the arla version)
     to /lib.
  2. Run "/sbin/ldconfig".
  3. Run "LD_PRELOAD=/lib/libgetcwd.so.0 /bin/pwd". If this fails
     with "/bin/pwd: can't load library '/lib/libgetcwd.so.0'" or
     some other error message, report this error.
  4. If the previous step went well, add this line to /etc/ld.so.preload:
     /lib/libgetcwd.so.0

  DO NOT load the file from /usr/arla/lib, since /usr probably is not
  part of the root partition of your system. If you do this, your system
  will probably not be able to boot, even in single user, since in most
  Linux installations, init, sh, mount and other programs are dynamically
  linked.

  If you use glibc 2.1 or later, the above method is unnecessary and
  the line /lib/libgetcwd.so.0 should be removed from /etc/ld.so.preload
  if present.

{Net|Open}BSD:

  You can not load kernel modules (the modload step) when your
  securelevel is above zero. There are two ways to make sure that you
  can load kernel modules:

  * You can compile a new kernel with "option INSECURE". This will make
    the securelevel be zero in multiuser. Then you can load the modules
    with the above commands. Some people might consider this a security
    risk.

  * You can load the modules in /etc/lkm.conf (for NetBSD) or
    /etc/rc.securelevel (for OpenBSD).

FreeBSD:
  
  Do like in {Net|Open} except that after the first time (when /dev/nnpfs0
  exists) you can skip the modload since the module with automatically
  be loaded by mount_nnpfs assuming you have copied nnpfs_mod.o to /modules with
  something like the following commands:

    mkdir /modules
    cp /usr/arla/bin/nnpfs.ko /modules

  And mount_nnpfs will load the filesystem into the kernel.

  As with other BSDs, /usr/arla/bin/startarla should do everything for you.

Solaris:

  Just use /usr/arla/sbin/startarla.  If that does not work, see the
  more detailed explanation here.

  Add a line to /etc/name_to_major with (138 should be any unused number)

    nnpfs 138

  and another one to /etc/name_to_sysnum (105 is the preferred system
  call number by Solaris < 7 and 73 for Solaris 7).  If that's already
  used by Transarc AFS on your machine pick some other number.  You can
  only pick system calls that are marked as loadable, namely these
  system calls on Solaris 7:
  40, 42, 45, 49, 51 - 53, 64-78, 82, 83, 101, 102, 110, 111, 127, 140,
  150, 151, 176 - 184, 226 - 229

    nnpfs 105

  (or)

    nnpfs 73

  You might have to reboot for these changes to take effect.  Then, type:

    modload nnpfs

  You should probably add a file in /usr/kernel/drv/nnpfs.conf with:

    name="nnpfs" parent="pseudo" instance=0;

  and then run:

    drvconfig -i nnpfs

  Create a /dev link and a directory:

    ln -s "/devices/pseudo/nnpfs@0:" /dev/nnpfs0
    mkdir /afs

  Now you can try mounting the file system and start the daemon:

    /usr/arla/bin/mount_nnpfs /dev/nnpfs0 /afs
    /usr/arla/libexec/arlad

  Note that if you are using a syscall other than 105, you have to
  set AFS_SYSCALL=nnpfs before starting arlad and using the token
  manipulating programs of heimdal.

  If you want to, you can copy the nnpfs/solaris/nnpfs module to /kernel/fs
  and nnpfs/solaris/bin/mount_nnpfs to /lib/fs/nnpfs/mount which enables you to
  automatically load the nnpfs module when mounting the nnpfs file system.

AIX:

  Create the device node:

    mknod /dev/nnpfs0 c 100 0

  And add a line like the following to /etc/vfs:

    arla    8       none    none

  Now you can try mounting the file system and start the daemon:

    /usr/arla/bin/nnpfs_load /usr/arla/bin/nnpfs
    /usr/arla/bin/mount_nnpfs /dev/nnpfs0 /afs
    /usr/arla/libexec/arlad

Tru64 Unix (aka Digital Unix (aka OSF/1)):

  Copy the nnpfs.mod to some of /subsys, /var/subsys, /sys/BINARY,
  or /subsystems. Depending on what your kloadsrv thinks is the
  right thing<tm>.

  Load (configure) the module with sysconfig -c nnpfs

  Query the module to see if it loaded ok and get the
  character device and syscall number from it with:
  sysconfig -q nnpfs

  Create the char-device "mknod /dev/nnpfs0 c <MAJOR> 0"
  where <MAJOR> is the number obtained above.

  Create the afs directory: mkdir /afs

  Mount the device and start the daemon: 
     /usr/arla/bin/mount_nnpfs /dev/nnpfs0 /afs
     /usr/arla/libexec/arlad

  It could look something like this:

  datan:~# sysconfig -c nnpfs
  datan:~# sysconfig -q nnpfs
  syscall = 34
  major = 68
  debug = 255
  datan:~# mknod /dev/nnpfs0 c 68 0
  datan:~# mkdir /afs
  datan:~# /usr/arla/bin/mount_nnpfs /dev/nnpfs0 /afs
  datan:~# /usr/arla/libexec/arlad 
  datan:~# ls /afs | head
  .stacken.kth.se
  afs.brain.de
  afs.hursley.ibm.com
  afs1.scri.fsu.edu

* command-line mode

If Arla does not work completely, if you do not have root permission
on your machine or want to test for some other reason, there is a
user-space command-line based program called arla-cli, that you can
use to to access AFS.  When starting, it should print some messages
and then give you the prompt `arla>'.  There are very minimal commands
for navigating the AFS space (ls, cd and cat).  Type `help' to get a
list of all the commands.

Run `arla-cli --help' for a list of the options supported.

* Tests

There are a number of tests in the `tests' directory.  Use a command
similar to the following to run them:

env WORKDIR=workdir ./run-tests

where `workdir' is a temporary directory in AFS space where you have
read and write permission.  run-tests takes lots of options, try
`-help'.  You should probably start by running `-fast -all' and if you
have a lot of patience and time try `-all'.  The `-fast -all' tests
test most of the common operations and is a good general test run.
The test that aren't marked `fast' do a rather unkind stress test of
things and takes a few hours to run.

* Firewalls and NAT

If you have to use Arla though a firewall, it is useful to review how
Arla communicates.  Arla uses UDP in the following way:

arlad                   Server
7001(*)  <-->           7000,7003

Tools(**)               Server
whatever(***) <-->      7002,7003,7005

(*) arla older then 0.36 used 4711

(**) vos/pts/bos

(***) dynamically assigned port numbers, depends on your OS

If your server is on the other side of a firewall or NAT gateway and
the configuration allows connections to be opened only one way, your
client will probably miss file updates from other clients, even if
your file system looks good after startup. If you manage to configure
your NAT gateway so that the UDP timeout is longer than the
duration between arlad's keepalive packets to the server you
might be able to use AFS behind a NAT anyway.