Research and Development Network

{{toc}}

h1. AFS Client Installation

Originally at the DevNet project pages.

A very nice guide can be found at Cornell https://confluence.cornell.edu/display/CNF/Installing+AFS

h1. Windows

Some good instructions at http://claymore.rfmh.org/public/computer_resources/winAFSclientinstall.html

# Install the Kerberos for Windows 3.2.2

## *IMPORTANT: Do NOT install version 4.X.  It does not work with AFS*

## *IMPORTANT: If you install the 64 bit version, you will also need to install the 32 bit tools*

## http://www.secure-endpoints.com/netidmgr/roadmap.html

# Install the latest version of Network Identity Manager

## https://www.secure-endpoints.com/netidmgr/v2/#download

## When asked, the kerberos realm is @CS.RU.IS@ *Note the uppercase letters*

## If you are not a RU student or staff, then your realm will be @RND.RU.IS@

# Download the latest OpenAFS version, preferably 1.7 or higherD

## *IMPORTANT: If you install the 64 bit version, you will also need to install the 32 bit tools*

## http://www.openafs.org/windows.html

## The AFS realm is @rnd.ru.is@  *Note the lowercase letters and that it is NOT cs.ru.is*

# Then reboot the computer

# You will notice after rebooting a new context menu "AFS" when you right click anywhere.  This is how you will interact with AFS to get information and change access control.

# You will need to get Kerberos Tickets from the "Network Identity Manager".  This will also show up in the little icons in the bottom right.  If you can't find it, you can also run it from the start menu

## You need to create a new credential.  Replace "username" in these instructions with your username

## Menubar Credential > New Credentials > Obtain new credentials...

## Click on the top bar where it says Kerberos Principal > New Identity

## Username:  (whatever your username was) and click "Next >"

## Realm: CS.RU.IS "Next >"

## Keep the default options. click "Next >"  

## Make sure "Obtain AFS credentials" is clicked.  The Cell should be "rnd.ru.is".  Note that this must be in lowercase and different than your kerberos realm.  Click on "Add/Update" then "Next >"

## If you are presented with Kerberos 4 options, disable them.  Click "Next >"

## You should now type in your password and "Finish"

### You will have to get new credentials and type in your password every 8 hours.

## If all goes well, you will see that the username@CS.RU.IS entry will say you have "Kerberos v5 tickets (s) AFS tokens (1)"

# To find AFS, goto the "Network" in an explorer window.  There should be an AFS entry.  

## Double click on it, then double click on "rnd.ru.is"

h1. Linux 

After you have followed the directions below, if you have local users, you will need to adjust the minimum UID in the pam settings or it won't let you change the password.  In debian, look under @/etc/pam.d/common-password@

<pre>

password        [success=2 default=ignore]      pam_krb5.so minimum_uid=2000

</pre>

Make sure that all of your local (non-kerberos) users have a UID that is lower than the minimum_uid.

h2. Raspberry Pi (Debian)

These instructions are not completely tested.

You will need at least a 4GB card to download all the necessary software and linux kernel

Much of this is taken from http://www.raspberrypi.org/phpBB3/viewtopic.php?f=71&t=17666

Other guides:

* rpi-update https://github.com/Hexxeh/rpi-update/

# Install the latest dist and necessary tools

<pre>sudo bash

apt-get update

apt-get -y dist-upgrade

apt-get -y install gcc make git build-essential dkms

</pre>

# Install rpi-update and grab the latest firmware

<pre>

cd rpi-update

apt-get install ca-certificates

sudo wget http://goo.gl/1BOfJ -O /usr/bin/rpi-update && sudo chmod +x /usr/bin/rpi-update

</pre>

# Grab latest kernel

<pre>cd /usr/src

wget  https://github.com/raspberrypi/linux/tarball/rpi-3.2.27 -O rpi-3.2.27.tgz

tar xzf rpi-3.2.27.tgz

</pre>

# Grab the configs from the kernel

<pre>cd raspberrypi-linux-*

zcat /proc/config.gz > .config

make oldconfig

make modules_prepare

</pre>

# Get the 

<pre>wget https://github.com/raspberrypi/firmware/raw/master/extra/Module.symvers</pre>

# Make symlinks for the build system

<pre>KSRC=`pwd`

pushd /lib/modules/`uname -r`

ln -s ${KSRC} source

ln -s ${KSRC} build

popd

pushd /usr/src

ln -s ${KSRC} linux-`uname -r`

ln -s ${KSRC} linux

popd</pre>

# Install kerberos packages

<pre>apt-get install krb5-auth-dialog krb5-user krb5-clients libpam-ccreds libpam-krb5</pre>

# Install the afs client and related modules

<pre>apt-get install  openafs-modules-dkms openafs-{client,krb5}</pre> 

## if it doesn't go successfuly, you can re-run it with:

<pre>dpkg-reconfigure openafs-modules-dkms</pre>

h2. Debian/Ubuntu

Note!  AFS and Keberos will mostly autoconfig on the client side unless RU's DNS is broken.  It is very important that you never let the disk that has the AFS cache fill up.  If that happens, bad things may occur.  See directions about how to setup a fixed cache if you are concerned about this.  In some installations, people put the cache in a separate partition to eliminate the risk.

h3. Kerberos Client

* see e.g., Spinlock Guide on Kerberos http://techpubs.spinlocksolutions.com/dklar/kerberos.html

# Install packages for Kerberos and AFS

<pre>sudo apt-get install krb5-auth-dialog krb5-user libpam-ccreds libpam-krb5 build-essential dkms linux-headers-`uname -r` libpam-afs-session openafs-modules-dkms openafs-{client,krb5}</pre>

# The kerberos config will ask you questions, you should answer:

** realm: @RND.RU.IS@

** Kerberos server: @kerberos.rnd.ru.is@

** Kerberos administrative server: @kerberos.rnd.ru.is@

** If you need to fix this later, run @dpkg-reconfigure krb5-config@

# Check DNS and hostnames

* Make sure that the hostname is not listed in @/etc/hosts@

* Make sure that the @hostname@ command returns the full hostname e.g. gryla.rnd.ru.is

# Edit the @/etc/krb5.conf@

** search for @[domain_realm]@ and add these lines after

<pre>

.rnd.ru.is = RND.RU.IS

rnd.ru.is = RND.RU.IS

</pre>

** After @[libdefaults]@ add

<pre> allow_weak_crypto = true </pre>

# if you do not have a Kerberos user name: ask Joe (foley@ru.is) or Stephan (stephans@ru.is) to give you one

# check if it works <pre>

$ kinit YOUR_KERBEROS_USERNAME

Password for YOUR_KERBEROS_USERNAME@RND.RU.IS:

$ klist

Ticket cache: FILE:/tmp/krb5cc_1000

Default principal: YOUR_KERBEROS_USERNAME@RND.RU.IS

Valid starting     Expires            Service principal

03/30/12 13:53:15  03/30/12 23:53:15  krbtgt/RND.RU.IS@RND.RU.IS

        renew until 03/31/12 13:53:11

</pre>

# if the Kerberos principal and the local username differ

** create the file @~/.k5login@ with the content <pre>MYPRINCIPAL@RND.RU.IS</pre>

** instruct pam-krb5 to read your principal from @~/.k5login@ by adding the following to @/etc/krb5.conf@:

<pre>

[appdefaults]

        pam = {

                search_k5login = true

        }

</pre>

Now use the Kerberos principal's password when asked for a password on login at your computer and you should automatically get a Kerberos ticket (check with @klist@ after login). If not connected to the Internet, the local password is active/requested again.

h3. AFS Client

# Install packages

<pre>sudo apt-get 

</pre> 

## Cell: @rnd.ru.is@

## Cache: @500000@ (choose depending on your hard disk space, more cache = less network traffic)

# Now setup the cache so it can never overfill (very bad things happen).  If you have already setup a partition for the cache then this step is unnecessary.

<pre>

cd /var/cache

sudo dd if=/rnd/zero of=openafs-cache.img bs=10M count=55   # (~550 MB partition)

sudo mkfs.ext4 openafs-cache.img

sudo sh -c "echo '/var/cache/openafs-cache.img /var/cache/openafs ext4 defaults,loop 0 2' >> /etc/fstab"

sudo tune2fs -c 0 -i 0 -m 0 openafs-cache.img

</pre>

# test by mounting the cache

<pre>sudo mount /var/cache/openafs</pre>

# Add entries to @/etc/openafs/CellServDB@

## Note that the AFS cell *MUST* be lowercase

<pre>>rnd.ru.is         # Reykjavik University Research and Development Network

130.208.242.66          #afsdb1.rnd.ru.is

130.208.242.67		#afsdb2.rnd.ru.is

130.208.242.68          #afsdb3.rnd.ru.is  

</pre>

# enable the AFS client (not always needed)

<pre>sudo perl -pi -e's/AFS_CLIENT=false/AFS_CLIENT=true/' /etc/openafs/afs.conf.client</pre>

# (re-)start the client

<pre>sudo invoke-rc.d openafs-client restart</pre>

# Get AFS tokens upon login (from pam-afs)

## Note that this will only automatically get tokens if you add this line in @/etc/pam.d/common-session@ after the @pam_krb5.so@ line

<pre>session required                        pam_afs_session.so program=/usr/bin/aklog</pre>

# have fun at @/afs/rnd.ru.is/@

# If you want to make it a little simpler, do a symlink from /afs/rnd.ru.is/<.,..>/<username> to /home/username

# then you don't have to change /etc/password to start using the homedirectory!

# To automatically get Kerberos tickets and AFStokens, grab this auth-client-config file http://afs.rnd.ru.is/project/rndnet/Public/Workstation/etc/auth-client-config/profile.d/rndnet and put it into @/etc/auth-client-config@.  You can also grab them via afs:

<pre>cp /afs/rnd.ru.is/project/rndnet/Public/Workstation/etc/auth-client-config/profile.d/rndnet /etc/auth-client-config/profile.d/.</pre>

# Then run it to set your machine to configure PAM and NSS for kerberos/afs

<pre>sudo auth-client-config -a -p rndnet_workstation</pre>

h3. Debian 7 on a KVM/Proxmox VM

The VMs need a fix for a module compile problem with struct dentry, which is fixed in openafs 1.6.11, which is sadly not in the stable distribution.

After you follow the main debian instructions, you need to:

# Switch to sid (unstable

<pre>zile /etc/apt/sources.list

#replace wheezy with sid

</pre>

# select 1.6.11

<pre>apt-get update; apt-get install openafs-modules-dkms=1.6.11.1-1</pre>

# Now the kernel module will build properly.

h2. Redhat Varients

Mageia: https://wiki.mageia.org/en/Installing_OpenAFS_Client

h3. Fedora

Openafs has binary builds for up to Fedora 20.  Follow the centos instructions.

For Fedora 21 (or others) you will need to do a source build.  Get the src.rpm and follow these instructions on the wiki

http://wiki.openafs.org/HowToBuildOpenAFSFromSource/

Alternatively use the copr packages from jsbillings

* https://copr.fedoraproject.org/coprs/jsbillings/openafs/

* https://copr.fedoraproject.org/coprs/jsbillings/openafs-kmod/

Generally this is a better idea

Let's get started

* Grab the appropriate .repo files and put them into /etc/yum.repos.d

* Update yum

<pre>yum -y update</pre>

* Prerequisites and the packages

<pre>

yum install git-core gcc autoconf automake libtool make flex bison glibc-devel krb5-devel perl-devel ncurses-devel pam-devel kernel-devel-$(uname -r) wget perl-devel perl-ExtUtils-Embed rpm-build krb5-libs krb5-workstation dkms rpmbuild kernel-headers dkms openafs-client openafs-krb5 dkms-openafs

</pre>

* Make sure that the /var/cache/openafs got labeled for selinux

<pre>restorecond -r -v /var/cache/openafs</pre>

* Sometimes dkms does not run for newer kernels, check in /var/lib/dkms/openafs.  Check which version e.g. 1.6.11-1.fc21 if you need to force it

<pre>dkms --verbose install -m openafs -v 1.6.11-1.fc21</pre>

* Start it up!

<pre>service openafs-client start</pre>

* Update your /etc/krb5.conf.  The stock version is missing a lot of entries.

If you have problems, it is most likely that the cache is the wrong size.

Another problem is if DKMS refuses to build because you don't have the latest kernel-dev installed or an older kernel build in the way

<pre>

dnf -y install kernel-devel-$(uname -r) --allowerasing

dnf reinstall dkms-openafs

</pre>

h3. Centos

From http://docs.openafs.org/QuickStartUnix/ch02s09.html

* Install EPAL repos

** i386 (32 bit) <pre>rpm -U http://www.fedora.is/epel/6/i386/epel-release-6-8.noarch.rpm</pre>

** 64(bit) <pre>rpm -U http://www.fedora.is/epel/6/x86_64/epel-release-6-8.noarch.rpm</pre>

* Grab the openafs repositories file 

<pre>wget http://dl.openafs.org/dl/openafs/1.6.6/openafs-repository-rhel-1.6.1-5.noarch.rpm</pre>

* Install the source repositories

<pre>rpm -U openafs-repository*.rpm</pre>

* Make sure that the source repositories are enabled in @/etc/yum.repos.d@.

* Edit @/etc/yum.conf.d/openafs-rhel.repo@

** change $basearch to $arch in <pre>baseurl=http://dl.openafs.org/dl/openafs/1.6.6/rhel$releasever/$arch/</pre>

** set <pre>gpgcheck=0</pre>  because the rpms are currently not signed

* Install kerberos

<pre>sudo yum -y install krb5-libs krb5-workstation

</pre>

* Install rndelopment packages

<pre>sudo yum -y groupinstall "Rndelopment Tools"</pre>

* Install the packages

<pre>sudo yum -y install kernel-headers kernel-rndel-`uname -r` dkms openafs-client openafs-krb5 dkms-openafs</pre>

* Now go edit @/etc/krb5.conf@

<pre>[libdefaults]

 default_realm = RND.RU.IS

 dns_lookup_realm = true

 dns_lookup_kdc = true

 allow_weak_crypto = true

</pre>

* Edit @/etc/ntp.conf@ and set time.rnd.ru.is as the server

* Restart ntpd

<pre>sudo service ntpd restart</pre>

* Edit @/etc/vice/etc/ThisCell@ and put rnd.ru.is in it

* Start the services

<pre>sudo service openafs-client start</pre>

h1. OSX

Guides:

* General guide http://www.spy-hill.com/~myers/help/apple/OpenAFS.html

* Server and tool guide http://workshop.openafs.org/afsbpw06/talks/kula-afsbpw06.pdf

h3. Install

# Install the client at http://openafs.org/macos.html

# Install the MIT Kerberos extras http://web.mit.edu/macdev/www/osx-kerberos-extras.html

# Reboot

h3. Where is the @krb5.conf@?

From: http://support.apple.com/kb/TS3265

Kerberos looks for configuration options in these locations (in this order):

# ODbundle (magic DNS)

# @~/Library/Preferences/edu.mit.Kerberos@

# @/Library/Preferences/edu.mit.Kerberos@

# @/etc/krb5.conf@

If you have not installed the MIT Kerberos extras, the files will not exist.

h2. Testing

# Notice the lock icon on the top of the Finder window that allows you to start and stop AFS

# To get tickets, you need to open a terminal

## Use Spotlight and type "Terminal" or goto Applications > Utilities > Terminal

# Use @kinit@ to get tickets.  Replace @user@ with your username

## <pre>kinit user@RND.RU.IS</pre>

# Use @aklog@ to get AFS tokens

## <pre>aklog rnd.ru.is</pre>

h2. Useful stuff

The AFS tools are in  @/Library/OpenAFS/Tools/bin/@  You may want to make a symlink to /usr/bin so that you don't have to type the name in all the time

<pre>sudo ln -s /Library/OpenAFS/Tools/bin/* /usr/bin/.</pre>

h1. Common

At some point in the install, you will may need to adjust the kerberos configuration file.  In the those instructions, you will be referred back to here.  You don't need to do so until instructed.

On windows systems, this file is @c:\Windows\krb5.ini@.  On OSX and Linux, it is @/etc/krb5.conf@.  See the OSX instructions for alternatives.

You can grab a copy at http://afs.rnd.ru.is/project/rndnet/Public/Workstation/etc/krb5.conf

Make sure it contains these lines.  There will be more entries in the file, don't delete them. Also, don't copy the ... lines

<pre>

[libdefaults]

default_realm = RND.RU.IS

dns_lookup_realm = true

dns_lookup_kdc = true

# The following krb5.conf variables are only for MIT Kerberos.

        krb4_config = /etc/krb.conf

        krb4_realms = /etc/krb.realms

        kdc_timesync = 1

#       ccache_type = 4

        forwardable = true

        proxiable = true

# need this for AFS and MIT

        allow_weak_crypto = yes

#... other stuff ...

[realms]

	RND.RU.IS = {

		kdc = kerberos.rnd.ru.is

		kdc = kerberos-1.rnd.ru.is

		kdc = kerberos-2.rnd.ru.is                

		admin_server = kerberos.rnd.ru.is

                default_domain = rnd.ru.is

	}

        CS.RU.IS = {

                kdc = ipa.cs.ru.is

                admin_server = ipa.cs.ru.is

                default_domain = cs.ru.is

        }

#... more stuff ...

[domain_realm]

        .cs.ru.is = CS.RU.IS

        cs.ru.is = CS.RU.IS

        .rnd.ru.is = RND.RU.IS

        rnd.ru.is = RND.RU.IS

#... more stuff ...

</pre>

h3. Debugging problems in windows

http://webchat.freenode.net and connect to channel #openafs

If you need to adjust the Kerberos or CellSrvDB settings.  This is *optional* and only necessary if you can't see the AFS folders after the above directions.

* Remember that you need to right-click on your editor first and "Run as administrator" *DO NOT OPEN IN NOTEPAD!  IT WILL MANGLE THE FILE!!!!*

* CellServDB is in @c:\Program Files\OpenAFS\Client@

<pre>>rnd.ru.is         # Reykjavik University Research and Development Network

130.208.242.66          #afsdb1.rnd.ru.is

130.208.242.67		#afsdb2.rnd.ru.is

130.208.242.68          #afsdb3.rnd.ru.is  

</pre>

* Now edit @c:\Windows\krb5.ini@.  You shouldn't need to do this if DNS is working right.  Refer to the [[AFS_Client_Installation#Common|Test]] section above for what should go into that file.

Tools:

* http://technet.microsoft.com/en-us/sysinternals/bb896653

* http://technet.microsoft.com/en-us/sysinternals/bb896655

h1. Frequently Asked Questions (FAQ)

Lots of issues and suggestions here:

* http://docs.oracle.com/cd/E19253-01/816-4557/trouble-6/index.html

* http://www.ncsa.illinois.edu/UserInfo/Resources/Software/kerberos/troubleshooting.html

A good place to get help is the #openafs channel at freenode IRC:  https://webchat.freenode.net/

h2. How do I calculate the maximum cache size?

See this page:  https://wiki.mageia.org/en/Installing_OpenAFS_Client#Check_correct_cache_size_is_defined

h2. AFS's module loaded but there is nothing in /afs.  What went wrong?

You might have a cache size issue or something else stopping the client.

Check the logs.  On a systemd/journald system <pre>systemctl status openafs-client</pre>

h2. I can see the AFS cell, but I can't access my files in my home directory/folder

This probably means you are not getting tokens.  make sure you see "AFS tokens(1)" next to your name on the Network Identity Manager.

If you don't:

# Menubar: Options > Identities

# Click on the username@RND.RU.IS entry

# Select the AFS tab

# Make sure "rnd.ru.is" is listed in the table.  Make sure that "openafs.org" is not listed.  You can use the "Add/Update" and "Delete" buttons to adjust the list.

# Click "Apply"

Another possibility is that AFS has old data in that particular folder.  This is where the "flush" commands can be useful.  Try these things in this order (it may start working after any of them)

# Click on the folder, then right-click AFS > Volume/Partition > Refresh name/ID map

# Click on the folder, then right-click AFS > Flush File/Dir

# Click on the folder, then right-click AFS > Flush Volume

# If that doesn't work, restart AFS through the Control Panel or rebooting

h2. "kinit: KDC has no support for encryption type while getting initial credentials"

This means you need to manually enable weak encryption.  This is needed by AFs in order to get an authentication token.  Older Kerberos servers only use the old encryption types.  Information at https://bugzilla.redhat.com/show_bug.cgi?id=573968

Solution:  Enable weak crypto

# Edit @/etc/krb5.conf@ (or equivalent) 

## Add @allow_weak_crypto = yes@ on the @[libdefaults]@ section

h2. While upgrading Kerberos, you get the need to restart the Kerberos Cache RPC SErver

Solution: Find the Process ID and kill it on the terminal

# Start Menu > Run > @taskkill /F /PID@ PID-number

h2. AFS appears to be running (windows) but no \\AFS directory

Oh boy, there are many things that can be wrong here.  First run a virus checker to look for rootkits.

A problem that we discovered was if the TEMP registry entries are set to a non-absolute path.  (e.g. c:\temp is good foo\bar\temp is bad)

# open a cmd.exe as administrator

# regedit.exe

# goto HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment

# Change the TMP and TEMP entries to a valid path that everyone can access, particularly SYSTEM

# Make sure that these (and windir) are all type REG_EXPAND_SZ

h1. Reference

* Ubuntu Serverguide to Kerberos https://help.ubuntu.com/12.04/serverguide/kerberos.html

h2. Kerberos complains about a generic error and seeing e-text

Not sure what causes this.  Some google searching implies problems with the directory lookup.  Simplest solution is to just delete the user and re-create