$Id: INSTALL,v 1.81 2001/01/08 18:13:38 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.
  (this is the recommended way but requires a make that understands VPATH)

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.

There are also some arla-specific arguments to configure:

  --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-krb4=dir         use kerberos 4 in dir
  --with-krb4-lib=dir     use krb4-lib in dir
  --with-krb4-include=dir use krb4-include in dir
  --with-krbafs=dir       use cmu's krbafs lib (If you not are using kth-krb.
			  This is not needed when using kth-krb since
			  libkafs is included there.)
  --with-krb5=dir	  use kerberos 4 compat from kerberos 5 in dir
  --disable-mmap	  don't use mmap at all
  --enable-mmaptime       use mmap:ed time from /dev/kmem
                          (known to work in FreeBSD)
  --disable-dynamic-afs	  don't use loaded AFS library with AIX
  --enable-smp		  compile for SMP (currently only on Linux and FreeBSD)
  --enable-knfs		  enable code to nfsmount AFS (*BSD only).
  --enable-kld		  build KLD modules (for FreeBSD[34]-current)
  --without-x		  don't build X code
  --with-pthreads=dir	  use the pthreads library in dir
  --with-sys=dir          The base directory of your kernel source
			  (compile-tree in case of osf)

  --with-roken=dir        The with-roken options are for the users
  --with-roken-include=dir   that knowns what they do and want to use
  --with-roken-lib=dir       another roken the default. You will shot off
                             your feet using this option.

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).

Running in a sh-style shell, type:

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

If you are stuck with a broken shell, try using the env program:

  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 (or Solaris 7)

On Solaris 2.7 the kernel itself can be either 32 bit or 64 bit.  The
xfs 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:

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

Once configured has completed, just run `make'.

One common problem is the file lwp/process.S.  This has to be
preprocessed with the appropriate defines and then assembled.  If the
magic in lwp/make-process.o.sh.in for some reason fails, try doing it
by hand. Then figure out what should be added and send us a patch to
lwp/make-process.o.sh.in.

Mac OS X/Darwin

The only platform that we have used is Mac OS X DP3 with the Kernel
development kit. Without the Kernel development kit, you won't be able
to compile the kernel module. It may also work under Darwin 1.0.

* 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
programs will print warning messages.  To get rid of these, add the
contents of SRCDIR/conf/services to /etc/services.

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

* Starting arla

First try running arla-cli.  If all goes well, 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.

If you have a kernel module you can try to load it and mount the
file system.  That's done somewhat differently depending on the
operating system:

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.

  The linux major character device number in arla is 103. Create the
  device node with the command below before you use arla if it doesn't exist.

  mknod /dev/xfs0 c 103 0
  insmod /usr/arla/bin/xfs.o
  /usr/arla/libexec/arlad
  mkdir /afs
  mount -t xfs arla /afs

  These commands are executed by the script /usr/arla/sbin/startarla so
  you might want to use that instead.  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.1 or 2.2 and libc4, libc5 or glibc 2.0,
  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.

SunOS4:

  modload /usr/arla/bin/libxfs.o
  modstat
  mknod /dev/xfs0 c <C-major from modstat> 0
  mkdir /afs
  /usr/arla/bin/mount_xfs /afs /dev/xfs0
  /usr/arla/libexec/arlad

{Net|Open}BSD:

  NetBSD 1.4.2 have a problem with syscall(2) and shared libs, it will
  simply not work. The configure script tries to detect that its 1.4.2
  and build everything static. Gross, but at least working.

  modload -e xfs_mod -o /var/tmp/symbols -p /usr/arla/bin/xfs_makedev /usr/arla/bin/xfs_mod.o
  mkdir /afs
  /usr/arla/bin/mount_xfs /dev/xfs0 /afs
  /usr/arla/libexec/arlad

  (or should you be able to use /usr/arla/bin/startarla)

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).

If you're running Arla on OpenBSD, there's a conflict in the kafs library
shipped with OpenBSD. To fix this, apply the following patch to the
file /usr/src/kerberosIV/lib/kafs/Makefile and do "make ; make install"
in that directory.
--- Makefile.orig       Thu Aug 31 23:00:24 2000
+++ Makefile    Thu Aug 31 21:31:41 2000
@@ -11,7 +11,7 @@
 
 .PATH: ${KRBSRC}/lib/kafs ${KRBSRC}/man
 
-SRCS=  afssys_openbsd.c \
+SRCS=  afssys.c \
        afskrb.c \
        $(afskrb5_c) \
        common.c \

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

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

And mount_xfs will load the filesystem into the kernel.

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

Mac OS X/Darwin:

  kmodload -o /var/tmp/symbols /usr/arla/bin/xfs_mod.o
  mkdir /afs
  /usr/arla/bin/mount_xfs /dev/xfs0 /afs
  /usr/arla/libexec/arlad

or run /usr/arla/sbin/startarla

Solaris:

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

  xfs 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

  xfs 105

(or)

  xfs 73

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

  modload xfs

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

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

and then run:

  drvconfig -i xfs

Create a /dev link and a directory:

  ln -s "/devices/pseudo/xfs@0:" /dev/xfs0
  mkdir /afs

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

  /usr/arla/bin/mount_xfs /dev/xfs0 /afs
  /usr/arla/libexec/arlad

Note that if you are using a syscall other than 105, you have to use a
new kth-krb (with afssys.c 1.59 or newer) and set AFS_SYSCALL=xfs
before starting arlad.

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

AIX:

Create the device node:

  mknod /dev/xfs0 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/xfs_load /usr/arla/bin/xfs
  /usr/arla/bin/mount_xfs /dev/xfs0 /afs
  /usr/arla/libexec/arlad

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

Copy the xfs.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 xfs

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

Create the char-device "mknod /dev/xfs0 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_xfs /dev/xfs0 /afs
   /usr/arla/libexec/arlad

It could look something like this:

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

* 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

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

arlad			Server
4711	 <-->		7000,7003

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

(*) vos/pts/bos

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

If your server is on the other side of a firewall 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.
