Documentation
Table of Contents
Description
This module is a SIMP Puppet profile for setting up common NFS configurations as supported by the SIMP ecosystem
This is a SIMP module
This module is a component of the System Integrity Management Platform, a compliance-management framework built on Puppet.
If you find any issues, they may be submitted to our bug tracker.
This module is optimally designed for use within a larger SIMP ecosystem, but it can be used independently:
- When included within the SIMP ecosystem, security compliance settings will be managed from the Puppet server.
- If used independently, all SIMP-managed security subsystems are disabled by
default and must be explicitly opted into by administrators. Please review
the parameters in
simp/simp_options
for details.
Setup
What simp_nfs affects
This module provides commonly used configurations for NFS server and client systems.
Usage
Serve NFS Home Directories over Stunnel
To export home directories for your users, over an Stunnel encrypted connection, use the following code and Hiera data:
include 'simp_nfs'
---
simp_options::stunnel: true
simp_nfs::export_home_dirs: true
Mount NFS Home Directories
To mount your exported home directories, over an Stunnel encrypted connection, use the following code and Hiera data:
include 'simp_nfs'
---
simp_options::stunnel: true
simp_nfs::home_dir_server : <your NFS server IP>
Mount Home NFS Directories on another NFS server
To mount home directories on another NFS server do not include the simp_nfs
class. This will try to call the nfs
class a second time. Instead
create a site manifest and call the simp_nfs::mount::home
class directly.
Note: Use the port parameter if you are using stunnel and set it to a different
port then the one the local NFS server is using.
class mounthome {
class { simp_nfs::mount::home:
nfs_server => $home_server,
port => 12049,
autodetect_remote => false
}
}
include mounthome
Reference
See REFERENCE.md for details.
Known Issues
The autofs
package that was released with CentOS 7.3 (5.0.7-56)
worked properly over a stunnel
connection.
The release shipped with with CentOS 7.4 (5.0.7-69) prevents any connection
from happening to the local stunnel
process and breaks mounts to remote systems
over stunnel
connections.
The release that ship with CentOS 7.6 (5.0.7-99) has fixed the issue.
To use NFS over stunnel
and automount
directories with old
CentOS 7 releases, you must use the appropriate autofs
package.
To determine what version of autofs
is installed, run automount -V
.
To force the package to the desired version:
- Make sure the package is available via your package-management facility then set the package version in Hiera data:
autofs::autofs_package_ensure: '5.0.7-99'
- Alternatively, ensure that the latest packages are available and set the following:
autofs::autofs_package_ensure: 'latest'
The associated bug reports can be found at:
Limitations
This is a SIMP Profile. It will not expose all options of the underlying modules, only the ones that are conducive to a supported SIMP infrastructure. If you need to do things that this module does not cover, you may need to create your own profile or inherit this profile and extend it to meet your needs.
SIMP Puppet modules are generally intended for use on Red Hat Enterprise Linux
and compatible distributions, such as CentOS. Please see the
metadata.json
file for the most up-to-date list of
supported operating systems, Puppet versions, and module dependencies.
Development
Please read our Contribution Guide.
Acceptance tests
This module includes Beaker acceptance tests using the SIMP Beaker Helpers. By default the tests use Vagrant with VirtualBox as a back-end; Vagrant and VirtualBox must both be installed to run these tests without modification. To execute the tests run the following:
bundle install
bundle exec rake beaker:suites
Please refer to the SIMP Beaker Helpers documentation for more information.
Reference
Table of Contents
Classes
simp_nfs
: A SIMP Profile for common NFS configurationssimp_nfs::create_home_dirs
: Adds a script to create user home directories for directory serversimp_nfs::export::home
: Configures an NFS server to share centralized home directories via NFSv4simp_nfs::mount::home
: Set up anNFS4
client to point to mount your remote home directories
Classes
simp_nfs
A SIMP Profile for common NFS configurations
Parameters
The following parameters are available in the simp_nfs
class.
export_home_dirs
Data type: Boolean
Set up home directory exports for this system
- The
simp_options::trusted_nets
parameter will govern what clients may connect to the share by default. - Further configuration for home directory exports can be tweaked via the
parameters in
simp_nfs::export_home
Default value: false
home_dir_server
Data type: Optional[Simplib::Ip]
If set, specifies the server from which you want to mount NFS home directories for your users
- If
$export_home_dirs
is also set, this class will assume that you want to mount on the local server if this is set at all - Further configuration for the home directory mounts can be tweaked via
the parameters in
simp_nfs::mount::home
Default value: undef
autodetect_remote
Data type: Boolean
Use inbuilt autodetection to determine if the local system is the server from which we should be mouting directories
- Generally, you should set this to
false
if you have issues with the system mounting to127.0.0.1
when your home directories are actually on another system
Default value: true
use_autofs
Data type: Boolean
Use autofs
for home directory mounts
Default value: true
simp_nfs::create_home_dirs
by pulling users from LDAP
https://github.com/simp/pupmod-simp-simp_nfs/graphs/contributors
Parameters
The following parameters are available in the simp_nfs::create_home_dirs
class.
uri
Data type: Array[Simplib::URI]
The uri(s) of the LDAP servers
Default value: simplib::lookup('simp_options::ldap::uri')
base_dn
Data type: String
The root DN that should be used when searching for entries
Default value: simplib::lookup('simp_options::ldap::base_dn')
bind_dn
Data type: String
The DN to use when binding to the LDAP server
Default value: simplib::lookup('simp_options::ldap::bind_dn')
bind_pw
Data type: String
The password to use when binding to the LDAP server
Default value: simplib::lookup('simp_options::ldap::bind_pw')
export_dir
Data type: Stdlib::Absolutepath
The location of the home directories being exported
- This location must be a puppet managed
File
resource - See the
simp_nfs::export_home
class for an example
Default value: '/var/nfs/home'
skel_dir
Data type: Stdlib::Absolutepath
The location of sample skeleton files for user directories
Default value: '/etc/skel'
ldap_scope
Data type: Enum['one','sub','base']
The search scope to use
Default value: 'one'
port
Data type: Simplib::Port
The target port on the LDAP server
- If none specified, defaults to
389
for regular andstart_tls
connections, and636
for legacy SSL connections
Default value: 389
tls
Data type: Enum['ssl','start_tls','none']
Whether or not to enable SSL/TLS for the connection
-
ssl
LDAPS
on port636
unless differentport
specified- Uses
simple_tls
; No validation of the LDAP server's SSL certificate is performed
- Uses
-
start_tls
- Start TLS on port
389
unless differentport
specified
- Start TLS on port
-
none
- LDAP without encryption on port
389
unless differentport
specified
- LDAP without encryption on port
Default value: 'start_tls'
quiet
Data type: Boolean
Whether or not to print potentially useful warnings
Default value: true
syslog_facility
Data type: Simplib::Syslog::CFacility
The syslog facility at which to log, must be Ruby syslog
compatible
Default value: 'LOG_LOCAL6'
syslog_severity
Data type: Simplib::Syslog::CSeverity
The syslog severity at which to log, must be Ruby syslog
compatible
Default value: 'LOG_NOTICE'
strip_128_bit_ciphers
Data type: Boolean
On EL6 systems, all 128-bit ciphers will be removed from tls_cipher_suite
- This is due to a bug in the LDAP client libraries that does not appear to honor the order of the SSL ciphers and will attempt to connect with 128-bit ciphers and not use stronger ciphers when those are present. This breaks connections to securely configured LDAP servers.
Default value: true
tls_cipher_suite
Data type: Array[String[1]]
The TLS ciphers that should be used for the connection to LDAP
- Presently only affects EL6 systems
Default value: simplib::lookup('simp_options::openssl::cipher_suite', { 'default_value' => ['DEFAULT','!MEDIUM'] })
package_ensure
Data type: String
The ensure status of the rubygem-net-ldap package
Default value: simplib::lookup('simp_options::package_ensure', { 'default_value' => 'installed' })
simp_nfs::export::home
Sets up the export root at ${data_dir}/nfs/exports
and then adds
${data_dir}/nfs/home
and submounts it under ${data_dir}/nfs/exports
.
- The export root is the root NFS share directory for the NFSv4 pseudo filesystem. Each directory below that NFS share should be a bind mount to a directory on the NFS server.
- The exported home directory should be mounted as
$nfs_server:/home
from your clients, where$nfs_server
is the IP address of the NFS server.
Examples
NFS Server System Hieradata
---
nfs::is_server : true
simp::classes :
- simp_nfs::export::home
NFS Client Home Mount
---
simp_nfs::mount::home::nfs_server : <nfs_server_ip>
simp::classes :
- simp_nfs::mount::home
Parameters
The following parameters are available in the simp_nfs::export::home
class.
data_dir
Data type: Stdlib::Absolutepath
Default value: '/var'
trusted_nets
Data type: Simplib::Netlist
The networks that are allowed to mount this space
Default value: simplib::lookup('simp_options::trusted_nets', { 'default_value' => ['127.0.0.1'] })
sec
Data type: Array[Enum['none','sys','krb5','krb5i','krb5p']]
An Array of sec modes for the export.
Default value: ['sys']
create_home_dirs
Data type: Boolean
Automatically create user home directories from LDAP data
Default value: simplib::lookup('simp_options::ldap', { 'default_value' => false })
simp_nfs::mount::home
If this system is also the NFS server, you need to set
nfs::client::is_server
to true
or set
simp_nfs::mount::home::nfs_server
to 127.0.0.1
.
Parameters
The following parameters are available in the simp_nfs::mount::home
class.
nfs_server
Data type: Simplib::IP
The NFS server to which you will be connecting
- If you are the server, please make sure that this is
127.0.0.1
remote_path
Data type: Stdlib::Absolutepath
The NFS share that you want to mount
Default value: '/home'
local_home
Data type: Stdlib::Absolutepath
The local base for home directories
-
Most sites will want this to be
/home
but some may opt for something like/exports/home
or the like. -
Top level directories will not be automatically managed
Default value: '/home'
port
Data type: Optional[Simplib::Port]
The NFS port to which to connect
Default value: undef
sec
Data type: Enum['sys','krb5','krb5i','krb5p']
The sec mode for the mount
- Only valid with NFSv4
Default value: 'sys'
options
Data type: Optional[String]
The mount options string that should be used
- fstype and port will already be set for you
Default value: undef
at_boot
Data type: Boolean
Ensure that this mount is mounted at boot time
- Has no effect if
$use_autofs
is set
Default value: true
autodetect_remote
Data type: Boolean
Use inbuilt autodetection to determine if the local system is the server from which we should be mouting directories
- Generally, you should set this to
false
if you have issues with the system mounting to127.0.0.1
when your home directories are actually on another system
Default value: true
use_autofs
Data type: Boolean
Enable automounting with Autofs
Default value: true
- Fri Oct 16 2020 Liz Nemsick lnemsick.simp@gmail.com - 1.0.1
- Fixed:
- Removed hostname as a possible entry for the NFS server in the sample code in the README. Specifying the NFS server as a hostname is no longer supported due to limitations of firewalld.
- Replaced deprecated 'classes' with 'simp:classes' in manifest documentation.
- Updated:
- In the README, removed EL6 from the autofs known issue discussion and added more details on how to work around the problem.
- Tue Mar 31 2020 Jeanne Greulich jeannegreulich@onyxpoint.com - 1.0.0
- Added support for EL8
- Removed support for EL6
- Updated to use pupmod-simp-nfs release 7.0.0
- Only accepts IP Adrresses for nfs server because firewalld needs IP Address.
- Wed Jul 03 2019 Trevor Vaughan tvaughan@onyxpoint.com - 0.2.0
- Documentation update
- Fix acceptance tests
- Remove pinning of autofs package
- Fri Jun 28 2019 Brandon Riden brandon.riden@onyxpoint.com - 0.2.0
- Add Compliance Engine 2.0 compatible data and tests
- Tue Apr 09 2019 Joseph Sharkey shark.bruhaha@gmail.com - 0.1.1
- Remove Elasticsearch and Grafana GPG Keys
- Updated tests in support of puppet6, and removed puppet4 support
- Mon Mar 04 2019 Liz Nemsick lnemsick.simp@gmail.com - 0.1.1
- Use simplib::nets2cidr in lieu of deprecated Puppet 3 nets2cidr
- Updated a URLs in the README.md
- Mon Nov 05 2018 Liz Nemsick lnemsick-simp@gmail.com - 0.1.0
- Update badges in README.md
- Thu Sep 13 2018 Nick Miller nick.miller@onyxpoint.com - 0.1.0
- Add support for Puppet 5 and OEL
- Upped stdlib dep to support version 5
- Add reference.md
- Added $simp_nfs::create_home_dirs::package_ensure parameter
- Changed the package from 'latest' to 'installed'
- It will also respect
simp_options::package_ensure
- Fri Sep 07 2018 Liz Nemsick lnemsick.simp@gmail.com - 0.1.0
- Drop Hiera 4 support
- Thu Jun 14 2018 Nick Miller nick.miller@onyxpoint.com - 0.0.5
- Update systemd fixtures and CI assets
- Wed Apr 18 2018 Trevor Vaughan tvaughan@onyxpoint.com - 0.0.5
- Allow users to properly disable autofs
- Added parameter, autodetect_remote, that allows users to disable the logic that determines if system is an NFS server and mounts directories locally. This allows the mounting of home directories to another NFS server.
- Fri Sep 01 2017 Jeanne Greulich jeannegreulich@onyxpoint.com - 0.0.4
- documented known bug and work around in CentOS 6.9 in the README file.
- Tue Apr 11 2017 Nick Markowski nmarkowski@keywcorp.com - 0.0.3
- Updated create_home_directories to handle multiple URIs
- Update puppet requirement in metadata.json
- Fri Apr 07 2017 Trevor Vaughan tvaughan@onyxpoint.com - 0.0.2
- Added the ability to override ciphers in the create_home_directories script for EL6 since the cipher order does not happen from strongest to weakest and breaks secure LDAP connections
- Added a check for create_home_directories to ensure that directories are not archived if the server doesn't respond for TLS reasons.
- Tue Jan 03 2017 Trevor Vaughan tvaughan@onyxpoint.com - 0.0.1
- Initial release
Dependencies
- simp/nfs (>= 7.0.0 < 8.0.0)
- simp/simplib (>= 4.1.0 < 5.0.0)
- puppetlabs/stdlib (>= 4.9.0 < 7.0.0)
simp_rsyslog - A SIMP Puppet Profile for standard Rsyslog configurations Per Section 105 of the Copyright Act of 1976, these works are not entitled to domestic copyright protection under US Federal law. The US Government retains the right to pursue copyright protections outside of the United States. The United States Government has unlimited rights in this software and all derivatives thereof, pursuant to the contracts under which it was developed and the License under which it falls. --- Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.