Add a page for OpenAFS Ansible roles
[openafs-wiki.git] / admin / AnsibleOpenAFS.mdwn
1 # Ansible Roles for OpenAFS
2
3 The `ansible-openafs` project is a collection of Ansible roles and playbooks to
4 deploy OpenAFS and clients with Ansible.  The roles can be used to deploy a new
5 Kerberos realm, install the servers, setup the initial cell, and install
6 OpenAFS clients in the cell.  The Ansible roles also are able to build OpenAFS
7 from source for testing and development.
8
9     https://github.com/openafs-contrib/ansible-openafs/
10
11 ## Platforms Supported
12
13 * OpenAFS 1.6.5+
14 * Ansible 2.5+
15 * OS Versions
16     * RHEL7/CentOS7
17     * Ubuntu 18.x
18
19 ## Kerberos Client Role
20
21 Name: `openafs_krbclient`
22
23 Install and configure the Kerberos workstation packages.
24
25 ### Role Variables
26
27     afs_realm: EXAMPLE.COM
28
29 The Kerberos realm name.
30
31 ## Kerberos Server Role
32
33 Name: `openafs_krbserver`
34
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.
37
38 ### Role Variables
39
40     afs_realm: EXAMPLE.COM
41
42 The Kerberos realm name.
43
44     afs_kerberos_master_password: (random by default)
45
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`.
49
50     afs_admin_principal: admin
51     afs_admin_password: (undefined by default)
52
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`.
56
57 ## OpenAFS Cell Role
58
59 Name: `openafs_cell`
60
61 Setup the top level volumes in the cell. This role is to be run on a single
62 client host.
63
64 ### Role Variables
65
66     afs_cell: example.com
67     afs_realm: EXAMPLE.COM
68
69 Cell and realm names.
70
71     afs_admin_principal: admin
72     afs_admin_password: (not defined)
73     afs_user_password:  (not defined)
74
75
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`.
80
81     afs_kdc:
82
83 The Kerberos KDC hostname. This host must be a member of the `afs_kdcs` host group.
84
85     afs_root_server:
86     afs_root_part: a
87
88 The primary fileserver hostname and AFS fileserver partition id. The cell's
89 top-level volumes will be created on this fileserver partition.
90
91     afs_volumes:
92
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>`.
97
98     afs_users:
99
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>`.
102
103     afs_groups:
104
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
107 usernames>`.
108
109 Example initial cell configuration:
110
111     # contents of inventory/example.com/group_vars/all/cell.yaml
112     # Initial top level volumes.
113     afs_volumes:
114       - name: test
115         mtpt: test
116     
117     # Initial AFS users.
118     afs_users:
119       - name: user1
120       - name: user2
121       - name: user3
122     
123     # Initial AFS groups
124     afs_groups:
125       - name: group1
126         members:
127           - user1
128           - user2
129       - name: group2
130         members:
131           - user2
132           - user3
133
134 ## OpenAFS Client Role
135
136 Name: `openafs_client`
137
138 Install and configure the OpenAFS client packages.  Optionally, build and install from
139 source code.
140
141 ### Role Variables
142
143     afs_cell: example.com
144     afs_desc: Example
145     afs_realm:  EXAMPLE.COM
146
147 The Kerberos realm name, AFS cell name, and the cell organizational
148 description.
149
150     # One of: 'package-manager', 'rsync'
151     afs_client_install_method: package-manager
152
153 The method used to install the OpenAFS client binaries. Values are:
154
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.
160
161     afs_openafs_client_repourl:
162
163 The URL of a yum repo containing OpenAFS client packages for the `package-manager` install method.
164
165     afs_client_install_dkms: no
166
167 Install kernel module with DKMS for the `package-manager` install method.
168
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"
175
176 Build options for `rsync` install method.
177
178     afs_cacheinfo_mount: /afs
179     afs_cacheinfo_cache: /usr/vice/cache
180     afs_cacheinfo_size: 50000
181
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
184 already exist.
185
186     afs_afsd_opts: -dynroot -fakestat -afsdb
187
188 The OpenAFS cache manager startup options.
189
190 ## OpenAFS Server Role
191
192 Name: `openafs_server`
193
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.
197
198 This role enables OpenAFS servers to operate correctly with selinux set to
199 enforcing mode.
200
201 ### Role Variables
202
203     afs_cell: example.com
204     afs_desc: Example
205     afs_realm:  EXAMPLE.COM
206
207 The Kerberos realm name, AFS cell name, and the cell organizational
208 description.
209
210     afs_admin_principal:
211     afs_admin_password: (undefined by default)
212
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`.
216
217     afs_server_install_method: package-manager
218
219 The method used to install the OpenAFS server binaries. Values are:
220
221 * `package-manager`:  Install OpenAFS server packages with yum. (default)
222 * `rsync`: Copy binary files. Build binares from source code if needed.
223
224     afs_openafs_server_repourl:
225
226 The URL of a yum repo containing OpenAFS server packages.
227
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"
234
235 Build from source options for the 'rsync' install method.
236
237     afs_selinux_mode: enforcing
238
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.
242
243     afs_fileserver_type: dafs
244
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
248 the default.
249
250     afs_bosserver_opts:
251     afs_ptserver_opts:
252     afs_vlserver_opts:
253     afs_dafileserver_opts: -L
254     afs_davolserver_opts:
255     afs_salvageserver_opts:
256     afs_dasalvager_opts:
257     afs_fileserver_opts:
258     afs_volserver_opts:
259     afs_salvager_opts:
260
261 The OpenAFS server command line options. See the OpenAFS man pages for the
262 server processes.
263
264     afs_kdc:
265
266 The Kerberos KDC hostname.
267
268     afs_root_server:
269     afs_root_part: a
270
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.
273
274 ## OpenAFS Devel Role
275
276 Name: `openafs_devel`
277
278 Install development packages and provide tasks to build an OpenAFS
279 binary distribution from source code.
280
281 ### Role Variables
282
283     afs_devel_build_server: yes
284
285 Build the server components.
286
287     afs_devel_build_client: yes
288
289 Build the client components, including the OpenAFS kernel module.
290
291     afs_devel_builddir: "/usr/local/src/openafs"
292
293 The path of the directory to perform the build.
294
295     afs_devel_destdir: "/tmp/openafs"
296
297 The path of the directory to place the generated binary distribution.
298
299     afs_devel_fetch_method: "git"
300
301 The method to obtain the source code. One of 'git', or 'none' (or 'skip')
302 Specify 'none' (or 'skip') to skip this stage.
303
304     afs_devel_git_repo: "https://github.com/openafs/openafs"
305
306 The git url to be used to checkout the source code.
307
308     afs_devel_git_ref: "master"
309
310 The git branch or tag to be checked out.
311
312 ## OpenAFS Test Suite Role
313
314 Name: `openafs_robotest`
315
316 Install and configure a set of Robot Framework test suites for OpenAFS.
317
318 ### Role Variables
319
320 TODO
321
322 ## License
323
324 BSD
325
326 ## Author Information
327
328 Copyright (c) 2018-2019 Sine Nomine Associates
329
330
331 [1]: https://www.openafs.org/
332 [2]: https://web.mit.edu/kerberos/