chef 16.0.287-universal-mingw32 → 16.2.73-universal-mingw32

data/lib/chef/resource/mount.rb

@@ -50,7 +50,7 @@ class Chef
         description: "The type of device: :device, :label, or :uuid",
         coerce: proc { |arg| arg.is_a?(String) ? arg.to_sym : arg },
         default: :device,
-        equal_to: RUBY_PLATFORM =~ /solaris/i ? %i{ device } : %i{ device label uuid }
+        equal_to: RUBY_PLATFORM.match?(/solaris/i) ? %i{ device } : %i{ device label uuid }
 
       # @todo this should get refactored away: https://github.com/chef/chef/issues/7621
       property :mounted, [TrueClass, FalseClass], default: false, skip_docs: true

data/lib/chef/resource/perl.rb

@@ -17,7 +17,6 @@
 #
 
 require_relative "script"
-require_relative "../provider/script"
 
 class Chef
   class Resource

data/lib/chef/resource/plist.rb

@@ -28,14 +28,33 @@ class Chef
 
       description "Use the **plist** resource to set config values in plist files on macOS systems."
       introduced "16.0"
+      examples <<~DOC
+        **Show hidden files in finder**:
+
+        ```ruby
+        plist 'show hidden files' do
+          path '/Users/vagrant/Library/Preferences/com.apple.finder.plist'
+          entry 'AppleShowAllFiles'
+          value true
+        end
+        ```
+      DOC
+
+      property :path, String, name_property: true,
+        description: "The path on disk to the plist file."
 
-      property :path, String, name_property: true
       property :entry, String
       property :value, [TrueClass, FalseClass, String, Integer, Float, Hash]
       property :encoding, String, default: "binary"
-      property :owner, String, default: "root"
-      property :group, String, default: "wheel"
-      property :mode, [String, Integer]
+
+      property :owner, String, default: "root",
+        description: "The owner of the plist file."
+
+      property :group, String, default: "wheel",
+        description: "The group of the plist file."
+
+      property :mode, [String, Integer],
+        description: "The file mode of the plist file. Ex: '644'"
 
       PLISTBUDDY_EXECUTABLE = "/usr/libexec/PlistBuddy".freeze
       DEFAULTS_EXECUTABLE = "/usr/bin/defaults".freeze

data/lib/chef/resource/powershell_script.rb

@@ -48,8 +48,10 @@ class Chef
                   " idempotent, as they are typically unique to the environment in which they are run. Use not_if"\
                   " and only_if to guard this resource for idempotence."
 
-      def initialize(name, run_context = nil)
-        super(name, run_context, :powershell_script, "powershell.exe")
+      def initialize(*args)
+        super
+        @interpreter = "powershell.exe"
+        @default_guard_interpreter = resource_name
         @convert_boolean_return = false
       end
 

data/lib/chef/resource/python.rb

@@ -16,7 +16,6 @@
 #
 
 require_relative "script"
-require_relative "../provider/script"
 
 class Chef
   class Resource

data/lib/chef/resource/remote_file.rb

@@ -22,6 +22,7 @@ require_relative "file"
 require_relative "../provider/remote_file"
 require_relative "../mixin/securable"
 require_relative "../mixin/uris"
+require_relative "../dist"
 
 class Chef
   class Resource
@@ -31,7 +32,7 @@ class Chef
 
       provides :remote_file
 
-      description "Use the **remote_file** resource to transfer a file from a remote location using file specificity. This resource is similar to the file resource."
+      description "Use the **remote_file** resource to transfer a file from a remote location using file specificity. This resource is similar to the **file** resource. Note: Fetching files from the `files/` directory in a cookbook should be done with the **cookbook_file** resource."
 
       def initialize(name, run_context = nil)
         super
@@ -72,7 +73,8 @@ class Chef
         end
       end
 
-      property :checksum, String
+      property :checksum, String,
+        description: "Optional, see `use_conditional_get`. The SHA-256 checksum of the file. Use to prevent a file from being re-downloaded. When the local file matches the checksum, #{Chef::Dist::PRODUCT} does not download it."
 
       # Disable or enable ETag and Last Modified conditional GET. Equivalent to
       #   use_etag(true_or_false)
@@ -82,25 +84,39 @@ class Chef
         use_last_modified(true_or_false)
       end
 
-      property :use_etag, [ TrueClass, FalseClass ], default: true
+      property :use_etag, [ TrueClass, FalseClass ], default: true,
+        description: "Enable ETag headers. Set to false to disable ETag headers. To use this setting, `use_conditional_get` must also be set to true."
 
       alias :use_etags :use_etag
 
-      property :use_last_modified, [ TrueClass, FalseClass ], default: true
+      property :use_last_modified, [ TrueClass, FalseClass ], default: true,
+        description: "Enable `If-Modified-Since` headers. Set to `false` to disable `If-Modified-Since` headers. To use this setting, `use_conditional_get` must also be set to `true`."
 
-      property :ftp_active_mode, [ TrueClass, FalseClass ], default: false
+      property :ftp_active_mode, [ TrueClass, FalseClass ], default: false,
+        description: "Whether #{Chef::Dist::PRODUCT} uses active or passive FTP. Set to `true` to use active FTP."
 
-      property :headers, Hash, default: lazy { {} }
+      property :headers, Hash, default: lazy { {} },
+        description: "A Hash of custom HTTP headers."
 
       property :show_progress, [ TrueClass, FalseClass ], default: false
 
-      property :remote_user, String
+      property :ssl_verify_mode, Symbol, equal_to: %i{verify_none verify_peer},
+        introduced: "16.2",
+        description: "Optional property to override SSL policy. If not specified, uses the SSL policy from `config.rb`."
 
-      property :remote_domain, String
+      property :remote_user, String,
+        introduced: "13.4",
+        description: '**Windows only** The name of a user with access to the remote file specified by the source property. The user name may optionally be specified with a domain, such as: `domain\user` or `user@my.dns.domain.com` via Universal Principal Name (UPN) format. The domain may also be set using the `remote_domain` property. Note that this property is ignored if source is not a UNC path. If this property is specified, the `remote_password` property is required.'
 
-      property :remote_password, String, sensitive: true
+      property :remote_domain, String,
+        introduced: "13.4",
+        description: "**Windows only** The domain of the user specified by the `remote_user` property. By default the resource will authenticate against the domain of the remote system, or as a local account if the remote system is not joined to a domain. If the remote system is not part of a domain, it is necessary to authenticate as a local user on the remote system by setting the domain to `.`, for example: remote_domain '.'. The domain may also be specified as part of the `remote_user` property."
 
-      property :authentication, equal_to: %i{remote local}, default: :remote
+      property :remote_password, String, sensitive: true,
+        introduced: "13.4",
+        description: "**Windows only** The password of the user specified by the `remote_user` property. This property is required if `remote_user` is specified and may only be specified if `remote_user` is specified. The `sensitive` property for this resource will automatically be set to `true` if `remote_password` is specified."
+
+      property :authentication, Symbol, equal_to: %i{remote local}, default: :remote
 
       def after_created
         validate_identity_platform(remote_user, remote_password, remote_domain)

data/lib/chef/resource/ruby.rb

@@ -17,7 +17,6 @@
 #
 
 require_relative "script"
-require_relative "../provider/script"
 
 class Chef
   class Resource

data/lib/chef/resource/scm/git.rb

@@ -53,7 +53,7 @@ class Chef
         description: "The path to the wrapper script used when running SSH with git. The `GIT_SSH` environment variable is set to this."
 
       property :checkout_branch, String,
-        description: "Set this to use a local branch to avoid checking SHAs or tags to a detatched head state."
+        description: "Set this to use a local branch to avoid checking SHAs or tags to a detached head state."
 
       alias :branch :revision
       alias :reference :revision

data/lib/chef/resource/ssh_known_hosts_entry.rb

@@ -29,6 +29,21 @@ class Chef
 
       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"
+      examples <<~DOC
+      **Add a single entry for github.com with the key auto detected**
+
+      ```ruby
+      ssh_known_hosts_entry 'github.com'
+      ```
+
+      **Add a single entry with your own provided key**
+
+      ```ruby
+      ssh_known_hosts_entry 'github.com' do
+        key 'node.example.com ssh-rsa ...'
+      end
+      ```
+      DOC
 
       property :host, String,
         description: "The host to add to the known hosts file.",

data/lib/chef/resource/sudo.rb

@@ -34,6 +34,33 @@ class Chef
                   " installation of the required sudo version. Chef-supported releases of Ubuntu, SuSE, Debian,"\
                   " and RHEL (6+) all support this feature."
       introduced "14.0"
+      examples <<~DOC
+      **Grant a user sudo privileges for any command**
+
+      ```ruby
+      sudo 'admin' do
+        user 'admin'
+      end
+      ```
+
+      **Grant a user and groups sudo privileges for any command**
+
+      ```ruby
+      sudo 'admins' do
+        users 'bob'
+        groups 'sysadmins, superusers'
+      end
+      ```
+
+      **Grant passwordless sudo privileges for specific commands**
+
+      ```ruby
+      sudo 'passwordless-access' do
+        commands ['/bin/systemctl restart httpd', '/bin/systemctl restart mysql']
+        nopasswd true
+      end
+      ```
+      DOC
 
       # According to the sudo man pages sudo will ignore files in an include dir that have a `.` or `~`
       # We convert either to `__`
@@ -53,7 +80,7 @@ class Chef
         coerce: proc { |x| coerce_groups(x) }
 
       property :commands, Array,
-        description: "An array of commands this sudoer can execute.",
+        description: "An array of full paths to commands this sudoer can execute.",
         default: ["ALL"]
 
       property :host, String,
@@ -112,7 +139,7 @@ class Chef
 
       # handle legacy cookbook property
       def after_created
-        raise "The 'visudo_path' property from the sudo cookbook has been replaced with the 'visudo_binary' property. The path is now more intelligently determined and for most users specifying the path should no longer be necessary. If this resource still cannot determine the path to visudo then provide the full path to the binary with the 'visudo_binary' property." if visudo_path
+        raise "The 'visudo_path' property from the sudo cookbook has been replaced with the 'visudo_binary' property. The path is now more intelligently determined and for most users specifying the path should no longer be necessary. If this resource still cannot determine the path to visudo then provide the absolute path to the binary with the 'visudo_binary' property." if visudo_path
       end
 
       # VERY old legacy properties

data/lib/chef/resource/swap_file.rb

@@ -26,6 +26,23 @@ class Chef
 
       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"
+      examples <<~DOC
+      **Create a swap file**
+
+      ```ruby
+      swap_file '/dev/sda1' do
+        size 1024
+      end
+      ```
+
+      **Remove a swap file**
+
+      ```ruby
+      swap_file '/dev/sda1' do
+        action :remove
+      end
+      ```
+      DOC
 
       property :path, String,
         description: "The path where the swap file will be created on the system if it differs from the resource block's name.",

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

@@ -28,6 +28,21 @@ class Chef
 
       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"
+      examples <<~DOC
+      **Set the timezone to UTC**
+
+      ```ruby
+      timezone 'UTC'
+      ```
+
+      **Set the timezone to UTC with a friendly resource name**
+
+      ```ruby
+      timezone 'Set the host's timezone to UTC' do
+        timezone 'UTC'
+      end
+      ```
+      DOC
 
       property :timezone, String,
         description: "An optional property to set the timezone value if it differs from the resource block's name.",

data/lib/chef/resource/windows_ad_join.rb

@@ -25,6 +25,35 @@ class Chef
 
       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