diff options
Diffstat (limited to 'roles/nfs_server')
-rw-r--r-- | roles/nfs_server/README.md | 189 | ||||
-rw-r--r-- | roles/nfs_server/tasks/exports.yml | 10 |
2 files changed, 194 insertions, 5 deletions
diff --git a/roles/nfs_server/README.md b/roles/nfs_server/README.md new file mode 100644 index 0000000..14ceea3 --- /dev/null +++ b/roles/nfs_server/README.md @@ -0,0 +1,189 @@ +NFS Server +========== + +Description +----------- + +The `nfs_server` role creates [zfs](../zfs/) filesystems, configures NFS and SMB +shares, adds `autofs` entries, and sets POSIX permissions and ACLs on the +corresponding directories. + +This role also manages home directories, which are considered a special case. +Both users and groups can have home directories. User home directories are +owned by the user, whereas group home directories are group-owned by the group. +In either case, two subdirectories are created: `priv` and `pub`. + +The `priv` directory is private to the user or group, while the `pub` directory +is world-readable. + +This role was written with the assumption that you're using ZFS for the +underlying storage. + +The lists and mappings in the variables in the role are somewhat complex. It's +probably easiest to start with the example playbook in the [Usage](#usage) +section at the bottom of this document. + +Variables +--------- + +This role **accepts** the following variables: + +Variable | Default | Description +----------------------------|--------------|------------ +`nfs_mountd_port` | `20048` | NFS `mountd` listening port +`nfs_exports` | `[]` | NFS exports to create (see [format](#nfs_exports) below) +`smb_shares` | `[]` | SMB shares to create (see [format](#smb_shares) below) +`nfs_homedirs` | `[]` | Home directories to create (see [format](#nfs_homedirs) below) +`nfs_homedir_user_dataset` | `tank/user` | ZFS dataset for user home directories +`nfs_homedir_group_dataset` | `tank/group` | ZFS dataset for group directories +`nfs_homedir_priv_quota` | `50G` | Default usage quota for private home/group directories +`nfs_homedir_pub_quota` | `10G` | Default usage quota for public home/group directories +`nfs_homedir_options` | `rw` | Export options for home/group directories +`nfs_homedir_clients` | `[]` | NFS clients for home/group directories (see [format](#nfs_homedir_clients) below + +### nfs\_exports + +The `nfs_exports` variable is used to configure NFS shares. It +should contain a list of dictionaries of the following format: + +Key | Default | Description +----------------|--------------------|----------- +`path` | | Path of export +`dataset` | | ZFS dataset to export +`group` | | Group owner for directory +`mode` | | Octal permissions for directory +`acl` | `[]` | List of POSIX ACL entries for directory (see [format](#acl) below) +`options` | `[]` | Export options (comma-separated or list, see `man 5 exports`) +`clients` | `[]` | List of clients (see [format](#clients) below) +`automount_map` | | Automount map name for export +`automount_key` | basename of `path` | Automount key name for export +`smb_share` | | Also create SMB share with given share name + +Either `path` or `dataset` should be specified, but not both. + +#### acl + +The `acl` key of an `nfs_exports` list item should contain a list of POSIX +ACLS, represented by dictionaries of the following format: + +Key | Default | Description +--------------|---------|------------ +`entity` | | User or group name +`etype` | | Entity type (either `user` or `group`) +`permissions` | | Some combination of `r`, `w`, `x`, or `X` +`default` | no | Apply ACL to all children of directory + +See `man 5 acl` for more details. + +#### clients + +The `clients` key of an `nfs_exports` list item should contain a list of NFS +clients, represented by dictionaries of the following format: + +Key | Default | Description +-----------|---------|------------ +`client` | | Client CIDR, IP address, or hostname +`options` | | Client-specific export options (comma-separated or list, see `man 5 exports`) + +### smb\_shares + +The `smb_shares` variable is used to configure SMB shares. It should contain a +list of dictionaries of the following format: + +Key | Default | Description +-----------|---------|------------ +`name` | | Share name +`path` | | Share path + +### nfs\_homedirs + +The `nfs_homedirs` variable is used to configure user and group home +directories that should live on the host. It should contain a list of +dictionaries of the following format: + +Key | Default | Description +-------------|--------------------------------|------------ +`user` | | User name +`group` | | Group name +`priv_quota` | `{{ nfs_homedir_priv_quota }}` | `priv` directory quota +`pub_quota` | `{{ nfs_homedir_pub_quota }}` | `pub` directory quota + +Specifying `user` creates a user home directory. Specifying `group` creates a +group home directory. You should not specify `user` and `group` at the same +time. + +### nfs\_homedir\_clients + +The `nfs_homedir_clients` variable is used to configure client access for home +directory exports. It should contain a list of dictionaries of the following +format: + +Key | Default | Description +----------|------------|------------ +`client` | | Client IP, CIDR, or hostname +`options` | `[]` | Export options (comma-separated or list, see `man 5 exports`) + + +Usage +----- + +Example playbook: + +````yaml +- hosts: nas1 + roles: + - role: nfs_server + vars: + nfs_exports: + - dataset: tank/media/pictures + group: role-photo-admin + mode: 02770 + acl: + - entity: role-photo-admin + etype: group + permissions: rwX + default: yes + options: rw,crossmnt + clients: + - client: 10.10.10.0/24 + options: sec=krb5p + automount_map: auto.nfs_media + + - dataset: tank/media/music + group: role-music-admin + mode: 02770 + acl: + - entity: role-music-admin + etype: group + permissions: rwX + default: yes + + - entity: role-music-access + etype: group + permissions: rX + default: yes + options: rw,crossmnt + clients: + - client: 10.10.10.0/24 + options: sec=krb5p + automount_map: auto.nfs_media + + nfs_homedir_clients: + - client: 10.10.10.0/24 + options: sec=krb5p + + - client: 10.10.11.0/24 + options: sec=sys + + nfs_homedirs: + - user: johndoe + priv_quota: 250G + - user: janedoe + priv_quota: 250G + - group: doefamily + priv_quota: 500G + + smb_shares: + - name: media + path: /tank/media +```` diff --git a/roles/nfs_server/tasks/exports.yml b/roles/nfs_server/tasks/exports.yml index 10ff894..b9ffbeb 100644 --- a/roles/nfs_server/tasks/exports.yml +++ b/roles/nfs_server/tasks/exports.yml @@ -18,7 +18,7 @@ - name: set directory permissions for exports file: - path: '{{ zfs_mountpoints[item.dataset] }}' + path: '{{ item.path | default(zfs_mountpoints[item.dataset]) }}' owner: '{{ item.owner | default(omit) }}' group: '{{ item.group | default(omit) }}' mode: "{{ '0%0o' % item.mode if item.mode is defined else omit }}" @@ -30,7 +30,7 @@ - name: set directory ACLs for exports acl: - path: '{{ zfs_mountpoints[item.0.dataset] }}' + path: '{{ item.0.path | default(zfs_mountpoints[item.0.dataset]) }}' default: '{{ item.1.default | default(omit) }}' entity: '{{ item.1.entity }}' etype: '{{ item.1.etype }}' @@ -39,11 +39,11 @@ state: present loop: "{{ nfs_exports | selectattr('acl', 'defined') | subelements('acl') }}" loop_control: - label: '{{ item.0.dataset }}: {{ item.1 }}' + label: '{{ item.0.path | default(item.0.dataset) }}: {{ item.1 }}' - name: for exports with a "default" ACL, ensure the ACL is set on the directory itself acl: - path: '{{ zfs_mountpoints[item.0.dataset] }}' + path: '{{ item.0.path | default(zfs_mountpoints[item.0.dataset]) }}' default: no entity: '{{ item.1.entity }}' etype: '{{ item.1.etype }}' @@ -52,4 +52,4 @@ state: present loop: "{{ nfs_exports | selectattr('acl', 'defined') | subelements('acl') | selectattr('1.default', 'defined') | selectattr('1.default', 'equalto', True) }}" loop_control: - label: '{{ item.0.dataset }}: {{ item.1 }}' + label: '{{ item.0.path | default(item.0.dataset) }}: {{ item.1 }}' |