Id: INSTALL,v 1.93 2002/09/07 10:41:43 lha Exp $arla: $) * 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. 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: --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 krbafs lib. For non kth-krb users, see README for more information about libkrbafs) --with-krb5=dir use kerberos 4 compat from kerberos 5 in dir --with-sl=dir use the sl in dir --with-sl-lib=dir use the sl library in dir --with-sl-include=dir use the sl includes in dir --disable-mmap don't use mmap at all --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) --disable-nnpfs do not build NNPFS --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-readline=dir link against readline in dir --with-readline-lib=dir (readline's library is in dir) --with-readline-include=dir (readline's headers are in dir) --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. If you use a roken, you want to use it from KTH-KRB1.2 or Heimdal 0.4e (or later) --with-bsd-make=prog When using a bsd and cross compiling we need to know your make, default /usr/bin/make --without-lwp-redzone LWP creates a redzone page on top of all thread stacks with mmap(), if this causes you problem you can turn it of with 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). 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 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 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. Another problem is that all symbol-rewrite #defines doesn't exists. {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. Solaris 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. * 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: 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. SunOS4: modload /usr/arla/bin/libnnpfs.o modstat mknod /dev/nnpfs0 c <C-major from modstat> 0 mkdir /afs /usr/arla/bin/mount_nnpfs /afs /dev/nnpfs0 /usr/arla/libexec/arlad {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 use a new kth-krb (with afssys.c 1.59 or newer) and set AFS_SYSCALL=nnpfs before starting arlad. 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 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 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 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.