University of Pretoria
Operational / Internal Site

Debian AFS

Direct AFS access is only possible on-campus. If you are accessing the clusters via the passthrough server (pst or wiener), you need not perform any operation described on this page.

The following procedure describes how to configure a Debian machine in order to access the EECE Kerberos / AFS cell on the UP LAN. The procedure assumes that the user wishes to automatically access his/her AFS home directory on the machine when logging into the machine. The latter part of the procedure, particularly the local configuration, is specific to EECE.

Your best resource for Debian installation documentation is http://www.debian.org. In particular, see the Debian Network Install Page. Local copies of the Network Install CD isos are available under http://ftp.ee.up.ac.za/pub/iso/debian (both the 32bit “i386” and 64bit “amd64” versions).

Network Install

  • Download the netinst CD image from the Debian Installer page and burn it to a CD.
  • Boot from the CD. For troubleshooting during the installation, you can type Ctrl-Alt-F2 then Enter to get a terminal.
  • Choose English, South Africa and American English.
  • On machines with multiple network interfaces, choose the interface that is connected to the UP LAN when prompted.
  • The installer should now obtain an IP address via DHCP and prompt you to enter a computer name. If not, check your network cable. If the hostname isn't correct, just set it to what you want it to be and proceed.
  • Set the domain name to ee.up.ac.za.
  • Choose to erase the entire disk for partitioning unless you want to save something.
  • Choose “All files in one partition” unless you have a different preference.
  • Finish partitioning.
  • Write changes to disks.
  • When prompted for the network repository, choose to manually enter the address (the first option). The repository address is ftp.up.ac.za. You can use the defaults for the rest of the repository configuration entries.
  • Reboot.
  • Set hardware clock to GMT. SAST.
  • For best performance on the UP campus, choose to configure the Debian archive access method manually and enter the following configuration (in /etc/apt/sources.list):
deb ftp://ftp.up.ac.za/debian/ testing main contrib non-free
deb ftp://ftp.up.ac.za/debian-mm/ testing main
deb ftp://ftp.ee.up.ac.za/debian/ debupeece main
  • Remember to do: (after changing the /etc/apt/sources.list file)
aptitude update
  • If you get an error about a key 07DC563D1F41B907, download this file and do the follow (redo the update afterwards):
apt-key add ./missing.txt
  • Choose any desired software to install from the list, such as a Desktop environment. For a custom system, you may not want to choose any software to install at this step.
  • For Exim configuration, choose “mail sent by smarthost; received via SMTP or fetchmail”. System mail name is kendy.up.ac.za. Listen on 127.0.0.1. Outgoing mail to kendy.up.ac.za. Root and postmaster mail recipient: real-root.
  • Choose to install GRUB boot loader to the MBR.
  • Remove CD-ROM and continue.
  • Login and su to root.
  • Update your installed packages:
aptitude update; aptitude dist-upgrade

You'll need to run this periodically to keep your system up-to-date.

  • If you upgraded the kernel, you should reboot:
/sbin/shutdown -r now 

Below is a list of recommended / useful packages under Debian. The obviously useful things such as a web browser, editor, etc. will not be listed.

Development / Programming

Note that in most cases you also need the -dev version of the package, as well as the -doc version.

  • atlas3-sse2: Automatically Tuned Linear Algebra Software. Provides highly optimize libraries that integrates with LAPACK.
  • doxygen: Documentation system for C, C++, Java, Python and other languages.
  • fftw3: Library for computing Fast Fourier Transforms. This implementation is the fastest FFT implementation readily available.
  • graphviz: Rich set of graph drawing tools. Used by doxygen to automatically generate UML diagrams of your OO code.
  • kcachegrind: Visualisation tool for valgrind profiling output. See where your code is spending its time!
  • libgsl0: GNU Scientific Library. Contains routines for Random Number Generation, Statistics, Histograms, Monte Carlo Integration,  Ordinary Differential Equations, Interpolation, Numerical Differentiation, Wavelet Transforms, Discrete Hankel Transforms, Least-Squares Fitting, and much more.
  • strace: A system call tracer.
  • subversion: Advanced version control system
  • sun-java6-jdk: Sun Java(TM) Development Kit (JDK) 6.0
  • valgrind: A memory debugger and profiler. A must have for any C / C++ developer.

Multimedia / Internet Plugins

  • acroread: Adobe Acrobat Reader: Portable Document Format file viewer
  • amarok: Versatile and easy to use audio player for KDE
  • flashplugin-nonfree: Adobe Flash Player plugin installer
  • mplayer: The Ultimate Movie Player For Linux

Customisation (Automatic / Recommended)

This customisation procedure is the recommended approach. Changes to the EECE Kerberos / AFS configuration will then automatically be reflected on the machine when a system update/upgrade is performed.

The following procedure customises a Debian installation for integration with EECE cell. This allows the users home directory to be in AFS and hence accessible from any EECE machine. During the configuration of the Kerberos and AFS standard packages, there will be prompts for site specific parameters. You can use the ones given below… they will be changed to the correct ones by the special Debian EECE@UP packages.

  • Login and su to root.
  • When integrating with LDAP, there is a problem with groups during the startup sequence. This occurs because the device manager (udev) tries to set the group of device files. This occurs early in the bootup sequence, before the network is active. Since LDAP is used for user/group information, the queries cannot succeed and long delays occur. To prevent the long startup delays, download this file and run it with:
sh udevldap.sh
  • Install standardised Debian EECE@UP packages that contain the necessary configuration to integrate the machine with the department's Kerberos / AFS cell:
aptitude install debupeece-afs-config debupeece-kerberos-config \
   debupeece-nssldap-config debupeece-nsswitch-config \
   debupeece-ntp-config debupeece-pam-config 
  • The following prompts ask for information about LDAP, Kerberos and AFS servers. The prompts occur as the above packages cause the required LDAP, Kerberos and AFS packages to be installed. The information entered is not critical as the above configuration packages eventually replace the configuration files with the correct entries.
    • Enter afs0.ee.up.ac.za for the LDAP server.
    • Enter EE.UP.AC.ZA for the Kerberos realm (must be uppercase!).
    • Enter afs0.ee.up.ac.za afs1.ee.up.ac.za afs2.ee.up.ac.za for the realm servers (with spaces separating the server names).
    • Enter afs0.ee.up.ac.za for the administrative server.
    • Enter ee.up.ac.za for the AFS cell.
  • The following entries should be set correctly as they are not handled by the configuration packages.
    • Set AFS cache size to at least 1000000 kB (1GB).
    • Choose to dynamically generate the contents of /afs.
  • Install the openafs-modules with: aptitude install openafs-modules-dkms. This will automatically build an openafs for your kernel.
  • It is recommended that the kredentials and kstart packages be installed. Included in the kstart package is the krenew program, which, once started, automatically renews Kerberos tickets and AFS tokens. If you wish to remain logged into your machine over a number of days, remember to run the krenew command (in a terminal) just after initially logging into your machine (see Access and General Usage for a description). Alternatively, under KDE run the Kredentials utility, which will remain on your desktop pannel and automatically renew your tickets / tokens.
  • If you wish to use Single Sign-On to EECE cluster nodes, install the debupeece-ssh-config package.

Customisation (Manual)

Instead of the semi-automatic customisation above, the procedure below gives a more detailed description.

  • Login and su to root.
  • Install some more useful software. For example:
aptitude install openssh-client openssh-server mozilla-firefox \
  openafs-client openafs-krb5 openafs-modules-source krb5-user \
  krb5-config krb5-clients openssl libpam-afs-session \
  libpam-krb5 libnss-ldap ntp-server ntpdate java-common \
  sudo sysutils valgrind libkrb5-dev libssl-dev \
  zlib1g-dev zlib1g libpam0g-dev 
  • Enter afs0.ee.up.ac.za for the LDAP server.
  • Enter EE.UP.AC.ZA for the Kerberos realm (must be uppercase!).
  • Enter afs0.ee.up.ac.za afs1.ee.up.ac.za afs2.ee.up.ac.za for the realm servers.
  • Enter afs0.ee.up.ac.za for the administrative server.
  • Add .ee.up.ac.za = EE.UP.AC.ZA in the [domain_realm] section of /etc/krb5.conf.
  • Enter ee.up.ac.za for the AFS cell.
  • Set AFS cache size to 1000000 kB (1GB).
  • Choose to dynamically generate the contents of /afs.
  • Install the openafs-modules (see /usr/share/doc/openafs-client/README.modules):
aptitude install module-assistant
module-assistant prepare openafs-modules
module-assistant build,install openafs-modules
/etc/init.d/openafs-client start
  • Set X11Forwarding yes and PermitRootLogin no in /etc/ssh/sshd_config.
  • Set NTP servers in /etc/ntp.conf and /etc/default/ntpdate. For UP hosts, use kendy.up.ac.za.
  • Setup PAM for Kerberos logins. Change /etc/pam.d/common-auth to contain only:
auth    [success=ok default=1] pam_krb5.so forwardable
auth    [default=done]  pam_openafs_session.so
auth    required        pam_unix.so nullok_secure try_first_pass

* Change /etc/pam.d/common-session to contain:

session    optional     pam_krb5.so
session    optional     pam_openafs_session.so
session    required     pam_unix.so
  • If desired, change to using a static IP address rather than DHCP:
aptitude install resolvconf 
  • Edit /etc/network/interfaces. For example:
# The primary network interface
auto eth0
#iface eth0 inet dhcp
#       pre-up iptables-restore < /etc/iptables.up.rules
iface eth0 inet static
        address 137.215.121.100
        netmask 255.255.255.0
        gateway 137.215.121.1
        pre-up iptables-restore < /etc/iptables.up.rules
        dns-search ee.up.ac.za
        dns-nameservers 137.215.101.30 137.215.8.16 137.215.101.16