admin/AnsibleOpenAFS.mdwn

   1 # Ansible Roles for OpenAFS
   2
   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.
   9
  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/