chef 16.0.257 → 16.0.275

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/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,7 +23,7 @@ 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"
 
       property :domain_name, String,

data/lib/chef/resource/windows_auto_run.rb

@@ -23,7 +23,7 @@ class Chef
     class WindowsAutorun < Chef::Resource
       provides(:windows_auto_run) { true }
 
-      description "Use the windows_auto_run resource to set applications to run at login."
+      description "Use the **windows_auto_run** resource to set applications to run at login."
       introduced "14.0"
 
       property :program_name, String,
@@ -32,7 +32,7 @@ class Chef
 
       property :path, String,
         coerce: proc { |x| x.tr("/", "\\") }, # make sure we have windows paths for the registry
-        description: "The path to the program that will run at login. "
+        description: "The path to the program that will run at login."
 
       property :args, String,
         description: "Any arguments to be used with the program."

data/lib/chef/resource/windows_certificate.rb

@@ -28,7 +28,7 @@ class Chef
     class WindowsCertificate < Chef::Resource
       provides :windows_certificate
 
-      description "Use the windows_certificate resource to install a certificate into the Windows certificate store from a file. The resource grants read-only access to the private key for designated accounts. Due to current limitations in WinRM, installing certificates remotely may not work if the operation requires a user profile. Operations on the local machine store should still work."
+      description "Use the **windows_certificate** resource to install a certificate into the Windows certificate store from a file. The resource grants read-only access to the private key for designated accounts. Due to current limitations in WinRM, installing certificates remotely may not work if the operation requires a user profile. Operations on the local machine store should still work."
       introduced "14.7"
 
       property :source, String,

data/lib/chef/resource/windows_dfs_folder.rb

@@ -23,7 +23,7 @@ class Chef
     class WindowsDfsFolder < Chef::Resource
       provides :windows_dfs_folder
 
-      description "The windows_dfs_folder resources creates a folder within dfs as many levels deep as required."
+      description "Use the **windows_dfs_folder** resource to creates a folder within DFS as many levels deep as required."
       introduced "15.0"
 
       property :folder_path, String,

data/lib/chef/resource/windows_dfs_namespace.rb

@@ -23,7 +23,7 @@ class Chef
     class WindowsDfsNamespace < Chef::Resource
       provides :windows_dfs_namespace
 
-      description "Creates a share and DFS namespace on the local server."
+      description "Use the **windows_dfs_namespace** resource to creates a share and DFS namespace on a Windows server."
       introduced "15.0"
 
       property :namespace_name, String,

data/lib/chef/resource/windows_dfs_server.rb

@@ -23,7 +23,7 @@ class Chef
     class WindowsDfsServer < Chef::Resource
       provides :windows_dfs_server
 
-      description "The windows_dfs_server resource sets system-wide DFS settings."
+      description "Use the **windows_dfs_server** resource to set system-wide DFS settings."
       introduced "15.0"
 
       property :use_fqdn, [TrueClass, FalseClass],

data/lib/chef/resource/windows_env.rb

@@ -25,7 +25,16 @@ class Chef
       provides :windows_env
       provides :env # backwards compat with the pre-Chef 14 resource name
 
-      description "Use the windows_env resource to manage environment keys in Microsoft Windows. After an environment key is set, Microsoft Windows must be restarted before the environment key will be available to the Task Scheduler."
+      description "Use the **windows_env** resource to manage environment keys in Microsoft Windows. After an environment key is set, Microsoft Windows must be restarted before the environment key will be available to the Task Scheduler."
+      examples <<~DOC
+      **Set an environment variable**:
+
+      ```ruby
+      windows_env 'ComSpec' do
+        value 'C:\\Windows\\system32\\cmd.exe'
+      end
+      ```
+      DOC
 
       default_action :create
       allowed_actions :create, :delete, :modify

data/lib/chef/resource/windows_feature.rb

@@ -23,8 +23,63 @@ class Chef
     class WindowsFeature < Chef::Resource
       provides(:windows_feature) { true }
 
-      description "Use the windows_feature resource to add, remove or entirely delete Windows features and roles. This resource calls the 'windows_feature_dism' or 'windows_feature_powershell' resources depending on the specified installation method, and defaults to DISM, which is available on both Workstation and Server editions of Windows."
+      description "Use the **windows_feature** resource to add, remove or entirely delete Windows features and roles. This resource calls the 'windows_feature_dism' or 'windows_feature_powershell' resources depending on the specified installation method, and defaults to DISM, which is available on both Workstation and Server editions of Windows."
       introduced "14.0"
+      examples <<~DOC
+      **Install the DHCP Server feature**:
+
+      ```ruby
+      windows_feature 'DHCPServer' do
+        action :install
+      end
+      ```
+
+      **Install the .Net 3.5.1 feature using repository files on DVD**:
+
+      ```ruby
+      windows_feature "NetFx3" do
+        action :install
+        source 'd:\\sources\\sxs'
+      end
+      ```
+
+      **Remove Telnet Server and Client features**:
+
+      ```ruby
+      windows_feature %w(TelnetServer TelnetClient) do
+        action :remove
+      end
+      ```
+
+      **Add the SMTP Server feature using the PowerShell provider**:
+
+      ```ruby
+      windows_feature 'smtp-server' do
+        action :install
+        all true
+        install_method :windows_feature_powershell
+      end
+      ```
+
+      **Install multiple features using one resource with the PowerShell provider**:
+
+      ```ruby
+      windows_feature %w(Web-Asp-Net45 Web-Net-Ext45) do
+        action :install
+        install_method :windows_feature_powershell
+      end
+      ```
+
+      **Install the Network Policy and Access Service feature, including the management tools**:
+
+      ```ruby
+      windows_feature 'NPAS' do
+        action :install
+        management_tools true
+        install_method :windows_feature_powershell
+      end
+      ```
+      DOC
 
       property :feature_name, [Array, String],
         description: "The name of the feature(s) or role(s) to install if they differ from the resource block's name. The same feature may have different names depending on the underlying installation method being used (ie DHCPServer vs DHCP; DNS-Server-Full-Role vs DNS).",
@@ -42,7 +97,7 @@ class Chef
         default: false
 
       property :install_method, Symbol,
-        description: "The underlying installation method to use for feature installation. Specify ':windows_feature_dism' for DISM or ':windows_feature_powershell' for PowerShell.",
+        description: "The underlying installation method to use for feature installation. Specify `:windows_feature_dism` for DISM or `:windows_feature_powershell` for PowerShell.",
         equal_to: %i{windows_feature_dism windows_feature_powershell windows_feature_servermanagercmd},
         default: :windows_feature_dism
 

data/lib/chef/resource/windows_feature_dism.rb

@@ -24,8 +24,21 @@ class Chef
     class WindowsFeatureDism < Chef::Resource
       provides(:windows_feature_dism) { true }
 
-      description "Use the windows_feature_dism resource to add, remove, or entirely delete Windows features and roles using DISM."
+      description "Use the **windows_feature_dism** resource to add, remove, or entirely delete Windows features and roles using DISM."
       introduced "14.0"
+      examples <<~DOC
+      **Installing the TelnetClient service**:
+
+      ```ruby
+      windows_feature_dism "TelnetClient"
+      ```
+
+      **Installing two features by using an array**:
+
+      ```ruby
+      windows_feature_dism %w(TelnetClient TFTP)
+      ```
+      DOC
 
       property :feature_name, [Array, String],
         description: "The name of the feature(s) or role(s) to install if they differ from the resource name.",
@@ -36,7 +49,7 @@ class Chef
         description: "Specify a local repository for the feature install."
 
       property :all, [TrueClass, FalseClass],
-        description: "Install all sub-features. When set to 'true', this is the equivalent of specifying the /All switch to dism.exe",
+        description: "Install all sub-features. When set to `true`, this is the equivalent of specifying the `/All` switch to `dism.exe`",
         default: false
 
       property :timeout, Integer,

data/lib/chef/resource/windows_feature_powershell.rb

@@ -25,8 +25,35 @@ class Chef
     class WindowsFeaturePowershell < Chef::Resource
       provides(:windows_feature_powershell) { true }
 
-      description "Use the windows_feature_powershell resource to add, remove, or entirely delete Windows features and roles using PowerShell. This resource offers significant speed benefits over the windows_feature_dism resource, but requires installation of the Remote Server Administration Tools on non-server releases of Windows."
+      description "Use the **windows_feature_powershell** resource to add, remove, or entirely delete Windows features and roles using PowerShell. This resource offers significant speed benefits over the windows_feature_dism resource, but requires installation of the Remote Server Administration Tools on non-server releases of Windows."
       introduced "14.0"
+      examples <<~DOC
+      **Add the SMTP Server feature**:
+
+      ```ruby
+      windows_feature_powershell "smtp-server" do
+        action :install
+        all true
+      end
+      ```
+
+      **Install multiple features using one resource**:
+
+      ```ruby
+      windows_feature_powershell ['Web-Asp-Net45', 'Web-Net-Ext45'] do
+        action :install
+      end
+      ```
+
+      **Install the Network Policy and Access Service feature**:
+
+      ```ruby
+      windows_feature_powershell 'NPAS' do
+        action :install
+        management_tools true
+      end
+      ```
+      DOC
 
       property :feature_name, [Array, String],
         description: "The name of the feature(s) or role(s) to install if they differ from the resource block's name.",
@@ -37,7 +64,7 @@ class Chef
         description: "Specify a local repository for the feature install."
 
       property :all, [TrueClass, FalseClass],
-        description: "Install all subfeatures. When set to 'true', this is the equivalent of specifying the '-InstallAllSubFeatures' switch with 'Add-WindowsFeature'.",
+        description: "Install all subfeatures. When set to `true`, this is the equivalent of specifying the `-InstallAllSubFeatures` switch with `Add-WindowsFeature`.",
         default: false
 
       property :timeout, Integer,

data/lib/chef/resource/windows_firewall_rule.rb

@@ -26,10 +26,11 @@ class Chef
     class WindowsFirewallRule < Chef::Resource
       provides :windows_firewall_rule
 
-      description "Use the windows_firewall_rule resource to create, change or remove Windows firewall rules."
+      description "Use the **windows_firewall_rule** resource to create, change or remove Windows firewall rules."
       introduced "14.7"
       examples <<~DOC
-      Allowing port 80 access
+      **Allowing port 80 access**:
+
       ```ruby
       windows_firewall_rule 'IIS' do
         local_port '80'
@@ -38,7 +39,8 @@ class Chef
       end
       ```
 
-      Allow protocol ICMPv6 with ICMP Type
+      **Allow protocol ICMPv6 with ICMP Type**:
+
       ```ruby
       windows_firewall_rule 'CoreNet-Rule' do
         rule_name 'CoreNet-ICMP6-LR2-In'
@@ -49,7 +51,8 @@ class Chef
       end
       ```
 
-      Blocking WinRM over HTTP on a particular IP
+      **Blocking WinRM over HTTP on a particular IP**:
+
       ```ruby
       windows_firewall_rule 'Disable WinRM over HTTP' do
         local_port '5985'
@@ -59,7 +62,8 @@ class Chef
       end
       ```
 
-      Deleting an existing rule
+      **Deleting an existing rule**
+
       ```ruby
       windows_firewall_rule 'Remove the SSH rule' do
         rule_name 'ssh'