Repository files navigation

1. Module Description - What the module does and why it is useful
2. Setup - The basics of getting started with puppet-nfs
   • What puppet-nfs affects
   • Setup requirements
   • Beginning with puppet-nfs
3. Usage - Configuration options and additional functionality
4. Reference - An under-the-hood peek at what the module is doing and how
5. Limitations - OS compatibility, etc.
6. Development - Guide for contributing to the module

Github Master:

This module installs, configures and manages everything on NFS clients and servers.

This module is a complete refactor of the module haraldsk/nfs, because Harald Skoglund sadly is notmaintaining his module actively anymore. It is stripped down to use only the class 'nfs'and parametrized to act as a server, client or both with the parameters 'server_enabled'and 'client_enabled'. It also has some dependencies on newer stdlib functions like 'difference'.

It supports the OS Families Ubuntu, Debian, Redhat, SUSE, Gentoo and Archlinux. It supports also Strict Variables, so if you pass allOS specific parameters correctly it should work on your preferred OS too. Feedback, bugreports,and feature requests are always welcome, visithttps://github.com/voxpupuli/puppet-nfs or send me an email.

When you are using a puppet version 3.x like it is shipped with Redhat Satellite 6, please use a version 1.x.x from puppet forgeor the branch puppet3 when cloning directly from Github. (Note:#49 (comment)).I'll recommend using puppet >= 4.6.1, puppet versions up until 4.6.0 had various issues.

If you want to contribute, please do a fork on github, create a branch "feature name" with yourfeatures and do a pull request.

Warning: I've introduced new dependencies with version 2.1.0 which were needed to fix buggy rpcbind-socket restarting with systemd:

• puppetlabs/transition
• herculesteam/augeasproviders_core
• herculesteam/augeasproviders_shellvar

This module can be used to configure your nfs client and/or server, it could exportnfs mount resources via storeconfigs or simply mount nfs shares on a client. You canalso easily use the create_resources function when you store your exports i.e. via hiera.

This Module depends on puppetlabs-stdlib >= 4.5.0 and puppetlabs-concat >= 1.1.2, you need tohave these modules installed to use puppet-nfs module.

On a nfs server the following code is sufficient to get all packages installed and servicesrunning to use nfs:

nodeserver {class {'::nfs':server_enabled=>true,    }  }

On a client the following code is sufficient:

nodeserver {class {'::nfs':client_enabled=>true,    }  }

This will export /data_folder on the server and automagically mount it on client.

nodeserver {class {'::nfs':server_enabled=>true    }nfs::server::export{'/data_folder':ensure=>'mounted',clients=>'10.0.0.0/24(rw,insecure,async,no_root_squash) localhost(rw)'    }  }# By default, mounts are mounted in the same folder on the clients as# they were exported from on the servernodeclient {class {'::nfs':client_enabled=>true,    }    Nfs::Client::Mount <<| |>>  }

This will mount /data on client in /share/data.

nodeclient {class {'::nfs':server_enabled=>false,client_enabled=>true,nfs_v4_client=>true,nfs_v4_idmap_domain=>$::domain,    }nfs::client::mount {'/share/data':server=>'192.168.0.1',share=>'data',    }  }

nodeserver1 {class {'::nfs':server_enabled=>true,    }nfs::server::export {'/data_folder':ensure=>'mounted',clients=>'10.0.0.0/24(rw,insecure,async,no_root_squash) localhost(rw)',    }nfs::server::export {'/homeexport':ensure=>'mounted',clients=>'10.0.0.0/24(rw,insecure,async,root_squash)',mount=>'/srv/home',    }  }nodeserver2 {class {'::nfs':server_enabled=>true,    }# ensure is passed to mount, which will make the client not mount it# the directory automatically, just add it to fstabnfs::server::export {'/media_library':ensure=>'present',nfstag=>'media',clients=>'10.0.0.0/24(rw,insecure,async,no_root_squash) localhost(rw)',    }  }nodeclient {class {'::nfs':client_enabled=>true,    }    Nfs::Client::Mount <<| |>>  }# Using a storeconfig override, to change ensure option, so we mount# all sharesnodegreedy_client {class {'::nfs':client_enabled=>true,    }    Nfs::Client::Mount <<| |>> {ensure=>'mounted',    }  }# only the mount tagged as media# also override mount pointnodemedia_client {class {'::nfs':client_enabled=>true,    }    Nfs::Client::Mount <<| nfstag =='media' |>> {ensure=>'mounted',mount=>'/import/media',    }  }# All @@nfs::server::mount storeconfigs can be filtered by parameters# Also all parameters can be overridden (not that it's smart to do# so).# Check out the doc on exported resources for more info:# http://docs.puppetlabs.com/guides/exported_resources.htmlnodesingle_server_client {class {'::nfs':client_enabled=>true,    }    Nfs::Client::Mount <<| server =='server1' |>> {ensure=>'absent',    }  }

# We use the $::domain fact for the Domain setting in# /etc/idmapd.conf.# For NFSv4 to work this has to be equal on servers and clients# set it manually if unsure.## All nfsv4 exports are bind mounted into /export/$mount_name# and mounted on /srv/$mount_name on the client.# Both values can be overridden through parameters both globally# and on individual nodes.nodeserver {file { ['/data_folder','/homeexport']:ensure=>'directory',    }class {'::nfs':server_enabled=>true,nfs_v4=>true,nfs_v4_idmap_domain=>'example.com',nfs_v4_export_root=>'/export',nfs_v4_export_root_clients=>'*(rw,fsid=0,insecure,no_subtree_check,async,no_root_squash)',    }nfs::server::export {'/data_folder':ensure=>'mounted',clients=>'*(rw,insecure,async,no_root_squash,no_subtree_check)',    }nfs::server::export {'/homeexport':ensure=>'mounted',clients=>'*(rw,insecure,async,root_squash,no_subtree_check)',mount=>'/srv/home',    }  }# By default, mounts are mounted in the same folder on the clients as# they were exported from on the servernodeclient {class {'::nfs':client_enabled=>true,nfs_v4_client=>true,    }    Nfs::Client::Mount <<| |>>  }# We can also mount the NFSv4 Root directly through nfs::client::mount::nfsv4::root.# By default /srv will be used for as mount point, but can be overriden through# the 'mounted' option.nodeclient2 {$server ='server'class {'::nfs':client_enabled=>true,nfs_v4_client=>true,    }    Nfs::Client::Mount::Nfs_v4::Root <<| server ==$server |>> {mount=>"/srv/${server}",    }  }

# and on individual nodes.nodeserver {class {'::nfs':server_enabled=>true,nfs_v4=>true,# Below are defaultsnfs_v4_idmap_domain=>$::domain,nfs_v4_export_root=>'/export',# Default access settings of /export rootnfs_v4_export_root_clients=>"*.${::domain}(ro,fsid=root,insecure,no_subtree_check,async,root_squash)",    }nfs::server::export {'/data_folder':# These are the defaultsensure=>'mounted',# rbind or bind mounting of folders bindmounted into /export# google itbind=>'rbind',# everything below here is propogated by to storeconfigs# to clients## Directory where we want export mounted on clientmount=>undef,remounts=>false,atboot=>false,#  Don't remove that option, but feel free to add more.options_nfs=>'_netdev',# If set will mount share inside /srv (or overridden mount_root)# and then bindmount to another directory elsewhere in the fs -# for fanatics.bindmount=>undef,# Used to identify a catalog item for filtering by by# storeconfigs, kick ass.nfstag=>'kick-ass',# copied directly into /etc/exports as a string, for simplicityclients=>'10.0.0.0/24(rw,insecure,no_subtree_check,async,no_root_squash)',    }  }nodeclient {class {'::nfs':client_enabled=>true,nfs_v4_client=>true,nfs_v4_idmap_domain=>$::domain,nfs_v4_mount_root=>'/srv',    }# We can as you by now know, override options set on the server# on the client node.# Be careful. Don't override mount points unless you are sure# that only one export will match your filter!    Nfs::Client::Mount <<| nfstag =='kick-ass' |>> {# Directory where we want export mounted on clientmount=>undef,remounts=>false,atboot=>false,#  Don't remove that option, but feel free to add more.options_nfs=>'_netdev',# If set will mount share inside /srv (or overridden mount_root)# and then bindmount to another directory elsewhere in the fs -# for fanatics.bindmount=>undef,    }  }

Hiera Server Role:

classes:    -nfsnfs::server_enabled:truenfs::client_enabled:falsenfs::nfs_v4:truenfs::nfs_v4_idmap_domain:%{::domain}nfs::nfs_v4_export_root:'/share'nfs::nfs_v4_export_root_clients:'192.168.0.0/24(rw,fsid=root,insecure,no_subtree_check,async,no_root_squash)'nfs::nfs_exports_global:/var/www:{}/var/smb:{}

Hiera Client Role:

classes:    -nfsnfs::client_enabled:truenfs::nfs_v4_client:truenfs::nfs_v4_idmap_domain:%{::domain}nfs::nfs_v4_mount_root:'/share'nfs::nfs_server:'nfs-server-fqdn'

Puppet:

nodeserver {    hiera_include('classes')$nfs_exports_global = hiera_hash('nfs::nfs_exports_global',false)$defaults_nfs_exports = {ensure=>'mounted',clients=>'192.168.0.0/24(rw,insecure,no_subtree_check,async,no_root_squash)',nfstag=>$::fqdn,    }if$nfs_exports_global {      create_resources('::nfs::server::export',$nfs_exports_global,$defaults_nfs_exports)    }  }nodeclient {    hiera_include('classes')$nfs_server = hiera('nfs::nfs_server',false)if$nfs_server {      Nfs::Client::Mount <<| nfstag ==$nfs_server |>>    }  }

• nfs: Main class, includes all other classes

• nfs::client::mount: Handles all mounts on a nfs client.
• nfs::server::export: Handles all nfs exports on a nfs server.

• nfs::client: Includes all relevant classes for configuring as a client.

• nfs::client::config: Handles the configuration files.

• nfs::client::package: Handles the packages.

• nfs::client::service: Handles the services.

• nfs::server: Includes all relevant classes for configuring as a server.

• nfs::server::config: Handles the configuration files.

• nfs::server::package: Handles the packages.

• nfs::server::service: Handles the services.

• nfs::params: Includes all os specific parameters.

• nfs::bindmount: Creates the bindmounts of nfs 3 exports.
• nfs::nfsv4_bindmount: Creates the bindmounts of nfs 4 exports.
• nfs::create_export: Creates the nfs exports.
• nfs::mkdir: Creates directories recursive.

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

String. Controls if the managed resources shall bepresent orabsent. If set toabsent:

• The managed software packages are being uninstalled.
• Any traces of the packages will be purged as good as possible. This mayinclude existing configuration files. The exact behavior is providerdependent. Q.v.:
  • Puppet type reference: {package, "purgeable"}[http://j.mp/xbxmNP]
  • {Puppet's package provider source code}[http://j.mp/wtVCaL]
• System modifications (if any) will be reverted as good as possible(e.g. removal of created users, services, changed log settings, ...).
• This is thus destructive and should be used with care.Defaults topresent.

Boolean. If set totrue, this module will configure the nodeto act as a nfs server.

Boolean. If set totrue, this module will configure the nodeto act as a nfs client, you can use the exported mount resourcesfrom configured servers.

Boolean. If set tofalse, this module will not export anyresources as storeconfigs. Defaults totrue.

Boolean. If set totrue, this module will use nfs version 4for exporting and mounting nfs resources. It defaults totrue.

Boolean. If set totrue, this module will use nfs version 4for mounting nfs resources. If set tofalse it will use nfsversion 3 to mount nfs resources. It defaults totrue.

String. It defines the location of the file with the nfs export resources usedby the nfs server.

String. It defines the location of the file with the idmapd settings.

String. It defines the location of the file with the nfs settings.

Boolean. It defines if the packages should be managed through this module

Array. It defines the packages needed to be installed for acting asa nfs server

String. It defines the packages state - any of present, installed,absent, purged, held, latest

Array. It defines the packages needed to be installed for acting asa nfs client

String. It defines the packages state - any of present, installed,absent, purged, held, latest

Boolean. Defines if module should manage server_service

Boolean. Defines if module should manage server_servicehelper

Boolean. Defines if module should manage client_service

String. It defines the servicename of the nfs server service

Boolean. It defines the service parameter ensure for nfs server services.

Boolean. It defines the service parameter enable for nfs server service.

Boolean. It defines the service parameter hasrestart for nfs server service.

Boolean. It defines the service parameter hasstatus for nfs server service.

String. It defines the service parameter restart for nfs server service.

Array. It defines the service helper like idmapd for servers configured withnfs version 4.

Nested Hash. It defines the servicenames need to be started when acting as a nfs client

Nested Hash. It defines the servicenames need to be started when acting as a nfs clientversion 4.

Boolean. It defines the service parameter hasrestart for nfs client services.

Boolean. It defines the service parameter hasstatus for nfs client services.

Array. It defines the Augeas parameter added indefaults_file when acting as a nfsversion 4 client.

String. It defines the name of the nfs filesystem, when adding entries to /etc/fstabon a client node.

String. It defines the options for the nfs filesystem, when adding entries to /etc/fstabon a client node.

String. It defines the name of the nfs version 4 filesystem, when adding entriesto /etc/fstab on a client node.

String. It defines the options for the nfs version 4filesystem, when adding entriesto /etc/fstab on a client node.

String. It defines the location where nfs version 4 exports should be bindmounted toon a server node. Defaults to/export.

String. It defines the clients that are allowed to mount nfs version 4 exports andincludes the option string. Defaults to*.${::domain}(ro,fsid=root,insecure,no_subtree_check,async,root_squash).

String. It defines the location where nfs version 4 clients find the mount rooton a server node. Defaults to/srv.

String. It defines the name of the idmapd domain setting inidmapd_file neededto be set to the same value on a server and client node to do correct uid and gidmapping. Defaults to$::domain.

Boolean. It defines if the module should create a bindmount for the export.Defaults totrue.

Boolean. If true, sets NEED_GSSD=yes in /etc/defauls/nfs-common, usable on Debian/Ubuntu

Boolean. If true enable rpc-gssd service.

String. Options for rpc-gssd service. Defaults to''

Boolean. If enabled, workaround for passing gssd_options which is broken on Debian 9. Usable only on Debian 9

String or Array. 'Local-Realms' option for idmapd. Defaults to''

Integer. 'Cache-Expiration' option for idmapd. Defaults to0 - unused.

Boolean. Enable setting Nobody mapping in idmapd. Defaults tofalse.

String. 'Nobody-User' option for idmapd. Defaults tonobody.

String. 'Nobody-Group' option for idmapd. Defaults tonobody ornogroup.

String. It defines the location of the file with the rpcbind config.

String. It defines the name of env variable that holds the rpcbind config. E.g. OPTIONS for Debian

String. Options for rpcbind service.

The following parameters are available in the::nfs::client::mount define:

String. Sets the ip address of the server with the nfs export

String. Sets the name of the nfs share on the server

String. Sets the ensure parameter of the mount.

String. Sets the remounts parameter of the mount.

String. Sets the atboot parameter of the mount.

String. Sets the mount options for a nfs version 4 mount.

String. Sets the mount options for a nfs mount.

String. When not undef it will create a bindmount on the nodefor the nfs mount.

String. Sets the nfstag parameter of the mount.

Boolean. When set to true, it uses nfs version 4 to mount a share.

String. Set owner of mount dir

String. Set group of mount dir

String. Set mode of mount dir

String. Overwrite mount root if differs from server config

The following parameters are available in the::nfs::server::export define:

String. Sets the allowed clients and options for the export in the exports file.Defaults tolocalhost(ro)

String. Sets the bind options setted in /etc/fstab for the bindmounts created.Defaults torbind. When you have any submounts in your exported folders,the rbind option will submount them in the bindmount folder. You have to set the crossmnt option in your nfs export to have the submounts from rbind availableon your client. Your export should look like this:

nodeclient {nfs::server::export {'/home':ensure=>'mounted',clients=>'*(rw,insecure,no_subtree_check,async,no_root_squash,crossmnt)',  }}

String. If enabled the mount will be created. Defaults tomounted

String. Sets the remounts parameter of the mount.

String. Sets the atboot parameter of the mount.

String. Sets the mount options for a nfs version 4 exported resource mount.

String. Sets the mount options for a nfs exported resource mount.

String. When not undef it will create a bindmount on the nodefor the nfs mount.

String. Sets the nfstag parameter of the mount.

String. Sets the mountpoint the client will mount the exported resource mount on. If undefit defaults to the same path as on the server

String. Sets the owner of the exported directory

String. Sets the group of the exported directory

String. Sets the permissions of the exported directory.

puppetlabs/stdlib >= 4.5.0puppetlabs/concat >= 1.1.2

facter > 1.6.2puppet > 3.2.0

augeas

If you want to have specific package versions installed you may manage the needed packages outside of thismodule (use manage_packages => false). It is only tested to use 'present', 'installed', 'absent','purged', 'held' and 'latest' as argument for the parameters server_package_ensure and client_package_ensure.

Derdanne modules are open projects. So if you want to make this module even better,you can contribute to this module onGithub.

Before pushing PRs to Github i would recommend you to test your work locally. So you can ensure all test buildson Travis CI were passing. I have prepared an easy way to test your code locally with the help of Docker.

For running the complete static code analysis, it is sufficient to run amake test-all.

I have set some defaults which you can change by setting the following environment variables.

Changes the puppet version which will be used for the tests. Defaults to6.0.

Sets strict variables on or off. Defaults toyes.

Sets the ruby version which will be used for the tests. Defaults to2.4.1.

Sets the beaker docker target host. Defaults toubuntu-20.04.

Sets the puppet version for acceptance tests. Defaults topuppet6.

You can run the following commands to setup and run the testsuite on your local machine.

Build a docker image with a Ruby version which is not available on Docker hub. Check outhttps://hub.docker.com/r/derdanne/rvm/ to see if i have already prepared a rvm build for the ruby versionyou want to test. Take a look at the Dockerfile located inspec/local-testing if you want to customizeyour builds.

Pull a prebuild rvm docker image with the Ruby version defined in the variableRVM.

Install all needed gems locally tovendor/bundle.

Run linting of metadata.

Run puppet lint tests.

Run syntax tests.

Run rspec puppet tests.

Run rubocop tests.

Run the whole testsuite.

Run puppetlabs beaker rspec tests.

This module based on Harald Skoglundharaldsk@redpill-linpro.com fromhttps://github.com/haraldsk/puppet-module-nfs/ but has been fundementally refactored

This plugin was originally authored by Daniel Klockenkaemperdk@marketing-factory.de.The maintainer preferred that Vox Pupuli take ownership of the module for future improvement and maintenance.Existing pull requests and issues were transferred over, please fork and continue to contribute here instead of Camptocamp.

Previously:https://github.com/derdanne/puppet-nfs