-This is a guide 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.
+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.
### <a name="Requirements"></a> Requirements
-Tools
+#### <a name="Tools"></a> Tools
-- cvs client
+- Git
- autoconf
- automake
- perl 5.6
-- gcc (versions?)
-- GNU make
+- make
+- compiler/linker (e.g. gcc tool chain)
- lex/yacc (flex/bison)
-Libraries
+#### <a name="Libraries"></a> Libraries
- libc
- kerberos, optional, but recommended
- ncurses
+- pam
- kernel headers
-The Kerberos development libraries are required if you are going to build with Kerberos 5 support. The [[OpenAFS]] legacy kaserver is deprecated.
+The required packages to build [[OpenAFS]] on Debian-based linux distributions can be installed with,
-If you are building on Debian, you can get the required software with the following apt-get commands.
-
- apt-get install cvs autoconf automake make gcc flex bison
+ apt-get install git-core autoconf automake make gcc flex bison
apt-get install libc6-dev libkrb5-dev libncurses5-dev linux-headers-$(uname -r)
-### <a name="Getting the Source Code from CVS"></a> Getting the Source Code from CVS
+On RPM based linux distributions, the packages required are,
-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.
+ yum install gcc autoconf automake make flex bison rpm-build
+ yum install glibc-devel krb5-devel ncurses-devel pam-devel kernel-devel-$(uname -r)
-First you need to run cvs login. This step is normally only done once. A ~/.cvspass file will be created for additional checkouts.
+### <a name="Getting the Source Code"></a> Getting the Source Code
- cvs -d :pserver:anonymous@cvs.openafs.org:/cvs login
- password is anonymous
+Snapshots of the [[OpenAFS]] source code is made available for each stable and each development release at <http://openafs.org>.
-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.
+The [[OpenAFS]] code base is now available from a Git repository. See [[GitDevelopers]] for more information.
-See the CVSWeb interface at <http://www.openafs.org/frameset/cgi-bin/cvsweb.cgi/openafs/> for the full list of available branches and tags.
+### <a name="Building the Binaries"></a> Building the Binaries
-To check out the stable branch:
+#### <a name="Modern Paths"></a> Modern Paths
- cvs -d :pserver:anonymous@cvs.openafs.org:/cvs checkout -r openafs-stable-1_4_x openafs
+To build [[OpenAFS]] with Kerberos 5 support, and with a custom install path. Be sure to run ./regen.sh to generate the configure script.
-To check out the development branch:
+ cd openafs-stable-1_4_x.
+ ./regen.sh
+ ./configure --prefix=/usr/local/openafs --with-krb5-conf=(full path to krb5-config script) --with-linux-kernel-headers=/usr/src/(path to desired kernel headers)
+ make
+ sudo make install
- cvs -d :pserver:anonymous@cvs.openafs.org:/cvs checkout -r openafs-devel-1_5_x openafs
+#### <a name="Transarc Paths"></a> Transarc Paths
-This will create a source tree in a directory named openafs.
+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.
-### <a name="Building the Binaries"></a> Building the Binaries
+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.
-#### <a name="Transarc Paths"></a> Transarc Paths
+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
-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.
+ $ which krb5-config
+ /usr/bin/krb5-config
-To build [[OpenAFS]] with Kerberos 5 support and the traditional, Transarc paths:
+To build [[OpenAFS]] with Kerberos 5 support and the Transarc path conventions:
- cd openafs
- ./regen.sh
- ./configure --enable-transarc-paths --with-krb5-conf=(full path to krb5-config script)
+ ./configure --enable-transarc-paths --with-krb5-conf=/usr/bin/krb5-config
make
make dest
# cp -r i386_linux26/dest/lib /usr/afsws
# cp -r i386_linux26/dest/root.server/usr/afs/* /usr/afs
-#### <a name="Custom Paths"></a> Custom Paths
+#### <a name="Building RPMs"></a> Building RPMs
-To build [[OpenAFS]] with Kerberos 5 support, and with a custom install path,
+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,
- cd openafs
- ./regen.sh
- ./configure --prefix=/usr/local/openafs --with-krb5-conf=(full path to krb5-config script)
- make
- sudo make install
+ makesrpm.pl openafs-<version>-src.tar.bz2 openafs-<version>-doc.tar.bz2
+
+This will create the srpm file openafs-<version>.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/
+
+ rpmbuild --rebuild openafs-<version>.src.rpm
+
+#### If You are Working with a Git Clone and Would Like to Make Your Own tar.bz2 Files
+Start by making sure the root directory of your openafs clone is named to match the version you have checked out. For instance, if you have checked out openafs-stable-1_4_14 from git, then the directory should be named "openafs-1.4.14".
+
+NOTE: If your have checked out a newer version of openafs (1.6), you may want to make sure that a .version file exists in the openafs root directory. It simply holds a bit of text equivalent to the tag on your checkout.
+
+Now tar and compress <afsroot> and <afsroot>/doc like so.
+
+ tar -cvjf openafs-<version>-src.tar.bz2 <afsroot>
+ tar -cvjf openafs-<version>-doc.tar.bz2 <afsroot>/doc
+
+After that, you can run makesrpm.pl as stated above.
+
+### <a name="Running the Test Suite"></a> Running the Test Suite
+
+[[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.
+
+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.
+
+ cd src/tests
+ make all
+ sudo perl afs-newcell.pl
+
+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).
+
+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.
+
+ Server options:
+ What server name should be used? [host.domain.com]
+ What cellname should be used? [testcell]
+ What vice partition? [a]
+ What administrator username? [admin]
+
+ Kerberos options:
+ Which Kerberos is to be used? [MIT]
+ What Kerberos realm? [TESTCELL]
+ What keytab file? [/usr/afs/etc/krb5.keytab]
+
+ Database Server options:
+ ptserver options: []
+ vlserver options: []
+
+ Fileserver options:
+ Use DAFS fileserver (requires DAFS build option)? (yes/no) [no]
+ fileserver options: []
+ volserver options: []
+ salvageserver options: []
+ salvager options: []
+
+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.
+
+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.
+
+ ./run-tests -all
+
+The output will look something like this,
-### <a name="Initial testing"></a> Initial testing
+ Authenticating to cell testcell.
+ ...
+ Running creat1
+ Running mkdir1
+ Running mkdir2
+ ....
+ -----------------------------------------------------------
+ Failed test(s) were: write-large write-ro ...
--- [[MichaelMeffie]] - 09 Oct 2007
+-- [[MichaelMeffie]] - 26 Mar 2008
git://git.openafs.org / openafs-wiki.git / blobdiff