1 # Ansible Roles for OpenAFS
3 The [[`ansible-openafs`|https://github.com/openafs-contrib/ansible-openafs] is
4 a collection of Ansible roles and playbooks to deploy OpenAFS and clients with
5 [[Ansible|https://www.ansible.com/]]. The roles can be used to deploy a new
6 Kerberos realm, install the servers, setup the initial cell, and install
7 OpenAFS clients in the cell. The Ansible roles also are able to build OpenAFS
8 from source for testing and development.
11 ## Platforms Supported
19 ## Kerberos Client Role
21 Name: `openafs_krbclient`
23 Install and configure the Kerberos workstation packages.
27 afs_realm: EXAMPLE.COM
29 The Kerberos realm name.
31 ## Kerberos Server Role
33 Name: `openafs_krbserver`
35 Install and configure the Kerberos master KDC on single host, create the
36 Kerberos database, the administrator's principal, and the OpenAFS service key.
40 afs_realm: EXAMPLE.COM
42 The Kerberos realm name.
44 afs_kerberos_master_password: (random by default)
46 The secret Kerberos database master password. The password is a random string
47 by default. It should be set on the command line (-e) or in a group variable,
48 preferably encrypted with `ansible-vault`.
50 afs_admin_principal: admin
51 afs_admin_password: (undefined by default)
53 A administrator principal to be created by this role.
54 The password is not defined by default and must be set on the command line
55 (-e) or in a group variable, preferably encrypted with `ansible-vault`.
61 Setup the top level volumes in the cell. This role is to be run on a single
67 afs_realm: EXAMPLE.COM
71 afs_admin_principal: admin
72 afs_admin_password: (not defined)
73 afs_user_password: (not defined)
76 A administrator credentials to create the regular users listed in `afs_users`
77 and the initial Kerberos password for those users. The passwords are not
78 defined by default and must be set on the command line (-e) or in group
79 variables, preferably encrypted with `ansible-vault`.
83 The Kerberos KDC hostname. This host must be a member of the `afs_kdcs` host group.
88 The primary fileserver hostname and AFS fileserver partition id. The cell's
89 top-level volumes will be created on this fileserver partition.
93 An optional list of top level volumes to be created and mounted in the cell.
94 This should be defined as a list of dictionaries of `name=<volume name>,
95 mtpt=<mount path>`, where `<mount path>` is relative to `/afs/<cell name>/`
96 and defaults to the `<volume-name>`.
100 An optional list of AFS users to be created in the new cell. This should be
101 defined as list of dictionaries of `name=<username>`.
105 An optional list of AFS groups to be created in the new cell. This should be
106 defined as a list of dictionaries of `name=<group name>, members=<list of
109 Example initial cell configuration:
111 # contents of inventory/example.com/group_vars/all/cell.yaml
112 # Initial top level volumes.
134 ## OpenAFS Client Role
136 Name: `openafs_client`
138 Install and configure the OpenAFS client packages. Optionally, build and install from
143 afs_cell: example.com
145 afs_realm: EXAMPLE.COM
147 The Kerberos realm name, AFS cell name, and the cell organizational
150 # One of: 'package-manager', 'rsync'
151 afs_client_install_method: package-manager
153 The method used to install the OpenAFS client binaries. Values are:
155 * `package-manager` : Install client packages and a pre-built kernel module
156 with the system package manager (e.g., `yum`, `apt`).
157 * `rsync`: Copy the binary files. Build the client binaries and kernel module from source
158 code if needed. Installs development packages in order to
159 build the OpenAFS client binaries and kernel module, if needed.
161 afs_openafs_client_repourl:
163 The URL of a yum repo containing OpenAFS client packages for the `package-manager` install method.
165 afs_client_install_dkms: no
167 Install kernel module with DKMS for the `package-manager` install method.
169 afs_client_build_force: no
170 afs_client_build_builddir: "/usr/local/src/openafs_client"
171 afs_client_build_destdir: "/tmp/openafs_client"
172 afs_client_build_fetch_method: "git"
173 afs_client_build_git_repo: "https://github.com/openafs/openafs"
174 afs_client_build_git_ref: "master"
176 Build options for `rsync` install method.
178 afs_cacheinfo_mount: /afs
179 afs_cacheinfo_cache: /usr/vice/cache
180 afs_cacheinfo_size: 50000
182 The OpenAFS cache configuration parameters; the AFS filesystem mount point, the
183 cache partition, and the cache manager cache size. The cache partition should
186 afs_afsd_opts: -dynroot -fakestat -afsdb
188 The OpenAFS cache manager startup options.
190 ## OpenAFS Server Role
192 Name: `openafs_server`
194 Install and configure the OpenAFS server packages. This role installs both the
195 fileserver and the database servers, which can be installed on the same hosts
196 or different hosts. Optionally, build and install from source code.
198 This role enables OpenAFS servers to operate correctly with selinux set to
203 afs_cell: example.com
205 afs_realm: EXAMPLE.COM
207 The Kerberos realm name, AFS cell name, and the cell organizational
211 afs_admin_password: (undefined by default)
213 A administrator principal and password to be used to set the AFS service key.
214 The password is not defined by default and must be set on the command line (-e)
215 or in a group variable, preferably encrypted with `ansible-vault`.
217 afs_server_install_method: package-manager
219 The method used to install the OpenAFS server binaries. Values are:
221 * `package-manager`: Install OpenAFS server packages with yum. (default)
222 * `rsync`: Copy binary files. Build binares from source code if needed.
224 afs_openafs_server_repourl:
226 The URL of a yum repo containing OpenAFS server packages.
228 afs_server_build_force: no
229 afs_server_build_builddir: "/usr/local/src/openafs_server"
230 afs_server_build_destdir: "/tmp/openafs_server"
231 afs_server_build_fetch_method: "git"
232 afs_server_build_git_repo: "https://github.com/openafs/openafs"
233 afs_server_build_git_ref: "master"
235 Build from source options for the 'rsync' install method.
237 afs_selinux_mode: enforcing
239 The selinux enforcing mode. May be one of `enforcing`, `passive`, or
240 `disabled`. When `enforcing`, update the required selinux bits to allow the
241 servers to properly operate.
243 afs_fileserver_type: dafs
245 Determines which fileserver variation is setup when the host is a member of the
246 `afs_fileservers` group. May be the legacy OpenAFS fileserver (`fs`), or the
247 modern demand-attach fileserver (`dafs`). The demand-attach (`dafs`) variant is
253 afs_dafileserver_opts: -L
254 afs_davolserver_opts:
255 afs_salvageserver_opts:
261 The OpenAFS server command line options. See the OpenAFS man pages for the
266 The Kerberos KDC hostname.
271 The primary fileserver hostname and AFS fileserver partition id. The cell root
272 volume (root.afs, root.cell) will be created on this fileserver partition.
274 ## OpenAFS Devel Role
276 Name: `openafs_devel`
278 Install development packages and provide tasks to build an OpenAFS
279 binary distribution from source code.
283 afs_devel_build_server: yes
285 Build the server components.
287 afs_devel_build_client: yes
289 Build the client components, including the OpenAFS kernel module.
291 afs_devel_builddir: "/usr/local/src/openafs"
293 The path of the directory to perform the build.
295 afs_devel_destdir: "/tmp/openafs"
297 The path of the directory to place the generated binary distribution.
299 afs_devel_fetch_method: "git"
301 The method to obtain the source code. One of 'git', or 'none' (or 'skip')
302 Specify 'none' (or 'skip') to skip this stage.
304 afs_devel_git_repo: "https://github.com/openafs/openafs"
306 The git url to be used to checkout the source code.
308 afs_devel_git_ref: "master"
310 The git branch or tag to be checked out.
312 ## OpenAFS Test Suite Role
314 Name: `openafs_robotest`
316 Install and configure a set of Robot Framework test suites for OpenAFS.
326 ## Author Information
328 Copyright (c) 2018-2019 Sine Nomine Associates
331 [1]: https://www.openafs.org/
332 [2]: https://web.mit.edu/kerberos/