nfs

Table of Contents

1. Overview - What is the nfs module?
2. Module Description - What does this module do?
3. Setup - The basics of getting started with nfs
   • Simple mount an nfs share
   • NFSv3 server and client
   • NFSv3 multiple exports, servers and multiple node
   • NFSv4 Simple example
   • NFSv4 insanely overcomplicated reference
   • A large number of clients
4. Usage - The classes and defined types available for configuration
   • Class: nfs::server
   • Defined Type: nfs::server::export
   • Class: nfs::client
   • Defined Type: nfs::client::mount
5. Requirements
6. Limitations - OS compatibility, etc.
7. Contributing to the graphite module

Overview

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

Module Description

This module can be used to simply mount nfs shares on a client or to configure your nfs servers. It can make use of storeconfigs on the puppetmaster to get its resources.

Setup

What nfs affects:

• packages/services/configuration files for NFS usage
• can be used with puppet storage

Simple mount nfs share

This example mounts a nfs share on the client, with NFSv3

include '::nfs::client'

::nfs::client::mount { '/mnt/mymountpoint':
  server  => 'nfsserver.my.domain',
  share   => '/share/on/server',
  options => 'rw',
}

NFSv3 server and client

This will export /data/folder on the server and automagically mount it on client. You need storeconfigs/puppetdb for this to work.

node server {
  include nfs::server

  ::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 server.

node client {
  include '::nfs::client'
  Nfs::Client::Mount <<| |>> 
}

NFSv3 multiple exports, servers and multiple node

  node server1 {
    include '::nfs::server'
    ::nfs::server::export{ 
      '/data_folder':
        ensure  => 'mounted',
        clients => '10.0.0.0/24(rw,insecure,async,no_root_squash) localhost(rw)'
      # exports /homeexport and mounts them om /srv/home on the clients
      '/homeexport':
        ensure  => 'mounted',
        clients => '10.0.0.0/24(rw,insecure,async,root_squash)',
        mount   => '/srv/home'
    }
  }

  node server2 {
    include '::nfs::server'
    # ensure is passed to mount, which will make the client not mount it
    # the directory automatically, just add it to fstab
    ::nfs::server::export{ 
      '/media_library':
        ensure  => 'present',
        nfstag     => 'media'
        clients => '10.0.0.0/24(rw,insecure,async,no_root_squash) localhost(rw)'
    }
  }

  node client {
    include '::nfs::client'
    Nfs::Client::Mount <<| |>>; 
  }

  # Using a storeconfig override, to change ensure option, so we mount
  # all shares
  
  node greedy_client {
    include '::nfs::client'
    Nfs::Client::Mount <<| |>> {
      ensure => 'mounted'
    }
  }


  # only the mount tagged as media 
  # also override mount point
  node media_client {
    include '::nfs::client'
    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.html
  node single_server_client {
    include '::nfs::client'
    Nfs::Client::Mount <<| server == 'server1' |>> {
      ensure => 'absent',
    }
  }

NFSv4 Simple example

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.

  node server {
    class { 'nfs::server':
      nfs_v4 => true,
      nfs_v4_export_root_clients =>
        '10.0.0.0/24(rw,fsid=root,insecure,no_subtree_check,async,no_root_squash)'
    }
    nfs::server::export{ '/data_folder':
      ensure  => 'mounted',
      clients => '10.0.0.0/24(rw,insecure,no_subtree_check,async,no_root_squash) localhost(rw)'
    }
  }

Set ownership and permissions on the folder being exported

  node server {
    nfs::server::export{ '/data_folder':
      ensure  => 'mounted',
      clients => '10.0.0.0/24(rw,insecure,no_subtree_check,async,no_root_squash) localhost(rw)',
      owner => 'root',
      group => 'root',
      perms => '0755',
    }
  }

By default, mounts are mounted in the same folder on the clients as they were exported from on the server

node client {
  class { 'nfs::client':
    nfs_v4 = true,
    nfs_v4_export_root_clients =>
      '10.0.0.0/24(rw,fsid=root,insecure,no_subtree_check,async,no_root_squash)'
  }
  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.

node client2 {
  $server = 'server'

  class { '::nfs::client':
    nfs_v4 = true,
  }
  Nfs::Client::Mount::Nfs_v4::Root <<| server == $server |>> { 
    mount => "/srv/$server",
  }
}

NFSv4 insanely overcomplicated reference

Just to show you, how complex we can make things ;-)

  # and on individual nodes.
  node server {
    class { 'nfs::server':
      nfs_v4              => true,
      # Below are defaults
      nfs_v4_idmap_domain => $::domain,
      nfs_v4_export_root  => '/export',
      # Default access settings of /export root
      nfs_v4_export_root_clients =>
        "*.${::domain}(ro,fsid=root,insecure,no_subtree_check,async,root_squash)"
    }
    
    nfs::server::export{ '/data_folder':
      # These are the defaults
      ensure  => 'mounted',
      # rbind or bind mounting of folders bindmounted into /export 
      # google it
      bind    => 'rbind',
      # everything below here is propogated by to storeconfigs
      # to clients
      #
      # Directory where we want export mounted on client 
      mount     => undef, 
      remounts  => false,
      atboot    => false,
      #  Don't remove that option, but feel free to add more.
      options   => '_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     => undef,
      # copied directly into /etc/exports as a string, for simplicity
      clients => '10.0.0.0/24(rw,insecure,no_subtree_check,async,no_root_squash)'
  }

  node client {
    class { 'nfs::client':
      nfs_v4              => 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 <<| # filter goes here # |>> {
      # Directory where we want export mounted on client 
      mount     => undef, 
      remounts  => false,
      atboot    => false,
      #  Don't remove that option, but feel free to add more.
      options   => '_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,    
    }
  }

A large number of clients

If a server has many clients it's a bit of a mess to put them all in a single 'clients' option for nfs::server::export. Instead, you can put them in a array or hash and use the mk_client_list function to generate the clients string.

$nfs_clients = [
    'common-*.loc.dom', 
    'hostb.loc.dom', 
    '10.0.9.0/24']

nfs::server::export { '/data':
    clients => mk_client_list($nfs_clients, {}, "ro"),
    # Which will produce:
    # 'common-*.loc.dom(ro) hostb.loc.dom(ro) 10.0.9.0/24(ro)'
    ...
}

In this case mk_client_list generates the string: `

The second option is a hash of client -> options. The third option is the default in case a client doesn't have options specified in the hash. In the above example none of the clients had specific settings, so they were all given the default options of ro.

$nfs_clients = [
    'common-*.loc.dom', 
    'hostb.loc.dom', 
    '10.0.9.0/24']

$nfs_client_options = {
    'hostb.loc.dom'     => 'rw,no_root_squash'}

nfs::server::export {'/data':
    # Use the stdlib keys function to get the array of keys from our hash.
    clients => mk_client_list($nfs_clients, $nfs_client_options, 'ro'),
    # Which will produce:
    # 'common-*.loc.dom(ro) hostb.loc.dom(rw,no_root_squash) 10.0.9.0/24(ro)'
    ...
}

You can also give options to each host in a hash, and then use the stdlib keys() function to extract the client array from the hash: mk_client_list(keys($client_hash), $client_hash, '')

Usage

Class: nfs::server

Set up NFS server and exports. NFSv3 and NFSv4 supported.

Parameters within nfs::server:

service_manage (true)

Should this class manage the services behind nfs? Set this to false if you are managing the service in another way (e.g. pacemaker).

package_ensure (installed)

Allow to update or set to a specific version the nfs server packages.

nfs_v4 (optional)

NFSv4 support. Will set up automatic bind mounts to export root. Disabled by default.

nfs_v4_export_root (optional)

Export root, where we bind mount shares, default /export

nfs_v4_idmap_domain (optional)

Domain setting for idmapd, must be the same across server and clients. Default is to use $domain fact.

exports (optional)

If set, this attribute will be used to construct nfs::server::export resources. You can use you ENC or hiera to provide the hash of nfs::server::export resources definitions:

nfs::server::exports:
  /mnt/something:
    ensure: mounted
    clients: '*(fsid=0,ro,insecure,async,all_squash,no_subtree_check,mountpoint=/mnt/something)'

Examples

class { '::nfs::server':
  nfs_v4                      => true,
  nfs_v4_export_root_clients  => "*.${::domain}(ro,fsid=root,insecure,no_subtree_check,async,root_squash)",
  # Generally parameters below have sane defaults.
  nfs_v4_export_root          => "/export",
  nfs_v4_idmap_domain         => $::domain,
}

Defined Type: nfs::server::export

Set up NFS export on the server (and stores data in configstore)

Parameters within nfs::server::export:

v3_export_name (optional)

Default is $name. Usally you do not set it explicit.

v4_export_name (optional)

Default results from $name. Usally you do not set it explicit.

ensure (optional)

Default is 'mounted'

bind (optional)

Default is 'rbind'. rbind or bind mounting of folders bindmounted into /export. Google it!

Following parameteres are propogated by to storeconfigs to clients

mount (optional)

Default is undef. This means client mount path is the same as server export path. Directory where we want export mounted on client

remounts (optional)

Default is false.

atboot (optional)

Default is false.

options (optional)

Default is '_netdev'. Don't remove that option, but feel free to add more.

bindmount (optional)

Default is undef. If set will mount share inside /srv (or overridden mount_root) and then bindmount to another directory elsewhere in the fs - for fanatics.

nfstag (optional)

Default is undef. Used to identify a catalog item for filtering by storeconfigs on clients.

clients (optional)

Default is 'localhost(ro)'. Copied directly into /etc/exports as a string, for simplicity.

server (optional)

Default is $::clientcert. Used to specify a other ip/name for the client to connect to. Usefull in machines with multiple ip addresses or network interfaces

Example

::nfs::server::export { '/media_library':
  nfstag  => 'media'
  clients => '10.0.0.0/24(rw,insecure,async,no_root_squash) localhost(rw)'
}

Class: nfs::client

Set up NFS client and mounts. NFSv3 and NFSv4 supported.

Parameters within nfs::client:

package_ensure (installed)

Allow to update or set to a specific version the nfs client packages.

nfs_v4

NFSv4 support. Disabled by default.

nfs_v4_mount_root

Mount root, where we mount shares, default /srv

nfs_v4_idmap_domain

Domain setting for idmapd, must be the same across server and clients. Default is to use $::domain fact.

mounts (optional)

If set, this attribute will be used to construct nfs::client::mount resources. You can use you ENC or hiera to provide the hash of nfs::client::mount resources definitions:

nfs::client::mounts:
  /mnt/test:
    ensure: 'mounted'
    server: '192.0.2.100'
    share:  '/export/data'

Example

class { '::nfs::client':
  nfs_v4              => true,
  # Generally parameters below have sane defaults.
  nfs_v4_mount_root   => '/srv',
  nfs_v4_idmap_domain => $::domain,
}

Defined Type: nfs::client::mount

Set up NFS mount on client.

Parameters within nfs::client::mount:

server

FQDN or IP of the NFS server.

share

Name of share to be mounted.

ensure (optional)

Default is 'mounted'.

mount (optional)

Default is $title of defined type. Defines mountpoint of the share on the client.

remounts (optional)

Default is false.

atboot (optional)

Default is false.

options (optional)

Default is '_netdev'. Don't remove that option, but feel free to add more.

bindmount (optional)

Default is undef. If set will mount share inside /srv (or overridden mount_root) and then bindmount to another directory elsewhere in the fs - for fanatics.

nfstag (optional)

Default is undef. Used to identify a catalog item for filtering by storeconfigs on clients.

owner (optional)

Default is 'root'. Sets owner of mountpoint directory. This is applied to the directory on every run, which means it is used both on the base mountpoint creation when unmounted, and also once mounted on the target NFS server and thus all servers accessing the same share.

group (optional)

Default is root. Sets group of mountpoint directory. This is applied to the directory on every run, which means it is used both on the base mountpoint creation when unmounted, and also once mounted on the target NFS server and thus all servers accessing the same share.

perm (optional)

Default is '0755'. Sets mode of mountpoint directory. This has changed from previous versons which used '0777' (world writable). This is applied to the directory on every run, which means it is used both on the base mountpoint creation when unmounted, and also once mounted on the target NFS server and thus all servers accessing the same share.

Requirements

If you want to have the full potential of this module its recommend to have storeconfigs enabled.

Limitations

##Contributing

Echocat modules are open projects. So if you want to make this module even better, you can contribute to this module on Github.

This module is forked/based on Harald Skoglund haraldsk@redpill-linpro.com from https://github.com/haraldsk/puppet-module-nfs/

Please read DEVELOP.md on how to contribute to this module.

2017-01-26 - 1.9.0 (Feature release)

Bugfixes:

• fix mountd thread number parameter for nfs server

Features:

• set specific version of nfs client packages with package_ensure
• allow client mounts to be defined in Hiera
• Ubuntu: support 16.04

2016-03-19 - 1.8.1 (Bugfix release)

Bugfixes:

• (60cfca6) #68 recognize newer releases of Amazon Linux
• (be6b4af) Debian: rpcmountdopts has double quotes

2016-01-18 - 1.8.0 (Feature release)

Warning: Requires puppetlabs-stdlib > =4.8.0 !

Features:

• (ba021e9) #62 Remove herculesteam/augeasproviders_shellvar dependency

2016-01-08 - 1.7.2 (Bugfix release)

Bugfixes:

• (174a9b4) #53 Debian do not stop (nonexisting) service, when using nfs-v3
• (21c2a1d) #54 #55 Debian/Ubuntu enable the idmapd service on boot, when using nfs-v3

2015-10-23 - 1.7.1 (Bugfix release)

Bugfixes:

• (cd47771) #49 Supporting kernel 4.x in recent Amazon Linux releases

2015-10-16 - 1.7.0 (Feature/Bugfixe release)

Features:

• (cf2d4f5) #37 #41 add optinal parameter exports for class server
• (70ea022) #42 add the ability to manage the services. See service_manage
• (1117238) #43 speed up puppet parser validate tests

Bugfixes:

• (426ad8f) #27 #44 add special config for ubuntu to fix service name bug for idmapd
• (f84c342) #45 ensure order of client class dependencies

2015-09-29 - 1.6.0 (Feature/Bugfixe release)

Features:

• Issue #30 Add ability to set owner,group,perms on server::export
• Issue #35 Enable mountd_port parameter for Red Hat.

Bugfixes:

• Fixed #28 Fix puppet dependency to puppetlabs-concat
• Fixed #32 #33 Fix service in EL7 that can not be enabled.
• Fixed #34 Fixed owner, group and perms on NFSv4 mount.

2015-06-05 - 1.5.0 (Feature/Bugfixe release)

Features:

• Issue #22 Make the name/ip of the server a config option in nfs::server::export
• Issue #24 More flexible nfsv4 export naming

Bugfixes:

• Fixed #20 fix client examples in README
• Fixed #21 Debian: fix service name fpr nfs v4
• Fixed #23 Default mount name in client::mount `should be undef, so it gets filled in the module
• Fixed #25 Fix tests for travis ci

2015-04-28 - 1.4.1 (Bugfixe release)

Bugfixes:

• Fixed #19 use of wrong variable for osfamily on servers

2015-04-22 - 1.4.0 (Feature/Bugfixe release)

Features:

• Issue #17 Add support for Amazon linux

Bugfixes:

• Fixed #16 revert default permissions from 0777 to 0755
• Fixed #18 problems with a host being client & server

2015-03-20 - 1.3.1 (Feature/Bugfixe release)

Features:

• Issue #11 Add function to easy handle large numer of clients (see README "A large number of clients")

Bugfixes:

• Fixed #13 RHEL 7: handle service enable correct
• Fixed #12 RHEL 7: ensure client mount works correct with undef mounts

2015-03-05 - 1.3.0 (Feature release)

Features:

• Allow mounting shares with the same name from different servers
• Add Scientific Linux CERN support

2015-02-16 - 1.2.1 (Bugfix release)

Bugfixes:

• ensure install dependencies for mount

2015-01-15 - 1.2.0 (Feature/Bugfix release)

Features:

• add support for gentoo
• add support for RHEL 7
• add support of puppet 3.x
• add possibility to set ownership of mountpoint
• lots of tests added

Behavior changes

• Parameter tag is now nfstag

2012-11.18 - 1.1.1

Original release of deprecated module haraldsk/nfs