OpenAFS Wiki/ devel/ InstallationGuideEnterpriseLinux

Installation Guide for Enterprise Linux

This guide provides step-by-step instructions for installing and configuring a complete OpenAFS environment on the Red Hat Enterprise Linux family of distributions, including RHEL, CentOS-Stream, Fedora, AlmaLinux, Rocky Linux, and Oracle Linux.

This guide is specifically for development and testing purposes. It covers the setup of a Kerberos Key Distribution Center (KDC), an OpenAFS server (database and file server), and an OpenAFS client, all on a single virtual machine. This document is intended for system administrators, developers, testers, or anyone interested in learning the fundamentals of OpenAFS by creating a functional, non-production test environment.

  1. Before you begin
    1. Requirements
    2. Naming conventions
    3. OpenAFS installation methods
    4. SSH Keys
    5. Storage considerations
    6. Static IP addresses
    7. DNS and hostname resolution
    8. SELinux modes
    9. Firewall rules
  2. Preparing a VirtualBox virtual machine
    1. Create a virtual machine
    2. Configure local SSH settings
    3. Configuring hostname resolution
    4. Setting permissive mode for development
    5. Adding a disk for the OpenAFS client cache
      1. Step 1: Adding a hard disk
      2. Step 2: Identifying the block device
      3. Step 3: Partitioning the disk
      4. Step 4: Formatting the partition
      5. Step 5: Mounting the filesystem
    6. Adding a disk for the OpenAFS file server
      1. Step 1: Adding a hard disk
      2. Step 2: Identifying the block device
      3. Step 3: Partitioning the disk
      4. Step 4: Formatting the partition
      5. Step 5: Mounting the filesystem
      6. Step 6: Repeat for additional partitions
    7. Finalizing the virtual machine preparation
  3. Installing Kerberos for authentication
    1. Installing the Kerberos server
    2. Creating the Kerberos realm
      1. Configuring the Kerberos configuration information
      2. Configuring the Kerberos KDC
      3. Configuring the Kerberos administration access controls
      4. Creating the Kerberos database
      5. Starting the Kerberos services
      6. Creating the admin principal
    3. Taking a snapshot after Kerberos installation
  4. Installing OpenAFS
    1. Method 1: Installing from a package repository
      1. Configuring the package repository
      2. Installing the packages
      3. Alternative 1: Installing with a pre-built kernel module
      4. Alternative 2: Installing with DKMS managed kernel module
    2. Method 2: Installing from packages
      1. Upload RPMs
    3. Method 3: Installing from source code
      1. Configuring EPEL repository
      2. Installing build requirements
      3. Checking out the source code
      4. Building the binaries
      5. Installing the binaries
      6. Pre-configuring the client
      7. Creating compatibility symlinks
      8. Configuring the systemd services
  5. Configuring the first OpenAFS server
    1. Creating the OpenAFS Service Principal
    2. Start the OpenAFS BosServer
    3. Configuring the cell name
    4. Creating the database servers
    5. Creating the file server
    6. Setting server restricted mode
    7. Verifying the servers are running
  6. Configuring the OpenAFS client
    1. Configuring the client's local cell
    2. Configuring the client disk cache
    3. Configuring the client startup options
    4. Starting the OpenAFS client
  7. Creating a new cell
    1. Creating an administrator user
    2. Creating the cell root volumes
    3. Logging in as an administrator
    4. Mounting the cell root volume
    5. Setting the root directory access rights
    6. Creating the read-only root volumes
    7. Taking a snapshot after configuring the cell
    8. Conclusion and next steps
  8. Adding OpenAFS database servers
    1. Creating additional virtual machines for the database servers
    2. Configuring hostname resolution for the cluster
    3. Prechecking the cluster health
      1. Checking connectivity
      2. Checking clock synchronization
      3. Checking hostnames resolution
    4. Installing OpenAFS on the database servers
    5. Configuring the database servers
    6. Starting the BosServer on the database servers
    7. Create the additional database instances
    8. Distributing the cell configuration
  9. Adding OpenAFS file servers
    1. Creating an additional virtual machine for a file server
    2. Installing OpenAFS on the file server
    3. Deploying the cell configuration to the file server
    4. Starting the file server
  10. Adding OpenAFS clients
    1. Creating an additional virtual machine for a client
    2. Installing OpenAFS on the additional client
    3. Configuring the additional client
    4. Starting the OpenAFS client on the additional machine

Before you begin

Requirements

This guide assumes you have the following prerequisites:

  • Ability to set up sudo access on the virtual machine to install packages and modify system configurations.
  • A working network connection on the virtual machine to download necessary software packages.
  • Familiarity with the Linux command line and editing configuration files with a text editor.
  • DNS configuration is not required for this guide, as we will use local hostname resolution.
  • No prior experience with OpenAFS is required.

Naming conventions

This guide uses placeholder names for hosts, users, and realms. You should replace these with values appropriate for your own environment:

  • openafs-server1: The hostname.
  • openafs-server1.example.test: The fully qualified hostname.
  • example.test: The OpenAFS cell name and DNS domain.
  • EXAMPLE.TEST: The Kerberos realm name.
  • root/admin: A Kerberos administrator principal.
  • root.admin: An OpenAFS administrator username.

OpenAFS installation methods

This guide presents three primary methods for installing OpenAFS, each suited for different testing scenarios:

  • Install from a package repository: This is the recommended method for testing official stable releases. It uses standard DNF commands to install OpenAFS from a yum repository.

  • Install from pre-built packages: This method is useful for testing release candidates or custom-built RPMs that are not yet in a repository. The packages are copied to the virtual machine and installed manually.

  • Install from source code: This approach is best for developers who need to test unreleased features, work with development branches, or run programs that are part of the build but not included in the official packaging. It involves cloning the source code with Git, compiling, and installing it.

When installing the OpenAFS client from RPM packages (the first two methods above), there are two alternatives for the OpenAFS kernel module:

  • Pre-built kernel module (kmod): This is the simplest method. It uses a pre-compiled kernel module that matches a specific kernel version.

  • Dynamic Kernel Module Support (DKMS): This method automatically rebuilds the OpenAFS kernel module whenever the system's kernel is updated. It is more flexible but requires the installation of the kernel development tools and can take longer to install.

SSH Keys

This guide assumes you already have an SSH public/private key pair, which is required to securely connect to the virtual machine you will create.

If you do not have an SSH key pair, you can generate one on your local Linux, macOS, or Windows (with WSL or Git Bash) machine using the ssh-keygen command. It is recommended to enter a strong passphrase to protect your private key. After running the ssh-keygen command, you will have two files: your private key and your public key, (which ends in .pub). You will use the content of the .pub file when configuring your virtual machine.

This guide assumes you are using a local SSH agent and you have enabled SSH key forwarding. This will allow you to SSH between machines when you create multiple VMs. If you are not using an agent, or choose not to enable SSH key forwarding, then you will need to set up SSH keys on each VM and distribute your public keys to the authorized_keys files on each VM.

Storage considerations

To simulate a production-like environment, this guide demonstrates setting up dedicated disk partitions for both the OpenAFS File Server (to store volume data) and the client's Cache Manager (for the disk cache). While dedicated partitions are recommended, we will also cover using directories on the root filesystem for simpler, light-duty testing.

Static IP addresses

It is recommended to configure a static IP address for your virtual machines. OpenAFS servers and clients rely on stable network addresses for proper operation. If the IP address of the server changes, the client will not be able to contact it, and you will need to update the /etc/hosts file and restart the OpenAFS services.

For short-lived test systems, you can use DHCP, but be aware that you may need to reconfigure the system if the IP address changes.

For longer-lived systems, you can use a static IP address.

DNS and hostname resolution

For this guide, we will not be setting up a dedicated DNS server or adding records to an existing DNS infrastructure. Instead, we will rely on modifying the /etc/hosts file on our virtual machine to resolve the necessary hostnames. This approach is sufficient for a self-contained test environment. However, in a production or multi-machine OpenAFS deployment, you would need to create the appropriate DNS records (A, AFSDB, and SRV) for your cell to function correctly.

SELinux modes

While an enforcing SELinux mode is recommended for production systems, this guide uses permissive mode. In permissive mode, SELinux logs actions that would have been denied but does not block them. This is useful in a development or testing environment to ensure that SELinux is not interfering with the software being tested. Additional configuration steps are required to run OpenAFS in a fully enforced SELinux environment, which will be covered in a future appendix.

Firewall rules

While firewalls are recommended for production systems, this guide assumes the machines are on a private network and so the firewall is disabled. To enable the firewall, you will need to add rules to allow OpenAFS traffic.

Preparing a VirtualBox virtual machine

This page describes how to create a new virtual machine on which you can set up OpenAFS for testing. In this guide, you will create a virtual machine running AlmaLinux.

Create a virtual machine

  • Download latest AlmaLinux ISO image and create a new virtual machine in VirtualBox with the following settings:

    • General: Identity: VM Name: openafs-server1
    • Motherboard: Base Memory: 2048MB
    • Processor: Number of CPUs: 2
    • Use EFI: Unchecked
    • Storage: 15GB
    • Network: NAT (configure DHCP for test system, otherwise static IP)

  • Boot into the VM

  • Ensure the system is up to date.

    $ sudo dnf update -y

  • After the update completes, reboot the system to apply all changes and ensure it is running the latest Linux kernel version:

    $ sudo reboot

  • Wait until the machine reboots. Once it is done, note the IPv4 address.

Configure local SSH settings

This step is optional, but it is helpful to set an entry in your local .ssh/config file for the new VM so you can connect to it by name.

Add the following stanza to your .ssh/config for your new VM. Replace the username and path to the identity file with the ones you use for other VMs.

Host openafs-server1
  HostName <your-vm-ip-address>
  User <your-user-name>
  IdentityFile <your-ssh-key-file-path>
  ForwardAgent yes
  StrictHostKeyChecking no
  UserKnownHostsFile=/dev/null
  LogLevel ERROR

Verify you can SSH to your new VM with:

$ ssh openafs-server1

The remaining steps in this section should be performed in the SSH session on openafs-server1.

Proceed to Configuring hostname resolution.

Configuring hostname resolution

For this self-contained test environment, we will use the /etc/hosts file for all hostname resolution instead of setting up a dedicated DNS server. This ensures that the OpenAFS components can communicate with each other using the configured hostnames. It is critical that the hostname resolves to a non-loopback IP address for the OpenAFS services to function correctly.

Verify the hostname is correct.

$ hostnamectl --static
openafs-server1.example.test

If the hostname is not correct, run hostnamectl hostname openafs-server1.example.test.

Determine the IPv4 address assigned to the local interface.

$ ip -f inet address | awk '/inet/ {print $2}' | grep -v '^127' | cut -f1 -d/

Append a line to the /etc/hosts file so the hostname will resolve to the IP address.

$ echo "<ip-address> openafs-server1.example.test openafs-server1" | sudo tee -a /etc/hosts
172.17.20.52 openafs-server1.example.test openafs-server1
$ cat /etc/hosts
127.0.0.1   localhost localhost.localdomain localhost4 localhost4.localdomain4
::1         localhost localhost.localdomain localhost6 localhost6.localdomain6
172.17.20.52 openafs-server1.example.test openafs-server1

Verify the hostname correctly resolves to the IPv4 address.

$ getent ahosts openafs-server1 openafs-server1.example.test
172.17.20.222   STREAM openafs-server1.example.test
172.17.20.222   DGRAM
172.17.20.222   RAW
172.17.20.222   STREAM openafs-server1.example.test
172.17.20.222   DGRAM
172.17.20.222   RAW

Proceed to Setting permissive mode for development.

Setting permissive mode for development

Since this guide is for setting up systems for testing and development, it is recommended to set the SELinux mode to permissive. This allows SELinux to log warnings without preventing the software under test from functioning. Set the SELinux mode to permissive and change the SELinux configuration file to make this persist over reboots.

$ sudo setenforce 0
$ sudo sed -i 's/^SELINUX=.*/SELINUX=permissive/' /etc/selinux/config

In addition, the firewalld ports for OpenAFS must be opened or the firewalld service must be disabled. Since our machines are on a private network, the firewall can be disabled.

$ sudo systemctl disable firewalld
$ sudo systemctl stop firewalld

If you would like to use disk partitions for this test machine, proceed to Adding a disk for the OpenAFS client cache.

Otherwise, proceed to Finalizing the virtual machine preparation

Adding a disk for the OpenAFS client cache

A dedicated partition is recommended for the client cache; however, for a quick test setup, this section is optional. If you choose to skip this section, proceed to Finalizing the virtual machine preparation.

Step 1: Adding a hard disk

In this guide, we add a cache partition by adding a small virtual disk and then formatting and mounting the disk in the running VM.

Add a virtual hard disk to your VM.

  • Shutdown your VM
  • In the settings pane, choose Storage and add another 4GiB hard drive.

Step 2: Identifying the block device

Log in to your VM with SSH and run lsblk to find the block device name of the new disk. The TYPE will be disk and the device will not have any part children. It will probably be sdb, but it could have a different name. If the device has a different name, use that name in the following examples.

Example lsblk output after adding a disk:

$ lsblk
NAME               MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS
sda                  8:0    0   32G  0 disk
├─sda1               8:1    0    1G  0 part /boot
└─sda2               8:2    0   31G  0 part
  ├─almalinux-root 253:0    0 28.9G  0 lvm  /
  └─almalinux-swap 253:1    0    2G  0 lvm  [SWAP]
sdb                  8:16   0    4G  0 disk
sr0                 11:0    1    4M  0 rom
sr1                 11:1    1  1.9G  0 rom

Step 3: Partitioning the disk

Create a primary partition with fdisk.

Caution: The partitioning process is destructive. Be sure to specify the correct device name found in step 2 in the steps that follow.

  • Run sudo fdisk /dev/, for example, sudo fdisk /dev/sdb
  • Inside the interactive prompt, type these keys in order:
    • n (New partition)
    • p (Primary)
    • 1 (Partition number)
    • Enter (First sector - default)
    • Enter (Last sector - default)
    • w (Write changes to disk and exit)

Example fdisk session:

$ sudo fdisk /dev/sdb

Welcome to fdisk (util-linux 2.37.4).
Changes will remain in memory only, until you decide to write them.
Be careful before using the write command.

Device does not contain a recognized partition table.
Created a new DOS disklabel with disk identifier 0x96fc7361.

Command (m for help): n
Partition type
   p   primary (0 primary, 0 extended, 4 free)
   e   extended (container for logical partitions)
Select (default p): p
Partition number (1-4, default 1): 1
First sector (2048-8388607, default 2048): <enter>
Last sector, +/-sectors or +/-size{K,M,G,T,P} (2048-8388607, default 8388607): <enter>

Created a new partition 1 of type 'Linux' and of size 4 GiB.

Command (m for help): w
The partition table has been altered.
Calling ioctl() to re-read partition table.
Syncing disks.

Step 4: Formatting the partition

Format the partition as an ext4 filesystem. The partition name is /dev/1, for example /dev/sdb1.

  • Run sudo mkfs.ext4 /dev/1, for example sudo mkfs.ext4 /dev/sdb1.

Example formatting output:

$ sudo mkfs.ext4 /dev/sdb1
mke2fs 1.46.5 (30-Dec-2021)
Discarding device blocks: done
Creating filesystem with 1048320 4k blocks and 262144 inodes
Filesystem UUID: 64394318-0746-444c-ab42-bbd8dd5b4806
Superblock backups stored on blocks:
    32768, 98304, 163840, 229376, 294912, 819200, 884736

Allocating group tables: done
Writing inode tables: done
Creating journal (16384 blocks): done
Writing superblocks and filesystem accounting information: done

Run the lsblk command to find the UUID of the partition. Note the UUID for the next steps.

$ lsblk -f | grep sdb1
└─sdb1 ext4        1.0                                   64394318-0746-444c-ab42-bbd8dd5b4806

Step 5: Mounting the filesystem

Run the following command to create the mount point directory.

$ sudo mkdir -p /usr/vice/cache

Append a line to the /etc/fstab file in the format using the UUID found in step 4.

$ echo "UUID=<your-uuid> /usr/vice/cache ext4 defaults,noatime 0 0" | sudo tee -a /etc/fstab

Example output.

$ echo "UUID=64394318-0746-444c-ab42-bbd8dd5b4806 /usr/vice/cache ext4 defaults,noatime 0 0" | sudo tee -a /etc/fstab

Reload the systemd services:

$ sudo systemctl daemon-reload

Finally, mount the partition.

$ sudo mount /usr/vice/cache

Verify the partition is mounted with the df command.

$ df -h | grep /usr/vice/cache

Example output:

$ df -h | grep /usr/vice/cache
/dev/sdb1                   3.9G   24K  3.7G   1% /usr/vice/cache

Proceed to Adding a disk for the OpenAFS file server.

Adding a disk for the OpenAFS file server

A dedicated partition is recommended for the file server volumes; however, for a quick test setup, this section is optional. If you choose to skip this section, proceed to Finalizing the virtual machine preparation

Adding and mounting the disk for the file server follows the same procedure as the disk for the cache manager, just the names of the device and mount point directory differ.

Step 1: Adding a hard disk

In this guide, we add a file server partition by adding a virtual disk in and then formatting and mounting the disk in the running VM.

Add a virtual hard disk to your VM.

  • Shutdown your VM.
  • In the settings for the VM, choose Storage and add another 8GiB hard drive. (A larger value may be used if you plan to store more data.)
  • Start your VM.

Step 2: Identifying the block device

Log in to your VM with SSH and run lsblk to find the block device name of the new disk. The TYPE will be disk and the device will not have any part children. It will probably be sdc, but it could have a different name. If the device has a different name, use that name in the following examples.

Example lsblk output after adding a disk:

$ lsblk
NAME               MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS
sda                  8:0    0   32G  0 disk
├─sda1               8:1    0    1G  0 part /boot
└─sda2               8:2    0   31G  0 part
  ├─almalinux-root 253:0    0 28.9G  0 lvm  /
  └─almalinux-swap 253:1    0    2G  0 lvm  [SWAP]
sdb                  8:16   0    4G  0 disk
└─sdb1               8:17   0    4G  0 part /usr/vice/cache
sdc                  8:32   0    8G  0 disk
sr0                 11:0    1    4M  0 rom
sr1                 11:1    1  1.9G  0 rom

Step 3: Partitioning the disk

Create a primary partition with fdisk.

Caution: The partitioning process is destructive. Be sure to specify the correct device name found in step 2 in the steps that follow.

  • Run sudo fdisk /dev/, for example, sudo fdisk /dev/sdc
  • Inside the interactive prompt, type these keys in order:
    • n (New partition)
    • p (Primary)
    • 1 (Partition number)
    • Enter (First sector - default)
    • Enter (Last sector - default)
    • w (Write changes to disk and exit)

Example fdisk session:

$ sudo fdisk /dev/sdc

Welcome to fdisk (util-linux 2.37.4).
Changes will remain in memory only, until you decide to write them.
Be careful before using the write command.

Device does not contain a recognized partition table.
Created a new DOS disklabel with disk identifier 0x9eec906e.

Command (m for help): n
Partition type
   p   primary (0 primary, 0 extended, 4 free)
   e   extended (container for logical partitions)
Select (default p): p
Partition number (1-4, default 1): 1
First sector (2048-16777215, default 2048):
Last sector, +/-sectors or +/-size{K,M,G,T,P} (2048-16777215, default 16777215):

Created a new partition 1 of type 'Linux' and of size 8 GiB.

Command (m for help): w
The partition table has been altered.
Calling ioctl() to re-read partition table.
Syncing disks.

Step 4: Formatting the partition

Format the partition as an ext4 filesystem. The partition name is /dev/1, for example /dev/sdc1.

  • Run sudo mkfs.ext4 /dev/1, for example sudo mkfs.ext4 /dev/sdc1.

Example formatting output:

$ sudo mkfs.ext4 /dev/sdc1
mke2fs 1.46.5 (30-Dec-2021)
Discarding device blocks: done
Creating filesystem with 2096896 4k blocks and 524288 inodes
Filesystem UUID: 15ec8d48-25e8-4b92-80b9-42b521f7f3b6
Superblock backups stored on blocks:
    32768, 98304, 163840, 229376, 294912, 819200, 884736, 1605632

Allocating group tables: done
Writing inode tables: done
Creating journal (16384 blocks): done
Writing superblocks and filesystem accounting information: done

Run the lsblk command to find the UUID of the partition. Note the UUID for the next steps.

$ lsblk -f | grep sdc1
└─sdb1 ext4        1.0                                   64394318-0746-444c-ab42-bbd8dd5b4806

Step 5: Mounting the filesystem

Run the following command to create the mount point directory.

$ sudo mkdir -p /vicepa

Append a line to the /etc/fstab file in the format using the UUID found in step 4.

$ echo "UUID=<your-uuid> /vicepa ext4 defaults,noatime 0 0" | sudo tee -a /etc/fstab

Example output.

$ echo "UUID=64394318-0746-444c-ab42-bbd8dd5b4806 /vicepa ext4 defaults,noatime 0 0" | sudo tee -a /etc/fstab

Reload the systemd services:

$ sudo systemctl daemon-reload

Finally, mount the partition.

$ sudo mount /vicepa

Verify the partition is mounted with the df command.

$ df -h | grep /vicepa

Example output:

$ df -h
/dev/sdc1                   3.9G   24K  3.7G   1% /vicepa

Step 6: Repeat for additional partitions

Repeat steps 1 to 5 for each additional partition desired. The second partition should be mounted as /vicepb, the third as /vicepc, and so on.

Proceed to Finalizing the virtual machine preparation.

Finalizing the virtual machine preparation

If you skipped Adding a disk for the OpenAFS file server, then add a "pseudo" partition for the file server. This will allow the OpenAFS file server to create volumes on the system without a dedicated partition.

$ test -d /vicepa || (sudo mkdir -p /vicepa && sudo touch /vicepa/AlwaysAttach)

Your virtual machine is now ready to install Kerberos and OpenAFS. You should take a virtual machine snapshot before proceeding. This will allow you to roll back to a fresh state if you need to install different versions of Kerberos and OpenAFS, or if you encounter issues.

  • Shutdown your virtual machine and wait for the shutdown to complete.
  • Open the **Snapshots'' tab
  • Select Take Snapshot
  • Enter a snapshot name, for example: "prepared"
  • Enter a snapshot description, for example: "Virtual machine prep completed"
  • Press Start to restart the VM.

Proceed to Installing Kerberos for authentication.

Installing Kerberos for authentication

This page describes how to configure Kerberos services on a virtual machine.

Installing the Kerberos server

Install both the server and client Kerberos packages to set up a Kerberos Key Distribution Center (KDC).

$ sudo dnf install krb5-server krb5-workstation

Creating the Kerberos realm

This section shows how to create a minimal Kerberos realm for OpenAFS development and testing.

Configuring the Kerberos configuration information

Edit /etc/krb5.conf to set the default realm name and the address of the Kerberos KDC and administration servers.

Change the configuration file to set the realm name and the server names.

$ sudo sed -i \
  -e 's/EXAMPLE.COM/EXAMPLE.TEST/' \
  -e 's/kerberos.example.com/openafs-server1.example.test/' \
  -e 's/example.com/example.test/' \
  -e '3,$s/^#//' \
  /etc/krb5.conf

Example /etc/krb5.conf file.

# To opt out of the system crypto-policies configuration of krb5, remove the
# symlink at /etc/krb5.conf.d/crypto-policies which will not be recreated.
includedir /etc/krb5.conf.d/

[logging]
default = FILE:/var/log/krb5libs.log
kdc = FILE:/var/log/krb5kdc.log
admin_server = FILE:/var/log/kadmind.log

[libdefaults]
dns_lookup_realm = false
ticket_lifetime = 168h
renew_lifetime = 7d
forwardable = true
rdns = false
pkinit_anchors = FILE:/etc/pki/tls/certs/ca-bundle.crt
spake_preauth_groups = edwards25519
dns_canonicalize_hostname = fallback
qualify_shortname = ""
default_realm = EXAMPLE.TEST
default_ccache_name = KEYRING:persistent:%{uid}

[realms]
EXAMPLE.TEST = {
    kdc = openafs-server1.example.test
    admin_server = openafs-server1.example.test
}

[domain_realm]
  .example.test = EXAMPLE.TEST
  example.test = EXAMPLE.TEST

Configuring the Kerberos KDC

Set the realm in the Kerberos KDC configuration file.

$ sudo sed -i 's/EXAMPLE.COM/EXAMPLE.TEST/' /var/kerberos/krb5kdc/kdc.conf

Example kdc.conf file:

[libdefaults]
# Allow RC4 HMAC-MD5 for session keys (see CVE-2022-37966)
#allow_rc4 = true

[kdcdefaults]
kdc_ports = 88
kdc_tcp_ports = 88
spake_preauth_kdc_challenge = edwards25519

[realms]
EXAMPLE.TEST = {
max_life = 168h 0m 0s
master_key_type = aes256-cts-hmac-sha384-192
acl_file = /var/kerberos/krb5kdc/kadm5.acl
dict_file = /usr/share/dict/words
default_principal_flags = +preauth
admin_keytab = /var/kerberos/krb5kdc/kadm5.keytab
supported_enctypes = aes256-cts-hmac-sha384-192:normal aes128-cts-hmac-sha256-128:normal aes256-cts-hmac-sha1-96:normal aes128-cts-hmac-sha1-96:normal camellia256-cts-cmac:normal camellia128-cts-cmac:normal arcfour-hmac-md5:normal
# Supported encryption types for FIPS mode:
#supported_enctypes = aes256-cts-hmac-sha384-192:normal aes128-cts-hmac-sha256-128:normal
}

Configuring the Kerberos administration access controls

Set the realm in the Kerberos admin server configuration file.

$ sudo sed -i 's/EXAMPLE.COM/EXAMPLE.TEST/' /var/kerberos/krb5kdc/kadm5.acl

Example kadm5.acl file.

*/admin@EXAMPLE.TEST    *

Creating the Kerberos database

Generate the Kerberos database with the kdb5_util create command. You will need to provide a master database password. This password is sensitive and should be kept secret.

$ sudo kdb5_util create -r EXAMPLE.TEST -s
Initializing database '/var/kerberos/krb5kdc/principal' for realm 'EXAMPLE.TEST',
master key name 'K/M@EXAMPLE.TEST'
You will be prompted for the database Master Password.
It is important that you NOT FORGET this password.
Enter KDC database master key: **********
Re-enter KDC database master key to verify: **********

Verify the kdb5_util create command created the Kerberos database files.

$ tree /var/kerberos
/var/kerberos/
 ├── krb5
 │   └── user
 └── krb5kdc
 ├── .k5.EXAMPLE.TEST
 ├── kadm5.acl
 ├── kdc.conf
 ├── principal
 ├── principal.kadm5
 ├── principal.kadm5.lock
 └── principal.ok

Starting the Kerberos services

Enable and start the Kerberos services with the command:

$ sudo systemctl enable --now krb5kdc kadmin

Verify that the services started successfully.

$ sudo systemctl status krb5kdc kadmin

Creating the admin principal

Run the kadmin.local program with sudo on the machine running the Kerberos KDC to create the root/admin principal. This principal will be used to administer the Kerberos realm and OpenAFS cell.

$ sudo kadmin.local addprinc root/admin@EXAMPLE.TEST
$ sudo kadmin.local listprincs

$ sudo kadmin.local addprinc root/admin
No policy specified for root/admin@EXAMPLE.TEST; defaulting to no policy
Enter password for principal "root/admin@EXAMPLE.TEST": **********
Re-enter password for principal "root/admin@EXAMPLE.TEST": **********
Principal "root/admin@EXAMPLE.TEST" created.

$ sudo kadmin.local listprincs
K/M@EXAMPLE.TEST
kadmin/admin@EXAMPLE.TEST
kadmin/changepw@EXAMPLE.TEST
krbtgt/EXAMPLE.TEST@EXAMPLE.TEST
root/admin@EXAMPLE.TEST

Verify you can acquire a ticket for the root/admin principal.

$ kinit root/admin@EXAMPLE.TEST
Password for root/admin@EXAMPLE.TEST:

$ klist
Ticket cache: KCM:1002
Default principal: root/admin@EXAMPLE.TEST
Valid starting     Expires            Service principal
02/20/26 15:32:17  02/27/26 15:32:14  krbtgt/EXAMPLE.TEST@EXAMPLE.TEST
    renew until 02/20/26 15:32:17

$ kdestroy

After this point, kadmin.local is no longer required. You can use kadmin for Kerberos administration on this machine and any new machines added to the realm.

Note: We run kadmin with sudo in this guide. This is to secure the logging messages generated by kadmin which is the default logging set up in modern RedHat-like distributions.

Taking a snapshot after Kerberos installation

You should create a virtual machine snapshot before proceeding. This will allow you to roll back in before installing different versions of OpenAFS.

Shutdown your virtual machine and take a snapshot in the Snapshots tab, and then press Start to restart the virtual machine.

Proceed to Installing OpenAFS

Installing OpenAFS

This guide presents three methods for installing OpenAFS, each suited for different testing scenarios:

Install from a package repository: This is the recommended method for testing official stable releases. This method uses standard package manager commands to install an OpenAFS release published by Sine Nomine Associates. To install from a package repository, proceed to Method 1: Installing from a package repository

Install from pre-built RPM files: This method is useful for testing release candidates or custom-built RPMs that are not yet in a repository. The packages are copied to the virtual machine and installed manually. To install from pre-built RPM files, proceed to Method 2: Installing from packages

Install from source code: This approach is best for developers who need to test unreleased features or fixes, work with development branches, or run programs that are part of the build but not included in the official packaging. It involves cloning the source code with Git, compiling, and installing it. To install from source code, proceed to Method 3: Installing from source code

Method 1: Installing from a package repository

You will be installing OpenAFS with the RPM binary packages provided by Sine Nomine Associates.

Configuring the package repository

The OpenAFS Packages for AlmaLinux page details how to add a package signing key and add the AlmaLinux OpenAFS repository, which can be followed to install the OpenAFS-Server package.

Import the package signing key and add the SNA OpenAFS repository for AlmaLinux.

$ sudo dnf install https://download.sinenomine.net/openafs/rpms/sna-openafs-release.rpm

Verify that the configuration has been updated on the system:

$ sudo dnf repolist
repo id         repo name
...
sna-openafs     Sine Nomine Associates: OpenAFS latest stable release for (AlmaLinux) 9 - x86_64

Installing the packages

Install the OpenAFS client and server packages.

There are two alternatives for the OpenAFS kernel module:

Pre-built kernel module (kmod): This is the simplest and fastest method. It uses a pre-compiled kernel module that matches a specific kernel version. To install with a pre-compiled kernel module, proceed to Alternative 1: Installing with a pre-built kernel module

Dynamic Kernel Module Support (DKMS): This method automatically rebuilds the OpenAFS kernel module whenever the system's kernel is updated. It is more flexible but requires the installation of the kernel development tools and can take longer to install. To install with DKMS, proceed to Alternative 2: Installing with DKMS managed kernel module

Alternative 1: Installing with a pre-built kernel module

Run the following command:

$ sudo dnf install openafs-server \
           openafs-client kmod-openafs \
           openafs-krb5 openafs-docs

Proceed to Configuring the first OpenAFS server.

Alternative 2: Installing with DKMS managed kernel module

Run the following command:

$ sudo dnf install openafs-server \
           openafs-client 
           dkms-openafs 
           kernel-devel-matched \
           openafs-krb5 openafs-docs

This will take several minutes while DKMS builds an OpenAFS kernel module for your running Linux kernel version.

Proceed to Configuring the first OpenAFS server.

Method 2: Installing from packages

This section shows how to install OpenAFS with a set of RPM binary packages. This guide assumes you already have a copy of the RPM files to be installed. See ?How to build OpenAFS RPMs for instructions on building RPMs.

Upload RPMs

Upload the RPM files to the VM into a temporary directory. Usually, you will have an archive file (.tar.gz) file containing a set of RPMs to be installed.

  • Create a destination directory on the VM, for example on your VM, run mkdir /tmp/openafs
  • Copy the RPMs to the destination directory, for example, on your local machine, run scp .tar.gz /tmp/openafs
  • Unpack the archive in the destination directory, for example, on your VM run cd /tmp/openafs && tar xvzf .tar.gz

If your archive includes a pre-built kernel module that matches your kernel version, install the kmod-openafs package, otherwise, install the dkms-openafs package.

In the following commands, replace with the version number in the RPM file names, and replace with the kernel version you are currently running.

To install the kmod package:

$ cd /tmp/openafs
$ sudo dnf install openafs-<version>-1.el9.<arch>.rpm \
           openafs-client-<version>-1.el9.<arch>.rpm \
           kmod-openafs-<version>-1.<kernel-version>.el9_1.<arch>.rpm \
           openafs-docs-<version>-1.el9.<arch>.rpm \
           openafs-krb5-<version>-1.el9.<arch>.rpm

To install the DKMS package:

$ cd /tmp/openafs
$ sudo dnf install openafs-<version>-1.el9.<arch>.rpm \
           openafs-client-<version>-1.el9.<arch>.rpm \
           dkms-openafs-<version>-1.el9.<arch>.rpm \
           openafs-docs-<version>-1.el9.<arch>.rpm \
           openafs-krb5-<version>-1.el9.<arch>.rpm

This will take several minutes while DKMS builds an OpenAFS kernel module for your running Linux kernel version.

Proceed to Configuring the first OpenAFS server

Method 3: Installing from source code

This section shows how to build and install OpenAFS from a source code checkout. This can be used to test development branches or release candidates.

Configuring EPEL repository

$ sudo dnf config-manager --set-enabled crb
$ sudo dnf install epel-release

See https://wiki.almalinux.org/repos/Extras.html for more information about EPEL.

Installing build requirements

Install the following packages.

$ sudo dnf install autoconf \
                   automake \
                   bison \
                   elfutils-devel \
                   flex \
                   fuse3-devel \
                   gcc \
                   git \
                   glibc-devel \
                   kernel-devel-matched \
                   krb5-devel \
                   libtool \
                   make \
                   ncurses-devel \
                   openssl-devel \
                   pam-devel \
                   perl-core \
                   perl-devel \
                   perl-ExtUtils-Embed \
                   swig

Checking out the source code

Clone an OpenAFS Git repo.

$ git clone git://scm.devlab.sinenomine.net/sna-openafs.git openafs && cd openafs

Check out the branch or tag name to be built. For example,

$ git checkout master

NOTE: The installation instructions that follow may depend on the version checked out. The following steps are for the current master branch.

Building the binaries

Run the autoconf wrapper script to generate the configure script and the Makefiles.

$ ./regen.sh

Run configure to set up the build tree.

$ ./configure \
      --prefix=/opt/openafs \
      --enable-checking \
      --enable-warnings \
      --disable-optimize \
      --disable-optimize-kernel \
      --disable-strip-binaries \
      --enable-pthreaded-bos \
      --enable-kernel-module \
      --with-linux-kernel-packaging

Run make to build the binaries. This will build the user-space programs and the kernel module.

$ make

Run the unit tests to verify the binaries:

$ make check

Installing the binaries

Install the binaries on your system.

$ sudo make install

The previous command will create some artifacts in your build tree owned by root. You can remove those with sudo make clean.

$ sudo make clean

Create a configuration file for the dynamic linker and run ldconfig to update the dynamic linker cache.

$ echo /opt/openafs/lib | sudo tee /etc/ld.so.conf.d/openafs.conf
$ sudo ldconfig

Verify the OpenAFS programs successfully load the shared libraries.

$ ldd /opt/openafs/sbin/vos
linux-vdso.so.1 (0x00007fff9fda1000)
libafshcrypto.so.2 => /opt/openafs/lib/libafshcrypto.so.2 (0x00007faeaa391000)
librokenafs.so.2 => /opt/openafs/lib/librokenafs.so.2 (0x00007faeaa38a000)
libc.so.6 => /lib64/libc.so.6 (0x00007faeaa000000)
/lib64/ld-linux-x86-64.so.2 (0x00007faeaa3c5000)

Verify the OpenAFS kernel module was installed and matches your current kernel version.

$ file /usr/lib/modules/$(uname -r)/extra/openafs/openafs.ko
/usr/lib/modules/5.14.0-611.35.1.el9_7.x86_64/extra/openafs/openafs.ko: ELF 64-bit LSB relocatable, x86-64, version 1 (SYSV), BuildID[sha1]=99430a2509a7412811b3b55316f4c427db8d2cf7, with debug_info, not stripped

Run the Linux depmod command to update the kernel module dependencies.

$ sudo /usr/sbin/depmod --all

Pre-configuring the client

The following steps are performed automatically when installing from RPM packages, and so must be done manually when installing from source.

Create the AFS filesystem mount point.

$ sudo mkdir -p /afs

Create the cache manager configuration directory and the cache manager configuration files. These files will be updated in a later section.

$ sudo mkdir -p /opt/openafs/etc/openafs
$ echo "/afs:/usr/vice/cache:100000" | sudo tee /opt/openafs/etc/openafs/cacheinfo
$ echo ">openafs.org # Cell name" | sudo tee /opt/openafs/etc/openafs/CellServDB
$ echo "openafs.org" | sudo tee /opt/openafs/etc/openafs/ThisCell

Creating compatibility symlinks

Run the following command to create the compatibility symlinks. This allows us to use the same paths as a system installed with RPMs.

$ sudo mkdir -p /usr/afs/bin /usr/vice/etc /opt/openafs/etc/openafs/server
$ sudo ln -s /opt/openafs/bin/* /usr/bin/
$ sudo ln -s /opt/openafs/sbin/* /usr/sbin/
$ sudo ln -s /opt/openafs/var/openafs/db /usr/afs/db
$ sudo ln -s /opt/openafs/var/openafs/logs /usr/afs/logs
$ sudo ln -s /opt/openafs/etc/openafs/server /usr/afs/etc
$ sudo ln -s /opt/openafs/sbin/bosserver /usr/afs/bin/
$ sudo ln -s /opt/openafs/libexec/openafs/* /usr/afs/bin/
$ sudo ln -s /opt/openafs/sbin/afsd /usr/vice/etc/
$ sudo ln -s /opt/openafs/etc/openafs/cacheinfo /usr/vice/etc/
$ sudo ln -s /opt/openafs/etc/openafs/CellServDB /usr/vice/etc/
$ sudo ln -s /opt/openafs/etc/openafs/ThisCell /usr/vice/etc/
$ sudo ln -s /opt/openafs/share/openafs/C /usr/vice/etc/

Configuring the systemd services

Install the systemd unit files to manage the OpenAFS client and server startup and shutdown. We can use the files provided in the contributed packaging in the source tree. These files use the compatibility paths created in the previous step.

Install the systemd unit files with the commands:

$ sudo install -m 644 src/packaging/RedHat/openafs-server.service /usr/lib/systemd/system/
$ sudo install -m 644 src/packaging/RedHat/openafs-client.service /usr/lib/systemd/system/
$ sudo install -m 755 src/packaging/RedHat/openafs-client-systemd-helper.sh /usr/vice/etc/
$ sudo install -m 644 src/packaging/RedHat/openafs.sysconfig /etc/sysconfig/openafs
$ sudo install -m 644 src/afsd/CellServDB /usr/vice/etc/CellServDB.dist
$ sudo touch /usr/vice/etc/CellServDB.local
$ sudo systemctl daemon-reload

Proceed to Configuring the first OpenAFS server

Configuring the first OpenAFS server

Creating the OpenAFS Service Principal

A Kerberos service key is required to secure the server. We create this key before starting the BosServer to avoid running the server without a security key and to avoid the use of the obsolete -noauth flag. The key value is sensitive and should be restricted to the root user on the server.

Run the Kerberos kadmin command to create the service principal with a random key value.

$ sudo kadmin -p root/admin@EXAMPLE.TEST addprinc -randkey afs/example.test@EXAMPLE.TEST

Run the Kerberos kadmin command to export service principal keys to a keytab file.

$ sudo kadmin -p root/admin@EXAMPLE.TEST ktadd -k /usr/afs/etc/rxkad.keytab \
          -e aes256-cts:normal,aes128-cts:normal afs/example.test@EXAMPLE.TEST

Verify that the keytab file was created:

$ sudo klist -e -k -t /usr/afs/etc/rxkad.keytab

Example output:

$ sudo klist -e -k -t /usr/afs/etc/rxkad.keytab
Keytab name: FILE:/usr/afs/etc/rxkad.keytab
KVNO Timestamp         Principal
---- ----------------- --------------------------------------------------------
   2 02/25/26 15:22:16 afs/example.test@EXAMPLE.TEST (aes256-cts-hmac-sha1-96)
   2 02/25/26 15:22:16 afs/example.test@EXAMPLE.TEST (aes128-cts-hmac-sha1-96)

Create minimal CellServDB and ThisCell files. These files must be present before running the OpenAFS akeyconvert command.

$ echo ">localcell #Cell name" | sudo tee /usr/afs/etc/CellServDB
$ echo "localcell" | sudo tee /usr/afs/etc/ThisCell

Run the OpenAFS akeyconvert command to import the keys into an OpenAFS specific format. This will create the KeyFile and KeyFileExt files from the data read from the rxkad.keytab file.

$ sudo akeyconvert -all

Example output:

$ sudo akeyconvert -all
Wrote 2 keys

Verify the KeyFile and KeyFileExt were created.

$ ls /usr/afs/etc

Example output:

$ ls /usr/afs/etc
CellServDB  KeyFile  KeyFileExt  rxkad.keytab  ThisCell

Remove the rxkad.keytab file. It is not needed after akeyconvert completes. Also remove the dummy CellServDB and ThisCell files. They will be recreated with default values when the BosServer is started in the next step.

$ sudo rm /usr/afs/etc/rxkad.keytab /usr/afs/etc/CellServDB /usr/afs/etc/ThisCell

Proceed to Start the OpenAFS BosServer.

Start the OpenAFS BosServer

Enable and start the openafs-server service to start the BosServer.

$ sudo systemctl enable --now openafs-server

Verify the service started.

$ sudo systemctl status openafs-server

Verify the bos command can contact the BosServer process.

$ sudo bos listhosts -server localhost -localauth

Example output:

$ sudo bos listhosts -server localhost -localauth
Cell name is localcell
    Host 1 is openafs-server1.example.test

Notice in the output above the cell name is localcell. This will be adjusted in the next steps.

Configuring the cell name

Use the bos command to set the cell name:

$ sudo bos setcellname -server localhost -name example.test -localauth

Verify the cell name has been changed.

$ sudo bos listhosts -server localhost -localauth
Cell name is example.test
    Host 1 is openafs-server1.example.test

Creating the database servers

Run the bos create command to create the Protection Database instance.

$ sudo bos create -server localhost \
                  -instance ptserver \
                  -type simple \
                  -cmd "/usr/afs/bin/ptserver" \
                  -localauth

Run the bos create command to create the Volume Location Database instance.

$ sudo bos create -server localhost \
                  -instance vlserver \
                  -type simple \
                  -cmd "/usr/afs/bin/vlserver" \
                  -localauth

Creating the file server

Run the bos create command to create the File Server instance.

$ sudo bos create -server localhost -instance dafs -type dafs \
                  -cmd "/usr/afs/bin/dafileserver -L" \
                  -cmd "/usr/afs/bin/davolserver" \
                  -cmd "/usr/afs/bin/salvageserver" \
                  -cmd "/usr/afs/bin/dasalvager" \
                  -localauth

Setting server restricted mode

Now that the BosServer is configured, we can place the BosServer in restricted mode. This is an optional but recommended step to improve the server security.

Run the bos command to set the restricted mode.

$ sudo bos setrestricted -server localhost -mode 1 -localauth
$ sudo bos getrestricted -server localhost -localauth
Restricted mode is on

Verifying the servers are running

Run bos status to verify the servers are running.

$ sudo bos status -server localhost -localauth
Instance ptserver, currently running normally.
Instance vlserver, currently running normally.
Instance dafs, currently running normally.
    Auxiliary status is: file server running.

Check the server logs in /usr/afs/logs and verify the servers started without errors. To see the last few lines of the logs, run the following command:

$ sudo bash -c "tail -n 5 /usr/afs/logs/*"
==> /usr/afs/logs/BosLog <==
Mon Feb 23 17:38:43 2026: WARNING: bosserver is not running in restricted mode.
Mon Feb 23 17:38:43 2026: WARNING: Superusers have unrestricted access to this host via bos.
Mon Feb 23 17:38:43 2026: WARNING: Use 'bos setrestricted' or restart with the -restricted option
Mon Feb 23 17:38:43 2026: WARNING: to enable restricted mode.
Mon Feb 23 17:38:43 2026: Listening on 0.0.0.0:7007

==> /usr/afs/logs/FileLog <==
Mon Feb 23 17:38:43 2026 Getting FileServer address...
Mon Feb 23 17:38:43 2026 FileServer openafs-server1.example.test has address 172.17.20.30 (0x1e1411ac or 0xac11141e in host byte order)
Mon Feb 23 17:38:43 2026 File Server started Mon Feb 23 17:38:43 2026
Mon Feb 23 17:38:43 2026 Set thread id 0xa for 'FsyncCheckLWP'
Mon Feb 23 17:38:43 2026 Set thread id 0xf for 'HostCheckLWP'

==> /usr/afs/logs/PtLog <==
Mon Feb 23 17:20:50 2026 Starting AFS ptserver 1.0 (/usr/afs/bin/ptserver)
Mon Feb 23 17:20:54 2026 urecovery_AbortAll: just aborted 0 read and 0 write transactions
Mon Feb 23 17:38:43 2026 ptserver binding rx to 0.0.0.0:7002
Mon Feb 23 17:38:43 2026 Using 172.17.20.30 as my primary address
Mon Feb 23 17:38:43 2026 Starting AFS ptserver 1.0 (/usr/afs/bin/ptserver)

==> /usr/afs/logs/SalsrvLog <==
Mon Feb 23 17:30:51 2026 @(#)OpenAFS 1.8.14 2007-12-12
Mon Feb 23 17:30:51 2026 Starting OpenAFS Online Salvage Server 2.4 (/usr/afs/bin/salvageserver)
Mon Feb 23 17:38:43 2026 @(#)OpenAFS 1.8.14 2007-12-12
Mon Feb 23 17:38:43 2026 Starting OpenAFS Online Salvage Server 2.4 (/usr/afs/bin/salvageserver)

==> /usr/afs/logs/VLLog <==
Mon Feb 23 17:30:51 2026    It will create a new entry in the VLDB.
Mon Feb 23 17:38:43 2026 vlserver binding rx to 0.0.0.0:7003
Mon Feb 23 17:38:43 2026 Using 172.17.20.30 as my primary address
Mon Feb 23 17:38:43 2026 Starting AFS vlserver 4 (/usr/afs/bin/vlserver)
Mon Feb 23 17:38:43 2026 @(#)OpenAFS 1.8.14 2007-12-12

==> /usr/afs/logs/VolserLog <==
Mon Feb 23 17:36:36 2026 Volserver shutdown complete
Mon Feb 23 17:38:46 2026 Volserver binding rx to 0.0.0.0:7005
Mon Feb 23 17:38:46 2026 Starting AFS Volserver 2.0 (/usr/afs/bin/davolserver)

Proceed to Configuring the OpenAFS client

Configuring the OpenAFS client

Configuring the client's local cell

Configure the client to locate the cell's database servers. Since the client and server are on the same machine in this guide, you can simply copy the CellServDB and ThisCell files created during the server set up.

Run the following commands:

$ sudo cp /usr/afs/etc/ThisCell /usr/vice/etc/ThisCell
$ sudo cp /usr/afs/etc/CellServDB /usr/vice/etc/CellServDB.local

Configuring the client disk cache

If you did not create a client cache partition in Adding a disk for the OpenAFS client cache, then proceed to Configuring the client startup options.

First, run the df command to determine the size of the client cache partition in 1K blocks.

$ df
Filesystem                 1K-blocks    Used Available Use% Mounted on
devtmpfs                        4096       0      4096   0% /dev
tmpfs                         873008       0    873008   0% /dev/shm
tmpfs                         349204    9320    339884   3% /run
/dev/mapper/almalinux-root  30289920 3390280  26899640  12% /
/dev/sda1                     983040  567280    415760  58% /boot
/dev/sdb1                    4045536      24   3819464   1% /usr/vice/cache
tmpfs                         174600       0    174600   0% /run/user/1002

Multiply the size by 0.9 and round to the nearest integer. This will be the maximum cache size in 1K blocks. For example:

$ python3 -c 'print(int(4045536 * 0.9))'
3640982

Update the cacheinfo file to set the maximum cache size. For example:

$ echo "/afs:/usr/vice/cache:3640982" | sudo tee /usr/vice/etc/cacheinfo
/afs:/usr/vice/cache:3640982

Proceed to Configuring the client startup options.

Configuring the client startup options

The client startup options are specified in the /etc/sysconfig/openafs file on RedHat-based systems.

Display the current startup values with:

$ cat /etc/sysconfig/openafs
# OpenAFS Client Configuration
AFSD_ARGS="-dynroot -fakestat -afsdb"

# OpenAFS Server Configuration
BOSSERVER_ARGS=

Verify the AFSD_ARGS include the -dynroot and -fakestat options. These are the defaults for modern systems and are assumed to be present in the steps that follow in this guide.

After any adjustments to the startup options, proceed to Starting the OpenAFS client.

Starting the OpenAFS client

Enable and start the openafs-client service with the commands:

$ sudo systemctl enable --now openafs-client

Verify the client service started.

$ sudo systemctl status openafs-client
● openafs-client.service - OpenAFS Client Service
 Loaded: loaded (/usr/lib/systemd/system/openafs-client.service; enabled; preset: disabled)
 Active: active (running) since Tue 2026-02-24 14:22:07 EST; 1h 12min ago
Process: 13788 ExecStart=/usr/vice/etc/openafs-client-systemd-helper.sh ExecStart (code=exited, status=0/SUCCESS)
  Tasks: 1 (limit: 10611)
 Memory: 804.0K (peak: 2.5M)
  CPU: 59ms
 CGroup: /system.slice/openafs-client.service
         └─13801 /usr/vice/etc/afsd -dynroot -fakestat -afsdb

Feb 24 14:22:07 openafs-server1.example.test systemd[1]: Starting OpenAFS Client Service...
Feb 24 14:22:07 openafs-server1.example.test openafs-client-systemd-helper.sh[13795]: insmod /lib/modules/5.14.0-611.34.1.el9_7.x86_64/extra/openafs/openafs.ko
Feb 24 14:22:07 openafs-server1.example.test openafs-client-systemd-helper.sh[13788]: afsd: All AFS daemons started.

Run lsmod to verify the OpenAFS kernel module is loaded.

$ sudo lsmod | grep openafs
openafs              3178496  2 # kmod loaded.

Run mount to verify that the AFS file system is mounted.

$ mount | grep afs
AFS on /afs type afs (rw,relatime)

Run the fs wscell command to verify the local cell name is correct.

$ fs wscell
This workstation belongs to cell 'example.test'

Proceed to Creating a new cell.

Creating a new cell

Now that we have a working server and client, we can create a new OpenAFS cell.

Log in to your VM with SSH to run the commands in this section.

Creating an administrator user

A user with administrator privileges is needed to create volumes and users.

This initial user must be created by running pts with the -localauth option on the server. The admin user will be called root.admin, which matches the root/admin Kerberos principal we created earlier.

Use the pts utility to add the root.admin OpenAFS user:

$ sudo pts createuser -name root.admin -localauth
User root.admin has id 1

Verify the root.admin was created.

$ sudo pts listentries -localauth
Name                          ID  Owner Creator
anonymous                  32766   -204    -204
root.admin                     1   -204    -204

Add the root.admin user to the system:administrators group.

$ sudo pts adduser -user root.admin -group system:administrators -localauth

Verify the root.admin user was added to the system:administrators group.

$ sudo pts membership -nameorid root.admin -localauth
Groups root.admin (id: 1) is a member of:
    system:administrators

Add the root.admin user to the superuser list on this server.

$ sudo bos adduser -server localhost -user root.admin -localauth

Verify the root.admin user is in the superuser list on this server.

$ sudo bos listusers -server localhost -localauth
SUsers are: root.admin

Proceed to Creating the cell root volumes.

Creating the cell root volumes

Run the vos create command with -localauth to create the root volumes. These volumes will be mounted after the client has been started.

$ sudo vos create -server openafs-server1 -partition a -name root.afs -localauth
Volume 536870912 created on partition /vicepa of openafs-server1
$ sudo vos create -server openafs-server1 -partition a -name root.cell -localauth
Volume 536870915 created on partition /vicepa of openafs-server1

Verify the root volumes are listed in the volume location database.

$ sudo vos listvldb -localauth
VLDB entries for all servers

root.afs
    RWrite: 536870912
    number of sites -> 1
    server openafs-server1.example.test partition /vicepa RW Site

root.cell
    RWrite: 536870915
    number of sites -> 1
    server openafs-server1.example.test partition /vicepa RW Site

Total entries: 2

Logging in as an administrator

Acquire a token for the administrator using kinit and aklog:

$ kinit root/admin@EXAMPLE.TEST
Password for root/admin@EXAMPLE.TEST: *********

$ klist
Ticket cache: KCM:1002
Default principal: root/admin@EXAMPLE.TEST

Valid starting     Expires            Service principal
02/25/26 16:10:03  02/26/26 16:10:01  krbtgt/EXAMPLE.TEST@EXAMPLE.TEST
     renew until 02/25/26 16:10:03

$ aklog -d
Authenticating to cell example.test (server openafs-server1.example.test).
Trying to authenticate to user's realm EXAMPLE.TEST.
Getting tickets: afs/example.test@EXAMPLE.TEST
Using Kerberos V5 ticket natively
About to resolve name root.admin to id in cell example.test.
Id 1
Setting tokens. root.admin @ example.test

Mounting the cell root volume

Note: The commands in this section require the client was started with the -dynroot option.

Create the /afs/example.test cell mount point:

$ fs mkmount -dir /afs/.:mount/example.test:root.afs/example.test -vol root.cell

Create the /afs/.example.test cell read-write mount point:

$ fs mkmount -dir /afs/.:mount/example.test:root.afs/.example.test -vol root.cell -rw

Setting the root directory access rights

Make the /afs and /afs/example.test root directories globally readable.

Note: The commands in this section require the client was started with the -dynroot option.

Set the /afs path access rights to world readable.

$ fs setacl -dir /afs/.:mount/example.test:root.afs/. -acl system:anyuser rl

Set the /afs/example.test and /afs/.example.test path access rights to world readable.

$ fs setacl -dir /afs/.:mount/example.test:root.cell/. -acl system:anyuser rl

Creating the read-only root volumes

Create a read-only clone of the root.cell volume.

$ vos addsite openafs-server1 a root.cell
Added replication site openafs-server1 /vicepa for volume root.cell

$ vos release root.cell -verbose
root.cell
RWrite: 536870915
number of sites -> 2
server openafs-server1.example.test partition /vicepa RW Site
server openafs-server1.example.test partition /vicepa RO Site  -- Not released
This is a complete release of volume 536870915
Creating a new permanent RO clone 536870916 ... done
Getting status of parent volume 536870915... done
Starting transaction on RO clone volume 536870916... done
Setting volume flags for volume 536870916... done
Ending transaction on volume 536870916... done
Replacing VLDB entry for root.cell... done
Starting transaction on cloned volume 536870916... done
updating VLDB ... done
Released volume root.cell successfully

Create a read-only clone of the root.afs volume.

$ vos addsite openafs-server1 a root.afs
Added replication site openafs-server1 /vicepa for volume root.afs

$ vos release root.afs -verbose
root.afs
RWrite: 536870912
number of sites -> 2
server openafs-server1.example.test partition /vicepa RW Site
server openafs-server1.example.test partition /vicepa RO Site  -- Not released
This is a complete release of volume 536870912
Creating a new permanent RO clone 536870913 ... done
Getting status of parent volume 536870912... done
Starting transaction on RO clone volume 536870913... done
Setting volume flags for volume 536870913... done
Ending transaction on volume 536870913... done
Replacing VLDB entry for root.afs... done
Starting transaction on cloned volume 536870913... done
updating VLDB ... done

Flush the volume to server mapping cache.

$ fs checkvolumes
All volumeID/name mappings checked.

Examine the root directories to verify the read-write and read-only volumes are mounted.

$ fs examine /afs/example.test/.
File /afs/example.test/. (536870916.1.1) contained in volume 536870916
Volume status for vid = 536870916 named root.cell.readonly
Current disk quota is 5000
Current blocks used are 2
The partition has 7717678 blocks available out of 7717804

$ fs examine /afs/.example.test/.
File /afs/.example.test/. (536870915.1.1) contained in volume 536870915
Volume status for vid = 536870915 named root.cell
Current disk quota is 5000
Current blocks used are 2
The partition has 7717678 blocks available out of 7717804

Taking a snapshot after configuring the cell

The OpenAFS cell is ready for use. You should take a virtual machine snapshot before proceeding. This will allow you to roll back to a fresh state if needed.

Shutdown your virtual machine and take a snapshot in the Snapshots tab, and then press Start to restart the virtual machine. You should create a virtual machine snapshot at this point.

Conclusion and next steps

You have successfully installed and configured a complete OpenAFS cell, including a Kerberos KDC, an OpenAFS database and file server, and an OpenAFS client. Your single-node development and testing environment is now ready for use.

From here, you can begin to explore the core features of OpenAFS. We recommend the following activities:

  • Create a new user and volume: Practice user and volume management by following the ?OpenAFS Tutorial.
  • Access your cell from another client: Try setting up another virtual machine as a client-only installation to learn how to access your new cell over the network.
  • Create a database server cluster: Add two additional machines and configure them to run the OpenAFS database servers by following the steps in Adding OpenAFS database servers

This environment provides a flexible sandbox for you to safely experiment with and learn about OpenAFS.

Adding OpenAFS database servers

In this section we will add two more database servers to the cell. The common practice is to have three database servers in a cell.

Creating additional virtual machines for the database servers

Follow the steps in Preparing a VirtualBox virtual machine to create two additional virtual machines named openafs-server2 and openafs-server3.

Configuring hostname resolution for the cluster

Log in to the primary VM (openafs-server1) and add the new hosts to the /etc/hosts file and then copy that file to the new machines.

Specify the IP address shown in the Summary tab for each new VM.

$ echo "<openafs-server2-ip-address> openafs-server2.example.test openafs-server2" | sudo tee -a /etc/hosts
$ echo "<openafs-server3-ip-address> openafs-server3.example.test openafs-server3" | sudo tee -a /etc/hosts

Example /etc/hosts

127.0.0.1 localhost.localdomain localhost
127.0.0.1 localhost4.localdomain4 localhost4

::1 localhost.localdomain localhost
::1 localhost6.localdomain6 localhost6

172.17.20.209 openafs-server1.example.test openafs-server1
172.17.20.211 openafs-server2.example.test openafs-server2
172.17.20.212 openafs-server3.example.test openafs-server3

Verify you can connect to the other servers. This also will add the SSH hosts keys to your known_hosts on openafs-server1.

Run this command on openafs-server1.

$ ssh openafs-server1 uname -a
$ ssh openafs-server2 uname -a
$ ssh openafs-server3 uname -a

Distribute the /etc/hosts file to the other servers.

$ cat /etc/hosts | ssh openafs-server2 "sudo tee /etc/hosts"
$ cat /etc/hosts | ssh openafs-server3 "sudo tee /etc/hosts"

Prechecking the cluster health

The database servers will communicate with each other to establish a quorum and elect a sync site. For this process to be successful, it is critical the following are set up correctly. In this section we check the following requirements before proceeding.

  • Each machine must be able to reach the other machines over the network.
  • The clocks on each server must be in sync.
  • The hostnames must be correct on each machine.
  • The hostnames to IP address resolution must be correct on each machine.

The commands in this section should be run from your local machine. They will connect to each VM to perform the checks.

Checking connectivity

$ echo "====> openafs-server1"
$ ssh openafs-server1 "ping -c 4 openafs-server1.example.test"
$ ssh openafs-server1 "ping -c 4 openafs-server2.example.test"
$ ssh openafs-server1 "ping -c 4 openafs-server3.example.test"
$ echo "====> openafs-server2"
$ ssh openafs-server2 "ping -c 4 openafs-server1.example.test"
$ ssh openafs-server2 "ping -c 4 openafs-server2.example.test"
$ ssh openafs-server2 "ping -c 4 openafs-server3.example.test"
$ echo "====> openafs-server3"
$ ssh openafs-server3 "ping -c 4 openafs-server1.example.test"
$ ssh openafs-server3 "ping -c 4 openafs-server2.example.test"
$ ssh openafs-server3 "ping -c 4 openafs-server3.example.test"

Checking clock synchronization

The clocks must be in sync within a few seconds.

$ ssh openafs-server1 date >&2 | ssh openafs-server2 date >&2 | ssh openafs-server3 date >&2
Thu Mar 12 13:38:11 EDT 2026
Thu Mar 12 13:38:11 EDT 2026
Thu Mar 12 13:38:11 EDT 2026

Checking hostnames resolution

$ echo "===> openafs-server1"
$ ssh openafs-server1 "getent ahosts openafs-server1 openafs-server1.example.test"
$ ssh openafs-server1 "getent ahosts openafs-server2 openafs-server2.example.test"
$ ssh openafs-server1 "getent ahosts openafs-server3 openafs-server3.example.test"
$ echo "===> openafs-server2"
$ ssh openafs-server2 "getent ahosts openafs-server1 openafs-server1.example.test"
$ ssh openafs-server2 "getent ahosts openafs-server2 openafs-server2.example.test"
$ ssh openafs-server2 "getent ahosts openafs-server3 openafs-server3.example.test"
$ echo "===> openafs-server3"
$ ssh openafs-server3 "getent ahosts openafs-server1 openafs-server1.example.test"
$ ssh openafs-server3 "getent ahosts openafs-server2 openafs-server2.example.test"
$ ssh openafs-server3 "getent ahosts openafs-server3 openafs-server3.example.test"

Installing OpenAFS on the database servers

Follow the steps in Installing OpenAFS on openafs-server2 and openafs-server3

Configuring the database servers

Log in to the primary VM (openafs-server1) with SSH. All of the following steps should be run on openafs-server1.

Acquire a token for the root.admin administrator user.

$ kinit root/admin@EXAMPLE.TEST && aklog -d

Add the new servers to our cell configuration.

$ bos addhost -server openafs-server1 -host openafs-server2.example.test $ bos addhost -server openafs-server1 -host openafs-server3.example.test $ cat /usr/afs/etc/CellServDB

example.test #Cell name 172.17.20.222 #openafs-server1.example.test 172.17.20.223 #openafs-server2.example.test 172.17.20.224 #openafs-server3.example.test

Restart the openafs-server service to ensure the server reloads the CellServDB and check the BosServer log to verify the BosServer started.

$ sudo systemctl restart openafs-server
$ sudo cat /usr/afs/logs/BosLog

Verify you can connect to the other machines with SSH.

$ ssh openafs-server2 uname -a
$ ssh openafs-server3 uname -a

Verify 'tar' utility is available on the system.

$ command -v tar >/dev/null 2>&1 || sudo dnf install tar -y

Securely distribute the cell configuration files to the other servers.

$ sudo tar -cpf - -C /usr/afs/etc . | ssh openafs-server2 "sudo tar -xvpf - -C /usr/afs/etc"
$ sudo tar -cpf - -C /usr/afs/etc . | ssh openafs-server3 "sudo tar -xvpf - -C /usr/afs/etc"

Verify the contents of the ThisCell files match on each machine.

$ echo "===> openafs-server1"
$ ssh openafs-server1 "cat /usr/afs/etc/ThisCell; echo"
$ echo "===> openafs-server2"
$ ssh openafs-server2 "cat /usr/afs/etc/ThisCell; echo"
$ echo "===> openafs-server3"
$ ssh openafs-server3 "cat /usr/afs/etc/ThisCell; echo"

Verify the contents of the CellServDB files match on each machine.

$ echo "===> openafs-server1"
$ ssh openafs-server1 "cat /usr/afs/etc/CellServDB"
$ echo "===> openafs-server2"
$ ssh openafs-server2 "cat /usr/afs/etc/CellServDB"
$ echo "===> openafs-server3"
$ ssh openafs-server3 "cat /usr/afs/etc/CellServDB"

If these files do not match Do Not Proceed. This must be corrected before continuing.

If they do match, proceed to Starting the BosServer on the database servers.

Starting the BosServer on the database servers

Enable and start the BosServer on openafs-server2 and openafs-server3 using systemctl.

$ ssh openafs-server2 "sudo systemctl enable --now openafs-server"
$ ssh openafs-server3 "sudo systemctl enable --now openafs-server"

Create the additional database instances

Create the database instances on openafs-server2.

$ bos create -server openafs-server2 \
             -instance ptserver \
             -type simple \
             -cmd "/usr/afs/bin/ptserver"

$ bos create -server openafs-server2 \
             -instance vlserver \
             -type simple \
             -cmd "/usr/afs/bin/vlserver"

Verify the database servers started.

$ bos status -server openafs-server2
$ bos getlog -server openafs-server2 -file BosLog

Create the database instances on openafs-server3.

$ bos create -server openafs-server3 \
             -instance ptserver \
             -type simple \
             -cmd "/usr/afs/bin/ptserver"

$ bos create -server openafs-server3 \
             -instance vlserver \
             -type simple \
             -cmd "/usr/afs/bin/vlserver"

Verify the database servers started.

$ bos status -server openafs-server3
Instance ptserver, currently running normally.
Instance vlserver, currently running normally.

$ bos getlog -server openafs-server3 -file BosLog
Fetching log file 'BosLog'...
Thu Mar 12 13:55:20 2026: Server directory access is okay
Thu Mar 12 13:55:20 2026: Core limits now -1 -1
Thu Mar 12 13:55:20 2026: WARNING: bosserver is not running in restricted mode.
Thu Mar 12 13:55:20 2026: WARNING: Superusers have unrestricted access to this host via bos.
Thu Mar 12 13:55:20 2026: WARNING: Use 'bos setrestricted' or restart with the -restricted option
Thu Mar 12 13:55:20 2026: WARNING: to enable restricted mode.
Thu Mar 12 13:55:20 2026: Listening on 0.0.0.0:7007
Thu Mar 12 14:00:07 2026: ptserver started pid 28396: /usr/afs/bin/ptserver
Thu Mar 12 14:00:07 2026: vlserver started pid 28398: /usr/afs/bin/vlserver

If the BosServer logs show the processes have not successfully started, stop the openafs-service on all the servers and recheck the cell configuration files and the steps in Prechecking the cluster health and then restart the openafs-service on each machine.

The election process will take at least 75 seconds. During that time you can check the logs to watch the progress and check for error messages.

Check the Protection Database logs on each server for error messages.

$ echo "===> openafs-server1"
$ bos getlog -server openafs-server1 -file PtLog | tail
$ echo "===> openafs-server2"
$ bos getlog -server openafs-server2 -file PtLog | tail
$ echo "===> openafs-server3"
$ bos getlog -server openafs-server3 -file PtLog | tail

Check the Volume Location Database logs on each server for error messages.

$ echo "===> openafs-server1"
$ bos getlog -server openafs-server1 -file VLLog | tail
$ echo "===> openafs-server2"
$ bos getlog -server openafs-server2 -file VLLog | tail
$ echo "===> openafs-server3"
$ bos getlog -server openafs-server3 -file VLLog | tail

Check the Protection Database quorum with udebug.

$ echo "===> openafs-server1"
$ udebug -server openafs-server1 -port 7002
$ echo "===> openafs-server2"
$ udebug -server openafs-server2 -port 7002
$ echo "===> openafs-server3"
$ udebug -server openafs-server3 -port 7002

Check the Volume Location Database quorum with udebug.

$ echo "===> openafs-server1"
$ udebug -server openafs-server1 -port 7003
$ echo "===> openafs-server2"
$ udebug -server openafs-server2 -port 7003
$ echo "===> openafs-server3"
$ udebug -server openafs-server3 -port 7003

Now that the BosServer has been configured to run the Database Servers it is recommended to place the BosServer on openafs-server2 and openafs-server3 into restricted mode. See Setting server restricted mode for details.

Distributing the cell configuration

The example.test cell is now running with a redundant, three-server database configuration. This setup ensures higher availability for your cell's metadata, however clients need to be informed of the new database servers. In a production environment, it is recommended to add SRV records to DNS to publish the addresses of the OpenAFS database servers.

In this test environment, we can update the /usr/afs/etc/CellServDB.local file on each client and restart the client.

Note: A restart of the client can be avoided by using the fs newcell command to update the cell configuration in memory. See the fs_newcell man page for more information.

On openafs-server1, update the CellServDB.local with,

$ sudo cp /usr/afs/etc/CellServDB /usr/vice/etc/CellServDB.local

And then restart the openafs-client service.

$ sudo systemctl restart openafs-client

Adding OpenAFS file servers

In this section we will add a file server machine to the cell. Adding file servers is straightforward.

Creating an additional virtual machine for a file server

Follow the steps in Preparing a VirtualBox virtual machine to create an additional virtual machines named openafs-server4.

The file server will require one or more vice partitions mounted at /vicepa, /vicepb, and so on. If you do not have a physical partition available, you can create a "pseudo" partition for testing with:

$ test -d /vicepa || (sudo mkdir -p /vicepa && sudo touch /vicepa/AlwaysAttach)

Installing OpenAFS on the file server

Follow the steps in Installing OpenAFS on openafs-server4.

Deploying the cell configuration to the file server

Log in to the primary VM (openafs-server1) with SSH. All of the following steps should be run on openafs-server1.

Acquire a token for the root.admin administrator user.

$ kinit root/admin@EXAMPLE.TEST && aklog -d

Follow the steps in Configuring hostname resolution for the cluster to add openafs-server4 ip address to /etc/hosts and distribute the hosts file to all the openafs servers.

Securely distribute the cell configuration files to the new server.

$ sudo tar -cpf - -C /usr/afs/etc . | ssh openafs-server4 "sudo tar -xvpf - -C /usr/afs/etc"

Starting the file server

Enable and start the BosServer.

$ ssh openafs-server4 "sudo systemctl enable --now openafs-server"

Verify the openafs-service is running.

$ ssh openafs-server4 "sudo systemctl status openafs-server"

Verify the bosserver started without errors.

$ bos getlog -server openafs-server4 -file BosLog

Run the bos create command to create the file server instance.

$ bos create \
   -server openafs-server4 \
   -instance dafs \
   -type dafs \
   -cmd "/usr/afs/bin/dafileserver -L" \
   -cmd "/usr/afs/bin/davolserver" \
   -cmd "/usr/afs/bin/salvageserver" \
   -cmd "/usr/afs/bin/dasalvager"

Verify the bosserver started the file server without errors.

$ bos getlog -server openafs-server4 -file BosLog

Verify the dafs instance is running.

$ bos status -server openafs-server4

Check the file server log to verify it started without errors.

$ bos getlog -server openafs-server4 -file FileLog

Now that the BosServer has been configured to run the File Server, it is recommended to place the BosServer into restricted mode. See Setting server restricted mode for details.

Adding OpenAFS clients

Creating an additional virtual machine for a client

Follow the steps in Preparing a VirtualBox virtual machine to create an additional virtual machine named openafs-server5.

Installing OpenAFS on the additional client

Log into openafs-server5 with SSH.

Follow the steps in Installing OpenAFS on openafs-server5. If installing with RPM package files, the openafs-server package may be skipped since this machine will only be running the client.

Configuring the additional client

Log into openafs-server5 with SSH.

If you created a client cache partition on the new machine, see the instructions in Configuring the client disk cache to configure the cache size in the cacheinfo file.

Set the local cell name.

$ echo "example.test" | sudo tee /usr/vice/etc/ThisCell

Follow the steps in Configuring hostname resolution for the cluster to add openafs-server5 ip address to /etc/hosts and distribute the hosts file to all the openafs servers.

Copy the CellServDB.local from openafs-server1 to openafs-server5. Run this command on openafs-server5.

$ ssh openafs-server1 "cat /usr/vice/etc/CellServDB.local" | sudo tee /usr/vice/etc/CellServDB.local

Starting the OpenAFS client on the additional machine

Log into openafs-server5 with SSH.

Enable and start the openafs-client service with the commands:

$ sudo systemctl enable --now openafs-client

Verify the client service started.

$ sudo systemctl status openafs-client

Run the fs wscell command to verify the local cell name is correct.

$ fs wscell

Run mount to verify that the AFS file system is mounted.

$ mount | grep afs
AFS on /afs type afs (rw,relatime)