AFSLore/HowToBuildOpenAFSFromSource.mdwn

   1 These are notes on how to build [[OpenAFS]] from source code. Note that [[OpenAFS]] pre-built binaries are available on the [[OpenAFS]] site and are available as prebuilt packages for many platforms. These instructions may be useful for you if you need to build [[OpenAFS]] from source.
   2
   3 ### <a name="Requirements"></a> Requirements
   4
   5 #### <a name="Tools"></a> Tools
   6
   7 - cvs client
   8 - autoconf
   9 - automake
  10 - perl 5.6
  11 - gcc
  12 - GNU make
  13 - lex/yacc (flex/bison)
  14
  15 #### <a name="Libraries"></a> Libraries
  16
  17 - libc
  18 - kerberos, optional, but recommended
  19 - ncurses
  20 - kernel headers
  21
  22 The Kerberos development libraries are required if you are going to build with Kerberos 5 support. The [[OpenAFS]] legacy kaserver is deprecated.
  23
  24 If you are building on Debian, you can get the required software with the following apt-get commands.
  25
  26       apt-get install cvs autoconf automake make gcc flex bison
  27       apt-get install libc6-dev libkrb5-dev libncurses5-dev linux-headers-$(uname -r)
  28
  29 ### <a name="Getting the Source Code from CVS"></a> Getting the Source Code from CVS
  30
  31 You can get development snapshots from the [[OpenAFS]] CVS repository . The CVS tree may not always have code which can currently be built. While every effort is made to keep the head of the tree buildable, you may at any time find yourself between commits and hence have a tree which does not build, or worse, causes more serious problems.
  32
  33 First you need to run cvs login. This step is normally only done once. A ~/.cvspass file will be created for additional checkouts.
  34
  35        cvs -d :pserver:anonymous@cvs.openafs.org:/cvs  login
  36        password is anonymous
  37
  38 Before doing a CVS check out, you'll need to decide which branch you want to check out. The trunk is for bleeding edge development and may not even build. The current stable series is openafs-stable-1\_4\_x and the current development work is going on the openafs-devel-1\_5\_x branch.
  39
  40 See the CVSWeb interface at <http://www.openafs.org/frameset/cgi-bin/cvsweb.cgi/openafs/> for the full list of available branches and tags.
  41
  42 To check out the stable branch:
  43
  44        cvs -d :pserver:anonymous@cvs.openafs.org:/cvs checkout -r openafs-stable-1_4_x -d openafs-stable-1_4_x openafs
  45
  46 This will create a source tree in a directory named openafs-stable-1\_4\_x.
  47
  48 To check out the development branch:
  49
  50        cvs -d :pserver:anonymous@cvs.openafs.org:/cvs checkout -r openafs-devel-1_5_x -d openafs-devel-1_5_x openafs
  51
  52 This will create a source tree in a directory named openafs-devel-1\_5\_x.
  53
  54 Next, step into your sandbox and run the regen.sh script to create the configure script.
  55
  56        cd openafs-stable-1_4_x.
  57        ./regen.sh
  58
  59 ### <a name="Building the Binaries"></a> Building the Binaries
  60
  61 #### <a name="Modern Paths"></a> Modern Paths
  62
  63 To build [[OpenAFS]] with Kerberos 5 support, and with a custom install path,
  64
  65        ./configure --prefix=/usr/local/openafs --with-krb5-conf=(full path to krb5-config script)
  66        make
  67        sudo make install
  68
  69 #### <a name="Transarc Paths"></a> Transarc Paths
  70
  71 By convention, [[OpenAFS]] server binaries and related files are located in /usr/afs, and client binaries and related files are located in /usr/vice. These are known as Transarc paths, so called because that is is the convention used by Transarc, the company that first commercialized AFS. To build with the Transarc paths, specify --enable-transarc-paths as a configure option.
  72
  73 There are a couple of side effects that you need need to be aware of when building with the --enable-transarc-paths mode. First of all, the typical make install target does not work in this mode. Instead the 'make dest' target is used to build a directory of the binaries to be copied to the target system. Secondly, the packaging targets are not executed, so for example the redhat spec file is not generated to build the rpms.
  74
  75 To build with Keberos support (recommended), you'll need to have the Keberos development libraries, and if available for your platform, the krb5-config. You will need the full path the the krb5-config script. For example
  76
  77        $ which krb5-config
  78        /usr/bin/krb5-config
  79
  80 To build [[OpenAFS]] with Kerberos 5 support and the Transarc path conventions:
  81
  82        ./configure  --enable-transarc-paths --with-krb5-conf=/usr/bin/krb5-config
  83        make
  84        make dest
  85
  86 If all goes well, then the binaries are located in a platform sub-directory, the name of which is platform specific, for example 'i386\_linux26/dest'.
  87
  88 The 'make install' command does not work with Transarc paths. You will have to manually copy the binaries into place after running make dest. For more information, see the Quick Start Guide for Unix on the [[OpenAFS]] documentation page.
  89
  90       # cp -r i386_linux26/dest/root.client/usr/vice/etc/modload /usr/vice/etc
  91       # cp i386_linux26/dest/root.client/usr/vice/etc/afsd /usr/vice/etc
  92       # cp -r i386_linux26/dest/bin /usr/afsws
  93       # cp -r i386_linux26/dest/etc /usr/afsws
  94       # cp -r i386_linux26/dest/include /usr/afsws
  95       # cp -r i386_linux26/dest/lib /usr/afsws
  96       # cp -r i386_linux26/dest/root.server/usr/afs/* /usr/afs
  97
  98 ### <a name="Running the Test Suite"></a> Running the Test Suite
  99
 100 [[OpenAFS]] includes a suite of basic test scripts in the src/tests directory. The tests directory also contains a utility called afs-newcell.pl to create a test cell on a single host. You will need to already have a kerberos server running with an AFS principal and an admin principal. You should also have a partitions mounted as /vicepa and /vicepb for the test volumes. See the src/tests/afs-newcell.pl for details.
 101
 102 The paths to the binaries and AFS configuration is are written to src/tests/OpenAFS/Dirpaths.pm when the tests are built. This means you must run 'make all' in src/tests before attempting to use afs-newcell.pl. The afs-newcell.pl program must be run as root.
 103
 104       cd src/tests
 105       make all
 106       sudo perl afs-newcell.pl
 107
 108 The afs-newcell.pl program will prompt for the required cell configuration unless started with the --batch options. You will need to specify the name of your new cell, the host name of this machine, the target partition id (a for /vicepa), and the username of the AFS administrator (which must be named 'admin' for the current pts tests).
 109
 110 You will also need to provide the type of Kerberos server, the name of the Kerberos realm (which can be different than the AFS cell name), and the location of the keytab file that contains the AFS server encryption key and the admin's encryption key. Finally, you may provide any server options for the AFS database and fileservers.
 111
 112     Server options:
 113     What server name should be used? [host.domain.com]
 114     What cellname should be used? [testcell]
 115     What vice partition? [a]
 116     What administrator username? [admin]
 117
 118     Kerberos options:
 119     Which Kerberos is to be used? [MIT]
 120     What Kerberos realm? [TESTCELL]
 121     What keytab file? [/usr/afs/etc/krb5.keytab]
 122
 123     Database Server options:
 124     ptserver options: []
 125     vlserver options: []
 126
 127     Fileserver options:
 128     Use DAFS fileserver (requires DAFS build option)? (yes/no) [no]
 129     fileserver options: []
 130     volserver options: []
 131     salvageserver options: []
 132     salvager options: []
 133
 134 The parameters are optionally saved to a script called run-afs-newcell.sh, in case you need to re-run the setup. Also, the Kerberos parameters for the new cell are saved in the file run-tests.conf. If all goes well, the servers should be running and the client loaded. You should be able to see your new cell at /afs/testcell (or whatever you called your cell). Your cell will have a few, empty test volumes that you should be able to see with a vos listvldb.
 135
 136 Run the run-tests script to run the AFS test suite. The program can be run as an ordinary user. The keytab file specified when afs-newcell was run will be used to authenticate the admin user for the tests.
 137
 138       ./run-tests -all
 139
 140 The output will look something like this,
 141
 142     Authenticating to cell testcell.
 143     ...
 144     Running creat1
 145     Running mkdir1
 146     Running mkdir2
 147     ....
 148     -----------------------------------------------------------
 149     Failed test(s) were:  write-large write-ro ...
 150
 151 -- [[MichaelMeffie]] - 26 Mar 2008