(#86) Enforce permissions on created files

* Add attributes for enforcing ownership and permissions on created files
* Add data types to all class and defined type parameters
* Move documentation to Puppet Strings
* Add generated REFERENCE.md
* Add rspec tests for `kmod::option`, new parameters, etc.
* Bump stdlib dependency to 5.0.0 (for `Stdlib::Filemode` type)

Fixes #86

data/common.yaml

@@ -0,0 +1,6 @@
+---
+kmod::owner: 'root'
+kmod::group: 'root'
+kmod::directory_mode: '0755'
+kmod::file_mode: '0644'
+kmod::exe_mode: '0755'

lib/facter/kmod.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# @summary Return a hash of loaded kernel modules
+
 Facter.add(:kmods) do
   confine kernel: :linux
 

manifests/alias.pp

@@ -1,16 +1,25 @@
-# = Define: kmod::alias
+# @summary Manage kernel module aliases
 #
-# == Example
-#
-#     kmod::alias { 'bond0':
-#       source => 'bonding',
-#     }
+# @param source Name of the module to alias
+# @param ensure State of the alias
+# @param file File to manage
+# @param aliasname Name of the alias (defaults to the resource title)
+# @param owner Owner of managed file
+# @param group Group of managed file
+# @param mode Mode of managed file
 #
+# @example
+#   kmod::alias { 'bond0':
+#     source => 'bonding',
+#   }
 define kmod::alias (
-  $source,
-  $ensure     = 'present',
-  $file       = "/etc/modprobe.d/${name}.conf",
-  $aliasname  = $name,
+  String[1]                  $source,
+  Enum['present', 'absent']  $ensure    = 'present',
+  Stdlib::Unixpath           $file      = "/etc/modprobe.d/${name}.conf",
+  String[1]                  $aliasname = $name,
+  Optional[String[1]]        $owner     = undef,
+  Optional[String[1]]        $group     = undef,
+  Optional[Stdlib::Filemode] $mode      = undef,
 ) {
   include kmod
 
@@ -21,5 +30,8 @@
     category => 'alias',
     option   => 'modulename',
     value    => $source,
+    owner    => $owner,
+    group    => $group,
+    mode     => $mode,
   }
 }

manifests/blacklist.pp

@@ -1,24 +1,29 @@
+# @summary Set a kernel module as blacklisted.
 #
-# == Definition: kmod::blacklist
-#
-# Set a kernel module as blacklisted.
-#
-# Parameters:
-# - *ensure*: present/absent;
-# - *file*: optionally, set the file where the stanza is written.
-#
-# Example usage:
+# @param ensure State of the setting
+# @param file File to manage
+# @param owner Owner of managed file
+# @param group Group of managed file
+# @param mode Mode of managed file
 #
+# @example
 #   kmod::blacklist { 'pcspkr': }
-#
 define kmod::blacklist (
-  $ensure=present,
-  $file='/etc/modprobe.d/blacklist.conf',
+  Enum['present', 'absent']  $ensure = 'present',
+  Stdlib::Unixpath           $file   = '/etc/modprobe.d/blacklist.conf',
+  Optional[String[1]]        $owner  = undef,
+  Optional[String[1]]        $group  = undef,
+  Optional[Stdlib::Filemode] $mode   = undef,
 ) {
+  include kmod
+
   kmod::setting { "kmod::blacklist ${title}":
     ensure   => $ensure,
     module   => $name,
     file     => $file,
     category => 'blacklist',
+    owner    => $owner,
+    group    => $group,
+    mode     => $mode,
   }
 }

manifests/init.pp

@@ -1,24 +1,52 @@
+# @summary Ensures a couple of mandatory files are present before managing their content.
 #
-# == Class: kmod
-#
-# Ensures a couple of mandatory files are present before managing their
-# content.
-#
+# @param owner Default owner for all files (set via Hiera to allow defaults on all defined types)
+# @param group Default group for all files (set via Hiera to allow defaults on all defined types)
+# @param directory_mode Default mode for all directories (set via Hiera to allow defaults on all defined types)
+# @param file_mode Default mode for all regular files (set via Hiera to allow defaults on all defined types)
+# @param exe_mode Default mode for all executable files (set via Hiera to allow defaults on all defined types)
+# @param list_of_aliases Hash of [`kmod::alias`](#kmodalias) resources
+# @param list_of_blacklists Hash of [`kmod::blacklist`](#kmodblacklist) resources
+# @param list_of_installs Hash of [`kmod::install`](#kmodinstall) resources
+# @param list_of_loads Hash of [`kmod::load`](#kmodload) resources
+# @param list_of_options Hash of [`kmod::option`](#kmodoption) resources
+# @param modprobe_d Location of `modprobe.d` directory
+# @param modprobe_d_files Default files to create in `modprobe.d` directory
 #
+# @example
+#   include kmod
 class kmod (
-  Hash $list_of_aliases    = {},
-  Hash $list_of_blacklists = {},
-  Hash $list_of_installs   = {},
-  Hash $list_of_loads      = {},
-  Hash $list_of_options    = {},
+  # Defaults for these are in Hiera to enable using them as
+  # defaults in the various defined types via `lookup()`.
+  String[1]               $owner,
+  String[1]               $group,
+  Stdlib::Filemode        $directory_mode,
+  Stdlib::Filemode        $file_mode,
+  Stdlib::Filemode        $exe_mode,
+  Hash                    $list_of_aliases = {},
+  Hash                    $list_of_blacklists = {},
+  Hash                    $list_of_installs = {},
+  Hash                    $list_of_loads = {},
+  Hash                    $list_of_options = {},
+  Stdlib::Unixpath        $modprobe_d       = '/etc/modprobe.d',
+  Array[Stdlib::Unixpath] $modprobe_d_files = [
+    '/etc/modprobe.d/modprobe.conf',
+    '/etc/modprobe.d/aliases.conf',
+    '/etc/modprobe.d/blacklist.conf',
+  ],
 ) {
-  file { '/etc/modprobe.d': ensure => directory }
+  file { $modprobe_d:
+    ensure => directory,
+    owner  => $owner,
+    group  => $group,
+    mode   => $directory_mode,
+  }
 
-  file { [
-      '/etc/modprobe.d/modprobe.conf',
-      '/etc/modprobe.d/aliases.conf',
-      '/etc/modprobe.d/blacklist.conf',
-    ]: ensure => file,
+  file { $modprobe_d_files:
+    ensure => file,
+    owner  => $owner,
+    group  => $group,
+    mode   => $file_mode,
   }
 
   $list_of_aliases.each | $name, $data | {

manifests/install.pp

@@ -1,28 +1,33 @@
+# @summary Set a kernel module as installed
 #
-# == Definition: kmod::install
-#
-# Set a kernel module as installed.
-#
-# Parameters:
-# - *ensure*: present/absent;
-# - *command*: optionally, set the command associated with the kernel module;
-# - *file*: optionally, set the file where the stanza is written.
-#
-# Example usage:
+# @param ensure State of the setting
+# @param command Command associated with the kernel module
+# @param file File where the stanza is written
+# @param owner Owner of managed file
+# @param group Group of managed file
+# @param mode Mode of managed file
 #
+# @example
 #   kmod::install { 'pcspkr': }
-#
 define kmod::install (
-  $ensure=present,
-  $command='/bin/true',
-  $file="/etc/modprobe.d/${name}.conf",
+  Enum['present', 'absent']  $ensure  = 'present',
+  String[1]                  $command = '/bin/true',
+  Stdlib::Unixpath           $file    = "/etc/modprobe.d/${name}.conf",
+  Optional[String[1]]        $owner   = undef,
+  Optional[String[1]]        $group   = undef,
+  Optional[Stdlib::Filemode] $mode    = undef,
 ) {
+  include kmod
+
   kmod::setting { "kmod::install ${title}":
     ensure   => $ensure,
     module   => $name,
     file     => $file,
     category => 'install',
     option   => 'command',
     value    => $command,
+    owner    => $owner,
+    group    => $group,
+    mode     => $mode,
   }
 }

manifests/load.pp

@@ -1,21 +1,29 @@
+# @summary Manage a kernel module in /etc/modules.
 #
-# == Definition: kmod::load
-#
-# Manage a kernel module in /etc/modules.
-#
-# Parameters:
-# - *ensure*: present/absent;
-# - *file*: optionally, set the file where the stanza is written. Not
-#           used for systems running systemd.
-#
-# Example usage:
+# @param ensure State of the setting
+# @param file
+#   Optionally, set the file where the stanza is written. Not
+#   used for systems running systemd.
+# @param owner Owner of managed files
+# @param group Group of managed files
+# @param mode Mode of managed regular files
+# @param exe_mode Mode of managed executable files
 #
+# @example
 #   kmod::load { 'sha256': }
-#
 define kmod::load (
-  $ensure=present,
-  $file='/etc/modules',
+  Enum['present', 'absent']  $ensure   = 'present',
+  Stdlib::Unixpath           $file     = '/etc/modules',
+  # Defaults for these are set in Hiera so they can be shared with the `kmod` class.
+  # lint:ignore:lookup_in_parameter
+  Optional[String[1]]        $owner    = lookup('kmod::owner', String[1], 'first', undef),
+  Optional[String[1]]        $group    = lookup('kmod::group', String[1], 'first', undef),
+  Optional[Stdlib::Filemode] $mode     = lookup('kmod::file_mode', String[1], 'first', undef),
+  Optional[Stdlib::Filemode] $exe_mode = lookup('kmod::exe_mode', String[1], 'first', undef),
+  # lint:endignore
 ) {
+  include kmod
+
   case $ensure {
     'present': {
       case $facts['os']['family'] {
@@ -57,12 +65,24 @@
   if $facts['service_provider'] == 'systemd' {
     file { "/etc/modules-load.d/${name}.conf":
       ensure  => $ensure,
-      mode    => '0644',
+      mode    => $mode,
+      owner   => $owner,
+      group   => $group,
       content => "# This file is managed by the puppet kmod module.\n${name}\n",
     }
   } else {
     case $facts['os']['family'] {
       'Debian': {
+        ensure_resource(
+          'file',
+          $file,
+          {
+            'ensure' => 'file',
+            'owner'  => $owner,
+            'group'  => $group,
+            'mode'   => $mode,
+          }
+        )
         augeas { "Manage ${name} in ${file}":
           incl    => $file,
           lens    => 'Modules.lns',
@@ -72,7 +92,9 @@
       'RedHat': {
         file { "/etc/sysconfig/modules/${name}.modules":
           ensure  => $ensure,
-          mode    => '0755',
+          mode    => $exe_mode,
+          owner   => $owner,
+          group   => $group,
           content => template('kmod/redhat.modprobe.erb'),
         }
       }
@@ -81,6 +103,16 @@
           '/etc/modules' => '/etc/sysconfig/kernel',
           default        => $file,
         }
+        ensure_resource(
+          'file',
+          $kernelfile,
+          {
+            'ensure' => 'file',
+            'owner'  => $owner,
+            'group'  => $group,
+            'mode'   => $mode,
+          }
+        )
         augeas { "sysconfig_kernel_MODULES_LOADED_ON_BOOT_${name}":
           lens    => 'Shellvars_list.lns',
           incl    => $kernelfile,

manifests/option.pp

@@ -1,31 +1,41 @@
-# = Define: kmod::alias
+# @summary Manage kernel module options
 #
-# == Example
-#
-#     kmod::option { 'bond0':
-#       option => 'bonding',
-#     }
+# @param option Option to manage
+# @param value Value of kernel module option
+# @param module Kernel module to manage
+# @param ensure State of the option
+# @param file File to manage
+# @param owner Owner of managed file
+# @param group Group of managed file
+# @param mode Mode of managed file
 #
+# @example
+#   kmod::option { 'bond0 mode':
+#     module  => 'bond0',
+#     option  => 'mode',
+#     value   => '1',
+#   }
 define kmod::option (
-  $option,
-  $value,
-  $module = $name,
-  $ensure = 'present',
-  $file   = undef,
+  String[1]                  $option,
+  Scalar                     $value,
+  String[1]                  $module = $name,
+  Enum['present', 'absent']  $ensure = 'present',
+  Stdlib::Unixpath           $file   = "/etc/modprobe.d/${module}.conf",
+  Optional[String[1]]        $owner  = undef,
+  Optional[String[1]]        $group  = undef,
+  Optional[Stdlib::Filemode] $mode   = undef,
 ) {
   include kmod
 
-  $target_file = $file ? {
-    undef   => "/etc/modprobe.d/${module}.conf",
-    default => $file,
-  }
-
   kmod::setting { "kmod::option ${title}":
     ensure   => $ensure,
     module   => $module,
     category => 'options',
-    file     => $target_file,
+    file     => $file,
     option   => $option,
     value    => $value,
+    owner    => $owner,
+    group    => $group,
+    mode     => $mode,
   }
 }