Usage

Installation Methods

OpenAFS may be installed and updated with prebuilt packages or built from source on the remote nodes. The following installation methods are supported:

  • managed - Install with the distro’s package manager (e.g., yum, apt).

  • packages - Install prebuilt packages (e.g. rpm, dpkg).

  • bdist - Install a binary distribution with Transarc-style paths.

  • source - Install from source code.

  • none - Skip installation tasks.

Different installation methods may be used on each remote node. However, when installing a client and server on the same node, the same installation method must be specified for the client and server roles, that is, you cannot mix installation methods on a given node.

The installation method is stored id the /etc/ansible/facts.d/openafs.fact json file on the remote node. This file must be changed if you want to change the installation method after OpenAFS has already been installed.

Inventory

Provide an Ansible inventory file for your host configuration. Ansible supports ini and yaml inventory files.

The OpenAFS ansible roles and example playbooks use the following group name conventions:

afs_kdcs

The Kerberos KDC server.

Currently, only one KDC is supported. Additional KDCs can be deployed with custom playbooks or community supported roles.

afs_databases

The OpenAFS database servers hosts.

afs_fileservers

The OpenAFS fileserver hosts.

afs_clients

The OpenAFS clients hosts.

afs_admin_client

The OpenAFS client host used for initial cell configuration.

Note that a given host may be a member of more than one group. For example, a given host can be in the afs_databases, afs_fileservers, and the afs_clients groups.

Example Inventory

[afs_kdcs]
kdc

[afs_databases]
db1
db2
db3

[afs_fileservers]
fs01
fs02
fs03
fs04

[afs_clients]
client[01:20]

[afs_admin_client]
client01

[afs_cell:children]
afs_databases
afs_fileservers
afs_clients

[afs_cell:vars]
afs_realm = EXAMPLE.COM
afs_cell = example.com

[afs_clients:vars]
afs_kdc_servers = kdc
afs_kadmin_server = kdc
afs_module_install_method = dkms

Cell Configuration (CellServDB)

The OpenAFS cell configuration (CellServDB file) is provided as an inventory variable or an external yaml file (with the same structure as the inventory variable.) The cell configuration contains the list of database server IPv4 addresses.

To specify the cell configuration with an inventory variable, add the afs_csdb dictionary to your inventory for all of the hosts in your cell. If your inventory is in ini format, then provide a afs_cell.yaml file in the Ansible group_vars directory.

# Contents of `group_vars/afs_cell.yaml`
afs_csdb:
  cell: example.com
  desc: My Example Cell
  hosts:
    - ip: 192.168.122.219
      name: afs02
      clone: no
    - ip: 192.168.122.154
      name: afs03
      clone: no
    - ip: 192.168.122.195
      name: afs04
      clone: no

A csdb.yaml file can be generated from a playbook and then saved for later use. This can be especially useful when creating short lived test cells from newly created virtual machine clusters.

# Retrieve the addresses of the database servers and generate
# a cell configuration yaml file (csdb.yaml)
- name: Create CellServDB
  hosts: afs_databases
  tasks:
    - include_role:
        name: openafs_contrib.openafs.openafs_common
        tasks_from: generate_csdb
      when: afs_csdb is undefined

Running playbooks

Create a set of Ansible playbooks for your environment to deploy the OpenAFS servers and clients. See the example playbooks in the playbooks directory as a starting point.

Run the playbooks with ansible-playbook [options] <playbooks>.

Import the openafs_client role to install and configure client machines, and import the openafs_server role to install and configure fileserver and database server machines. A single machine may have both a client and server installed on it, but with the limitation the client and server versions must match.

Use the openafs_volume module on a client machine to create and mount the OpenAFS root.afs and root.cell volumes. This module may also be used to create additional volumes.

Use the openafs_user module on a client to create initial users.

See the Ansible documentation for more information on running ansible-playbook.