diff --git a/data/infra/resources/alternatives.yaml b/data/infra/resources/alternatives.yaml index 46de9b9a..d72c9613 100644 --- a/data/infra/resources/alternatives.yaml +++ b/data/infra/resources/alternatives.yaml @@ -62,6 +62,8 @@ properties_list: required: false description_list: - markdown: The priority of the alternative. +target_mode: + support: full examples: | **Install an alternative**: @@ -110,4 +112,4 @@ examples: | path '/usr/bin/python3' action :remove end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/apt_package.yaml b/data/infra/resources/apt_package.yaml index 538af5f5..b6cef95a 100644 --- a/data/infra/resources/apt_package.yaml +++ b/data/infra/resources/apt_package.yaml @@ -20,18 +20,18 @@ syntax_description: | which will install the named package using all of the default options and the default action of `:install`. syntax_full_code_block: |- apt_package 'name' do - anchor_package_regex true, false # default value: false - default_release String - environment Hash # default value: {} - options String, Array - overwrite_config_files true, false # default value: false - package_name String, Array - response_file String - response_file_variables Hash # default value: {} - source String - timeout String, Integer - version String, Array - action Symbol # defaults to :install if not specified + anchor_package_regex true, false # default value: false + default_release String + environment Hash # default value: {} + options String, Array + overwrite_config_files true, false # default value: false + package_name String, Array + response_file String + response_file_variables Hash # default value: {} + source String + timeout String, Integer + version String, Array + action Symbol # defaults to :install if not specified end syntax_properties_list: syntax_full_properties_list: @@ -39,9 +39,9 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`anchor_package_regex`, `environment`, `default_release`, `options`, `overwrite_config_files`, `package_name`, `response_file`, - `response_file_variables`, `source`, `timeout`, and `version` are the properties - available to this resource." +- "`anchor_package_regex`, `default_release`, `environment`, `options`, `overwrite_config_files`, + `package_name`, `response_file`, `response_file_variables`, `source`, `timeout`, + and `version` are the properties available to this resource." actions_list: :nothing: shortcode: resources_common_actions_nothing.md @@ -68,9 +68,9 @@ properties_list: default_value: 'false' new_in: '18.3' description_list: - - markdown: A Boolean flag that allows (`false`) or prevents (`true`) apt_package - from matching the named package with packages by regular expression if it can't - find a package with the exact same name. + - markdown: A Boolean flag that indicates whether the package name, which can be + a regular expression, must match the entire name of the package (true) or if + the regular expression is allowed to match a subset of the name (false). - property: default_release ruby_type: String required: false @@ -116,6 +116,11 @@ properties_list: default_value: "{}" description_list: - markdown: A Hash of response file variables in the form of {'VARIABLE' => 'VALUE'}. +- property: source + ruby_type: String + required: false + description_list: + - markdown: The optional path to a package on the local file system. - property: timeout ruby_type: String, Integer required: false @@ -126,6 +131,11 @@ properties_list: required: false description_list: - markdown: The version of a package to be installed or upgraded. +target_mode: + support: full + introduced: '15.1' + updated: '19.0' + description: Does not support the `response_file` property in Target Mode. examples: | **Install a package using package manager**: diff --git a/data/infra/resources/apt_preference.yaml b/data/infra/resources/apt_preference.yaml index 8cee2a2d..091c4a9e 100644 --- a/data/infra/resources/apt_preference.yaml +++ b/data/infra/resources/apt_preference.yaml @@ -17,7 +17,7 @@ syntax_full_code_block: |- pin_priority String, Integer action Symbol # defaults to :add if not specified end -syntax_properties_list: +syntax_properties_list: syntax_full_properties_list: - "`apt_preference` is the resource." - "`name` is the name given to the resource block." @@ -57,6 +57,8 @@ properties_list: description_list: - markdown: Sets the Pin-Priority for a package. See for more details. +target_mode: + support: full examples: | **Pin libmysqlclient16 to a version 5.1.49-3**: diff --git a/data/infra/resources/apt_update.yaml b/data/infra/resources/apt_update.yaml index 69361c68..31d8b0f3 100644 --- a/data/infra/resources/apt_update.yaml +++ b/data/infra/resources/apt_update.yaml @@ -14,7 +14,7 @@ syntax_full_code_block: |- frequency Integer # default value: 86400 action Symbol # defaults to :periodic if not specified end -syntax_properties_list: +syntax_properties_list: syntax_full_properties_list: - "`apt_update` is the resource." - "`name` is the name given to the resource block." @@ -37,6 +37,8 @@ properties_list: description_list: - markdown: Determines how frequently (in seconds) APT repository updates are made. Use this property when the `:periodic` action is specified. +target_mode: + support: full examples: | **Update the Apt repository at a specified interval**: diff --git a/data/infra/resources/archive_file.yaml b/data/infra/resources/archive_file.yaml index ac9a3f37..7f53825c 100644 --- a/data/infra/resources/archive_file.yaml +++ b/data/infra/resources/archive_file.yaml @@ -21,7 +21,7 @@ syntax_full_code_block: |- strip_components Integer # default value: 0 action Symbol # defaults to :extract if not specified end -syntax_properties_list: +syntax_properties_list: syntax_full_properties_list: - "`archive_file` is the resource." - "`name` is the name given to the resource block." @@ -93,6 +93,7 @@ properties_list: - markdown: Remove the specified number of leading path elements. Pathnames with fewer elements will be silently skipped. This behaves similarly to tar's --strip-components command line argument. +target_mode: examples: | **Extract a zip file to a specified directory**: diff --git a/data/infra/resources/bash.yaml b/data/infra/resources/bash.yaml index fef25d8f..9a2e4154 100644 --- a/data/infra/resources/bash.yaml +++ b/data/infra/resources/bash.yaml @@ -12,6 +12,7 @@ resource_description_list: in which they are run. Use `not_if` and `only_if` to guard this resource for idempotence. syntax_full_code_block: |- bash 'name' do + cgroup String code String command String, Array # default value: 'name' unless specified creates String @@ -32,21 +33,29 @@ syntax_full_code_block: |- user String, Integer action Symbol # defaults to :run if not specified end -syntax_properties_list: +syntax_properties_list: syntax_full_properties_list: - "`bash` is the resource." - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`code`, `command`, `creates`, `cwd`, `default_env`, `domain`, `elevated`, `environment`, - `flags`, `group`, `input`, `interpreter`, `live_stream`, `login`, `password`, `returns`, - `timeout`, and `user` are the properties available to this resource." +- "`cgroup`, `code`, `command`, `creates`, `cwd`, `default_env`, `domain`, `elevated`, + `environment`, `flags`, `group`, `input`, `interpreter`, `live_stream`, `login`, + `password`, `returns`, `timeout`, and `user` are the properties available to this + resource." actions_list: :nothing: shortcode: resources_common_actions_nothing.md :run: markdown: Run a command. (default) properties_list: +- property: cgroup + ruby_type: String + required: false + new_in: '19.0' + description_list: + - markdown: 'Linux only: Run the command within a specific cgroup, creating it if + it doesn''t exist.' - property: code ruby_type: String required: true @@ -126,6 +135,11 @@ properties_list: new_in: '16.2' description_list: - markdown: An optional property to set the input sent to the command as STDIN. +- property: interpreter + ruby_type: String + required: false + description_list: + - markdown: - property: live_stream ruby_type: true, false required: false @@ -173,6 +187,8 @@ properties_list: also be specified without a domain simply as user if the domain is instead specified using the domain property. On Windows only, if this property is specified, the password property must be specified. +target_mode: + support: full examples: | **Compile an application** diff --git a/data/infra/resources/batch.yaml b/data/infra/resources/batch.yaml index 7f0a2b1c..19a16ce3 100644 --- a/data/infra/resources/batch.yaml +++ b/data/infra/resources/batch.yaml @@ -13,6 +13,7 @@ resource_description_list: run. Use `not_if` and `only_if` to guard this resource for idempotence. syntax_full_code_block: |- batch 'name' do + cgroup String code String command String, Array # default value: 'name' unless specified creates String @@ -39,23 +40,23 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`code`, `command`, `creates`, `cwd`, `default_env`, `domain`, `elevated`, `environment`, - `flags`, `group`, `input`, `interpreter`, `live_stream`, `login`, `password`, `returns`, - `timeout`, and `user` are the properties available to this resource." +- "`cgroup`, `code`, `command`, `creates`, `cwd`, `default_env`, `domain`, `elevated`, + `environment`, `flags`, `group`, `input`, `interpreter`, `live_stream`, `login`, + `password`, `returns`, `timeout`, and `user` are the properties available to this + resource." actions_list: :nothing: shortcode: resources_common_actions_nothing.md :run: - markdown: Run a batch file. + markdown: Run a command. (default) properties_list: -- property: architecture - ruby_type: Symbol +- property: cgroup + ruby_type: String required: false + new_in: '19.0' description_list: - - markdown: 'The architecture of the process under which a script is executed. If a value is not provided, - Chef Infra Client defaults to the correct value for the architecture, as determined by Ohai. - An exception is raised when anything other than `:i386` is specified for a 32-bit process. - Possible values: `:i386` (for 32-bit processes) and `:x86_64` (for 64-bit processes).' + - markdown: 'Linux only: Run the command within a specific cgroup, creating it if + it doesn''t exist.' - property: code ruby_type: String required: true @@ -66,7 +67,11 @@ properties_list: required: false default_value: The resource block's name. description_list: - - markdown: The name of the command to be executed. + - markdown: An optional property to set the command to be executed if it differs + from the resource block's name. + - note: + markdown: Use the **execute** resource to run a single command. Use multiple + **execute** resource blocks to run multiple commands. - property: creates ruby_type: String required: false @@ -77,6 +82,43 @@ properties_list: required: false description_list: - markdown: The current working directory from which the command will be run. +- property: default_env + ruby_type: true, false + required: false + default_value: 'false' + new_in: '14.2' + description_list: + - markdown: When true this enables ENV magic to add path_sanity to the PATH and + force the locale to English+UTF-8 for parsing output +- property: domain + ruby_type: String + required: false + new_in: '12.21' + description_list: + - markdown: 'Windows only: The domain of the user specified by the user property. + If not specified, the username and password specified by the `user` and `password` + properties will be used to resolve that user against the domain in which the + system running Chef Infra Client is joined, or if that system is not joined + to a domain it will resolve the user as a local account on that system. An alternative + way to specify the domain is to leave this property unspecified and specify + the domain as part of the user property.' +- property: elevated + ruby_type: true, false + required: false + default_value: 'false' + new_in: '13.3' + description_list: + - markdown: |- + Determines whether the script will run with elevated permissions to circumvent User Access Control (UAC) from interactively blocking the process. + This will cause the process to be run under a batch login instead of an interactive login. The user running chef-client needs the 'Replace a process level token' and 'Adjust Memory Quotas for a process' permissions. The user that is running the command needs the 'Log on as a batch job' permission. + Because this requires a login, the user and password properties are required. +- property: environment + ruby_type: Hash + required: false + description_list: + - markdown: 'A Hash of environment variables in the form of `({''ENV_VARIABLE'' + => ''VALUE''})`. **Note**: These variables must exist for a command to be run + successfully.' - property: flags ruby_type: String required: false @@ -88,18 +130,41 @@ properties_list: required: false description_list: - markdown: The group name or group ID that must be changed before running a command. -- property: guard_interpreter - ruby_type: Symbol +- property: input + ruby_type: String required: false - default_value: :batch + new_in: '16.2' description_list: - - markdown: 'When this property is set to `:batch`, the 64-bit version of the cmd.exe shell will be used to evaluate strings values for the not_if and only_if properties. - Set this value to `:default` to use the 32-bit version of the cmd.exe shell.' + - markdown: An optional property to set the input sent to the command as STDIN. - property: interpreter ruby_type: String required: false description_list: - - markdown: The script interpreter to use during code execution. Changing the default value of this property is not supported. + - markdown: +- property: live_stream + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Send the output of the command run by this execute resource block to + the Chef Infra Client event stream. +- property: login + ruby_type: true, false + required: false + default_value: 'false' + new_in: '17.0' + description_list: + - markdown: Use a login shell to run the commands instead of inheriting the existing + execution environment. +- property: password + ruby_type: String + required: false + new_in: '12.21' + description_list: + - markdown: 'Windows only: The password of the user specified by the user property. + This property is mandatory if user is specified on Windows and may only be specified + if user is specified. The sensitive property for this resource will automatically + be set to true if password is specified.' - property: returns ruby_type: Integer, Array required: false @@ -114,7 +179,7 @@ properties_list: description_list: - markdown: The amount of time (in seconds) a command is to wait before timing out. - property: user - ruby_type: String + ruby_type: String, Integer required: false description_list: - markdown: 'The user name of the user identity with which to launch the new process. diff --git a/data/infra/resources/bff_package.yaml b/data/infra/resources/bff_package.yaml index 6248f59b..29801988 100644 --- a/data/infra/resources/bff_package.yaml +++ b/data/infra/resources/bff_package.yaml @@ -13,8 +13,10 @@ resource_description_list: Chef Infra Client will still identify the correct provider to use based on the platform, regardless of the file extension. - notes_resource_based_on_package: true +resource_new_in: '12.0' syntax_full_code_block: |- bff_package 'name' do + environment Hash options String, Array package_name String source String @@ -28,20 +30,35 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`options`, `package_name`, `source`, `timeout`, and `version` are the properties - available to this resource." +- "`environment`, `options`, `package_name`, `source`, `timeout`, and `version` are + the properties available to this resource." actions_list: :nothing: shortcode: resources_common_actions_nothing.md :install: - markdown: (default) Install a package. If a version is specified, install the specified - version of the package. + markdown: Install a package. If a version is specified, install the specified + version of the package. (default) + :upgrade: + markdown: Install a package and ensure that a package is the latest version. :remove: markdown: Remove a package. :purge: markdown: Purge a package. This action typically removes the configuration files as well as the package. + :reconfig: + markdown: + :lock: + markdown: + :unlock: + markdown: properties_list: +- property: environment + ruby_type: Hash + required: false + new_in: '19.0' + description_list: + - markdown: A Hash of environment variables in the form of {'ENV_VARIABLE' => 'VALUE'} + to be set before running the command. - property: options ruby_type: String, Array required: false @@ -57,9 +74,7 @@ properties_list: ruby_type: String required: false description_list: - - markdown: 'Required. The path to a package in the local file system. The AIX - platform requires `source` to be a local file system path because - `installp` does not retrieve packages using HTTP or FTP.' + - markdown: The optional path to a package on the local file system. - property: timeout ruby_type: String, Integer required: false @@ -70,6 +85,8 @@ properties_list: required: false description_list: - markdown: The version of a package to be installed or upgraded. +target_mode: + support: full examples: | The **bff_package** resource is the default package provider on the AIX platform. The base **package** resource may be used, and then when the platform is AIX, Chef Infra Client will identify the correct package provider. The following examples show how to install part of the IBM XL C/C++ compiler. @@ -89,4 +106,4 @@ examples: | source '/var/tmp/IBM_XL_C_13.1.0/usr/sys/inst.images/xlccmp.13.1.0' action :install end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/breakpoint.yaml b/data/infra/resources/breakpoint.yaml index 8cb93028..6cf45225 100644 --- a/data/infra/resources/breakpoint.yaml +++ b/data/infra/resources/breakpoint.yaml @@ -26,6 +26,9 @@ actions_list: :break: markdown: Add a breakpoint for use with chef-shell (default) properties_list: [] +target_mode: + support: full + introduced: '15.1' examples: | **A recipe without a breakpoint** diff --git a/data/infra/resources/build_essential.yaml b/data/infra/resources/build_essential.yaml index b7cd4df4..f13ca10f 100644 --- a/data/infra/resources/build_essential.yaml +++ b/data/infra/resources/build_essential.yaml @@ -14,7 +14,7 @@ syntax_full_code_block: |- raise_if_unsupported true, false # default value: false action Symbol # defaults to :install if not specified end -syntax_properties_list: +syntax_properties_list: syntax_full_properties_list: - "`build_essential` is the resource." - "`name` is the name given to the resource block." @@ -37,6 +37,7 @@ properties_list: new_in: '15.5' description_list: - markdown: Raise a hard error on platforms where this resource is unsupported. +target_mode: examples: | **Install compilation packages**: diff --git a/data/infra/resources/cab_package.yaml b/data/infra/resources/cab_package.yaml index b5f507c3..1b9c3538 100644 --- a/data/infra/resources/cab_package.yaml +++ b/data/infra/resources/cab_package.yaml @@ -10,6 +10,7 @@ resource_description_list: resource_new_in: '12.15' syntax_full_code_block: |- cab_package 'name' do + environment Hash options String, Array package_name String source String # default value: The package name. @@ -23,17 +24,35 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`options`, `package_name`, `source`, `timeout`, and `version` are the properties - available to this resource." +- "`environment`, `options`, `package_name`, `source`, `timeout`, and `version` are + the properties available to this resource." actions_list: :nothing: shortcode: resources_common_actions_nothing.md :install: - markdown: Install a cabinet package. If a version is specified, install the specified + markdown: Install a package. If a version is specified, install the specified version of the package. (default) + :upgrade: + markdown: Install a package and ensure that a package is the latest version. :remove: - markdown: Remove a cabinet package. + markdown: Remove a package. + :purge: + markdown: Purge a package. This action typically removes the configuration files + as well as the package. + :reconfig: + markdown: + :lock: + markdown: + :unlock: + markdown: properties_list: +- property: environment + ruby_type: Hash + required: false + new_in: '19.0' + description_list: + - markdown: A Hash of environment variables in the form of {'ENV_VARIABLE' => 'VALUE'} + to be set before running the command. - property: options ruby_type: String, Array required: false @@ -61,6 +80,7 @@ properties_list: required: false description_list: - markdown: The version of a package to be installed or upgraded. +target_mode: examples: | **Using local path in source** @@ -88,4 +108,4 @@ examples: | source 'https://s3.amazonaws.com/my_bucket/Temp\Windows6.1-KB958488-x64.cab' action :remove end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/chef_acl.yaml b/data/infra/resources/chef_acl.yaml deleted file mode 100644 index 1c1de6ca..00000000 --- a/data/infra/resources/chef_acl.yaml +++ /dev/null @@ -1,169 +0,0 @@ ---- -title: chef_acl resource -resource: chef_acl -aliases: -- /resource_chef_acl.html -menu: - infra: - title: chef_acl - identifier: chef_infra/resources/chef_acl chef_acl - parent: chef_infra/resources - -resource_reference: true -resource_description_list: -- markdown: 'Use the **chef_acl** resource to interact with access control lists - - (ACLs) that exist on the Chef Infra Server.' -syntax_description: "The syntax for using the **chef_acl** resource in a recipe is\ - \ as\nfollows:\n\n```ruby\nchef_acl 'name' do\n attribute 'value' # see properties\ - \ section below\n ...\n action :action # see actions section below\nend\n```" -syntax_properties_list: -- '`chef_acl` tells Chef Infra Client to use the `Chef::Provider::ChefAcl` provider - during a Chef Infra Client run' -- '`name` is the name of the resource block; when the `path` property is not specified - as part of a recipe, `name` is also the name of the Chef Infra Client.' -- '`attribute` is zero (or more) of the properties that are available for this resource' -- '`action` identifies which steps Chef Infra Client will take to bring the node into - the desired state' -actions_list: - :create: - markdown: (default) - :nothing: - shortcode: resources_common_actions_nothing.md -properties_list: -- property: chef_server - ruby_type: null - required: false - description_list: - - markdown: The URL for the Chef Infra Server. -- property: complete - ruby_type: null - required: false - description_list: - - markdown: 'Use to specify if this resource defines a chef-client completely. - - When `true`, any property not specified by this resource will be - - reset to default property values.' -- property: ignore_failure - ruby_type: true, false - required: false - default_value: 'false' - description_list: - - markdown: Continue running a recipe if a resource fails for any reason. -- property: notifies - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_notifies.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_notifies_syntax.md -- property: path - ruby_type: null - required: false - description_list: - - markdown: 'A path to a directory in the chef-repo against which the ACL is - - applied. For example: `nodes`, `nodes/*`, `nodes/my_node`, `*/*`, - - `**`, `roles/base`, `data/secrets`, `cookbooks/apache2`, `/users/*`, - - and so on.' -- property: raw_json - ruby_type: null - required: false - description_list: - - markdown: "Chef Infra Client as JSON data. For example:\n\n```javascript\n{\n\ - \ \"clientname\": \"client_name\",\n \"orgname\": \"org_name\",\n \"validator\"\ - : false,\n \"certificate\": \"-----BEGIN CERTIFICATE-----\\n\n \ - \ ...\n 1234567890abcdefghijklmnopq\\n\n \ - \ ...\n -----END CERTIFICATE-----\\n\",\n \"name\": \"\ - node_name\"\n}\n```" -- property: recursive - ruby_type: null - required: false - description_list: - - markdown: 'Use to apply changes to child objects. Use `:on_change` to apply - - changes to child objects only if the parent object changes. Set to - - `true` to apply changes even if the parent object does not change. - - Set to `false` to prevent any changes. Default value: `:on_change`.' -- property: remove_rights - ruby_type: null - required: false - description_list: - - markdown: 'Use to remove rights. For example: - - - ```ruby - - remove_rights :read, :users => ''jkeiser'', :groups => [ ''admins'', ''users'' - ] - - ``` - - - or: - - - ```ruby - - remove_rights [ :create, :read ], :users => [ ''jkeiser'', ''adam'' ] - - ``` - - - or: - - - ```ruby - - remove_rights :all, :users => [ ''jkeiser'', ''adam'' ] - - ```' -- property: rights - ruby_type: null - required: false - description_list: - - markdown: 'Use to add rights. Syntax: - - `:right, :right => ''user'', :groups => [ ''group'', ''group'']`. For - - example: - - - ```ruby - - rights :read, :users => ''jkeiser'', :groups => [ ''admins'', ''users'' ] - - ``` - - - or: - - - ```ruby - - rights [ :create, :read ], :users => [ ''jkeiser'', ''adam'' ] - - ``` - - - or: - - - ```ruby - - rights :all, :users => ''jkeiser'' - - ```' -- property: subscribes - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_subscribes.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_subscribes_syntax.md - diff --git a/data/infra/resources/chef_client.yaml b/data/infra/resources/chef_client.yaml deleted file mode 100644 index 2a5628ca..00000000 --- a/data/infra/resources/chef_client.yaml +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: chef_client resource -resource: chef_client -aliases: -- /resource_chef_client.html -menu: - infra: - title: chef_client - identifier: chef_infra/resources/chef_client chef_client - parent: chef_infra/resources - -resource_reference: true -resource_description_list: -- markdown: Use the **chef_client** resource to create clients on your Chef Infra Server from within Chef Infra cookbook code. -syntax_description: "The syntax for using the **chef_client** resource in a recipe\ - \ is as\nfollows:\n\n```ruby\nchef_client 'name' do\n attribute 'value' # see\ - \ properties section below\n ...\n action :action # see actions section below\n\ - end\n```" -syntax_properties_list: -- '`chef_client` tells Chef Infra Client to use the `Chef::Provider::ChefClient` provider - during a Chef Infra Client run' -- '`name` is the name of the resource block; when the `name` property is not specified - as part of a recipe, `name` is also the name of the Chef Infra Client' -- '`attribute` is zero (or more) of the properties that are available for this resource' -- '`action` identifies which steps Chef Infra Client will take to bring the node into - the desired state' -actions_list: - :create: - markdown: (default) Use to create a chef-client. - :delete: - markdown: Use to delete a chef-client. - :nothing: - shortcode: resources_common_actions_nothing.md - :regenerate_keys: - markdown: Use to regenerate the RSA public key for a chef-client. -properties_list: -- property: admin - ruby_type: null - required: false - description_list: - - markdown: Use to specify whether Chef Infra Client is an API client. -- property: chef_server - ruby_type: null - required: false - description_list: - - markdown: The URL for the Chef Infra Server. -- property: complete - ruby_type: null - required: false - description_list: - - markdown: 'Use to specify if this resource defines a chef-client completely. - - When `true`, any property not specified by this resource will be - - reset to default property values.' -- property: ignore_failure - ruby_type: true, false - required: false - default_value: 'false' - description_list: - - markdown: Continue running a recipe if a resource fails for any reason. -- property: name - ruby_type: null - required: false - description_list: - - markdown: The name of Chef Infra Client. -- property: notifies - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_notifies.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_notifies_syntax.md -- property: output_key_format - ruby_type: null - required: false - description_list: - - markdown: 'Use to specify the format of a public key. Possible values: `pem`, - `der`, or `openssh`. Default value: `openssh`.' -- property: output_key_path - ruby_type: null - required: false - description_list: - - markdown: 'Use to specify the path to the location in which a public key will - - be written.' -- property: raw_json - ruby_type: null - required: false - description_list: - - markdown: "Chef Infra Client as JSON data. For example:\n\n```javascript\n{\n\ - \ \"clientname\": \"client_name\",\n \"orgname\": \"org_name\",\n \"validator\"\ - : false,\n \"certificate\": \"-----BEGIN CERTIFICATE-----\\n\n \ - \ ...\n 1234567890abcdefghijklmnopq\\n\n \ - \ ...\n -----END CERTIFICATE-----\\n\",\n \"name\": \"\ - node_name\"\n}\n```" -- property: source_key - ruby_type: null - required: false - description_list: - - markdown: 'Use to copy a public or private key, but apply a different `format` - - and `password`. Use in conjunction with `source_key_pass_phrase` and - - `source_key_path`.' -- property: source_key_pass_phrase - ruby_type: null - required: false - description_list: - - markdown: 'The pass phrase for the public key. Use in conjunction with - - `source_key` and `source_key_path`.' -- property: source_key_path - ruby_type: null - required: false - description_list: - - markdown: 'The path to the public key. Use in conjunction with `source_key` and - - `source_key_pass_phrase`.' -- property: subscribes - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_subscribes.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_subscribes_syntax.md -- property: validator - ruby_type: null - required: false - description_list: - - markdown: Use to specify if Chef Infra Client is a chef-validator. - diff --git a/data/infra/resources/chef_client_config.yaml b/data/infra/resources/chef_client_config.yaml index d85d534c..b98fcdeb 100644 --- a/data/infra/resources/chef_client_config.yaml +++ b/data/infra/resources/chef_client_config.yaml @@ -29,7 +29,7 @@ syntax_full_code_block: |- https_proxy String log_level Symbol log_location String, Symbol - minimal_ohai true, false + minimal_ohai true, false # default value: false named_run_list String no_proxy String, Array # default value: [] node_name String @@ -38,7 +38,7 @@ syntax_full_code_block: |- pid_file String policy_group String policy_name String - policy_persist_run_list true, false + policy_persist_run_list true, false # default value: false report_handlers Array # default value: [] rubygems_url String, Array ssl_verify_mode Symbol, String @@ -194,11 +194,12 @@ properties_list: - property: minimal_ohai ruby_type: true, false required: false + default_value: 'false' description_list: - markdown: Run a minimal set of Ohai plugins providing data necessary for the execution of Chef Infra Client's built-in resources. Setting this to true will skip many large and time consuming data sets such as `cloud` or `packages`. Setting this - this to true may break cookbooks that assume all Ohai data will be present. + to true may break cookbooks that assume all Ohai data will be present. - property: named_run_list ruby_type: String required: false @@ -260,6 +261,7 @@ properties_list: - property: policy_persist_run_list ruby_type: true, false required: false + default_value: 'false' new_in: '17.3' description_list: - markdown: Override run lists defined in a Policyfile with the `run_list` defined @@ -280,8 +282,8 @@ properties_list: new_in: '17.11' description_list: - markdown: The location to source rubygems. It can be set to a string or array - of strings for URIs to set as rubygems sources. This allows individuals to set up - an internal mirror of rubygems for airgapped environments. + of strings for URIs to set as rubygems sources. This allows individuals to setup + an internal mirror of rubygems for “airgapped” environments. - property: ssl_verify_mode ruby_type: Symbol, String required: false @@ -312,6 +314,8 @@ properties_list: markdown: The configuration directory will not be created if it already exists, which allows you to further control the setup of that directory outside of this resource. +target_mode: + support: full examples: | **Bare minimum Chef Infra Client client.rb**: diff --git a/data/infra/resources/chef_client_cron.yaml b/data/infra/resources/chef_client_cron.yaml index b516c115..d4aacf61 100644 --- a/data/infra/resources/chef_client_cron.yaml +++ b/data/infra/resources/chef_client_cron.yaml @@ -13,7 +13,7 @@ syntax_full_code_block: |- chef_client_cron 'name' do accept_chef_license true, false # default value: false append_log_file true, false # default value: true - chef_binary_path String # default value: "/opt/chef/bin/chef-client" + chef_binary_path String comment String config_directory String # default value: "/etc/chef" daemon_options Array # default value: [] @@ -65,7 +65,7 @@ properties_list: - property: chef_binary_path ruby_type: String required: false - default_value: "/opt/chef/bin/chef-client" + default_value: lazy default description_list: - markdown: The path to the chef-client binary. - property: comment @@ -170,6 +170,7 @@ properties_list: description_list: - markdown: The day of the week on which Chef Infra Client is to run (0-7, mon-sun, or *), where Sunday is both 0 and 7. +target_mode: examples: | **Setup Chef Infra Client to run using the default 30 minute cadence**: diff --git a/data/infra/resources/chef_client_hab_ca_cert.yaml b/data/infra/resources/chef_client_hab_ca_cert.yaml new file mode 100644 index 00000000..446fc998 --- /dev/null +++ b/data/infra/resources/chef_client_hab_ca_cert.yaml @@ -0,0 +1,76 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: chef_client_hab_ca_cert +resource_description_list: +- markdown: Use the **chef_client_hab_ca_cert** resource to add certificates to habitat + Chef Infra Client's CA bundle. This allows the Chef Infra Client to communicate + with internal encrypted resources without errors. To make sure these CA certs + take effect the `ssl_ca_file` should be configured to point to the CA Cert file + path of `core/cacerts` habitat package. +resource_new_in: '19.1' +syntax_full_code_block: |- + chef_client_hab_ca_cert 'name' do + cert_name String # default value: 'name' unless specified + certificate String + action Symbol # defaults to :add if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`chef_client_hab_ca_cert` is the resource." +- "`name` is the name given to the resource block." +- "`action` identifies which steps Chef Infra Client will take to bring the node into + the desired state." +- "`cert_name` and `certificate` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :add: + markdown: Add a local certificate to habitat based Chef Infra Client's CA bundle. + (default) +properties_list: +- property: cert_name + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: The name to use for the certificate. If not provided the name of the + resource block will be used instead. +- property: certificate + ruby_type: String + required: true + description_list: + - markdown: The text of the certificate file including the BEGIN/END comment lines. +target_mode: +examples: | + **Trust a self signed certificate**: + + ```ruby + chef_client_hab_ca_cert 'self-signed.badssl.com' do + certificate <<~CERT + -----BEGIN CERTIFICATE----- + MIIDeTCCAmGgAwIBAgIJAPziuikCTox4MA0GCSqGSIb3DQEBCwUAMGIxCzAJBgNV + BAYTAlVTMRMwEQYDVQQIDApDYWxpZm9ybmlhMRYwFAYDVQQHDA1TYW4gRnJhbmNp + c2NvMQ8wDQYDVQQKDAZCYWRTU0wxFTATBgNVBAMMDCouYmFkc3NsLmNvbTAeFw0x + OTEwMDkyMzQxNTJaFw0yMTEwMDgyMzQxNTJaMGIxCzAJBgNVBAYTAlVTMRMwEQYD + VQQIDApDYWxpZm9ybmlhMRYwFAYDVQQHDA1TYW4gRnJhbmNpc2NvMQ8wDQYDVQQK + DAZCYWRTU0wxFTATBgNVBAMMDCouYmFkc3NsLmNvbTCCASIwDQYJKoZIhvcNAQEB + BQADggEPADCCAQoCggEBAMIE7PiM7gTCs9hQ1XBYzJMY61yoaEmwIrX5lZ6xKyx2 + PmzAS2BMTOqytMAPgLaw+XLJhgL5XEFdEyt/ccRLvOmULlA3pmccYYz2QULFRtMW + hyefdOsKnRFSJiFzbIRMeVXk0WvoBj1IFVKtsyjbqv9u/2CVSndrOfEk0TG23U3A + xPxTuW1CrbV8/q71FdIzSOciccfCFHpsKOo3St/qbLVytH5aohbcabFXRNsKEqve + ww9HdFxBIuGa+RuT5q0iBikusbpJHAwnnqP7i/dAcgCskgjZjFeEU4EFy+b+a1SY + QCeFxxC7c3DvaRhBB0VVfPlkPz0sw6l865MaTIbRyoUCAwEAAaMyMDAwCQYDVR0T + BAIwADAjBgNVHREEHDAaggwqLmJhZHNzbC5jb22CCmJhZHNzbC5jb20wDQYJKoZI + hvcNAQELBQADggEBAGlwCdbPxflZfYOaukZGCaxYK6gpincX4Lla4Ui2WdeQxE95 + w7fChXvP3YkE3UYUE7mupZ0eg4ZILr/A0e7JQDsgIu/SRTUE0domCKgPZ8v99k3A + vka4LpLK51jHJJK7EFgo3ca2nldd97GM0MU41xHFk8qaK1tWJkfrrfcGwDJ4GQPI + iLlm6i0yHq1Qg1RypAXJy5dTlRXlCLd8ufWhhiwW0W75Va5AEnJuqpQrKwl3KQVe + wGj67WWRgLfSr+4QG1mNvCZb2CkjZWmxkGPuoP40/y7Yu5OFqxP5tAjj4YixCYTW + EVA0pmzIzgBg+JIe3PdRy27T0asgQW/F4TY61Yk= + -----END CERTIFICATE----- + CERT + end + ``` diff --git a/data/infra/resources/chef_client_launchd.yaml b/data/infra/resources/chef_client_launchd.yaml index 986daf5d..10adc6ec 100644 --- a/data/infra/resources/chef_client_launchd.yaml +++ b/data/infra/resources/chef_client_launchd.yaml @@ -11,7 +11,7 @@ resource_new_in: '16.5' syntax_full_code_block: |- chef_client_launchd 'name' do accept_chef_license true, false # default value: false - chef_binary_path String # default value: "/opt/chef/bin/chef-client" + chef_binary_path String config_directory String # default value: "/etc/chef" daemon_options Array # default value: [] environment Hash # default value: {} @@ -52,7 +52,7 @@ properties_list: - property: chef_binary_path ruby_type: String required: false - default_value: "/opt/chef/bin/chef-client" + default_value: lazy default description_list: - markdown: The path to the chef-client binary. - property: config_directory @@ -123,6 +123,7 @@ properties_list: default_value: "/var/root" description_list: - markdown: The working directory to run the Chef Infra Client from. +target_mode: examples: | **Set the Chef Infra Client to run on a schedule**: diff --git a/data/infra/resources/chef_client_scheduled_task.yaml b/data/infra/resources/chef_client_scheduled_task.yaml index a614b217..9ddf7c73 100644 --- a/data/infra/resources/chef_client_scheduled_task.yaml +++ b/data/infra/resources/chef_client_scheduled_task.yaml @@ -12,8 +12,8 @@ resource_new_in: '16.0' syntax_full_code_block: |- chef_client_scheduled_task 'name' do accept_chef_license true, false # default value: false - chef_binary_path String # default value: "C:/opscode/chef/bin/chef-client" - config_directory String # default value: "/etc/chef" + chef_binary_path String + config_directory String # default value: "C:/chef" daemon_options Array # default value: [] frequency String # default value: "minute" frequency_modifier Integer, String # default value: "30 if frequency is 'minute', 1 otherwise" @@ -57,7 +57,7 @@ properties_list: - property: chef_binary_path ruby_type: String required: false - default_value: C:/opscode/chef/bin/chef-client + default_value: lazy default description_list: - markdown: The path to the chef-client binary. - property: config_directory @@ -155,6 +155,7 @@ properties_list: default_value: System description_list: - markdown: The name of the user that Chef Infra Client runs as. +target_mode: examples: | **Setup Chef Infra Client to run using the default 30 minute cadence**: diff --git a/data/infra/resources/chef_client_systemd_timer.yaml b/data/infra/resources/chef_client_systemd_timer.yaml index 1f3a84c2..ba9e5052 100644 --- a/data/infra/resources/chef_client_systemd_timer.yaml +++ b/data/infra/resources/chef_client_systemd_timer.yaml @@ -11,7 +11,7 @@ resource_new_in: '16.0' syntax_full_code_block: |- chef_client_systemd_timer 'name' do accept_chef_license true, false # default value: false - chef_binary_path String # default value: "/opt/chef/bin/chef-client" + chef_binary_path String config_directory String # default value: "/etc/chef" cpu_quota Integer, String daemon_options Array # default value: [] @@ -52,7 +52,7 @@ properties_list: - property: chef_binary_path ruby_type: String required: false - default_value: "/opt/chef/bin/chef-client" + default_value: lazy default description_list: - markdown: The path to the chef-client binary. - property: config_directory @@ -140,6 +140,7 @@ properties_list: default_value: root description_list: - markdown: The name of the user that Chef Infra Client runs as. +target_mode: examples: | **Setup Chef Infra Client to run using the default 30 minute cadence**: diff --git a/data/infra/resources/chef_client_trusted_certificate.yaml b/data/infra/resources/chef_client_trusted_certificate.yaml index b6011ef1..d4df1e2a 100644 --- a/data/infra/resources/chef_client_trusted_certificate.yaml +++ b/data/infra/resources/chef_client_trusted_certificate.yaml @@ -44,6 +44,7 @@ properties_list: required: true description_list: - markdown: The text of the certificate file including the BEGIN/END comment lines. +target_mode: examples: | **Trust a self signed certificate**: @@ -73,4 +74,4 @@ examples: | -----END CERTIFICATE----- CERT end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/chef_container.yaml b/data/infra/resources/chef_container.yaml deleted file mode 100644 index 89a8fef1..00000000 --- a/data/infra/resources/chef_container.yaml +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: chef_container resource -resource: chef_container -aliases: -- /resource_chef_container.html -menu: - infra: - title: chef_container - identifier: chef_infra/resources/chef_container chef_container - parent: chef_infra/resources - -resource_reference: true -resource_description_list: -- markdown: 'Use the **chef_container** resource to interact with container objects - - that exist on the Chef Infra Server.' -syntax_description: "The syntax for using the **chef_container** resource in a recipe\ - \ is as\nfollows:\n\n```ruby\nchef_container 'name' do\n attribute 'value' # see\ - \ properties section below\n ...\n action :action # see actions section below\n\ - end\n```" -syntax_properties_list: -- '`chef_container` tells Chef Infra Client to use the `Chef::Provider::ChefContainer` - provider during a Chef Infra Client run' -- '`name` is the name of the resource block' -- '`attribute` is zero (or more) of the properties that are available for this resource' -- '`action` identifies which steps Chef Infra Client will take to bring the node into - the desired state' -actions_list: - :create: - markdown: (default) - :delete: - markdown: '' - :nothing: - shortcode: resources_common_actions_nothing.md -properties_list: -- property: chef_server - ruby_type: null - required: false - description_list: - - markdown: The URL for the Chef Infra Server. -- property: ignore_failure - ruby_type: true, false - required: false - default_value: 'false' - description_list: - - markdown: Continue running a recipe if a resource fails for any reason. -- property: name - ruby_type: null - required: false - description_list: - - markdown: The name of the container. -- property: notifies - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_notifies.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_notifies_syntax.md -- property: subscribes - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_subscribes.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_subscribes_syntax.md - diff --git a/data/infra/resources/chef_data_bag.yaml b/data/infra/resources/chef_data_bag.yaml deleted file mode 100644 index 5e5bd0e1..00000000 --- a/data/infra/resources/chef_data_bag.yaml +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: chef_data_bag resource -resource: chef_data_bag -aliases: -- /resource_chef_data_bag.html -menu: - infra: - title: chef_data_bag - identifier: chef_infra/resources/chef_data_bag chef_data_bag - parent: chef_infra/resources - -resource_reference: true -resource_description_list: -- shortcode: data_bag.md -- markdown: Use the **chef_data_bag** resource to manage data bags. -syntax_description: "The syntax for using the **chef_data_bag** resource in a recipe\ - \ is as\nfollows:\n\n```ruby\nchef_data_bag 'name' do\n attribute 'value' # see\ - \ properties section below\n ...\n action :action # see actions section below\n\ - end\n```" -syntax_properties_list: -- '`chef_data_bag` tells Chef Infra Client to use the `Chef::Provider::ChefDataBag` - provider during a Chef Infra Client run' -- '`name` is the name of the resource block and also the name of the data bag' -- '`attribute` is zero (or more) of the properties that are available for this resource' -- '`action` identifies which steps Chef Infra Client will take to bring the node into - the desired state' -actions_list: - :create: - markdown: (default) Use to create a data bag. - :delete: - markdown: Use to delete a data bag. - :nothing: - shortcode: resources_common_actions_nothing.md -properties_list: -- property: chef_server - ruby_type: null - required: false - description_list: - - markdown: The URL for the Chef Infra Server. -- property: ignore_failure - ruby_type: true, false - required: false - default_value: 'false' - description_list: - - markdown: Continue running a recipe if a resource fails for any reason. -- property: name - ruby_type: null - required: false - description_list: - - markdown: The name of the data bag. -- property: notifies - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_notifies.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_notifies_syntax.md -- property: subscribes - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_subscribes.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_subscribes_syntax.md - diff --git a/data/infra/resources/chef_data_bag_item.yaml b/data/infra/resources/chef_data_bag_item.yaml deleted file mode 100644 index 1ef96a6c..00000000 --- a/data/infra/resources/chef_data_bag_item.yaml +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: chef_data_bag_item resource -resource: chef_data_bag_item -aliases: -- /resource_chef_data_bag_item.html -menu: - infra: - title: chef_data_bag_item - identifier: chef_infra/resources/chef_data_bag_item chef_data_bag_item - parent: chef_infra/resources - -resource_reference: true -resource_description_list: -- shortcode: data_bag_item.md -- markdown: Use the **chef_data_bag_item** resource to manage data bag items. -syntax_description: "The syntax for using the **chef_data_bag_item** resource in a\ - \ recipe\nis as follows:\n\n```ruby\nchef_data_bag_item 'name' do\n attribute\ - \ 'value' # see properties section below\n ...\n action :action # see actions\ - \ section below\nend\n```" -syntax_properties_list: -- '`chef_data_bag_item` tells Chef Infra Client to use the `Chef::Provider::ChefDataBagItem` - provider during a Chef Infra Client run' -- '`name` is the name of the resource block and also the name of the data bag item' -- '`attribute` is zero (or more) of the properties that are available for this resource' -- '`action` identifies which steps Chef Infra Client will take to bring the node into - the desired state' -actions_list: - :create: - markdown: (default) Use to create a data bag item. - :delete: - markdown: Use to delete a data bag item. - :nothing: - shortcode: resources_common_actions_nothing.md -properties_list: -- property: chef_server - ruby_type: null - required: false - description_list: - - markdown: The URL for the Chef Infra Server. -- property: complete - ruby_type: null - required: false - description_list: - - markdown: 'Use to specify if this resource defines a data bag item completely. - - When `true`, any property not specified by this resource will be - - reset to default property values.' -- property: encrypt - ruby_type: null - required: false - description_list: - - markdown: Use to specify whether encryption is used for a data bag item. -- property: encryption_version - ruby_type: null - required: false - description_list: - - markdown: 'The minimum required version of data bag encryption. Possible - - values: `0`, `1`, `2`, and `3`. When all of the machines in an - - organization are running chef-client version 13.0.113 (or higher), it is - - recommended that this value be set to `3`.' -- property: ignore_failure - ruby_type: true, false - required: false - default_value: 'false' - description_list: - - markdown: Continue running a recipe if a resource fails for any reason. -- property: notifies - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_notifies.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_notifies_syntax.md -- property: raw_data - ruby_type: null - required: false - description_list: - - markdown: 'Use to create a data bag from a local file from - - `./data_bags/bag_name/file`.' -- property: raw_json - ruby_type: null - required: false - description_list: - - markdown: "The data bag item as JSON data. For example:\n\n```javascript\n{\n\ - \ \"id\": \"adam\",\n \"real_name\": \"Adam Brent Jacob\"\n}\n```" -- property: subscribes - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_subscribes.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_subscribes_syntax.md - diff --git a/data/infra/resources/chef_environment.yaml b/data/infra/resources/chef_environment.yaml deleted file mode 100644 index 3c35ea0d..00000000 --- a/data/infra/resources/chef_environment.yaml +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: chef_environment resource -resource: chef_environment -aliases: -- /resource_chef_environment.html -menu: - infra: - title: chef_environment - identifier: chef_infra/resources/chef_environment chef_environment - parent: chef_infra/resources - -resource_reference: true -resource_description_list: -- shortcode: environment.md -- markdown: Use the **chef_environment** resource to manage environments. -syntax_description: "The syntax for using the **chef_environment** resource in a recipe\ - \ is\nas follows:\n\n```ruby\nchef_environment 'name' do\n attribute 'value' #\ - \ see properties section below\n ...\n action :action # see actions section below\n\ - end\n```" -syntax_properties_list: -- '`chef_environment` tells Chef Infra Client to use the `Chef::Provider::ChefEnvironment` - provider during a Chef Infra Client run' -- '`name` is the name of the resource block; when the `name` property is not specified - as part of a recipe, `name` is also the name of the environment' -- '`attribute` is zero (or more) of the properties that are available for this resource' -- '`action` identifies which steps Chef Infra Client will take to bring the node into - the desired state' -actions_list: - :create: - markdown: (default) Use to create an environment. - :delete: - markdown: Use to delete an environment. - :nothing: - shortcode: resources_common_actions_nothing.md -properties_list: -- property: chef_server - ruby_type: null - required: false - description_list: - - markdown: The URL for the Chef Infra Server. -- property: complete - ruby_type: null - required: false - description_list: - - markdown: 'Use to specify if this resource defines an environment completely. - - When `true`, any property not specified by this resource will be - - reset to default property values.' -- property: cookbook_versions - ruby_type: null - required: false - description_list: - - markdown: 'The cookbook versions used with the environment. Default value: - - `{}`.' -- property: default_attributes - ruby_type: null - required: false - description_list: - - shortcode: node_attribute_type_default.md - - markdown: 'Default value: `{}`.' -- property: description - ruby_type: null - required: false - description_list: - - markdown: 'The description of the environment. This value populates the - - description field for the environment on the Chef Infra Server.' -- property: ignore_failure - ruby_type: true, false - required: false - default_value: 'false' - description_list: - - markdown: Continue running a recipe if a resource fails for any reason. -- property: name - ruby_type: null - required: false - description_list: - - markdown: The name of the environment. -- property: notifies - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_notifies.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_notifies_syntax.md -- property: override_attributes - ruby_type: null - required: false - description_list: - - shortcode: node_attribute_type_override.md - - markdown: 'Default value: `{}`.' -- property: raw_json - ruby_type: null - required: false - description_list: - - markdown: "The environment as JSON data. For example:\n\n```javascript\n{\n \ - \ \"name\":\"backend\",\n \"description\":\"\",\n \"cookbook_versions\":{},\n\ - \ \"json_class\":\"Chef::Environment\",\n \"chef_type\":\"environment\",\n\ - \ \"default_attributes\":{},\n \"override_attributes\":{}\n}\n```" -- property: subscribes - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_subscribes.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_subscribes_syntax.md - diff --git a/data/infra/resources/chef_gem.yaml b/data/infra/resources/chef_gem.yaml index 738bd842..581417fb 100644 --- a/data/infra/resources/chef_gem.yaml +++ b/data/infra/resources/chef_gem.yaml @@ -16,10 +16,16 @@ resource_description_list: - Runs its actions immediately, before convergence, allowing a gem to be used in a recipe immediately after it is installed. - Runs `Gem.clear_paths` after the action, ensuring that gem is aware of changes so that it can be required immediately after it is installed. - warning: - shortcode: resource_chef_gem_gem_package_install.md + markdown: |- + The **chef_gem** and **gem_package** resources are both used to install Ruby gems. For any machine on which Chef Infra Client is + installed, there are two instances of Ruby. One is the standard, system-wide instance of Ruby and the other is a dedicated instance that is + available only to Chef Infra Client. + Use the **chef_gem** resource to install gems into the instance of Ruby that is dedicated to Chef Infra Client. + Use the **gem_package** resource to install all other gems (i.e. install gems system-wide). syntax_full_code_block: |- chef_gem 'name' do clear_sources true, false + environment Hash gem_binary String include_default_source true, false options String, Hash, Array @@ -35,23 +41,28 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`clear_sources`, `gem_binary`, `include_default_source`, `options`, `package_name`, - `source`, `timeout`, and `version` are the properties available to this resource." +- "`clear_sources`, `environment`, `gem_binary`, `include_default_source`, `options`, + `package_name`, `source`, `timeout`, and `version` are the properties available + to this resource." actions_list: - :install: - markdown: Install a gem. If a version is specified, install the specified - version of the gem. (default) :nothing: shortcode: resources_common_actions_nothing.md + :install: + markdown: Install a package. If a version is specified, install the specified + version of the package. (default) + :upgrade: + markdown: Install a package and ensure that a package is the latest version. + :remove: + markdown: Remove a package. :purge: - markdown: Purge a gem. This action typically removes the configuration files - as well as the gem. + markdown: Purge a package. This action typically removes the configuration files + as well as the package. :reconfig: - markdown: Reconfigure a gem. This action requires a response file. - :remove: - markdown: Remove a gem. - :upgrade: - markdown: Install a gem and ensure that a gem is the latest version. + markdown: + :lock: + markdown: + :unlock: + markdown: properties_list: - property: clear_sources ruby_type: true, false @@ -60,6 +71,13 @@ properties_list: description_list: - markdown: Set to `true` to download a gem from the path specified by the `source` property (and not from RubyGems). +- property: environment + ruby_type: Hash + required: false + new_in: '19.0' + description_list: + - markdown: A Hash of environment variables in the form of {'ENV_VARIABLE' => 'VALUE'} + to be set before running the command. - property: gem_binary ruby_type: String required: false @@ -107,6 +125,7 @@ properties_list: required: false description_list: - markdown: The version of a package to be installed or upgraded. +target_mode: examples: | **Compile time vs. converge time installation of gems** diff --git a/data/infra/resources/chef_group.yaml b/data/infra/resources/chef_group.yaml deleted file mode 100644 index fe460286..00000000 --- a/data/infra/resources/chef_group.yaml +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: chef_group resource -resource: chef_group -aliases: -- /resource_chef_group.html -menu: - infra: - title: chef_group - identifier: chef_infra/resources/chef_group chef_group - parent: chef_infra/resources - -resource_reference: true -resource_description_list: -- markdown: 'Use the **chef_group** resource to interact with group objects that - - exist on the Chef server.' -syntax_description: "The syntax for using the **chef_group** resource in a recipe\ - \ is as\nfollows:\n\n```ruby\nchef_group 'name' do\n attribute 'value' # see properties\ - \ section below\n ...\n action :action # see actions section below\nend\n```" -syntax_properties_list: -- '`chef_group` tells Chef Infra Client to use the `Chef::Provider::ChefGroup` provider - during a Chef Infra Client run' -- '`name` is the name of the resource block' -- '`attribute` is zero (or more) of the properties that are available for this resource' -- '`action` identifies which steps Chef Infra Client will take to bring the node into - the desired state' -actions_list: - :create: - markdown: (default) - :delete: - markdown: '' - :nothing: - shortcode: resources_common_actions_nothing.md -properties_list: -- property: chef_server - ruby_type: null - required: false - description_list: - - markdown: The URL for the Chef server. -- property: clients - ruby_type: null - required: false - description_list: - - markdown: '...' -- property: complete - ruby_type: null - required: false - description_list: - - markdown: 'Use to specify if this resource defines a chef-client completely. - - When `true`, any property not specified by this resource will be - - reset to default property values.' -- property: groups - ruby_type: null - required: false - description_list: - - markdown: '...' -- property: ignore_failure - ruby_type: true, false - required: false - default_value: 'false' - description_list: - - markdown: Continue running a recipe if a resource fails for any reason. -- property: notifies - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_notifies.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_notifies_syntax.md -- property: raw_json - ruby_type: null - required: false - description_list: - - markdown: "The group as JSON data. For example:\n\n```javascript\n{\n :groupname\ - \ => \"chef\"\n}\n```" -- property: remove_clients - ruby_type: null - required: false - description_list: - - markdown: '...' -- property: remove_groups - ruby_type: null - required: false - description_list: - - markdown: '...' -- property: remove_users - ruby_type: null - required: false - description_list: - - markdown: '...' -- property: subscribes - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_subscribes.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_subscribes_syntax.md -- property: users - ruby_type: null - required: false - description_list: - - markdown: '...' - diff --git a/data/infra/resources/chef_handler.yaml b/data/infra/resources/chef_handler.yaml index 3ccc2f11..b8768eb6 100644 --- a/data/infra/resources/chef_handler.yaml +++ b/data/infra/resources/chef_handler.yaml @@ -34,14 +34,14 @@ syntax_full_properties_list: - "`arguments`, `class_name`, `source`, and `type` are the properties available to this resource." actions_list: - :disable: - markdown: Disables the handler for the current Chef Infra Client run on the current - node. + :nothing: + shortcode: resources_common_actions_nothing.md :enable: markdown: Enables the handler for the current Chef Infra Client run on the current node. (default) - :nothing: - shortcode: resources_common_actions_nothing.md + :disable: + markdown: Disables the handler for the current Chef Infra Client run on the current + node. properties_list: - property: arguments ruby_type: Array, Hash @@ -81,6 +81,7 @@ properties_list: default_value: '{"report"=>true, "exception"=>true}' description_list: - markdown: The type of handler to register as, i.e. :report, :exception or both. +target_mode: examples: | **Enable the 'MyHandler' handler** diff --git a/data/infra/resources/chef_node.yaml b/data/infra/resources/chef_node.yaml deleted file mode 100644 index f94c999b..00000000 --- a/data/infra/resources/chef_node.yaml +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: chef_node resource -resource: chef_node -aliases: -- /resource_chef_node.html -menu: - infra: - title: chef_node - identifier: chef_infra/resources/chef_node chef_node - parent: chef_infra/resources - -resource_reference: true -resource_description_list: -- shortcode: node.md -- markdown: Use the **chef_node** resource to manage nodes. -syntax_description: "The syntax for using the **chef_node** resource in a recipe is\ - \ as\nfollows:\n\n```ruby\nchef_node 'name' do\n attribute 'value' # see properties\ - \ section below\n ...\n action :action # see actions section below\nend\n```" -syntax_properties_list: -- '`chef_node` tells Chef Infra Client to use the `Chef::Provider::ChefNode` provider - during a Chef Infra Client run' -- '`name` is the name of the resource block' -- '`attribute` is zero (or more) of the properties that are available for this resource' -- '`action` identifies which steps Chef Infra Client will take to bring the node into - the desired state' -actions_list: - :create: - markdown: (default) Use to create a node. - :delete: - markdown: Use to delete a node. - :nothing: - shortcode: resources_common_actions_nothing.md -properties_list: -- property: automatic_attributes - ruby_type: null - required: false - description_list: - - shortcode: node_attribute_type_automatic.md - - markdown: 'Default value: `{}`.' -- property: chef_environment - ruby_type: null - required: false - description_list: - - markdown: 'The Chef Infra Server environment in which this node should exist (or does - - exist).' -- property: chef_server - ruby_type: null - required: false - description_list: - - markdown: The URL for the Chef Infra Server. -- property: complete - ruby_type: null - required: false - description_list: - - markdown: 'Use to specify if this resource defines a node completely. When - - `true`, any property not specified by this resource will be reset to - - default property values.' -- property: default_attributes - ruby_type: null - required: false - description_list: - - shortcode: node_attribute_type_default.md - - markdown: 'Default value: `{}`.' -- property: ignore_failure - ruby_type: true, false - required: false - default_value: 'false' - description_list: - - markdown: Continue running a recipe if a resource fails for any reason. -- property: name - ruby_type: null - required: false - description_list: - - markdown: The unique identifier of the node. -- property: normal_attributes - ruby_type: null - required: false - description_list: - - shortcode: node_attribute_type_normal.md - - markdown: 'Default value: `{}`.' -- property: notifies - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_notifies.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_notifies_syntax.md -- property: override_attributes - ruby_type: null - required: false - description_list: - - shortcode: node_attribute_type_override.md - - markdown: 'Default value: `{}`.' -- property: raw_json - ruby_type: null - required: false - description_list: - - markdown: "The node as JSON data. For example:\n\n```javascript\n{\n \"overrides\"\ - : {},\n \"name\": \"latte\",\n \"chef_type\": \"node\",\n \"json_class\"\ - : \"Chef::Node\",\n \"attributes\": {\n \"hardware_type\": \"laptop\"\n\ - \ },\n \"run_list\": [\n \"recipe[apache2]\"\n ],\n \"defaults\": {}\n\ - }\n```" -- property: run_list - ruby_type: null - required: false - description_list: - - markdown: 'A comma-separated list of roles and/or recipes to be applied. - - Default value: `[]`. For example: - - `["recipe[default]","recipe[apache2]"]`' -- property: subscribes - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_subscribes.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_subscribes_syntax.md - diff --git a/data/infra/resources/chef_organization.yaml b/data/infra/resources/chef_organization.yaml deleted file mode 100644 index 56e868b4..00000000 --- a/data/infra/resources/chef_organization.yaml +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: chef_organization resource -resource: chef_organization -aliases: -- /resource_chef_organization.html -menu: - infra: - title: chef_organization - identifier: chef_infra/resources/chef_organization chef_organization - parent: chef_infra/resources - -resource_reference: true -resource_description_list: -- markdown: 'Use the **chef_organization** resource to interact with organization - - objects that exist on the Chef Infra Server.' -syntax_description: "The syntax for using the **chef_organization** resource in a\ - \ recipe is\nas follows:\n\n```ruby\nchef_organization 'name' do\n attribute 'value'\ - \ # see attributes section below\n ...\n action :action # see actions section\ - \ below\nend\n```" -syntax_properties_list: -- '`chef_organization` tells Chef Infra Client to use the `Chef::Provider::ChefOrganization` - provider during a Chef Infra Client run' -- '`name` is the name of the resource block' -- '`attribute` is zero (or more) of the attributes that are available for this resource' -- '`action` identifies which steps Chef Infra Client will take to bring the node into - the desired state' -actions_list: - :create: - markdown: (default) - :delete: - markdown: '' - :nothing: - shortcode: resources_common_actions_nothing.md -properties_list: -- property: chef_server - ruby_type: null - required: false - description_list: - - markdown: The URL for the Chef Infra Server. -- property: complete - ruby_type: null - required: false - description_list: - - markdown: 'Use to specify if this resource defines an organization completely. - - When `true`, any property not specified by this resource will be - - reset to default property values.' -- property: full_name - ruby_type: null - required: false - description_list: - - markdown: 'The full name must begin with a non-white space character and must - - be between 1 and 1023 characters. For example: - - `Chef Software, Inc.`.' -- property: ignore_failure - ruby_type: true, false - required: false - default_value: 'false' - description_list: - - markdown: Continue running a recipe if a resource fails for any reason. -- property: invites - ruby_type: null - required: false - description_list: - - markdown: 'Use to specify a list of users to be invited to the organization. An - - invitation is sent to any user in this list who is not already a - - member of the organization.' -- property: members - ruby_type: null - required: false - description_list: - - markdown: 'Use to specify a list of users who MUST be members of the - - organization. These users will be added directly to the - - organization. The user who initiates this operation MUST also have - - permission to add users to the specified organization.' -- property: members_specified - ruby_type: null - required: false - description_list: - - markdown: 'Use to discover if a user is a member of an organization. Will - - return `true` if the user is a member.' -- property: name - ruby_type: null - required: false - description_list: - - markdown: 'The name must begin with a lower-case letter or digit, may only - - contain lower-case letters, digits, hyphens, and underscores, and - - must be between 1 and 255 characters. For example: `chef`.' -- property: notifies - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_notifies.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_notifies_syntax.md -- property: raw_json - ruby_type: null - required: false - description_list: - - markdown: "The organization as JSON data. For example:\n\n```none\n{\n \"name\"\ - : \"chef\",\n \"full_name\": \"Chef Software, Inc\",\n \"guid\": \"f980d1asdfda0331235s00ff36862\n\ - \ ...\n}\n```" -- property: remove_members - ruby_type: null - required: false - description_list: - - markdown: 'Use to remove the specified users from an organization. Invitations - - that have not been accepted will be cancelled.' -- property: subscribes - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_subscribes.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_subscribes_syntax.md - diff --git a/data/infra/resources/chef_role.yaml b/data/infra/resources/chef_role.yaml deleted file mode 100644 index e169cd8f..00000000 --- a/data/infra/resources/chef_role.yaml +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: chef_role resource -resource: chef_role -aliases: -- /resource_chef_role.html -menu: - infra: - title: chef_role - identifier: chef_infra/resources/chef_role chef_role - parent: chef_infra/resources -resource_reference: true -resource_description_list: -- shortcode: role.md -- markdown: Use the **chef_role** resource to manage roles. -syntax_description: "The syntax for using the **chef_role** resource in a recipe is\ - \ as\nfollows:\n\n```ruby\nchef_role 'name' do\n attribute 'value' # see properties\ - \ section below\n ...\n action :action # see actions section below\nend\n```" -syntax_properties_list: -- '`chef_role` tells Chef Infra Client to use the `Chef::Provider::ChefRole` provider - during a Chef Infra Client run' -- '`name` is the name of the resource block; when the `name` property is not specified - as part of a recipe, `name` is also the name of the role' -- '`attribute` is zero (or more) of the properties that are available for this resource' -- '`action` identifies which steps Chef Infra Client will take to bring the node into - the desired state' -actions_list: - :create: - markdown: (default) Use to create a role. - :delete: - markdown: Use to delete a role. - :nothing: - shortcode: resources_common_actions_nothing.md -properties_list: -- property: chef_server - ruby_type: null - required: false - description_list: - - markdown: The URL for the Chef Infra Server. -- property: complete - ruby_type: null - required: false - description_list: - - markdown: 'Use to specify if this resource defines a role completely. When - - `true`, any property not specified by this resource will be reset to - - default property values.' -- property: default_attributes - ruby_type: null - required: false - description_list: - - shortcode: node_attribute_type_default.md - - markdown: 'Default value: `{}`.' -- property: description - ruby_type: null - required: false - description_list: - - markdown: 'The description of the role. This value populates the description - - field for the role on the Chef Infra Server.' -- property: env_run_lists - ruby_type: null - required: false - description_list: - - markdown: 'The environment-specific run-list for a role. Default value: `[]`. - - For example: `["env_run_lists[webserver]"]`' -- property: ignore_failure - ruby_type: true, false - required: false - default_value: 'false' - description_list: - - markdown: Continue running a recipe if a resource fails for any reason. -- property: name - ruby_type: null - required: false - description_list: - - markdown: The name of the role. -- property: notifies - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_notifies.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_notifies_syntax.md -- property: override_attributes - ruby_type: null - required: false - description_list: - - shortcode: node_attribute_type_override.md - - markdown: 'Default value: `{}`.' -- property: raw_json - ruby_type: null - required: false - description_list: - - markdown: "The role as JSON data. For example:\n\n```javascript\n{\n \"name\"\ - : \"webserver\",\n \"chef_type\": \"role\",\n \"json_class\": \"Chef::Role\"\ - ,\n \"default_attributes\": {},\n \"description\": \"A webserver\",\n \"\ - run_list\": [\n \"recipe[apache2]\"\n ],\n \"override_attributes\": {}\n\ - }\n```" -- property: run_list - ruby_type: null - required: false - description_list: - - markdown: 'A comma-separated list of roles and/or recipes to be applied. - - Default value: `[]`. For example: - - `["recipe[default]","recipe[apache2]"]`' -- property: subscribes - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_subscribes.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_subscribes_syntax.md - diff --git a/data/infra/resources/chef_sleep.yaml b/data/infra/resources/chef_sleep.yaml index a1e49994..cf62c232 100644 --- a/data/infra/resources/chef_sleep.yaml +++ b/data/infra/resources/chef_sleep.yaml @@ -33,6 +33,8 @@ properties_list: default_value: The resource block's name description_list: - markdown: The number of seconds to sleep. +target_mode: + support: full examples: | **Sleep for 10 seconds**: @@ -61,4 +63,4 @@ examples: | seconds 30 action :nothing end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/chef_user.yaml b/data/infra/resources/chef_user.yaml deleted file mode 100644 index 725709e8..00000000 --- a/data/infra/resources/chef_user.yaml +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: chef_user resource -resource: chef_user -aliases: -- /resource_chef_user.html -menu: - infra: - title: chef_user - identifier: chef_infra/resources/chef_user chef_user - parent: chef_infra/resources - -resource_reference: true -resource_description_list: -- markdown: Use the **chef_user** resource to manage users. -syntax_description: "The syntax for using the **chef_user** resource in a recipe is\ - \ as\nfollows:\n\n```ruby\nchef_user 'value' # see properties section below\n \ - \ ...\n action :action # see actions section below\nend\n```" -syntax_properties_list: -- '`chef_user` tells Chef Infra Client to use the `Chef::Provider::ChefUser` provider - during a Chef Infra Client run' -- '`name` is the name of the resource block; when the `name` property is not specified - as part of a recipe, `name` is also the name of the user' -- '`attribute` is zero (or more) of the properties that are available for this resource' -- '`action` identifies which steps Chef Infra Client will take to bring the node into - the desired state' -actions_list: - :create: - markdown: (default) Use to create a user. - :delete: - markdown: Use to delete a user. - :nothing: - shortcode: resources_common_actions_nothing.md -properties_list: -- property: admin - ruby_type: null - required: false - description_list: - - markdown: 'Create a client as an admin client. This is required for any user to - - access Chef as an administrator.' -- property: chef_server - ruby_type: null - required: false - description_list: - - markdown: The URL for the Chef Infra Server. -- property: complete - ruby_type: null - required: false - description_list: - - markdown: 'Use to specify if this resource defines a user completely. When - - `true`, any property not specified by this resource will be reset to - - default property values.' -- property: email - ruby_type: null - required: false - description_list: - - markdown: The email address for the user. -- property: external_authentication_uid - ruby_type: null - required: false - description_list: - - markdown: '...' -- property: ignore_failure - ruby_type: true, false - required: false - default_value: 'false' - description_list: - - markdown: Continue running a recipe if a resource fails for any reason. -- property: name - ruby_type: null - required: false - description_list: - - markdown: The name of the user. -- property: notifies - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_notifies.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_notifies_syntax.md -- property: output_key_format - ruby_type: null - required: false - description_list: - - markdown: 'Use to specify the format of a public key. Possible values: `pem`, - - `der`, or `openssh`. Default value: `openssh`.' -- property: output_key_path - ruby_type: null - required: false - description_list: - - markdown: 'Use to specify the path to the location in which a public key will - - be written.' -- property: raw_json - ruby_type: null - required: false - description_list: - - markdown: "The user as JSON data. For example:\n\n```javascript\n{\n \"name\"\ - : \"Robert Forster\"\n}\n```" -- property: recovery_authentication_enabled - ruby_type: null - required: false - description_list: - - markdown: '...' -- property: source_key - ruby_type: null - required: false - description_list: - - markdown: 'Use to copy a public or private key, but apply a different `format` - - and `password`. Use in conjunction with `source_key_pass_phrase` and - - `source_key_path`.' -- property: source_key_pass_phrase - ruby_type: null - required: false - description_list: - - markdown: 'The pass phrase for the public key. Use in conjunction with - - `source_key` and `source_key_path`.' -- property: source_key_path - ruby_type: null - required: false - description_list: - - markdown: 'The path to the public key. Use in conjunction with `source_key` and - - `source_key_pass_phrase`.' -- property: subscribes - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_subscribes.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_subscribes_syntax.md -resources_common_properties: false -resources_common_notification: false -resources_common_guards: false - diff --git a/data/infra/resources/chef_vault_secret.yaml b/data/infra/resources/chef_vault_secret.yaml index b41de92b..f4463c0c 100644 --- a/data/infra/resources/chef_vault_secret.yaml +++ b/data/infra/resources/chef_vault_secret.yaml @@ -81,6 +81,7 @@ properties_list: description_list: - markdown: Search query that would match the same used for the clients, gets stored as a field in the item. +target_mode: examples: | **To create a 'foo' item in an existing 'bar' data bag**: diff --git a/data/infra/resources/chocolatey_config.yaml b/data/infra/resources/chocolatey_config.yaml index 07f5895c..080a58b9 100644 --- a/data/infra/resources/chocolatey_config.yaml +++ b/data/infra/resources/chocolatey_config.yaml @@ -46,6 +46,7 @@ properties_list: required: false description_list: - markdown: The value to set. +target_mode: examples: | **Set the Chocolatey cacheLocation config**: diff --git a/data/infra/resources/chocolatey_feature.yaml b/data/infra/resources/chocolatey_feature.yaml index fa766f94..6e358c53 100644 --- a/data/infra/resources/chocolatey_feature.yaml +++ b/data/infra/resources/chocolatey_feature.yaml @@ -39,6 +39,7 @@ properties_list: default_value: The resource block's name description_list: - markdown: The name of the Chocolatey feature to enable or disable. +target_mode: examples: | **Enable the checksumFiles Chocolatey feature** @@ -54,4 +55,4 @@ examples: | chocolatey_feature 'checksumFiles' do action :disable end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/chocolatey_installer.yaml b/data/infra/resources/chocolatey_installer.yaml index 1ec897c9..97b7f06f 100644 --- a/data/infra/resources/chocolatey_installer.yaml +++ b/data/infra/resources/chocolatey_installer.yaml @@ -5,9 +5,11 @@ resources_common_notification: true resources_common_properties: true resource: chocolatey_installer resource_description_list: -- markdown: Use the chocolatey_installer resource to install the Chocolatey package manager. Use the chocolatey_feature resource to customize - your install and the chocolatey_package resource to install packages. -resource_new_in: '18.4' +- markdown: Use the chocolatey_installer resource to ensure that Chocolatey itself + is installed to your specification. Use the Chocolatey Feature resource to customize + your install. Then use the Chocolatey Package resource to install packages on + Windows via Chocolatey. +resource_new_in: '18.3' syntax_full_code_block: |- chocolatey_installer 'name' do chocolatey_version String @@ -31,41 +33,43 @@ actions_list: :nothing: shortcode: resources_common_actions_nothing.md :install: - markdown: Installs Chocolatey package manager (default). + markdown: Installs Chocolatey package manager (default) :uninstall: - markdown: Uninstall Chocolatey package manager. + markdown: Uninstall Chocolatey package manager :upgrade: - markdown: Upgrades the Chocolatey package manager. + markdown: Upgrades the Chocolatey package manager properties_list: - property: chocolatey_version ruby_type: String required: false description_list: - markdown: Specifies a target version of Chocolatey to install. By default, the - latest stable version is installed. This will use the value in `$env:ChocolateyVersion` - by default if that environment variable is present. This parameter is ignored - if you set `download_url`. + latest stable version is installed. This will use the value in $env:ChocolateyVersion + by default, if that environment variable is present. This parameter is ignored + if download_url is set. - property: download_url ruby_type: String required: false description_list: - - markdown: The URL to download Chocolatey from. This sets the value of `$env:ChocolateyDownloadUrl` + - markdown: The URL to download Chocolatey from. This sets the value of $env:ChocolateyDownloadUrl and causes the installer to choose an alternate download location. If this is - not set, this resource downloads Chocolatey from the official Chocolatey community - repository. You can set a path to a `chocolatey.nupkg` file for offline installation. + not set, Chocolatey installs fall back to the official Chocolatey community + repository to download Chocolatey from. It can also be used for offline installation + by providing a path to a Chocolatey.nupkg. - property: ignore_proxy ruby_type: true, false required: false default_value: 'false' description_list: - - markdown: If set, this overrides any configured proxy, proxy environment - variables, or parameters. This is enabled if set + - markdown: If set, ignores any configured proxy. This will override any proxy environment + variables or parameters. This will be set by default if ignore_proxy is set to a value other than 'false' or '0'. - property: proxy_password ruby_type: String required: false description_list: - - markdown: The password used to connect to the proxy server with. If set, you must also set `proxy_user`. + - markdown: The password to use to build a proxy credential with. Will be consumed + by the proxy_credential property if both this property and proxy_user are set - property: proxy_url ruby_type: String required: false @@ -75,15 +79,19 @@ properties_list: ruby_type: String required: false description_list: - - markdown: The username used to connect to the proxy server with. If set, you must also set `proxy_password`. + - markdown: The username to use to build a proxy credential with. Will be consumed + by the proxy_credential property if both this property and proxy_password are + set - property: use_native_unzip ruby_type: true, false required: false default_value: 'false' description_list: - - markdown: If `true`, this resource uses built-in Windows decompression tools instead of 7zip when - unpacking the downloaded NuPkg file. This parameter is ignored in PowerShell 5+ in favour of using - the `Expand-Archive` built-in PowerShell cmdlet directly. + - markdown: If set, uses built-in Windows decompression tools instead of 7zip when + unpacking the downloaded nupkg. This will be set by default if use_native_unzip + is set to a value other than 'false' or '0'. This parameter will be ignored + in PS 5+ in favour of using the Expand-Archive built in PowerShell cmdlet directly. +target_mode: examples: "**Install Chocolatey**\n\n```ruby\nchocolatey_installer 'latest' do\n action :install\nend\n```\n\n**Uninstall Chocolatey**\n\n```ruby\nchocolatey_installer 'Some random verbiage' do\n action :uninstall\nend\n```\n\n**Install Chocolatey diff --git a/data/infra/resources/chocolatey_package.yaml b/data/infra/resources/chocolatey_package.yaml index b3fe2c8c..fed8ae61 100644 --- a/data/infra/resources/chocolatey_package.yaml +++ b/data/infra/resources/chocolatey_package.yaml @@ -19,6 +19,7 @@ resource_new_in: '12.7' syntax_full_code_block: |- chocolatey_package 'name' do bulk_query true, false # default value: false + environment Hash list_options String options String, Array package_name String, Array @@ -37,9 +38,9 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`bulk_query`, `list_options`, `options`, `package_name`, `password`, `returns`, - `source`, `timeout`, `use_choco_list`, `user`, and `version` are the properties - available to this resource." +- "`bulk_query`, `environment`, `list_options`, `options`, `package_name`, `password`, + `returns`, `source`, `timeout`, `use_choco_list`, `user`, and `version` are the + properties available to this resource." actions_list: :nothing: shortcode: resources_common_actions_nothing.md @@ -53,14 +54,27 @@ actions_list: :purge: markdown: Purge a package. This action typically removes the configuration files as well as the package. + :reconfig: + markdown: + :lock: + markdown: + :unlock: + markdown: properties_list: - property: bulk_query ruby_type: true, false required: false default_value: 'false' description_list: - - markdown: Whether to bulk query the Chocolatey server. This makes the provider list + - markdown: Bulk query the chocolatey server? This will cause the provider to list all packages instead of doing individual queries. +- property: environment + ruby_type: Hash + required: false + new_in: '19.0' + description_list: + - markdown: A Hash of environment variables in the form of {'ENV_VARIABLE' => 'VALUE'} + to be set before running the command. - property: list_options ruby_type: String required: false @@ -107,8 +121,9 @@ properties_list: required: false default_value: 'false' description_list: - - markdown: Whether to use `choco list` for getting locally installed packages instead of querying for NuGet package files. - This defaults to `false` since reading the package data is faster. + - markdown: Use choco list for getting the locally installed packages, rather than + reading the nupkg database directly? This defaults to false, since reading + the package data is faster. - property: user ruby_type: String required: false @@ -120,6 +135,7 @@ properties_list: required: false description_list: - markdown: The version of a package to be installed or upgraded. +target_mode: examples: | **Install a Chocolatey package**: diff --git a/data/infra/resources/chocolatey_source.yaml b/data/infra/resources/chocolatey_source.yaml index 68f130b7..24b33656 100644 --- a/data/infra/resources/chocolatey_source.yaml +++ b/data/infra/resources/chocolatey_source.yaml @@ -111,6 +111,7 @@ properties_list: new_in: '17.7' description_list: - markdown: The username to use when authenticating against the source +target_mode: examples: | **Add a Chocolatey source** @@ -127,4 +128,4 @@ examples: | chocolatey_source 'MySource' do action :remove end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/cookbook_file.yaml b/data/infra/resources/cookbook_file.yaml index 1a7b43ab..4d2f898e 100644 --- a/data/infra/resources/cookbook_file.yaml +++ b/data/infra/resources/cookbook_file.yaml @@ -10,43 +10,27 @@ resource: cookbook_file resource_description_list: - shortcode: resource_cookbook_file_summary.md - markdown: |- - During a Chef Infra Client run, the checksum for each local file is calculated and then compared against the checksum for the same file as it currently exists in the cookbook on the Chef Infra Server. A file isn't transferred when the checksums match. Only files that require an update are transferred from the Chef Infra Server to a node. -syntax_description: "A **cookbook_file** resource block manages files by using files\ - \ that\nexist within a cookbook's `/files` directory. For example, to write the\n\ - home page for an Apache website:\n\n```ruby\ncookbook_file '/var/www/customers/public_html/index.php'\ - \ do\n source 'index.php'\n owner 'web_admin'\n group 'web_admin'\n mode '0755'\n\ - \ action :create\nend\n```" -syntax_full_code_block: |- - cookbook_file 'name' do - atomic_update true, false - backup Integer, false # default value: 5 - cookbook String - force_unlink true, false # default value: false - group String, Integer - inherits true, false - manage_symlink_source true, false - mode String, Integer - owner String, Integer - path String # default value: 'name' unless specified - rights Hash - source String, Array - verify String, Block - action Symbol # defaults to :create if not specified - end + Use the **cookbook_file** resource to transfer files from a sub-directory of COOKBOOK_NAME/files/ to a specified path located on a host that is running the Chef Infra Client. The file is selected according to file specificity, which allows different source files to be used based on the hostname, host platform (operating system, distro, or as appropriate), or platform version. Files that are located in the COOKBOOK_NAME/files/default sub-directory may be used on any platform. + + During a Chef Infra Client run, the checksum for each local file is calculated and then compared against the checksum for the same file as it currently exists in the cookbook on the Chef Infra Server. A file is not transferred when the checksums match. Only files that require an update are transferred from the Chef Infra Server to a node. +syntax_full_code_block: "cookbook_file 'name' do\n atomic_update true, + false\n backup Integer, false # default value: 5\n checksum + \ String\n content String\n cookbook String + # default value: \"The current cookbook name\"\n force_unlink true, + false # default value: false\n group \n manage_symlink_source + \ true, false\n mode \n owner \n + \ path String # default value: 'name' unless specified\n source + \ String, Array\n action Symbol # defaults + to :create if not specified\nend" syntax_properties_list: -- '`''/var/www/customers/public_html/index.php''` is path to the file to be created' -- '`''index.php''` is a file in the `/files` directory in a cookbook that is used - to create that file (the contents of the file in the cookbook will become the contents - of the file on the node)' -- '`owner`, `group`, and `mode` define the permissions' syntax_full_properties_list: - "`cookbook_file` is the resource." - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`atomic_update`, `backup`, `checksum`, `content`, `cookbook`, `deny_rights`, `force_unlink`, - `manage_symlink_source`, `path`, `rights`, and `source` are the properties available - to this resource." +- "`atomic_update`, `backup`, `checksum`, `content`, `cookbook`, `force_unlink`, `group`, + `manage_symlink_source`, `mode`, `owner`, `path`, and `source` are the properties + available to this resource." actions_list: :nothing: shortcode: resources_common_actions_nothing.md @@ -80,6 +64,19 @@ properties_list: - markdown: The number of backups to be kept in `/var/chef/backup` (for UNIX- and Linux-based platforms) or `C:/chef/backup` (for the Microsoft Windows platform). Set to `false` to prevent backups from being kept. +- property: checksum + ruby_type: String + required: false + description_list: + - markdown: The SHA-256 checksum of the file. Use to ensure that a specific file + is used. If the checksum does not match, the file is not used. +- property: content + ruby_type: String + required: false + description_list: + - markdown: A string that is written to the file. The contents of this property + replace any previous content when this property has something other than the + default value. The default behavior will not modify content. - property: cookbook ruby_type: String required: false @@ -125,20 +122,14 @@ properties_list: Change the behavior of the file resource if it is pointed at a symlink. When this value is set to `true`, Chef Infra Client 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 Infra Client will follow the - + content. When this value is set to false, Chef Infra Client 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." + 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." - property: mode - ruby_type: Integer, String + ruby_type: '' required: false description_list: - markdown: 'If `mode` is not specified and if the file already exists, the @@ -239,10 +230,8 @@ properties_list: required: false default_value: The resource block's name. description_list: - - markdown: The name of the file in `COOKBOOK_NAME/files/default` or the path to a - - file located in `COOKBOOK_NAME/files`. The path must include the file name and - + - markdown: The name of the file in COOKBOOK_NAME/files/default or the path to a + file located in COOKBOOK_NAME/files. The path must include the file name and its extension. This can be used to distribute specific files depending upon files depending upon the platform used - see [File @@ -272,6 +261,8 @@ remote_file_prevent_re_downloads: false ps_credential_helper: false ruby_style_basics_chef_log: false debug_recipes_chef_shell: false +target_mode: + support: full examples: " Transfer a file\n\n ```ruby\n cookbook_file 'file.txt' do\n \ \ mode '0755'\n end\n ```\n\n Handle cookbook_file and package resources in\ diff --git a/data/infra/resources/cron.yaml b/data/infra/resources/cron.yaml index 0f05f16d..2fdbe987 100644 --- a/data/infra/resources/cron.yaml +++ b/data/infra/resources/cron.yaml @@ -142,6 +142,8 @@ properties_list: description_list: - markdown: The day of the week on which this entry is to run (`0-7`, `mon-sun`, `monday-sunday`, or `*`), where Sunday is both `0` and `7`. +target_mode: + support: full examples: | **Run a program at a specified interval** diff --git a/data/infra/resources/cron_access.yaml b/data/infra/resources/cron_access.yaml index 0bdf111a..b6684a1a 100644 --- a/data/infra/resources/cron_access.yaml +++ b/data/infra/resources/cron_access.yaml @@ -39,6 +39,8 @@ properties_list: description_list: - markdown: An optional property to set the user name if it differs from the resource block's name. +target_mode: + support: full examples: | **Add the mike user to cron.allow** diff --git a/data/infra/resources/cron_d.yaml b/data/infra/resources/cron_d.yaml index dcd47c42..a4f76507 100644 --- a/data/infra/resources/cron_d.yaml +++ b/data/infra/resources/cron_d.yaml @@ -190,6 +190,8 @@ properties_list: description_list: - markdown: The day of the week on which this entry is to run (`0-7`, `mon-sun`, `monday-sunday`, or `*`), where Sunday is both `0` and `7`. +target_mode: + support: full examples: | **Run a program on the fifth hour of the day** diff --git a/data/infra/resources/csh.yaml b/data/infra/resources/csh.yaml index 070e308e..3890be56 100644 --- a/data/infra/resources/csh.yaml +++ b/data/infra/resources/csh.yaml @@ -12,6 +12,7 @@ resource_description_list: in which they are run. Use `not_if` and `only_if` to guard this resource for idempotence. syntax_full_code_block: |- csh 'name' do + cgroup String code String command String, Array # default value: 'name' unless specified creates String @@ -38,20 +39,38 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`code`, `command`, `creates`, `cwd`, `default_env`, `domain`, `elevated`, `environment`, - `flags`, `group`, `input`, `interpreter`, `live_stream`, `login`, `password`, `returns`, - `timeout`, and `user` are the properties available to this resource." +- "`cgroup`, `code`, `command`, `creates`, `cwd`, `default_env`, `domain`, `elevated`, + `environment`, `flags`, `group`, `input`, `interpreter`, `live_stream`, `login`, + `password`, `returns`, `timeout`, and `user` are the properties available to this + resource." actions_list: :nothing: shortcode: resources_common_actions_nothing.md :run: markdown: Run a command. (default) properties_list: +- property: cgroup + ruby_type: String + required: false + new_in: '19.0' + description_list: + - markdown: 'Linux only: Run the command within a specific cgroup, creating it if + it doesn''t exist.' - property: code ruby_type: String required: true description_list: - markdown: A quoted string of code to be executed. +- property: command + ruby_type: String, Array + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the command to be executed if it differs + from the resource block's name. + - note: + markdown: Use the **execute** resource to run a single command. Use multiple + **execute** resource blocks to run multiple commands. - property: creates ruby_type: String required: false @@ -62,6 +81,36 @@ properties_list: required: false description_list: - markdown: The current working directory from which the command will be run. +- property: default_env + ruby_type: true, false + required: false + default_value: 'false' + new_in: '14.2' + description_list: + - markdown: When true this enables ENV magic to add path_sanity to the PATH and + force the locale to English+UTF-8 for parsing output +- property: domain + ruby_type: String + required: false + new_in: '12.21' + description_list: + - markdown: 'Windows only: The domain of the user specified by the user property. + If not specified, the username and password specified by the `user` and `password` + properties will be used to resolve that user against the domain in which the + system running Chef Infra Client is joined, or if that system is not joined + to a domain it will resolve the user as a local account on that system. An alternative + way to specify the domain is to leave this property unspecified and specify + the domain as part of the user property.' +- property: elevated + ruby_type: true, false + required: false + default_value: 'false' + new_in: '13.3' + description_list: + - markdown: |- + Determines whether the script will run with elevated permissions to circumvent User Access Control (UAC) from interactively blocking the process. + This will cause the process to be run under a batch login instead of an interactive login. The user running chef-client needs the 'Replace a process level token' and 'Adjust Memory Quotas for a process' permissions. The user that is running the command needs the 'Log on as a batch job' permission. + Because this requires a login, the user and password properties are required. - property: environment ruby_type: Hash required: false @@ -80,6 +129,41 @@ properties_list: required: false description_list: - markdown: The group name or group ID that must be changed before running a command. +- property: input + ruby_type: String + required: false + new_in: '16.2' + description_list: + - markdown: An optional property to set the input sent to the command as STDIN. +- property: interpreter + ruby_type: String + required: false + description_list: + - markdown: +- property: live_stream + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Send the output of the command run by this execute resource block to + the Chef Infra Client event stream. +- property: login + ruby_type: true, false + required: false + default_value: 'false' + new_in: '17.0' + description_list: + - markdown: Use a login shell to run the commands instead of inheriting the existing + execution environment. +- property: password + ruby_type: String + required: false + new_in: '12.21' + description_list: + - markdown: 'Windows only: The password of the user specified by the user property. + This property is mandatory if user is specified on Windows and may only be specified + if user is specified. The sensitive property for this resource will automatically + be set to true if password is specified.' - property: returns ruby_type: Integer, Array required: false @@ -97,10 +181,12 @@ properties_list: ruby_type: String, Integer required: false description_list: - - markdown: The user name or user ID that should be changed before running a command. -- property: umask - ruby_type: String, Integer - required: false - description_list: - - markdown: The file mode creation mask, or umask. + - markdown: The user name of the user identity with which to launch the new process. + The user name may optionally be specified with a domain, i.e. `domain\user` + or `user@my.dns.domain.com` via Universal Principal Name (UPN)format. It can + also be specified without a domain simply as user if the domain is instead specified + using the domain property. On Windows only, if this property is specified, the + password property must be specified. +target_mode: + support: full examples: diff --git a/data/infra/resources/directory.yaml b/data/infra/resources/directory.yaml index 7ecf3590..6f92086b 100644 --- a/data/infra/resources/directory.yaml +++ b/data/infra/resources/directory.yaml @@ -154,13 +154,8 @@ properties_list: required: false default_value: The resource block's name description_list: - - markdown: 'The path to the directory. Using a fully qualified path is - - recommended, but is not always required. Default value: the `name` - - of the resource block. See "Syntax" section above for more - - information.' + - markdown: The path to the directory. Using a fully qualified path is recommended, + but is not always required. - property: recursive ruby_type: true, false required: false diff --git a/data/infra/resources/dmg_package.yaml b/data/infra/resources/dmg_package.yaml index 63b35fcb..9340c803 100644 --- a/data/infra/resources/dmg_package.yaml +++ b/data/infra/resources/dmg_package.yaml @@ -39,6 +39,8 @@ syntax_full_properties_list: `dmg_passphrase`, `file`, `headers`, `owner`, `package_id`, `source`, `type`, and `volumes_dir` are the properties available to this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md :install: markdown: Installs the application. (default) properties_list: @@ -127,6 +129,7 @@ properties_list: description_list: - markdown: The directory under `/Volumes` where the `dmg` is mounted if it differs from the name of the `.dmg` file. +target_mode: examples: | **Install Google Chrome via the DMG package**: @@ -156,4 +159,4 @@ examples: | checksum '9435f79d5b52d0febeddfad392adf82db9df159196f496c1ab139a6957242ce9' accept_eula true end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/dnf_package.yaml b/data/infra/resources/dnf_package.yaml index 7ad99066..2cc66a90 100644 --- a/data/infra/resources/dnf_package.yaml +++ b/data/infra/resources/dnf_package.yaml @@ -42,8 +42,8 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`allow_downgrade`, `arch`, `environment`, `flush_cache`, `options`, `package_name`, `source`, - `timeout`, and `version` are the properties available to this resource." +- "`allow_downgrade`, `arch`, `environment`, `flush_cache`, `options`, `package_name`, + `source`, `timeout`, and `version` are the properties available to this resource." actions_list: :nothing: shortcode: resources_common_actions_nothing.md @@ -63,6 +63,8 @@ actions_list: markdown: Locks the DNF package to a specific version. :unlock: markdown: Unlocks the DNF package so that it can be upgraded to a newer version. + :flush_cache: + markdown: properties_list: - property: allow_downgrade ruby_type: true, false @@ -139,6 +141,7 @@ properties_list: - markdown: 'The version of a package to be installed or upgraded. This property is ignored when using the `:upgrade` action.' +target_mode: examples: " Install an exact version\n\n ```ruby\n dnf_package 'netpbm = 10.35.58-8.el5'\n\ \ ```\n\n Install a minimum version\n\n ```ruby\n dnf_package 'netpbm >= 10.35.58-8.el5'\n\ diff --git a/data/infra/resources/dpkg_package.yaml b/data/infra/resources/dpkg_package.yaml index 8390c5d0..19aa1f55 100644 --- a/data/infra/resources/dpkg_package.yaml +++ b/data/infra/resources/dpkg_package.yaml @@ -45,12 +45,26 @@ actions_list: :install: markdown: Install a package. If a version is specified, install the specified version of the package. (default) + :upgrade: + markdown: Install a package and ensure that a package is the latest version. :remove: markdown: Remove a package. :purge: markdown: Purge a package. This action typically removes the configuration files as well as the package. + :reconfig: + markdown: + :lock: + markdown: + :unlock: + markdown: properties_list: +- property: allow_downgrade + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Allow downgrading a package to satisfy requested version requirements. - property: environment ruby_type: Hash required: false @@ -96,6 +110,10 @@ properties_list: required: false description_list: - markdown: The version of a package to be installed or upgraded. +target_mode: + support: full + introduced: '19.0' + description: Does not support the `response_file` property in Target Mode. examples: " Install a package\n\n ```ruby\n dpkg_package 'wget_1.13.4-2ubuntu1.4_amd64.deb'\ \ do\n source '/foo/bar/wget_1.13.4-2ubuntu1.4_amd64.deb'\n action :install\n\ diff --git a/data/infra/resources/dsc_resource.yaml b/data/infra/resources/dsc_resource.yaml index 4b4488c2..8a5a8028 100644 --- a/data/infra/resources/dsc_resource.yaml +++ b/data/infra/resources/dsc_resource.yaml @@ -275,10 +275,12 @@ properties_list: - property: timeout ruby_type: Integer required: false + new_in: '12.6' description_list: - markdown: 'The amount of time (in seconds) a command is to wait before timing out.' +target_mode: examples: " Open a Zip file\n\n ```ruby\n dsc_resource 'example' do\n \ \ resource :archive\n property :ensure, 'Present'\n property :path, 'C:\\\ diff --git a/data/infra/resources/dsc_script.yaml b/data/infra/resources/dsc_script.yaml index 2a3a107d..a3b0db11 100644 --- a/data/infra/resources/dsc_script.yaml +++ b/data/infra/resources/dsc_script.yaml @@ -215,6 +215,7 @@ remote_file_prevent_re_downloads: false remote_file_unc_path: false ruby_style_basics_chef_log: false debug_recipes_chef_shell: false +target_mode: examples: " Specify DSC code directly\n\n DSC data can be specified directly\ \ in a recipe:\n\n ```ruby\n dsc_script 'emacs' do\n code <<-EOH\n Environment\ diff --git a/data/infra/resources/execute.yaml b/data/infra/resources/execute.yaml index 3e330fec..350297c8 100644 --- a/data/infra/resources/execute.yaml +++ b/data/infra/resources/execute.yaml @@ -58,6 +58,7 @@ syntax_properties_list: that file already exists' syntax_full_code_block: |- execute 'name' do + cgroup String command String, Array # default value: 'name' unless specified creates String cwd String @@ -80,7 +81,7 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`command`, `creates`, `cwd`, `default_env`, `domain`, `elevated`, `environment`, +- "`cgroup`, `command`, `creates`, `cwd`, `default_env`, `domain`, `elevated`, `environment`, `group`, `input`, `live_stream`, `login`, `password`, `returns`, `timeout`, and `user` are the properties available to this resource." actions_list: @@ -89,6 +90,13 @@ actions_list: :run: markdown: Run a command. (default) properties_list: +- property: cgroup + ruby_type: String + required: false + new_in: '19.0' + description_list: + - markdown: 'Linux only: Run the command within a specific cgroup, creating it if + it doesn''t exist.' - property: command ruby_type: String, Array required: false @@ -115,8 +123,8 @@ properties_list: default_value: 'false' new_in: '14.2' description_list: - - markdown: When `true` this enables ENV magic to add path_sanity to the PATH and - force the locale to English+UTF-8 for parsing output. + - markdown: When true this enables ENV magic to add path_sanity to the PATH and + force the locale to English+UTF-8 for parsing output - property: domain ruby_type: String required: false @@ -204,6 +212,10 @@ properties_list: also be specified without a domain simply as user if the domain is instead specified using the domain property. On Windows only, if this property is specified, the password property must be specified. +target_mode: + support: full + introduced: '15.1' + updated: '19.0' examples: | **Run a command upon notification**: @@ -618,14 +630,14 @@ examples: | NetworkService have this right when running as a service. This is necessary even if the user is an Administrator. - This right can be added and checked in a recipe using this example: + This right can be added and checked in a recipe using this example (will not take effect in the same Chef run): ```ruby - # Add 'SeAssignPrimaryTokenPrivilege' for the user - Chef::ReservedNames::Win32::Security.add_account_right('', 'SeAssignPrimaryTokenPrivilege') - - # Check if the user has 'SeAssignPrimaryTokenPrivilege' rights - Chef::ReservedNames::Win32::Security.get_account_right('').include?('SeAssignPrimaryTokenPrivilege') + windows_user_privilege 'add assign token privilege' do + principal '' + privilege 'SeAssignPrimaryTokenPrivilege' + action :add + end ``` The following example shows how to run `mkdir test_dir` from a Chef Infra Client @@ -668,6 +680,8 @@ examples: | **Run a command with an external input file**: + ```ruby execute 'md5sum' do input File.read(__FILE__) end + ``` diff --git a/data/infra/resources/file.yaml b/data/infra/resources/file.yaml index f311abae..bfa4528e 100644 --- a/data/infra/resources/file.yaml +++ b/data/infra/resources/file.yaml @@ -50,14 +50,12 @@ syntax_properties_list: the filename to be managed - '`content` defines the contents of the file' syntax_full_properties_list: - - '`file` is the resource.' - - '`name` is the name given to the resource block.' - - >- - `action` identifies which steps Chef Infra Client will take to bring the - node into the desired state. - - '`atomic_update`, `backup`, `checksum`, `content`, `force_unlink`, `group`, `inherits`, - `manage_symlink_source`, `mode`, `owner`, `path`, `rights`, and `verify` - are properties of this resource, with the Ruby type shown.' +- "`file` is the resource." +- "`name` is the name given to the resource block." +- "`action` identifies which steps Chef Infra Client will take to bring the node into + the desired state." +- "`atomic_update`, `backup`, `checksum`, `content`, `force_unlink`, `group`, `manage_symlink_source`, + `mode`, `owner`, and `path` are the properties available to this resource." actions_list: ':create': markdown: >- @@ -76,283 +74,88 @@ actions_list: Touch a file. This updates the access (atime) and file modification (mtime) times for a file. properties_list: - - property: atomic_update - ruby_type: 'true, false' - required: false - default_value: >- - false if modifying /etc/hosts, /etc/hostname, or /etc/resolv.conf within - Docker containers. Otherwise default to the client.rb 'file_atomic_update' - config value. - description_list: - - markdown: | - Perform atomic file updates on a per-resource basis. - - Set to `true` for atomic file updates. Set to `false` for non-atomic file updates. - - This setting overrides `file_atomic_update`, which is a global setting - found in the `client.rb` file. - - property: backup - ruby_type: 'Integer, false' - required: false - default_value: '5' - description_list: - - markdown: | - The number of backups to be kept in `/var/chef/backup` (for UNIX- and - Linux-based platforms) or `C:/chef/backup` (for the Microsoft Windows - platform). - - Set to `false` to prevent backups from being kept. - - property: checksum - ruby_type: String - required: false - description_list: - - markdown: >- - The SHA-256 checksum of the file. Use to ensure that a specific file - is used. If the checksum does not match, the file is not used. - - property: content - ruby_type: String - required: false - description_list: - - markdown: >- - A string that is written to the file. The contents of this property - replace any previous content when this property has something other - than the default value. The default behavior will not modify content. - - property: force_unlink - ruby_type: 'true, false' - required: false - default_value: 'false' - description_list: - - markdown: >- - How Chef Infra Client 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 Infra Client to delete the - non-file target and replace it with the specified file. Set to `false` - for Chef Infra Client to raise an error. - - property: group - ruby_type: 'Integer, String' - required: false - description_list: - - markdown: |- - A string or ID that identifies the group owner by group name or SID, - including fully qualified group names such as `domain\group` or - `group@domain`. - - - If this value is not specified, existing groups - remain unchanged and new group assignments use the default `POSIX` - group (if available). - - property: inherits - ruby_type: 'true, false' - required: false - default_value: 'true' - description_list: - - markdown: |- - Microsoft Windows only. Whether a file inherits rights from its - parent directory. - - property: manage_symlink_source - ruby_type: 'true, false' - required: false - default_value: 'true' - description_list: - - markdown: >- - Change the behavior of the **file** resource if it is pointed at a - symlink. - - - When this value is set to `true`, Chef Infra Client 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 Infra Client 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. - - property: mode - ruby_type: 'Integer, String' - required: false - description_list: - - markdown: >- - A quoted 3-5 character string that defines the octal mode. For - example: `'755'`, `'0755'`, or `00755`. - - - If `mode` is not specified and - if the file already exists, the existing mode on the file is used. If - `mode` is not specified, the file does not exist, and the `:create` - action is specified, Chef Infra Client assumes a mask value of - `'0777'` and then applies the umask for the system on which the file - is to be created to the `mask` value. For example, if the umask on a - system is `'022'`, Chef Infra Client uses the default value of - `'0755'`. - - - The behavior is different depending on the platform. - - - UNIX- and Linux-based systems: A quoted 3-5 character string that defines - the octal mode that is passed to chmod. For example: `'755'`, - `'0755'`, or `00755`. If the value is specified as a quoted string, it - works exactly as if the `chmod` command was passed. If the value is - specified as an integer, prepend a zero (`0`) to the value to ensure - that it is interpreted as an octal number. For example, to assign - read, write, and execute rights for all users, use `'0777'` or - `'777'`; for the same rights, plus the sticky bit, use `01777` or - `'1777'`. - - - Microsoft Windows: A quoted 3-5 character string that - defines the octal mode that is translated into rights for Microsoft - Windows security. For example: `'755'`, `'0755'`, or `00755`. Values - up to `'0777'` are allowed (no sticky bits) and mean the same in - Microsoft Windows as they do in UNIX, where `4` equals `GENERIC_READ`, - `2` equals `GENERIC_WRITE`, and `1` equals `GENERIC_EXECUTE`. - - - This property cannot be used to set `:full_control`. This property has no - effect if not specified, but when it and `rights` are both specified, - the effects are cumulative. - - property: owner - ruby_type: 'Integer, String' - required: false - description_list: - - markdown: | - A string or ID that identifies the group owner by user name or SID, - including fully qualified user names such as `domain\user` or - `user@domain`. - - If this value is not specified, existing owners remain - unchanged and new owner assignments use the current user (when - necessary). - - property: path - ruby_type: String - required: false - default_value: The resource block's name - description_list: - - markdown: | - The full path to the file, including the file name and its extension. - For example: /files/file.txt. - - Default value: the name of the resource block. - - Microsoft Windows: A path that begins with a forward slash `/` - will point to the root of the current working directory of the Chef - Infra Client process. This path can vary from system to system. - Therefore, using a path that begins with a forward slash `/` is not - recommended. - - property: rights - ruby_type: 'Integer, String' - required: false - description_list: - - markdown: |- - Microsoft Windows only. The permissions for users and groups in a - Microsoft Windows environment. For example: - `rights , , ` where `` - specifies the rights granted to the principal, `` is the - group or user name, and `` is a Hash with one (or more) - advanced rights options. - - property: verify - ruby_type: 'String, Block, Symbol' - required: false - description_list: - - markdown: | - Allows verification of a file's contents before it is created. - Creates a temporary file and then allows execution of commands or - Ruby code. If this code evaluates to `true`, the file is created. If - the code evaluates to `false`, an error is raised. - - The types for this property are a block, string, or a symbol. When - specified - as a block, it returns `true` or `false`. When specified as a - string, it is executed as a system command. It returns `true` - if the command returns `0` as its exit status code and `false` if the - command returns a non-zero exit status code. When using a built-in - verifier - symbol it returns `true` if the verifier succeeds else it returns - `false`. - - Currently suppported verifiers are `:yaml`, `:json` and - `:systemd_unit`. - - note: - markdown: | - A block is arbitrary Ruby defined within the resource block by using - the `verify` property. When a block returns `true`, Chef Infra - Client will continue to update the file as appropriate.' - - markdown: | - For example, this should return `true`: - - ```ruby - file '/tmp/baz' do - verify { 1 == 1 } - end - ``` - - This should also return `true`: - - ```ruby - file '/etc/nginx.conf' do - verify 'nginx -t -c %{path}' - end - ``` - - In this example, the `%{path}` portion of this command is expanded - to the temporary location where a copy of the file to be created - exists. This will use Nginx's syntax checking feature to ensure the - file is a valid Nginx configuration file before writing the file. An - error will be raised if the executed command returns a non-zero exit - status code. - - - This should return `true`: - - ```ruby - file '/tmp/foo' do - content "hello" - verify do |path| - open(path).read.include? "hello" - end - end - ``` - - Whereas, this should return `false`: - - ```ruby - file '/tmp/foo' do - content "goodbye" - verify do |path| - open(path).read.include? "hello" - end - end - ``` - - When using one of the built-in symbols(`:json`, `:yaml`, `:systemd_unit`) - - This should return `true`: - - ```ruby - file 'foo.json' do - content '{"foo": "bar"}' - verify :json - end - ``` - - Whereas, this should return `false`: - - ```ruby - file 'foo.yaml' do - content "--- foo: 'foo-" - verify :yaml - end - ``` - - If a string, block or symbol returns `false`, the Chef Infra Client run - will stop and an error is raised. +- property: atomic_update + ruby_type: true, false + required: false + default_value: False if modifying /etc/hosts, /etc/hostname, or /etc/resolv.conf + within Docker containers. Otherwise default to the client.rb 'file_atomic_update' + config value. + description_list: + - markdown: Perform atomic file updates on a per-resource basis. Set to true for + atomic file updates. Set to false for non-atomic file updates. This setting + overrides `file_atomic_update`, which is a global setting found in the `client.rb` + file. +- property: backup + ruby_type: Integer, false + required: false + default_value: '5' + description_list: + - markdown: The number of backups to be kept in `/var/chef/backup` (for UNIX- and + Linux-based platforms) or `C:/chef/backup` (for the Microsoft Windows platform). + Set to `false` to prevent backups from being kept. +- property: checksum + ruby_type: String + required: false + description_list: + - markdown: The SHA-256 checksum of the file. Use to ensure that a specific file + is used. If the checksum does not match, the file is not used. +- property: content + ruby_type: String + required: false + description_list: + - markdown: A string that is written to the file. The contents of this property + replace any previous content when this property has something other than the + default value. The default behavior will not modify content. +- property: force_unlink + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: How Chef Infra Client 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 Infra Client to delete the non-file target and replace + it with the specified file. Set to `false` for Chef Infra Client to raise an + error. +- property: group + ruby_type: '' + required: false + description_list: + - markdown: +- property: manage_symlink_source + ruby_type: true, false + required: false + description_list: + - markdown: Change the behavior of the file resource if it is pointed at a symlink. + When this value is set to true, Chef Infra Client 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 Infra Client 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. +- property: mode + ruby_type: '' + required: false + description_list: + - markdown: +- property: owner + ruby_type: '' + required: false + description_list: + - markdown: +- property: path + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: 'The full path to the file, including the file name and its extension. + For example: /files/file.txt. Default value: the name of the resource block. + Microsoft Windows: A path that begins with a forward slash `/` will point to + the root of the current working directory of the Chef Infra Client process. + This path can vary from system to system. Therefore, using a path that begins + with a forward slash `/` is not recommended.' +target_mode: + support: full properties_multiple_packages: false resource_directory_recursive_directories: false remote_file_prevent_re_downloads: false diff --git a/data/infra/resources/freebsd_package.yaml b/data/infra/resources/freebsd_package.yaml index 79145fbc..26c994a8 100644 --- a/data/infra/resources/freebsd_package.yaml +++ b/data/infra/resources/freebsd_package.yaml @@ -22,6 +22,7 @@ syntax_description: | syntax_full_code_block: |- freebsd_package 'name' do + environment Hash options String, Array package_name String, Array source String @@ -31,19 +32,28 @@ syntax_full_code_block: |- end syntax_properties_list: syntax_full_properties_list: -- '`freebsd_package` is the resource.' -- '`name` is the name given to the resource block.' -- '`action` identifies which steps Chef Infra Client will take to bring the node into - the desired state.' -- '`options`, `package_name`, `source`, `timeout`, and `version` are the properties - available to this resource.' +- "`freebsd_package` is the resource." +- "`name` is the name given to the resource block." +- "`action` identifies which steps Chef Infra Client will take to bring the node into + the desired state." +- "`environment`, `options`, `package_name`, `source`, `timeout`, and `version` are + the properties available to this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md :install: markdown: (default) Install a package. If a version is specified, install the specified version of the package. :remove: markdown: Remove a package. properties_list: +- property: environment + ruby_type: Hash + required: false + new_in: '19.0' + description_list: + - markdown: A Hash of environment variables in the form of {'ENV_VARIABLE' => 'VALUE'} + to be set before running the command. - property: options ruby_type: String, Array required: false @@ -70,7 +80,9 @@ properties_list: required: false description_list: - markdown: The version of a package to be installed or upgraded. -examples: " +target_mode: + support: full + examples: " Install a package\n\n ```ruby\n freebsd_package 'name of package'\ \ do\n action :install\n end\n ```\n" diff --git a/data/infra/resources/gem_package.yaml b/data/infra/resources/gem_package.yaml index ef4ae379..058f20af 100644 --- a/data/infra/resources/gem_package.yaml +++ b/data/infra/resources/gem_package.yaml @@ -12,10 +12,16 @@ resource_description_list: markdown: The **gem_package** resource must be specified as `gem_package` and cannot be shortened to `package` in a recipe. - warning: - shortcode: resource_chef_gem_gem_package_install.md + markdown: |- + The **chef_gem** and **gem_package** resources are both used to install Ruby gems. For any machine on which Chef Infra Client is + installed, there are two instances of Ruby. One is the standard, system-wide instance of Ruby and the other is a dedicated instance that is + available only to Chef Infra Client. + Use the **chef_gem** resource to install gems into the instance of Ruby that is dedicated to Chef Infra Client. + Use the **gem_package** resource to install all other gems (i.e. install gems system-wide). syntax_full_code_block: |- gem_package 'name' do clear_sources true, false + environment Hash gem_binary String include_default_source true, false options String, Hash, Array @@ -31,19 +37,28 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`clear_sources`, `gem_binary`, `include_default_source`, `options`, `package_name`, - `source`, `timeout`, and `version` are the properties available to this resource." +- "`clear_sources`, `environment`, `gem_binary`, `include_default_source`, `options`, + `package_name`, `source`, `timeout`, and `version` are the properties available + to this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md :install: markdown: Install a package. If a version is specified, install the specified version of the package. (default) + :upgrade: + markdown: Install a package and ensure that a package is the latest version. + :remove: + markdown: Remove a package. :purge: markdown: Purge a package. This action typically removes the configuration files as well as the package. - :remove: - markdown: Remove a package. - :upgrade: - markdown: Install a package and/or ensure that a package is the latest version. + :reconfig: + markdown: + :lock: + markdown: + :unlock: + markdown: properties_list: - property: clear_sources ruby_type: true, false @@ -52,6 +67,13 @@ properties_list: description_list: - markdown: Set to `true` to download a gem from the path specified by the `source` property (and not from RubyGems). +- property: environment + ruby_type: Hash + required: false + new_in: '19.0' + description_list: + - markdown: A Hash of environment variables in the form of {'ENV_VARIABLE' => 'VALUE'} + to be set before running the command. - property: gem_binary ruby_type: String required: false @@ -98,6 +120,7 @@ properties_list: required: false description_list: - markdown: The version of a package to be installed or upgraded. +target_mode: examples: | The following examples demonstrate various approaches for using the **gem_package** resource in recipes: @@ -117,4 +140,4 @@ examples: | action :install ignore_failure true end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/git.yaml b/data/infra/resources/git.yaml index b9aa9373..f7b84f9f 100644 --- a/data/infra/resources/git.yaml +++ b/data/infra/resources/git.yaml @@ -185,19 +185,15 @@ properties_list: ruby_type: Integer required: false description_list: - - markdown: 'The amount of time (in seconds) to wait for a command to execute - - before timing out. When this property is specified using the - - **deploy** resource, the value of the `timeout` property is passed - - from the **deploy** resource to the **git** resource.' + - markdown: The amount of time (in seconds) to wait before timing out. - property: user ruby_type: String, Integer required: false default_value: "`HOME` environment variable of the user running chef-client" description_list: - markdown: The system user that will own the checked-out code. +target_mode: + support: full examples: | **Use the git mirror** @@ -240,14 +236,14 @@ examples: | The following example shows how Bash can be used to install a plug-in for rbenv named ruby-build, which is located in git version source control. First, the application is synchronized, and then Bash changes its working directory to the location in which ruby-build is located, and then runs a command. ```ruby - git "/Users/tsmith/.chef/cache/ruby-build" do + git "#{Chef::Config[:file_cache_path]}/ruby-build" do repository 'git://github.com/rbenv/ruby-build.git' revision 'master' action :sync end bash 'install_ruby_build' do - cwd "/Users/tsmith/.chef/cache/ruby-build" + cwd "#{Chef::Config[:file_cache_path]}/ruby-build" user 'rbenv' group 'rbenv' code <<-EOH @@ -260,7 +256,7 @@ examples: | **Notify a resource post-checkout** ```ruby - git "/Users/tsmith/.chef/cache/my_app" do + git "#{Chef::Config[:file_cache_path]}/my_app" do repository node['my_app']['git_repository'] revision node['my_app']['git_revision'] action :sync @@ -277,4 +273,4 @@ examples: | environment 'VAR' => 'whatever' action :sync end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/group.yaml b/data/infra/resources/group.yaml index 03e79752..bfbee47c 100644 --- a/data/infra/resources/group.yaml +++ b/data/infra/resources/group.yaml @@ -72,9 +72,7 @@ properties_list: required: false default_value: The resource block's name description_list: - - markdown: 'The name of the group. Default value: the `name` of the resource - - block. See "Syntax" section above for more information.' + - markdown: The name of the group. - property: members ruby_type: String, Array required: false @@ -96,10 +94,18 @@ properties_list: default_value: 'false' description_list: - markdown: Set to `true` if the group belongs to a system group. +target_mode: + support: full + platforms: + - aix + - bsd + - linux + - macos_x + - solaris examples: | The following examples demonstrate various approaches for using the **group** resource in recipes: - **Append users to groups**: + Append users to groups: ```ruby group 'www-data' do @@ -109,7 +115,7 @@ examples: | end ``` - **Add a user to group on the Windows platform**: + Add a user to group on the Windows platform: ```ruby group 'Administrators' do diff --git a/data/infra/resources/habitat_config.yaml b/data/infra/resources/habitat_config.yaml index a56f16a3..4fca7031 100644 --- a/data/infra/resources/habitat_config.yaml +++ b/data/infra/resources/habitat_config.yaml @@ -67,6 +67,8 @@ properties_list: description_list: - markdown: Name of user key to use for encryption. Passes `--user` to `hab config apply`. +target_mode: + support: full examples: | **Configure your nginx defaults** diff --git a/data/infra/resources/habitat_install.yaml b/data/infra/resources/habitat_install.yaml index 0b33f2de..ba6ca80b 100644 --- a/data/infra/resources/habitat_install.yaml +++ b/data/infra/resources/habitat_install.yaml @@ -69,6 +69,8 @@ properties_list: - markdown: Sets TMPDIR environment variable for location to place temp files. - note: markdown: This is required if `/tmp` and `/var/tmp` are mounted `noexec`. +target_mode: + support: full examples: | **Installation Without a Resource Name** diff --git a/data/infra/resources/habitat_package.yaml b/data/infra/resources/habitat_package.yaml index 7591fa65..1ac8baae 100644 --- a/data/infra/resources/habitat_package.yaml +++ b/data/infra/resources/habitat_package.yaml @@ -14,6 +14,7 @@ syntax_full_code_block: |- binlink true, false, force # default value: false bldr_url String # default value: "https://bldr.habitat.sh" channel String # default value: "stable" + environment Hash exclude String keep_latest String no_deps true, false # default value: false @@ -30,9 +31,9 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`auth_token`, `binlink`, `bldr_url`, `channel`, `exclude`, `keep_latest`, `no_deps`, - `options`, `package_name`, `source`, `timeout`, and `version` are the properties - available to this resource." +- "`auth_token`, `binlink`, `bldr_url`, `channel`, `environment`, `exclude`, `keep_latest`, + `no_deps`, `options`, `package_name`, `source`, `timeout`, and `version` are the + properties available to this resource." actions_list: :install: markdown: Install a package. If a version is specified, install the specified @@ -76,6 +77,13 @@ properties_list: default_value: stable description_list: - markdown: The release channel to install your package from. +- property: environment + ruby_type: Hash + required: false + new_in: '19.0' + description_list: + - markdown: A Hash of environment variables in the form of {'ENV_VARIABLE' => 'VALUE'} + to be set before running the command. - property: exclude ruby_type: String required: false @@ -120,6 +128,8 @@ properties_list: required: false description_list: - markdown: The version of a package to be installed or upgraded. +target_mode: + support: full examples: | **Install core/redis** diff --git a/data/infra/resources/habitat_service.yaml b/data/infra/resources/habitat_service.yaml index a5005abd..0527d6b5 100644 --- a/data/infra/resources/habitat_service.yaml +++ b/data/infra/resources/habitat_service.yaml @@ -162,6 +162,8 @@ properties_list: This requires a minimum habitat version of 1.5.71_** - `latest`: Runs the latest package that can be found in the configured channel and local packages. - `track-channel`: Always run the package at the head of a given channel. This enables service rollback, where demoting a package from a channel will cause the package to rollback to an older version of the package. A ramification of enabling this condition is that packages that are newer than the package at the head of the channel are also uninstalled during a service rollback. +target_mode: + support: full examples: | **Install and load nginx** diff --git a/data/infra/resources/habitat_sup.yaml b/data/infra/resources/habitat_sup.yaml index 67ba4590..801b1a1e 100644 --- a/data/infra/resources/habitat_sup.yaml +++ b/data/infra/resources/habitat_sup.yaml @@ -238,6 +238,8 @@ properties_list: This requires a minimum habitat version of 1.5.71_** - `latest`: Runs the latest package that can be found in the configured channel and local packages. - `track-channel`: Always run what is at the head of a given channel. This enables service rollback where demoting a package from a channel will cause the package to rollback to an older version of the package. A ramification of enabling this condition is packages newer than the package at the head of the channel will be automatically uninstalled during a service rollback. +target_mode: + support: full examples: | **Set up with just the defaults** @@ -273,7 +275,7 @@ examples: | end ``` - **Provide event_stream_* information** + **Provide event stream information** ```ruby habitat_sup 'default' do diff --git a/data/infra/resources/habitat_user_toml.yaml b/data/infra/resources/habitat_user_toml.yaml index 4e4d9eba..18115fe7 100644 --- a/data/infra/resources/habitat_user_toml.yaml +++ b/data/infra/resources/habitat_user_toml.yaml @@ -43,6 +43,7 @@ properties_list: default_value: The resource block's name description_list: - markdown: The service group to apply the configuration to, for example, `nginx.default`. +target_mode: examples: | **Configure user specific settings to nginx** diff --git a/data/infra/resources/homebrew_cask.yaml b/data/infra/resources/homebrew_cask.yaml index f3c686fd..47f45804 100644 --- a/data/infra/resources/homebrew_cask.yaml +++ b/data/infra/resources/homebrew_cask.yaml @@ -22,8 +22,8 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`cask_name`, `homebrew_path`, `options`, and `owner` are the properties - available to this resource." +- "`cask_name`, `homebrew_path`, `options`, and `owner` are the properties available + to this resource." actions_list: :nothing: shortcode: resources_common_actions_nothing.md @@ -43,7 +43,7 @@ properties_list: ruby_type: String required: false description_list: - - markdown: The path to the homebrew binary. + - markdown: The path to the Homebrew binary. - property: options ruby_type: String required: false @@ -55,4 +55,5 @@ properties_list: default_value: Calculated default username description_list: - markdown: The owner of the Homebrew installation. -examples: \ No newline at end of file +target_mode: +examples: diff --git a/data/infra/resources/homebrew_package.yaml b/data/infra/resources/homebrew_package.yaml index d264bd61..3912eeca 100644 --- a/data/infra/resources/homebrew_package.yaml +++ b/data/infra/resources/homebrew_package.yaml @@ -15,6 +15,7 @@ resource_description_list: resource_new_in: '12.0' syntax_full_code_block: |- homebrew_package 'name' do + environment Hash homebrew_user String, Integer options String, Array package_name String, Array @@ -29,30 +30,45 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`homebrew_user`, `options`, `package_name`, `source`, `timeout`, and `version` - are the properties available to this resource." +- "`environment`, `homebrew_user`, `options`, `package_name`, `source`, `timeout`, + and `version` are the properties available to this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md :install: markdown: Install a package. If a version is specified, install the specified version of the package. (default) + :upgrade: + markdown: Install a package and ensure that a package is the latest version. + :remove: + markdown: Remove a package. :purge: markdown: Purge a package. This action typically removes the configuration files as well as the package. - :remove: - markdown: Remove a package. - :upgrade: - markdown: Install a package and ensure that a package is the latest version. + :reconfig: + markdown: + :lock: + markdown: + :unlock: + markdown: properties_list: +- property: environment + ruby_type: Hash + required: false + new_in: '19.0' + description_list: + - markdown: A Hash of environment variables in the form of {'ENV_VARIABLE' => 'VALUE'} + to be set before running the command. - property: homebrew_user ruby_type: String, Integer required: false description_list: - markdown: |- - The name or uid of the Homebrew owner to be used by Chef Infra Client when executing a command. + The name or UID of the Homebrew owner to be used by Chef Infra Client when executing a command. Chef Infra Client, by default, will attempt to execute a Homebrew command as the owner of the `/usr/local/bin/brew` executable on x86_64 machines or `/opt/homebrew/bin/brew` executable on arm64 machines. If that executable doesn't exist, Chef Infra Client will attempt to find the user by executing `which brew`. If that executable can't be found, Chef Infra Client will print an error message: `Couldn't find the 'brew' executable anywhere on the path.`. - Set this property to specify the Homebrew owner for situations where Chef Infra Client can't automatically detect the correct owner.' + Set this property to specify the Homebrew owner for situations where Chef Infra Client cannot automatically detect the correct owner.' - property: options ruby_type: String, Array required: false @@ -79,6 +95,7 @@ properties_list: required: false description_list: - markdown: The version of a package to be installed or upgraded. +target_mode: examples: | **Install a package**: @@ -106,4 +123,4 @@ examples: | homebrew_package 'vim' do homebrew_user 'user1' end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/homebrew_tap.yaml b/data/infra/resources/homebrew_tap.yaml index d7fbd37a..e3b7d8d8 100644 --- a/data/infra/resources/homebrew_tap.yaml +++ b/data/infra/resources/homebrew_tap.yaml @@ -55,8 +55,8 @@ properties_list: required: false description_list: - markdown: The URL of the tap. +target_mode: examples: | - **Tap a repository**: ```ruby diff --git a/data/infra/resources/homebrew_update.yaml b/data/infra/resources/homebrew_update.yaml index daa38214..3c2fb823 100644 --- a/data/infra/resources/homebrew_update.yaml +++ b/data/infra/resources/homebrew_update.yaml @@ -35,6 +35,7 @@ properties_list: description_list: - markdown: Determines how frequently (in seconds) Homebrew updates are made. Use this property when the `:periodic` action is specified. +target_mode: examples: | **Update the homebrew repository data at a specified interval**: ```ruby @@ -46,4 +47,4 @@ examples: | **Update the Homebrew repository at the start of a Chef Infra Client run**: ```ruby homebrew_update 'update' - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/hostname.yaml b/data/infra/resources/hostname.yaml index 1f34389b..59d7d0e6 100644 --- a/data/infra/resources/hostname.yaml +++ b/data/infra/resources/hostname.yaml @@ -86,6 +86,14 @@ properties_list: description_list: - markdown: Determines whether or not Windows should be reboot after changing the hostname, as this is required for the change to take effect. +target_mode: + support: full + platforms: + - aix + - bsd + - linux + - macos_x + - solaris examples: | **Set the hostname using the IP address, as detected by Ohai**: diff --git a/data/infra/resources/http_request.yaml b/data/infra/resources/http_request.yaml index 7bf71fc5..b4588425 100644 --- a/data/infra/resources/http_request.yaml +++ b/data/infra/resources/http_request.yaml @@ -11,7 +11,6 @@ resource_description_list: syntax_full_code_block: |- http_request 'name' do headers Hash # default value: {} - message Object # defaults to 'name' if not specified url String action Symbol # defaults to :get if not specified end @@ -27,13 +26,11 @@ syntax_description: | ``` syntax_full_properties_list: -- '`http_request` is the resource.' -- '`name` is the name given to the resource block.' -- '`action` identifies which steps Chef Infra Client will take to bring the node into - the desired state.' -- '`headers`, `message`, and `url` are properties of this resource, with the Ruby - type shown. See "Properties" section below for more information about all of the - properties that may be used with this resource.' +- "`http_request` is the resource." +- "`name` is the name given to the resource block." +- "`action` identifies which steps Chef Infra Client will take to bring the node into + the desired state." +- "`headers` and `url` are the properties available to this resource." actions_list: :delete: markdown: Send a `DELETE` request. @@ -56,22 +53,16 @@ properties_list: - property: headers ruby_type: Hash required: false + default_value: "{}" description_list: - markdown: A Hash of custom headers. -- property: message - ruby_type: Object - required: false - description_list: - - markdown: 'The message that is sent by the HTTP request. Default value: the - - `name` of the resource block. See "Syntax" section above for more - - information.' - property: url ruby_type: String required: false description_list: - markdown: The URL to which an HTTP request is sent. +target_mode: + support: full examples: "\n Send a GET request\n\n ```ruby\n http_request 'some_message' do\n\ \ url 'http://example.com/check_in'\n end\n ```\n\n The message is sent as\n\ \ `http://example.com/check_in?message=some_message`.\n\n Send a POST request\n\ diff --git a/data/infra/resources/ifconfig.yaml b/data/infra/resources/ifconfig.yaml index 7e4c2dce..dcbb64cd 100644 --- a/data/infra/resources/ifconfig.yaml +++ b/data/infra/resources/ifconfig.yaml @@ -48,18 +48,18 @@ syntax_full_properties_list: `onboot`, `onparent`, `slave`, `target`, and `vlan` are the properties available to this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md :add: markdown: Run ifconfig to configure a network interface and (on some platforms) write a configuration file for that network interface. (default) :delete: markdown: Run ifconfig to disable a network interface and (on some platforms) delete that network interface’s configuration file. - :disable: - markdown: Run ifconfig to disable a network interface. :enable: markdown: Run ifconfig to enable a network interface. - :nothing: - shortcode: resources_common_actions_nothing.md + :disable: + markdown: Run ifconfig to disable a network interface. properties_list: - property: bcast ruby_type: String @@ -181,6 +181,8 @@ properties_list: new_in: '14.4' description_list: - markdown: The VLAN to assign the interface to. +target_mode: + support: full examples: | **Configure a network interface with a static IP** @@ -226,4 +228,4 @@ examples: | ``` iface eth1 inet dhcp address 33.33.33.80 - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/inspec_input.yaml b/data/infra/resources/inspec_input.yaml index 4e18391b..9d02c611 100644 --- a/data/infra/resources/inspec_input.yaml +++ b/data/infra/resources/inspec_input.yaml @@ -21,10 +21,10 @@ syntax_full_properties_list: the desired state." - "`input` and `source` are the properties available to this resource." actions_list: - :add: - markdown: Add an input to the compliance phase (default) :nothing: shortcode: resources_common_actions_nothing.md + :add: + markdown: Add an input to the compliance phase (default) properties_list: - property: input ruby_type: Hash, String @@ -38,6 +38,8 @@ properties_list: default_value: The resource block's name description_list: - markdown: +target_mode: + support: full examples: |2 **Activate the default input in the openssh cookbook's compliance segment**: diff --git a/data/infra/resources/inspec_waiver.yaml b/data/infra/resources/inspec_waiver.yaml index db68efdc..53ae0d31 100644 --- a/data/infra/resources/inspec_waiver.yaml +++ b/data/infra/resources/inspec_waiver.yaml @@ -25,10 +25,10 @@ syntax_full_properties_list: - "`control`, `expiration`, `justification`, `run_test`, and `source` are the properties available to this resource." actions_list: - :add: - markdown: Add a waiver to the compliance phase (default) :nothing: shortcode: resources_common_actions_nothing.md + :add: + markdown: Add a waiver to the compliance phase (default) properties_list: - property: control ruby_type: String @@ -59,6 +59,8 @@ properties_list: required: false description_list: - markdown: +target_mode: + support: full examples: | **Activate the default waiver in the openssh cookbook's compliance segment**: diff --git a/data/infra/resources/inspec_waiver_file_entry.yaml b/data/infra/resources/inspec_waiver_file_entry.yaml index ccf0fa86..931c6ff7 100644 --- a/data/infra/resources/inspec_waiver_file_entry.yaml +++ b/data/infra/resources/inspec_waiver_file_entry.yaml @@ -28,10 +28,10 @@ syntax_full_properties_list: - "`backup`, `control`, `expiration`, `file_path`, `justification`, and `run_test` are the properties available to this resource." actions_list: - :add: - markdown: " (default)" :nothing: shortcode: resources_common_actions_nothing.md + :add: + markdown: " (default)" :remove: markdown: properties_list: @@ -74,6 +74,8 @@ properties_list: - markdown: If present and `true`, the control will run and be reported, but failures in it won’t make the overall run fail. If absent or `false`, the control will not be run. +target_mode: + support: full examples: | **Add an InSpec waiver entry to a given waiver file**: diff --git a/data/infra/resources/ips_package.yaml b/data/infra/resources/ips_package.yaml index 663850f6..08188db6 100644 --- a/data/infra/resources/ips_package.yaml +++ b/data/infra/resources/ips_package.yaml @@ -21,6 +21,7 @@ syntax_description: | syntax_full_code_block: |- ips_package 'name' do accept_license true, false # default value: false + environment Hash options String, Array package_name String source String @@ -28,23 +29,33 @@ syntax_full_code_block: |- version String action Symbol # defaults to :install if not specified end +syntax_properties_list: syntax_full_properties_list: - "`ips_package` is the resource." - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`accept_license`, `options`, `package_name`, `source`, `timeout`, and `version` - are the properties available to this resource." +- "`accept_license`, `environment`, `options`, `package_name`, `source`, `timeout`, + and `version` are the properties available to this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md :install: markdown: Install a package. If a version is specified, install the specified version of the package. (default) - :nothing: - shortcode: resources_common_actions_nothing.md - :remove: - markdown: Remove a package. :upgrade: markdown: Install a package and ensure that a package is the latest version. + :remove: + markdown: Remove a package. + :purge: + markdown: Purge a package. This action typically removes the configuration files + as well as the package. + :reconfig: + markdown: + :lock: + markdown: + :unlock: + markdown: properties_list: - property: accept_license ruby_type: true, false @@ -52,6 +63,13 @@ properties_list: default_value: 'false' description_list: - markdown: Accept an end-user license agreement, automatically. +- property: environment + ruby_type: Hash + required: false + new_in: '19.0' + description_list: + - markdown: A Hash of environment variables in the form of {'ENV_VARIABLE' => 'VALUE'} + to be set before running the command. - property: options ruby_type: String, Array required: false @@ -78,6 +96,8 @@ properties_list: required: false description_list: - markdown: The version of a package to be installed or upgraded. +target_mode: + support: full examples: " Install a package\n\n ```ruby\n ips_package 'name of package'\ \ do\n action :install\n end\n ```\n" diff --git a/data/infra/resources/kernel_module.yaml b/data/infra/resources/kernel_module.yaml index 338bd755..3b2c584d 100644 --- a/data/infra/resources/kernel_module.yaml +++ b/data/infra/resources/kernel_module.yaml @@ -26,21 +26,21 @@ syntax_full_properties_list: - "`load_dir`, `modname`, `options`, and `unload_dir` are the properties available to this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :install: + markdown: Load kernel module, and ensure it loads on reboot. (default) + :uninstall: + markdown: Unload a kernel module and remove module config, so it doesn't load + on reboot. :blacklist: markdown: Blacklist a kernel module. :disable: markdown: Disable a kernel module. **New in Chef Infra Client 15.2.** :enable: markdown: Enable a kernel module. Reverse :disable actions - :install: - markdown: Load kernel module, and ensure it loads on reboot. (default) :load: markdown: Load a kernel module. - :nothing: - shortcode: resources_common_actions_nothing.md - :uninstall: - markdown: Unload a kernel module and remove module config, so it doesn't load - on reboot. :unload: markdown: Unload kernel module. properties_list: @@ -69,6 +69,8 @@ properties_list: default_value: "/etc/modprobe.d" description_list: - markdown: The modprobe.d directory. +target_mode: + support: full examples: | Install and load a kernel module, and ensure it loads on reboot. diff --git a/data/infra/resources/ksh.yaml b/data/infra/resources/ksh.yaml index 9279e786..004161d2 100644 --- a/data/infra/resources/ksh.yaml +++ b/data/infra/resources/ksh.yaml @@ -26,42 +26,68 @@ syntax_description: | where: - `code` specifies the command to run. +resource_new_in: '12.6' syntax_full_code_block: |- ksh 'name' do - code String - creates String - cwd String - environment Hash - flags String - group String, Integer - path Array - returns Integer, Array - timeout Integer, Float - user String, Integer - umask String, Integer - action Symbol # defaults to :run if not specified + cgroup String + code String + command String, Array # default value: 'name' unless specified + creates String + cwd String + default_env true, false # default value: false + domain String + elevated true, false # default value: false + environment Hash + flags String + group String, Integer + input String + interpreter String + live_stream true, false # default value: false + login true, false # default value: false + password String + returns Integer, Array # default value: 0 + timeout Integer, String, Float # default value: 3600 + user String, Integer + action Symbol # defaults to :run if not specified end syntax_properties_list: -- '`code` specifies the command to run' syntax_full_properties_list: - "`ksh` is the resource." - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`code`, `creates`, `cwd`, `environment`, - `flags`, `group`, `input`, `path`, `returns`, - `timeout`, `user`, and `umask` are the properties available to this resource." +- "`cgroup`, `code`, `command`, `creates`, `cwd`, `default_env`, `domain`, `elevated`, + `environment`, `flags`, `group`, `input`, `interpreter`, `live_stream`, `login`, + `password`, `returns`, `timeout`, and `user` are the properties available to this + resource." actions_list: :nothing: shortcode: resources_common_actions_nothing.md :run: markdown: Run a command. (default) properties_list: +- property: cgroup + ruby_type: String + required: false + new_in: '19.0' + description_list: + - markdown: 'Linux only: Run the command within a specific cgroup, creating it if + it doesn''t exist.' - property: code ruby_type: String required: true description_list: - markdown: A quoted string of code to be executed. +- property: command + ruby_type: String, Array + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the command to be executed if it differs + from the resource block's name. + - note: + markdown: Use the **execute** resource to run a single command. Use multiple + **execute** resource blocks to run multiple commands. - property: creates ruby_type: String required: false @@ -72,6 +98,36 @@ properties_list: required: false description_list: - markdown: The current working directory from which the command will be run. +- property: default_env + ruby_type: true, false + required: false + default_value: 'false' + new_in: '14.2' + description_list: + - markdown: When true this enables ENV magic to add path_sanity to the PATH and + force the locale to English+UTF-8 for parsing output +- property: domain + ruby_type: String + required: false + new_in: '12.21' + description_list: + - markdown: 'Windows only: The domain of the user specified by the user property. + If not specified, the username and password specified by the `user` and `password` + properties will be used to resolve that user against the domain in which the + system running Chef Infra Client is joined, or if that system is not joined + to a domain it will resolve the user as a local account on that system. An alternative + way to specify the domain is to leave this property unspecified and specify + the domain as part of the user property.' +- property: elevated + ruby_type: true, false + required: false + default_value: 'false' + new_in: '13.3' + description_list: + - markdown: |- + Determines whether the script will run with elevated permissions to circumvent User Access Control (UAC) from interactively blocking the process. + This will cause the process to be run under a batch login instead of an interactive login. The user running chef-client needs the 'Replace a process level token' and 'Adjust Memory Quotas for a process' permissions. The user that is running the command needs the 'Log on as a batch job' permission. + Because this requires a login, the user and password properties are required. - property: environment ruby_type: Hash required: false @@ -90,6 +146,41 @@ properties_list: required: false description_list: - markdown: The group name or group ID that must be changed before running a command. +- property: input + ruby_type: String + required: false + new_in: '16.2' + description_list: + - markdown: An optional property to set the input sent to the command as STDIN. +- property: interpreter + ruby_type: String + required: false + description_list: + - markdown: +- property: live_stream + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Send the output of the command run by this execute resource block to + the Chef Infra Client event stream. +- property: login + ruby_type: true, false + required: false + default_value: 'false' + new_in: '17.0' + description_list: + - markdown: Use a login shell to run the commands instead of inheriting the existing + execution environment. +- property: password + ruby_type: String + required: false + new_in: '12.21' + description_list: + - markdown: 'Windows only: The password of the user specified by the user property. + This property is mandatory if user is specified on Windows and may only be specified + if user is specified. The sensitive property for this resource will automatically + be set to true if password is specified.' - property: returns ruby_type: Integer, Array required: false @@ -107,10 +198,12 @@ properties_list: ruby_type: String, Integer required: false description_list: - - markdown: The user name or user ID that should be changed before running a command. -- property: umask - ruby_type: String, Integer - required: false - description_list: - - markdown: The file mode creation mask, or umask. + - markdown: The user name of the user identity with which to launch the new process. + The user name may optionally be specified with a domain, i.e. `domain\user` + or `user@my.dns.domain.com` via Universal Principal Name (UPN)format. It can + also be specified without a domain simply as user if the domain is instead specified + using the domain property. On Windows only, if this property is specified, the + password property must be specified. +target_mode: + support: full examples: diff --git a/data/infra/resources/launchd.yaml b/data/infra/resources/launchd.yaml index cd548c37..2f7115c2 100644 --- a/data/infra/resources/launchd.yaml +++ b/data/infra/resources/launchd.yaml @@ -65,7 +65,7 @@ syntax_full_code_block: |- working_directory String action Symbol # defaults to :create if not specified end -syntax_properties_list: +syntax_properties_list: syntax_full_properties_list: - "`launchd` is the resource." - "`name` is the name given to the resource block." @@ -111,7 +111,7 @@ properties_list: ruby_type: Array required: false description_list: - - markdown: This optional key indicates which bundles the **Login Items Added by Apps** + - markdown: This optional key indicates which bundles the Login Items Added by Apps panel associates with the helper executable. - property: backup ruby_type: Integer, false @@ -160,8 +160,8 @@ properties_list: ruby_type: String, Integer required: false description_list: - - markdown: When launchd is run as the root user, this is the corresponding group to run the job as. If - the `username` property is specified and this property is not, this value is set + - markdown: When launchd is run as the root user, the group to run the job as. If + the username property is specified and this property is not, this value is set to the default group for the user. - property: hard_resource_limits ruby_type: Hash @@ -261,7 +261,7 @@ properties_list: required: false description_list: - markdown: A string or ID that identifies the group owner by user name, including - fully qualified user names such as `domain_user` or `user@domain`. If this value + fully qualified user names such as domain_user or user@domain. If this value is not specified, existing owners remain unchanged and new owner assignments use the current user (when necessary). - property: path @@ -352,11 +352,8 @@ properties_list: ruby_type: Hash, Array required: false description_list: - - markdown: 'A Hash (similar to `crontab`) or an Array that defines the calendar frequency at - which a job is started. For example: - `{ Minute => "0", Hour => "20", Day => "*", Weekday => "1-5", Month => "*" }` - will run a job at 8:00 PM every day, Monday through Friday, every - month of the year.' + - markdown: A Hash (similar to crontab) that defines the calendar frequency at which + a job is started or an Array. - property: start_interval ruby_type: Integer required: false @@ -406,6 +403,7 @@ properties_list: required: false description_list: - markdown: "`chdir` to this directory, and then run the job." +target_mode: examples: " Create a Launch Daemon from a cookbook file\n\n ```ruby\n launchd\ \ 'com.chef.every15' do\n source 'com.chef.every15.plist'\n end\n ```\n\n \ diff --git a/data/infra/resources/link.yaml b/data/infra/resources/link.yaml index 05ca9c87..13950a45 100644 --- a/data/infra/resources/link.yaml +++ b/data/infra/resources/link.yaml @@ -8,9 +8,7 @@ resource_description_list: - markdown: |- Use the **link** resource to create symbolic or hard links. - A symbolic link--sometimes referred to as a soft link--is a directory entry that associates a file name with a string - that contains an absolute or relative path to a file on any file system. In other words, it's a file that contains a path - that points to another file. A symbolic link creates a new file with a new inode that points to the inode location of the original file. + A symbolic link—sometimes referred to as a soft link—is a directory entry that associates a file name with a string that contains an absolute or relative path to a file on any file system. In other words, 'a file that contains a path that points to another file.' A symbolic link creates a new file with a new inode that points to the inode location of the original file. A hard link is a directory entry that associates a file with another file in the same file system. In other words, multiple directory entries to the same file. A hard link creates a new file that points to the same inode as the original file. @@ -72,66 +70,7 @@ properties_list: default_value: ":symbolic" allowed_values: ":hard, :symbolic" description_list: - - markdown: 'The type of link: `:symbolic` or `:hard`. On Windows, `:symbolic` will create a junction point if the target is a directory.' -- property: mode - ruby_type: Integer, String - required: false - default_value: '777' - description_list: - - markdown: 'If `mode` is not specified and if the file already exists, the - - existing mode on the file is used. If `mode` is not specified, the - - file does not exist, and the `:create` action is specified, Chef - - Infra Client assumes a mask value of `''0777''` and then applies the - - umask for the system on which the file is to be created to the - - `mask` value. For example, if the umask on a system is `''022''`, Chef - - Infra Client uses the default value of `''0755''`. - - - The behavior is different depending on the platform. - - - UNIX- and Linux-based systems: A quoted 3-5 character string that - - defines the octal mode that is passed to chmod. For example: - - `''755''`, `''0755''`, or `00755`. If the value is specified as a quoted - - string, it works exactly as if the `chmod` command was passed. If - - the value is specified as an integer, prepend a zero (`0`) to the - - value to ensure that it is interpreted as an octal number. For - - example, to assign read, write, and execute rights for all users, - - use `''0777''` or `''777''`; for the same rights, plus the sticky bit, - - use `01777` or `''1777''`. - - - Microsoft Windows: A quoted 3-5 character string that defines the - - octal mode that is translated into rights for Microsoft Windows - - security. For example: `''755''`, `''0755''`, or `00755`. Values up to - - `''0777''` are allowed (no sticky bits) and mean the same in Microsoft - - Windows as they do in UNIX, where `4` equals `GENERIC_READ`, `2` - - equals `GENERIC_WRITE`, and `1` equals `GENERIC_EXECUTE`. This - - property cannot be used to set `:full_control`. This property has no - - effect if not specified, but when it and `rights` are both - - specified, the effects are cumulative.' + - markdown: 'The type of link: :symbolic or :hard.' - property: owner ruby_type: String, Integer required: false @@ -142,14 +81,15 @@ properties_list: required: false default_value: The resource block's name description_list: - - markdown: 'An optional property to set the target file if it differs from the - - resource block''s name.' + - markdown: An optional property to set the target file if it differs from the resource + block's name. - property: to ruby_type: String required: false description_list: - markdown: The actual file to which the link is to be created. +target_mode: + support: full examples: | **Create symbolic links** diff --git a/data/infra/resources/locale.yaml b/data/infra/resources/locale.yaml index 505165de..391216ad 100644 --- a/data/infra/resources/locale.yaml +++ b/data/infra/resources/locale.yaml @@ -39,6 +39,8 @@ properties_list: description_list: - markdown: A Hash of LC_* env variables in the form of `({ 'LC_ENV_VARIABLE' => 'VALUE' })`. +target_mode: + support: full examples: | Set the lang to 'en_US.UTF-8' diff --git a/data/infra/resources/log.yaml b/data/infra/resources/log.yaml index e34c7ddd..07bdb41f 100644 --- a/data/infra/resources/log.yaml +++ b/data/infra/resources/log.yaml @@ -11,13 +11,44 @@ resource_description_list: - markdown: 'Use the **log** resource to create log entries. The log resource behaves like any other resource: built into the resource collection during the compile phase, and then run during the execution phase. (To create a log entry that is - not built into the resource collection, use `Chef::Log` instead of the log resource.)' + not built into the resource collection, use Chef::Log instead of the log resource.)' +syntax_full_code_block: |- + log 'name' do + level Symbol # default value: :info + message String # default value: 'name' unless specified + action Symbol # defaults to :write if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`log` is the resource." +- "`name` is the name given to the resource block." +- "`action` identifies which steps Chef Infra Client will take to bring the node into + the desired state." +- "`level` and `message` are the properties available to this resource." actions_list: :nothing: shortcode: resources_common_actions_nothing.md :write: - markdown: "(default)" -examples: " + markdown: " (default)" +properties_list: +- property: level + ruby_type: Symbol + required: false + default_value: ":info" + allowed_values: ":debug, :error, :fatal, :info, :warn" + description_list: + - markdown: The logging level to display this message at. +- property: message + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: The message to be added to a log file. If not specified we'll use the + resource's name instead. +target_mode: + support: full + introduced: '15.1' +examples: " Set default logging level\n\n ```ruby\n log 'a string to log'\n\ \ ```\n\n Set debug logging level\n\n ```ruby\n log 'a debug string' do\n \ \ level :debug\n end\n ```\n\n Add a message to a log file\n\n ```ruby\n\ diff --git a/data/infra/resources/macos_pkg.yaml b/data/infra/resources/macos_pkg.yaml new file mode 100644 index 00000000..19ca7cf8 --- /dev/null +++ b/data/infra/resources/macos_pkg.yaml @@ -0,0 +1,79 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: macos_pkg +resource_description_list: +- markdown: Use the **macos_pkg** resource to install a macOS `.pkg` file, optionally + downloading it from a remote source. A `package_id` property must be provided + for idempotency. Either a `file` or `source` property is required. +resource_new_in: '18.1' +syntax_full_code_block: |- + macos_pkg 'name' do + checksum String + file String + headers Hash + package_id String + source String + target String # default value: "/" + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`macos_pkg` is the resource." +- "`name` is the name given to the resource block." +- "`action` identifies which steps Chef Infra Client will take to bring the node into + the desired state." +- "`checksum`, `file`, `headers`, `package_id`, `source`, and `target` are the properties + available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :install: + markdown: Installs the pkg. (default) +properties_list: +- property: checksum + ruby_type: String + required: false + description_list: + - markdown: The sha256 checksum of the `.pkg` file to download. +- property: file + ruby_type: String + required: false + description_list: + - markdown: The absolute path to the `.pkg` file on the local system. +- property: headers + ruby_type: Hash + required: false + description_list: + - markdown: Allows custom HTTP headers (like cookies) to be set on the `remote_file` + resource. +- property: package_id + ruby_type: String + required: true + description_list: + - markdown: The package ID registered with `pkgutil` when a `pkg` or `mpkg` is installed. +- property: source + ruby_type: String + required: false + description_list: + - markdown: The remote URL used to download the `.pkg` file. +- property: target + ruby_type: String + required: false + default_value: "/" + description_list: + - markdown: The device to install the package on. +target_mode: +examples: | + **Install osquery**: + + ```ruby + macos_pkg 'osquery' do + checksum '1fea8ac9b603851d2e76c5fc73138a468a3075a3002c8cb1fd7fff53b889c4dd' + package_id 'io.osquery.agent' + source 'https://pkg.osquery.io/darwin/osquery-5.8.2.pkg' + action :install + end + ``` diff --git a/data/infra/resources/macos_userdefaults.yaml b/data/infra/resources/macos_userdefaults.yaml index e0ea9e2c..ea11838b 100644 --- a/data/infra/resources/macos_userdefaults.yaml +++ b/data/infra/resources/macos_userdefaults.yaml @@ -70,7 +70,8 @@ properties_list: markdown: 'With the `type` property set to `bool`, `String` forms of Boolean true/false values that Apple accepts in the defaults command will be coerced: 0/1, ''TRUE''/''FALSE,'' ''true''/false'', ''YES''/''NO'', or ''yes''/''no''.' -examples: | +target_mode: +examples: |+ **Specify a global domain value** ```ruby @@ -99,4 +100,6 @@ examples: | user 'jane' host :current end - ``` \ No newline at end of file + ``` + +... diff --git a/data/infra/resources/macosx_service.yaml b/data/infra/resources/macosx_service.yaml index f76da862..0f7ad66b 100644 --- a/data/infra/resources/macosx_service.yaml +++ b/data/infra/resources/macosx_service.yaml @@ -52,6 +52,10 @@ actions_list: markdown: Stop and then start a service again. :reload: markdown: Reload the configuration for this service. + :mask: + markdown: + :unmask: + markdown: properties_list: - property: init_command ruby_type: String @@ -59,26 +63,25 @@ properties_list: description_list: - markdown: The path to the init script that is associated with the service. Use `init_command` to prevent the need to specify overrides for the `start_command`, - `stop_command`, and `restart_command` properties. When this property is not specified, - the Chef Infra Client will use the default init command for the service provider - being used. + `stop_command`, and `restart_command` properties. When this property is not + specified, the Chef Infra Client will use the default init command for the service + provider being used. - property: options ruby_type: Array, String required: false description_list: - - markdown: | - **Solaris platform only**. Options to pass to the `service` command. See the + - markdown: Solaris platform only. Options to pass to the service command. See the svcadm manual for details of possible options. - property: parameters ruby_type: Hash required: false description_list: - - markdown: '**Upstart only**. A hash of parameters to pass to the `service` command for + - markdown: 'Upstart only: A hash of parameters to pass to the service command for use in the service definition.' - property: pattern ruby_type: String required: false - default_value: The value provided to `service_name` or the resource block's name + default_value: The value provided to 'service_name' or the resource block's name description_list: - markdown: The pattern to look for in the process table. - property: plist @@ -91,8 +94,7 @@ properties_list: ruby_type: Integer, String, Hash required: false description_list: - - markdown: | - **Debian platform only**. The relative priority of the program for start + - markdown: Debian platform only. The relative priority of the program for start and shutdown ordering. May be an integer or a Hash. An integer is used to define the start run levels; stop run levels are then 100-integer. A Hash is used to define values for specific run levels. For example, { 2 => [:start, 20], 3 => @@ -112,7 +114,7 @@ properties_list: ruby_type: Array required: false description_list: - - markdown: '**RHEL platforms only**. Specific run levels the service will run under.' + - markdown: 'RHEL platforms only: Specific run_levels the service will run under.' - property: service_name ruby_type: String required: false @@ -124,7 +126,7 @@ properties_list: ruby_type: String required: false description_list: - - markdown: The type of plist to be created + - markdown: - property: start_command ruby_type: String, false required: false @@ -169,4 +171,5 @@ properties_list: new_in: '12.21' description_list: - markdown: 'systemd only: A username to run the service under.' +target_mode: examples: diff --git a/data/infra/resources/macports_package.yaml b/data/infra/resources/macports_package.yaml index 97dd07ef..654dd879 100644 --- a/data/infra/resources/macports_package.yaml +++ b/data/infra/resources/macports_package.yaml @@ -27,6 +27,7 @@ syntax_description: 'A **macports_package** resource block manages a package on and the default action (`:install`).' syntax_full_code_block: |- macports_package 'name' do + environment Hash options String, Array package_name String source String @@ -40,20 +41,35 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`options`, `package_name`, `source`, `timeout`, and `version` are the properties - available to this resource." +- "`environment`, `options`, `package_name`, `source`, `timeout`, and `version` are + the properties available to this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md :install: markdown: Install a package. If a version is specified, install the specified version of the package. (default) + :upgrade: + markdown: Install a package and ensure that a package is the latest version. + :remove: + markdown: Remove a package. :purge: markdown: Purge a package. This action typically removes the configuration files as well as the package. - :remove: - markdown: Remove a package. - :upgrade: - markdown: Install a package and ensure that a package is the latest version. + :reconfig: + markdown: + :lock: + markdown: + :unlock: + markdown: properties_list: +- property: environment + ruby_type: Hash + required: false + new_in: '19.0' + description_list: + - markdown: A Hash of environment variables in the form of {'ENV_VARIABLE' => 'VALUE'} + to be set before running the command. - property: options ruby_type: String, Array required: false @@ -80,6 +96,7 @@ properties_list: required: false description_list: - markdown: The version of a package to be installed or upgraded. +target_mode: examples: " Install a package\n\n ```ruby\n macports_package 'name of package'\ \ do\n action :install\n end\n ```\n" diff --git a/data/infra/resources/mdadm.yaml b/data/infra/resources/mdadm.yaml index 8b85033c..250069bb 100644 --- a/data/infra/resources/mdadm.yaml +++ b/data/infra/resources/mdadm.yaml @@ -31,13 +31,13 @@ syntax_full_properties_list: - "`bitmap`, `chunk`, `devices`, `layout`, `level`, `metadata`, and `raid_device` are the properties available to this resource." actions_list: - :assemble: - markdown: Assemble a previously created array into an active array. + :nothing: + shortcode: resources_common_actions_nothing.md :create: markdown: Create an array with per-device superblocks. If an array already exists (but does not match), update that array to match. (default) - :nothing: - shortcode: resources_common_actions_nothing.md + :assemble: + markdown: Assemble a previously created array into an active array. :stop: markdown: Stop an active array. properties_list: @@ -85,6 +85,7 @@ properties_list: description_list: - markdown: An optional property to specify the name of the RAID device if it differs from the resource block's name. +target_mode: examples: | **Create and assemble a RAID 0 array** diff --git a/data/infra/resources/mount.yaml b/data/infra/resources/mount.yaml index 941bdec2..325ecbb2 100644 --- a/data/infra/resources/mount.yaml +++ b/data/infra/resources/mount.yaml @@ -33,20 +33,20 @@ syntax_full_properties_list: `mount_point`, `options`, `pass`, `password`, `supports`, and `username` are the properties available to this resource." actions_list: - :disable: - markdown: Remove an entry from the file systems table (fstab). - :enable: - markdown: Add an entry to the file systems table (fstab). - :mount: - markdown: "(default) Mount a device." :nothing: shortcode: resources_common_actions_nothing.md - :remount: - markdown: Remount a device + :mount: + markdown: "(default) Mount a device." :umount: markdown: Unmount a device. :unmount: markdown: Alias for the `:umount` action. + :remount: + markdown: Remount a device + :enable: + markdown: Add an entry to the file systems table (fstab). + :disable: + markdown: Remove an entry from the file systems table (fstab). properties_list: - property: device ruby_type: String @@ -66,7 +66,7 @@ properties_list: ruby_type: String required: false description_list: - - markdown: '**Windows only**. Use to specify the domain in which the `username` and + - markdown: 'Windows only: Use to specify the domain in which the `username` and `password` are located.' - property: dump ruby_type: Integer, false @@ -86,13 +86,13 @@ properties_list: required: false default_value: "-" description_list: - - markdown: '**Solaris only**. The fsck device.' + - markdown: 'Solaris only: The fsck device.' - property: fstype ruby_type: String required: false default_value: auto description_list: - - markdown: The file system type of the device. + - markdown: The file system type (fstype) of the device. - property: mount_point ruby_type: String required: false @@ -117,7 +117,7 @@ properties_list: ruby_type: String required: false description_list: - - markdown: '**Windows only**. Use to specify the password for username.' + - markdown: Windows only:. Use to specify the password for username. - property: supports ruby_type: Array, Hash required: false @@ -128,7 +128,13 @@ properties_list: ruby_type: String required: false description_list: - - markdown: '**Windows only**. Use to specify the user name.' + - markdown: 'Windows only: Use to specify the user name.' +target_mode: + support: full + platforms: + - aix + - bsd + - linux examples: " Mount a labeled file system\n\n ```ruby\n mount '/mnt/volume1'\ \ do\n device 'volume1'\n device_type :label\n fstype 'xfs'\n options\ diff --git a/data/infra/resources/msu_package.yaml b/data/infra/resources/msu_package.yaml index 950affc3..4d9cf55c 100644 --- a/data/infra/resources/msu_package.yaml +++ b/data/infra/resources/msu_package.yaml @@ -11,6 +11,7 @@ resource_new_in: '12.17' syntax_full_code_block: |- msu_package 'name' do checksum String + environment Hash options String, Array package_name String source String @@ -23,17 +24,40 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`checksum`, `options`, `package_name`, `source`, and `timeout` are the properties - available to this resource." +- "`checksum`, `environment`, `options`, `package_name`, `source`, and `timeout` are + the properties available to this resource." actions_list: :nothing: shortcode: resources_common_actions_nothing.md + :install: + markdown: Install a package. If a version is specified, install the specified + version of the package. (default) + :upgrade: + markdown: Install a package and ensure that a package is the latest version. + :remove: + markdown: Remove a package. + :purge: + markdown: Purge a package. This action typically removes the configuration files + as well as the package. + :reconfig: + markdown: + :lock: + markdown: + :unlock: + markdown: properties_list: - property: checksum ruby_type: String required: false description_list: - markdown: SHA-256 digest used to verify the checksum of the downloaded MSU package. +- property: environment + ruby_type: Hash + required: false + new_in: '19.0' + description_list: + - markdown: A Hash of environment variables in the form of {'ENV_VARIABLE' => 'VALUE'} + to be set before running the command. - property: options ruby_type: String, Array required: false @@ -57,6 +81,7 @@ properties_list: default_value: '3600' description_list: - markdown: The amount of time (in seconds) to wait before timing out. +target_mode: examples: " Using local path in source\n\n ```ruby\n msu_package 'Install\ \ Windows 2012R2 Update KB2959977' do\n source 'C:\\Users\\xyz\\AppData\\Local\\\ diff --git a/data/infra/resources/notify_group.yaml b/data/infra/resources/notify_group.yaml index c03c8639..20692047 100644 --- a/data/infra/resources/notify_group.yaml +++ b/data/infra/resources/notify_group.yaml @@ -22,10 +22,12 @@ syntax_full_properties_list: the desired state." actions_list: :nothing: - shortcode: resources_common_actions_nothing_default.md + shortcode: resources_common_actions_nothing.md :run: markdown: properties_list: [] +target_mode: + support: full examples: | Wire up a notification from a service resource to stop and start the service with a 60 second delay. @@ -55,4 +57,4 @@ examples: | variables node["crude"] notifies :run, "notify_group[crude_stop_and_start]", :immediately end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/ohai.yaml b/data/infra/resources/ohai.yaml index 69ca661c..cfd4b3f6 100644 --- a/data/infra/resources/ohai.yaml +++ b/data/infra/resources/ohai.yaml @@ -36,6 +36,8 @@ properties_list: you can pass `ipaddress` to reload `node['ipaddress']` even though that data comes from the `Network` plugin. If this property is not specified, Chef Infra Client will reload all plugins. +target_mode: + support: full examples: | Reload All Ohai Plugins diff --git a/data/infra/resources/ohai_hint.yaml b/data/infra/resources/ohai_hint.yaml index 7da29cdd..bb6cd45d 100644 --- a/data/infra/resources/ohai_hint.yaml +++ b/data/infra/resources/ohai_hint.yaml @@ -50,6 +50,8 @@ properties_list: description_list: - markdown: An optional property to set the hint name if it differs from the resource block's name. +target_mode: + support: full examples: | **Create a hint file** @@ -81,4 +83,4 @@ examples: | ohai_hint 'example' do action :delete end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/openbsd_package.yaml b/data/infra/resources/openbsd_package.yaml index 97368ba6..857af4d1 100644 --- a/data/infra/resources/openbsd_package.yaml +++ b/data/infra/resources/openbsd_package.yaml @@ -22,6 +22,7 @@ syntax_description: | and the default action (`:install`). syntax_full_code_block: |- openbsd_package 'name' do + environment Hash options String, Array package_name String source String @@ -35,15 +36,35 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`options`, `package_name`, `source`, `timeout`, and `version` are the properties - available to this resource." +- "`environment`, `options`, `package_name`, `source`, `timeout`, and `version` are + the properties available to this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md :install: markdown: Install a package. If a version is specified, install the specified version of the package. (default) + :upgrade: + markdown: Install a package and ensure that a package is the latest version. :remove: markdown: Remove a package. + :purge: + markdown: Purge a package. This action typically removes the configuration files + as well as the package. + :reconfig: + markdown: + :lock: + markdown: + :unlock: + markdown: properties_list: +- property: environment + ruby_type: Hash + required: false + new_in: '19.0' + description_list: + - markdown: A Hash of environment variables in the form of {'ENV_VARIABLE' => 'VALUE'} + to be set before running the command. - property: options ruby_type: String, Array required: false @@ -70,6 +91,8 @@ properties_list: required: false description_list: - markdown: The version of a package to be installed or upgraded. +target_mode: + support: full examples: | **Install a package** diff --git a/data/infra/resources/openssl_dhparam.yaml b/data/infra/resources/openssl_dhparam.yaml index 264bdea5..a2f0b602 100644 --- a/data/infra/resources/openssl_dhparam.yaml +++ b/data/infra/resources/openssl_dhparam.yaml @@ -29,10 +29,10 @@ syntax_full_properties_list: - "`generator`, `group`, `key_length`, `mode`, `owner`, and `path` are the properties available to this resource." actions_list: - :create: - markdown: Create the `dhparam.pem` file. (default) :nothing: shortcode: resources_common_actions_nothing.md + :create: + markdown: Create the `dhparam.pem` file. (default) properties_list: - property: generator ruby_type: Integer @@ -71,6 +71,7 @@ properties_list: description_list: - markdown: An optional property for specifying the path to write the file to if it differs from the resource block's name. +target_mode: examples: | **Create a dhparam file** @@ -101,4 +102,4 @@ examples: | openssl_dhparam 'httpd_dhparam' do path '/etc/httpd/ssl/dhparam.pem' end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/openssl_ec_private_key.yaml b/data/infra/resources/openssl_ec_private_key.yaml index 3cb03b44..7f223020 100644 --- a/data/infra/resources/openssl_ec_private_key.yaml +++ b/data/infra/resources/openssl_ec_private_key.yaml @@ -87,6 +87,7 @@ properties_list: description_list: - markdown: An optional property for specifying the path to write the file to if it differs from the resource block's name. +target_mode: examples: | **Generate a new ec privatekey with prime256v1 key curve and default des3 cipher** diff --git a/data/infra/resources/openssl_ec_public_key.yaml b/data/infra/resources/openssl_ec_public_key.yaml index dc38cdd5..5a3c37ac 100644 --- a/data/infra/resources/openssl_ec_public_key.yaml +++ b/data/infra/resources/openssl_ec_public_key.yaml @@ -73,6 +73,7 @@ properties_list: required: false description_list: - markdown: The path to the private key file. +target_mode: examples: | **Generate new EC public key from a private key on disk** diff --git a/data/infra/resources/openssl_rsa_private_key.yaml b/data/infra/resources/openssl_rsa_private_key.yaml index 3c1d8908..23d1c4b1 100644 --- a/data/infra/resources/openssl_rsa_private_key.yaml +++ b/data/infra/resources/openssl_rsa_private_key.yaml @@ -86,6 +86,7 @@ properties_list: description_list: - markdown: An optional property for specifying the path to write the file to if it differs from the resource block's name. +target_mode: examples: | Generate new 2048bit key with the default des3 cipher @@ -104,4 +105,4 @@ examples: | key_cipher 'aes-128-cbc' action :create end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/openssl_rsa_public_key.yaml b/data/infra/resources/openssl_rsa_public_key.yaml index 69c70bbd..08c9065d 100644 --- a/data/infra/resources/openssl_rsa_public_key.yaml +++ b/data/infra/resources/openssl_rsa_public_key.yaml @@ -73,6 +73,7 @@ properties_list: required: false description_list: - markdown: The path to the private key file. +target_mode: examples: | Generate new public key from a private key on disk @@ -122,4 +123,4 @@ examples: | " action :create end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/openssl_x509_certificate.yaml b/data/infra/resources/openssl_x509_certificate.yaml index 2fd80941..29feb5d9 100644 --- a/data/infra/resources/openssl_x509_certificate.yaml +++ b/data/infra/resources/openssl_x509_certificate.yaml @@ -208,6 +208,7 @@ properties_list: description_list: - markdown: Array of Subject Alternative Name entries, in format `DNS:example.com` or `IP:1.2.3.4`. +target_mode: examples: | Create a simple self-signed certificate file diff --git a/data/infra/resources/openssl_x509_crl.yaml b/data/infra/resources/openssl_x509_crl.yaml index 4df1f01b..1c0ed4f1 100644 --- a/data/infra/resources/openssl_x509_crl.yaml +++ b/data/infra/resources/openssl_x509_crl.yaml @@ -104,6 +104,7 @@ properties_list: required: false description_list: - markdown: Serial of the X509 Certificate to revoke. +target_mode: examples: | **Create a certificate revocation file** @@ -122,4 +123,4 @@ examples: | ca_key_file '/etc/ssl_test/my_ca.key' serial_to_revoke C7BCB6602A2E4251EF4E2827A228CB52BC0CEA2F end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/openssl_x509_request.yaml b/data/infra/resources/openssl_x509_request.yaml index 809ff2c7..7a4fe274 100644 --- a/data/infra/resources/openssl_x509_request.yaml +++ b/data/infra/resources/openssl_x509_request.yaml @@ -139,6 +139,7 @@ properties_list: required: false description_list: - markdown: Value for the `ST` certificate field. +target_mode: examples: | **Generate new EC key and CSR file** diff --git a/data/infra/resources/package.yaml b/data/infra/resources/package.yaml index 0da7758f..16b1ae7b 100644 --- a/data/infra/resources/package.yaml +++ b/data/infra/resources/package.yaml @@ -4,11 +4,9 @@ resource_package_options: true resource: package resource_description_list: - markdown: |- - Use the **package** resource to manage packages. When the package is installed from a local file (such as with RubyGems, - dpkg, or RPM Package Manager), the file must be added to the node using the **remote_file** or **cookbook_file** resources. + Use the **package** resource to manage packages. When the package is installed from a local file (such as with RubyGems, dpkg, or RPM Package Manager), the file must be added to the node using the remote_file or cookbook_file resources. - This resource is the base resource for several other resources used for package management on specific platforms. While it - is possible to use each of these specific resources, we recommend using the **package** resource as often as possible. + This resource is the base resource for several other resources used for package management on specific platforms. While it is possible to use each of these specific resources, we recommend using the **package** resource as often as possible. For more information about specific resources for specific platforms, see the following topics: @@ -81,23 +79,27 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`environment`, `options`, `package_name`, `source`, `timeout`, and `version` are the properties - available to this resource." +- "`environment`, `options`, `package_name`, `source`, `timeout`, and `version` are + the properties available to this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md :install: markdown: Install a package. If a version is specified, install the specified version of the package. (default) - :nothing: - shortcode: resources_common_actions_nothing.md + :upgrade: + markdown: Install a package and ensure that a package is the latest version. + :remove: + markdown: Remove a package. :purge: markdown: Purge a package. This action typically removes the configuration files as well as the package. :reconfig: markdown: Reconfigure a package. This action requires a response file. - :remove: - markdown: Remove a package. - :upgrade: - markdown: Install a package and ensure that a package is the latest version. + :lock: + markdown: + :unlock: + markdown: properties_list: - property: allow_downgrade ruby_type: true, false @@ -125,119 +127,26 @@ properties_list: - property: environment ruby_type: Hash required: false - default_value: "{}" new_in: '18.8' description_list: - markdown: A Hash of environment variables in the form of {'ENV_VARIABLE' => 'VALUE'} to be set before running the command. -- property: flush_cache - ruby_type: Array - required: false - description_list: - - markdown: 'Flush the in-memory cache before or after a Yum operation that - - installs, upgrades, or removes a package. Default value: - - `[ :before, :after ]`. The value may also be a Hash: - - `( { :before => true/false, :after => true/false } )`.' - - shortcode: resources_common_package_yum_cache.md - - markdown: | - As an array: - - ```ruby - yum_package 'some-package' do - #... - - flush_cache [ :before ] - #... - end - ``` - - and as a Hash: - - ```ruby - yum_package 'some-package' do - #... - flush_cache( { :after => true } ) - - #... - end - - note: - markdown: 'The `flush_cache` property does not flush the local Yum cache! Use - - Yum tools---`yum clean headers`, `yum clean packages`, - - `yum clean all`---to clean the local Yum cache.' -- property: gem_binary - ruby_type: String - required: false - description_list: - - markdown: 'A property for the `gem_package` provider that is used to specify a - - gems binary.' -- property: homebrew_user - ruby_type: String, Integer - required: false - description_list: - - markdown: '**homebrew_package** resource only. The name of the Homebrew owner - - to be used by Chef Infra Client when executing a command.' -- property: ignore_failure - ruby_type: true, false - required: false - default_value: 'false' - description_list: - - markdown: Continue running a recipe if a resource fails for any reason. -- property: notifies - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_notifies.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_notifies_syntax.md - property: options - ruby_type: String + ruby_type: String, Array required: false description_list: - - markdown: One (or more) additional options that are passed to the command. + - markdown: One (or more) additional command options that are passed to the command. - property: package_name ruby_type: String, Array required: false description_list: - - markdown: 'The name of the package. Default value: the `name` of the resource - - block. See "Syntax" section above for more information.' -- property: response_file - ruby_type: String - required: false - description_list: - - markdown: '**apt_package** and **dpkg_package** resources only. The direct - - path to the file used to pre-seed a package.' -- property: response_file_variables - ruby_type: Hash - required: false - description_list: - - markdown: '**apt_package** and **dpkg_package** resources only. A Hash of - - response file variables in the form of `{"VARIABLE" => "VALUE"}`.' + - markdown: An optional property to set the package name if it differs from the + resource block's name. - property: source ruby_type: String required: false description_list: - - markdown: Optional. The path to a package in the local file system. - - note: - markdown: 'The AIX platform requires `source` to be a local file system path - - because `installp` does not retrieve packages using HTTP or FTP.' -- property: subscribes - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_subscribes.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_subscribes_syntax.md + - markdown: The optional path to a package on the local file system. - property: timeout ruby_type: String, Integer required: false @@ -249,18 +158,8 @@ properties_list: description_list: - markdown: The version of a package to be installed or upgraded. multi_package_resource: true -resource_directory_recursive_directories: false -resources_common_atomic_update: false -properties_resources_common_windows_security: false -remote_file_prevent_re_downloads: false -remote_file_unc_path: false -ps_credential_helper: false -ruby_style_basics_chef_log: false -debug_recipes_chef_shell: false -resources_common_properties: false -resources_common_notification: false -resources_common_guards: false -common_resource_functionality_multiple_packages: null +target_mode: + support: full examples: | **Install a gems file for use in recipes** diff --git a/data/infra/resources/pacman_package.yaml b/data/infra/resources/pacman_package.yaml index fda11fd5..538128b2 100644 --- a/data/infra/resources/pacman_package.yaml +++ b/data/infra/resources/pacman_package.yaml @@ -22,6 +22,7 @@ syntax_description: | and the default action (`:install`). syntax_full_code_block: |- pacman_package 'name' do + environment Hash options String, Array package_name String, Array source String @@ -29,25 +30,41 @@ syntax_full_code_block: |- version String, Array action Symbol # defaults to :install if not specified end +syntax_properties_list: syntax_full_properties_list: - "`pacman_package` is the resource." - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`options`, `package_name`, `source`, `timeout`, and `version` are the properties - available to this resource." +- "`environment`, `options`, `package_name`, `source`, `timeout`, and `version` are + the properties available to this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md :install: markdown: Install a package. If a version is specified, install the specified version of the package. (default) + :upgrade: + markdown: Install a package and ensure that a package is the latest version. + :remove: + markdown: Remove a package. :purge: markdown: Purge a package. This action typically removes the configuration files as well as the package. - :remove: - markdown: Remove a package. - :upgrade: - markdown: Install a package and ensure that a package is the latest version. + :reconfig: + markdown: + :lock: + markdown: + :unlock: + markdown: properties_list: +- property: environment + ruby_type: Hash + required: false + new_in: '19.0' + description_list: + - markdown: A Hash of environment variables in the form of {'ENV_VARIABLE' => 'VALUE'} + to be set before running the command. - property: options ruby_type: String, Array required: false @@ -74,6 +91,8 @@ properties_list: required: false description_list: - markdown: The version of a package to be installed or upgraded. +target_mode: + support: full examples: | **Install a package** diff --git a/data/infra/resources/paludis_package.yaml b/data/infra/resources/paludis_package.yaml index a9a0eb13..45135e4d 100644 --- a/data/infra/resources/paludis_package.yaml +++ b/data/infra/resources/paludis_package.yaml @@ -20,6 +20,7 @@ syntax_description: 'A **paludis_package** resource block manages a package on a resource_new_in: '12.1' syntax_full_code_block: |- paludis_package 'name' do + environment Hash options String, Array package_name String source String @@ -33,19 +34,35 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`options`, `package_name`, `source`, `timeout`, and `version` are the properties - available to this resource." +- "`environment`, `options`, `package_name`, `source`, `timeout`, and `version` are + the properties available to this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md :install: markdown: Install a package. If a version is specified, install the specified version of the package. (default) - :nothing: - shortcode: resources_common_actions_nothing.md - :remove: - markdown: Remove a package. :upgrade: markdown: Install a package and ensure that a package is the latest version. + :remove: + markdown: Remove a package. + :purge: + markdown: Purge a package. This action typically removes the configuration files + as well as the package. + :reconfig: + markdown: + :lock: + markdown: + :unlock: + markdown: properties_list: +- property: environment + ruby_type: Hash + required: false + new_in: '19.0' + description_list: + - markdown: A Hash of environment variables in the form of {'ENV_VARIABLE' => 'VALUE'} + to be set before running the command. - property: options ruby_type: String, Array required: false @@ -73,6 +90,8 @@ properties_list: required: false description_list: - markdown: The version of a package to be installed or upgraded. +target_mode: + support: full examples: " Install a package\n\n ```ruby\n paludis_package 'name of package'\ \ do\n action :install\n end\n ```\n" diff --git a/data/infra/resources/perl.yaml b/data/infra/resources/perl.yaml index d55cc4c8..731bf13c 100644 --- a/data/infra/resources/perl.yaml +++ b/data/infra/resources/perl.yaml @@ -23,6 +23,7 @@ syntax_description: | `code` specifies the command to run. syntax_full_code_block: |- perl 'name' do + cgroup String code String command String, Array # default value: 'name' unless specified creates String @@ -44,26 +45,43 @@ syntax_full_code_block: |- action Symbol # defaults to :run if not specified end syntax_properties_list: -- '`code` specifies the command to run' syntax_full_properties_list: - "`perl` is the resource." - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`code`, `creates`, `cwd`, `environment`, - `flags`, `group`, `ignore_failure`, `notifies`, `returns`, - `subscribes`,`timeout`, `user`, and `umask` are the properties available to this resource." +- "`cgroup`, `code`, `command`, `creates`, `cwd`, `default_env`, `domain`, `elevated`, + `environment`, `flags`, `group`, `input`, `interpreter`, `live_stream`, `login`, + `password`, `returns`, `timeout`, and `user` are the properties available to this + resource." actions_list: :nothing: shortcode: resources_common_actions_nothing.md :run: markdown: Run a command. (default) properties_list: +- property: cgroup + ruby_type: String + required: false + new_in: '19.0' + description_list: + - markdown: 'Linux only: Run the command within a specific cgroup, creating it if + it doesn''t exist.' - property: code ruby_type: String required: true description_list: - markdown: A quoted string of code to be executed. +- property: command + ruby_type: String, Array + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the command to be executed if it differs + from the resource block's name. + - note: + markdown: Use the **execute** resource to run a single command. Use multiple + **execute** resource blocks to run multiple commands. - property: creates ruby_type: String required: false @@ -74,51 +92,96 @@ properties_list: required: false description_list: - markdown: The current working directory from which the command will be run. +- property: default_env + ruby_type: true, false + required: false + default_value: 'false' + new_in: '14.2' + description_list: + - markdown: When true this enables ENV magic to add path_sanity to the PATH and + force the locale to English+UTF-8 for parsing output +- property: domain + ruby_type: String + required: false + new_in: '12.21' + description_list: + - markdown: 'Windows only: The domain of the user specified by the user property. + If not specified, the username and password specified by the `user` and `password` + properties will be used to resolve that user against the domain in which the + system running Chef Infra Client is joined, or if that system is not joined + to a domain it will resolve the user as a local account on that system. An alternative + way to specify the domain is to leave this property unspecified and specify + the domain as part of the user property.' +- property: elevated + ruby_type: true, false + required: false + default_value: 'false' + new_in: '13.3' + description_list: + - markdown: |- + Determines whether the script will run with elevated permissions to circumvent User Access Control (UAC) from interactively blocking the process. + This will cause the process to be run under a batch login instead of an interactive login. The user running chef-client needs the 'Replace a process level token' and 'Adjust Memory Quotas for a process' permissions. The user that is running the command needs the 'Log on as a batch job' permission. + Because this requires a login, the user and password properties are required. - property: environment ruby_type: Hash required: false description_list: - - markdown: 'A Hash of environment variables in the form of - `({"ENV_VARIABLE" => "VALUE"})`. (These variables must exist for a - command to be run successfully.)' + - markdown: 'A Hash of environment variables in the form of `({''ENV_VARIABLE'' + => ''VALUE''})`. **Note**: These variables must exist for a command to be run + successfully.' - property: flags ruby_type: String required: false description_list: - - markdown: 'One or more command line flags that are passed to the interpreter - when a command is invoked.' + - markdown: One or more command line flags that are passed to the interpreter when + a command is invoked. - property: group ruby_type: String, Integer required: false description_list: - markdown: The group name or group ID that must be changed before running a command. -- property: ignore_failure +- property: input + ruby_type: String + required: false + new_in: '16.2' + description_list: + - markdown: An optional property to set the input sent to the command as STDIN. +- property: interpreter + ruby_type: String + required: false + description_list: + - markdown: +- property: live_stream + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Send the output of the command run by this execute resource block to + the Chef Infra Client event stream. +- property: login ruby_type: true, false required: false + default_value: 'false' + new_in: '17.0' description_list: - - markdown: Continue running a recipe if a resource fails for any reason. (default false) -- property: notifies - ruby_type: Symbol, Chef::Resource\[String\] + - markdown: Use a login shell to run the commands instead of inheriting the existing + execution environment. +- property: password + ruby_type: String required: false + new_in: '12.21' description_list: - - shortcode: resources_common_notification_notifies.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_notifies_syntax.md + - markdown: 'Windows only: The password of the user specified by the user property. + This property is mandatory if user is specified on Windows and may only be specified + if user is specified. The sensitive property for this resource will automatically + be set to true if password is specified.' - property: returns ruby_type: Integer, Array required: false default_value: '0' description_list: - - markdown: 'The return value for a command. This may be an array of accepted - values. An exception is raised when the return value(s) do not - match.' -- property: subscribes - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_subscribes.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_subscribes_syntax.md + - markdown: The return value for a command. This may be an array of accepted values. + An exception is raised when the return value(s) do not match. - property: timeout ruby_type: Integer, String, Float required: false @@ -129,11 +192,12 @@ properties_list: ruby_type: String, Integer required: false description_list: - - markdown: The user name or user ID that should be changed before running a - command. -- property: umask - ruby_type: String, Integer - required: false - description_list: - - markdown: The file mode creation mask, or umask. + - markdown: The user name of the user identity with which to launch the new process. + The user name may optionally be specified with a domain, i.e. `domain\user` + or `user@my.dns.domain.com` via Universal Principal Name (UPN)format. It can + also be specified without a domain simply as user if the domain is instead specified + using the domain property. On Windows only, if this property is specified, the + password property must be specified. +target_mode: + support: full examples: diff --git a/data/infra/resources/plist.yaml b/data/infra/resources/plist.yaml index 7291ae12..0dd17d6b 100644 --- a/data/infra/resources/plist.yaml +++ b/data/infra/resources/plist.yaml @@ -72,6 +72,7 @@ properties_list: required: false description_list: - markdown: +target_mode: examples: | **Show hidden files in finder**: @@ -81,4 +82,4 @@ examples: | entry 'AppleShowAllFiles' value true end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/portage_package.yaml b/data/infra/resources/portage_package.yaml index 2e9bbd94..1da7733b 100644 --- a/data/infra/resources/portage_package.yaml +++ b/data/infra/resources/portage_package.yaml @@ -10,6 +10,7 @@ resource_description_list: - notes_resource_based_on_package: true syntax_full_code_block: |- portage_package 'name' do + environment Hash options String, Array package_name String source String @@ -23,20 +24,35 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`options`, `package_name`, `source`, `timeout`, and `version` are the properties - available to this resource." +- "`environment`, `options`, `package_name`, `source`, `timeout`, and `version` are + the properties available to this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md :install: - markdown: (default) Install a package. If a version is specified, install the specified - version of the package. + markdown: Install a package. If a version is specified, install the specified + version of the package. (default) + :upgrade: + markdown: Install a package and ensure that a package is the latest version. + :remove: + markdown: Remove a package. :purge: markdown: Purge a package. This action typically removes the configuration files as well as the package. - :remove: - markdown: Remove a package. - :upgrade: - markdown: Install a package and ensure that a package is the latest version. + :reconfig: + markdown: + :lock: + markdown: + :unlock: + markdown: properties_list: +- property: environment + ruby_type: Hash + required: false + new_in: '19.0' + description_list: + - markdown: A Hash of environment variables in the form of {'ENV_VARIABLE' => 'VALUE'} + to be set before running the command. - property: options ruby_type: String, Array required: false @@ -64,6 +80,8 @@ properties_list: required: false description_list: - markdown: The version of a package to be installed or upgraded. +target_mode: + support: full examples: " Install a package\n\n ```ruby\n portage_package 'name of package'\ \ do\n action :install\n end\n ```\n" diff --git a/data/infra/resources/powershell_package.yaml b/data/infra/resources/powershell_package.yaml index ce867fac..75e253ee 100644 --- a/data/infra/resources/powershell_package.yaml +++ b/data/infra/resources/powershell_package.yaml @@ -21,6 +21,7 @@ syntax_description: | syntax_full_code_block: |- powershell_package 'name' do allow_clobber true, false # default value: false + environment Hash options String, Array package_name String, Array skip_publisher_check true, false # default value: false @@ -35,14 +36,27 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`allow_clobber`, `options`, `package_name`, `skip_publisher_check`, `source`, `timeout`, - and `version` are the properties available to this resource." +- "`allow_clobber`, `environment`, `options`, `package_name`, `skip_publisher_check`, + `source`, `timeout`, and `version` are the properties available to this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md :install: markdown: Install a package. If a version is specified, install the specified version of the package. (default) + :upgrade: + markdown: Install a package and ensure that a package is the latest version. :remove: markdown: Remove a package. + :purge: + markdown: Purge a package. This action typically removes the configuration files + as well as the package. + :reconfig: + markdown: + :lock: + markdown: + :unlock: + markdown: properties_list: - property: allow_clobber ruby_type: true, false @@ -52,6 +66,13 @@ properties_list: description_list: - markdown: Overrides warning messages about installation conflicts about existing commands on a computer. +- property: environment + ruby_type: Hash + required: false + new_in: '19.0' + description_list: + - markdown: A Hash of environment variables in the form of {'ENV_VARIABLE' => 'VALUE'} + to be set before running the command. - property: options ruby_type: String, Array required: false @@ -85,6 +106,7 @@ properties_list: required: false description_list: - markdown: The version of a package to be installed or upgraded. +target_mode: examples: | **Install a specific version of a package**: diff --git a/data/infra/resources/powershell_package_source.yaml b/data/infra/resources/powershell_package_source.yaml index 77fd6865..1febc106 100644 --- a/data/infra/resources/powershell_package_source.yaml +++ b/data/infra/resources/powershell_package_source.yaml @@ -25,6 +25,7 @@ syntax_full_code_block: |- user String action Symbol # defaults to :register if not specified end +syntax_properties_list: syntax_full_properties_list: - "`powershell_package_source` is the resource." - "`name` is the name given to the resource block." @@ -109,6 +110,7 @@ properties_list: description_list: - markdown: A username that, as part of a credential object, is used to register a repository or other package source with. +target_mode: examples: | **Add a new PowerShell repository that is not trusted and which requires credentials to connect to**: diff --git a/data/infra/resources/powershell_script.yaml b/data/infra/resources/powershell_script.yaml index 0abc1eab..cbcdc37a 100644 --- a/data/infra/resources/powershell_script.yaml +++ b/data/infra/resources/powershell_script.yaml @@ -24,11 +24,13 @@ syntax_description: | ``` syntax_full_code_block: |- powershell_script 'name' do + cgroup String code String command String, Array # default value: 'name' unless specified convert_boolean_return true, false # default value: false creates String cwd String + default_env true, false # default value: false domain String elevated true, false # default value: false environment Hash @@ -37,6 +39,7 @@ syntax_full_code_block: |- input String interpreter String # default value: "powershell" live_stream true, false # default value: false + login true, false # default value: false password String returns Integer, Array # default value: 0 timeout Integer, String, Float # default value: 3600 @@ -50,9 +53,9 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`code`, `command`, `convert_boolean_return`, `creates`, `cwd`, `domain`, - `elevated`, `environment`, `flags`, `group`, `input`, `interpreter`, `live_stream`, - `password`, `returns`, `timeout`, `use_inline_powershell`, and `user` are +- "`cgroup`, `code`, `command`, `convert_boolean_return`, `creates`, `cwd`, `default_env`, + `domain`, `elevated`, `environment`, `flags`, `group`, `input`, `interpreter`, `live_stream`, + `login`, `password`, `returns`, `timeout`, `use_inline_powershell`, and `user` are the properties available to this resource." actions_list: :nothing: @@ -60,6 +63,13 @@ actions_list: :run: markdown: Run a command. (default) properties_list: +- property: cgroup + ruby_type: String + required: false + new_in: '19.0' + description_list: + - markdown: 'Linux only: Run the command within a specific cgroup, creating it if + it doesn''t exist.' - property: code ruby_type: String required: true @@ -72,6 +82,9 @@ properties_list: description_list: - markdown: An optional property to set the command to be executed if it differs from the resource block's name. + - note: + markdown: Use the **execute** resource to run a single command. Use multiple + **execute** resource blocks to run multiple commands. - property: convert_boolean_return ruby_type: true, false required: false @@ -107,6 +120,14 @@ properties_list: required: false description_list: - markdown: The current working directory from which the command will be run. +- property: default_env + ruby_type: true, false + required: false + default_value: 'false' + new_in: '14.2' + description_list: + - markdown: When true this enables ENV magic to add path_sanity to the PATH and + force the locale to English+UTF-8 for parsing output - property: domain ruby_type: String required: false @@ -140,28 +161,12 @@ properties_list: ruby_type: String required: false description_list: - - markdown: | - A string that is passed to the Windows PowerShell command - value (Windows PowerShell 3.0+): - - `-NoLogo` - - `-NonInteractive` - - `-NoProfile` - - `-ExecutionPolicy Bypass` - - `-InputFormat None` + - markdown: A string that is passed to the Windows PowerShell command - property: group ruby_type: String, Integer required: false description_list: - markdown: The group name or group ID that must be changed before running a command. -- property: guard_interpreter - ruby_type: Symbol - required: false - default_value: :powershell_script - description_list: - - markdown: 'When this property is set to `:powershell_script`, the 64-bit - version of the Windows PowerShell shell will be used to evaluate - strings values for the `not_if` and `only_if` properties. Set this - value to `:default` to use the 32-bit version of the cmd.exe shell.' - property: input ruby_type: String required: false @@ -182,12 +187,20 @@ properties_list: description_list: - markdown: Send the output of the command run by this execute resource block to the Chef Infra Client event stream. +- property: login + ruby_type: true, false + required: false + default_value: 'false' + new_in: '17.0' + description_list: + - markdown: Use a login shell to run the commands instead of inheriting the existing + execution environment. - property: password ruby_type: String required: false new_in: '12.21' description_list: - - markdown: '**Windows only** The password of the user specified by the user property. + - markdown: 'Windows only: The password of the user specified by the user property. This property is mandatory if user is specified on Windows and may only be specified if user is specified. The sensitive property for this resource will automatically be set to true if password is specified.' @@ -208,12 +221,11 @@ properties_list: ruby_type: true, false required: false default_value: 'false' - new_in: '18.4' description_list: - - markdown: Use the inline PowerShell DLL rather than shelling out. The PowerShell DLL is faster, - but its semantics could be different from shelling out. In particular, - it doesn't allow for streaming output, nor does it allow for passing custom - parameters to the interpreter. + - markdown: Use inline powershell.dll rather than shelling out - this is faster, + but could have different semantics to the traditional method. In particular, + it does not allow for streaming output, nor does it allow for passing custom + parameters to the interpreter - property: user ruby_type: String, Integer required: false @@ -224,6 +236,7 @@ properties_list: also be specified without a domain simply as user if the domain is instead specified using the domain property. On Windows only, if this property is specified, the password property must be specified. +target_mode: examples: | **Write to an interpolated path**: diff --git a/data/infra/resources/python.yaml b/data/infra/resources/python.yaml index cc90f709..5a975596 100644 --- a/data/infra/resources/python.yaml +++ b/data/infra/resources/python.yaml @@ -20,6 +20,7 @@ syntax_description: | ``` syntax_full_code_block: |- python 'name' do + cgroup String code String command String, Array # default value: 'name' unless specified creates String @@ -46,20 +47,38 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`code`, `command`, `creates`, `cwd`, `default_env`, `domain`, `elevated`, `environment`, - `flags`, `group`, `input`, `interpreter`, `live_stream`, `login`, `password`, `returns`, - `timeout`, and `user` are the properties available to this resource." +- "`cgroup`, `code`, `command`, `creates`, `cwd`, `default_env`, `domain`, `elevated`, + `environment`, `flags`, `group`, `input`, `interpreter`, `live_stream`, `login`, + `password`, `returns`, `timeout`, and `user` are the properties available to this + resource." actions_list: :nothing: shortcode: resources_common_actions_nothing.md :run: markdown: Run a command. (default) properties_list: +- property: cgroup + ruby_type: String + required: false + new_in: '19.0' + description_list: + - markdown: 'Linux only: Run the command within a specific cgroup, creating it if + it doesn''t exist.' - property: code ruby_type: String required: true description_list: - markdown: A quoted string of code to be executed. +- property: command + ruby_type: String, Array + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the command to be executed if it differs + from the resource block's name. + - note: + markdown: Use the **execute** resource to run a single command. Use multiple + **execute** resource blocks to run multiple commands. - property: creates ruby_type: String required: false @@ -70,6 +89,36 @@ properties_list: required: false description_list: - markdown: The current working directory from which the command will be run. +- property: default_env + ruby_type: true, false + required: false + default_value: 'false' + new_in: '14.2' + description_list: + - markdown: When true this enables ENV magic to add path_sanity to the PATH and + force the locale to English+UTF-8 for parsing output +- property: domain + ruby_type: String + required: false + new_in: '12.21' + description_list: + - markdown: 'Windows only: The domain of the user specified by the user property. + If not specified, the username and password specified by the `user` and `password` + properties will be used to resolve that user against the domain in which the + system running Chef Infra Client is joined, or if that system is not joined + to a domain it will resolve the user as a local account on that system. An alternative + way to specify the domain is to leave this property unspecified and specify + the domain as part of the user property.' +- property: elevated + ruby_type: true, false + required: false + default_value: 'false' + new_in: '13.3' + description_list: + - markdown: |- + Determines whether the script will run with elevated permissions to circumvent User Access Control (UAC) from interactively blocking the process. + This will cause the process to be run under a batch login instead of an interactive login. The user running chef-client needs the 'Replace a process level token' and 'Adjust Memory Quotas for a process' permissions. The user that is running the command needs the 'Log on as a batch job' permission. + Because this requires a login, the user and password properties are required. - property: environment ruby_type: Hash required: false @@ -88,19 +137,41 @@ properties_list: required: false description_list: - markdown: The group name or group ID that must be changed before running a command. -- property: ignore_failure +- property: input + ruby_type: String + required: false + new_in: '16.2' + description_list: + - markdown: An optional property to set the input sent to the command as STDIN. +- property: interpreter + ruby_type: String + required: false + description_list: + - markdown: +- property: live_stream + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Send the output of the command run by this execute resource block to + the Chef Infra Client event stream. +- property: login ruby_type: true, false required: false default_value: 'false' + new_in: '17.0' description_list: - - markdown: Continue running a recipe if a resource fails for any reason. -- property: notifies - ruby_type: Symbol, Chef::Resource\[String\] + - markdown: Use a login shell to run the commands instead of inheriting the existing + execution environment. +- property: password + ruby_type: String required: false + new_in: '12.21' description_list: - - shortcode: resources_common_notification_notifies.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_notifies_syntax.md + - markdown: 'Windows only: The password of the user specified by the user property. + This property is mandatory if user is specified on Windows and may only be specified + if user is specified. The sensitive property for this resource will automatically + be set to true if password is specified.' - property: returns ruby_type: Integer, Array required: false @@ -108,24 +179,12 @@ properties_list: description_list: - markdown: The return value for a command. This may be an array of accepted values. An exception is raised when the return value(s) do not match. -- property: subscribes - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_subscribes.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_subscribes_syntax.md - property: timeout ruby_type: Integer, String, Float required: false default_value: '3600' description_list: - markdown: The amount of time (in seconds) a command is to wait before timing out. -- property: umask - ruby_type: String, Integer - required: false - description_list: - - markdown: The file mode creation mask, or umask. - property: user ruby_type: String, Integer required: false @@ -136,4 +195,6 @@ properties_list: also be specified without a domain simply as user if the domain is instead specified using the domain property. On Windows only, if this property is specified, the password property must be specified. +target_mode: + support: full examples: diff --git a/data/infra/resources/reboot.yaml b/data/infra/resources/reboot.yaml index 51b355c8..35cb0308 100644 --- a/data/infra/resources/reboot.yaml +++ b/data/infra/resources/reboot.yaml @@ -24,7 +24,7 @@ syntax_full_properties_list: - "`delay_mins` and `reason` are the properties available to this resource." actions_list: :nothing: - shortcode: resources_common_actions_nothing_default.md + shortcode: resources_common_actions_nothing.md :request_reboot: markdown: Reboot a node at the end of a Chef Infra Client run. :reboot_now: @@ -45,6 +45,8 @@ properties_list: default_value: Reboot by Chef Infra Client description_list: - markdown: A string that describes the reboot action. +target_mode: + support: full examples: | **Reboot a node immediately** diff --git a/data/infra/resources/registry_key.yaml b/data/infra/resources/registry_key.yaml index 3f375572..23f7d475 100644 --- a/data/infra/resources/registry_key.yaml +++ b/data/infra/resources/registry_key.yaml @@ -7,14 +7,12 @@ resource_description_list: Microsoft Windows. - note: markdown: |- - 64-bit versions of Microsoft Windows have a 32-bit compatibility layer in the registry that reflects and redirects certain keys - (and their values) into specific locations (or logical views) of the registry hive. + 64-bit versions of Microsoft Windows have a 32-bit compatibility layer in the registry that reflects and redirects certain keys (and their values) into specific locations (or logical views) of the registry hive. - Chef Infra Client can access any reflected or redirected registry key. The machine architecture of the system on which Chef Infra Client - is running is used as the default (non-redirected) location. Access to the SysWow64 location is redirected must be specified. Typically, - this is only necessary to ensure compatibility with 32-bit applications that are running on a 64-bit operating system. + Chef Infra Client can access any reflected or redirected registry key. The machine architecture of the system on which Chef Infra Client is running is used as the default (non-redirected) location. Access to the SysWow64 location is redirected must be specified. Typically, this is only necessary to ensure compatibility with 32-bit applications that are running on a 64-bit operating system. + + For more information, see: [Registry Reflection](https://docs.microsoft.com/en-us/windows/win32/winprog64/registry-reflection). - For more information, see [Microsoft's documentation on Registry Reflection](https://docs.microsoft.com/en-us/windows/win32/winprog64/registry-reflection). syntax_description: "A **registry_key** resource block creates and deletes registry\ \ keys in\nMicrosoft Windows:\n\n```ruby\nregistry_key 'HKEY_LOCAL_MACHINE\\\\\ ...\\\\System' do\n values [{\n name: 'NewRegistryKeyValue',\n type: :multi_string,\n\ @@ -28,38 +26,23 @@ syntax_description: "A **registry_key** resource block creates and deletes regis \ :create\nend\n```" syntax_full_code_block: |- registry_key 'name' do - architecture Symbol # default value: :machine - key String # default value: 'name' unless specified - only_record_changes true, false # default value: true - recursive true, false # default value: false - values Hash, Array # default value: [] - action Symbol # defaults to :create if not specified + architecture Symbol # default value: :machine + key String # default value: 'name' unless specified + recursive true, false # default value: false + values Hash, Array # default value: [] + action Symbol # defaults to :create if not specified end syntax_properties_list: syntax_full_properties_list: -- '`registry_key` is the resource' -- '`name` is the name of the resource block' -- '`values` is a hash that contains at least one registry key to be created or deleted. - Each registry key in the hash is grouped by brackets in which the `name:`, `type:`, - and `data:` values for that registry key are specified.' -- "`type:` represents the values available for registry keys in Microsoft Windows:\n\ - \ - `:binary` for REG_BINARY\n\ - \ - `:string` for REG_SZ\n\ - \ - `:multi_string` for REG_MULTI_SZ\n\ - \ - `:expand_string` for REG_EXPAND_SZ\n\ - \ - `:dword` for REG_DWORD\n\ - \ - `:dword_big_endian` for REG_DWORD_BIG_ENDIAN\n\ - \ - `:qword` for REG_QWORD\n\ - \
\ - \

Warning

\ - \
:multi_string\ - \ must be an array, even if there is only a single string.
" -- '`action` identifies the steps Chef Infra Client will take to bring the node into - the desired state' -- '`architecture`, `key`, `recursive` and `values` are properties of this resource, - with the Ruby type shown. See "Properties" section below for more information about - all of the properties that may be used with this resource.' +- "`registry_key` is the resource." +- "`name` is the name given to the resource block." +- "`action` identifies which steps Chef Infra Client will take to bring the node into + the desired state." +- "`architecture`, `key`, `recursive`, and `values` are the properties available to + this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md :create: markdown: (default) Create a registry key. If a registry key already exists (but does not match), update that registry key to match. @@ -73,8 +56,6 @@ actions_list: action with the `recursive` attribute will delete the registry key, all of its values and all of the names, types, and data associated with them. This cannot be undone by Chef Infra Client. - :nothing: - shortcode: resources_common_actions_nothing.md properties_list: - property: architecture ruby_type: Symbol @@ -132,14 +113,6 @@ properties_list: `HKEY_CURRENT_CONFIG`, `HKCC`, `HKEY_CLASSES_ROOT`, `HKCR`, `HKEY_USERS`, `HKU`, `HKEY_CURRENT_USER`, and `HKCU`.' -- property: only_record_changes - ruby_type: true, false - required: false - default_value: 'true' - new_in: '18.7' - description_list: - - markdown: Suppress reporting of the current value of sibling values in a registry - key. Setting this to false may result in a large number of values reported. - property: recursive ruby_type: true, false required: false @@ -171,14 +144,9 @@ properties_list: REG_SZ, `:multi_string` for REG_MULTI_SZ, `:expand_string` for REG_EXPAND_SZ, `:dword` for REG_DWORD, `:dword_big_endian` for REG_DWORD_BIG_ENDIAN, or `:qword` for REG_QWORD.' - - warning: - markdown: '`:multi_string` must be an array, even if there is only a single - string.' -resources_common_properties: false -resources_common_notification: false -resources_common_guards: false +target_mode: examples: | - **Create a registry key**: + **Create a registry key** ```ruby registry_key 'HKEY_LOCAL_MACHINE\\path-to-key\\Policies\\System' do @@ -191,20 +159,6 @@ examples: | end ``` - **Suppress reporting the sibling values of the values being updated in a registry key** - - ```ruby - registry 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\CONTROL\Session Manager' do - values [{ - name: 'ProtectionMode', - type: :dword, - data: 1 - }] - only_record_changes true - action :create - end - ``` - **Create a registry key with binary data: "\x01\x02\x03"**: ```ruby @@ -219,9 +173,9 @@ examples: | end ``` - **Create 32-bit key in redirected wow6432 tree**: + **Create 32-bit key in redirected wow6432 tree** - In 64-bit versions of Microsoft Windows, HKEY_LOCAL_MACHINE\SOFTWARE\Example is a re-directed key. In the following examples, because HKEY_LOCAL_MACHINE\SOFTWARE\Example is a 32-bit key, the output will be �Found 32-bit key� if they are run on a version of Microsoft Windows that is 64-bit: + In 64-bit versions of Microsoft Windows, HKEY_LOCAL_MACHINE\SOFTWARE\Example is a re-directed key. In the following examples, because HKEY_LOCAL_MACHINE\SOFTWARE\Example is a 32-bit key, the output will be “Found 32-bit key” if they are run on a version of Microsoft Windows that is 64-bit: ```ruby registry_key 'HKEY_LOCAL_MACHINE\SOFTWARE\Example' do @@ -231,7 +185,7 @@ examples: | end ``` - **Set proxy settings to be the same as those used by #{ChefUtils::Dist::Infra::PRODUCT}**: + **Set proxy settings to be the same as those used by #{ChefUtils::Dist::Infra::PRODUCT}** ```ruby proxy = URI.parse(Chef::Config[:http_proxy]) @@ -244,7 +198,7 @@ examples: | end ``` - **Set the name of a registry key to "(Default)"**: + **Set the name of a registry key to "(Default)"** ```ruby registry_key 'Set (Default) value' do @@ -256,7 +210,7 @@ examples: | end ``` - **Delete a registry key value**: + **Delete a registry key value** ```ruby registry_key 'HKEY_LOCAL_MACHINE\SOFTWARE\path\to\key\AU' do @@ -269,9 +223,9 @@ examples: | end ``` - *Note*: If data is not specified, Chef Infra Client returns error: "Missing data key in RegistryKey values hash". + Note: If data: is not specified, you get an error: Missing data key in RegistryKey values hash - **Delete a registry key and its subkeys, recursively**: + **Delete a registry key and its subkeys, recursively** ```ruby registry_key 'HKCU\SOFTWARE\Policies\path\to\key\Themes' do @@ -280,5 +234,4 @@ examples: | end ``` - *Note*: Be careful when using the `:delete_key` action with the recursive attribute. This will delete the registry key, all of its values - and all of the names, types, and data associated with them. This cannot be undone by `#{ChefUtils::Dist::Infra::PRODUCT}`. + Note: Be careful when using the :delete_key action with the recursive attribute. This will delete the registry key, all of its values and all of the names, types, and data associated with them. This cannot be undone by #{ChefUtils::Dist::Infra::PRODUCT}. diff --git a/data/infra/resources/remote_directory.yaml b/data/infra/resources/remote_directory.yaml index a6e190af..1a8cd0e0 100644 --- a/data/infra/resources/remote_directory.yaml +++ b/data/infra/resources/remote_directory.yaml @@ -25,6 +25,7 @@ syntax_full_code_block: "remote_directory 'name' do\n cookbook String\ false # default value: false\n recursive true, false # default value: true\n \ source String\n action Symbol # defaults to :create if not specified\nend" +syntax_properties_list: syntax_full_properties_list: - "`remote_directory` is the resource." - "`name` is the name given to the resource block." @@ -34,16 +35,16 @@ syntax_full_properties_list: `mode`, `overwrite`, `owner`, `path`, `purge`, `recursive`, and `source` are the properties available to this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md :create: markdown: Create a directory. If a directory already exists (but does not match), update that directory to match. (default) + :delete: + markdown: Delete a directory. :create_if_missing: markdown: Create a directory and/or the contents of that directory, but only if it does not exist. - :delete: - markdown: Delete a directory, including the contents of that directory. - :nothing: - shortcode: resources_common_actions_nothing.md properties_list: - property: cookbook ruby_type: String @@ -72,17 +73,8 @@ properties_list: description_list: - markdown: |- The octal mode for a file. - - **UNIX- and Linux-based systems**: A quoted 3-5 character string that defines the octal mode that is passed to chmod. - For example: `'755'`, `'0755'`, or `'00755'`. If the value is specified as a quoted string, it works exactly as if - the chmod command was passed. If the value is specified as an integer, prepend a zero (0) to the value to ensure - that it is interpreted as an octal number. For example, to assign read, write, and execute rights for all users, use `'0777'` or `'777'`; - for the same rights, plus the sticky bit, use `'01777'` or `'1777'`. - - **Microsoft Windows**: A quoted 3-5 character string that defines the octal mode that is translated into rights for Microsoft Windows security. - For example: `'755'`, `'0755'`, or `'00755'`. Values up to `'0777'` are allowed (no sticky bits) and mean the same in Microsoft Windows as they do in - UNIX, where 4 equals GENERIC_READ, 2 equals GENERIC_WRITE, and 1 equals GENERIC_EXECUTE. This property cannot be used to set `:full_control`. - This property has no effect if not specified, but when it and rights are both specified, the effects are cumulative. + UNIX- and Linux-based systems: A quoted 3-5 character string that defines the octal mode that is passed to chmod. For example: '755', '0755', or 00755. If the value is specified as a quoted string, it works exactly as if the chmod command was passed. If the value is specified as an integer, prepend a zero (0) to the value to ensure that it is interpreted as an octal number. For example, to assign read, write, and execute rights for all users, use '0777' or '777'; for the same rights, plus the sticky bit, use 01777 or '1777'. + Microsoft Windows: A quoted 3-5 character string that defines the octal mode that is translated into rights for Microsoft Windows security. For example: '755', '0755', or 00755. Values up to '0777' are allowed (no sticky bits) and mean the same in Microsoft Windows as they do in UNIX, where 4 equals GENERIC_READ, 2 equals GENERIC_WRITE, and 1 equals GENERIC_EXECUTE. This property cannot be used to set :full_control. This property has no effect if not specified, but when it and rights are both specified, the effects are cumulative. - property: files_owner ruby_type: String, Integer required: false @@ -92,7 +84,7 @@ properties_list: or `user@domain`. If this value is not specified, existing owners remain unchanged and new owner assignments use the current user (when necessary). - property: group - ruby_type: Integer, String + ruby_type: '' required: false description_list: - markdown: 'Use to configure permissions for directories. A string or ID that @@ -104,16 +96,8 @@ properties_list: is not specified, existing groups remain unchanged and new group assignments use the default `POSIX` group (if available).' -- property: inherits - ruby_type: true, false - required: false - default_value: 'true' - description_list: - - markdown: 'Microsoft Windows only. Whether a file inherits rights from its - - parent directory.' - property: mode - ruby_type: Integer, String + ruby_type: '' required: false description_list: - markdown: 'A quoted 3-5 character string that defines the octal mode. For @@ -181,7 +165,7 @@ properties_list: description_list: - markdown: Overwrite a file when it is different. - property: owner - ruby_type: Integer, String + ruby_type: '' required: false description_list: - markdown: 'Use to configure permissions for directories. A string or ID that @@ -213,32 +197,15 @@ properties_list: description_list: - markdown: Create or delete parent directories recursively. For the owner, group, and mode properties, the value of this attribute applies only to the leaf directory. -- property: rights - ruby_type: Integer, String - required: false - description_list: - - markdown: "Microsoft Windows only. The permissions for users and groups in a Microsoft Windows environment. - For example: rights , , where specifies the rights granted to the principal, - is the group or user name, and is a Hash with one (or more) advanced rights options." - property: source ruby_type: String required: false default_value: The base portion of the 'path' property. For example '/some/path/' would be 'path'. description_list: - - markdown: 'The base name of the source file (and inferred from the `path` - - property). For example, in the default value, ''/some/path/'' would be - - ''path''.' -properties_multiple_packages: false -resources_common_atomic_update: false -properties_resources_common_windows_security: false -remote_file_prevent_re_downloads: false -remote_file_unc_path: false -ps_credential_helper: false -ruby_style_basics_chef_log: false -debug_recipes_chef_shell: false + - markdown: The base name of the source file (and inferred from the path property). +target_mode: + support: full examples: " Recursively transfer a directory from a remote location\n\n ```\ \ ruby\n # create up to 10 backups of the files\n # set the files owner different\ diff --git a/data/infra/resources/remote_file.yaml b/data/infra/resources/remote_file.yaml index df994fa1..81bf82f7 100644 --- a/data/infra/resources/remote_file.yaml +++ b/data/infra/resources/remote_file.yaml @@ -16,59 +16,43 @@ syntax_description: "A **remote_file** resource block manages files by using fil \n```ruby\nremote_file '/var/www/customers/public_html/index.html' do\n source\ \ 'http://somesite.com/index.html'\n owner 'web_admin'\n group 'web_admin'\n \ \ mode '0755'\n action :create\nend\n```" -syntax_full_code_block: | - remote_file 'name' do - atomic_update true, false - authentication Symbol # default value: :remote - backup Integer, false # default value: 5 - checksum String - content String - deny_rights - force_unlink true, false # default value: false - ftp_active_mode true, false # default value: false - headers Hash # default value: {} - http_options Hash # default value: {} - manage_symlink_source true, false - path String # default value: 'name' unless specified - remote_domain String - remote_password String - remote_user String - rights - show_progress true, false # default value: false - ssl_verify_mode Symbol - use_conditional_get true, false # default value: true - use_etag true, false # default value: true - use_last_modified true, false # default value: true - action Symbol # defaults to :create if not specified - end +syntax_full_code_block: "remote_file 'name' do\n atomic_update true, + false\n authentication Symbol # default value: :remote\n backup Integer, + false # default value: 5\n checksum String\n content String\n + \ force_unlink true, false # default value: false\n ftp_active_mode + \ true, false # default value: false\n group \n + \ headers Hash # default value: {}\n http_options Hash + # default value: {}\n manage_symlink_source true, false\n mode \n + \ owner \n path String # default value: + 'name' unless specified\n remote_domain String\n remote_password + \ String\n remote_user String\n show_progress true, + false # default value: false\n ssl_verify_mode Symbol\n use_etag true, + false # default value: true\n use_last_modified true, false # default + value: true\n action Symbol # defaults to :create if not specified\nend" syntax_properties_list: -- '`''/var/www/customers/public_html/index.html''` is path to the file to be created' -- '`''http://somesite.com/index.html''` specifies the location of the remote file, - the file is downloaded from there' -- '`owner`, `group`, and `mode` define the permissions' syntax_full_properties_list: - "`remote_file` is the resource." - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`atomic_update`, `authentication`, `backup`, `checksum`, `content`, `deny_rights`, - `force_unlink`, `ftp_active_mode`, `headers`, `http_options`, `manage_symlink_source`, - `path`, `remote_domain`, `remote_password`, `remote_user`, `rights`, `show_progress`, - `ssl_verify_mode`, `use_conditional_get`, `use_etag`, and `use_last_modified` are the properties available +- "`atomic_update`, `authentication`, `backup`, `checksum`, `content`, `force_unlink`, + `ftp_active_mode`, `group`, `headers`, `http_options`, `manage_symlink_source`, + `mode`, `owner`, `path`, `remote_domain`, `remote_password`, `remote_user`, `show_progress`, + `ssl_verify_mode`, `use_etag`, and `use_last_modified` are the properties available to this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md :create: markdown: (default) Create a file. If a file already exists (but does not match), update that file to match. - :create_if_missing: - markdown: Create a file only if the file does not exist. When the file exists, - nothing happens. :delete: markdown: Delete a file. - :nothing: - shortcode: resources_common_actions_nothing.md :touch: markdown: Touch a file. This updates the access (atime) and file modification (mtime) times for a file. (This action may be used with this resource, but is typically only used with the file resource.) + :create_if_missing: + markdown: Create a file only if the file does not exist. When the file exists, + nothing happens. properties_list: - property: atomic_update ruby_type: true, false @@ -128,7 +112,7 @@ properties_list: - markdown: Whether Chef Infra Client uses active or passive FTP. Set to `true` to use active FTP. - property: group - ruby_type: Integer, String + ruby_type: '' required: false description_list: - markdown: 'A string or ID that identifies the group owner by group name or SID, @@ -170,7 +154,6 @@ properties_list: - property: manage_symlink_source ruby_type: true, false required: false - default_value: 'true' description_list: - markdown: Change the behavior of the file resource if it is pointed at a symlink. When this value is set to true, Chef Infra Client will manage the symlink's @@ -181,7 +164,7 @@ properties_list: be changed to false in a future version; setting this explicitly to true or false suppresses this warning. - property: mode - ruby_type: Integer, String + ruby_type: '' required: false description_list: - markdown: 'A quoted 3-5 character string that defines the octal mode. For @@ -213,7 +196,7 @@ properties_list: effect if not specified, but when it and `rights` are both specified, the effects are cumulative.' - property: owner - ruby_type: Integer, String + ruby_type: '' required: false description_list: - markdown: 'A string or ID that identifies the group owner by user name or SID, @@ -226,9 +209,12 @@ properties_list: required: false default_value: The resource block's name description_list: - - markdown: 'The full path to the file, including the file name and its - extension. Default value: the `name` of the resource block. See - "Syntax" section above for more information.' + - markdown: 'The full path to the file, including the file name and its extension. + For example: /files/file.txt. Default value: the name of the resource block. + Microsoft Windows: A path that begins with a forward slash `/` will point to + the root of the current working directory of the Chef Infra Client process. + This path can vary from system to system. Therefore, using a path that begins + with a forward slash `/` is not recommended.' - property: remote_domain ruby_type: String required: false @@ -261,64 +247,6 @@ properties_list: 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: rights - ruby_type: Integer, String - required: false - description_list: - - markdown: 'Microsoft Windows only. The permissions for users and groups in a - Microsoft Windows environment. For example: - `rights , , ` where `` - specifies the rights granted to the principal, `` is the - group or user name, and `` is a Hash with one (or more) - advanced rights options.' -- property: source - ruby_type: String, Array - required: false - description_list: - - markdown: 'Required. The location of the source file. The location of the - source file may be HTTP (`http://`), FTP (`ftp://`), SFTP - (`sftp://`), local (`file:///`), or UNC - (`\\host\share\file.tar.gz`). - There are many ways to define the location of a source file. By - using a path: - ```ruby - source ''http://couchdb.apache.org/img/sketch.png'' - ``` - By using FTP: - ```ruby - source ''ftp://remote_host/path/to/img/sketch.png'' - ``` - By using SFTP: - ```ruby - source ''sftp://username:password@remote_host:22/path/to/img/sketch.png'' - ``` - By using a local path: - ```ruby - source ''file:///path/to/img/sketch.png'' - ``` - By using a Microsoft Windows UNC: - ```ruby - source ''\\\\path\\to\\img\\sketch.png'' - ``` - By using a node attribute: - ```ruby - source node[''nginx''][''foo123''][''url''] - ``` - By using attributes to define paths: - ```ruby - source "#{node[''python''][''url'']}/#{version}/Python-#{version}.tar.bz2" - ``` - By defining multiple paths for multiple locations: - ```ruby - source ''http://seapower/spring.png'', ''http://seapower/has_sprung.png'' - ``` - By defining those same multiple paths as an array: - ```ruby - source [''http://seapower/spring.png'', ''http://seapower/has_sprung.png''] - ``` - When multiple paths are specified, Chef Infra Client will attempt to - download the files in the order listed, stopping after the first - successful download.' - property: show_progress ruby_type: true, false required: false @@ -333,15 +261,6 @@ properties_list: description_list: - markdown: Optional property to override SSL policy. If not specified, uses the SSL policy from `config.rb`. -- property: use_conditional_get - ruby_type: true, false - required: false - default_value: 'true' - description_list: - - markdown: 'Enable conditional HTTP requests by using a conditional `GET` (with - the If-Modified-Since header) or an opaque identifier (ETag). To use - If-Modified-Since headers, `use_last_modified` must also be set to - `true`. To use ETag headers, `use_etag` must also be set to `true`.' - property: use_etag ruby_type: true, false required: false @@ -356,23 +275,8 @@ properties_list: description_list: - markdown: 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: verify - ruby_type: String, Block - required: false - description_list: - - markdown: "A block or a string that returns `true` or `false`. A string, when\n\ - `true` is executed as a system command.\n\nA block is arbitrary Ruby defined\ - \ within the resource block by using\nthe `verify` property. When a block is\ - \ `true`, Chef Infra Client\nwill continue to update the file as appropriate.\n\ - \nFor example, this should return `true`:\n\n```ruby\nremote_file '/tmp/baz'\ - \ do\n verify { 1 == 1 }\nend\n```\n\nThis should return `true`:\n\n```ruby\n\ - remote_file '/etc/nginx.conf' do\n verify 'nginx -t -c %{path}'\nend\n```" - - markdown: "This should return `true`:\n\n```ruby\nremote_file '/tmp/bar' do\n\ - \ verify { 1 == 1}\nend\n```\n\nAnd this should return `true`:\n\n```ruby\n\ - remote_file '/tmp/foo' do\n verify do |path|\n true\n end\nend\n```\n\n\ - Whereas, this should return `false`:\n\n```ruby\nremote_file '/tmp/turtle'\ - \ do\n verify '/usr/bin/false'\nend\n```\n\nIf a string or a block return `false`,\ - \ the Chef Infra Client run\nwill stop and an error is returned." +target_mode: + support: full examples: | **Download a file without checking the checksum**: diff --git a/data/infra/resources/rhsm_errata.yaml b/data/infra/resources/rhsm_errata.yaml index f0ca12f9..93e670e7 100644 --- a/data/infra/resources/rhsm_errata.yaml +++ b/data/infra/resources/rhsm_errata.yaml @@ -34,6 +34,8 @@ properties_list: description_list: - markdown: An optional property for specifying the errata ID if it differs from the resource block's name. +target_mode: + support: full examples: | **Install a package from an Errata ID** diff --git a/data/infra/resources/rhsm_errata_level.yaml b/data/infra/resources/rhsm_errata_level.yaml index dd62ad54..1721b52f 100644 --- a/data/infra/resources/rhsm_errata_level.yaml +++ b/data/infra/resources/rhsm_errata_level.yaml @@ -36,6 +36,8 @@ properties_list: description_list: - markdown: An optional property for specifying the errata level of packages to install if it differs from the resource block's name. +target_mode: + support: full examples: | **Specify an errata level that differs from the resource name** diff --git a/data/infra/resources/rhsm_register.yaml b/data/infra/resources/rhsm_register.yaml index 465ae463..a2625ef6 100644 --- a/data/infra/resources/rhsm_register.yaml +++ b/data/infra/resources/rhsm_register.yaml @@ -10,33 +10,34 @@ resource_description_list: resource_new_in: '14.0' syntax_full_code_block: |- rhsm_register 'name' do - activation_key String, Array - auto_attach true, false # default value: false - base_url String - environment String - force true, false # default value: false - https_for_ca_consumer true, false # default value: false - install_katello_agent true, false # default value: true - organization String - password String - release Float, String - satellite_host String - server_url String - service_level String - system_name String - username String - action Symbol # defaults to :register if not specified + activation_key String, Array + auto_attach true, false # default value: false + base_url String + environment String + force true, false # default value: false + https_for_ca_consumer true, false # default value: false + install_katello_agent true, false # default value: true + not_registered_strings String, Array # default value: ["Overall Status: Unknown", "Overall Status: Not registered"] + organization String + password String + release Float, String + satellite_host String + server_url String + service_level String + system_name String + username String + action Symbol # defaults to :register if not specified end -syntax_properties_list: +syntax_properties_list: syntax_full_properties_list: - "`rhsm_register` is the resource." - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." - "`activation_key`, `auto_attach`, `base_url`, `environment`, `force`, `https_for_ca_consumer`, - `install_katello_agent`, `organization`, `password`, `release`, `satellite_host`, - `server_url`, `service_level`, `system_name`, and `username` are the properties - available to this resource." + `install_katello_agent`, `not_registered_strings`, `organization`, `password`, `release`, + `satellite_host`, `server_url`, `service_level`, `system_name`, and `username` are + the properties available to this resource." actions_list: :nothing: shortcode: resources_common_actions_nothing.md @@ -97,6 +98,14 @@ properties_list: default_value: 'true' description_list: - markdown: If true, the 'katello-agent' RPM will be installed. +- property: not_registered_strings + ruby_type: String, Array + required: false + default_value: '["Overall Status: Unknown", "Overall Status: Not registered"]' + new_in: '18.9' + description_list: + - markdown: The string value(s) that when present in the output of the `subscription-manager + status` command indicate that the system is not registered. - property: organization ruby_type: String required: false @@ -117,7 +126,7 @@ properties_list: description_list: - markdown: Sets the operating system minor release to use for subscriptions for the system. Products and updates are limited to the specified minor release - version. This is used with the `auto_attach` or `activation_key` options. For + version. This is used with the `auto_attach` or `activation_key` options. For example, `release '6.4'` will append `--release=6.4` to the register command. - property: satellite_host ruby_type: String @@ -153,6 +162,8 @@ properties_list: - markdown: The username to use when registering. This property is not applicable if using an activation key. If specified, password and environment properties are also required. +target_mode: + support: full examples: | **Register a node with RHSM** diff --git a/data/infra/resources/rhsm_repo.yaml b/data/infra/resources/rhsm_repo.yaml index cfd627fb..ed6b90a3 100644 --- a/data/infra/resources/rhsm_repo.yaml +++ b/data/infra/resources/rhsm_repo.yaml @@ -35,6 +35,8 @@ properties_list: description_list: - markdown: An optional property for specifying the repository name if it differs from the resource block's name. +target_mode: + support: full examples: | **Enable an RHSM repository** diff --git a/data/infra/resources/rhsm_subscription.yaml b/data/infra/resources/rhsm_subscription.yaml index 1a92c4c1..cbb6e848 100644 --- a/data/infra/resources/rhsm_subscription.yaml +++ b/data/infra/resources/rhsm_subscription.yaml @@ -36,4 +36,6 @@ properties_list: description_list: - markdown: An optional property for specifying the Pool ID if it differs from the resource block's name. +target_mode: + support: full examples: diff --git a/data/infra/resources/route.yaml b/data/infra/resources/route.yaml index d1c1fcfe..591fcecf 100644 --- a/data/infra/resources/route.yaml +++ b/data/infra/resources/route.yaml @@ -30,12 +30,12 @@ syntax_full_properties_list: - "`comment`, `device`, `gateway`, `metric`, `netmask`, `route_type`, and `target` are the properties available to this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md :add: markdown: (default) Add a route. :delete: markdown: Delete a route. - :nothing: - shortcode: resources_common_actions_nothing.md properties_list: - property: comment ruby_type: String @@ -75,4 +75,6 @@ properties_list: default_value: The resource block's name description_list: - markdown: The IP address of the target route. +target_mode: + support: full examples: diff --git a/data/infra/resources/rpm_package.yaml b/data/infra/resources/rpm_package.yaml index 030c6996..3a00be6d 100644 --- a/data/infra/resources/rpm_package.yaml +++ b/data/infra/resources/rpm_package.yaml @@ -24,18 +24,27 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`allow_downgrade`, `environment`, `options`, `package_name`, `source`, `timeout`, and `version` - are the properties available to this resource." +- "`allow_downgrade`, `environment`, `options`, `package_name`, `source`, `timeout`, + and `version` are the properties available to this resource." actions_list: :nothing: shortcode: resources_common_actions_nothing.md :install: markdown: Install a package. If a version is specified, install the specified version of the package. (default) - :remove: - markdown: Remove a package. :upgrade: markdown: Install a package and ensure that a package is the latest version. + :remove: + markdown: Remove a package. + :purge: + markdown: Purge a package. This action typically removes the configuration files + as well as the package. + :reconfig: + markdown: + :lock: + markdown: + :unlock: + markdown: properties_list: - property: allow_downgrade ruby_type: true, false @@ -77,6 +86,8 @@ properties_list: required: false description_list: - markdown: The version of a package to be installed or upgraded. +target_mode: + support: full examples: " Install a package\n\n ```ruby\n rpm_package 'name of package'\ \ do\n action :install\n end\n ```\n" diff --git a/data/infra/resources/ruby.yaml b/data/infra/resources/ruby.yaml index 15cd080b..bc4eebbf 100644 --- a/data/infra/resources/ruby.yaml +++ b/data/infra/resources/ruby.yaml @@ -1,5 +1,6 @@ --- resource_reference: true +resources_common_guards: true resource: ruby resource_description_list: - markdown: Use the **ruby** resource to execute scripts using the Ruby interpreter. @@ -18,43 +19,65 @@ syntax_description: | ``` syntax_full_code_block: |- ruby 'name' do + cgroup String code String + command String, Array # default value: 'name' unless specified creates String cwd String + default_env true, false # default value: false + domain String + elevated true, false # default value: false environment Hash flags String group String, Integer - ignore_failure True, False - notifies Symbol + input String + interpreter String + live_stream true, false # default value: false + login true, false # default value: false + password String returns Integer, Array # default value: 0 - subscribes Symbol timeout Integer, String, Float # default value: 3600 user String, Integer - umask String, Integer action Symbol # defaults to :run if not specified end syntax_properties_list: -- '`cwd` specifies the directory from which the command is run' -- '`code` specifies the command to run' syntax_full_properties_list: - "`ruby` is the resource." - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`code`, `creates`, `cwd`, `environment`, `flags`, - `group`, `ignore_failure`, `notifies`, `returns`, `subscribes` - `timeout`, `user`, and `umask` are the properties available to this resource." +- "`cgroup`, `code`, `command`, `creates`, `cwd`, `default_env`, `domain`, `elevated`, + `environment`, `flags`, `group`, `input`, `interpreter`, `live_stream`, `login`, + `password`, `returns`, `timeout`, and `user` are the properties available to this + resource." actions_list: :nothing: shortcode: resources_common_actions_nothing.md :run: markdown: Run a command. (default) properties_list: +- property: cgroup + ruby_type: String + required: false + new_in: '19.0' + description_list: + - markdown: 'Linux only: Run the command within a specific cgroup, creating it if + it doesn''t exist.' - property: code ruby_type: String required: true description_list: - markdown: A quoted string of code to be executed. +- property: command + ruby_type: String, Array + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the command to be executed if it differs + from the resource block's name. + - note: + markdown: Use the **execute** resource to run a single command. Use multiple + **execute** resource blocks to run multiple commands. - property: creates ruby_type: String required: false @@ -65,6 +88,36 @@ properties_list: required: false description_list: - markdown: The current working directory from which the command will be run. +- property: default_env + ruby_type: true, false + required: false + default_value: 'false' + new_in: '14.2' + description_list: + - markdown: When true this enables ENV magic to add path_sanity to the PATH and + force the locale to English+UTF-8 for parsing output +- property: domain + ruby_type: String + required: false + new_in: '12.21' + description_list: + - markdown: 'Windows only: The domain of the user specified by the user property. + If not specified, the username and password specified by the `user` and `password` + properties will be used to resolve that user against the domain in which the + system running Chef Infra Client is joined, or if that system is not joined + to a domain it will resolve the user as a local account on that system. An alternative + way to specify the domain is to leave this property unspecified and specify + the domain as part of the user property.' +- property: elevated + ruby_type: true, false + required: false + default_value: 'false' + new_in: '13.3' + description_list: + - markdown: |- + Determines whether the script will run with elevated permissions to circumvent User Access Control (UAC) from interactively blocking the process. + This will cause the process to be run under a batch login instead of an interactive login. The user running chef-client needs the 'Replace a process level token' and 'Adjust Memory Quotas for a process' permissions. The user that is running the command needs the 'Log on as a batch job' permission. + Because this requires a login, the user and password properties are required. - property: environment ruby_type: Hash required: false @@ -83,19 +136,41 @@ properties_list: required: false description_list: - markdown: The group name or group ID that must be changed before running a command. -- property: ignore_failure +- property: input + ruby_type: String + required: false + new_in: '16.2' + description_list: + - markdown: An optional property to set the input sent to the command as STDIN. +- property: interpreter + ruby_type: String + required: false + description_list: + - markdown: +- property: live_stream + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Send the output of the command run by this execute resource block to + the Chef Infra Client event stream. +- property: login ruby_type: true, false required: false default_value: 'false' + new_in: '17.0' description_list: - - markdown: Continue running a recipe if a resource fails for any reason. -- property: notifies - ruby_type: Symbol, Chef::Resource\[String\] + - markdown: Use a login shell to run the commands instead of inheriting the existing + execution environment. +- property: password + ruby_type: String required: false + new_in: '12.21' description_list: - - shortcode: resources_common_notification_notifies.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_notifies_syntax.md + - markdown: 'Windows only: The password of the user specified by the user property. + This property is mandatory if user is specified on Windows and may only be specified + if user is specified. The sensitive property for this resource will automatically + be set to true if password is specified.' - property: returns ruby_type: Integer, Array required: false @@ -103,28 +178,23 @@ properties_list: description_list: - markdown: The return value for a command. This may be an array of accepted values. An exception is raised when the return value(s) do not match. -- property: subscribes - ruby_type: Symbol, Chef::Resource\[String\] - required: false - description_list: - - shortcode: resources_common_notification_subscribes.md - - shortcode: resources_common_notification_timers.md - - shortcode: resources_common_notification_subscribes_syntax.md - property: timeout ruby_type: Integer, String, Float required: false default_value: '3600' description_list: - markdown: The amount of time (in seconds) a command is to wait before timing out. -- property: umask - ruby_type: String, Integer - required: false - description_list: - - markdown: The file mode creation mask, or umask. - property: user ruby_type: String, Integer required: false description_list: - - markdown: 'The user name or user ID that should be changed before running a - command.' + - markdown: The user name of the user identity with which to launch the new process. + The user name may optionally be specified with a domain, i.e. `domain\user` + or `user@my.dns.domain.com` via Universal Principal Name (UPN)format. It can + also be specified without a domain simply as user if the domain is instead specified + using the domain property. On Windows only, if this property is specified, the + password property must be specified. +target_mode: + support: full + description: Needs Ruby interpreter installed on target node. examples: diff --git a/data/infra/resources/ruby_block.yaml b/data/infra/resources/ruby_block.yaml index f457e944..098d8e60 100644 --- a/data/infra/resources/ruby_block.yaml +++ b/data/infra/resources/ruby_block.yaml @@ -12,33 +12,24 @@ syntax_description: "A **ruby_block** resource block executes a block of arbitra /etc/chef/client.rb\")\n end\n action :run\nend\n```" syntax_full_code_block: |- ruby_block 'name' do - block Block block_name String # default value: 'name' unless specified action Symbol # defaults to :run if not specified end syntax_properties_list: syntax_full_properties_list: -- '`ruby_block` is the resource.' -- '`name` is the name given to the resource block.' -- '`block` is the block of Ruby code to be executed.' -- '`action` identifies which steps Chef Infra Client will take to bring the node into - the desired state.' -- '`block` and `block_name` are properties of this resource, with the Ruby type shown. - See "Properties" section below for more information about all of the properties - that may be used with this resource.' +- "`ruby_block` is the resource." +- "`name` is the name given to the resource block." +- "`action` identifies which steps Chef Infra Client will take to bring the node into + the desired state." +- "`block_name` is the property available to this resource." actions_list: - :create: - markdown: The same as `:run`. :nothing: shortcode: resources_common_actions_nothing.md :run: markdown: "Run a Ruby block. (default)" + :create: + markdown: The same as `:run`. properties_list: -- property: block - ruby_type: block - required: false - description_list: - - markdown: A block of Ruby code. - property: block_name ruby_type: String required: false @@ -47,6 +38,10 @@ properties_list: - markdown: 'The name of the Ruby block. Default value: the `name` of the resource block. See "Syntax" section above for more information.' +target_mode: + support: full + description: Ruby code will be run locally and not on the target node. Use the **ruby** + resource for this. examples: | **Reload Chef Infra Client configuration data** diff --git a/data/infra/resources/script.yaml b/data/infra/resources/script.yaml index d8b0ab01..11038e5b 100644 --- a/data/infra/resources/script.yaml +++ b/data/infra/resources/script.yaml @@ -51,18 +51,24 @@ syntax_properties_list: ``` syntax_full_code_block: |- script 'name' do + cgroup String code String + command String, Array # default value: 'name' unless specified creates String cwd String + default_env true, false # default value: false domain String + elevated true, false # default value: false environment Hash flags String group String, Integer + input String interpreter String + live_stream true, false # default value: false + login true, false # default value: false password String returns Integer, Array # default value: 0 timeout Integer, String, Float # default value: 3600 - umask String, Integer user String, Integer action Symbol # defaults to :run if not specified end @@ -71,20 +77,38 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`code`, `creates`, `cwd`, `domain`, `environment`, - `flags`, `group`, `interpreter`, `password`, `returns`, - `timeout`, `umask`, and `user` are the properties available to this resource." +- "`cgroup`, `code`, `command`, `creates`, `cwd`, `default_env`, `domain`, `elevated`, + `environment`, `flags`, `group`, `input`, `interpreter`, `live_stream`, `login`, + `password`, `returns`, `timeout`, and `user` are the properties available to this + resource." actions_list: :nothing: shortcode: resources_common_actions_nothing.md :run: markdown: Run a command. (default) properties_list: +- property: cgroup + ruby_type: String + required: false + new_in: '19.0' + description_list: + - markdown: 'Linux only: Run the command within a specific cgroup, creating it if + it doesn''t exist.' - property: code ruby_type: String required: true description_list: - markdown: A quoted string of code to be executed. +- property: command + ruby_type: String, Array + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the command to be executed if it differs + from the resource block's name. + - note: + markdown: Use the **execute** resource to run a single command. Use multiple + **execute** resource blocks to run multiple commands. - property: creates ruby_type: String required: false @@ -95,21 +119,36 @@ properties_list: required: false description_list: - markdown: The current working directory from which the command will be run. +- property: default_env + ruby_type: true, false + required: false + default_value: 'false' + new_in: '14.2' + description_list: + - markdown: When true this enables ENV magic to add path_sanity to the PATH and + force the locale to English+UTF-8 for parsing output - property: domain ruby_type: String required: false + new_in: '12.21' + description_list: + - markdown: 'Windows only: The domain of the user specified by the user property. + If not specified, the username and password specified by the `user` and `password` + properties will be used to resolve that user against the domain in which the + system running Chef Infra Client is joined, or if that system is not joined + to a domain it will resolve the user as a local account on that system. An alternative + way to specify the domain is to leave this property unspecified and specify + the domain as part of the user property.' +- property: elevated + ruby_type: true, false + required: false + default_value: 'false' + new_in: '13.3' description_list: - - markdown: '*Windows only*: The domain of the user user specified by the user property. Default value: nil. If not specified, the user name and - password specified by the user and - password properties will be used to - resolve that user against the domain in which the system running - Chef client is joined, or if that system is not joined to a domain - it will resolve the user as a local account on that system. An - alternative way to specify the domain is to leave this property - unspecified and specify the domain as part of the user property.' + - markdown: |- + Determines whether the script will run with elevated permissions to circumvent User Access Control (UAC) from interactively blocking the process. + This will cause the process to be run under a batch login instead of an interactive login. The user running chef-client needs the 'Replace a process level token' and 'Adjust Memory Quotas for a process' permissions. The user that is running the command needs the 'Log on as a batch job' permission. + Because this requires a login, the user and password properties are required. - property: environment ruby_type: Hash required: false @@ -128,11 +167,32 @@ properties_list: required: false description_list: - markdown: The group name or group ID that must be changed before running a command. +- property: input + ruby_type: String + required: false + new_in: '16.2' + description_list: + - markdown: An optional property to set the input sent to the command as STDIN. - property: interpreter ruby_type: String required: false description_list: - markdown: The script interpreter to use during code execution. +- property: live_stream + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Send the output of the command run by this execute resource block to + the Chef Infra Client event stream. +- property: login + ruby_type: true, false + required: false + default_value: 'false' + new_in: '17.0' + description_list: + - markdown: Use a login shell to run the commands instead of inheriting the existing + execution environment. - property: password ruby_type: String required: false @@ -155,11 +215,6 @@ properties_list: default_value: '3600' description_list: - markdown: The amount of time (in seconds) a command is to wait before timing out. -- property: umask - ruby_type: String, Integer - required: false - description_list: - - markdown: The file mode creation mask, or umask. - property: user ruby_type: String, Integer required: false @@ -170,6 +225,9 @@ properties_list: also be specified without a domain simply as user if the domain is instead specified using the domain property. On Windows only, if this property is specified, the password property must be specified. +target_mode: + support: full + description: Needs interpreter installed on target node. examples: " Use a named provider to run a script\n\n ```ruby\n bash 'install_something'\ \ do\n user 'root'\n cwd '/tmp'\n code <<-EOH\n wget http://www.example.com/tarball.tar.gz\n\ diff --git a/data/infra/resources/selinux_boolean.yaml b/data/infra/resources/selinux_boolean.yaml index cf7f8c0a..b837b07e 100644 --- a/data/infra/resources/selinux_boolean.yaml +++ b/data/infra/resources/selinux_boolean.yaml @@ -5,7 +5,7 @@ resources_common_notification: true resources_common_properties: true resource: selinux_boolean resource_description_list: -- markdown: Use the **selinux_boolean** resource to set SELinux boolean values. +- markdown: Use **selinux_boolean** resource to set SELinux boolean values. resource_new_in: '18.0' syntax_full_code_block: |- selinux_boolean 'name' do @@ -30,7 +30,7 @@ properties_list: - property: boolean ruby_type: String required: false - default_value: The resource block's name. + default_value: The resource block's name description_list: - markdown: SELinux boolean to set. - property: persistent @@ -38,13 +38,15 @@ properties_list: required: false default_value: 'true' description_list: - - markdown: Set to `true` for value setting to survive reboot. + - markdown: Set to true for value setting to survive reboot. - property: value ruby_type: Integer, String, true, false required: true - allowed_values: '"on", "off", true, false, 0, 1' + allowed_values: '"off", "on"' description_list: - markdown: SELinux boolean value. +target_mode: + support: full examples: | **Set ssh_keysign to true**: diff --git a/data/infra/resources/selinux_fcontext.yaml b/data/infra/resources/selinux_fcontext.yaml index dc5fa2bb..d8671740 100644 --- a/data/infra/resources/selinux_fcontext.yaml +++ b/data/infra/resources/selinux_fcontext.yaml @@ -15,7 +15,7 @@ syntax_full_code_block: |- secontext String action Symbol # defaults to :manage if not specified end -syntax_properties_list: +syntax_properties_list: syntax_full_properties_list: - "`selinux_fcontext` is the resource." - "`name` is the name given to the resource block." @@ -36,12 +36,12 @@ actions_list: :modify: markdown: Update the file context if previously set. :delete: - markdown: 'Removes the file context if set.' + markdown: 'Removes the file context if set. ' properties_list: - property: file_spec ruby_type: String required: false - default_value: The resource block's name. + default_value: The resource block's name description_list: - markdown: Path to or regex matching the files or directories to label. - property: file_type @@ -56,8 +56,10 @@ properties_list: required: true description_list: - markdown: SELinux context to assign. +target_mode: + support: full examples: | - **Allow http servers (e.g. nginx/apache) to modify Moodle files**: + **Allow http servers (e.g. nginx/apache) to modify moodle files**: ```ruby selinux_fcontext '/var/www/moodle(/.*)?' do diff --git a/data/infra/resources/selinux_install.yaml b/data/infra/resources/selinux_install.yaml index dac32ea5..5f6c6063 100644 --- a/data/infra/resources/selinux_install.yaml +++ b/data/infra/resources/selinux_install.yaml @@ -5,8 +5,8 @@ resources_common_notification: true resources_common_properties: true resource: selinux_install resource_description_list: -- markdown: Use the **selinux_install** resource to encapsulate the set of SELinux packages - to install in order to manage SELinux. It also ensures the directory `/etc/selinux` +- markdown: Use **selinux_install** resource to encapsulates the set of selinux packages + to install in order to manage selinux. It also ensures the directory `/etc/selinux` is created. resource_new_in: '18.0' syntax_full_code_block: |- @@ -37,6 +37,8 @@ properties_list: default_value: lazy default description_list: - markdown: SELinux packages for system. +target_mode: + support: full examples: | **Default installation**: @@ -53,7 +55,6 @@ examples: | ``` **Uninstall** - ```ruby selinux_install 'example' do action :remove diff --git a/data/infra/resources/selinux_login.yaml b/data/infra/resources/selinux_login.yaml index 5f2d13ea..fef00bb9 100644 --- a/data/infra/resources/selinux_login.yaml +++ b/data/infra/resources/selinux_login.yaml @@ -15,7 +15,7 @@ syntax_full_code_block: |- user String action Symbol # defaults to :manage if not specified end -syntax_properties_list: +syntax_properties_list: syntax_full_properties_list: - "`selinux_login` is the resource." - "`name` is the name given to the resource block." @@ -46,12 +46,14 @@ properties_list: ruby_type: String required: false description_list: - - markdown: Multi-Level Security (MLS) or Multi-Category Security (MCS) range for the SELinux user. + - markdown: MLS/MCS security range for the SELinux user. - property: user ruby_type: String required: false description_list: - markdown: SELinux user to be mapped. +target_mode: + support: full examples: | **Manage test OS user mapping with a range of s0 and associated SELinux user test_u**: diff --git a/data/infra/resources/selinux_module.yaml b/data/infra/resources/selinux_module.yaml index 8e0f07eb..88518502 100644 --- a/data/infra/resources/selinux_module.yaml +++ b/data/infra/resources/selinux_module.yaml @@ -5,7 +5,7 @@ resources_common_notification: true resources_common_properties: true resource: selinux_module resource_description_list: -- markdown: Use the **selinux_module** module resource to create an SELinux policy module +- markdown: Use **selinux_module** module resource to create an SELinux policy module from a cookbook file or content provided as a string. resource_new_in: '18.0' syntax_full_code_block: |- @@ -52,12 +52,12 @@ properties_list: ruby_type: String required: false description_list: - - markdown: Cookbook to source module source file from (if it is not located + - markdown: Cookbook to source from module source file from(if it is not located in the current cookbook). The default value is the current cookbook. - property: module_name ruby_type: String required: false - default_value: The resource block's name. + default_value: The resource block's name description_list: - markdown: Override the module name. - property: source @@ -65,8 +65,10 @@ properties_list: required: false description_list: - markdown: Module source file name. +target_mode: + support: full examples: | - **Create an SElinux module from a TE file located at `files` directory of your cookbook**: + **Creating SElinux module from .te file located at `files` directory of your cookbook.**: ```ruby selinux_module 'my_policy_module' do diff --git a/data/infra/resources/selinux_permissive.yaml b/data/infra/resources/selinux_permissive.yaml index 4e1c05f3..a762b837 100644 --- a/data/infra/resources/selinux_permissive.yaml +++ b/data/infra/resources/selinux_permissive.yaml @@ -14,7 +14,7 @@ syntax_full_code_block: |- context String # default value: 'name' unless specified action Symbol # defaults to :add if not specified end -syntax_properties_list: +syntax_properties_list: syntax_full_properties_list: - "`selinux_permissive` is the resource." - "`name` is the name given to the resource block." @@ -25,9 +25,9 @@ actions_list: :nothing: shortcode: resources_common_actions_nothing.md :add: - markdown: Make a domain permissive, unless already set. (default) + markdown: Add a permissive, unless already set. (default) :delete: - markdown: Stop a domain from being permissive, if set. + markdown: Remove a permissive, if set. properties_list: - property: context ruby_type: String @@ -35,6 +35,8 @@ properties_list: default_value: The resource block's name description_list: - markdown: The SELinux context to permit. +target_mode: + support: full examples: | **Disable enforcement on Apache**: diff --git a/data/infra/resources/selinux_port.yaml b/data/infra/resources/selinux_port.yaml index 43d826a4..aea73d64 100644 --- a/data/infra/resources/selinux_port.yaml +++ b/data/infra/resources/selinux_port.yaml @@ -40,7 +40,7 @@ properties_list: - property: port ruby_type: Integer, String required: false - default_value: The resource block's name. + default_value: The resource block's name description_list: - markdown: Port to modify. - property: protocol @@ -54,8 +54,10 @@ properties_list: required: true description_list: - markdown: SELinux context to assign to the port. +target_mode: + support: full examples: | - **Allow Nginx or Apache to bind to port 5678 by giving it the `http_port_t` context**: + **Allow nginx/apache to bind to port 5678 by giving it the http_port_t context**: ```ruby selinux_port '5678' do diff --git a/data/infra/resources/selinux_state.yaml b/data/infra/resources/selinux_state.yaml index 8a45a77f..31e5f71f 100644 --- a/data/infra/resources/selinux_state.yaml +++ b/data/infra/resources/selinux_state.yaml @@ -5,7 +5,7 @@ resources_common_notification: true resources_common_properties: true resource: selinux_state resource_description_list: -- markdown: Use the **selinux_state** resource to manage the SELinux state on a system. +- markdown: Use **selinux_state** resource to manages the SELinux state on the system. It does this by using the `setenforce` command and rendering the `/etc/selinux/config` file from a template. resource_new_in: '18.0' @@ -17,7 +17,7 @@ syntax_full_code_block: |- policy String action Symbol # defaults to :enforcing if not specified end -syntax_properties_list: +syntax_properties_list: syntax_full_properties_list: - "`selinux_state` is the resource." - "`name` is the name given to the resource block." @@ -47,7 +47,7 @@ properties_list: required: false default_value: "/etc/selinux/config" description_list: - - markdown: Path to the SELinux config file on disk. + - markdown: Path to SELinux config file on disk. - property: persistent ruby_type: true, false required: false @@ -61,6 +61,8 @@ properties_list: allowed_values: '"default", "minimum", "mls", "src", "strict", "targeted"' description_list: - markdown: SELinux policy type. +target_mode: + support: full examples: | **Set SELinux state to permissive**: @@ -79,7 +81,6 @@ examples: | ``` **Set SELinux state to disabled**: - ```ruby selinux_state 'disabled' do action :disabled diff --git a/data/infra/resources/selinux_user.yaml b/data/infra/resources/selinux_user.yaml index e6c776cc..3ea5ad45 100644 --- a/data/infra/resources/selinux_user.yaml +++ b/data/infra/resources/selinux_user.yaml @@ -39,12 +39,12 @@ properties_list: ruby_type: String required: false description_list: - - markdown: Multi-Level Security (MLS) or Multi-Category Security (MCS) security level for the SELinux user. + - markdown: MLS/MCS security level for the SELinux user. - property: range ruby_type: String required: false description_list: - - markdown: Multi-Level Security (MLS) or Multi-Category Security (MCS) security range for the SELinux user. + - markdown: MLS/MCS security range for the SELinux user. - property: roles ruby_type: Array required: false @@ -57,11 +57,13 @@ properties_list: description_list: - markdown: An optional property to set the SELinux user value if it differs from the resource block's name. +target_mode: + support: full examples: | - **Set an SELinux user with a level and range of `s0` and roles `sysadm_r` and `staff_r`**: + **Manage test_u SELinux user with a level and range of s0 and roles sysadm_r and staff_r**: ```ruby - selinux_user 'username' do + selinux_user 'test_u' do level 's0' range 's0' roles %w(sysadm_r staff_r) diff --git a/data/infra/resources/service.yaml b/data/infra/resources/service.yaml index ff4eb1b3..1ba0591e 100644 --- a/data/infra/resources/service.yaml +++ b/data/infra/resources/service.yaml @@ -25,7 +25,7 @@ syntax_full_code_block: |- user String action Symbol # defaults to :nothing if not specified end -syntax_properties_list: +syntax_properties_list: syntax_full_properties_list: - "`service` is the resource." - "`name` is the name given to the resource block." @@ -54,6 +54,14 @@ actions_list: markdown: Start a service, and keep it running until stopped or disabled. :stop: markdown: Stop a service. + :restart: + markdown: + :reload: + markdown: + :mask: + markdown: + :unmask: + markdown: properties_list: - property: init_command ruby_type: String @@ -89,8 +97,8 @@ properties_list: - markdown: Debian platform only. The relative priority of the program for start and shutdown ordering. May be an integer or a Hash. An integer is used to define the start run levels; stop run levels are then 100-integer. A Hash is used to - define values for specific run levels. For example, `{ 2 => [:start, 20], 3 => - [:stop, 55] }` will set a priority of twenty for run level two and a priority + define values for specific run levels. For example, { 2 => [:start, 20], 3 => + [:stop, 55] } will set a priority of twenty for run level two and a priority of fifty-five for run level three. - property: reload_command ruby_type: String, false @@ -132,20 +140,20 @@ properties_list: - property: supports ruby_type: Hash required: false - default_value: '{"restart" => nil, "reload" => nil, "status" => nil}' + default_value: '{"restart"=>nil, "reload"=>nil, "status"=>nil}' description_list: - markdown: 'A list of properties that controls how Chef Infra Client is to attempt - to manage a service: `:restart`, `:reload`, `:status`. For `:restart`, the init script - or other service provider can use a restart command; if `:restart` is not specified, - the Chef Infra Client attempts to stop and then start a service. For :reload, the - init script or other service provider can use a reload command. For `:status`, + to manage a service: :restart, :reload, :status. For :restart, the init script + or other service provider can use a restart command; if :restart is not specified, + the chef-client attempts to stop and then start a service. For :reload, the + init script or other service provider can use a reload command. For :status, the init script or other service provider can use a status command to determine - if the service is running; if `:status` is not specified, the Chef Infra Client attempts + if the service is running; if :status is not specified, the chef-client attempts to match the service_name against the process table as a regular expression, - unless a pattern is specified as a parameter property. Default value: `{ restart: - false, reload: false, status: false }` for all platforms (except for the Red - Hat platform family, which defaults to `{ restart: false, reload: false, status: - true }`.)' + unless a pattern is specified as a parameter property. Default value: { restart: + false, reload: false, status: false } for all platforms (except for the Red + Hat platform family, which defaults to { restart: false, reload: false, status: + true }.)' - property: timeout ruby_type: Integer required: false @@ -158,6 +166,10 @@ properties_list: new_in: '12.21' description_list: - markdown: 'systemd only: A username to run the service under.' +target_mode: + support: full + introduced: '15.1' + updated: '19.0' examples: " Start a service\n\n ```ruby\n service 'example_service' do\n \ \ action :start\n end\n ```\n\n Start a service, enable it\n\n ```ruby\n\ diff --git a/data/infra/resources/smartos_package.yaml b/data/infra/resources/smartos_package.yaml index 346bfc35..a77a12f7 100644 --- a/data/infra/resources/smartos_package.yaml +++ b/data/infra/resources/smartos_package.yaml @@ -10,6 +10,7 @@ resource_description_list: - notes_resource_based_on_package: true syntax_full_code_block: |- smartos_package 'name' do + environment Hash options String, Array package_name String source String @@ -23,19 +24,35 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`options`, `package_name`, `source`, `timeout`, and `version` are the properties - available to this resource." +- "`environment`, `options`, `package_name`, `source`, `timeout`, and `version` are + the properties available to this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md :install: markdown: Install a package. If a version is specified, install the specified version of the package. (default) - :nothing: - shortcode: resources_common_actions_nothing.md - :remove: - markdown: Remove a package. :upgrade: markdown: Install a package and ensure that a package is the latest version. + :remove: + markdown: Remove a package. + :purge: + markdown: Purge a package. This action typically removes the configuration files + as well as the package. + :reconfig: + markdown: + :lock: + markdown: + :unlock: + markdown: properties_list: +- property: environment + ruby_type: Hash + required: false + new_in: '19.0' + description_list: + - markdown: A Hash of environment variables in the form of {'ENV_VARIABLE' => 'VALUE'} + to be set before running the command. - property: options ruby_type: String, Array required: false @@ -62,4 +79,6 @@ properties_list: required: false description_list: - markdown: The version of a package to be installed or upgraded. +target_mode: + support: full examples: diff --git a/data/infra/resources/snap_package.yaml b/data/infra/resources/snap_package.yaml index 61b2383a..b30b61ef 100644 --- a/data/infra/resources/snap_package.yaml +++ b/data/infra/resources/snap_package.yaml @@ -6,12 +6,13 @@ resources_common_notification: true resources_common_properties: true resource: snap_package resource_description_list: -- markdown: Use the **snap_package** resource to manage snap packages on Debian and - Ubuntu platforms. +- markdown: Use the **snap_package** resource to manage snap packages on supported + Linux distributions. resource_new_in: '15.0' syntax_full_code_block: |- snap_package 'name' do - channel String # default value: "stable" + channel String # default value: "latest/stable" + environment Hash options String, Array package_name String, Array source String @@ -25,29 +26,43 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`channel`, `options`, `package_name`, `source`, `timeout`, and `version` are the - properties available to this resource." +- "`channel`, `environment`, `options`, `package_name`, `source`, `timeout`, and `version` + are the properties available to this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md :install: markdown: Install a package. If a version is specified, install the specified version of the package. (default) + :upgrade: + markdown: Install a package and ensure that a package is the latest version. + :remove: + markdown: Remove a package. :purge: markdown: Purge a package. This action typically removes the configuration files as well as the package. - :remove: - markdown: Remove a package. - :upgrade: - markdown: Install a package and ensure that a package is the latest version. - :nothing: - shortcode: resources_common_actions_nothing.md + :reconfig: + markdown: + :lock: + markdown: + :unlock: + markdown: properties_list: - property: channel ruby_type: String required: false - default_value: stable - allowed_values: '"beta", "candidate", "edge", "stable"' + default_value: latest/stable description_list: - - markdown: 'The default channel. For example: stable.' + - markdown: 'The desired channel. For example: `latest/stable`. `latest/beta/fix-test-062`, + or `0.x/edge`. If nil, the resource will install the snap''s default version. + See .' +- property: environment + ruby_type: Hash + required: false + new_in: '19.0' + description_list: + - markdown: A Hash of environment variables in the form of {'ENV_VARIABLE' => 'VALUE'} + to be set before running the command. - property: options ruby_type: String, Array required: false @@ -74,6 +89,8 @@ properties_list: required: false description_list: - markdown: The version of a package to be installed or upgraded. +target_mode: + support: full examples: | **Install a package** @@ -89,6 +106,15 @@ examples: | end ``` + **Install a package from a specific channel track** + + ```ruby + snap_package 'firefox' do + channel 'esr/stable' + action :upgrade + end + ``` + **Install a package with classic confinement** ```ruby diff --git a/data/infra/resources/solaris_package.yaml b/data/infra/resources/solaris_package.yaml index f6f861d1..d315ce43 100644 --- a/data/infra/resources/solaris_package.yaml +++ b/data/infra/resources/solaris_package.yaml @@ -9,6 +9,7 @@ resource_description_list: platform. syntax_full_code_block: |- solaris_package 'name' do + environment Hash options String, Array package_name String source String @@ -22,17 +23,35 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`options`, `package_name`, `source`, `timeout`, and `version` are the properties - available to this resource." +- "`environment`, `options`, `package_name`, `source`, `timeout`, and `version` are + the properties available to this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md :install: markdown: Install a package. If a version is specified, install the specified version of the package. (default) + :upgrade: + markdown: Install a package and ensure that a package is the latest version. :remove: markdown: Remove a package. - :nothing: - shortcode: resources_common_actions_nothing.md + :purge: + markdown: Purge a package. This action typically removes the configuration files + as well as the package. + :reconfig: + markdown: + :lock: + markdown: + :unlock: + markdown: properties_list: +- property: environment + ruby_type: Hash + required: false + new_in: '19.0' + description_list: + - markdown: A Hash of environment variables in the form of {'ENV_VARIABLE' => 'VALUE'} + to be set before running the command. - property: options ruby_type: String, Array required: false @@ -59,6 +78,8 @@ properties_list: required: false description_list: - markdown: The version of a package to be installed or upgraded. +target_mode: + support: full examples: " Install a package\n\n ```ruby\n solaris_package 'name of package'\ \ do\n source '/packages_directory'\n action :install\n end\n ```\n" diff --git a/data/infra/resources/ssh_known_hosts_entry.yaml b/data/infra/resources/ssh_known_hosts_entry.yaml index 39f0d868..3122c400 100644 --- a/data/infra/resources/ssh_known_hosts_entry.yaml +++ b/data/infra/resources/ssh_known_hosts_entry.yaml @@ -102,6 +102,8 @@ properties_list: default_value: '30' description_list: - markdown: The timeout in seconds for ssh-keyscan. +target_mode: + support: full examples: | **Add a single entry for github.com with the key auto detected** @@ -115,4 +117,4 @@ examples: | ssh_known_hosts_entry 'github.com' do key 'node.example.com ssh-rsa ...' end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/subversion.yaml b/data/infra/resources/subversion.yaml index 6c9a87f2..593119e3 100644 --- a/data/infra/resources/subversion.yaml +++ b/data/infra/resources/subversion.yaml @@ -48,6 +48,10 @@ actions_list: does nothing. :export: markdown: Export the source, excluding or removing any version control artifacts. + :diff: + markdown: + :log: + markdown: :force_export: markdown: Export the source, excluding or removing any version control artifacts and force an export of the source that is overwriting the existing copy (if @@ -80,9 +84,7 @@ properties_list: required: false default_value: HEAD description_list: - - markdown: 'A branch, tag, or commit to be synchronized with git. This can be - symbolic, like `HEAD` or it can be a source control - management-specific revision identifier.' + - markdown: The revision to checkout. - property: svn_arguments ruby_type: String, false required: false @@ -123,6 +125,8 @@ properties_list: default_value: "`HOME` environment variable of the user running chef-client" description_list: - markdown: The system user that will own the checked-out code. +target_mode: + support: full examples: | **Get the latest version of an application** @@ -133,4 +137,4 @@ examples: | destination '/opt/my_sources/couch' action :sync end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/sudo.yaml b/data/infra/resources/sudo.yaml index 277969ab..0fb15434 100644 --- a/data/infra/resources/sudo.yaml +++ b/data/infra/resources/sudo.yaml @@ -47,6 +47,10 @@ actions_list: :create: markdown: Create a single sudoers configuration file in the `sudoers.d` directory. (default) + :install: + markdown: + :remove: + markdown: :delete: markdown: Remove a sudoers configuration file from the `sudoers.d` directory. properties_list: @@ -55,13 +59,17 @@ properties_list: required: false default_value: "[]" description_list: - - markdown: Command aliases that can be used as allowed commands later in the configuration. + - markdown: 'Command aliases that can be used as allowed commands later in the configuration. + The object represents an array of hashes in the following format: `[{''name'':''ALIAS1'',''command_list'': + [ ''command1'', ''command2'' ] }, {''name'':''Alias2'',''command_list: [ ''command3'', + ''command4 arg1 arg2'' ]}]`' - property: commands ruby_type: Array required: false default_value: '["ALL"]' description_list: - - markdown: An array of full paths to commands this sudoer can execute. + - markdown: An array of full paths to commands and/or command aliases this sudoer + can execute. - property: config_prefix ruby_type: String required: false @@ -156,6 +164,8 @@ properties_list: default_value: "/usr/sbin/visudo" description_list: - markdown: The path to visudo for configuration verification. +target_mode: + support: full examples: | **Grant a user sudo privileges for any command** @@ -182,3 +192,29 @@ examples: | nopasswd true end ``` + + **Create command aliases and assign them to a group** + + ```ruby + sudo 'webteam' do + command_aliases [ + { + 'name': 'WEBTEAM_SYSTEMD_JBOSS', + 'command_list': [ + '/usr/bin/systemctl start eap7-standalone.service', + '/usr/bin/systemctl start jbcs-httpd24-httpd.service', '/usr/bin/systemctl stop eap7-standalone.service', '/usr/bin/systemctl stop jbcs-httpd24-httpd.service', '/usr/bin/systemctl restart eap7-standalone.service', '/usr/bin/systemctl restart jbcs-httpd24-httpd.service', '/usr/bin/systemctl --full edit eap7-standalone.service', '/usr/bin/systemctl --full edit jbcs-httpd24-httpd.service', '/usr/bin/systemctl daemon-reload', + ] + }, + { + 'name': 'GENERIC_SYSTEMD', + 'command_list': [ + '/usr/sbin/systemctl list-unit-files', + '/usr/sbin/systemctl list-timers', '/usr/sbin/systemctl is-active *', '/usr/sbin/systemctl is-enabled *', + ] + } + ] + nopasswd true + users '%webteam' + commands [ 'WEBTEAM_SYSTEMD_JBOSS', 'GENERIC_SYSTEMD' ] + end + ``` diff --git a/data/infra/resources/swap_file.yaml b/data/infra/resources/swap_file.yaml index 9259c329..719a3307 100644 --- a/data/infra/resources/swap_file.yaml +++ b/data/infra/resources/swap_file.yaml @@ -62,6 +62,8 @@ properties_list: default_value: '600' description_list: - markdown: Timeout for `dd` / `fallocate` commands. +target_mode: + support: full examples: | **Create a swap file** @@ -77,4 +79,4 @@ examples: | swap_file '/dev/sda1' do action :remove end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/sysctl.yaml b/data/infra/resources/sysctl.yaml index a6af63ff..d87cf8af 100644 --- a/data/infra/resources/sysctl.yaml +++ b/data/infra/resources/sysctl.yaml @@ -66,6 +66,8 @@ properties_list: required: true description_list: - markdown: The value to set. +target_mode: + support: full examples: | **Set vm.swappiness**: diff --git a/data/infra/resources/systemd_unit.yaml b/data/infra/resources/systemd_unit.yaml index 070b8d9f..f9e5ed0f 100644 --- a/data/infra/resources/systemd_unit.yaml +++ b/data/infra/resources/systemd_unit.yaml @@ -28,7 +28,7 @@ syntax_full_properties_list: available to this resource." actions_list: :nothing: - shortcode: resources_common_actions_nothing_default.md + shortcode: resources_common_actions_nothing.md :create: markdown: Create a systemd unit file, if it does not already exist. :delete: @@ -106,6 +106,10 @@ properties_list: - markdown: Specifies if the unit will be verified before installation. Systemd can be overly strict when verifying units, so in certain cases it is preferable not to verify the unit. +target_mode: + support: full + introduced: '15.1' + updated: '19.0' examples: | **Create systemd service unit file from a Hash** @@ -145,4 +149,4 @@ examples: | action [:create, :enable] end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/template.yaml b/data/infra/resources/template.yaml index 3d887753..b8af5c94 100644 --- a/data/infra/resources/template.yaml +++ b/data/infra/resources/template.yaml @@ -26,67 +26,71 @@ syntax_properties_list: - '`''motd.erb''` specifies the name of a template that exists in in the `/templates` folder of a cookbook' - '`owner`, `group`, and `mode` define the permissions' -syntax_full_code_block: "template 'name' do\n atomic_update true, false\n\ - \ backup false, Integer\n cookbook String\n\ - \ force_unlink true, false\n group String,\ - \ Integer\n helper(:method) Method { String } # see Helpers below\n\ - \ helpers(module) Module # see Helpers below\n inherits \ - \ true, false\n local true, false\n manage_symlink_source\ - \ true, false\n mode String, Integer\n owner \ - \ String, Integer\n path String # defaults\ - \ to 'name' if not specified\n rights Hash\n sensitive \ - \ true, false\n source String, Array\n variables\ - \ Hash\n verify String, Block\n action \ - \ Symbol # defaults to :create if not specified\nend" +syntax_full_code_block: "template 'name' do\n atomic_update true, false\n + \ backup Integer, false # default value: 5\n checksum String\n + \ content String\n cookbook String\n force_unlink + \ true, false # default value: false\n group \n + \ local true, false # default value: false\n manage_symlink_source + \ true, false\n mode \n owner \n + \ path String # default value: 'name' unless specified\n variables + \ Hash # default value: {}\n action Symbol + # defaults to :create if not specified\nend" syntax_full_properties_list: -- '`template` is the resource' -- '`name` is the name of the resource block, typically the path to the location in - which a file is created *and also* the name of the file to be managed. For example: - `/var/www/html/index.html`, where `/var/www/html/` is the fully qualified path to - the location and `index.html` is the name of the file' -- '`source` is the template file that will be used to create the file on the node, - for example: `index.html.erb`; the template file is located in the `/templates` - directory of a cookbook' -- '`action` identifies the steps Chef Infra Client will take to bring the node into - the desired state' -- '`atomic_update`, `backup`, `cookbook`, `force_unlink`, `group`, `helper`, `helpers`, - `inherits`, `local`, `manage_symlink_source`, `mode`, `owner`, `path`, `rights`, - `source`, `variables`, and `verify` are properties of this resource, - with the Ruby type shown. See "Properties" section below for more information about - all of the properties that may be used with this resource.' +- "`template` is the resource." +- "`name` is the name given to the resource block." +- "`action` identifies which steps Chef Infra Client will take to bring the node into + the desired state." +- "`atomic_update`, `backup`, `checksum`, `content`, `cookbook`, `force_unlink`, `group`, + `local`, `manage_symlink_source`, `mode`, `owner`, `path`, and `variables` are the + properties available to this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md :create: markdown: (default) Create a file. If a file already exists (but does not match), update that file to match. - :create_if_missing: - markdown: Create a file only if the file does not exist. When the file exists, - nothing happens. :delete: markdown: Delete a file. - :nothing: - shortcode: resources_common_actions_nothing.md :touch: markdown: Touch a file. This updates the access (atime) and file modification (mtime) times for a file. (This action may be used with this resource, but is typically only used with the **file** resource.) + :create_if_missing: + markdown: Create a file only if the file does not exist. When the file exists, + nothing happens. properties_list: - property: atomic_update ruby_type: true, false required: false + default_value: False if modifying /etc/hosts, /etc/hostname, or /etc/resolv.conf + within Docker containers. Otherwise default to the client.rb 'file_atomic_update' + config value. description_list: - - markdown: 'Perform atomic file updates on a per-resource basis. Set to `true` - for atomic file updates. Set to `false` for non-atomic file updates. - This setting overrides `file_atomic_update`, which is a global - setting found in the client.rb file.' + - markdown: Perform atomic file updates on a per-resource basis. Set to true for + atomic file updates. Set to false for non-atomic file updates. This setting + overrides `file_atomic_update`, which is a global setting found in the `client.rb` + file. - property: backup ruby_type: Integer, false required: false default_value: '5' description_list: - - markdown: 'The number of backups to be kept in `/var/chef/backup` (for UNIX- - and Linux-based platforms) or `C:/chef/backup` (for the Microsoft - Windows platform). Set to `false` to prevent backups from being - kept.' + - markdown: The number of backups to be kept in `/var/chef/backup` (for UNIX- and + Linux-based platforms) or `C:/chef/backup` (for the Microsoft Windows platform). + Set to `false` to prevent backups from being kept. +- property: checksum + ruby_type: String + required: false + description_list: + - markdown: The SHA-256 checksum of the file. Use to ensure that a specific file + is used. If the checksum does not match, the file is not used. +- property: content + ruby_type: String + required: false + description_list: + - markdown: A string that is written to the file. The contents of this property + replace any previous content when this property has something other than the + default value. The default behavior will not modify content. - property: cookbook ruby_type: String required: false @@ -104,66 +108,33 @@ properties_list: it with the specified file. Set to `false` for Chef Infra Client to raise an error. - property: group - ruby_type: Integer, String + ruby_type: '' required: false description_list: - - markdown: 'A string or ID that identifies the group owner by group name or SID, - including fully qualified group names such as `domain\group` or - `group@domain`. If this value is not specified, existing groups - remain unchanged and new group assignments use the default `POSIX` - group (if available).' -- property: helper - ruby_type: Method - required: false - default_value: '{}' - description_list: - - markdown: 'Define a helper method inline. For example: - `helper(:hello_world) { "hello world" }` or - `helper(:app) { node["app"] }` or - `helper(:app_conf) { |setting| node["app"][setting] }`.' -- property: helpers - ruby_type: Module - required: false - default_value: '[]' - description_list: - - markdown: 'Define a helper module inline or in a library. For example, an - inline module: `helpers do`, which is then followed by a block of - Ruby code. And for a library module: `helpers(MyHelperModule)`.' -- property: inherits - ruby_type: true, false - required: false - default_value: 'true' - description_list: - - markdown: 'Microsoft Windows only. Whether a file inherits rights from its - parent directory.' + - markdown: - property: local ruby_type: true, false required: false default_value: 'false' description_list: - - markdown: 'Load a template from a local path. By default, Chef Infra 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.' + - markdown: Load a template from a local path. By default, the chef-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. - property: manage_symlink_source ruby_type: true, false required: false - default_value: 'true' description_list: - - markdown: '(with warning) - - Change the behavior of the file resource if it is pointed at a - symlink. When this value is set to `true`, Chef Infra Client 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 will follow the symlink and will manage the - permissions and content of the 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.' + - markdown: Change the behavior of the file resource if it is pointed at a symlink. + When this value is set to true, Chef Infra Client 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 Infra Client 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. - property: mode - ruby_type: Integer, String + ruby_type: '' required: false description_list: - markdown: 'A quoted 3-5 character string that defines the octal mode. For @@ -199,7 +170,7 @@ properties_list: effect if not specified, but when it and `rights` are both specified, the effects are cumulative.' - property: owner - ruby_type: Integer, String + ruby_type: '' required: false description_list: - markdown: 'A string or ID that identifies the group owner by user name or SID, @@ -212,66 +183,21 @@ properties_list: required: false default_value: The resource block's name description_list: - - markdown: 'The full path to the file, including the file name and its - extension. - - Microsoft Windows: A path that begins with a forward slash (`/`) - will point to the root of the current working directory of Chef - Infra Client process. This path can vary from system to system. - Therefore, using a path that begins with a forward slash (`/`) is - not recommended.' -- property: rights - ruby_type: Integer, String - required: false - description_list: - - markdown: 'Microsoft Windows only. The permissions for users and groups in a - Microsoft Windows environment. For example: - `rights , , ` where `` - specifies the rights granted to the principal, `` is the - group or user name, and `` is a Hash with one (or more) - advanced rights options.' -- property: source - ruby_type: String, Array - required: false - description_list: - - markdown: 'The location of a template file. By default, Chef Infra Client looks - for a template file in the `/templates` directory of a cookbook. - When the `local` property is set to `true`, use to specify the path - to a template on the local node. This property may also be used to - distribute specific files to specific platforms. See "File - Specificity" below for more information. Default value: the `name` - of the resource block. See "Syntax" section above for more - information.' + - markdown: 'The full path to the file, including the file name and its extension. + For example: /files/file.txt. Default value: the name of the resource block. + Microsoft Windows: A path that begins with a forward slash `/` will point to + the root of the current working directory of the Chef Infra Client process. + This path can vary from system to system. Therefore, using a path that begins + with a forward slash `/` is not recommended.' - property: variables ruby_type: Hash required: false + default_value: "{}" description_list: - - markdown: A Hash of variables that are passed into a Ruby template file. - - shortcode: template_partials_variables_attribute.md -- property: verify - ruby_type: String, Block - required: false - description_list: - - markdown: "A block or a string that returns `true` or `false`. A string, when\n\ - `true` is executed as a system command.\n\nA block is arbitrary Ruby defined\ - \ within the resource block by using\nthe `verify` property. When a block is\ - \ `true`, Chef Infra Client\nwill continue to update the file as appropriate.\n\ - \nFor example, this should return `true`:\n\n```ruby\ntemplate '/tmp/baz' do\n\ - \ verify { 1 == 1 }\nend\n```\n\nThis should return `true`:\n\n```ruby\ntemplate\ - \ '/etc/nginx.conf' do\n verify 'nginx -t -c %{path}'\nend\n```" - - markdown: "This should return `true`:\n\n```ruby\ntemplate '/tmp/bar' do\n verify\ - \ { 1 == 1}\nend\n```\n\nAnd this should return `true`:\n\n```ruby\ntemplate\ - \ '/tmp/foo' do\n verify do |path|\n true\n end\nend\n```\n\nWhereas, this\ - \ should return `false`:\n\n```ruby\ntemplate '/tmp/turtle' do\n verify '/usr/bin/false'\n\ - end\n```\n\nIf a string or a block return `false`, the Chef Infra Client run\n\ - will stop and an error is returned." -properties_multiple_packages: false -resource_directory_recursive_directories: false -remote_file_prevent_re_downloads: false -remote_file_unc_path: false -ps_credential_helper: false -ruby_style_basics_chef_log: false -debug_recipes_chef_shell: false + - markdown: The variables property of the template resource can be used to reference + a partial template file by using a Hash. +target_mode: + support: full examples: " Configure a file from a template\n\n ```ruby\n template '/tmp/config.conf'\ \ do\n source 'config.conf.erb'\n end\n ```\n\n Configure a file from a local\ diff --git a/data/infra/resources/timezone.yaml b/data/infra/resources/timezone.yaml index bde5cb48..5adeeefc 100644 --- a/data/infra/resources/timezone.yaml +++ b/data/infra/resources/timezone.yaml @@ -35,6 +35,8 @@ properties_list: description_list: - markdown: An optional property to set the timezone value if it differs from the resource block's name. +target_mode: + support: full examples: | **Set the timezone to UTC** diff --git a/data/infra/resources/user.yaml b/data/infra/resources/user.yaml deleted file mode 100644 index dc11a8a3..00000000 --- a/data/infra/resources/user.yaml +++ /dev/null @@ -1,217 +0,0 @@ ---- -title: user resource -resource: user -aliases: -- /resource_user.html -menu: - infra: - title: user - identifier: chef_infra/resources/user user - parent: chef_infra/resources -resource_reference: true -resource_description_list: -- markdown: 'Use the **user** resource to add users, update existing users, remove - - users, and to lock/unlock user passwords.' -- note: - markdown: 'System attributes are collected by Ohai at the start of every Chef - Infra - - Client run. By design, the actions available to the **user** resource - - are processed **after** the start of a Chef Infra Client run. This means - - that system attributes added or modified by the **user** resource during - - a Chef Infra Client run must be reloaded before they can be available to - - Chef Infra Client. These system attributes can be reloaded in two ways: - - by picking up the values at the start of the (next) Chef Infra Client - - run or by using the [ohai resource](/resources/bundled/ohai/) to reload the - - system attributes during the current Chef Infra Client run.' -syntax_description: "A **user** resource block manages users on a node:\n\n```ruby\n\ - user 'a user' do\n comment 'A random user'\n uid 1234\n gid 'groupname'\n home\ - \ '/home/random'\n shell '/bin/bash'\n password '$1$JJsvHslasdfjVEroftprNn4JHtDi'\n\ - end\n```" -syntax_properties_list: null -syntax_full_code_block: "user 'name' do\n comment String\n force\ - \ true, false # see description\n gid \ - \ String, Integer\n home String\n iterations \ - \ Integer\n manage_home true, false\n non_unique \ - \ true, false\n password String\n salt \ - \ String\n shell String\n system \ - \ true, false\n uid String, Integer\n username \ - \ String # defaults to 'name' if not specified\n action \ - \ Symbol # defaults to :create if not specified\nend" -syntax_full_properties_list: -- '`user` is the resource' -- '`name` is the name of the resource block' -- '`action` identifies the steps Chef Infra Client will take to bring the node into - the desired state' -- '`comment`, `force`, `gid`, `home`, `iterations`, `manage_home`, `non_unique`, `password`, - `salt`, `shell`, `system`, `uid`, and `username` are properties of this resource, - with the Ruby type shown. See "Properties" section below for more information about - all of the properties that may be used with this resource.' -actions_list: - :create: - markdown: (default) Create a user with given properties. If a user already exists - (but does not match), update that user to match. - :lock: - markdown: Lock a user's password. - :manage: - markdown: Manage an existing user. This action does nothing if the user does not - exist. - :modify: - markdown: Modify an existing user. This action raises an exception if the user - does not exist. - :nothing: - shortcode: resources_common_actions_nothing.md - :remove: - markdown: Remove a user. - :unlock: - markdown: Unlock a user's password. -properties_list: -- property: comment - ruby_type: String - required: false - description_list: - - markdown: One (or more) comments about the user. -- property: expire_date - ruby_type: String - new_in: '18.0' - required: false - description_list: - - markdown: (Linux) The date on which the user account will be disabled. The date is specified in YYYY-MM-DD format. -- property: force - ruby_type: true, false - required: false - description_list: - - markdown: 'Force the removal of a user. May be used only with the `:remove` - - action.' - - warning: - markdown: 'Using this property may leave the system in an inconsistent state. - - For example, a user account will be removed even if the user is - - logged in. A user''s home directory will be removed, even if that - - directory is shared by multiple users.' -- property: gid - ruby_type: String, Integer - required: false - description_list: - - markdown: 'The identifier for the group. This property was previously named - - `group` and both continue to function.' -- property: home - ruby_type: String - required: false - description_list: - - markdown: The location of the home directory. -- property: inactive - ruby_type: String, Integer - new_in: '18.0' - required: false - description_list: - - markdown: (Linux) The number of days after a password expires until the account is permanently disabled. A value of `0` disables the account as soon as the password has expired, and a value of `-1` disables the feature. -- property: iterations - ruby_type: Integer - required: false - description_list: - - markdown: 'macOS platform only. The number of iterations for a password with a - - SALTED-SHA512-PBKDF2 shadow hash.' -- property: manage_home - ruby_type: true, false - required: false - description_list: - - markdown: 'Manage a user''s home directory. - - - When 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. - - - When 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.' -- property: non_unique - ruby_type: true, false - required: false - description_list: - - markdown: Create a duplicate (non-unique) user account. -- property: password - ruby_type: String - required: false - description_list: - - markdown: The password shadow hash -- property: salt - ruby_type: String - required: false - description_list: - - markdown: A SALTED-SHA512-PBKDF2 hash. -- property: shell - ruby_type: String - required: false - description_list: - - markdown: The login shell. -- property: system - ruby_type: true, false - required: false - description_list: - - markdown: 'Create a system user. This property may be used with `useradd` as - - the provider to create a system user which passes the `-r` flag to - - `useradd`.' -- property: uid - ruby_type: String, Integer - required: false - description_list: - - markdown: The numeric user identifier. -- property: username - ruby_type: String - required: false - description_list: - - markdown: 'The name of the user. Default value: the `name` of the resource - - block. See "Syntax" section above for more information.' -resources_common_properties: true -resources_common_notification: true -resources_common_guards: true -examples: " - Create a system user\n\n ```ruby\n user 'systemguy' do\n comment\ - \ 'system guy'\n system true\n shell '/bin/false'\n end\n ```\n\n Create\ - \ a system user with a variable\n\n The following example shows how to create a\ - \ system user. In this\n instance, the `home` value is calculated and stored in\ - \ a variable called\n `user_home` which sets the user's `home` attribute.\n\n \ - \ ```ruby\n user_home = \"/home/#{node['cookbook_name']['user']}\"\n\n user node['cookbook_name']['user']\ - \ do\n gid node['cookbook_name']['group']\n shell '/bin/bash'\n home user_home\n\ - \ system true\n action :create\n end\n ```\n\n Use SALTED-SHA512-PBKDF2\ - \ passwords\n\n macOS 10.8 (and higher) calculates the password shadow hash using\n\ - \ SALTED-SHA512-PBKDF2. The length of the shadow hash value is 128 bytes,\n the\ - \ salt value is 32 bytes, and an integer specifies the number of\n iterations.\ - \ The following code will calculate password shadow hashes for\n macOS 10.8 (and\ - \ higher):\n\n ```ruby\n password = 'my_awesome_password'\n salt = OpenSSL::Random.random_bytes(32)\n\ - \ iterations = 25000 # Any value above 20k should be fine.\n\n shadow_hash = OpenSSL::PKCS5::pbkdf2_hmac(\n\ - \ password,\n salt,\n iterations,\n 128,\n OpenSSL::Digest::SHA512.new\n\ - \ ).unpack('H*').first\n salt_value = salt.unpack('H*').first\n ```\n\n Use\ - \ the calculated password shadow hash with the **user** resource:\n\n ```ruby\n\ - \ user 'my_awesome_user' do\n password 'cbd1a....fc843' # Length: 256\n \ - \ salt 'bd1a....fc83' # Length: 64\n iterations 25000\n end\n ```\n" - diff --git a/data/infra/resources/user_ulimit.yaml b/data/infra/resources/user_ulimit.yaml index ca793bf1..7e0d5eb7 100644 --- a/data/infra/resources/user_ulimit.yaml +++ b/data/infra/resources/user_ulimit.yaml @@ -265,6 +265,8 @@ properties_list: required: false description_list: - markdown: +target_mode: + support: full examples: | **Set filehandle limit for the tomcat user**: diff --git a/data/infra/resources/windows_ad_join.yaml b/data/infra/resources/windows_ad_join.yaml index 7c366043..dd3320a6 100644 --- a/data/infra/resources/windows_ad_join.yaml +++ b/data/infra/resources/windows_ad_join.yaml @@ -89,6 +89,7 @@ properties_list: - markdown: Specifies the name of a workgroup to which the computer is added to when it is removed from the domain. The default value is WORKGROUP. This property is only applicable to the :leave action. +target_mode: examples: | **Join a domain** @@ -116,4 +117,4 @@ examples: | action :leave workgroup 'local' end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/windows_audit_policy.yaml b/data/infra/resources/windows_audit_policy.yaml index d924a3ec..782fd3ed 100644 --- a/data/infra/resources/windows_audit_policy.yaml +++ b/data/infra/resources/windows_audit_policy.yaml @@ -97,6 +97,7 @@ properties_list: - markdown: 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. +target_mode: examples: | **Set Logon and Logoff policy to "Success and Failure"**: @@ -127,4 +128,4 @@ examples: | crash_on_audit_fail true action :set end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/windows_auto_run.yaml b/data/infra/resources/windows_auto_run.yaml index 39243840..6b55166d 100644 --- a/data/infra/resources/windows_auto_run.yaml +++ b/data/infra/resources/windows_auto_run.yaml @@ -55,13 +55,14 @@ properties_list: allowed_values: ":machine, :user" description_list: - markdown: The registry root key to put the entry under. +target_mode: examples: | **Run BGInfo at login** ```ruby windows_auto_run 'BGINFO' do program 'C:/Sysinternals/bginfo.exe' - args ''C:/Sysinternals/Config.bgi' /NOLICPROMPT /TIMER:0' + args "'C:/Sysinternals/Config.bgi' /NOLICPROMPT /TIMER:0" action :create end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/windows_certificate.yaml b/data/infra/resources/windows_certificate.yaml index 915630e2..42099f7e 100644 --- a/data/infra/resources/windows_certificate.yaml +++ b/data/infra/resources/windows_certificate.yaml @@ -95,6 +95,7 @@ properties_list: - markdown: Use the `CurrentUser` store instead of the default `LocalMachine` store. - note: markdown: Prior to chef-client. 16.10 this property was ignored. +target_mode: examples: | **Add PFX cert to local machine personal store and grant accounts read-only access to private key** diff --git a/data/infra/resources/windows_defender.yaml b/data/infra/resources/windows_defender.yaml index 3ef974c9..aafd74e2 100644 --- a/data/infra/resources/windows_defender.yaml +++ b/data/infra/resources/windows_defender.yaml @@ -92,6 +92,7 @@ properties_list: default_value: 'false' description_list: - markdown: Scan scripts in malware scans. +target_mode: examples: | **Configure Windows Defender AV settings**: diff --git a/data/infra/resources/windows_defender_exclusion.yaml b/data/infra/resources/windows_defender_exclusion.yaml index ba420924..d8b15a6d 100644 --- a/data/infra/resources/windows_defender_exclusion.yaml +++ b/data/infra/resources/windows_defender_exclusion.yaml @@ -49,6 +49,7 @@ properties_list: default_value: "[]" description_list: - markdown: Paths to executables to exclude from scanning. +target_mode: examples: | **Add excluded items to Windows Defender scans**: diff --git a/data/infra/resources/windows_dfs_folder.yaml b/data/infra/resources/windows_dfs_folder.yaml index c6a98f06..30ad9423 100644 --- a/data/infra/resources/windows_dfs_folder.yaml +++ b/data/infra/resources/windows_dfs_folder.yaml @@ -54,4 +54,5 @@ properties_list: required: false description_list: - markdown: The target that this path will connect you to. +target_mode: examples: diff --git a/data/infra/resources/windows_dfs_namespace.yaml b/data/infra/resources/windows_dfs_namespace.yaml index 1b5889be..e57df527 100644 --- a/data/infra/resources/windows_dfs_namespace.yaml +++ b/data/infra/resources/windows_dfs_namespace.yaml @@ -70,4 +70,5 @@ properties_list: default_value: C:\DFSRoots description_list: - markdown: The root from which to create the DFS tree. Defaults to C:\DFSRoots. +target_mode: examples: diff --git a/data/infra/resources/windows_dfs_server.yaml b/data/infra/resources/windows_dfs_server.yaml index f93025fd..8f9b37d9 100644 --- a/data/infra/resources/windows_dfs_server.yaml +++ b/data/infra/resources/windows_dfs_server.yaml @@ -58,4 +58,5 @@ properties_list: - markdown: Indicates whether a DFS namespace server uses FQDNs in referrals. If this property is set to true, the server uses FQDNs in referrals. If this property is set to false then the server uses NetBIOS names. +target_mode: examples: diff --git a/data/infra/resources/windows_dns_record.yaml b/data/infra/resources/windows_dns_record.yaml index 67c83991..e515ea82 100644 --- a/data/infra/resources/windows_dns_record.yaml +++ b/data/infra/resources/windows_dns_record.yaml @@ -63,4 +63,5 @@ properties_list: required: true description_list: - markdown: The zone to create the record in. +target_mode: examples: diff --git a/data/infra/resources/windows_dns_zone.yaml b/data/infra/resources/windows_dns_zone.yaml index 91aca122..e3aea2db 100644 --- a/data/infra/resources/windows_dns_zone.yaml +++ b/data/infra/resources/windows_dns_zone.yaml @@ -51,4 +51,5 @@ properties_list: description_list: - markdown: An optional property to set the dns zone name if it differs from the resource block's name. +target_mode: examples: diff --git a/data/infra/resources/windows_env.yaml b/data/infra/resources/windows_env.yaml index 8faa8800..72fd8c6a 100644 --- a/data/infra/resources/windows_env.yaml +++ b/data/infra/resources/windows_env.yaml @@ -64,6 +64,7 @@ properties_list: required: true description_list: - markdown: The value of the environmental variable to set. +target_mode: examples: | **Set an environment variable**: @@ -71,4 +72,4 @@ examples: | windows_env 'ComSpec' do value 'C:\Windows\system32\cmd.exe' end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/windows_feature.yaml b/data/infra/resources/windows_feature.yaml index b9cf0a13..53521c71 100644 --- a/data/infra/resources/windows_feature.yaml +++ b/data/infra/resources/windows_feature.yaml @@ -5,13 +5,11 @@ resources_common_notification: true resources_common_properties: true resource: windows_feature resource_description_list: -- markdown: 'Use the **windows_feature** resource to add, remove or entirely delete - Windows features and roles. This resource calls the - [windows_feature_dism](/resources/bundled/windows_feature_dism/) or - [windows_feature_powershell](/resources/bundled/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.' +- markdown: 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. resource_new_in: '14.0' syntax_full_code_block: |- windows_feature 'name' do @@ -83,6 +81,7 @@ properties_list: default_value: '600' description_list: - markdown: Specifies a timeout (in seconds) for the feature installation. +target_mode: examples: | **Install the DHCP Server feature**: @@ -136,4 +135,4 @@ examples: | management_tools true install_method :windows_feature_powershell end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/windows_feature_dism.yaml b/data/infra/resources/windows_feature_dism.yaml index 0fc5238f..5ca12257 100644 --- a/data/infra/resources/windows_feature_dism.yaml +++ b/data/infra/resources/windows_feature_dism.yaml @@ -59,6 +59,7 @@ properties_list: default_value: '600' description_list: - markdown: Specifies a timeout (in seconds) for the feature installation. +target_mode: examples: | **Installing the TelnetClient service**: @@ -70,4 +71,4 @@ examples: | ```ruby windows_feature_dism %w(TelnetClient TFTP) - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/windows_feature_powershell.yaml b/data/infra/resources/windows_feature_powershell.yaml index bc97cd3c..b3cf4224 100644 --- a/data/infra/resources/windows_feature_powershell.yaml +++ b/data/infra/resources/windows_feature_powershell.yaml @@ -5,12 +5,10 @@ resources_common_notification: true resources_common_properties: true resource: windows_feature_powershell resource_description_list: -- markdown: '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](/resources/bundled/windows_feature_dism/) resource, - but requires installation of the Remote Server Administration Tools on - non-server releases of Windows.' +- markdown: 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. resource_new_in: '14.0' syntax_full_code_block: |- windows_feature_powershell 'name' do @@ -71,6 +69,7 @@ properties_list: default_value: '600' description_list: - markdown: Specifies a timeout (in seconds) for the feature installation. +target_mode: examples: | **Add the SMTP Server feature**: @@ -96,4 +95,4 @@ examples: | action :install management_tools true end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/windows_firewall_profile.yaml b/data/infra/resources/windows_firewall_profile.yaml index 9dd033d6..7a39d5c5 100644 --- a/data/infra/resources/windows_firewall_profile.yaml +++ b/data/infra/resources/windows_firewall_profile.yaml @@ -101,6 +101,7 @@ properties_list: allowed_values: '"Domain", "Private", "Public"' description_list: - markdown: Set the Windows Profile being configured +target_mode: examples: | **Enable and Configure the Private Profile of the Windows Profile**: @@ -133,4 +134,4 @@ examples: | profile 'Domain' action :disable end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/windows_firewall_rule.yaml b/data/infra/resources/windows_firewall_rule.yaml index da61814d..befe2c23 100644 --- a/data/infra/resources/windows_firewall_rule.yaml +++ b/data/infra/resources/windows_firewall_rule.yaml @@ -151,6 +151,7 @@ properties_list: required: false description_list: - markdown: The service the firewall rule applies to. +target_mode: examples: | **Allowing port 80 access**: diff --git a/data/infra/resources/windows_font.yaml b/data/infra/resources/windows_font.yaml index fcfe0601..d16f675f 100644 --- a/data/infra/resources/windows_font.yaml +++ b/data/infra/resources/windows_font.yaml @@ -40,6 +40,7 @@ properties_list: required: false description_list: - markdown: A local filesystem path or URI that is used to source the font file. +target_mode: examples: | **Install a font from a https source**: diff --git a/data/infra/resources/windows_package.yaml b/data/infra/resources/windows_package.yaml index e4bdaced..0f659479 100644 --- a/data/infra/resources/windows_package.yaml +++ b/data/infra/resources/windows_package.yaml @@ -43,6 +43,7 @@ syntax_description: | syntax_full_code_block: |- windows_package 'name' do checksum String + environment Hash installer_type Symbol options String package_name String @@ -50,7 +51,7 @@ syntax_full_code_block: |- returns String, Integer, Array source String # default value: "The resource block's name" timeout String, Integer # default value: "600 (seconds)" - version String + version String, Array action Symbol # defaults to :install if not specified end syntax_properties_list: @@ -59,16 +60,28 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`checksum`, `installer_type`, `options`, `package_name`, `remote_file_attributes`, +- "`checksum`, `environment`, `installer_type`, `options`, `package_name`, `remote_file_attributes`, `returns`, `source`, `timeout`, and `version` are the properties available to this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md :install: markdown: Install a package. If a version is specified, install the specified version of the package. (default) - :nothing: - shortcode: resources_common_actions_nothing.md + :upgrade: + markdown: Install a package and ensure that a package is the latest version. :remove: + markdown: Remove a package. + :purge: + markdown: Purge a package. This action typically removes the configuration files + as well as the package. + :reconfig: + markdown: + :lock: + markdown: + :unlock: + markdown: properties_list: - property: checksum ruby_type: String @@ -77,15 +90,22 @@ properties_list: - markdown: The SHA-256 checksum of the file. Use to prevent a file from being re-downloaded. When the local file matches the checksum, Chef Infra Client does not download it. Use when a URL is specified by the `source` property. +- property: environment + ruby_type: Hash + required: false + new_in: '19.0' + description_list: + - markdown: A Hash of environment variables in the form of {'ENV_VARIABLE' => 'VALUE'} + to be set before running the command. - property: installer_type ruby_type: Symbol required: false allowed_values: ":custom, :inno, :installshield, :msi, :nsis, :wise" description_list: - - markdown: 'A symbol that specifies the type of package. Possible values: `:custom` - (such as installing a non-.msi file that embeds an .msi-based installer), `:inno` - (Inno Setup), `:installshield` (InstallShield), `:msi` (Microsoft Installer Package - (MSI)), `:nsis` (Nullsoft Scriptable Install System (NSIS)), `:wise` (Wise).' + - markdown: 'A symbol that specifies the type of package. Possible values: :custom + (such as installing a non-.msi file that embeds an .msi-based installer), :inno + (Inno Setup), :installshield (InstallShield), :msi (Microsoft Installer Package + (MSI)), :nsis (Nullsoft Scriptable Install System (NSIS)), :wise (Wise).' - property: options ruby_type: String required: false @@ -105,7 +125,7 @@ properties_list: allows you to define a hash of properties which will be used by the underlying **remote_file** resource used to fetch the source. - property: returns - ruby_type: String, Integer, Array of integers + ruby_type: String, Integer, Array required: false default_value: 0 (success) and 3010 (success where a reboot is necessary) description_list: @@ -116,37 +136,8 @@ properties_list: required: false default_value: The resource block's name description_list: - - markdown: 'The path to a package in the local file system. The location of the - - package may be at a URL. - - - If the `source` property is not specified, the package name MUST be - - exactly the same as the display name found in **Add/Remove - - programs** or exactly the same as the `DisplayName` property in the - - appropriate registry key, which may be one of the following: - - - ```ruby - - HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall - - HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Uninstall - - HKEY_LOCAL_MACHINE\Software\Wow6432Node\Microsoft\Windows\CurrentVersion\Uninstall - - ```' - - note: - markdown: 'If there are multiple versions of a package installed with the same - - display name, all of those packages will be removed unless a version - - is provided in the `version` property or unless it can be discovered - - in the installer file specified by the `source` property.' + - markdown: The path to a package in the local file system or the URL of a remote + file that will be downloaded. - property: timeout ruby_type: String, Integer required: false @@ -154,10 +145,11 @@ properties_list: description_list: - markdown: The amount of time (in seconds) to wait before timing out. - property: version - ruby_type: String + ruby_type: String, Array required: false description_list: - markdown: The version of a package to be installed or upgraded. +target_mode: examples: | **Install a package**: @@ -181,7 +173,7 @@ examples: | ```ruby windows_package '7zip' do source 'http://www.7-zip.org/a/7z938-x64.msi' - checksum '7c8e873991c82ad9cfc123415254ea6101e9a645e12977dcd518979e50fdedf3' + checksum '7c8e873991c82ad9cfcdbdf45254ea6101e9a645e12977dcd518979e50fdedf3' end ``` @@ -194,7 +186,7 @@ examples: | source 'http://www.7-zip.org/a/7z938-x64.msi' remote_file_attributes ({ :path => 'C:\7zip.msi', - :checksum => '7c8e873991c82ad9cfc123415254ea6101e9a645e12977dcd518979e50fdedf3' + :checksum => '7c8e873991c82ad9cfcdbdf45254ea6101e9a645e12977dcd518979e50fdedf3' }) end ``` diff --git a/data/infra/resources/windows_pagefile.yaml b/data/infra/resources/windows_pagefile.yaml index d310b8f3..7622ba23 100644 --- a/data/infra/resources/windows_pagefile.yaml +++ b/data/infra/resources/windows_pagefile.yaml @@ -61,6 +61,7 @@ properties_list: required: false description_list: - markdown: Configures whether the system manages the pagefile size. +target_mode: examples: | **Set the system to manage pagefiles**: @@ -83,7 +84,7 @@ examples: | ```ruby windows_pagefile 'Change the pagefile to System Managed' do - path 'E:' + path 'E:\' system_managed true action :set end @@ -93,8 +94,8 @@ examples: | ```ruby windows_pagefile 'create the pagefile with these sizes' do - path 'f:' + path 'f:\' initial_size 100 maximum_size 200 end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/windows_path.yaml b/data/infra/resources/windows_path.yaml index a022ed9e..17df3cf3 100644 --- a/data/infra/resources/windows_path.yaml +++ b/data/infra/resources/windows_path.yaml @@ -35,6 +35,7 @@ properties_list: description_list: - markdown: An optional property to set the path value if it differs from the resource block's name. +target_mode: examples: | **Add Sysinternals to the system path**: @@ -50,4 +51,4 @@ examples: | windows_path 'C:\7-Zip' do action :remove end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/windows_printer.yaml b/data/infra/resources/windows_printer.yaml index b71df105..97bfdc22 100644 --- a/data/infra/resources/windows_printer.yaml +++ b/data/infra/resources/windows_printer.yaml @@ -102,6 +102,7 @@ properties_list: default_value: 'false' description_list: - markdown: Determines whether or not the printer is shared. +target_mode: examples: | **Create a printer**: diff --git a/data/infra/resources/windows_printer_port.yaml b/data/infra/resources/windows_printer_port.yaml index 715af201..84ff7634 100644 --- a/data/infra/resources/windows_printer_port.yaml +++ b/data/infra/resources/windows_printer_port.yaml @@ -65,6 +65,7 @@ properties_list: default_value: 'false' description_list: - markdown: Determines if SNMP is enabled on the port. +target_mode: examples: | **Delete a printer port** diff --git a/data/infra/resources/windows_security_policy.yaml b/data/infra/resources/windows_security_policy.yaml index 2fc4eee0..797967a4 100644 --- a/data/infra/resources/windows_security_policy.yaml +++ b/data/infra/resources/windows_security_policy.yaml @@ -44,6 +44,7 @@ properties_list: required: true description_list: - markdown: Policy value to be set for policy name. +target_mode: examples: | **Set Administrator Account to Enabled**: diff --git a/data/infra/resources/windows_service.yaml b/data/infra/resources/windows_service.yaml index e92ec48d..50acf55c 100644 --- a/data/infra/resources/windows_service.yaml +++ b/data/infra/resources/windows_service.yaml @@ -20,12 +20,17 @@ syntax_full_code_block: |- desired_access Integer # default value: 983551 display_name String error_control Integer # default value: 1 + init_command String load_order_group String + options Array, String + parameters Hash pattern String + priority Integer, String, Hash reload_command String, false restart_command String, false run_as_password String run_as_user String # default value: "localsystem" + run_levels Array service_name String # default value: 'name' unless specified service_type Integer # default value: 16 start_command String, false @@ -34,6 +39,7 @@ syntax_full_code_block: |- stop_command String, false supports Hash # default value: {"restart"=>nil, "reload"=>nil, "status"=>nil} timeout Integer # default value: 60 + user String action Symbol # defaults to :nothing if not specified end syntax_properties_list: @@ -43,10 +49,10 @@ syntax_full_properties_list: - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." - "`binary_path_name`, `delayed_start`, `dependencies`, `description`, `desired_access`, - `display_name`, `error_control`, `load_order_group`, - `pattern`, `reload_command`, `restart_command`, `run_as_password`, - `run_as_user`, `service_name`, `service_type`, `start_command`, `startup_type`, - `status_command`, `stop_command`, `supports`, and `timeout` are the properties + `display_name`, `error_control`, `init_command`, `load_order_group`, `options`, + `parameters`, `pattern`, `priority`, `reload_command`, `restart_command`, `run_as_password`, + `run_as_user`, `run_levels`, `service_name`, `service_type`, `start_command`, `startup_type`, + `status_command`, `stop_command`, `supports`, `timeout`, and `user` are the properties available to this resource." actions_list: :configure: @@ -130,18 +136,49 @@ properties_list: new_in: '14.0' description_list: - markdown: +- property: init_command + ruby_type: String + required: false + description_list: + - markdown: The path to the init script that is associated with the service. Use + `init_command` to prevent the need to specify overrides for the `start_command`, + `stop_command`, and `restart_command` properties. When this property is not + specified, the Chef Infra Client will use the default init command for the service + provider being used. - property: load_order_group ruby_type: String required: false new_in: '14.0' description_list: - markdown: The name of the service's load ordering group(s). +- property: options + ruby_type: Array, String + required: false + description_list: + - markdown: Solaris platform only. Options to pass to the service command. See the + svcadm manual for details of possible options. +- property: parameters + ruby_type: Hash + required: false + description_list: + - markdown: 'Upstart only: A hash of parameters to pass to the service command for + use in the service definition.' - property: pattern ruby_type: String required: false default_value: The value provided to 'service_name' or the resource block's name description_list: - markdown: The pattern to look for in the process table. +- property: priority + ruby_type: Integer, String, Hash + required: false + description_list: + - markdown: Debian platform only. The relative priority of the program for start + and shutdown ordering. May be an integer or a Hash. An integer is used to define + the start run levels; stop run levels are then 100-integer. A Hash is used to + define values for specific run levels. For example, { 2 => [:start, 20], 3 => + [:stop, 55] } will set a priority of twenty for run level two and a priority + of fifty-five for run level three. - property: reload_command ruby_type: String, false required: false @@ -163,6 +200,11 @@ properties_list: default_value: localsystem description_list: - markdown: The user under which a Microsoft Windows service runs. +- property: run_levels + ruby_type: Array + required: false + description_list: + - markdown: 'RHEL platforms only: Specific run_levels the service will run under.' - property: service_name ruby_type: String required: false @@ -204,26 +246,31 @@ properties_list: required: false default_value: '{"restart"=>nil, "reload"=>nil, "status"=>nil}' description_list: - - markdown: 'A list of properties that controls how Chef Infra Client is to - attempt to manage a service: `:restart`, `:reload`, `:status`. For - `:restart`, the init script or other service provider can use a - restart command; if `:restart` is not specified, Chef Infra Client - attempts to stop and then start a service. For `:reload`, the init - script or other service provider can use a reload command. For - `:status`, the init script or other service provider can use a - status command to determine if the service is running; if `:status` - is not specified, Chef Infra Client attempts to match the - `service_name` against the process table as a regular expression, - unless a pattern is specified as a parameter property. Default - value: `{ restart: false, reload: false, status: false }` for all - platforms (except for the Red Hat platform family, which defaults to - `{ restart: false, reload: false, status: true }`.)' + - markdown: 'A list of properties that controls how Chef Infra Client is to attempt + to manage a service: :restart, :reload, :status. For :restart, the init script + or other service provider can use a restart command; if :restart is not specified, + the chef-client attempts to stop and then start a service. For :reload, the + init script or other service provider can use a reload command. For :status, + the init script or other service provider can use a status command to determine + if the service is running; if :status is not specified, the chef-client attempts + to match the service_name against the process table as a regular expression, + unless a pattern is specified as a parameter property. Default value: { restart: + false, reload: false, status: false } for all platforms (except for the Red + Hat platform family, which defaults to { restart: false, reload: false, status: + true }.)' - property: timeout ruby_type: Integer required: false default_value: '60' description_list: - markdown: The amount of time (in seconds) to wait before timing out. +- property: user + ruby_type: String + required: false + new_in: '12.21' + description_list: + - markdown: 'systemd only: A username to run the service under.' +target_mode: examples: | **Starting Services** @@ -329,4 +376,4 @@ examples: | binary_path_name "C:\opscode\chef\bin" startup_type :manual end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/windows_share.yaml b/data/infra/resources/windows_share.yaml index be655454..dd6a61a3 100644 --- a/data/infra/resources/windows_share.yaml +++ b/data/infra/resources/windows_share.yaml @@ -117,6 +117,7 @@ properties_list: description_list: - markdown: The lifetime of the new SMB share. A temporary share does not persist beyond the next restart of the computer. +target_mode: examples: | **Create a share**: diff --git a/data/infra/resources/windows_shortcut.yaml b/data/infra/resources/windows_shortcut.yaml index 9a13f01b..70fa5b2c 100644 --- a/data/infra/resources/windows_shortcut.yaml +++ b/data/infra/resources/windows_shortcut.yaml @@ -65,6 +65,7 @@ properties_list: required: false description_list: - markdown: The destination that the shortcut links to. +target_mode: examples: | **Create a shortcut with a description**: @@ -73,4 +74,4 @@ examples: | target 'C:\original_dir' description 'Make a shortcut to C:\original_dir' end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/windows_task.yaml b/data/infra/resources/windows_task.yaml index 63f54662..d9e3c7e0 100644 --- a/data/infra/resources/windows_task.yaml +++ b/data/infra/resources/windows_task.yaml @@ -50,21 +50,23 @@ syntax_full_properties_list: `stop_if_going_on_batteries`, `task_name`, and `user` are the properties available to this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md :create: markdown: Creates a scheduled task, or updates an existing task if any property has changed. (default) :delete: markdown: Deletes a scheduled task. - :disable: - markdown: Disables a scheduled task. - :enable: - markdown: Enables a scheduled task. - :end: - markdown: Ends a scheduled task. - :nothing: - shortcode: resources_common_actions_nothing.md :run: markdown: Runs a scheduled task. + :end: + markdown: Ends a scheduled task. + :enable: + markdown: Enables a scheduled task. + :disable: + markdown: Disables a scheduled task. + :change: + markdown: properties_list: - property: backup ruby_type: Integer, false @@ -233,6 +235,7 @@ properties_list: default_value: The localized SYSTEM user for the node. description_list: - markdown: The user to run the task as. +target_mode: examples: | **Create a scheduled task to run every 15 minutes as the Administrator user**: diff --git a/data/infra/resources/windows_uac.yaml b/data/infra/resources/windows_uac.yaml index ee19bdad..013d7d10 100644 --- a/data/infra/resources/windows_uac.yaml +++ b/data/infra/resources/windows_uac.yaml @@ -74,6 +74,7 @@ properties_list: default_value: 'false' description_list: - markdown: Only elevate executables that are signed and validated. Sets HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System\EnableLUA\ValidateAdminCodeSignatures. +target_mode: examples: | **Disable UAC prompts for the admin**: diff --git a/data/infra/resources/windows_update_settings.yaml b/data/infra/resources/windows_update_settings.yaml index e86c0785..7b0cab1d 100644 --- a/data/infra/resources/windows_update_settings.yaml +++ b/data/infra/resources/windows_update_settings.yaml @@ -42,6 +42,8 @@ actions_list: shortcode: resources_common_actions_nothing.md :set: markdown: Set Windows Update settings. (default) + :enable: + markdown: properties_list: - property: automatic_update_option ruby_type: Integer, Symbol @@ -132,6 +134,7 @@ properties_list: required: false description_list: - markdown: The URL of your WSUS server if you use one. +target_mode: examples: | **Set Windows Update settings**: diff --git a/data/infra/resources/windows_user_privilege.yaml b/data/infra/resources/windows_user_privilege.yaml index 6b7767df..1a96626a 100644 --- a/data/infra/resources/windows_user_privilege.yaml +++ b/data/infra/resources/windows_user_privilege.yaml @@ -7,7 +7,7 @@ resource: windows_user_privilege resource_description_list: - markdown: |- Use the **windows_user_privilege** resource to set privileges for a principal, user, or group. - See [Microsoft's user rights assignment documentation](https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/user-rights-assignment) for more information. + See [Microsoft's user rights assignment documentation](https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/user-rights-assignment) for more information. resource_new_in: '16.0' syntax_full_code_block: |- windows_user_privilege 'name' do @@ -27,7 +27,7 @@ actions_list: :nothing: shortcode: resources_common_actions_nothing.md :add: - markdown: Add a privilege to a principal. (default) + markdown: Add a privileges to a principal. (default) :set: markdown: Set the privileges that are listed in the `privilege` property for only the users listed in the `users` property. All other users not listed with given @@ -35,28 +35,29 @@ actions_list: :clear: markdown: Clear all user privileges :remove: - markdown: Remove a privilege from a principal. + markdown: Remove a principal privilege properties_list: - property: principal ruby_type: String required: false default_value: The resource block's name description_list: - - markdown: An optional property to add the privilege for the specified principal. Use - only with add and remove action. The principal can either be a user, group, or - [special identity](https://learn.microsoft.com/en-us/windows-server/identity/ad-ds/manage/understand-special-identities-groups). + - markdown: An optional property to add the privilege for given principal. Use only + with add and remove action. Principal can either be a user, group, or [special + identity](https://docs.microsoft.com/en-us/windows/security/identity-protection/access-control/special-identities). - property: privilege ruby_type: Array, String required: true description_list: - - markdown: "One or more privileges to set for principal or users/groups. For more information, see - [Microsoft's privileges documentation](https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/user-rights-assignment)." + - markdown: One or more privileges to set for principal or users/groups. For more + information, see [Microsoft's documentation on what each privilege does](https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/user-rights-assignment). - property: users ruby_type: Array, String required: false description_list: - markdown: An optional property to set the privilege for the specified users. Use - only with `:set` action. + only with `:set` action +target_mode: examples: | **Set the SeNetworkLogonRight privilege for the Builtin Administrators and Authenticated Users groups**: @@ -106,7 +107,7 @@ examples: | ```ruby windows_user_privilege 'Create Pagefile' do privilege 'SeCreatePagefilePrivilege' - principal 'BUILTIN\\Guests' + principal 'BUILTIN\Guests' action :remove end ``` diff --git a/data/infra/resources/windows_workgroup.yaml b/data/infra/resources/windows_workgroup.yaml index bdf6f325..3d0ffe0e 100644 --- a/data/infra/resources/windows_workgroup.yaml +++ b/data/infra/resources/windows_workgroup.yaml @@ -58,6 +58,7 @@ properties_list: description_list: - markdown: An optional property to set the workgroup name if it differs from the resource block's name. +target_mode: examples: | **Join a workgroup**: diff --git a/data/infra/resources/yum_package.yaml b/data/infra/resources/yum_package.yaml index 6526f744..5f22c0c1 100644 --- a/data/infra/resources/yum_package.yaml +++ b/data/infra/resources/yum_package.yaml @@ -36,26 +36,30 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`allow_downgrade`, `arch`, `environment`, `flush_cache`, `options`, `package_name`, `source`, - `timeout`, `version`, and `yum_binary` are the properties available to this resource." +- "`allow_downgrade`, `arch`, `environment`, `flush_cache`, `options`, `package_name`, + `source`, `timeout`, `version`, and `yum_binary` are the properties available to + this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md :install: markdown: Install a package. If a version is specified, install the specified version of the package. (default) - :lock: - markdown: Locks the yum package to a specific version. + :upgrade: + markdown: Install a package and ensure that a package is the latest version. + :remove: + markdown: Remove a package. :purge: markdown: Purge a package. This action typically removes the configuration files as well as the package. - :remove: - markdown: Remove a package. - :nothing: - shortcode: resources_common_actions_nothing.md + :reconfig: + markdown: + :lock: + markdown: Locks the yum package to a specific version. :unlock: markdown: Unlocks the yum package so that it can be upgraded to a newer version. - :upgrade: - markdown: Install a package and/or ensure that a package is the latest version. - This action will ignore the `version` attribute. + :flush_cache: + markdown: properties_list: - property: allow_downgrade ruby_type: true, false @@ -82,19 +86,9 @@ properties_list: required: false default_value: '{"before"=>false, "after"=>false}' description_list: - - markdown: 'Flush the in-memory cache before or after a Yum operation that - installs, upgrades, or removes a package. Accepts a Hash in the - form: `{ :before =\> true/false, :after =\> true/false }` or an Array - in the form `[ :before, :after ]`.' - - shortcode: resources_common_package_yum_cache.md - - markdown: "As an array:\n\n```ruby\nyum_package 'some-package' do\n #...\n \ - \ flush_cache [ :before ]\n #...\nend\n```\n\nand as a Hash:\n\n```ruby\n\ - yum_package 'some-package' do\n #...\n flush_cache( { :after => true } )\n\ - \ #...\nend\n```" - - note: - markdown: 'The `flush_cache` property does not flush the local Yum cache! Use - Yum tools---`yum clean headers`, `yum clean packages`, - `yum clean all`---to clean the local Yum cache.' + - markdown: |- + Flush the in-memory cache before or after a Yum operation that installs, upgrades, or removes a package. Accepts a Hash in the form: { :before => true/false, :after => true/false } or an Array in the form [ :before, :after ]. + Yum automatically synchronizes remote metadata to a local cache. The chef-client creates a copy of the local cache, and then stores it in-memory during the chef-client run. The in-memory cache allows packages to be installed during the chef-client run without the need to continue synchronizing the remote metadata to the local cache while the chef-client run is in-progress. - property: options ruby_type: String, Array required: false @@ -105,9 +99,7 @@ properties_list: required: false description_list: - markdown: 'One of the following: the name of a package, the name of a package - and its architecture, the name of a dependency. Default value: the - `name` of the resource block. See "Syntax" section above for more - information.' + and its architecture, the name of a dependency.' - property: source ruby_type: String required: false @@ -129,6 +121,8 @@ properties_list: required: false description_list: - markdown: The path to the yum binary. +target_mode: + support: full examples: | **Install an exact version**: diff --git a/data/infra/resources/yum_repository.yaml b/data/infra/resources/yum_repository.yaml index 14882370..262a6f42 100644 --- a/data/infra/resources/yum_repository.yaml +++ b/data/infra/resources/yum_repository.yaml @@ -65,22 +65,26 @@ syntax_full_properties_list: the desired state." - "`baseurl`, `clean_metadata`, `cost`, `description`, `enabled`, `enablegroups`, `exclude`, `failovermethod`, `fastestmirror_enabled`, `gpgcheck`, `gpgkey`, `http_caching`, - `include_config`, `includepkgs`, `keepalive`, `make_cache`, `makecache_fast`, `max_retries`, `metadata_expire`, - `metalink`, `mirror_expire`, `mirrorlist`, `mirrorlist_expire`, `mode`, `options`, - `password`, `priority`, `proxy`, `proxy_password`, `proxy_username`, `repo_gpgcheck`, - `report_instanceid`, `reposdir`, `repositoryid`, `skip_if_unavailable`, `source`, - `sslcacert`, `sslclientcert`, `sslclientkey`, `sslverify`, `throttle`, `timeout`, - and `username` are the properties available to this resource." + `include_config`, `includepkgs`, `keepalive`, `make_cache`, `makecache_fast`, `max_retries`, + `metadata_expire`, `metalink`, `mirror_expire`, `mirrorlist`, `mirrorlist_expire`, + `mode`, `options`, `password`, `priority`, `proxy`, `proxy_password`, `proxy_username`, + `repo_gpgcheck`, `report_instanceid`, `reposdir`, `repositoryid`, `skip_if_unavailable`, + `source`, `sslcacert`, `sslclientcert`, `sslclientkey`, `sslverify`, `throttle`, + `timeout`, and `username` are the properties available to this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md :create: markdown: Create a repository based on the properties. (default) - :delete: - markdown: Remove a repository. + :remove: + markdown: :makecache: markdown: Force the creation of the repository cache. This is also done automatically when a repository is updated. - :nothing: - shortcode: resources_common_actions_nothing.md + :add: + markdown: + :delete: + markdown: Remove a repository. properties_list: - property: baseurl ruby_type: String, Array @@ -196,13 +200,12 @@ properties_list: By using cached data, you can carry out certain operations without a network connection. - property: makecache_fast - new_in: 18.1 ruby_type: true, false required: false default_value: 'false' description_list: - - markdown: If `make_cache` is `true`, this uses `yum makecache fast`, which downloads - only the minimum amount of data required. Useful over slower connections and when + - markdown: if make_cache is true, uses `yum makecache fast`, which downloads only + the minimum amount of data required. Useful over slower connections and when disk space is at a premium. - property: max_retries ruby_type: String, Integer @@ -379,6 +382,8 @@ properties_list: required: false description_list: - markdown: Username to use for basic authentication to a repository. +target_mode: + support: full examples: | **Add an internal company repository**: @@ -397,4 +402,4 @@ examples: | yum_repository 'CentOS-Media' do action :delete end - ``` \ No newline at end of file + ``` diff --git a/data/infra/resources/zypper_package.yaml b/data/infra/resources/zypper_package.yaml index ed890cca..79911e7c 100644 --- a/data/infra/resources/zypper_package.yaml +++ b/data/infra/resources/zypper_package.yaml @@ -12,6 +12,7 @@ resource_description_list: syntax_full_code_block: |- zypper_package 'name' do allow_downgrade true, false # default value: true + environment Hash global_options String, Array gpg_check true, false # default value: "true" options String, Array @@ -27,25 +28,27 @@ syntax_full_properties_list: - "`name` is the name given to the resource block." - "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state." -- "`allow_downgrade`, `global_options`, `gpg_check`, `options`, `package_name`, `source`, - `timeout`, and `version` are the properties available to this resource." +- "`allow_downgrade`, `environment`, `global_options`, `gpg_check`, `options`, `package_name`, + `source`, `timeout`, and `version` are the properties available to this resource." actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md :install: markdown: Install a package. If a version is specified, install the specified version of the package. (default) - :lock: - markdown: Locks the zypper package to a specific version. - :nothing: - shortcode: resources_common_actions_nothing.md + :upgrade: + markdown: Install a package and ensure that a package is the latest version. + :remove: + markdown: Remove a package. :purge: markdown: Purge a package. This action typically removes the configuration files as well as the package. - :remove: - markdown: Remove a package. + :reconfig: + markdown: + :lock: + markdown: Locks the zypper package to a specific version. :unlock: markdown: Unlocks the zypper package so that it can be upgraded to a newer version. - :upgrade: - markdown: Install a package and/or ensure that a package is the latest version. properties_list: - property: allow_downgrade ruby_type: true, false @@ -54,6 +57,13 @@ properties_list: new_in: '13.6' description_list: - markdown: Allow downgrading a package to satisfy requested version requirements. +- property: environment + ruby_type: Hash + required: false + new_in: '19.0' + description_list: + - markdown: A Hash of environment variables in the form of {'ENV_VARIABLE' => 'VALUE'} + to be set before running the command. - property: global_options ruby_type: String, Array required: false @@ -95,6 +105,8 @@ properties_list: required: false description_list: - markdown: The version of a package to be installed or upgraded. +target_mode: + support: full examples: | **Install a package using package manager:** diff --git a/data/infra/resources/zypper_repository.yaml b/data/infra/resources/zypper_repository.yaml index 3b184c06..3bcdfcbd 100644 --- a/data/infra/resources/zypper_repository.yaml +++ b/data/infra/resources/zypper_repository.yaml @@ -47,6 +47,8 @@ actions_list: markdown: Add a new Zypper repository. (default) :remove: markdown: Remove a Zypper repository. + :add: + markdown: :refresh: markdown: Refresh Zypper repository. properties_list: @@ -151,6 +153,8 @@ properties_list: default_value: NONE description_list: - markdown: Specifies the repository type. +target_mode: + support: full examples: | **Add the Apache repo on openSUSE Leap 15**: