diff options
| -rw-r--r-- | lib/chef/resource/file.rb | 2 | ||||
| -rw-r--r-- | lib/chef/resource/homebrew_update.rb | 2 | ||||
| -rw-r--r-- | lib/chef/resource/remote_file.rb | 34 | ||||
| -rw-r--r-- | lib/chef/resource/windows_shortcut.rb | 1 | ||||
| -rw-r--r-- | lib/chef/resource/windows_task.rb | 4 | ||||
| -rw-r--r-- | lib/chef/resource/windows_user_privilege.rb | 10 | ||||
| -rw-r--r-- | lib/chef/resource/yum_repository.rb | 18 |
7 files changed, 41 insertions, 30 deletions
diff --git a/lib/chef/resource/file.rb b/lib/chef/resource/file.rb index 59e917fbc4..eacddd02af 100644 --- a/lib/chef/resource/file.rb +++ b/lib/chef/resource/file.rb @@ -76,7 +76,7 @@ class Chef property :diff, [ String, nil ], desired_state: false, skip_docs: true property :force_unlink, [ TrueClass, FalseClass ], desired_state: false, default: false, - description: "How #{Chef::Dist::PRODUCT} handles certain situations when the target file turns out not to be a file. For example, when a target file is actually a symlink. Set to true for #{Chef::Dist::PRODUCT} to delete the non-file target and replace it with the specified file. Set to false for #{Chef::Dist::PRODUCT} to raise an error." + description: "How #{Chef::Dist::PRODUCT} handles certain situations when the target file turns out not to be a file. For example, when a target file is actually a symlink. Set to `true` for #{Chef::Dist::PRODUCT} to delete the non-file target and replace it with the specified file. Set to `false` for #{Chef::Dist::PRODUCT} to raise an error." property :manage_symlink_source, [ TrueClass, FalseClass ], desired_state: false, description: "Change the behavior of the file resource if it is pointed at a symlink. When this value is set to true, #{Chef::Dist::PRODUCT} will manage the symlink's permissions or will replace the symlink with a normal file if the resource has content. When this value is set to false, #{Chef::Dist::PRODUCT} will follow the symlink and will manage the permissions and content of symlink's target file. The default behavior is true but emits a warning that the default value will be changed to false in a future version; setting this explicitly to true or false suppresses this warning." diff --git a/lib/chef/resource/homebrew_update.rb b/lib/chef/resource/homebrew_update.rb index 824d327b67..53639c3ee2 100644 --- a/lib/chef/resource/homebrew_update.rb +++ b/lib/chef/resource/homebrew_update.rb @@ -30,7 +30,7 @@ class Chef description "Use the **homebrew_update** resource to manage Homebrew repository updates on MacOS." introduced "16.2" examples <<~DOC - **Update the Apt repository at a specified interval**: + **Update the homebrew repository data at a specified interval**: ```ruby homebrew_update 'all platforms' do frequency 86400 diff --git a/lib/chef/resource/remote_file.rb b/lib/chef/resource/remote_file.rb index 965301411a..c76f4cafed 100644 --- a/lib/chef/resource/remote_file.rb +++ b/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,28 +84,38 @@ 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 :ssl_verify_mode, equal_to: %i{verify_none verify_peer}, default: nil, - description: "Optional property to override SSL policy. If not specified, uses the SSL polify from config.rb." + description: "Optional property to override SSL policy. If not specified, uses the SSL polify from `config.rb`." - property :remote_user, 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_domain, String + 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 :remote_password, String, sensitive: true + 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, equal_to: %i{remote local}, default: :remote + property :authentication, Symbol, equal_to: %i{remote local}, default: :remote def after_created validate_identity_platform(remote_user, remote_password, remote_domain) diff --git a/lib/chef/resource/windows_shortcut.rb b/lib/chef/resource/windows_shortcut.rb index e272e89e16..b5b532cb86 100644 --- a/lib/chef/resource/windows_shortcut.rb +++ b/lib/chef/resource/windows_shortcut.rb @@ -34,7 +34,6 @@ class Chef description 'Make a shortcut to C:\\original_dir' end ``` - DOC property :shortcut_name, String, diff --git a/lib/chef/resource/windows_task.rb b/lib/chef/resource/windows_task.rb index d73030311e..2dfa22b8ca 100644 --- a/lib/chef/resource/windows_task.rb +++ b/lib/chef/resource/windows_task.rb @@ -189,11 +189,11 @@ class Chef description: "The frequency with which to run the task." property :start_day, String, - description: "Specifies the first date on which the task runs in MM/DD/YYYY format.", + description: "Specifies the first date on which the task runs in **MM/DD/YYYY** format.", default_description: "The current date." property :start_time, String, - description: "Specifies the start time to run the task, in HH:mm format." + description: "Specifies the start time to run the task, in **HH:mm** format." property :day, [String, Integer], description: "The day(s) on which the task runs." diff --git a/lib/chef/resource/windows_user_privilege.rb b/lib/chef/resource/windows_user_privilege.rb index 862a348e68..aeff7ad468 100644 --- a/lib/chef/resource/windows_user_privilege.rb +++ b/lib/chef/resource/windows_user_privilege.rb @@ -68,7 +68,7 @@ class Chef } provides :windows_user_privilege - description "The windows_user_privilege resource allows to add and set principal (User/Group) to the specified privilege. \n Ref: https://docs.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/user-rights-assignment" + description "The windows_user_privilege resource allows to add and set principal (User/Group) to the specified privilege.\n Ref: https://docs.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/user-rights-assignment" introduced "16.0" @@ -78,7 +78,7 @@ class Chef ```ruby windows_user_privilege 'Network Logon Rights' do privilege 'SeNetworkLogonRight' - users ['BUILTIN\Administrators', 'NT AUTHORITY\Authenticated Users'] + users ['BUILTIN\\Administrators', 'NT AUTHORITY\\Authenticated Users'] action :set end ``` @@ -88,7 +88,7 @@ class Chef ```ruby windows_user_privilege 'Remote interactive logon' do privilege 'SeDenyRemoteInteractiveLogonRight' - users ['Builtin\Guests', 'NT AUTHORITY\Local Account'] + users ['Builtin\\Guests', 'NT AUTHORITY\\Local Account'] action :add end ``` @@ -98,7 +98,7 @@ class Chef ```ruby windows_user_privilege 'Create Pagefile' do privilege 'SeCreatePagefilePrivilege' - users ['BUILTIN\Guests', 'BUILTIN\Administrators'] + users ['BUILTIN\\Guests', 'BUILTIN\\Administrators'] action :set end ``` @@ -108,7 +108,7 @@ class Chef ```ruby windows_user_privilege 'Create Pagefile' do privilege 'SeCreatePagefilePrivilege' - users ['BUILTIN\Guests'] + users ['BUILTIN\\Guests'] action :remove end ``` diff --git a/lib/chef/resource/yum_repository.rb b/lib/chef/resource/yum_repository.rb index 4e23244dfe..3070075959 100644 --- a/lib/chef/resource/yum_repository.rb +++ b/lib/chef/resource/yum_repository.rb @@ -95,7 +95,7 @@ class Chef description: "URL pointing to the ASCII-armored GPG key file for the repository. This is used if Yum needs a public key to verify a package and the required key hasn't been imported into the RPM database. If this option is set, Yum will automatically import the key from the specified URL. Multiple URLs may be specified in the same manner as the baseurl option. If a GPG key is required to install a package from a repository, all keys specified for that repository will be installed.\nMultiple URLs may be specified in the same manner as the baseurl option. If a GPG key is required to install a package from a repository, all keys specified for that repository will be installed." property :http_caching, String, equal_to: %w{packages all none}, - description: "Determines how upstream HTTP caches are instructed to handle any HTTP downloads that Yum does. This option can take the following values: all (all HTTP downloads should be cached), packages (only RPM package downloads should be cached, but not repository metadata downloads), or none (no HTTP downloads should be cached)" + description: "Determines how upstream HTTP caches are instructed to handle any HTTP downloads that Yum does. This option can take the following values:\n - `all` means all HTTP downloads should be cached\n - `packages` means only RPM package downloads should be cached, but not repository metadata downloads\n - `none` means no HTTP downloads should be cached.\n\nThe default value of `all` is recommended unless you are experiencing caching related issues." property :include_config, String, description: "An external configuration file using the format `url://to/some/location`." @@ -114,25 +114,25 @@ class Chef description: "Number of times any attempt to retrieve a file should retry before returning an error. Setting this to `0` makes Yum try forever." property :metadata_expire, String, regex: [/^\d+$/, /^\d+[mhd]$/, /never/], - description: "Time (in seconds) after which the metadata will expire. If the current metadata downloaded is less than the value specified, then Yum will not update the metadata against the repository. If you find that Yum is not downloading information on updates as often as you would like lower the value of this option. You can also change from the default of using seconds to using days, hours or minutes by appending a 'd', 'h' or 'm' respectively. The default is six hours to compliment yum-updates running once per hour. It is also possible to use the word `never`, meaning that the metadata will never expire. Note: When using a metalink file, the metalink must always be newer than the metadata for the repository due to the validation, so this timeout also applies to the metalink file.", - validation_message: "The metadata_expire property must be a numeric value for time in seconds, the string 'never', or a numeric value appended with with 'd', 'h', or 'm'!" + description: "Time (in seconds) after which the metadata will expire. If the current metadata downloaded is less than the value specified, then Yum will not update the metadata against the repository. If you find that Yum is not downloading information on updates as often as you would like lower the value of this option. You can also change from the default of using seconds to using days, hours or minutes by appending a `d`, `h` or `m` respectively. The default is six hours to compliment yum-updates running once per hour. It is also possible to use the word `never`, meaning that the metadata will never expire. Note: When using a metalink file, the metalink must always be newer than the metadata for the repository due to the validation, so this timeout also applies to the metalink file.", + validation_message: "The metadata_expire property must be a numeric value for time in seconds, the string 'never', or a numeric value appended with with `d`, `h`, or `m`!" property :metalink, String, description: "Specifies a URL to a metalink file for the repomd.xml, a list of mirrors for the entire repository are generated by converting the mirrors for the repomd.xml file to a baseurl." property :mirror_expire, String, regex: [/^\d+$/, /^\d+[mhd]$/], - description: "Time (in seconds) after which the mirrorlist locally cached will expire. If the current mirrorlist is less than this many seconds old then Yum will not download another copy of the mirrorlist, it has the same extra format as metadata_expire. If you find that Yum is not downloading the mirrorlists as often as you would like lower the value of this option. You can also change from the default of using seconds to using days, hours or minutes by appending a 'd', 'h' or 'm' respectively.", - validation_message: "The mirror_expire property must be a numeric value for time in seconds, the string 'never', or a numeric value appended with with 'd', 'h', or 'm'!" + description: "Time (in seconds) after which the mirrorlist locally cached will expire. If the current mirrorlist is less than this many seconds old then Yum will not download another copy of the mirrorlist, it has the same extra format as metadata_expire. If you find that Yum is not downloading the mirrorlists as often as you would like lower the value of this option. You can also change from the default of using seconds to using days, hours or minutes by appending a `d`, `h` or `m` respectively.", + validation_message: "The mirror_expire property must be a numeric value for time in seconds, the string 'never', or a numeric value appended with with `d`, `h`, or `m`!" property :mirrorlist_expire, String, regex: [/^\d+$/, /^\d+[mhd]$/], - description: "Specifies the time (in seconds) after which the mirrorlist locally cached will expire. If the current mirrorlist is less than the value specified, then Yum will not download another copy of the mirrorlist. You can also change from the default of using seconds to using days, hours or minutes by appending a 'd', 'h' or 'm' respectively.", - validation_message: "The mirrorlist_expire property must be a numeric value for time in seconds, the string 'never', or a numeric value appended with with 'd', 'h', or 'm'!" + description: "Specifies the time (in seconds) after which the mirrorlist locally cached will expire. If the current mirrorlist is less than the value specified, then Yum will not download another copy of the mirrorlist. You can also change from the default of using seconds to using days, hours or minutes by appending a `d`, `h` or `m` respectively.", + validation_message: "The mirrorlist_expire property must be a numeric value for time in seconds, the string 'never', or a numeric value appended with with `d`, `h`, or `m`!" property :mirrorlist, String, description: "URL to a file containing a list of baseurls. This can be used instead of or with the baseurl option. Substitution variables, described below, can be used with this option." property :mode, [String, Integer], - description: "Permissions mode of .repo file on disk. This is useful for scenarios where secrets are in the repo file. If this value is set to '600', normal users will not be able to use Yum search, Yum info, etc.", + description: "Permissions mode of .repo file on disk. This is useful for scenarios where secrets are in the repo file. If this value is set to `600`, normal users will not be able to use Yum search, Yum info, etc.", default: "0644" property :options, Hash, @@ -142,7 +142,7 @@ class Chef description: "Password to use with the username for basic authentication." property :priority, String, regex: /^(\d?[1-9]|[0-9][0-9])$/, - description: "Assigns a priority to a repository where the priority value is between '1' and '99' inclusive. Priorities are used to enforce ordered protection of repositories. Packages from repositories with a lower priority (higher numerical value) will never be used to upgrade packages that were installed from a repository with a higher priority (lower numerical value). The repositories with the lowest numerical priority number have the highest priority.", + description: "Assigns a priority to a repository where the priority value is between `1` and `99` inclusive. Priorities are used to enforce ordered protection of repositories. Packages from repositories with a lower priority (higher numerical value) will never be used to upgrade packages that were installed from a repository with a higher priority (lower numerical value). The repositories with the lowest numerical priority number have the highest priority.", validation_message: "The priority property must be a numeric value from 1-99!" property :proxy_password, String, |