(no commit message)
[openafs-wiki.git] / 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 - Git
8 - autoconf
9 - automake
10 - perl 5.6
11 - make
12 - compiler/linker (e.g. gcc tool chain)
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 required packages to build [[OpenAFS]] on Debian-based linux distributions can be installed with,
23
24       apt-get install git-core autoconf automake make gcc flex bison
25       apt-get install libc6-dev libkrb5-dev libncurses5-dev linux-headers-$(uname -r)
26
27 On RPM based linux distributions, the packages required are,
28
29      yum install gcc autoconf automake make flex bison rpm-build
30      yum install glibc-devel krb5-devel ncurses-devel pam-devel kernel-devel-$(uname -r)
31
32 (The last time I did this for a 1.4.x build, I also needed to manually create a symlink
33 /usr/src/linux to point to the correct path /usr/src/kernel/<version>.)
34
35 ### <a name="Getting the Source Code"></a> Getting the Source Code
36
37 Snapshots of the [[OpenAFS]] source code is made available for each stable and each development release at <http://openafs.org>.
38
39 The [[OpenAFS]] code base is now available from a Git repository. See [[GitDevelopers]] for more information.
40
41 ### <a name="Building the Binaries"></a> Building the Binaries
42
43 #### <a name="Modern Paths"></a> Modern Paths
44
45 To build [[OpenAFS]] with Kerberos 5 support, and with a custom install path. Be sure to run ./regen.sh to generate the configure script.
46
47        cd openafs-stable-1_4_x.
48        ./regen.sh
49        ./configure --prefix=/usr/local/openafs --with-krb5-conf=(full path to krb5-config script)
50        make
51        sudo make install
52
53 #### <a name="Transarc Paths"></a> Transarc Paths
54
55 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.
56
57 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.
58
59 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
60
61        $ which krb5-config
62        /usr/bin/krb5-config
63
64 To build [[OpenAFS]] with Kerberos 5 support and the Transarc path conventions:
65
66        ./configure  --enable-transarc-paths --with-krb5-conf=/usr/bin/krb5-config
67        make
68        make dest
69
70 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'.
71
72 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.
73
74       # cp -r i386_linux26/dest/root.client/usr/vice/etc/modload /usr/vice/etc
75       # cp i386_linux26/dest/root.client/usr/vice/etc/afsd /usr/vice/etc
76       # cp -r i386_linux26/dest/bin /usr/afsws
77       # cp -r i386_linux26/dest/etc /usr/afsws
78       # cp -r i386_linux26/dest/include /usr/afsws
79       # cp -r i386_linux26/dest/lib /usr/afsws
80       # cp -r i386_linux26/dest/root.server/usr/afs/* /usr/afs
81
82 #### <a name="Building RPMs"></a> Building RPMs
83
84 The makesrpm.pl script, available in the directory src/packaging/RedHat, is used to build [[OpenAFS]] rpm packages. First build a srpm file using makesrpm.pl, then run rpmbuild to build and package the binaries. makesrpm.pl builds a srpm from the source and document tar files,
85
86     makesrpm.pl openafs-<version>-src.tar.bz2 openafs-<version>-doc.tar.bz2
87
88 This will create the srpm file openafs-.src.rpm. Use rpmbuld with the --rebuild option, which will run configure and then make to build the binaries, and create the rpm files. The rpm files will be placed into /usr/src/redhat/
89
90     rpmbuild --rebuild openafs-<version>.src.rpm
91
92 ### <a name="Running the Test Suite"></a> Running the Test Suite
93
94 [[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.
95
96 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.
97
98       cd src/tests
99       make all
100       sudo perl afs-newcell.pl
101
102 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).
103
104 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.
105
106     Server options:
107     What server name should be used? [host.domain.com]
108     What cellname should be used? [testcell]
109     What vice partition? [a]
110     What administrator username? [admin]
111
112     Kerberos options:
113     Which Kerberos is to be used? [MIT]
114     What Kerberos realm? [TESTCELL]
115     What keytab file? [/usr/afs/etc/krb5.keytab]
116
117     Database Server options:
118     ptserver options: []
119     vlserver options: []
120
121     Fileserver options:
122     Use DAFS fileserver (requires DAFS build option)? (yes/no) [no]
123     fileserver options: []
124     volserver options: []
125     salvageserver options: []
126     salvager options: []
127
128 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.
129
130 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.
131
132       ./run-tests -all
133
134 The output will look something like this,
135
136     Authenticating to cell testcell.
137     ...
138     Running creat1
139     Running mkdir1
140     Running mkdir2
141     ....
142     -----------------------------------------------------------
143     Failed test(s) were:  write-large write-ro ...
144
145 -- [[MichaelMeffie]] - 26 Mar 2008