chef 16.0.257 → 16.2.44

data/lib/chef/resource/ssh_known_hosts_entry.rb

@@ -27,7 +27,7 @@ class Chef
 
       provides :ssh_known_hosts_entry
 
-      description "Use the ssh_known_hosts_entry resource to add an entry for the specified host in /etc/ssh/ssh_known_hosts or a user's known hosts file if specified."
+      description "Use the **ssh_known_hosts_entry** resource to add an entry for the specified host in /etc/ssh/ssh_known_hosts or a user's known hosts file if specified."
       introduced "14.3"
 
       property :host, String,

data/lib/chef/resource/sudo.rb

@@ -28,7 +28,7 @@ class Chef
 
       provides(:sudo) { true }
 
-      description "Use the sudo resource to add or remove individual sudo entries using sudoers.d files."\
+      description "Use the **sudo** resource to add or remove individual sudo entries using sudoers.d files."\
                   " Sudo version 1.7.2 or newer is required to use the sudo resource, as it relies on the"\
                   " '#includedir' directive introduced in version 1.7.2. This resource does not enforce"\
                   " installation of the required sudo version. Chef-supported releases of Ubuntu, SuSE, Debian,"\
@@ -88,15 +88,15 @@ class Chef
         default: lazy { [] }
 
       property :setenv, [TrueClass, FalseClass],
-        description: "Determines whether or not to permit preservation of the environment with 'sudo -E'.",
+        description: "Determines whether or not to permit preservation of the environment with `sudo -E`.",
         default: false
 
       property :env_keep_add, Array,
-        description: "An array of strings to add to env_keep.",
+        description: "An array of strings to add to `env_keep`.",
         default: lazy { [] }
 
       property :env_keep_subtract, Array,
-        description: "An array of strings to remove from env_keep.",
+        description: "An array of strings to remove from `env_keep`.",
         default: lazy { [] }
 
       property :visudo_path, String,

data/lib/chef/resource/swap_file.rb

@@ -24,7 +24,7 @@ class Chef
 
       provides(:swap_file) { true }
 
-      description "Use the swap_file resource to create or delete swap files on Linux systems, and optionally to manage the swappiness configuration for a host."
+      description "Use the **swap_file** resource to create or delete swap files on Linux systems, and optionally to manage the swappiness configuration for a host."
       introduced "14.0"
 
       property :path, String,
@@ -39,7 +39,7 @@ class Chef
         default: false
 
       property :timeout, Integer,
-        description: "Timeout for 'dd' / 'fallocate' commands.",
+        description: "Timeout for `dd` / `fallocate` commands.",
         default: 600,
         desired_state: false
 

data/lib/chef/resource/sysctl.rb

@@ -25,11 +25,70 @@ class Chef
       provides(:sysctl) { true }
       provides(:sysctl_param) { true }
 
-      description "Use the sysctl resource to set or remove kernel parameters using the sysctl"\
+      description "Use the **sysctl** resource to set or remove kernel parameters using the sysctl"\
                   " command line tool and configuration files in the system's sysctl.d directory. "\
                   "Configuration files managed by this resource are named 99-chef-KEYNAME.conf. If"\
                   " an existing value was already set for the value it will be backed up to the node"\
                   " and restored if the :remove action is used later."
+      examples <<~DOC
+      **Set vm.swappiness**:
+
+      ```ruby
+      sysctl 'vm.swappiness' do
+        value 19
+      end
+      ```
+
+      **Remove kernel.msgmax**:
+
+      **Note**: This only removes the sysctl.d config for kernel.msgmax. The value will be set back to the kernel default value.
+
+      ```ruby
+      sysctl 'kernel.msgmax' do
+        action :remove
+      end
+      ```
+
+      **Adding Comments to sysctl configuration files**:
+
+      ```ruby
+      sysctl 'vm.swappiness' do
+        value 19
+        comment "define how aggressively the kernel will swap memory pages."
+      end
+      ```
+
+      This produces /etc/sysctl.d/99-chef-vm.swappiness.conf as follows:
+
+      ```
+      # define how aggressively the kernel will swap memory pages.
+      vm.swappiness = 1
+      ```
+
+      **Converting sysctl settings from shell scripts**:
+
+      Example of existing settings:
+
+      ```bash
+      fs.aio-max-nr = 1048576 net.ipv4.ip_local_port_range = 9000 65500 kernel.sem = 250 32000 100 128
+      ```
+
+      Converted to sysctl resources:
+
+      ```ruby
+      sysctl 'fs.aio-max-nr' do
+        value '1048576'
+      end
+
+      sysctl 'net.ipv4.ip_local_port_range' do
+        value '9000 65500'
+      end
+
+      sysctl 'kernel.sem' do
+        value '250 32000 100 128'
+      end
+      ```
+      DOC
 
       introduced "14.0"
 
@@ -44,7 +103,7 @@ class Chef
       property :value, [Array, String, Integer, Float],
         description: "The value to set.",
         coerce: proc { |v| coerce_value(v) },
-        required: true
+        required: [:apply]
 
       property :comment, [Array, String],
         description: "Comments, placed above the resource setting in the generated file. For multi-line comments, use an array of strings, one per line.",

data/lib/chef/resource/systemd_unit.rb

@@ -27,7 +27,7 @@ class Chef
 
       provides(:systemd_unit) { true }
 
-      description "Use the systemd_unit resource to create, manage, and run systemd units."
+      description "Use the **systemd_unit** resource to create, manage, and run systemd units."
       introduced "12.11"
 
       default_action :nothing
@@ -52,7 +52,7 @@ class Chef
                description: "The user account that the systemd unit process is run under. The path to the unit for that user would be something like '/etc/systemd/user/sshd.service'. If no user account is specified, the systemd unit will run under a 'system' account, with the path to the unit being something like '/etc/systemd/system/sshd.service'."
 
       property :content, [String, Hash],
-        description: "A string or hash that contains a systemd `unit file <https://www.freedesktop.org/software/systemd/man/systemd.unit.html>`_ definition that describes the properties of systemd-managed entities, such as services, sockets, devices, and so on. In #{Chef::Dist::PRODUCT} 14.4 or later, repeatable options can be implemented with an array."
+        description: "A string or hash that contains a systemd [unit file](https://www.freedesktop.org/software/systemd/man/systemd.unit.html) definition that describes the properties of systemd-managed entities, such as services, sockets, devices, and so on. In #{Chef::Dist::PRODUCT} 14.4 or later, repeatable options can be implemented with an array."
 
       property :triggers_reload, [TrueClass, FalseClass],
         description: "Specifies whether to trigger a daemon reload when creating or deleting a unit.",

data/lib/chef/resource/template.rb

@@ -69,7 +69,7 @@ class Chef
 
       property :local, [ TrueClass, FalseClass ],
         default: false, desired_state: false,
-        description: "Load a template from a local path. By default, the #{Chef::Dist::CLIENT} loads templates from a cookbook’s /templates directory. When this property is set to true, use the source property to specify the path to a template on the local node."
+        description: "Load a template from a local path. By default, the #{Chef::Dist::CLIENT} loads templates from a cookbook's /templates directory. When this property is set to true, use the source property to specify the path to a template on the local node."
 
       # Declares a helper method to be defined in the template context when
       # rendering.

data/lib/chef/resource/timezone.rb

@@ -26,7 +26,7 @@ class Chef
 
       provides :timezone
 
-      description "Use the timezone resource to change the system timezone on Windows, Linux, and macOS hosts. Timezones are specified in tz database format, with a complete list of available TZ values for Linux and macOS here: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones and for Windows here: https://ss64.com/nt/timezones.html."
+      description "Use the **timezone** resource to change the system timezone on Windows, Linux, and macOS hosts. Timezones are specified in tz database format, with a complete list of available TZ values for Linux and macOS here: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones and for Windows here: https://ss64.com/nt/timezones.html."
       introduced "14.6"
 
       property :timezone, String,

data/lib/chef/resource/user.rb

@@ -23,7 +23,7 @@ class Chef
     class User < Chef::Resource
       unified_mode true
 
-      description "Use the user resource to add users, update existing users, remove users, and to lock/unlock user passwords."
+      description "Use the **user** resource to add users, update existing users, remove users, and to lock/unlock user passwords."
 
       default_action :create
       allowed_actions :create, :remove, :modify, :manage, :lock, :unlock
@@ -55,7 +55,7 @@ class Chef
         default: false, desired_state: false
 
       property :manage_home, [ TrueClass, FalseClass ],
-        description: "Manage a user’s home directory.\nWhen used with the :create action, a user’s home directory is created based on HOME_DIR. If the home directory is missing, it is created unless CREATE_HOME in /etc/login.defs is set to no. When created, a skeleton set of files and subdirectories are included within the home directory.\nWhen used with the :modify action, a user’s home directory is moved to HOME_DIR. If the home directory is missing, it is created unless CREATE_HOME in /etc/login.defs is set to no. The contents of the user’s home directory are moved to the new location.",
+        description: "Manage a user's home directory.\nWhen used with the :create action, a user's home directory is created based on HOME_DIR. If the home directory is missing, it is created unless CREATE_HOME in /etc/login.defs is set to no. When created, a skeleton set of files and subdirectories are included within the home directory.\nWhen used with the :modify action, a user's home directory is moved to HOME_DIR. If the home directory is missing, it is created unless CREATE_HOME in /etc/login.defs is set to no. The contents of the user's home directory are moved to the new location.",
         default: false, desired_state: false
 
       property :force, [ TrueClass, FalseClass ],

data/lib/chef/resource/user_ulimit.rb

@@ -26,32 +26,34 @@ class Chef
 
       provides :user_ulimit
 
+      description "Use the **user_ulimit** resource to create individual ulimit files that are installed into the `/etc/security/limits.d/` directory."
       introduced "16.0"
-      description "Use the user_ulimit resource to create individual ulimit files that are installed into the `/etc/security/limits.d/` directory."
       examples <<~DOC
-        set filehandle limit for the tomcat user
-        ```ruby
-        user_ulimit 'tomcat' do
-          filehandle_limit 8192
-        end
-        ```
+      **Set filehandle limit for the tomcat user**:
 
-        specify a username that differs from the name given to the resource block
-        ```ruby
-        user_ulimit 'Bump filehandle limits for tomcat user' do
-          username 'tomcat'
-          filehandle_limit 8192
-        end
-        ```
+      ```ruby
+      user_ulimit 'tomcat' do
+        filehandle_limit 8192
+      end
+      ```
 
-        specify a non-default filename
-        set filehandle limit for the tomcat user
-        ```ruby
-        user_ulimit 'tomcat' do
-          filehandle_limit 8192
-          filename 'tomcat_filehandle_limits.conf'
-        end
-        ```
+      **Specify a username that differs from the name given to the resource block**:
+
+      ```ruby
+      user_ulimit 'Bump filehandle limits for tomcat user' do
+        username 'tomcat'
+        filehandle_limit 8192
+      end
+      ```
+
+      **Set filehandle limit for the tomcat user with a non-default filename**:
+
+      ```ruby
+      user_ulimit 'tomcat' do
+        filehandle_limit 8192
+        filename 'tomcat_filehandle_limits.conf'
+      end
+      ```
       DOC
 
       property :username, String, name_property: true

data/lib/chef/resource/windows_ad_join.rb

@@ -23,8 +23,37 @@ class Chef
     class WindowsAdJoin < Chef::Resource
       provides :windows_ad_join
 
-      description "Use the windows_ad_join resource to join a Windows Active Directory domain."
+      description "Use the **windows_ad_join** resource to join a Windows Active Directory domain."
       introduced "14.0"
+      examples <<~DOC
+      **Join a domain**
+
+      ```ruby
+      windows_ad_join 'ad.example.org' do
+        domain_user 'nick'
+        domain_password 'p@ssw0rd1'
+      end
+      ```
+
+      **Join a domain, as `win-workstation`**
+
+      ```ruby
+      windows_ad_join 'ad.example.org' do
+        domain_user 'nick'
+        domain_password 'p@ssw0rd1'
+        new_hostname 'win-workstation'
+      end
+      ```
+
+      **Leave the current domain and re-join the `local` workgroup**
+
+      ```ruby
+      windows_ad_join 'Leave domain' do
+        action :leave
+        workgroup 'local'
+      end
+      ```
+      DOC
 
       property :domain_name, String,
         description: "An optional property to set the FQDN of the Active Directory domain to join if it differs from the resource block's name.",
@@ -175,7 +204,7 @@ class Chef
         #   links: https://docs.microsoft.com/en-us/windows/win32/ad/naming-properties#userprincipalname https://tools.ietf.org/html/rfc822
         #   regex: https://rubular.com/r/isAWojpTMKzlnp
         def sanitize_usename
-          if new_resource.domain_user =~ /@/
+          if /@/.match?(new_resource.domain_user)
             new_resource.domain_user
           else
             "#{new_resource.domain_user}@#{new_resource.domain_name}"

data/lib/chef/resource/windows_audit_policy.rb

@@ -0,0 +1,227 @@
+#
+# Author:: Ross Moles (<rmoles@chef.io>)
+# Author:: Rachel Rice (<rrice@chef.io>)
+# Author:: Davin Taddeo (<davin@chef.io>)
+# Copyright:: Copyright (c) Chef Software Inc.
+#
+# 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.
+#
+
+require_relative "../resource"
+
+class Chef
+  class Resource
+    class WindowsAuditPolicy < Chef::Resource
+      WIN_AUDIT_SUBCATEGORIES = ["Account Lockout",
+                                 "Application Generated",
+                                 "Application Group Management",
+                                 "Audit Policy Change",
+                                 "Authentication Policy Change",
+                                 "Authorization Policy Change",
+                                 "Central Policy Staging",
+                                 "Certification Services",
+                                 "Computer Account Management",
+                                 "Credential Validation",
+                                 "DPAPI Activity",
+                                 "Detailed Directory Service Replication",
+                                 "Detailed File Share",
+                                 "Directory Service Access",
+                                 "Directory Service Changes",
+                                 "Directory Service Replication",
+                                 "Distribution Group Management",
+                                 "File Share",
+                                 "File System",
+                                 "Filtering Platform Connection",
+                                 "Filtering Platform Packet Drop",
+                                 "Filtering Platform Policy Change",
+                                 "Group Membership",
+                                 "Handle Manipulation",
+                                 "IPsec Driver",
+                                 "IPsec Extended Mode",
+                                 "IPsec Main Mode",
+                                 "IPsec Quick Mode",
+                                 "Kerberos Authentication Service",
+                                 "Kerberos Service Ticket Operations",
+                                 "Kernel Object",
+                                 "Logoff",
+                                 "Logon",
+                                 "MPSSVC Rule-Level Policy Change",
+                                 "Network Policy Server",
+                                 "Non Sensitive Privilege Use",
+                                 "Other Account Logon Events",
+                                 "Other Account Management Events",
+                                 "Other Logon/Logoff Events",
+                                 "Other Object Access Events",
+                                 "Other Policy Change Events",
+                                 "Other Privilege Use Events",
+                                 "Other System Events",
+                                 "Plug and Play Events",
+                                 "Process Creation",
+                                 "Process Termination",
+                                 "RPC Events",
+                                 "Registry",
+                                 "Removable Storage",
+                                 "SAM",
+                                 "Security Group Management",
+                                 "Security State Change",
+                                 "Security System Extension",
+                                 "Sensitive Privilege Use",
+                                 "Special Logon",
+                                 "System Integrity",
+                                 "Token Right Adjusted Events",
+                                 "User / Device Claims",
+                                 "User Account Management",
+                                ].freeze
+      provides :windows_audit_policy
+
+      description "Use the **windows_audit_policy** resource to configure system level and per-user Windows advanced audit policy settings."
+      introduced "16.2"
+
+      examples <<~DOC
+      **Set Logon and Logoff policy to "Success and Failure"**:
+
+      ```ruby
+      windows_audit_policy "Set Audit Policy for 'Logon and Logoff' actions to 'Success and Failure'" do
+        subcategory %w(Logon Logoff)
+        success true
+        failure true
+        action :set
+      end
+      ```
+
+      **Set Credential Validation policy to "Success"**:
+
+      ```ruby
+      windows_audit_policy "Set Audit Policy for 'Credential Validation' actions to 'Success'" do
+        subcategory  'Credential Validation'
+        success true
+        failure false
+        action :set
+      end
+      ```
+
+      **Enable CrashOnAuditFail option**:
+
+      ```ruby
+      windows_audit_policy 'Enable CrashOnAuditFail option' do
+        crash_on_audit_fail true
+        action :set
+      end
+      ```
+      DOC
+
+      property :subcategory, [String, Array],
+        coerce: proc { |p| Array(p) },
+        description: "The audit policy subcategory, specified by GUID or name. Applied system-wide if no user is specified.",
+        callbacks: { "Subcategories entered should be actual advanced audit policy subcategories" => proc { |n| (Array(n) - WIN_AUDIT_SUBCATEGORIES).empty? } }
+
+      property :success, [true, false],
+               description: "Specify success auditing. By setting this property to true the resource will enable success for the category or sub category. Success is the default and is applied if neither success nor failure are specified."
+
+      property :failure, [true, false],
+               description: "Specify failure auditing. By setting this property to true the resource will enable failure for the category or sub category. Success is the default and is applied if neither success nor failure are specified."
+
+      property :include_user, String,
+               description: "The audit policy specified by the category or subcategory is applied per-user if specified. When a user is specified, include user. Include and exclude cannot be used at the same time."
+
+      property :exclude_user, String,
+               description: "The audit policy specified by the category or subcategory is applied per-user if specified. When a user is specified, exclude user. Include and exclude cannot be used at the same time."
+
+      property :crash_on_audit_fail, [true, false],
+               description: "Setting this audit policy option to true will cause the system to crash if the auditing system is unable to log events."
+
+      property :full_privilege_auditing, [true, false],
+               description: "Setting this audit policy option to true will force the audit of all privilege changes except SeAuditPrivilege. Setting this property may cause the logs to fill up more quickly."
+
+      property :audit_base_objects, [true, false],
+               description: "Setting this audit policy option to true will force the system to assign a System Access Control List to named objects to enable auditing of base objects such as mutexes."
+
+      property :audit_base_directories, [true, false],
+               description: "Setting this audit policy option to true will force the system to assign a System Access Control List to named objects to enable auditing of container objects such as directories."
+
+      def subcategory_configured?(sub_cat, success_value, failure_value)
+        setting = if success_value && failure_value
+                    "Success and Failure$"
+                  elsif success_value && !failure_value
+                    "Success$"
+                  elsif !success_value && failure_value
+                    "(Failure$)&!(Success and Failure$)"
+                  else
+                    "No Auditing"
+                  end
+        powershell_exec(<<-CODE).result
+          $auditpol_config = auditpol /get /subcategory:"#{sub_cat}"
+          if ($auditpol_config | Select-String "#{setting}") { return $true } else { return $false }
+        CODE
+      end
+
+      def option_configured?(option_name, option_setting)
+        setting = option_setting ? "Enabled$" : "Disabled$"
+        powershell_exec(<<-CODE).result
+          $auditpol_config = auditpol /get /option:#{option_name}
+          if ($auditpol_config | Select-String "#{setting}") { return $true } else { return $false }
+        CODE
+      end
+
+      action :set do
+        unless new_resource.subcategory.nil?
+          new_resource.subcategory.each do |subcategory|
+            next if subcategory_configured?(subcategory, new_resource.success, new_resource.failure)
+
+            s_val = new_resource.success ? "enable" : "disable"
+            f_val = new_resource.failure ? "enable" : "disable"
+            converge_by "Update Audit Policy for \"#{subcategory}\" to Success:#{s_val} and Failure:#{f_val}" do
+              cmd = "auditpol /set "
+              cmd += "/user:\"#{new_resource.include_user}\" /include " if new_resource.include_user
+              cmd += "/user:\"#{new_resource.exclude_user}\" /exclude " if new_resource.exclude_user
+              cmd += "/subcategory:\"#{subcategory}\" /success:#{s_val} /failure:#{f_val}"
+              powershell_exec!(cmd)
+            end
+          end
+        end
+
+        if !new_resource.crash_on_audit_fail.nil? && option_configured?("CrashOnAuditFail", new_resource.crash_on_audit_fail)
+          val = new_resource.crash_on_audit_fail ? "Enable" : "Disable"
+          converge_by "Configure Audit: CrashOnAuditFail to #{val}" do
+            cmd = "auditpol /set /option:CrashOnAuditFail /value:#{val}"
+            powershell_exec!(cmd)
+          end
+        end
+
+        if !new_resource.full_privilege_auditing.nil? && option_configured?("FullPrivilegeAuditing", new_resource.full_privilege_auditing)
+          val = new_resource.full_privilege_auditing ? "Enable" : "Disable"
+          converge_by "Configure Audit: FullPrivilegeAuditing to #{val}" do
+            cmd = "auditpol /set /option:FullPrivilegeAuditing /value:#{val}"
+            powershell_exec!(cmd)
+          end
+        end
+
+        if !new_resource.audit_base_directories.nil? && option_configured?("AuditBaseDirectories", new_resource.audit_base_directories)
+          val = new_resource.audit_base_directories ? "Enable" : "Disable"
+          converge_by "Configure Audit: AuditBaseDirectories to #{val}" do
+            cmd = "auditpol /set /option:AuditBaseDirectories /value:#{val}"
+            powershell_exec!(cmd)
+          end
+        end
+
+        if !new_resource.audit_base_objects.nil? && option_configured?("AuditBaseObjects", new_resource.audit_base_objects)
+          val = new_resource.audit_base_objects ? "Enable" : "Disable"
+          converge_by "Configure Audit: AuditBaseObjects to #{val}" do
+            cmd = "auditpol /set /option:AuditBaseObjects /value:#{val}"
+            powershell_exec!(cmd)
+          end
+        end
+      end
+    end
+  end
+end