Skip to content

Latest commit

 

History

History
1232 lines (755 loc) · 35.1 KB

REFERENCE.md

File metadata and controls

1232 lines (755 loc) · 35.1 KB
Raw

Reference

Table of Contents

Classes

Public Classes

  • nfs: Provides the base configuration and services for an NFS server and/or client.
  • nfs::idmapd::client: Manage the idmapd client configuration
  • nfs::idmapd::config: Manage idmapd configuration
  • nfs::lvm2: Class to counterract a packaging bug with nfs-utils.

Private Classes

  • nfs::base::config: Manage configuration common to an NFS server and an NFS client
  • nfs::base::service: Manage services common to an NFS server and an NFS client
  • nfs::client: Manage configuration and services for a NFS client
  • nfs::client::config: Manage NFS client-specific configuration
  • nfs::client::service: Manage NFS client-specific services
  • nfs::client::tcpwrappers: Configure TCP wrappers for NFS client services
  • nfs::idmapd::server: Manage the idmapd server configuration and service
  • nfs::install: Manage the required NFS packages
  • nfs::selinux_hotfix: Provides hotfix for broken SElinux policy
  • nfs::server: Manage configuration and services for a NFS server
  • nfs::server::config: Manage NFS server-specific configuration
  • nfs::server::firewall: NFS server firewall configuration
  • nfs::server::firewall::nfsv3and4: NFS server firewall configuration for NFSv3 and NFSv4
  • nfs::server::firewall::nfsv4: NFS server firewall configuration for NFSv4 only
  • nfs::server::service: Manage NFS server-specific services
  • nfs::server::stunnel: Configures a server for NFSv4 over stunnel
  • nfs::server::tcpwrappers: Configure TCP wrappers for NFS server services

Defined types

Public Defined types

Private Defined types

  • nfs::client::mount::connection: Manage cross-system connectivity parts of a mount
  • nfs::client::stunnel: Connect to an NFSv4 server over stunnel

Data types

  • Nfs::LegacyDaemonArgs: Legacy NFS daemon *ARGS environment variables set in /etc/sysconfig/nfs and automatically converted to the environment variables needed by th
  • Nfs::MountEnsure: Ensure for non-autofs mounts
  • Nfs::NfsConfHash: Hash representing nfs.conf configuration in which the key is the section name and the value is a Hash of key/value options for that section.
  • Nfs::SecurityFlavor: NFS security flavor

Classes

nfs

Provides the base configuration and services for an NFS server and/or client.

Parameters

The following parameters are available in the nfs class:

is_server

Data type: Boolean

Explicitly state that this system should be an NFS server

  • Further configuration can be made via the nfs::server class

Default value: false

is_client

Data type: Boolean

Explicitly state that this system should be an NFS client

  • Further configuration can be be made via the nfs::client class

Default value: true

nfsv3

Data type: Boolean

Allow use of NFSv3. When false, only NFSv4 will be allowed.

Default value: false

gssd_avoid_dns

Data type: Boolean

Use a reverse DNS lookup, even if the server name looks like a canonical name

  • Sets the avoid-dns option in the gssd section of /etc/nfs.conf

Default value: true

gssd_limit_to_legacy_enctypes

Data type: Boolean

Restrict sessions to weak encryption types

  • Sets the limit-to-legacy-enctypes option in the gssd section of /etc/nfs.conf

Default value: false

gssd_use_gss_proxy

Data type: Boolean

Use the gssproxy daemon to hold the credentials used in secure NFS and perform GSSAPI operations on behalf of NFS.

  • Sets the use-gss-proxy option in the gssd section of /etc/nfs.conf This is not yet documented in the rpc.gssd man page for EL8, but is available in the example /etc/nsf.conf file packaged with nfs-utils.
  • Sets GSS_USE_PROXY in /etc/sysconfig/nfs in EL7, because the use-gss-proxy option in /etc/nfs.conf is not yet used in EL7.

Default value: true

lockd_port

Data type: Simplib::Port

The TCP port upon which lockd should listen on both the NFS server and the NFS client (NFSv3)

  • Sets the port option in the lockd section of /etc/nfs.conf
  • Corresponds to the nlockmgr service TCP port reported by rpcinfo

Default value: 32803

lockd_udp_port

Data type: Simplib::Port

The UDP port upon which lockd should listen on both the NFS server and the NFS client (NFSv3)

  • Sets the udp-port option in the lockd section of /etc/nfs.conf
  • Corresponds to the nlockmgr service UDP port reported by rpcinfo

Default value: 32769

nfsd_port

Data type: Simplib::Port

The port upon which NFS daemon on the NFS server should listen

  • Sets the port option in the nfsd section of /etc/nfs.conf
  • Corresponds to the nfs and nfs_acl service ports reported by rpcinfo

Default value: 2049

sm_notify_outgoing_port

Data type: Simplib::Port

The port that sm-notify will use when notifying NFSv3 peers

  • Sets the outgoing-port option in the sm-notify section of /etc/nfs.conf

Default value: 2021

statd_port

Data type: Simplib::Port

The port upon which statd should listen on both the NFS server and the NFS client (NFSv3)

  • Sets the port option in the statd section of /etc/nfs.conf
  • Corresponds to the status service port reported by rpcinfo

Default value: 662

statd_outgoing_port

Data type: Simplib::Port

The port that statd will use when communicating with NFSv3 peers

  • Sets the outgoing-port option in the status section of /etc/nfs.conf

Default value: 2020

custom_nfs_conf_opts

Data type: Nfs::NfsConfHash

Hash that allows other configuration options to be set in /etc/nfs.conf

  • Each key is a known section of /etc/nfs.conf, such as nfsd.
  • Each value is a Hash of config parameter names and values.
  • Configuration values are not validated.
  • If a new section needs to be added to /etc/nfs.conf, you can use concat::fragment.

@example Set NFS server's grace and lease times in Hiera nfs::custom_nfs_conf_opts: nfsd: grace-time: 60 lease-time: 60

Default value: {}

custom_daemon_args

Data type: Nfs::LegacyDaemonArgs

Hash that allows other configuration options to be set as daemon arguments in /etc/sysconfig/nfs in EL7

  • Necessary to address /etc/nfs.conf limitations - Not all configuration options in EL7 can be specified in /etc/nfs.conf

  • Each key is the name of the shell variables processed by /usr/lib/systemd/scripts/nfs-utils_env.sh

    • nfs-utils_env.sh generates /run/sysconfig/nfs-utils which contains the NFS daemon command line shell variables used by NFS services
    • Unfortunately, not all shell variable names in /etc/sysconfig/nfs match the generated variable names in /run/sysconfig/nfs-utils. For example, STATDARG gets transformed into STATDARGS.

  • Each value is the argument string which will be wrapped in double quotes in /etc/sysconfig/nfs.

@example Disable syslog messages from the NFSv3 rpc.statd daemon in Hiera nfs::custom_daemon_args: STATDARG: "--no-syslog"

Default value: {}

idmapd

Data type: Boolean

Whether to use idmapd for NFSv4 ID to name mapping

Default value: false

secure_nfs

Data type: Boolean

Whether to enable secure NFS mounts

Default value: false

sunrpc_udp_slot_table_entries

Data type: Integer[1]

Set the default UDP slot table entries in the kernel

  • Most NFS performance guides seem to recommend this setting
  • If you have a low memory system, you may want to reduce this

Default value: 128

sunrpc_tcp_slot_table_entries

Data type: Integer[1]

Set the default TCP slot table entries in the kernel

  • Most NFS performance guides seem to recommend this setting
  • If you have a low memory system, you may want to reduce this

Default value: 128

ensure_latest_lvm2

Data type: Boolean

See nfs::lvm2 for further description

Default value: true

kerberos

Data type: Boolean

Use the SIMP krb5 module for Kerberos support

  • You may need to set variables in krb5::config via Hiera or your ENC if you do not like the defaults.

Default value: simplib::lookup('simp_options::kerberos', { 'default_value' => false })

keytab_on_puppet

Data type: Boolean

Whether the NFS server will pull its keytab directly from the Puppet server

  • Only applicable if $kerberos is `true.
  • If false, you will need to ensure the appropriate services are restarted and cached credentials are destroyed (e.g., gssproxy cache), when the keytab is changed.

Default value: simplib::lookup('simp_options::kerberos', { 'default_value' => true})

firewall

Data type: Boolean

Use the SIMP iptables module to manage firewall connections

Default value: simplib::lookup('simp_options::firewall', { 'default_value' => false})

tcpwrappers

Data type: Boolean

Use the SIMP tcpwrappers module to manage TCP wrappers

Default value: simplib::lookup('simp_options::tcpwrappers', { 'default_value' => false })

stunnel

Data type: Boolean

Wrap stunnel around critical NFSv4 connections

  • This is intended for environments without a working Kerberos setup and may cause issues when used with Kerberos.

  • Use of Kerberos is preferred.

  • This will configure the NFS server and client mount to only use TCP communication

  • Cannot be used for NFSv4.0 connections, because NFSv4.0 uses a side channel to each NFS client to recall delegation responsibilities.

  • The following connections will not be secured, due to tunneling limitations in deployments using multiple NFS servers

    • Connections to the rbcbind service
    • Connections to the rpc-rquotad service

  • Use of stunnel for an individual client mount can be controlled by the stunnel parameter in the nfs::client::mount define.

  • Use of stunnel for just the NFS server on this host can be controlled by the stunnel parameter in the nfs::server class.

Default value: simplib::lookup('simp_options::stunnel', { 'default_value' => false })

stunnel_nfsd_port

Data type: Simplib::Port

Listening port on the NFS server for the tunneled connection to the NFS server daemon

  • Decrypted traffic will be forwarded to $nfsd_port on the NFS server

Default value: 20490

stunnel_socket_options

Data type: Array[String]

Additional socket options to set for all stunnel connections

  • Stunnel socket options for an individual client mount can be controlled by the stunnel_socket_options parameter in the nfs::client::mount define.
  • Stunnel socket options for just the NFS server on this host can be controlled by the stunnel_socket_options parameter in the nfs::server class.

Default value: ['l:TCP_NODELAY=1','r:TCP_NODELAY=1']

stunnel_verify

Data type: Integer

The level at which to verify TLS connections

  • Levels:

    • level 0 - Request and ignore peer certificate.
    • level 1 - Verify peer certificate if present.
    • level 2 - Verify peer certificate.
    • level 3 - Verify peer with locally installed certificate.
    • level 4 - Ignore CA chain and only verify peer certificate.

  • Stunnel verify for an individual client mount can be controlled by the stunnel_verify parameter in the nfs::client::mount define.

  • Stunnel verify for just the NFS server on this host can be controlled by the stunnel_verify parameter in the nfs::server class.

Default value: 2

tcpwrappers

Use the SIMP tcpwrappers module to manage TCP wrappers

Default value: simplib::lookup('simp_options::tcpwrappers', { 'default_value' => false })

trusted_nets

Data type: Simplib::Netlist

The systems that are allowed to connect to this service

  • Set to 'any' or 'ALL' to allow the world

Default value: simplib::lookup('simp_options::trusted_nets', { 'default_value' => ['127.0.0.1'] })

nfs::idmapd::client

When using idmapd, an NFSv4 client uses nfsidmap, directly, instead of nfs-idmapd.service. nfsidmap is configured by /etc/idmapd.conf, but must be hooked into /sbin/request-key via /etc/request-key.conf.

Parameters

The following parameters are available in the nfs::idmapd::client class:

timeout

Data type: Integer[0]

nfsidmap key expiration timeout in seconds

Default value: 600

nfs::idmapd::config

Manage idmapd configuration

  • See also
    • idmapd.conf(5)

Parameters

The following parameters are available in the nfs::idmapd::config class:

verbosity

Data type: Optional[Integer]

Default value: undef

domain

Data type: Optional[String[1]]

Default value: undef

no_strip

Data type: Optional[Enum['user','group','both','none']]

Default value: undef

reformat_group

Data type: Optional[Boolean]

Default value: undef

local_realms

Data type: Optional[Array[String[1],1]]

Default value: undef

nobody_user

Data type: String

Default value: 'nobody'

nobody_group

Data type: String

Default value: 'nobody'

trans_method

Data type: Array[Enum['nsswitch','static'],1]

[Translation] Method

  • Method is a reserved word in Ruby
  • umich_ldap is not yet supported

Default value: ['nsswitch']

gss_methods

Data type: Optional[Array[Enum['nsswitch','static'],1]]

Default value: undef

static_translation

Data type: Optional[Hash[String[1],String[1]]]

Will be translated into the [Static] section variables as presented in the man page

  • For example: { 'foo' => 'bar' } will be foo = bar in the output file

Default value: undef

content

Data type: Optional[String]

Use this as the explicit content for the idmapd configuration file

  • Overrides all other options

Default value: undef

nfs::lvm2

Unless lvm2 is ensured latest, nfs-utils cannot upgrade. The class will be removed once the bug is fixed upstream.

Parameters

The following parameters are available in the nfs::lvm2 class:

ensure

Data type: String

The ensure status of the lvm2 package

Default value: simplib::lookup('simp_options::package_ensure', { 'default_value' => 'latest' })

Defined types

nfs::client::mount

Set up a NFS client mount, optionally using autofs

Examples

Static mount
nfs::client::mount { '/mnt/apps1':
  nfs_server  => '10.0.1.2',
  remote_path => '/exports/apps1',
  autofs      => false
}
Direct automount
nfs::client::mount { '/mnt/apps2':
  nfs_server  => '10.0.1.3',
  remote_path => '/exports/apps2'
}
Indirect automount with map key substitution
nfs::client::mount { '/home':
  nfs_server              => '10.0.1.4',
  remote_path             => '/exports/home',
  autofs_indirect_map_key => '*',
  autofs_add_key_subst    => true
}
NFSv3 mount
nfs::client::mount { '/mnt/apps3':
  nfs_server  => '10.0.1.5',
  nfs_version => 3,
  remote_path => '/exports/apps3',
  autofs      => false
}

Parameters

The following parameters are available in the nfs::client::mount defined type:

name

The local mount path

  • When not using autofs ($autofs is false), this will be a static mount and you must ensure the target directory exists. This define will NOT create the target directory for you.

  • When using autofs ($autofs is true)

    • autofs will create the target directory for you (full path).

    • If $autofs_indirect_map_key is unset, a direct mount will be created for this path.

    • If $autofs_indirect_map_key is set, an indirect mount will be created:

      • $name will be the mount point
      • $autofs_indirect_map_key will be the map key
nfs_server

Data type: Simplib::Ip

The IP address of the NFS server to which you will be connecting

  • If this host is also the NFS server, please set this to 127.0.0.1.
remote_path

Data type: Stdlib::Absolutepath

The NFS share that you want to mount

autodetect_remote

Data type: Boolean

Attempts to figure out if this host is also the NFS server and adjust the connection to the local IP address, 127.0.0.1, in lieu of the IP address specified in $nfs_server.

  • When you know this host is also the NFS server, setting $nfs_server to 127.0.0.1 is best.
  • Auto-detect logic only works with IPv4 addresses.

Default value: true

nfs_version

Data type: Integer[3,4]

The NFS major version that you want to use.

  • Used to set the nfsvers mount option
  • If you need to specify an explicit minor version of NFSv4, include 'minorversion=<#>' in $options.

Default value: 4

sec

Data type: Nfs::SecurityFlavor

The security flavor for the mount

  • Used to set the sec mount option for NFSv4 mounts
  • Ignored for NFSv3 mounts

Default value: 'sys'

options

Data type: String

String containing comma-separated list of additional mount options

  • fstype will already be set for you
  • If using stunnel with NFSv4, proto will be set to tcp for you

Default value: 'soft'

ensure

Data type: Nfs::MountEnsure

The mount state of the specified mount point

  • mounted => Ensure that the mount point is actually mounted
  • present => Just add the entry to the fstab and do not mount it
  • unmounted => Add the entry to the fstab and ensure that it is not mounted
  • Has no effect if $autofs is true

Default value: 'mounted'

at_boot

Data type: Boolean

Ensure that this mount is mounted at boot time

  • Has no effect if $autofs is true

Default value: true

autofs

Data type: Boolean

Enable automounting with Autofs

Default value: true

autofs_indirect_map_key

Data type: Optional[String[1]]

Autofs indirect map key

  • May be '*', the wildcard map key

Default value: undef

autofs_add_key_subst

Data type: Boolean

This enables map key substitution for a wildcard map key in an indirect map.

  • Appends '/&' to the remote location.
  • Only makes sense if $autofs_indirect_map_key is set to '*', the wildcard map key.

Default value: false

nfsd_port

Data type: Optional[Simplib::Port]

The NFS server daemon listening port

  • Used to set the port mount option
  • If left unset, the value will be taken from $nfs::nfsd
  • When using stunnel, must be a different value for each distinct NFS server for which a stunneled mount connection is to be made.

Default value: undef

stunnel

Data type: Optional[Boolean]

Controls enabling stunnel to encrypt NFSv4 connection to the NFS server

  • If left unset, the value will be taken from $nfs::client::stunnel

  • May be set to false to ensure that stunnel will not be used for this connection

  • May be set to true to force the use of stunnel on this connection

  • Unused when $nfs_version is 3.

    • stunneled connections are not viable for NFSv3 because of the UDP-only NFS client NSM notifications and the inability to effectively configure the rpcbind port.
    • If you know the NFS version negotiated with the NFS server will fallback to NFSv3, you must set $nfs_version to 3 or $stunnel to false. The mount will fail otherwise.

  • Will attempt to determine if the host is trying to connect to itself and use a direct, local connection in lieu of a stunnel in this case.

    • When you know this host is also the NFS server, setting this to false and $nfs_server to 127.0.0.1 is best.
    • Auto-detect logic only works with IPv4 addresses.

Default value: undef

stunnel_nfsd_port

Data type: Optional[Simplib::Port]

Listening port on the NFS server for the tunneled connection to the NFS server daemon

  • Decrypted traffic will be forwarded to nfsd_port on the NFS server
  • If left unset, the value will be taken from $nfs::stunnel_nfsd_port
  • Unused when $stunnel is false

Default value: undef

stunnel_socket_options

Data type: Optional[Array[String]]

Additional stunnel socket options to be applied to the stunnel to the NFS server

  • If left unset, the value will be taken from $nfs::client::stunnel_socket_options
  • Unused when $stunnel is false

Default value: undef

stunnel_verify

Data type: Optional[Integer]

The level at which to verify TLS connections

  • Levels:

    • level 0 - Request and ignore peer certificate.
    • level 1 - Verify peer certificate if present.
    • level 2 - Verify peer certificate.
    • level 3 - Verify peer with locally installed certificate.
    • level 4 - Ignore CA chain and only verify peer certificate.

  • If left unset, the value will be taken from $nfs::client::stunnel_socket_verify

  • Unused when $stunnel is false

Default value: undef

stunnel_wantedby

Data type: Optional[Array[String]]

The systemd targets that need stunnel to be active prior to being activated

  • If left unset, the value will be taken from $nfs::client::stunnel_wantedby
  • Unused when $stunnel is false

Default value: undef

nfs::server::export

Be careful! The name of these mounts must be unique, but the only unique combination is mountpoint + client. Therefore, you can actually have duplicate entries.

NFS will function fine with this but the last duplicate entry in the file will win!

  • See also
    • exports(5)

Parameters

The following parameters are available in the nfs::server::export defined type:

export_path

Data type: Stdlib::Absolutepath

The path on the filesystem to export

clients

Data type: Array[String]

NFS export-compatible clients to which the export should be served.

  • The entry will be repeated for each client
  • Use ['*'] for client wildcard
comment

Data type: Optional[String]

A comment to be added to the set of entries

Default value: undef

insecure

Data type: Boolean

Do not require that requests originate on a Port less than 1024

  • Due to a NFS kernel bug when processing exports, you must set this to true when allowing stunneled NFSv4 connections.

    • The export rule processor is supposed to select the most specific rule that matches. However, when rules overlap and one rule is has insecure enabled and another does not, the rule without insecure specified is selected, even when it is less specific.
    • See https://bugzilla.redhat.com/show_bug.cgi?id=1804912

Default value: false

rw

Data type: Boolean

Allow both reads and writes on this volume

Default value: false

async

Data type: Boolean

Allow the NFS server to reply to request before changes have been committed to stable storage

Default value: false

no_wdelay

Data type: Boolean

Disable write delays

  • Has no effect if $async is set

Default value: false

nohide

Data type: Boolean

Disable hiding of subordinate filesystems

Default value: false

crossmnt

Data type: Boolean

Allow clients to access all filesystems mounted on a filesystem marked with crossmnt

Default value: false

subtree_check

Data type: Boolean

Enable subtree checking

Default value: false

insecure_locks

Data type: Boolean

Do not require authentication of locking requests

Default value: false

mountpoint

Data type: Optional[Variant[Stdlib::Absolutepath,Boolean]]

Require this path to be successfully mounted on disk

  • If a Boolean, require the export path to be successfully mounted

Default value: undef

fsid

Data type: Optional[String]

A specific ID for the exported filesystem

Default value: undef

nordirplus

Data type: Boolean

Disable READDIRPLUS request handling on NFSv3 clients

Default value: false

refer

Data type: Optional[Array[Pattern['^/.+@.+$']]]

A list of alternate locations for the filesystem

  • This should be in the form specified by the man page: path@host[+host]
  • There will be minimal validation and they will be joined by :

Default value: undef

replicas

Data type: Optional[Array[Pattern['^/.+@.+$']]]

Alternative locations for the export point

  • This should be in the form specified by the man page: path@host[+host]
  • There will be minimal validation and they will be joined by :

Default value: undef

pnfs

Data type: Boolean

Enables use of pNFS extensions for NFSv4.1 or higher and the filesystem supports pNFS exports

Default value: false

security_label

Data type: Boolean

Allow clients using NFSv4.2 or higher to set and retrieve security labels (such as those used by SELinux)

Default value: true

sec

Data type: Array[Nfs::SecurityFlavor]

Security flavors, in order of preference

Default value: ['sys']

no_root_squash

Data type: Boolean

Disable root squashing

  • This should only be done if you really know what you are doing!

Default value: false

all_squash

Data type: Boolean

Map all uids and gids to the anonymous user

Default value: false

anonuid

Data type: Simplib::Port

Explicity set the UID of the anonymous user

Default value: 65534

anongid

Data type: Simplib::Port

Explicity set the GID of the anonymous user

Default value: 65534

custom

Data type: Optional[String]

A custom set of options

  • If set, all other options will be ignored
  • $mountpoint and $client must still be set
  • Do not include the parenthesis if you are writing a custom options string.

Default value: undef

Data types

Nfs::LegacyDaemonArgs

Legacy NFS daemon *ARGS environment variables set in /etc/sysconfig/nfs and automatically converted to the environment variables needed by the daemons in their service scripts by /usr/lib/systemd/scripts/nfs-utils_env.sh

Alias of

Struct[{
  Optional['GSSDARGS']      => String,
  Optional['RPCIDMAPDARGS'] => String,
  Optional['RPCMOUNTDARGS'] => String,
  Optional['RPCNFSDARGS']   => String,
  Optional['SMNOTIFYARGS']  => String,
  # This is converted to STATDARGS
  Optional['STATDARG']      => String
}]

Nfs::MountEnsure

Ensure for non-autofs mounts

Alias of Enum['mounted', 'present', 'unmounted']

Nfs::NfsConfHash

Hash representing nfs.conf configuration in which the key is the section name and the value is a Hash of key/value options for that section.

Alias of

Struct[{
  Optional['general']     => Hash[String,Variant[Boolean,Integer,Float,String]],
  Optional['exportfs']    => Hash[String,Variant[Boolean,Integer,Float,String]],
  Optional['gssd']        => Hash[String,Variant[Boolean,Integer,Float,String]],
  Optional['lockd']       => Hash[String,Variant[Boolean,Integer,Float,String]],
  Optional['mountd']      => Hash[String,Variant[Boolean,Integer,Float,String]],
  Optional['nfsd']        => Hash[String,Variant[Boolean,Integer,Float,String]],
  Optional['nfsdcltrack'] => Hash[String,Variant[Boolean,Integer,Float,String]],
  Optional['sm-notify']   => Hash[String,Variant[Boolean,Integer,Float,String]],
  Optional['statd']       => Hash[String,Variant[Boolean,Integer,Float,String]]
}]

Nfs::SecurityFlavor

NFS security flavor

Alias of Enum['none', 'sys', 'krb5', 'krb5i', 'krb5p']