# Ansible Roles for OpenAFS

The [[`ansible-openafs`|https://github.com/openafs-contrib/ansible-openafs] is
a collection of Ansible roles and playbooks to deploy OpenAFS and clients with
[[Ansible|https://www.ansible.com/]].  The roles can be used to deploy a new
Kerberos realm, install the servers, setup the initial cell, and install
OpenAFS clients in the cell.  The Ansible roles also are able to build OpenAFS
from source for testing and development.


## Platforms Supported

* OpenAFS 1.6.5+
* Ansible 2.5+
* OS Versions
    * RHEL7/CentOS7
    * Ubuntu 18.x

## Kerberos Client Role

Name: `openafs_krbclient`

Install and configure the Kerberos workstation packages.

### Role Variables

    afs_realm: EXAMPLE.COM

The Kerberos realm name.

## Kerberos Server Role

Name: `openafs_krbserver`

Install and configure the Kerberos master KDC on single host, create the
Kerberos database, the administrator's principal, and the OpenAFS service key.

### Role Variables

    afs_realm: EXAMPLE.COM

The Kerberos realm name.

    afs_kerberos_master_password: (random by default)

The secret Kerberos database master password. The password is a random string
by default. It should be set on the command line (-e) or in a group variable,
preferably encrypted with `ansible-vault`.

    afs_admin_principal: admin
    afs_admin_password: (undefined by default)

A administrator principal to be created by this role.
The password is not defined by default and must be set on the command line
(-e) or in a group variable, preferably encrypted with `ansible-vault`.

## OpenAFS Cell Role

Name: `openafs_cell`

Setup the top level volumes in the cell. This role is to be run on a single
client host.

### Role Variables

    afs_cell: example.com
    afs_realm: EXAMPLE.COM

Cell and realm names.

    afs_admin_principal: admin
    afs_admin_password: (not defined)
    afs_user_password:  (not defined)


A administrator credentials to create the regular users listed in `afs_users`
and the initial Kerberos password for those users.  The passwords are not
defined by default and must be set on the command line (-e) or in group
variables, preferably encrypted with `ansible-vault`.

    afs_kdc:

The Kerberos KDC hostname. This host must be a member of the `afs_kdcs` host group.

    afs_root_server:
    afs_root_part: a

The primary fileserver hostname and AFS fileserver partition id. The cell's
top-level volumes will be created on this fileserver partition.

    afs_volumes:

An optional list of top level volumes to be created and mounted in the cell.
This should be defined as a list of dictionaries of `name=<volume name>,
mtpt=<mount path>`, where `<mount path>` is relative to `/afs/<cell name>/`
and defaults to the `<volume-name>`.

    afs_users:

An optional list of AFS users to be created in the new cell. This should be
defined as list of dictionaries of `name=<username>`.

    afs_groups:

An optional list of AFS groups to be created in the new cell. This should be
defined as a list of dictionaries of `name=<group name>, members=<list of
usernames>`.

Example initial cell configuration:

    # contents of inventory/example.com/group_vars/all/cell.yaml
    # Initial top level volumes.
    afs_volumes:
      - name: test
        mtpt: test
    
    # Initial AFS users.
    afs_users:
      - name: user1
      - name: user2
      - name: user3
    
    # Initial AFS groups
    afs_groups:
      - name: group1
        members:
          - user1
          - user2
      - name: group2
        members:
          - user2
          - user3

## OpenAFS Client Role

Name: `openafs_client`

Install and configure the OpenAFS client packages.  Optionally, build and install from
source code.

### Role Variables

    afs_cell: example.com
    afs_desc: Example
    afs_realm:  EXAMPLE.COM

The Kerberos realm name, AFS cell name, and the cell organizational
description.

    # One of: 'package-manager', 'rsync'
    afs_client_install_method: package-manager

The method used to install the OpenAFS client binaries. Values are:

* `package-manager` :  Install client packages and a pre-built kernel module
                with  the system package manager (e.g., `yum`, `apt`).
* `rsync`:      Copy the binary files. Build the client binaries and kernel module from source
                code if needed. Installs development packages in order to
                build the OpenAFS client binaries and kernel module, if needed.

    afs_openafs_client_repourl:

The URL of a yum repo containing OpenAFS client packages for the `package-manager` install method.

    afs_client_install_dkms: no

Install kernel module with DKMS for the `package-manager` install method.

    afs_client_build_force: no
    afs_client_build_builddir: "/usr/local/src/openafs_client"
    afs_client_build_destdir: "/tmp/openafs_client"
    afs_client_build_fetch_method: "git"
    afs_client_build_git_repo: "https://github.com/openafs/openafs"
    afs_client_build_git_ref: "master"

Build options for `rsync` install method.

    afs_cacheinfo_mount: /afs
    afs_cacheinfo_cache: /usr/vice/cache
    afs_cacheinfo_size: 50000

The OpenAFS cache configuration parameters; the AFS filesystem mount point, the
cache partition, and the cache manager cache size.  The cache partition should
already exist.

    afs_afsd_opts: -dynroot -fakestat -afsdb

The OpenAFS cache manager startup options.

## OpenAFS Server Role

Name: `openafs_server`

Install and configure the OpenAFS server packages. This role installs both the
fileserver and the database servers, which can be installed on the same hosts
or different hosts.  Optionally, build and install from source code.

This role enables OpenAFS servers to operate correctly with selinux set to
enforcing mode.

### Role Variables

    afs_cell: example.com
    afs_desc: Example
    afs_realm:  EXAMPLE.COM

The Kerberos realm name, AFS cell name, and the cell organizational
description.

    afs_admin_principal:
    afs_admin_password: (undefined by default)

A administrator principal and password to be used to set the AFS service key.
The password is not defined by default and must be set on the command line (-e)
or in a group variable, preferably encrypted with `ansible-vault`.

    afs_server_install_method: package-manager

The method used to install the OpenAFS server binaries. Values are:

* `package-manager`:  Install OpenAFS server packages with yum. (default)
* `rsync`: Copy binary files. Build binares from source code if needed.

    afs_openafs_server_repourl:

The URL of a yum repo containing OpenAFS server packages.

    afs_server_build_force: no
    afs_server_build_builddir: "/usr/local/src/openafs_server"
    afs_server_build_destdir: "/tmp/openafs_server"
    afs_server_build_fetch_method: "git"
    afs_server_build_git_repo: "https://github.com/openafs/openafs"
    afs_server_build_git_ref: "master"

Build from source options for the 'rsync' install method.

    afs_selinux_mode: enforcing

The selinux enforcing mode. May be one of `enforcing`, `passive`, or
`disabled`.  When `enforcing`, update the required selinux bits to allow the
servers to properly operate.

    afs_fileserver_type: dafs

Determines which fileserver variation is setup when the host is a member of the
`afs_fileservers` group.  May be the legacy OpenAFS fileserver (`fs`), or the
modern demand-attach fileserver (`dafs`). The demand-attach (`dafs`) variant is
the default.

    afs_bosserver_opts:
    afs_ptserver_opts:
    afs_vlserver_opts:
    afs_dafileserver_opts: -L
    afs_davolserver_opts:
    afs_salvageserver_opts:
    afs_dasalvager_opts:
    afs_fileserver_opts:
    afs_volserver_opts:
    afs_salvager_opts:

The OpenAFS server command line options. See the OpenAFS man pages for the
server processes.

    afs_kdc:

The Kerberos KDC hostname.

    afs_root_server:
    afs_root_part: a

The primary fileserver hostname and AFS fileserver partition id. The cell root
volume (root.afs, root.cell) will be created on this fileserver partition.

## OpenAFS Devel Role

Name: `openafs_devel`

Install development packages and provide tasks to build an OpenAFS
binary distribution from source code.

### Role Variables

    afs_devel_build_server: yes

Build the server components.

    afs_devel_build_client: yes

Build the client components, including the OpenAFS kernel module.

    afs_devel_builddir: "/usr/local/src/openafs"

The path of the directory to perform the build.

    afs_devel_destdir: "/tmp/openafs"

The path of the directory to place the generated binary distribution.

    afs_devel_fetch_method: "git"

The method to obtain the source code. One of 'git', or 'none' (or 'skip')
Specify 'none' (or 'skip') to skip this stage.

    afs_devel_git_repo: "https://github.com/openafs/openafs"

The git url to be used to checkout the source code.

    afs_devel_git_ref: "master"

The git branch or tag to be checked out.

## OpenAFS Test Suite Role

Name: `openafs_robotest`

Install and configure a set of Robot Framework test suites for OpenAFS.

### Role Variables

TODO

## License

BSD

## Author Information

Copyright (c) 2018-2019 Sine Nomine Associates


[1]: https://www.openafs.org/
[2]: https://web.mit.edu/kerberos/