diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 02fb352..09c49ee 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -38,7 +38,7 @@ jobs: - uses: carlosperate/download-file-action@v1.1.2 id: download-mdl-config with: - file-url: 'https://raw.githubusercontent.com/chef/chef-web-docs/main/.markdownlint.yaml' + file-url: 'https://raw.githubusercontent.com/chef/chef-client-docs/main/.markdownlint.yaml' file-name: 'markdownlint.yaml' - uses: DavidAnson/markdownlint-cli2-action@v5 with: @@ -57,7 +57,7 @@ jobs: - uses: actions/checkout@v3 - uses: errata-ai/vale-action@reviewdog with: - files: '["archetypes", "content", "layouts"]' - vale_flags: "--config=tools/vale/.vale-github-action.ini" + files: '["content", "layouts"]' + vale_flags: "--config=.vale.ini --minAlertLevel=error" filter_mode: diff_context fail_on_error: true diff --git a/.vale.ini b/.vale.ini index d243889..e38aae5 100644 --- a/.vale.ini +++ b/.vale.ini @@ -16,3 +16,6 @@ BasedOnStyles = chef, Microsoft, vale, write-good # Ignore SVG markup TokenIgnores = (\*\*\{\w*\}\*\*), (Master License and Services Agreement) + +# Modify rule alert levels +write-good.ThereIs = warning diff --git a/config/_default/menu.toml b/config/_default/menu.toml index 9a6ca75..69be5f2 100644 --- a/config/_default/menu.toml +++ b/config/_default/menu.toml @@ -60,35 +60,195 @@ title = "Install" identifier = "install" [[install]] - title = "Migration tool" - identifier = "install/migration_tool" + title = "Installer" + identifier = "install/installer" parent = "install" + weight = 20 [[install]] - title = "Native installer" - identifier = "install/installer" + title = "Migration Tool" + identifier = "install/migration_tool" parent = "install" + weight = 30 [[licensing]] title = "Licensing" identifier = "licensing" -[[agentless]] -title = "Agentless" -identifier = "agentless" - -[[workstation]] -title = "Chef Workstation" -identifier = "workstation" - - [[workstation]] - title = "Knife" - identifier = "workstation/knife" - parent = "workstation" - weight = 100 - - [[workstation]] - title = "Test Kitchen Enterprise" - identifier = "workstation/tke" - parent = "workstation" - weight = 200 +[[features]] +title = "Features" +identifier = "features" + + [[features]] + title = "Agentless Mode" + identifier = "features/agentless" + parent = "features" + + [[features]] + title = "Resources" + identifier = "features/agentless/resources" + parent = "features/agentless" + weight = 40 + + [[features]] + title = "Chef Solo" + identifier = "features/chef_solo" + parent = "features" + + [[features]] + title = "Ohai" + identifier = "features/ohai" + parent = "features" + +[[integrations]] +title = "Integrations" +identifier = "integrations" + + [[integrations]] + title = "Azure" + identifier = "integrations/azure" + parent = "integrations" + + [[integrations]] + title = "Windows" + identifier = "integrations/windows" + parent = "integrations" + +[[policy]] +title = "Policy" +identifier = "policy" + +[[security]] +title = "Security" +identifier = "security" + +[[cookbooks]] +title = "Cookbooks" +identifier = "cookbooks" + + [[cookbooks]] + title = "Attributes" + identifier = "cookbooks/attributes" + parent = "cookbooks" + weight = 30 + + [[cookbooks]] + title = "Recipes" + identifier = "cookbooks/recipes" + parent = "cookbooks" + weight = 70 + +[[infra_language]] +title = "Infra language" +identifier = "infra_language" + +[[resources]] +title = "Resources" +identifier = "resources" + + [[resources]] + title = "Bundled resources" + parent = "resources" + identifier = "resources/bundled" + + [[resources]] + title = "Custom resources" + parent = "resources" + identifier = "resources/custom" + +[[extension_apis]] +title = "Extension APIs" +identifier = "extension_apis" + + [[extension_apis]] + title = "Compliance DSL" + identifier = "extension_apis/inspec/dsl_inspec/ Compliance DSL" + parent = "extension_apis" + url = "https://docs.chef.io/inspec/latest/profiles/controls/" + weight = 20 + + [[extension_apis]] + title = "Handlers" + identifier = "extension_apis/handlers" + parent = "extension_apis" + weight = 20 + + [[extension_apis]] + title = "Custom handlers" + identifier = "extension_apis/handlers/handlers.md#custom-handlers Custom Handlers" + parent = "extension_apis/handlers" + url = "/features/handlers/#custom-handlers" + weight = 10 + + [[extension_apis]] + title = "Community handlers" + identifier = "extension_apis/handlers/plugin_community.md#handlers Community Handlers" + parent = "extension_apis/handlers" + url = "/extension_apis/community_plugins/#handlers" + weight = 30 + + [[extension_apis]] + title = "Ohai plugins" + identifier = "extension_apis/ohai_plugins" + parent = "extension_apis" + weight = 40 + +[[reference]] +title = "Reference" +identifier = "reference" + + [[reference]] + title = "chef-solo (executable)" + identifier = "reference/ctl_chef_solo.md chef-solo (executable)" + parent = "reference" + url = "/features/chef_solo/ctl_chef_solo/" + weight = 20 + + [[reference]] + title = "Handler DSL" + identifier = "reference/dsl_handler.md Handler Commands" + parent = "reference" + url = "/extension_apis/dsl_handler/" + weight = 40 + + [[reference]] + title = "ohai (executable)" + identifier = "reference/ctl_ohai.md ohai (executable)" + parent = "reference" + url = "/features/ohai/ctl_ohai/" + weight = 50 + + [[reference]] + title = "supermarket-ctl" + identifier = "supermarket/reference/ctl_supermarket.md supermarket-ctl" + parent = "reference" + url = "https://docs.chef.io/supermarket/ctl_supermarket/" + weight = 60 + + [[reference]] + title = "client.rb" + identifier = "reference/config_rb_client.md client.rb" + parent = "reference" + url = "/install/config_rb_client/" + weight = 70 + + [[reference]] + title = "metadata.rb" + identifier = "reference/config_rb_metadata.md metadata.rb" + parent = "reference" + url = "/cookbooks/config_rb_metadata/" + weight = 80 + + [[reference]] + title = "Policyfile.rb" + identifier = "reference/config_rb_policyfile.md Policyfile.rb" + parent = "reference" + url = "/policy/config_rb_policyfile/" + weight = 90 + + [[reference]] + title = "solo.rb" + identifier = "reference/config_rb_solo.md solo.rb" + parent = "reference" + url = "/install/config_rb_solo/" + weight = 100 \ No newline at end of file diff --git a/config/_default/params.toml b/config/_default/params.toml index 17a1a85..c0adf98 100644 --- a/config/_default/params.toml +++ b/config/_default/params.toml @@ -7,7 +7,22 @@ # Menus are defined in the /config/_default/menu.toml file ####### -menuOrder = ["landing_page", "install", "licensing", "agentless", "workstation", "resources", "chef_gem_server", "cookbooks", "reference", "release_notes"] +menuOrder = [ + "overview", + "install", + "licensing", + "quickstart", + "features", + "policy", + "integrations", + "security", + "cookbooks", + "infra_language", + "resources", + "extension_apis", + "troubleshooting", + "reference" +] ####### # robots = The default robots config applied to each page in the robots meta tag. @@ -26,6 +41,10 @@ robots = '' ####### breadcrumbs = true +[[breadcrumb_base]] +breadcrumb = "Documentation" +url = "https://docs.chef.io" + ####### # # Settings for the link and image render hooks. diff --git a/config/branch-deploy/params.toml b/config/branch-deploy/params.toml index 71a82e2..8b13789 100644 --- a/config/branch-deploy/params.toml +++ b/config/branch-deploy/params.toml @@ -1,5 +1 @@ -breadcrumbs = true -[[breadcrumb_base]] -breadcrumb = "Docs" -url = "https://docs.chef.io" diff --git a/config/vocabularies/Chef/accept.txt b/config/vocabularies/Chef/accept.txt new file mode 100644 index 0000000..427adc8 --- /dev/null +++ b/config/vocabularies/Chef/accept.txt @@ -0,0 +1,2 @@ +Chef Backend +[B|b]ackend diff --git a/content/_index.md b/content/_index.md index 64ee005..1158130 100644 --- a/content/_index.md +++ b/content/_index.md @@ -1,5 +1,5 @@ +++ -title = "Chef Infra Client 19 RC3" +title = "Chef Infra Client" linkTitle = "Chef Infra Client" [cascade] @@ -7,49 +7,89 @@ linkTitle = "Chef Infra Client" breadcrumbs = true st_robots = '' -[menu.landing_page] -title = "Chef Infra Client" +[menu.overview] + title = "Chef Infra Client" + identifier = "overview/Client Overview" + parent = "overview" + weight = 10 +++ -To provide enterprise stability, Progress Chef has created a [Long Term Support (LTS) model](https://www.chef.io/blog/long-term-support-progress-chef-providing-stability) for products. -Chef Infra Client 19 is the first LTS version for infrastructure management and compliance mode. -This release---Release Candidate 3 (RC3)---is a preview for a limited audience to provide candid feedback on Chef Infra Client, -the new Infra Client migration tool, and updated Test Kitchen developer tools to ensure a seamless transition at the time of general availability (GA). +Chef Infra Client is an agent that runs locally on every node that's under management by Chef Infra Server. +Chef Infra Client transforms your infrastructure into code by automatically configuring systems to match your desired state. + +When Chef Infra Client runs, it performs all the steps required to bring a node into the expected state, including: + +- Registering and authenticating the node with Chef Infra Server +- Synchronizing cookbooks from Chef Infra Server to the node +- Compiling the resource collection by loading each of the required cookbooks, including recipes, attributes, and all other dependencies +- Taking the appropriate and required actions to configure the node based on recipes and attributes +- Reporting summary information on the run to Chef Automate + +## Chef Infra Client components + +Chef Infra Client works with key components to manage your infrastructure: + +### Compliance Phase + +The Compliance Phase is an integrated security and compliance feature that runs Chef InSpec profiles automatically as part of every Chef Infra Client run. +This phase allows you to continuously audit your infrastructure for compliance with security policies and regulatory requirements without managing separate tools or processes. + +For detailed information, see [About the Compliance Phase](/features/chef_compliance_phase/). + +### Node + +A node represents any system that Chef Infra Client manages - whether it's a virtual machine, container instance, or physical server. +Every node runs Chef Infra Client and maintains its configuration state according to the policies you define. + +### Cookbooks and recipes + +Cookbooks contain the instructions (recipes) that tell Chef Infra Client how to configure your systems. +Recipes use resources to describe the desired state of system components like packages, files, and services. + +### Run list + +The run list defines which cookbooks and recipes Chef Infra Client should execute on a node and in what order. +You can customize run lists for different node types or environments. + +### Ohai + +Ohai is a system profiling tool that collects detailed information about your nodes, including hardware details, network configuration, and operating system data. +Chef Infra Client uses this information to make intelligent configuration decisions. + +### Agentless -The new Chef Infra Client migration tool simplifies the transition from previous methods of installing and maintaining earlier versions of Infra Client to Chef Infra Client 19 release candidates and the final LTS version. +Agentless allows you to execute Infra Client runs on a target node over SSH without having Chef Infra Client installed on the node. -The new Test Kitchen Enterprise bundle is a fully Chef-maintained version of Test Kitchen that will be part of Chef Workstation at the time of release. +For more details and setup instructions, see the [Agentless documentation](/features/agentless/). -**Important:** Use Chef Infra Client 19 RC3 in non-production environments to verify existing deployment patterns and content against customer-specific infrastructure platforms. +## How Chef Infra Client works -## Supported environments +Chef Infra Client operates on a pull-based model where nodes periodically contact Chef Infra Server to retrieve their configuration policies. +This approach ensures that your infrastructure remains in the desired state even if individual nodes experience temporary disconnections or issues. -Chef Infra Client RC3 supports testing in non-production environments on Linux and Windows x86-64 systems. -Agentless Mode and Chef Workstation 26 RC3 are supported on Linux systems. +## Common use cases -This release allows you to: +You can use Chef Infra Client to automate infrastructure management tasks: -- Determine if the migration tool can upgrade your infrastructure to Chef Infra Client 19 -- Gain familiarity with Habitat-based builds -- Prepare for new licensing requirements +- **Server provisioning**: Automatically configure new servers with required software and settings +- **Application deployment**: Deploy and configure applications across different environments +- **Security compliance**: Enforce security policies and compliance requirements +- **Configuration drift prevention**: Continuously check and correct configuration changes +- **Environment management**: Maintain consistent configurations across development, staging, and production environments -## Key features +## The Chef Infra Client run -Chef Infra Client 19 has the following key features: +{{< readfile file="content/reusable/md/chef_client_run.md" >}} -- **Long-term support (LTS):** Chef Infra Client 19 uses Habitat-based packaging instead of traditional omnibus builds. -- **Test Kitchen Enterprise:** A foundational development tool for testing cookbooks and profiles across versions of Chef Infra Client. - Chef InSpec receives full support from Chef in a modularized Chef Workstation toolkit. -- **Standard licensing:** Infra Client 19 and Test Kitchen Enterprise use standard licensing for commercial, community, and trial customers. -- **Enhanced performance:** Chef InSpec resource packs will be modularized to improve performance. -- **Migration tool:** The Chef Infra Client migration tool installs and upgrades from previous versions to Chef Infra 19, supporting side-by-side installations. +## Related content -## Important changes +- [Chef Infra Client (executable)](/reference/ctl_chef_client/) +- [Chef Infra Server](https://docs.chef.io/server/) +- [Cookbooks](/cookbooks/) +- [Nodes](/overview/nodes/) +- [Run Lists](/policy/run_lists/) -Customers moving to Chef Infra Client 19 should be aware of these significant changes: +## Next steps -- **Platform support:** RC3 supports Linux and Windows x86-64 infrastructure. Future releases will expand support to include traditional Chef platforms. -- **Packaging changes:** Chef no longer provides Omnibus builds for Infra Client and associated tools. -- **New packaging options:** Chef now offers OS-native and Habitat-based packaging. -- **Modular components:** Chef Workstation components become modularized to provide better support for individual tools. -- **InSpec changes:** Chef InSpec resource packs become modularized for InSpec as part of the InSpec 7 LTS release (separate from the Infra Client LTS release). +- [Install Chef Workstation](https://docs.chef.io/workstation/install_workstation/) +- [Bootstrap Nodes](/install/install_bootstrap/) diff --git a/content/agentless/resources/_index.md b/content/agentless/resources/_index.md deleted file mode 100644 index 6aa2893..0000000 --- a/content/agentless/resources/_index.md +++ /dev/null @@ -1,106 +0,0 @@ -+++ -title = "Supported Chef Infra resources in Agentless Mode" -linkTitle = "Resources" - -[menu.agentless] -title = "Supported resources" -identifier = "agentless/resources/overview" -parent = "agentless" -weight = 10 -+++ - -The following Chef Infra resources are supported in Agentless Mode. - -| **Resources Name** | **Verified Platforms** | **Remarks** | -|---|---|---| -| [alternatives](https://docs.chef.io/resources/alternatives/) | Ubuntu, Linux | | -| [apt_package](https://docs.chef.io/resources/apt_package/) | Ubuntu | | -| [apt_preference](https://docs.chef.io/resources/apt_preference/) | Ubuntu, Linux | | -| [apt_repository](https://docs.chef.io/resources/apt_repository/) | Ubuntu, Linux | | -| [apt_update](https://docs.chef.io/resources/apt_update/) | Ubuntu, Linux | | -| [bash](https://docs.chef.io/resources/bash/) | Ubuntu, Linux, Solaris, Alpine, SUSE | | -| [breakpoint](https://docs.chef.io/resources/breakpoint/) | Ubuntu, Linux | | -| [chef_acl](https://docs.chef.io/resources/chef_acl/) | Ubuntu, Linux, CentOS 9 | | -| [chef_client](https://docs.chef.io/resources/chef_client/) | Ubuntu 24.04, Linux Red Hat 9, Solaris, Alpine, SUSE | | -| [chef_client_config](https://docs.chef.io/resources/chef_client_config/) | Ubuntu, Linux, Solaris, Alpine, SUSE | | -| [chef_container](https://docs.chef.io/resources/chef_container/) | Ubuntu, Linux | | -| [chef_data_bag](https://docs.chef.io/resources/chef_data_bag/) | Ubuntu, Linux | | -| [chef_environment](https://docs.chef.io/resources/chef_environment/) | Ubuntu, Linux | | -| [chef_group](https://docs.chef.io/resources/chef_group/) | Ubuntu 24.04 and 18.04, RHEL | | -| [chef_node](https://docs.chef.io/resources/chef_node/) | Ubuntu 24.04, Linux Red Hat 9 | | -| [chef_organization](https://docs.chef.io/resources/chef_organization/) | Ubuntu 24.04 and 18.04, RHEL | | -| [chef_role](https://docs.chef.io/resources/chef_role/) | Ubuntu 24.04, Linux Red Hat 9, Solaris, Alpine, SUSE | | -| [chef_sleep](https://docs.chef.io/resources/chef_sleep/) | Ubuntu, Linux | | -| [chef_user](https://docs.chef.io/resources/chef_user/) | Ubuntu 24.04 and 18.04, RHEL, Solaris, Alpine, SUSE | | -| [cookbook_file](https://docs.chef.io/resources/cookbook_file/) | Ubuntu, Linux, Solaris, Alpine, SUSE | | -| [cron](https://docs.chef.io/resources/cron/) | Ubuntu, Linux, Solaris SunOS, Alpine | | -| [cron_access](https://docs.chef.io/resources/cron_access/) | Ubuntu, Linux, Solaris SunOS, Alpine | | -| [cron_d](https://docs.chef.io/resources/cron_d/) | Ubuntu, Linux | | -| [csh](https://docs.chef.io/resources/csh/) | Ubuntu 24.04, Linux Red Hat 9, Alpine | | -| [directory](https://docs.chef.io/resources/directory/) | Ubuntu, Linux, Solaris, Alpine, SUSE | | -| [execute](https://docs.chef.io/resources/execute/) | Ubuntu, Linux, Solaris, Alpine, SUSE | | -| [file](https://docs.chef.io/resources/file/) | Ubuntu, Linux, Solaris, Alpine, SUSE | | -| [freebsd_package](https://docs.chef.io/resources/freebsd_package/) | FreeBSD 14 | Only supported on FreeBSD. | -| [git](https://docs.chef.io/resources/git/) | Ubuntu, Linux, Solaris, Alpine, SUSE | | -| [group](https://docs.chef.io/resources/group/) | Ubuntu, Linux, Solaris, Alpine, SUSE | | -| [habitat_config](https://docs.chef.io/resources/habitat_config/) | Ubuntu 24.04, Linux Red Hat 9, Solaris, Alpine, SUSE | | -| [habitat_install](https://docs.chef.io/resources/habitat_install/) | Ubuntu, Linux, Solaris, Alpine, SUSE | | -| [habitat_package](https://docs.chef.io/resources/habitat_package/) | Ubuntu, Linux, Solaris, Alpine, SUSE | | -| [habitat_service](https://docs.chef.io/resources/habitat_service/) | Ubuntu, Linux | | -| [habitat_sup](https://docs.chef.io/resources/habitat_sup/) | Ubuntu, Linux | | -| [hostname](https://docs.chef.io/resources/hostname/) | Ubuntu, Linux | | -| [http_request](https://docs.chef.io/resources/http_request/) | Ubuntu, Linux, , Solaris, Alpine, SUSE | | -| [ifconfig](https://docs.chef.io/resources/ifconfig/) | Ubuntu, Linux | | -| [inspec_input](https://docs.chef.io/resources/inspec_input/) | Ubuntu 24.04, Linux Red Hat 9 | | -| [inspec_waiver](https://docs.chef.io/resources/inspec_waiver/) | Ubuntu, Linux | | -| [inspec_waiver_file_entry](https://docs.chef.io/resources/inspec_waiver_file_entry/) | Ubuntu, Linux | | -| [kernel_module](https://docs.chef.io/resources/kernel_module/) | Ubuntu, Linux | | -| [ksh](https://docs.chef.io/resources/ksh/) | Ubuntu 24.04, Linux Red Hat 9, Solaris, Alpine, SUSE | | -| [link](https://docs.chef.io/resources/link/) | Ubuntu, Linux, Solaris, Alpine, SUSE | | -| [locale](https://docs.chef.io/resources/locale/) | Ubuntu | | -| [log](https://docs.chef.io/resources/log/) | Ubuntu, Linux, Solaris, Alpine, SUSE | | -| [mount](https://docs.chef.io/resources/mount/) | Ubuntu 24.04, CentOS 9 | | -| [notify_group](https://docs.chef.io/resources/notify_group/) | Ubuntu, Linux | | -| [ohai](https://docs.chef.io/resources/ohai/) | Ubuntu, Linux | | -| [ohai_hint](https://docs.chef.io/resources/ohai_hint/) | Ubuntu, Linux | | -| [owner](https://docs.chef.io/resources/owner/) | Ubuntu, Linux, Solaris, Alpine, SUSE | | -| [package](https://docs.chef.io/resources/package/) | Ubuntu, Linux, CentOS 9, Solaris, Alpine, SUSE | | -| [perl](https://docs.chef.io/resources/perl/) | Ubuntu | | -| [python](https://docs.chef.io/resources/python/) | Ubuntu 24.04, Linux Red Hat 9, Solaris, Alpine, SUSE | | -| [reboot](https://docs.chef.io/resources/reboot/) | Ubuntu, Linux | | -| [remote_file](https://docs.chef.io/resources/remote_file/) | Ubuntu, Linux, CentOS 9, Solaris, Alpine, SUSE | | -| [rhsm_errata](https://docs.chef.io/resources/rhsm_errata/) | Linux (redhat) | | -| [rhsm_errata_level](https://docs.chef.io/resources/rhsm_errata_level/) | Linux (redhat) | | -| [rhsm_register](https://docs.chef.io/resources/rhsm_register/) | Linux (redhat) | | -| [rhsm_repo](https://docs.chef.io/resources/rhsm_repo/) | Linux (redhat) | | -| [rhsm_subscription](https://docs.chef.io/resources/rhsm_subscription/) | Linux (redhat) | | -| [route](https://docs.chef.io/resources/route/) | Ubuntu 24.04 / CentOS 9 | | -| [rpm_package](https://docs.chef.io/resources/rpm_package/) | CentOS 9 | The RPM package must be locally available on the remote system. | -| [ruby_block](https://docs.chef.io/resources/ruby_block/) | Ubuntu, Linux, CentOS 9 | | -| [script](https://docs.chef.io/resources/script/) | Ubuntu 24.04, Linux Red Hat 9, , Solaris, Alpine | | -| [selinux_boolean](https://docs.chef.io/resources/selinux_boolean/) | Ubuntu, Linux | | -| [selinux_fcontext](https://docs.chef.io/resources/selinux_fcontext/) | Ubuntu, Linux | | -| [selinux_install](https://docs.chef.io/resources/selinux_install/) | Ubuntu, Linux | | -| [selinux_login](https://docs.chef.io/resources/selinux_login/) | Ubuntu, Linux | | -| [selinux_module](https://docs.chef.io/resources/selinux_module/) | Ubuntu, Linux | | -| [selinux_permissive](https://docs.chef.io/resources/selinux_permissive/) | Ubuntu, Linux | | -| [selinux_port](https://docs.chef.io/resources/selinux_port/) | Ubuntu, Linux | | -| [selinux_state](https://docs.chef.io/resources/selinux_state/) | Ubuntu, Linux | | -| [selinux_user](https://docs.chef.io/resources/selinux_user/) | Ubuntu, Linux | | -| [service](https://docs.chef.io/resources/service/) | Ubuntu, Linux, CentOS 9, Solaris, Alpine, SUSE | `crond` for Linux | -| [snap_package](https://docs.chef.io/resources/snap_package/) | Ubuntu 24.04 | Only supported on Linux. | -| [ssh_known_hosts_entry](https://docs.chef.io/resources/ssh_known_hosts_entry/) | Ubuntu, Linux | | -| [subversion](https://docs.chef.io/resources/subversion/) | Ubuntu 24.04, Linux Red Hat 9, CentOS 9 | The subversion resource has known bugs and may not work as expected. For more information, see the Chef GitHub issues, particularly [#4050](https://github.com/chef/chef/issues/4050) and [#4257](https://github.com/chef/chef/issues/4257). | -| [sudo](https://docs.chef.io/resources/sudo/) | Ubuntu, Linux, CentOS 9, Solaris, Alpine, SUSE | | -| [swap_file](https://docs.chef.io/resources/swap_file/) | Ubuntu, Linux | | -| [sysctl](https://docs.chef.io/resources/sysctl/) | Ubuntu, Linux | | -| [systemd_unit](https://docs.chef.io/resources/systemd_unit/) | Ubuntu, Linux | | -| [template](https://docs.chef.io/resources/template/) | Ubuntu, Linux, CentOS 9, Solaris, Alpine, SUSE | Require absolute path for source attribute. | -| [timezone](https://docs.chef.io/resources/timezone/) | Linux, Solaris, Alpine, SUSE | | -| [user](https://docs.chef.io/resources/user/) | Ubuntu, Linux | | -| [user_ulimit](https://docs.chef.io/resources/user_ulimit/) | Ubuntu, Linux | | -| [yum_package](https://docs.chef.io/resources/yum_package/) | CentOS 9 | Only supported on Linux. | -| [yum_repository](https://docs.chef.io/resources/yum_repository/) | Linux | | -| [yum_repository](https://docs.chef.io/resources/yum_repository/) | CentOS 9, RHEL 8 | Only supported on Linux. | -| [zypper_package](https://docs.chef.io/resources/zypper_package/) | SUSE Linux 15 | | -| [solaris_package](https://docs.chef.io/resources/solaris_package/) | Solaris | | diff --git a/content/cookbooks.md b/content/cookbooks.md deleted file mode 100644 index 59c5262..0000000 --- a/content/cookbooks.md +++ /dev/null @@ -1,8 +0,0 @@ -+++ -title = "Sample cookbook" - -[menu.cookbooks] -title = "Sample cookbook" -+++ - -You can test Chef Infra Client 19 RC3 using a basic cookbook in the [infra-19-rc1-examples](https://github.com/chef/infra-19-rc1-examples/) repository. This includes a recipe that allows you to test Agentless Mode. diff --git a/content/cookbooks/_index.md b/content/cookbooks/_index.md new file mode 100644 index 0000000..a356426 --- /dev/null +++ b/content/cookbooks/_index.md @@ -0,0 +1,102 @@ ++++ +title = "About Cookbooks" +draft = false + +[menu] + [menu.cookbooks] + title = "About Cookbooks" + identifier = "cookbooks/cookbooks.md About Cookbooks" + parent = "cookbooks" + weight = 10 ++++ + +{{< readfile file="content/reusable/md/cookbooks_summary.md" >}} + +{{< readfile file="content/reusable/md/infra_lang_ruby.md" >}} + +{{< readfile file="content/reusable/md/infra_lang_summary.md" >}} + +Chef Infra Client runs a recipe only when instructed. When Chef Infra Client runs the same recipe more than once, the results will be the same system state each time. When a recipe is run against a system, but nothing has changed on either the system or in the recipe, Chef Infra Client won't change anything. + +## Components + +A cookbook is comprised of recipes and other optional components as files or directories. + +[Recipes](recipes) +: Directory: `recipes/` + + {{< readfile file="content/reusable/md/cookbooks_recipe.md" >}} + +[Attributes](attributes) +: Directory: `attributes/` + + {{< readfile file="content/reusable/md/cookbooks_attribute.md" >}} + +[Files](files) +: Directory: `files/` + + A file distribution is a specific type of resource that tells a cookbook how to distribute files, including by node, by platform, or by file version. + +[Libraries](libraries) +: Directory: `libraries/` + + A library allows the use of arbitrary Ruby code in a cookbook, either as a way to extend the Chef Infra Client language or to implement a new class. + +[Custom Resources](/resources/custom/) +: Directory: `resources/` + + A custom resource is an abstract approach for defining a set of actions and (for each action) a set of properties and validation parameters. + +[Templates](templates) +: Directory: `templates/` + + A template is a file written in markup language that uses Ruby statements to solve complex configuration scenarios. + +[Ohai Plugins](/extension_apis/custom_plugins/) +: Directory: `ohai/` + + Custom Ohai plugins can be written to load additional information about your nodes to be used in recipes. This requires Chef Infra Server 12.18.14 or later. + +[Metadata](config_rb_metadata) +: File: `metadata.rb` + + This file contains information about the cookbook such as the cookbook name, description, and version. + +## Community Cookbooks + +Chef maintains a large collection of cookbooks. In addition, there are thousands of cookbooks created and maintained by the community: + +| Components | Description | +|:------------------------------------------------------------------------------:|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------:| +| [Cookbooks Maintained by Chef](https://github.com/chef-cookbooks) | Chef maintains a collection of cookbooks that are widely used by the community. | +| [Cookbooks Maintained by Sous Chefs](https://github.com/sous-chefs) | Sous Chefs is a community organization that collaborates to maintain many of the most used Chef cookbooks. | +| [Cookbooks Maintained by the Community](https://supermarket.chef.io/cookbooks) | The community has authored thousands of cookbooks, ranging from niche cookbooks that are used by only a few organizations to popular cookbooks used by almost everyone. | + +## Generate a Cookbook + +Use the [chef generate cookbook subcommand](https://docs.chef.io/workstation/ctl_chef/#chef-generate-cookbook) to generate a cookbook. + +A cookbook generated with`chef generate cookbook custom_web` creates a cookbook named `custom_web` with the directory structure: + +```text +. cookbooks +└── custom_web + ├── CHANGELOG.md + ├── LICENSE + ├── Policyfile.rb + ├── README.md + ├── chefignore + ├── compliance + │ ├── README.md + │ ├── inputs + │ ├── profiles + │ └── waivers + ├── kitchen.yml + ├── metadata.rb + ├── recipes + │ └── default.rb + └── test + └── integration + └── default + └── default_test.rb +``` diff --git a/content/cookbooks/attributes/_index.md b/content/cookbooks/attributes/_index.md new file mode 100644 index 0000000..8e99e2c --- /dev/null +++ b/content/cookbooks/attributes/_index.md @@ -0,0 +1,13 @@ ++++ +title = "About Attributes" +draft = false + +[menu] + [menu.cookbooks] + title = "Attributes" + identifier = "cookbooks/attributes/attributes.md Attributes" + parent = "cookbooks/attributes" + weight = 10 ++++ + +{{< readfile file="content/reusable/md/node_attribute.md" >}} diff --git a/content/cookbooks/attributes/attribute_arrays.md b/content/cookbooks/attributes/attribute_arrays.md new file mode 100644 index 0000000..6b404af --- /dev/null +++ b/content/cookbooks/attributes/attribute_arrays.md @@ -0,0 +1,210 @@ ++++ +title = "Attribute Arrays" +description = "Define multiple attributes in an array or hash and deep merge" +draft = false + +[menu] + [menu.cookbooks] + title = "Attributes Arrays" + identifier = "cookbooks/attributes/attribute_arrays Attribute Arrays" + parent = "cookbooks/attributes" ++++ + + + +Attributes are typically defined in cookbooks, recipes, roles, and environments. +These attributes are rolled up to the node level during a Chef Infra Client run. +A recipe can store attribute values using a multi-level hash or array. + +For example, a group of attributes for web servers might be: + +```ruby +override_attributes( + :apache => { + :listen_ports => [ 80 ], + :prefork => { + :startservers => 20, + :minspareservers => 20, + :maxspareservers => 40 + } + } +) +``` + +But, what if all of the web servers aren't the same or require a single attribute to have a different value? +You could store these settings in two locations: one like the preceding example and one like the following: + +```ruby +override_attributes( + :apache => { + :listen_ports => [ 80 ], + :prefork => { + :startservers => 30, + :minspareservers => 20, + :maxspareservers => 40 + } + } +) +``` + +But that isn't efficient, especially because most of them are identical. + +Chef Infra Client's deep merge capabilities allow you to layer attributes across cookbooks, recipes, roles, and environments. +This allows an attribute to be reused across nodes, making use of default attributes set at the cookbook level, while also providing a way for certain attributes (with a higher attribute precedence) to be applied only when they're needed. + +For example, you can have a role named `baseline.rb`: + +```ruby +name "baseline" +description "The most basic role for all configurations" +run_list "recipe[baseline]" + +override_attributes( + :apache => { + :listen_ports => [ 80 ], + :prefork => { + :startservers => 20, + :minspareservers => 20, + :maxspareservers => 40 + } + } +) +``` + +and a role named `web.rb`: + +```ruby +name 'web' +description 'Web server config' +run_list 'role[baseline]' + +override_attributes( + :apache => { + :prefork => { + :startservers => 30 + } + } +) +``` + +The `web.rb` role references the `baseline.rb` role. +The `web.rb` file only provides a value for one attribute: `:startservers`. +When Chef Infra Client compares these attributes, the deep merge feature ensures that `:startservers` (and its value of `30`) is applied to any node for which the `web.rb` attribute structure should be applied. + +This approach allows a recipe like this: + +```ruby +include_recipe 'apache2' +Chef::Log.info(node['apache']['prefork'].to_hash) +``` + +and a `run_list` like this: + +```ruby +run_list/web.json +{ + "run_list": [ "role[web]" ] +} +``` + +to produce results like this: + +```ruby +[Tue, 16 Aug 2011 14:44:26 -0700] INFO: + { + "startservers"=>30, + "minspareservers"=>20, + "maxspareservers"=>40, + "serverlimit"=>400, + "maxclients"=>400, + "maxrequestsperchild"=>10000 + } +``` + +Even though the `web.rb` file doesn't contain attributes and values for `minspareservers`, `maxspareservers`, `serverlimit`, `maxclients`, and `maxrequestsperchild`, the deep merge capabilities pulled them in. + +## Attribute array logic + +The following sections show how the logic works for using deep merge to perform substitutions and additions of attributes. + +When an attribute value is a hash, that data is merged. +When an attribute value is an array, if the attribute precedence levels are the same, then that data is merged. +If the attribute value precedence levels in an array are different, then that data is replaced. +For all other value types (such as strings or integers), that data is replaced. + +### Substitution + +The following examples show how the logic works for substituting an existing string using a hash: + +```text +role_or_environment 1 { :x => '1', :y => '2' } ++ +role_or_environment 2 { :y => '3' } += +{ :x => '1', :y => '3' } +``` + +For substituting an existing boolean using a hash: + +```text +role_or_environment 1 { :x => true, :y => false } ++ +role_or_environment 2 { :y => true } += +{ :x => true, :y => true } +``` + +For substituting an array with a hash: + +```text +role_or_environment 1 [ '1', '2', '3' ] ++ +role_or_environment 2 { :x => '1' , :y => '2' } += +{ :x => '1', :y => '2' } +``` + +When items can't be merged through substitution, the original data is overwritten. + +### Addition + +The following examples show how the logic works for adding a string +using a hash: + +```text +role_or_environment 1 { :x => '1', :y => '2' } ++ +role_or_environment 2 { :z => '3' } += +{ :x => '1', :y => '2', :z => '3' } +``` + +For adding a string using an array: + +```text +role_or_environment 1 [ '1', '2' ] ++ +role_or_environment 2 [ '3' ] += +[ '1', '2', '3' ] +``` + +For adding a string using a multi-level hash: + +```text +role_or_environment 1 { :x => { :y => '2' } } ++ +role_or_environment 2 { :x => { :z => '3' } } += +{ :x => { :y => '2', :z => '3' } } +``` + +For adding a string using a multi-level array: + +```text +role_or_environment 1 [ [ 1, 2 ] ] ++ +role_or_environment 2 [ [ 3 ] ] += +[ [ 1, 2 ], [ 3 ] ] +``` diff --git a/content/cookbooks/attributes/attribute_persistence.md b/content/cookbooks/attributes/attribute_persistence.md new file mode 100644 index 0000000..8873178 --- /dev/null +++ b/content/cookbooks/attributes/attribute_persistence.md @@ -0,0 +1,114 @@ ++++ +title = "Attribute Persistence" +draft = false + +[menu] + [menu.cookbooks] + title = "Attribute Persistence" + identifier = "cookbooks/attributes/attribute_persistence.md Attributes" + parent = "cookbooks/attributes" ++++ + +All attributes, except for normal attributes, are reset at the beginning of a Chef Infra Client run. +Attributes set using `chef-client -j` with a JSON file have normal precedence and are persisted between Chef Infra Client runs. +Chef Infra Client rebuilds these attributes using automatic attributes collected by Ohai at the beginning of each Chef Infra Client +run, and then uses default and override attributes that are specified in cookbooks, roles, environments, and Policyfiles. +All attributes are then merged and applied to the node according to attribute precedence. +The attributes that were applied to the node are saved to Chef Infra Server as part of the node object at the conclusion of each Chef Infra Client run. + +## Limiting Attribute Persistence + +Some organizations find it helpful to control attribute data stored by Chef Infra Server, whether to limit the disk and CPU resources used when processing unused attributes, or to keep secrets like API keys from being submitted to the server. +For example, your organization may find the data from the Ohai `Package` plugin useful when writing cookbooks, but don't see the need in saving ~100kB of package information for each Chef Infra Client run. +Attribute data will still be available on the node within cookbooks, but any information you limit won't be saved to Chef Infra Server for use in searches. + +You can block or allow the saving of specific key using the [`client.rb`](/install/config_rb_client/) file. +Each setting is an array of keys specifying each attribute to be filtered out or allowed. Use a "/" to separate subkeys, for example `network/interfaces`. + +For attributes containing slashes (`/`) within the attribute value, such as the `filesystem` attribute, use a nested array. For example: + +```ruby +blocked_automatic_attributes [['filesystem', '/dev/diskos2']] +``` + +{{< note >}} + +In **Chef Infra Client 16.3**, the node Blacklist and Whitelist features were deprecated and renamed to Blocklist and Allowlist. +In **Chef Infra Client 18.4.12** these features became EOL. +For backwards compatibility, the old configuration values will continue to work through Chef Infra Client 17.x + +See each section below for the appropriate legacy configuration values if you are running legacy clients in your organization. + +Legacy attribute config mapping: + +- automatic_attribute_blacklist -> blocked_automatic_attributes +- default_attribute_blacklist -> blocked_default_attributes +- normal_attribute_blacklist -> blocked_normal_attributes +- override_attribute_blacklist -> blocked_override_attributes +- automatic_attribute_whitelist -> allowed_automatic_attributes +- default_attribute_whitelist -> allowed_default_attributes +- normal_attribute_whitelist -> allowed_normal_attributes +- override_attribute_whitelist -> allowed_override_attributes + +{{< /note >}} + +### Attribute Blocklist + +{{< warning >}} + +{{< readfile file="content/reusable/md/node_attribute_blocklist_warning.md" >}} + +{{< /warning >}} + +{{< readfile file="content/reusable/md/node_attribute_blocklist.md" >}} + +### Attribute Allowlist + +{{< warning >}} + +{{< readfile file="content/reusable/md/node_attribute_allowlist_warning.md" >}} + +{{< /warning >}} + +Attributes are allowlisted by attribute type, with each attribute type being allowlisted independently in the `client.rb` file. + +The four attribute types are: + +- `automatic` +- `default` +- `normal` +- `override` + +The allowlist settings are: + +`allowed_automatic_attributes` + +: An array that allows saving specific `automatic` attributes. For example: `['network/interfaces/eth0']`. + + Default value: `nil`, all attributes are saved. + + If the array is empty, no attributes are saved. + +`allowed_default_attributes` + +: An array that allows saving specific `default` attributes. For example: `['filesystem/dev/disk0s2/size']`. + + Default value: `nil`, all attributes are saved. + + If the array is empty, no attributes are saved. + +`allowed_normal_attributes` + +: An array that allows saving specific `normal` attributes. For example: `['filesystem/dev/disk0s2/size']`. + + Default value: `nil`, all attributes are saved. + + If the array is empty, no attributes are saved. + +`allowed_override_attributes` + +: An array that allows specific `override` attributes, preventing blocklisted attributes from being saved. For example: `['map - autohome/size']`. + + Default value: `nil`, all attributes are saved. + + If the array is empty, no attributes are saved. diff --git a/content/cookbooks/attributes/attribute_precedence.md b/content/cookbooks/attributes/attribute_precedence.md new file mode 100644 index 0000000..efb7acc --- /dev/null +++ b/content/cookbooks/attributes/attribute_precedence.md @@ -0,0 +1,516 @@ ++++ +title = "Attribute Precedence" +draft = false + +[menu] + [menu.cookbooks] + title = "Attribute Precedence" + identifier = "cookbooks/attributes/attribute_precedence" + parent = "cookbooks/attributes" ++++ + +Chef Infra Client applies attributes in the following +order: + +| Application Order (Last One Wins) | Attribute Type | Source Order | +|-----------------------------------|------------------|---------------------------------------------------------------------| +| 1 | `default` | Cookbook attribute fileRecipeEnvironmentRole | +| 2 | `force_default` | Cookbook attribute fileRecipe | +| 3 | `normal` | JSON file passed with `chef-client -j`Cookbook attribute fileRecipe | +| 4 | `override` | Cookbook attribute fileRecipeRoleEnvironment | +| 5 | `force_override` | Cookbook attribute fileRecipe | +| 6 | `automatic` | Identified by Ohai at the start of a Chef Infra Client Run | + +{{< note >}} + +The attribute precedence order for the sources "roles" and "environments" are opposite in the `default` and `override`. The `default` order is **environment** then **role**. The `override` order is **role** then **environment** + +Applying the role `override` first lets you use the same role in a set of environments. +Applying the environment `override` on top of the role `override` lets you define a subset of these with environment-specific settings. + +This is useful if you have an environment that's different within a sub-set of a role. For example, the role for an application server may exist in all environments, but one environment may use a different database server. + +{{< /note >}} + +Attribute precedence, viewed from the same perspective as the overview +diagram, where the numbers in the diagram match the order of attribute +precedence: + +![image](/images/overview_chef_attributes_precedence.png) + +Attribute precedence, when viewed as a table: + +| | Attribute Files | Node/Recipe | Environment | Role | Ohai Data | +|----------------|-----------------|-------------|-------------|------|-----------| +| default | 1 | 2 | 3 | 4 | | +| force_default | 5 | 6 | | | | +| normal | 7 | 8 | | | | +| override | 9 | 10 | 12 | 11 | | +| force_override | 13 | 14 | | | | +| automatic | | | | | 15 | + +## Examples + +The following examples are listed from low to high precedence. + +**Default attribute in /attributes/default.rb** + +```ruby +default['apache']['dir'] = '/etc/apache2' +``` + +**Default attribute in node object in recipe** + +```ruby +node.default['apache']['dir'] = '/etc/apache2' +``` + +**Default attribute in /environments/environment_name.rb** + +```ruby +default_attributes({ 'apache' => {'dir' => '/etc/apache2'}}) +``` + +**Default attribute in /roles/role_name.rb** + +```ruby +default_attributes({ 'apache' => {'dir' => '/etc/apache2'}}) +``` + +**Normal attribute set as a cookbook attribute** + +```ruby +normal['apache']['dir'] = '/etc/apache2' +``` + +**Normal attribute set in a recipe** + +```ruby +node.normal['apache']['dir'] = '/etc/apache2' +``` + +**Override attribute in /attributes/default.rb** + +```ruby +override['apache']['dir'] = '/etc/apache2' +``` + +**Override attribute in /roles/role_name.rb** + +```ruby +override_attributes({ 'apache' => {'dir' => '/etc/apache2'}}) +``` + +**Override attribute in /environments/environment_name.rb** + +```ruby +override_attributes({ 'apache' => {'dir' => '/etc/apache2'}}) +``` + +**Override attribute in a node object (from a recipe)** + +```ruby +node.override['apache']['dir'] = '/etc/apache2' +``` + +**Ensure that a default attribute has precedence over other attributes** + +When a default attribute is set like this: + +```ruby +default['attribute'] = 'value' +``` + +any value set by a role or an environment will replace it. To prevent +this value from being replaced, use the `force_default` attribute +precedence: + +```ruby +force_default['attribute'] = 'I will crush you, role or environment attribute' +``` + +or: + +```ruby +default!['attribute'] = "The '!' means I win!" +``` + +**Ensure that an override attribute has precedence over other +attributes** + +When an override attribute is set like this: + +```ruby +override['attribute'] = 'value' +``` + +any value set by a role or an environment will replace it. To prevent +this value from being replaced, use the `force_override` attribute +precedence: + +```ruby +force_override['attribute'] = 'I will crush you, role or environment attribute' +``` + +or: + +```ruby +override!['attribute'] = "The '!' means I win!" +``` + +## Change Attributes + +Attribute precedence levels may be: + +- Removed for a specific, named attribute precedence level. +- Removed for all attribute precedence levels. +- Fully assigned attributes. + +### Remove Precedence Level + +A specific attribute precedence level for default, normal, and override +attributes may be removed by using one of the following syntax patterns. + +For default attributes: + +- `node.rm_default('foo', 'bar')` + +For normal attributes: + +- `node.rm_normal('foo', 'bar')` + +For override attributes: + +- `node.rm_override('foo', 'bar')` + +These patterns return the computed value of the key being deleted for +the specified precedence level. + +#### Examples + +The following examples show how to remove a specific, named attribute +precedence level. + +**Delete a default value when only default values exist** + +Given the following code structure under `'foo'`: + +```ruby +node.default['foo'] = { + 'bar' => { + 'baz' => 52, + 'thing' => 'stuff', + }, + 'bat' => { + 'things' => [5, 6], + }, +} +``` + +And some role attributes: + +```ruby +# Please don't ever do this in real code :) +node.role_default['foo']['bar']['thing'] = 'otherstuff' +``` + +And a force attribute: + +```ruby +node.force_default['foo']['bar']['thing'] = 'allthestuff' +``` + +When the default attribute precedence `node['foo']['bar']` is removed: + +```ruby +node.rm_default('foo', 'bar') #=> {'baz' => 52, 'thing' => 'allthestuff'} +``` + +What's left under `'foo'` is only `'bat'`: + +```ruby +node.attributes.combined_default['foo'] #=> {'bat' => { 'things' => [5,6] } } +``` + +**Delete default without touching higher precedence attributes** + +Given the following code structure: + +```ruby +node.default['foo'] = { + 'bar' => { + 'baz' => 52, + 'thing' => 'stuff', + }, + 'bat' => { + 'things' => [5, 6], + }, +} +``` + +And some role attributes: + +```ruby +# Please don't ever do this in real code :) +node.role_default['foo']['bar']['thing'] = 'otherstuff' +``` + +And a force attribute: + +```ruby +node.force_default['foo']['bar']['thing'] = 'allthestuff' +``` + +And also some override attributes: + +```ruby +node.override['foo']['bar']['baz'] = 99 +``` + +Same delete as before: + +```ruby +node.rm_default('foo', 'bar') #=> { 'baz' => 52, 'thing' => 'allthestuff' } +``` + +The other attribute precedence levels are unaffected: + +```ruby +node.attributes.combined_override['foo'] #=> { 'bar' => {'baz' => 99} } +node['foo'] #=> { 'bar' => {'baz' => 99}, 'bat' => { 'things' => [5,6] } +``` + +**Delete override without touching lower precedence attributes** + +Given the following code structure, which has an override attribute: + +```ruby +node.override['foo'] = { + 'bar' => { + 'baz' => 52, + 'thing' => 'stuff', + }, + 'bat' => { + 'things' => [5, 6], + }, +} +``` + +with a single default value: + +```ruby +node.default['foo']['bar']['baz'] = 11 +``` + +and a force at each attribute precedence: + +```ruby +node.force_default['foo']['bar']['baz'] = 55 +node.force_override['foo']['bar']['baz'] = 99 +``` + +Delete the override: + +```ruby +node.rm_override('foo', 'bar') #=> { 'baz' => 99, 'thing' => 'stuff' } +``` + +The other attribute precedence levels are unaffected: + +```ruby +node.attributes.combined_default['foo'] #=> { 'bar' => {'baz' => 55} } +``` + +**Non-existent key deletes return nil** + +```ruby +node.rm_default("no", "such", "thing") #=> nil +``` + +### Remove All Levels + +All attribute precedence levels may be removed by using the following +syntax pattern: + +- `node.rm('foo', 'bar')` + +{{< note >}} + +Using `node['foo'].delete('bar')` will throw an exception that points to +the new API. + +{{< /note >}} + +#### Examples + +The following examples show how to remove all attribute precedence +levels. + +**Delete all attribute precedence levels** + +Given the following code structure: + +```ruby +node.default['foo'] = { + 'bar' => { + 'baz' => 52, + 'thing' => 'stuff', + }, + 'bat' => { + 'things' => [5, 6], + }, +} +``` + +With override attributes: + +```ruby +node.override['foo']['bar']['baz'] = 999 +``` + +Removing the `'bar'` key returns the computed value: + +```ruby +node.rm('foo', 'bar') #=> {'baz' => 999, 'thing' => 'stuff'} +``` + +Looking at `'foo'`, all that's left is the `'bat'` entry: + +```ruby +node['foo'] #=> {'bat' => { 'things' => [5,6] } } +``` + +**Non-existent key deletes return nil** + +```ruby +node.rm_default("no", "such", "thing") #=> nil +``` + +### Full Assignment + +Use `!` to clear out the key for the named attribute precedence level, +and then complete the write by using one of the following syntax +patterns: + +- `node.default!['foo']['bar'] = {...}` +- `node.force_default!['foo']['bar'] = {...}` +- `node.normal!['foo']['bar'] = {...}` +- `node.override!['foo']['bar'] = {...}` +- `node.force_override!['foo']['bar'] = {...}` + +#### Examples + +The following examples show how to remove all attribute precedence +levels. + +**Just one component** + +Given the following code structure: + +```ruby +node.default['foo']['bar'] = {'a' => 'b'} +node.default!['foo']['bar'] = {'c' => 'd'} +``` + +The `'!'` caused the entire 'bar' key to be overwritten: + +```ruby +node['foo'] #=> {'bar' => {'c' => 'd'} +``` + +**Multiple components; one "after"** + +Given the following code structure: + +```ruby +node.default['foo']['bar'] = {'a' => 'b'} +# Please don't ever do this in real code :) +node.role_default['foo']['bar'] = {'c' => 'd'} +node.default!['foo']['bar'] = {'d' => 'e'} +``` + +The `'!'` write overwrote the "cookbook-default" value of `'bar'`, but +since role data is later in the resolution list, it was unaffected: + +```ruby +node['foo'] #=> {'bar' => {'c' => 'd', 'd' => 'e'} +``` + +**Multiple components; all "before"** + +Given the following code structure: + +```ruby +node.default['foo']['bar'] = {'a' => 'b'} +# Please don't ever do this in real code :) +node.role_default['foo']['bar'] = {'c' => 'd'} +node.force_default!['foo']['bar'] = {'d' => 'e'} +``` + +With `force_default!` there is no other data under `'bar'`: + +```ruby +node['foo'] #=> {'bar' => {'d' => 'e'} +``` + +**Multiple precedence levels** + +Given the following code structure: + +```ruby +node.default['foo'] = { + 'bar' => { + 'baz' => 52, + 'thing' => 'stuff', + }, + 'bat' => { + 'things' => [5, 6], + }, +} +``` + +And some attributes: + +```ruby +# Please don't ever do this in real code :) +node.role_default['foo']['bar']['baz'] = 55 +node.force_default['foo']['bar']['baz'] = 66 +``` + +And other precedence levels: + +```ruby +node.normal['foo']['bar']['baz'] = 88 +node.override['foo']['bar']['baz'] = 99 +``` + +With a full assignment: + +```ruby +node.default!['foo']['bar'] = {} +``` + +Role default and force default are left in default, plus other +precedence levels: + +```ruby +node.attributes.combined_default['foo'] #=> {'bar' => {'baz' => 66}, 'bat'=>{'things'=>[5, 6]}} +node.attributes.normal['foo'] #=> {'bar' => {'baz' => 88}} +node.attributes.combined_override['foo'] #=> {'bar' => {'baz' => 99}} +node['foo']['bar'] #=> {'baz' => 99} +``` + +If `force_default!` is written: + +```ruby +node.force_default!['foo']['bar'] = {} +``` + +the difference is: + +```ruby +node.attributes.combined_default['foo'] #=> {'bat'=>{'things'=>[5, 6]}, 'bar' => {}} +node.attributes.normal['foo'] #=> {'bar' => {'baz' => 88}} +node.attributes.combined_override['foo'] #=> {'bar' => {'baz' => 99}} +node['foo']['bar'] #=> {'baz' => 99} +``` diff --git a/content/cookbooks/attributes/attribute_sources.md b/content/cookbooks/attributes/attribute_sources.md new file mode 100644 index 0000000..78e82fc --- /dev/null +++ b/content/cookbooks/attributes/attribute_sources.md @@ -0,0 +1,144 @@ ++++ +title = "Attribute Sources" +draft = false + +[menu] + [menu.cookbooks] + title = "Attribute Sources" + identifier = "cookbooks/attributes/attribute_sources Attributes" + parent = "cookbooks/attributes" ++++ + + +Chef Infra Client evaluates attributes in the order that they're defined in the +run-list, including any attributes that are in the run-list as +cookbook dependencies. + +Attributes are provided to Chef Infra Client from the following +locations: + +- JSON files passed using the `chef-client -j` +- Nodes (collected by Ohai at the start of each Chef Infra Client run) +- Attribute files (in cookbooks) +- Recipes (in cookbooks) +- Environments +- Roles +- Policyfiles + +Notes: + +- Many attributes are maintained in the chef-repo for Policyfiles, + environments, roles, and cookbooks (attribute files and recipes) +- Many attributes are collected by Ohai on each individual node at the + start of every Chef Infra Client run +- The attributes that are maintained in the chef-repo are uploaded to + Chef Infra Server from the workstation, periodically +- Chef Infra Client will pull down the node object from the Chef Infra + Server and then reset all the attributes except `normal`. The node + object will contain the attribute data from the previous Chef Infra + Client run including attributes set with JSON files using `-j`. +- Chef Infra Client will update the cookbooks on the node (if + required), which updates the attributes contained in attribute files + and recipes +- Chef Infra Client will update the role and environment data (if + required) +- Chef Infra Client will rebuild the attribute list and apply + attribute precedence while configuring the node +- Chef Infra Client pushes the node object to Chef Infra Server at + the end of a Chef Infra Client run; the updated node object on the + Chef Infra Server is then indexed for search and is stored until the + next Chef Infra Client run + +## Automatic Attributes (Ohai) + +{{< readfile file="content/reusable/md/ohai_automatic_attribute.md" >}} + +{{< readfile file="content/reusable/md/ohai_attribute_list.md" >}} + +## Attribute Files + +An attribute file is located in the `attributes/` sub-directory for a +cookbook. When a cookbook is run against a node, the attributes +contained in all attribute files are evaluated in the context of the +node object. Node methods (when present) are used to set attribute +values on a node. For example, the `apache2` cookbook contains an +attribute file called `default.rb`, which contains the following +attributes: + +```ruby +default['apache']['dir'] = '/etc/apache2' +default['apache']['listen_ports'] = [ '80','443' ] +``` + +The use of the node object (`node`) is implicit in the previous example; +the following example defines the node object itself as part of the +attribute: + +```ruby +node.default['apache']['dir'] = '/etc/apache2' +node.default['apache']['listen_ports'] = [ '80','443' ] +``` + +Another (much less common) approach is to set a value only if an +attribute has no value. This can be done by using the `_unless` variants +of the attribute priority methods: + +- `default_unless` +- `normal_unless` + +Use the `_unless` variants carefully (and only when necessary) because +when they're used, attributes applied to nodes may become out of sync +with the values in the cookbooks as these cookbooks are updated. This +approach can create situations where two otherwise identical nodes end +up having slightly different configurations and can also be a challenge +to debug. + +### File Methods + +Use the following methods within the attributes file for a cookbook or within a recipe. These methods correspond to the attribute type of the same name: + +- `override` +- `default` +- `normal` +- `_unless` + +### attribute? + +A useful method that's related to attributes is the `attribute?` +method. This method will check for the existence of an attribute, so +that processing can be done in an attributes file or recipe, but only if +a specific attribute exists. + +Using `attribute?()` in an attributes file: + +```ruby +if attribute?('ec2') + # ... set stuff related to EC2 +end +``` + +Using `attribute?()` in a recipe: + +```ruby +if node.attribute?('ec2') + # ... do stuff on EC2 nodes +end +``` + +## Attributes from Recipes + +{{< readfile file="content/reusable/md/cookbooks_recipe.md" >}} + +{{< readfile file="content/reusable/md/cookbooks_attribute.md" >}} + +## Attributes from Roles + +{{< readfile file="content/reusable/md/role.md" >}} + +{{< readfile file="content/reusable/md/role_attribute.md" >}} + +## Attributes from Environments + +{{< readfile file="content/reusable/md/environment.md" >}} + +{{< readfile file="content/reusable/md/environment_attribute.md" >}} diff --git a/content/cookbooks/attributes/attribute_types.md b/content/cookbooks/attributes/attribute_types.md new file mode 100644 index 0000000..8e41423 --- /dev/null +++ b/content/cookbooks/attributes/attribute_types.md @@ -0,0 +1,34 @@ ++++ +title = "Attribute Types" +draft = false + +[menu] + [menu.cookbooks] + title = "Attribute Types" + identifier = "cookbooks/attributes/attributes_types.md Attributes" + parent = "cookbooks/attributes" ++++ + +Chef Infra Client uses six types of attributes to determine the value that's applied to a node during a Chef Infra Client run. +In addition, Chef Infra Client gathers attribute values from up to five locations. +The combination of attribute types and sources makes up to 15 different competing values available during a Chef Infra Client run. + +The attribute types are: + +`default` +: {{< readfile file="content/reusable/md/node_attribute_type_default.md" >}} + +`force_default` +: Use the force_default attribute to ensure that an attribute defined in a cookbook (by an attribute file or by a recipe) takes precedence over a default attribute set by a role or an environment. + +`normal` +: {{< readfile file="content/reusable/md/node_attribute_type_normal.md" >}} + +`override` +: {{< readfile file="content/reusable/md/node_attribute_type_override.md" >}} + +`force_override` +: Use the force_override attribute to ensure that an attribute defined in a cookbook (by an attribute file or by a recipe) takes precedence over an override attribute set by a role or an environment. + +`automatic` +: {{< readfile file="content/reusable/md/node_attribute_type_automatic.md" >}} diff --git a/content/cookbooks/chef_repo/_index.md b/content/cookbooks/chef_repo/_index.md new file mode 100644 index 0000000..517f0f6 --- /dev/null +++ b/content/cookbooks/chef_repo/_index.md @@ -0,0 +1,116 @@ ++++ +title = "About chef-repo" +draft = false + +[menu] + [menu.chef_repo] + title = "About chef-repo" + identifier = "chef_repo/chef_repo.md" + parent = "chef_repo" + weight = 15 ++++ + +{{< readfile file="content/reusable/md/chef_repo_description.md" >}} + +## Generate the chef-repo + +Use the [chef generate repo command](https://docs.chef.io/workstation/ctl_chef/#chef-generate-repo) to create your chef-repo directory along with the base folder structure. This command uses the `chef` command-line tool that's packaged as part of Chef Workstation to create a chef-repo. + +```bash +chef generate repo REPO_NAME +``` + +{{< note >}} + +`chef generate repo` generates a chef-repo that's configured for Policyfiles by default. To create a repository that's setup for Roles and Environments use the `--roles` flag when running the command. + +{{< /note >}} + +## Directory structure + +The chef-repo contains several directories, each with a README file that describes what it's for and how to use that directory when managing systems. + +The default structure of a new chef-repo is: + +```plain +. chef-repo +├── LICENSE +├── README.md +├── chefignore +├── cookbooks +│ ├── README.md +│ └── example +│ ├── README.md +│ ├── attributes +│ │ ├── README.md +│ │ └── default.rb +│ ├── metadata.rb +│ └── recipes +│ ├── README.md +│ └── default.rb +├── data_bags +│ ├── README.md +│ └── example +│ ├── README.md +│ └── example_item.json +└── policyfiles + └── README.md +``` + +### cookbooks + +The `cookbooks` directory contains cookbooks that configure systems in the infrastructure which are are downloaded from the [Chef Supermarket](https://supermarket.chef.io/) or created locally. The Chef Infra Client uses cookbooks to configuring the systems in the organization. Each cookbook can be configured to contain cookbook-specific copyright, email, and license data. + +### data_bags + +The `data_bags` directory is used to store all the data bags that exist for an organization. Each sub-directory corresponds to a single data bag on Chef Infra Server and contains a JSON file corresponding to each data bag item. + +### policyfiles + +The `policyfiles` directory is used to store Policyfiles in the `.rb` format that define the set of cookbooks and attributes to apply to specific systems managed by Chef Infra Server. + +### chefignore + +A `chefignore` file tells knife which cookbook files in the chef-repo it should ignore when uploading data to Chef Infra Server. +Include swap files, version control data, and build output data in a `chefignore` file. + +The `chefignore` file has the following rules: + +- Patterns use `*`, `**`, and `?` wildcards to match files and directories as defined by the `File.fnmatch` Ruby method. +- A pattern is relative to the directory it's included in. +- A pattern may contain relative directory names. +- A pattern may match all files in a directory. +- You can add a `chefignore` file to any subdirectory of a chef-repo. For example, `/`, `/cookbooks`, `/cookbooks/COOKBOOK_NAME/`, etc. +- Lines that start with `#` are comments. + +Group types of ignored files in sections similar to the following: + +```plain +## OS generated files +*ignore_pattern + +## Editors +another_ignore_pattern* +``` + +See Ruby's [`File.fnmatch` documentation](https://ruby-doc.org/core-2.5.1/File.html#method-c-fnmatch) for information on creating matching file patterns. + +#### Examples + +Many text editors leave files behind. To prevent knife from uploading these files to Chef Infra Server, add an entry to the `chefignore` file. + +For Emacs backup files: + +```plain +*~ +``` + +and for Vim swap files: + +```plain +*.sw[a-z] +``` + +## Many Users, Same Repo + +{{< readfile file="content/reusable/md/chef_repo_many_users_same_knife.md" >}} diff --git a/content/cookbooks/config_rb_metadata.md b/content/cookbooks/config_rb_metadata.md new file mode 100644 index 0000000..b059afd --- /dev/null +++ b/content/cookbooks/config_rb_metadata.md @@ -0,0 +1,290 @@ ++++ +title = "metadata.rb" +draft = false + +[menu] + [menu.cookbooks] + title = "metadata.rb" + identifier = "cookbooks/config_rb_metadata.md metadata.rb Configuration" + parent = "cookbooks" + weight = 60 ++++ + + + +{{< readfile file="content/reusable/md/cookbooks_metadata.md" >}} + +* Located at the top level of a cookbook's directory structure. +* Compiled whenever a cookbook is uploaded to Chef Infra Server or when the `knife cookbook metadata` subcommand is run, and then stored as JSON data. +* Created automatically by knife whenever the `knife cookbook create` subcommand is run. +* Edited using a text editor, and then re-uploaded to Chef Infra Server as part of a cookbook upload. + +## Error Messages + +Chef Infra Server will only try to distribute the cookbooks that are needed to configure an individual node. This is determined by identifying the roles and recipes that are assigned directly to that system, and then to expand the list of dependencies, and then to deliver that entire set to the node. In some cases, if the dependency isn't specified in the cookbook's metadata, Chef Infra Server may not treat that dependency as a requirement, which will result in an error message. If an error message is received from Chef Infra Server about cookbook distribution, verify the `depends` entries in the `metadata.rb` file, and then try again. + +{{< note >}} + +A metadata.json file can be edited directly, should temporary changes be required. Any subsequent upload or action that generates metadata will cause the existing metadata.json file to be overwritten with the newly generated metadata. Therefore, any permanent changes to cookbook metadata should be done in the `metadata.rb` file, and then re-uploaded to Chef Infra Server. + +{{< /note >}} + +## Version Constraints + +Many fields in a cookbook's metadata allow the user to constrain versions. The following operators are common to all fields: + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SpecificationOperator
Pessimistic (see note below)~>
Equal to=
Greater than or equal to>=
Greater than>
Less than<
Less than or equal to<=
+ + +{{< note >}} + +Pessimistic locking is enabled by proper [semantic versioning](https://semver.org) of cookbooks. If we're on version 2.2.3 of a cookbook, we know that the API will be stable until the 3.0.0 release. Using traditional operators, we'd write this as `>= 2.2.0, < 3.0`. Instead, we can write this by combining a tilde "\~" and right angle bracket "\>"--often called a tilde-rocket or "twiddle-wakka"--followed by the major and minor version numbers. For example: `~> 2.2` + +{{< /note >}} + +## Settings + +This configuration file has the following settings: + +`chef_version` + +: A range of Chef Infra Client versions that are supported by this cookbook. All [version constraint operators](#version-constraints) are applicable to this field. + + For example, to match any 16.x version of the Chef Infra Client, but not 15.x or 17.x: + + ```ruby + chef_version '~> 16.0' + ``` + + A more complex example where you set both a lower and upper bound of the Chef Infra Client version: + + ```ruby + chef_version '>= 17.2', '< 17.4' + ``` + +`depends` + +: This field requires that a cookbook with a matching name and version exists on Chef Infra Server. When the match exists, Chef Infra Server includes the dependency as part of the set of cookbooks that are sent to the node during a Chef Infra Client run. It's important that the `depends` field contain accurate data. If a dependency statement is inaccurate, Chef Infra Client may not be able to complete the configuration of the system. All [version constraint operators](#version-constraints) are applicable to this field. + + For example, to set a dependency a cookbook named `cats`: + + ```ruby + depends 'cats' + ``` + + or, to set a dependency on the same cookbook, but only when the version is less than 1.0: + + ```ruby + depends 'cats', '< 1.0' + ``` + +`description` + +: A short description of a cookbook and its functionality. + + For example: + + ```ruby + description 'A fancy cookbook that manages a herd of cats!' + ``` + +`gem` + +: Specifies a gem dependency for installation in Chef Infra Client through bundler. The gem installation occurs after all cookbooks are synchronized but before loading any other cookbooks. Use this attribute one time for each gem dependency. For example: + + ```ruby + gem 'loofah' + gem 'chef-sugar' + ``` + + {{< warning >}} + + Use the `gem` setting only for making external chef libraries shipped as gems accessible in a Chef Infra Client run for libraries and attribute files. The `gem` setting in `metadata.rb` allows for the early installation of this specific type of gem, with the fundamental limitation that it can't install native gems. + + Don't install native gems with the `gem` setting in `metadata.rb`. The `gem` setting isn't a general purpose replacement for the [chef_gem resource](/resources/bundled/chef_gem/), and doesn't internally re-use the `chef_gem` resource. Native gems require C compilation and must not be installed with `metadata.rb` because `metadata.rb` runs before any recipe code runs. Consequently, Chef Infra Client Linux install the C compilers before the gem installation occurs. Instead, install native gems with the `chef_gem` resource called from the recipe code. You'll also need to use the `build_essential` resource in the recipe code to install the prerequisite compilers onto the system. + + Pure ruby gems can also be installed with `metadata.rb`. + + {{< /warning >}} + +`issues_url` + +: The URL of the location in which a cookbook's issue tracking is maintained. This setting is also used by Chef Supermarket. In Chef Supermarket, this value is used to define the destination for the "View Issues" link. + + For example: + + ```ruby + issues_url 'https://github.com/chef-cookbooks/chef-client/issues' + ``` + +`license` + +: The type of license under which a cookbook is distributed: `Apache v2.0`, `GPL v2`, `GPL v3`, `MIT`, or `license 'Proprietary - All Rights Reserved` (default). Please be aware of the licenses for files inside of a cookbook and be sure to follow any restrictions they describe. + + For example: + + ```ruby + license 'Apache-2.0' + ``` + + or: + + ```ruby + license 'GPL-3.0' + ``` + + or: + + ```ruby + license 'MIT' + ``` + + or: + + ```ruby + license 'Proprietary - All Rights Reserved' + ``` + +`maintainer` + +: The name of the person responsible for maintaining a cookbook, either an individual or an organization. + + For example: + + ```ruby + maintainer 'Bob Bobberson' + ``` + +`maintainer_email` + +: The email address for the person responsible for maintaining a cookbook. Only one email can be listed here, so if this needs to be forwarded to multiple people consider using an email address that's already setup for mail forwarding. + + For example: + + ```ruby + maintainer_email 'bob@example.com' + ``` + +`name` + +: Required. The name of the cookbook. + + For example: + + ```ruby + name 'cats' + ``` + +`ohai_version` + +: A range of Ohai versions that are supported by this cookbook. All [version constraint operators](#version-constraints) are applicable to this field. + + For example, to match any 8.x version of Ohai, but not 7.x or 9.x: + + ```ruby + ohai_version '~> 8' + ``` + + {{< note >}} + + This setting isn't visible in Chef Supermarket. + + {{< /note >}} + +`privacy` + +: Specify a cookbook as private. This prevents a cookbook from being uploaded to the public Supermarket or any Supermarket where ``ENFORCE_PRIVACY`` has been enabled. + + For example: + + ```ruby + privacy true + ``` + +`source_url` + +: The URL of the location in which a cookbook's source code is maintained. This setting is also used by Chef Supermarket. In Chef Supermarket, this value is used to define the destination for the "View Source" link. + + For example: + + ```ruby + source_url 'https://github.com/chef-cookbooks/chef-client' + ``` + +`supports` + +: Show that a cookbook has a supported platform. Use a version constraint to define dependencies for platform versions: `<` (less than), `<=` (less than or equal to), `=` (equal to), `>=` (greater than or equal to), `~>` (approximately greater than), or `>` (greater than). To specify more than one platform, use more than one `supports` field, once for each platform. + + For example, to support every version of Ubuntu: + + ```ruby + supports 'ubuntu' + ``` + + or, to support versions of Ubuntu greater than or equal to 20.04: + + ```ruby + supports 'ubuntu', '>= 20.04' + ``` + + or, to support only Ubuntu 20.04: + + ```ruby + supports 'ubuntu', '= 20.04' + ``` + + Here is a list of all of the supported specific operating systems: + + ```ruby + %w( aix amazon centos fedora freebsd debian oracle mac_os_x redhat suse opensuseleap ubuntu windows zlinux ).each do |os| + supports os + end + ``` + +`version` + +: The current version of a cookbook. Version numbers always follow a simple three-number version sequence. + + For example: + + ```ruby + version '2.0.0' + ``` diff --git a/content/cookbooks/cookbook_repo.md b/content/cookbooks/cookbook_repo.md new file mode 100644 index 0000000..a869e53 --- /dev/null +++ b/content/cookbooks/cookbook_repo.md @@ -0,0 +1,130 @@ ++++ +title = "Get Started" +draft = false + +[menu] + [menu.cookbooks] + title = "Cookbook Directory" + identifier = "cookbooks/cookbook_repo.md Cookbook Repo" + parent = "cookbooks" + weight = 20 ++++ + +The `cookbooks/` directory of your Chef Infra repository is used to +store the cookbooks that Chef Infra Client uses in configuring the +various systems in the organization. + +## Chef Repository + +The the `\cookbook` directory is automatically generated as part of your Chef Infra repository. + +```bash +chef generate repo REPO_NAME +``` + +### Cookbook Directory Structure + +The default structure of the cookbooks directory is: + +```plain +. chef-repo +└── cookbooks + ├── README.md + └── example + ├── README.md + ├── attributes + │ ├── README.md + │ └── default.rb + ├── metadata.rb + └── recipes + ├── README.md + └── default.rb +``` + +## Cookbook Commands + +Use the following commands to create a cookbook, install a cookbook from Supermarket, and/or download cookbooks. + +### Create + +Chef Workstation generates the `cookbooks` directory as part of your Chef Infra repository, the `chef-repo`. + +Generate a `chef-repo/cookbooks` directory with the command: + +```bash +chef generate template PATH_TO_COOKBOOKS COOKBOOK_NAME +``` + +For example, this command generates a `custom_web` cookbook: + +```bash +chef generate cookbook cookbooks/custom_web +``` + +The `custom_web` cookbook directory has the structure: + +```text +. cookbooks +└── custom_web + ├── CHANGELOG.md + ├── LICENSE + ├── Policyfile.rb + ├── README.md + ├── chefignore + ├── compliance + │ ├── README.md + │ ├── inputs + │ ├── profiles + │ └── waivers + ├── kitchen.yml + ├── metadata.rb + ├── recipes + │ └── default.rb + └── test + └── integration + └── default + └── default_test.rb +``` + +Any unneeded directory components can be left unused or deleted, if +preferred. + +### Install + +To download a cookbook when git is used for version source control, run +the following command: + +```bash +knife supermarket install COOKBOOK_NAME +``` + +where `COOKBOOK_NAME` is the name of a cookbook on [Chef +Supermarket](https://supermarket.chef.io/). This will start a process +that: + +- downloads the cookbook from [Chef Supermarket](https://supermarket.chef.io/) as a `tar.gz` archive +- ensures that its using the git main branch, and then checks out + the cookbook from a vendor branch (creating a new vendor branch, if + required) +- removes the old (existing) version +- expands the tar.gz archive and adds the expanded files to the git + index and commits +- creates a tag for the version that was downloaded +- checks out the main branch +- merges the cookbook into the main branch (to ensure that any local + changes or modifications are preserved) + +### Download + +To download a cookbook when git isn't used for version source control, +run the following command: + +```bash +knife supermarket download COOKBOOK_NAME +``` + +where `COOKBOOK_NAME` is the name of a cookbook on [Chef +Supermarket](https://supermarket.chef.io/). This will download the +tar.gz file associated with the cookbook and will create a file named +`COOKBOOK_NAME.tar.gz` in the current directory (`~/chef-repo`). +Once downloaded, using a version source control system is recommended. diff --git a/content/cookbooks/cookbook_versioning.md b/content/cookbooks/cookbook_versioning.md new file mode 100644 index 0000000..62ddc3f --- /dev/null +++ b/content/cookbooks/cookbook_versioning.md @@ -0,0 +1,343 @@ ++++ +title = "About cookbook versioning" +draft = false + +[menu] + [menu.cookbooks] + title = "Versioning cookbooks" + identifier = "cookbooks/cookbook_versioning.md Versioning Cookbooks" + parent = "cookbooks" + weight = 150 ++++ + + + +{{< readfile file="content/reusable/md/cookbooks_version.md" >}} + +## Syntax + +A cookbook version always takes the form x.y.z, where x, y, and z are +decimal numbers that are used to represent major (x), minor (y), and +patch (z) versions. A two-part version (x.y) is also allowed. +Alphanumeric version numbers (1.2.a3) and version numbers with more than +three parts (1.2.3.4) aren't allowed. + +## Constraints + +A version constraint is a string that combines the cookbook version +syntax with an operator, in the following format: + +```ruby +operator cookbook_version_syntax +``` + +{{< note >}} + +Single digit cookbook versions aren't allowed. Cookbook versions must +specify at least the major and minor version. For example, use `1.0` or +`1.0.1`; don't use `1`. + +{{< /note >}} + +{{< readfile file="content/reusable/md/cookbooks_version_constraints_operators.md" >}} + +For example, a version constraint for "equals version 1.0.7" is +expressed like this: + +```ruby += 1.0.7 +``` + +A version constraint for "greater than version 1.0.2" is expressed like +this: + +```ruby +> 1.0.2 +``` + +An optimistic version constraint is one that looks for versions greater +than or equal to the specified version. For example: + +```ruby +>= 2.6.5 +``` + +will match cookbooks greater than or equal to 2.6.5, such as 2.6.5, +2.6.7 or 3.1.1. + +A pessimistic version constraint is one that will find the upper limit +version number within the range specified by the minor version number or +patch version number. For example, a pessimistic version constraint for +minor version numbers: + +```ruby +~> 2.6 +``` + +will match cookbooks that are greater than or equal to version 2.6, but +less than version 3.0. + +Or, a pessimistic version constraint for patch version numbers: + +```ruby +~> 2.6.5 +``` + +will match cookbooks that are greater than or equal to version 2.6.5, +but less than version 2.7.0. + +Or, a pessimistic version constraint that matches cookbooks less than a +version number: + +```ruby +< 2.3.4 +``` + +or will match cookbooks less than or equal to a specific version number: + +```ruby +<= 2.6.5 +``` + +## Metadata + +{{< readfile file="content/reusable/md/cookbooks_metadata.md" >}} + +Versions and version constraints can be specified in a cookbook's `metadata.rb` file by using the following functions. +Each function accepts a name and an optional version constraint. +If a version constraint isn't provided, `>= 0.0.0` is used as the default. + + + +`depends` +: Specify that a cookbook has a dependency on another cookbook. + You can use a version constraint to define dependencies for cookbook versions: + + - `<`: less than + - `<=`: less than or equal to + - `=`: equal to + - `>=`: greater than or equal to---also known as optimistically greater than or optimistic. + - `~>`: approximately greater than---also known as pessimistically greater than or pessimistic + - `>`: greater than + + A cookbook with a matching name and version must exist on Chef Infra Server. + When the match exists, Chef Infra Server includes the dependency as part of the set of cookbooks that are sent to the node when Chef Infra Client runs. + + The `depends` field must contain accurate data. + If a dependency statement is inaccurate, Chef Infra Client may not be able to complete the configuration of the system. + + For example: + + ```ruby + depends 'opscode-base' + ``` + + or: + + ```ruby + depends 'opscode-github', '> 1.0.0' + ``` + + or: + + ```ruby + depends 'runit', '~> 1.2.3' + ``` + +`provides` +: Add a recipe, definition, or resource that's provided by this cookbook if the populated list is insufficient. + +`supports` +: Specify that a cookbook has a supported platform. + + You can use a version constraint to define dependencies for platform versions: + + - `<`: less than + - `<=`: less than or equal to + - `=`: equal to + - `>=`: greater than or equal to + - `~>`: approximately greater than + - `>`: greater than + + To specify more than one platform, use more than one `supports` field, once for each platform. + +## Environments + +An environment can use version constraints to specify a list of allowed +cookbook versions by specifying the cookbook's name, along with the +version constraint. For example: + +```ruby +cookbook 'apache2', '~> 1.2.3' +``` + +Or: + +```ruby +cookbook 'runit', '= 4.2.0' +``` + +If a cookbook isn't explicitly given a version constraint the +environment will assume the cookbook has no version constraint and will +use any version of that cookbook with any node in the environment. + +## Freeze versions + +A cookbook version can be frozen, which will prevent updates from being +made to that version of a cookbook. (A user can always upload a new +version of a cookbook.) Using cookbook versions that are frozen within +environments is a reliable way to keep a production environment safe +from accidental updates while testing changes that are made to a +development infrastructure. + +For example, to freeze a cookbook version using knife, enter: + +```bash +knife cookbook upload redis --freeze +``` + +To return: + +```bash +Uploading redis... +Upload completed +``` + +Once a cookbook version is frozen, only by using the `--force` option +can an update be made. For example: + +```bash +knife cookbook upload redis --force +``` + +Without the `--force` option specified, an error will be returned +similar to: + +```bash +Version 0.0.0 of cookbook redis is frozen. Use --force to override +``` + +## Managing Many Cookbook Versions + +{{< warning >}} + +If you continually upload all versions of many cookbooks to your Chef Infra Server, you may overload Chef Infra Server's dependency solver, causing it to time out and leading to a failed Chef Infra Client run. + +There are three solutions to this problem: + +- use [Policyfiles](/policy/policyfile/) (recommended) +- place version constraints on all cookbooks and all dependencies of all cookbooks in any run list you use for a Chef Infra Client run +- upload only the required cookbook versions to a Chef Infra Server + +{{< /warning >}} + +In a CI/CD workflow where new cookbook versions are continually uploaded to a Chef Infra Server, the Chef Infra Server dependency solver must look at more and more cookbook versions while trying to solve the constraints given to it from the run list of each Chef Infra Client that starts up. Eventually, it runs out of time to produce a solution, times out, and the Chef Infra Client run fails as a result. Chef Infra Server may also pick older cookbook versions than the versions that you intended. + +The dependency solver workers in a Chef Infra Server have a default timeout of five seconds. The solution isn't to increase their timeout, but to control the problem so that the dependency solvers can solve it in a reasonable amount of time. + +### Policyfiles + +The current best practice is to control cookbook versions through Policyfiles. In this way, the dependency resolution is shifted left to the cookbook author designing the cookbook, its dependency structure, and the needed versions of all involved cookbooks. See the [Policyfiles](/policy/policyfile/) documentation for more information. + +### Version Constraints + +In a CI/CD environment where you have many versions of cookbooks, place version constraints on all cookbooks and all dependencies of all cookbooks in any run list you use for a Chef Infra Client run. + +The way to control the problem traditionally is by pinning the versions of cookbooks in an environment file or by using a wrapper cookbook that calls out the dependencies AND their versions in its `metadata.rb` file, and the dependencies do the same in their own `metadata.rb` files. See the [Cookbook Metadata Files](/cookbooks/config_rb_metadata/) for more information. + +### Minimum Number of Cookbook Versions + +The dependency solver will also work properly if you upload the minimum number of cookbook versions needed to Chef Infra Server. + +You can make a start at this by only uploading tested and blessed cookbook versions to your Chef Infra Server. These cookbooks would be ones where each scenario or role for the nodes is considered and that small set of cookbook versions are made available for those sets of nodes. Before Policyfiles, this policy could be implemented by constraining dependency solver access to candidate versions using an [environment]({{< relref "environments" >}}) file. + +## Version Source Control + +There are two strategies to consider when using version control as part +of the cookbook management process: + +- Use maximum version control when it's important to keep every bit of data within version control +- Use branch tracking when cookbooks are being managed in separate environments using git branches and the versioning policy information is already stored in a cookbook's metadata. + +### Branch Tracking + +Using a branch tracking strategy requires that a branch for each +environment exists in the source control and that each cookbook's +versioning policy is tracked at the branch level. This approach is +relatively simple and lightweight: for development environments that +track the latest cookbooks, just bump the version before a cookbook is +uploaded for testing. For any cookbooks that require higher levels of +version control, knife allows cookbooks to be uploaded to specific +environments and for cookbooks to be frozen (which prevents others from +being able to make changes to that cookbook). + +The typical workflow with a branch tracking version control strategy +includes: + +1. Bumping the version number as appropriate. +2. Making changes to a cookbook. +3. Uploading and testing a cookbook. +4. Moving a tested cookbook to production. + +For example, to bump a version number, first make changes to the +cookbook, and then upload and test it. Repeat this process as required, +and then upload it using a knife command similar to: + +```bash +knife cookbook upload my-app +``` + +When the cookbook is finished, move those changes to the production +environment and use the `--freeze` option to prevent others from making +further changes: + +```bash +knife cookbook upload my-app -E production --freeze +``` + +### Maximum Versions + +Using a maximum version control strategy is required when everything +needs to be tracked in source control. This approach is similar to +a branch tracking strategy while the cookbook is in development and +being tested, but is more complicated and time-consuming (and requires +file-level editing for environment data) to get the cookbook +deployed to a production environment. + +The typical workflow with a maximum version control strategy includes: + +1. Bumping the version number as appropriate. +2. Making changes to a cookbook. +3. Uploading and testing a cookbook. +4. Moving a tested cookbook to production. + +For example, to bump a version number, first make changes to the +cookbook, and then upload and test it. Repeat this process as required, +and then upload it using a knife command similar to: + +```bash +knife cookbook upload my-app +``` + +When the cookbook is finished, move those changes to the production +environment and use the `--freeze` option to prevent others from making +further changes: + +```bash +knife cookbook upload my-app -E production --freeze +``` + +Then modify the environment so that it prefers the newly uploaded +version: + +```bash +(vim|emacs|mate|ed) YOUR_REPO/environments/production.rb +``` + +Upload the updated environment: + +```bash +knife environment from file production.rb +``` + +And then deploy the new cookbook version. diff --git a/content/cookbooks/files.md b/content/cookbooks/files.md new file mode 100644 index 0000000..7ddd050 --- /dev/null +++ b/content/cookbooks/files.md @@ -0,0 +1,15 @@ ++++ +title = "Cookbook Files" +draft = false + +[menu] + [menu.cookbooks] + title = "Files" + identifier = "cookbooks/files.md Files" + parent = "cookbooks" + weight = 40 ++++ + +The `files` directory in Chef Infra cookbooks stores files that are used +in your cookbook with the [cookbook_file](/resources/bundled/cookbook_file/) +resource. diff --git a/content/cookbooks/libraries.md b/content/cookbooks/libraries.md new file mode 100644 index 0000000..699529d --- /dev/null +++ b/content/cookbooks/libraries.md @@ -0,0 +1,189 @@ ++++ +title = "About Libraries" +draft = false + +[menu] + [menu.cookbooks] + title = "Libraries" + identifier = "cookbooks/libraries.md Libraries" + parent = "cookbooks" + weight = 50 ++++ + +{{< readfile file="content/reusable/md/libraries_summary.md" >}} + +Use a library to: + +- Connect to a database +- Fetch secrets from a cloud provider +- Talk to an LDAP provider +- Do anything that can be done with Ruby + +## Syntax + +The syntax for a library varies because library files are created using +Ruby and are designed to handle custom situations. See the Examples +section below for samples. + +## Template Helper Modules + +{{< readfile file="content/reusable/md/resource_template_library_module.md" >}} + +## Examples + +The following examples show how to use cookbook libraries. + +### Create a Namespace + +A database can contain a list of virtual hosts that are used by +customers. A custom namespace could be created that looks something +like: + +```ruby +# Sample provided by "Arjuna (fujin)". Thank you! + +require 'sequel' + +class Chef::Recipe::ISP + # We can call this with ISP.vhosts + def self.vhosts + v = [] + @db = Sequel.mysql( + 'web', + user: 'example', + password: 'example_pw', + host: 'dbserver.example.com' + ) + @db[ + "SELECT virtualhost.domainname, + usertable.userid, + usertable.uid, + usertable.gid, + usertable.homedir + FROM usertable, virtualhost + WHERE usertable.userid = virtualhost.user_name" + ].all do |query| + vhost_data = { + servername: query[:domainname], + documentroot: query[:homedir], + uid: query[:uid], + gid: query[:gid], + } + v.push(vhost_data) + end + Chef::Log.debug('About to provision #{v.length} vhosts') + v + end +end +``` + +After the custom namespace is created, it could then be used in a +recipe, like this: + +```ruby +ISP.vhosts.each do |vhost| + directory vhost[:documentroot] do + owner vhost[:uid] + group vhost[:gid] + mode '0755' + action :create + end + + directory "#{vhost[:documentroot]}/#{vhost[:domainname]}" do + owner vhost[:uid] + group vhost[:gid] + mode '0755' + action :create + end +end +``` + +### Extend a Recipe + +A customer record is stored in an attribute file that looks like this: + +```ruby +mycompany_customers({ + bob: { + homedir: '/home/bob', + webdir: '/home/bob/web', + }, +} +) +``` + +A simple recipe may contain something like this: + +```ruby +directory node["mycompany_customers"]["bob"]["webdir"] do + owner 'bob' + group 'bob' + action :create +end +``` + +Or a less verbose version of the same simple recipe: + +```ruby +directory customer(:bob)[:webdir] do + owner 'bob' + group 'bob' + action :create +end +``` + +A simple library could be created that extends `Chef::Recipe::`, like +this: + +```ruby +class Chef + class Recipe + # A shortcut to a customer + def customer(name) + node["mycompany_customers"][name] + end + end +end +``` + +### Loop Over a Record + +A customer record is stored in an attribute file that looks like this: + +```ruby +mycompany_customers({ + bob: { + homedir: '/home/bob', + webdir: '/home/bob/web', + }, +} +) +``` + +If there are many customer records in an environment, a simple recipe +can be used to loop over every customer, like this: + +```ruby +all_customers do |name, info| + directory info[:webdir] do + owner name + group name + action :create + end +end +``` + +A simple library could be created that extends `Chef::Recipe::`, like +this: + +```ruby +class Chef + class Recipe + def all_customers(&block) + node["mycompany_customers"].each do |name, info| + block.call(name, info) + end + end + end +end +``` diff --git a/content/cookbooks/recipes/_index.md b/content/cookbooks/recipes/_index.md new file mode 100644 index 0000000..57e5b76 --- /dev/null +++ b/content/cookbooks/recipes/_index.md @@ -0,0 +1,547 @@ ++++ +title = "About Recipes" +draft = false + +[menu] + [menu.cookbooks] + title = "About Recipes" + identifier = "cookbooks/recipes/recipes.md About Recipes" + parent = "cookbooks/recipes" + weight = 10 ++++ + +{{< readfile file="content/reusable/md/cookbooks_recipe.md" >}} + +## YAML and JSON recipes + +{{< readfile file = "content/reusable/md/recipes_yaml_json_overview.md" >}} + +See the [YAML and JSON recipe documentation]({{< relref "recipes_json_yaml" >}}) for more information. + +## Recipe Attributes + +{{< readfile file="content/reusable/md/cookbooks_attribute.md" >}} + +{{< note >}} + +{{< readfile file="content/reusable/md/notes_see_attributes_overview.md" >}} + +{{< /note >}} + +## Environment Variables + +In UNIX, a process environment is a set of key-value pairs made +available to a process. Programs expect their environment to contain +information required for the program to run. The details of how these +key-value pairs are accessed depends on the API of the language being +used. + +If processes is started by using the **execute** or **script** resources +(or any of the resources based on those two resources, such as +**bash**), use the `environment` attribute to alter the environment that +will be passed to the process. + +```bash +bash 'env_test' do + code <<-EOF + echo $FOO +EOF + environment ({ 'FOO' => 'bar' }) +end +``` + +The only environment being altered is the one being passed to the child +process that's started by the **bash** resource. This won't affect +the Chef Infra Client environment or any child processes. + +## Work with Recipes + +The following sections show approaches to working with recipes. + +### Use Data Bags + +{{< readfile file="content/reusable/md/data_bag.md" >}} + +The contents of a data bag can be loaded into a recipe. For example, a +data bag named `apps` and a data bag item named `my_app`: + +```json +{ + "id": "my_app", + "repository": "git://github.com/company/my_app.git" +} +``` + +can be accessed in a recipe, like this: + +```ruby +my_bag = data_bag_item('apps', 'my_app') +``` + +The data bag item's keys and values can be accessed with a Hash: + +```ruby +my_bag['repository'] #=> 'git://github.com/company/my_app.git' +``` + +#### Secret Keys + +{{< readfile file="content/reusable/md/data_bag_encryption_secret_key.md" >}} + +#### Store Keys on Nodes + +An encryption key can also be stored in an alternate file on the nodes +that need it and specify the path location to the file inside an +attribute; however, `EncryptedDataBagItem.load` expects to see the +actual secret as the third argument, rather than a path to the secret +file. In this case, you can use `EncryptedDataBagItem.load_secret` to +slurp the secret file contents and then pass them: + +```ruby +# inside your attribute file: +# default[:mysql][:secretpath] = 'C:\\chef\\any_secret_filename' +# +# inside your recipe: +# look for secret in file pointed to by mysql attribute :secretpath +mysql_secret = Chef::EncryptedDataBagItem.load_secret('#{node['mysql']['secretpath']}') +mysql_creds = Chef::EncryptedDataBagItem.load('passwords', 'mysql', mysql_secret) +mysql_creds['pass'] # will be decrypted +``` + +### Assign Dependencies + +If a cookbook has a dependency on a recipe that's located in another +cookbook, that dependency must be declared in the metadata.rb file for +that cookbook using the `depends` keyword. + +{{< note >}} + +Declaring cookbook dependencies isn't required with chef-solo. + +{{< /note >}} + +For example, if the following recipe is included in a cookbook named +`my_app`: + +```ruby +include_recipe 'apache2::mod_ssl' +``` + +Then the metadata.rb file for that cookbook would have: + +```ruby +depends 'apache2' +``` + +### Include Recipes + +{{< readfile file="content/reusable/md/cookbooks_recipe_include_in_recipe.md" >}} + +### Reload Attributes + +Attributes sometimes depend on actions taken from within recipes, so it +may be necessary to reload a given attribute from within a recipe. For +example: + +```ruby +ruby_block 'some_code' do + block do + node.from_file(run_context.resolve_attribute('COOKBOOK_NAME', 'ATTR_FILE')) + end + action :nothing +end +``` + +### Use Ruby + +Anything that can be done with Ruby can be used within a recipe, such as +expressions (if, unless, etc.), case statements, loop statements, +arrays, hashes, and variables. In Ruby, the conditionals `nil` and +`false` are false; every other conditional is `true`. + +#### Assign a value + +A variable uses an equals sign (`=`) to assign a value. + +To assign a value to a variable: + +```ruby +package_name = 'apache2' +``` + +#### Use Case Statement + +A case statement can be used to compare an expression, and then execute +the code that matches. + +To select a package name based on platform: + +```ruby +package 'apache2' do + case node['platform'] + when 'centos', 'redhat', 'fedora', 'suse' + package_name 'httpd' + when 'debian', 'ubuntu' + package_name 'apache2' + when 'arch' + package_name 'apache' + end + action :install +end +``` + +#### Check Conditions + +An if expression can be used to check for conditions (true or false). + +To check for condition only for Debian and Ubuntu platforms: + +```ruby +if platform?('debian', 'ubuntu') + # do something if node['platform'] is debian or ubuntu +else + # do other stuff +end +``` + +#### Execute Conditions + +An unless expression can be used to execute code when a condition +returns a false value (effectively, an unless expression is the opposite +of an if statement). + +To use an expression to execute when a condition returns a false value: + +```ruby +unless node['platform_version'] == '5.0' + # do stuff on everything but 5.0 +end +``` + +#### Loop over Array + +A loop statement is used to execute a block of code one (or more) times. +A loop statement is created when `.each` is added to an expression that +defines an array or a hash. An array is an integer-indexed collection of +objects. Each element in an array can be associated with and referred to +by an index. + +To loop over an array of package names by platform: + +```ruby +['apache2', 'apache2-mpm'].each do |p| + package p +end +``` + +#### Loop over Hash + +A hash is a collection of key-value pairs. Indexing for a hash is done +using arbitrary keys of any object (as opposed to the indexing done by +an array). The syntax for a hash is: `key => "value"`. + +To loop over a hash of gem package names: + +```ruby +{ 'fog' => '0.6.0', 'highline' => '1.6.0' }.each do |g, v| + gem_package g do + version v + end +end +``` + +### Apply to Run-lists + +A recipe must be assigned to a run-list using the appropriate name, as +defined by the cookbook directory and namespace. For example, a cookbook +directory has the following structure: + +```text +cookbooks/ + apache2/ + recipes/ + default.rb + mod_ssl.rb +``` + +There are two recipes: a default recipe (that has the same name as the +cookbook) and a recipe named `mod_ssl`. The syntax that applies a recipe +to a run-list is similar to: + +```ruby +{ + 'run_list': [ + 'recipe[cookbook_name::default_recipe]', + 'recipe[cookbook_name::recipe_name]' + ] +} +``` + +where `::default_recipe` is implied (and doesn't need to be specified). +On a node, these recipes can be assigned to a node's run-list similar +to: + +```ruby +{ + 'run_list': [ + 'recipe[apache2]', + 'recipe[apache2::mod_ssl]' + ] +} +``` + +#### Chef Infra Server + +Use knife to add a recipe to the run-list for a node. For example: + +```bash +knife node run list add NODENAME "recipe[apache2]" +``` + +More than one recipe can be added: + +```bash +% knife node run list add NODENAME "recipe[apache2],recipe[mysql],role[ssh]" +``` + +which creates a run-list similar to: + +```ruby +run_list: + recipe[apache2] + recipe[mysql] + role[ssh] +``` + +#### chef-solo + +Use a JSON file to pass run-list details to chef-solo as long as the +cookbook in which the recipe is located is available to the system on +which chef-solo is running. For example, a file named `dna.json` +contains the following details: + +```json +{ + "run_list": ["recipe[apache2]"] +} +``` + +To add the run-list to the node, enter the following: + +```bash +sudo chef-solo -j /etc/chef/dna.json +``` + +### Use Search Results + +{{< readfile file="content/reusable/md/search.md" >}} + +The results of a search query can be loaded into a recipe. For example, +a simple search query (in a recipe) might look like this: + +```ruby +search(:node, 'attribute:value') +``` + +A search query can be assigned to variables and then used elsewhere in a +recipe. For example, to search for all nodes that have a role assignment +named `webserver`, and then render a template which includes those role +assignments: + +```ruby +webservers = search(:node, 'role:webserver') + +template '/tmp/list_of_webservers' do + source 'list_of_webservers.erb' + variables(webservers: webservers) +end +``` + +### Use Tags + +{{< readfile file="content/reusable/md/chef_tags.md" >}} + +{{< readfile file="content/reusable/md/cookbooks_recipe_tags.md" >}} + +### End Chef Infra Client Run + +Sometimes it may be necessary to stop processing a recipe and/or stop +processing the entire Chef Infra Client run. There are a few ways to do +this: + +- Use the `return` keyword to stop processing a recipe based on a + condition, but continue processing a Chef Infra Client run +- Use the `raise` keyword to stop a Chef Infra Client run by + triggering an unhandled exception +- Use a `rescue` block in Ruby code +- Use an [exception handler](/features/handlers/) + +The following sections show various approaches to ending a Chef Infra +Client run. + +#### return Keyword + +The `return` keyword can be used to stop processing a recipe based on a +condition, but continue processing a Chef Infra Client run. For example: + +```ruby +file '/tmp/name_of_file' do + action :create +end + +return if platform?('windows') + +package 'name_of_package' do + action :install +end +``` + +where `platform?('windows')` is the condition set on the `return` +keyword. When the condition is met, stop processing the recipe. This +approach is useful when there is no need to continue processing, such as +when a package can't be installed. In this situation, it's OK for a +recipe to stop processing. + +#### raise Keyword + +In certain situations it may be useful to stop a Chef Infra Client run +entirely by using an unhandled exception. The `raise` keyword can be used +to stop a Chef Infra Client run in both the compile and execute phases. + +{{< note >}} + +You may also see code that uses the `fail` keyword, which behaves the same +but is discouraged and will result in Cookstyle warnings. + +{{< /note >}} + +Use these keywords in a recipe---but outside of any resource blocks---to +trigger an unhandled exception during the compile phase. For example: + +```ruby +file '/tmp/name_of_file' do + action :create +end + +raise "message" if platform?('windows') + +package 'name_of_package' do + action :install +end +``` + +where `platform?('windows')` is the condition that will trigger the +unhandled exception. + +Use these keywords in the **ruby_block** resource to trigger an +unhandled exception during the execute phase. For example: + +```ruby +ruby_block "name" do + block do + # Ruby code with a condition, for example if ::File.exist?(::File.join(path, "/tmp")) + raise "message" # for example "Ordering issue with file path, expected foo" + end +end +``` + +Use these keywords in a class. For example: + +```ruby +class CustomError < StandardError; end +``` + +and then later on: + +```ruby +def custom_error + raise CustomError, "error message" +end +``` + +or: + +```ruby +def custom_error + raise CustomError, "error message" +end +``` + +#### Rescue Blocks + +Since recipes are written in Ruby, they can be written to attempt to +handle error conditions using the `rescue` block. + +For example: + +```ruby +begin + dater = data_bag_item(:basket, 'flowers') +rescue Net::HTTPClientException + # maybe some retry code here? + raise 'message_to_be_raised' +end +``` + +where `data_bag_item` makes an HTTP request to Chef Infra Server to +get a data bag item named `flowers`. If there is a problem, the request +will return a `Net::HTTPClientException`. The `rescue` block can be used +to try to retry or otherwise handle the situation. If the `rescue` block +is unable to handle the situation, then the `raise` keyword is used to +specify the message to be raised. + +### node.run_state + +Use `node.run_state` to stash transient data during a Chef Infra Client +run. This data may be passed between resources, and then evaluated +during the execution phase. `run_state` is an empty Hash that's always +discarded at the end of a Chef Infra Client run. + +For example, the following recipe will install the Apache web server, +randomly choose PHP or Perl as the scripting language, and then install +that scripting language: + +```ruby +package 'httpd' do + action :install +end + +ruby_block 'randomly_choose_language' do + block do + if Random.rand > 0.5 + node.run_state['scripting_language'] = 'php' + else + node.run_state['scripting_language'] = 'perl' + end + end +end + +package 'scripting_language' do + package_name lazy { node.run_state['scripting_language'] } + action :install +end +``` + +where: + +- The **ruby_block** resource declares a `block` of Ruby code that's + run during the execution phase of a Chef Infra Client run +- The `if` statement randomly chooses PHP or Perl, saving the choice + to `node.run_state['scripting_language']` +- When the **package** resource has to install the package for the + scripting language, it looks up the scripting language and uses the + one defined in `node.run_state['scripting_language']` +- `lazy {}` ensures that the **package** resource evaluates this + during the execution phase of a Chef Infra Client run (as opposed to + during the compile phase) + +When this recipe runs, Chef Infra Client will print something like the +following: + +```bash +* ruby_block[randomly_choose_language] action run + - execute the ruby block randomly_choose_language + +* package[scripting_language] action install + - install version 5.3.3-27.el6_5 of package php +``` diff --git a/content/cookbooks/recipes/debug.md b/content/cookbooks/recipes/debug.md new file mode 100644 index 0000000..03cd71f --- /dev/null +++ b/content/cookbooks/recipes/debug.md @@ -0,0 +1,350 @@ ++++ +title = "Debug Recipes, Chef Infra Client Runs" +draft = false + +[menu] + [menu.cookbooks] + title = "Debug Recipes, Client Runs" + identifier = "cookbooks/recipes/debug.md Debug Recipes, Client Runs" + parent = "cookbooks/recipes" + weight = 20 ++++ + +Elements of good approaches to building cookbooks and recipes that are +reliable include: + +* A consistent syntax pattern when constructing recipes +* Using the same patterns in Ruby +* Using resources included in Chef Infra Client or community cookbooks before creating custom ones + +Ideally, the best way to debug a recipe is to not have to debug it in the first place. That said, the following sections discuss various approaches to debugging recipes and failed Chef Infra Client runs. + +## Basic + +Some simple ways to identify common issues that can trigger recipe and/or Chef Infra Client run failures include: + +* Using an empty run-list +* Using verbose logging with knife +* Using logging with Chef Infra Client +* Using the **log** resource in a recipe to define custom logging + +### Empty Run-lists + +{{< readfile file="content/reusable/md/node_run_list_empty.md" >}} + +### Knife + +Use the verbose logging that's built into knife: + +`-V`, `--verbose` + +: Set for more verbose outputs. Use `-VV` for much more verbose outputs. Use `-VVV` for maximum verbosity, which may provide more information than is actually helpful. + +{{< note >}} + +Plugins don't always support verbose logging. + +{{< /note >}} + +### Chef Infra Client + +Use the verbose logging that's built into Chef Infra Client: + +`-l LEVEL`, `--log_level LEVEL` + +: The level of logging to be stored in a log file. Possible levels: `auto` (default), `debug`, `error`, `fatal`, `info`, `trace`, or `warn`. Default value: `warn` (when a terminal is available) or `info` (when a terminal isn't available). + +`-L LOGLOCATION`, `--logfile c` + +: The location of the log file. This is recommended when starting any executable as a daemon. Default value: `STDOUT`. + +### log Resource + +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 isn't built into the resource collection, use +`Chef::Log` instead of the **log** resource.) + +{{< note >}} + +By default, every log resource that executes will count as an updated +resource in the updated resource count at the end of a Chef run. You can +disable this behavior by adding `count_log_resource_updates false` to +your Chef `client.rb` configuration file. + +{{< /note >}} + +New in 12.0, `-o RUN_LIST_ITEM`. Changed in 12.0 `-f` no longer allows unforked intervals, `-i SECONDS` is applied before a Chef Infra Client run. + +#### Syntax + +{{< readfile file="content/reusable/md/resource_log_syntax.md" >}} + +#### Actions + +The log resource has the following actions: + +`:nothing` + +: {{< readfile file="content/reusable/md/resources_common_actions_nothing.md" >}} + +`:write` + +: Default. Write to log. + +#### Properties + +{{< readfile file="content/reusable/md/resource_log_properties.md" >}} + +#### Examples + +The following examples demonstrate various approaches for using +resources in recipes: + +##### Specify a Log Entry + +```ruby +log 'a string to log' +``` + +##### Set debug logging level + +{{< readfile file="content/reusable/md/resource_log_set_debug.md" >}} + +##### Create log entry when the contents of a data bag are used + +{{< readfile file="content/reusable/md/resource_log_set_debug.md" >}} + +##### Add a message to a log file + +```ruby +log 'message' do + message 'This is the message that will be added to the log.' + level :info +end +``` + +## Advanced + +Some more complex ways to debug issues with a Chef Infra Client run +include: + +* Using the **chef_handler** resource +* Using the chef-shell and the **breakpoint** resource to add breakpoints to recipes, and to then step through the recipes using the breakpoints +* Using the `debug_value` method from chef-shell to identify the locations from which attribute values are being set +* Using the `ignore_failure` method in a recipe to force Chef Infra Client to move past an error to see what else is going on in the recipe, outside of a known failure +* Using chef-solo to run targeted Chef Infra Client runs for specific scenarios + +### chef_handler + +{{< readfile file="content/reusable/md/handler.md" >}} + +{{< readfile file="content/reusable/md/handler_types.md" >}} + +Read more [about exception, report, and start handlers](/features/handlers/). + +### chef-shell + +{{< readfile file="content/reusable/md/chef_shell_summary.md" >}} + +{{< readfile file="content/reusable/md/chef_shell_modes.md" >}} + +#### Configure + +{{< readfile file="content/reusable/md/chef_shell_config.md" >}} + +#### chef-shell.rb + +{{< readfile file="content/reusable/md/chef_shell_config_rb.md" >}} + +#### Run as a Chef Infra Client + +{{< readfile file="content/reusable/md/chef_shell_run_as_chef_client.md" >}} + +#### Manage + +{{< readfile file="content/reusable/md/chef_shell_manage.md" >}} + +### breakpoint Resource + +{{< readfile file="content/reusable/md/chef_shell_breakpoints.md" >}} + +Use the **breakpoint** resource to add breakpoints to recipes. Run the +chef-shell in Chef Infra Client mode, and then use those breakpoints to +debug recipes. Breakpoints are ignored by Chef Infra Client during an +actual Chef Infra Client run. That said, breakpoints are typically used +to debug recipes only when running them in a non-production environment, +after which they're removed from those recipes before the parent +cookbook is uploaded to Chef Infra Server. + +#### Syntax + +A **breakpoint** resource block creates a breakpoint in a recipe: + +```ruby +breakpoint 'name' do + action :break +end +``` + +where + +`:break` will tell Chef Infra Client to stop running a recipe; can +only be used when Chef Infra Client is being run in chef-shell mode + +#### Actions + +The breakpoint resource has the following actions: + +`:break` + +: Use to add a breakpoint to a recipe. + +`:nothing` + +: {{< readfile file="content/reusable/md/resources_common_actions_nothing.md" >}} + +#### Attributes + +This resource doesn't have any properties. + +#### Examples + +The following examples demonstrate various approaches for using resources in recipes: + +##### A recipe without a breakpoint + +```ruby +yum_key node['yum']['elrepo']['key'] do + url node['yum']['elrepo']['key_url'] + action :add +end + +yum_repository 'elrepo' do + description 'ELRepo.org Community Enterprise Linux Extras Repository' + key node['yum']['elrepo']['key'] + mirrorlist node['yum']['elrepo']['url'] + includepkgs node['yum']['elrepo']['includepkgs'] + exclude node['yum']['elrepo']['exclude'] + action :create +end +``` + +##### The same recipe with breakpoints + +```ruby +breakpoint "before yum_key node['yum']['repo_name']['key']" do + action :break +end + +yum_key node['yum']['repo_name']['key'] do + url node['yum']['repo_name']['key_url'] + action :add +end + +breakpoint "after yum_key node['yum']['repo_name']['key']" do + action :break +end + +breakpoint "before yum_repository 'repo_name'" do + action :break +end + +yum_repository 'repo_name' do + description 'description' + key node['yum']['repo_name']['key'] + mirrorlist node['yum']['repo_name']['url'] + includepkgs node['yum']['repo_name']['includepkgs'] + exclude node['yum']['repo_name']['exclude'] + action :create +end + +breakpoint "after yum_repository 'repo_name'" do + action :break +end +``` + +where the name of each breakpoint is an arbitrary string. In the +previous examples, the names are used to indicate if the breakpoint is +before or after a resource, and then also to specify which resource. + +### Step Through Run-list + +{{< readfile file="content/reusable/md/chef_shell_step_through_run_list.md" >}} + +### Debug Existing Recipe + +{{< readfile file="content/reusable/md/chef_shell_debug_existing_recipe.md" >}} + +### Advanced Debugging + +{{< readfile file="content/reusable/md/chef_shell_advanced_debug.md" >}} + +### debug_value + +Use the `debug_value` method to discover the location within the attribute precedence hierarchy from which a particular attribute (or sub-attribute) is set. This method is available when running chef-shell in Chef Infra Client mode: + +```bash +chef-shell -z +``` + +For example, the following attributes exist in a cookbook. Some are defined in a role file: + +```ruby +default_attributes 'test' => { 'source' => 'role default' } +override_attributes 'test' => { 'source' => 'role override' } +``` + +And others are defined in an attributes file: + +```ruby +default[:test][:source] = 'attributes default' +normal[:test][:source] = 'attributes normal' +override[:test][:source] = 'attributes override' +``` + +To debug the location in which the value of `node[:test][:source]` is set, use chef-shell and run a command similar to: + +```ruby +pp node.debug_value('test', 'source') +``` + +This will pretty-print return all of the attributes and sub-attributes as an array of arrays; `:not_present` is returned for any attribute without a value: + +```bash +[['set_unless_enabled?', false], + ['default', 'attributes default'], + ['env_default', :not_present], + ['role_default', 'role default'], + ['force_default', :not_present], + ['normal', 'attributes normal'], + ['override', 'attributes override'], + ['role_override', 'role override'], + ['env_override', :not_present], + ['force_override', :not_present], + ['automatic', :not_present]] +``` + +where + +* `set_unless_enabled` indicates if the attribute collection is in `set_unless` mode; this typically returns `false` +* Each attribute type is listed in order of precedence +* Each attribute value shown is the value that's set for that precedence level +* `:not_present` is shown for any attribute precedence level that has no attributes + +### ignore_failure method + +All resources share a set of common actions, attributes, and other properties. Use the following attribute in a resource to help identify where an issue within a recipe may be located: + +| Attribute | Description | +|----------------|---------------------------------------------------------------------------------------| +| ignore_failure | Continue running a recipe if a resource fails for any reason. Default value: `false`. | + +### chef-solo + +See [chef-solo (executable)](/features/chef_solo/ctl_chef_solo/) for complete CTL documentation. + +{{< readfile file="content/reusable/md/chef_solo_summary.md" >}} + +See [chef-solo (executable)](/features/chef_solo/ctl_chef_solo/) for complete CTL documentation. diff --git a/content/cookbooks/recipes/recipes_json_yaml.md b/content/cookbooks/recipes/recipes_json_yaml.md new file mode 100644 index 0000000..da18ca2 --- /dev/null +++ b/content/cookbooks/recipes/recipes_json_yaml.md @@ -0,0 +1,499 @@ ++++ +title = "Chef Infra JSON and YAML recipes" +draft = false +gh_repo = "chef-web-docs" + +[menu] + [menu.infra] + title = "JSON/YAML recipes" + identifier = "chef_infra/cookbook_reference/recipes/YAML recipes" + parent = "chef_infra/cookbook_reference/recipes" + weight = 20 ++++ + +{{< readfile file = "content/reusable/md/recipes_yaml_json_overview.md" >}} + +For information about Ruby recipes, see the [Ruby recipe documentation]({{< relref "recipes" >}}). + +## Support + +We introduced YAML recipes in Chef Infra Client 16.0. We added support for YAML recipes with the `.yml` file extension in Infra Client 17.2.29. We added support for JSON recipes in Chef Infra Client 18.8. + +## Create a JSON or YAML recipe + +To create a JSON or YAML recipe, follow these steps: + +1. Create a JSON or YAML file for your recipe in the same locations as Ruby recipes: + + - Standard recipe location: + + - `cookbooks/cookbook_name/recipes/default.yml` + - `cookbooks/cookbook_name/recipes/default.yaml` + - `cookbooks/cookbook_name/recipes/default.json` + + - Named recipes: + + - `cookbooks/cookbook_name/recipes/web.yml` + - `cookbooks/cookbook_name/recipes/database.yaml` + - `cookbooks/cookbook_name/recipes/app.json` + + - Root-level recipe alias (acts as the default recipe): + + - `cookbooks/cookbook_name/recipe.yml` + - `cookbooks/cookbook_name/recipe.yaml` + - `cookbooks/cookbook_name/recipe.json` + + {{< note >}} + + Creating more than one recipe with the same filename but different file extensions isn't supported. For example, `default.yaml` and `default.yml`. + + {{< /note >}} + +1. Define your recipe with the top-level `resources` key containing an array of items where each item has the following: + + - `type`: The Chef resource type (string) + - `name`: The resource name/identifier (string) + - resource-specific actions and properties as key-value pairs + + For example: + + {{< foundation_tabs tabs-id="create-json-yaml-recipe-example" >}} + {{< foundation_tab active="true" panel-link="create-yaml-recipe-example" tab-text="YAML">}} + {{< foundation_tab panel-link="create-json-recipe-example" tab-text="JSON" >}} + {{< /foundation_tabs >}} + + {{< foundation_tabs_panels tabs-id="create-json-yaml-recipe-example" >}} + {{< foundation_tabs_panel active="true" panel-id="create-yaml-recipe-example" >}} + + ```yaml + resources: + - type: "package" + name: "nginx" + action: "install" + version: "1.18.0" + - type: "service" + name: "nginx" + action: ["enable", "start"] + ``` + + {{< /foundation_tabs_panel >}} + + {{< foundation_tabs_panel panel-id="create-json-recipe-example" >}} + + ```json + { + "resources": [ + { + "type": "package", + "name": "nginx", + "action": "install", + "version": "1.18.0" + }, + { + "type": "service", + "name": "nginx", + "action": [ + "enable", + "start" + ] + } + ] + } + ``` + + {{< /foundation_tabs_panel >}} + {{< /foundation_tabs_panels >}} + + In this example: + + - the [`package` resource]({{< relref "/resources/bundled/package/" >}}) uses the `install` action and the `version` property to install Nginx 1.18.0. + - the [`service` resource]({{< relref "/resources/bundled/service/" >}}) uses the `enable` and `start` actions to enable and start Nginx. + +## Examples + +### Basic file management + +Use the [`directory` resource]({{< relref "/resources/bundled/directory">}}) to create the `/opt/app_name` directory and apply owner and group permissions to the directory. Use the [`file` resource]({{< relref "/resources/bundled/">}}) to create the `/opt/app_name/config.txt` file, add text to the file, and apply file owner and group permissions to the file. + +{{< foundation_tabs tabs-id="basic-file-management-json-yaml-recipe-example" >}} + {{< foundation_tab active="true" panel-link="basic-file-management-yaml-recipe-example" tab-text="YAML">}} + {{< foundation_tab panel-link="basic-file-management-json-recipe-example" tab-text="JSON" >}} +{{< /foundation_tabs >}} + +{{< foundation_tabs_panels tabs-id="basic-file-management-json-yaml-recipe-example" >}} +{{< foundation_tabs_panel active="true" panel-id="basic-file-management-yaml-recipe-example" >}} + +```yaml +--- +resources: + - type: "directory" + name: "/opt/app_name" + owner: "app_name" + group: "app_name" + mode: "0755" + recursive: true + + - type: "file" + name: "/opt/app_name/config.txt" + content: "This is a configuration file" + owner: "app_name" + group: "app_name" + mode: "0644" +``` + +{{< /foundation_tabs_panel >}} + +{{< foundation_tabs_panel panel-id="basic-file-management-json-recipe-example" >}} + +```json +{ + "resources": [ + { + "type": "directory", + "name": "/opt/app_name", + "owner": "app_name", + "group": "app_name", + "mode": "0755", + "recursive": true + }, + { + "type": "file", + "name": "/opt/app_name/config.txt", + "content": "This is a configuration file", + "owner": "app_name", + "group": "app_name", + "mode": "0644" + } + ] +} +``` + +{{< /foundation_tabs_panel >}} +{{< /foundation_tabs_panels >}} + +### Package and service management + +Use the [`package` resource]({{< relref "/resources/bundled/package">}}) to install Nginx and curl. Then use the [`service` resource]({{< relref "/resources/bundled/service">}}) to enable and start Nginx. + +{{< foundation_tabs tabs-id="package-service-management-json-yaml-recipe-example" >}} + {{< foundation_tab active="true" panel-link="package-service-management-yaml-recipe-example" tab-text="YAML">}} + {{< foundation_tab panel-link="package-service-management-json-recipe-example" tab-text="JSON" >}} +{{< /foundation_tabs >}} + +{{< foundation_tabs_panels tabs-id="package-service-management-json-yaml-recipe-example" >}} +{{< foundation_tabs_panel active="true" panel-id="package-service-management-yaml-recipe-example" >}} + +```yaml +--- +resources: + - type: "package" + name: "nginx" + action: "install" + + - type: "package" + name: "curl" + action: "install" + + - type: "service" + name: "nginx" + action: ["enable", "start"] +``` + +{{< /foundation_tabs_panel >}} + +{{< foundation_tabs_panel panel-id="package-service-management-json-recipe-example" >}} + +```json +{ + "resources": [ + { + "type": "package", + "name": "nginx", + "action": "install" + }, + { + "type": "package", + "name": "curl", + "action": "install" + }, + { + "type": "service", + "name": "nginx", + "action": [ + "enable", + "start" + ] + } + ] +} +``` + +{{< /foundation_tabs_panel >}} +{{< /foundation_tabs_panels >}} + +### User management + +Use the [`group` resource]({{< relref "/resources/bundled/group">}}) to create a group called "developers" and the [`user` resource]({{< relref "/resources/bundled/">}}) to create a user, give them properties, and assign them to the developers group. + +{{< foundation_tabs tabs-id="user-management-json-yaml-recipe-example" >}} + {{< foundation_tab active="true" panel-link="user-management-yaml-recipe-example" tab-text="YAML">}} + {{< foundation_tab panel-link="user-management-json-recipe-example" tab-text="JSON" >}} +{{< /foundation_tabs >}} + +{{< foundation_tabs_panels tabs-id="user-management-json-yaml-recipe-example" >}} +{{< foundation_tabs_panel active="true" panel-id="user-management-yaml-recipe-example" >}} + +```yaml +--- +resources: + - type: "group" + name: "developers" + gid: 3000 + + - type: "user" + name: "alice" + uid: 2001 + gid: 3000 + home: "/home/alice" + shell: "/bin/bash" + action: "create" +``` + +{{< /foundation_tabs_panel >}} + +{{< foundation_tabs_panel panel-id="user-management-json-recipe-example" >}} + +```json +{ + "resources": [ + { + "type": "group", + "name": "developers", + "gid": 3000 + }, + { + "type": "user", + "name": "alice", + "uid": 2001, + "gid": 3000, + "home": "/home/alice", + "shell": "/bin/bash", + "action": "create" + } + ] +} +``` + +{{< /foundation_tabs_panel >}} +{{< /foundation_tabs_panels >}} + +### Template with static variables + +Use the [`template` resource]({{< relref "/resources/bundled/template">}}) create the `/etc/app_name/config.yml` file using the `config.yml.erb` template. + +{{< foundation_tabs tabs-id="template-with-static-variables-json-yaml-recipe-example" >}} + {{< foundation_tab active="true" panel-link="template-with-static-variables-yaml-recipe-example" tab-text="YAML">}} + {{< foundation_tab panel-link="template-with-static-variables-json-recipe-example" tab-text="JSON" >}} +{{< /foundation_tabs >}} + +{{< foundation_tabs_panels tabs-id="template-with-static-variables-json-yaml-recipe-example" >}} +{{< foundation_tabs_panel active="true" panel-id="template-with-static-variables-yaml-recipe-example" >}} + +```yaml +--- +resources: + - type: "template" + name: "/etc/app_name/config.yml" + source: "config.yml.erb" + owner: "root" + group: "root" + mode: "0644" +``` + +{{< /foundation_tabs_panel >}} + +{{< foundation_tabs_panel panel-id="template-with-static-variables-json-recipe-example" >}} + +```json +{ + "resources": [ + { + "type": "template", + "name": "/etc/app_name/config.yml", + "source": "config.yml.erb", + "owner": "root", + "group": "root", + "mode": "0644" + } + ] +} +``` + +{{< /foundation_tabs_panel >}} +{{< /foundation_tabs_panels >}} + +### Guards + +Some common resource functionality is also supported, as long as the value of a property can be expressed as one of the four primitive types (string, integer, boolean, array). That means it's possible to use [`only_if` or `not_if` guards]({{< relref "/resources/common_functionality/#guards" >}}) as long as they shell out to Bash or PowerShell and aren't passed a Ruby block. + +For example, this is supported: + +{{< foundation_tabs tabs-id="guards-json-yaml-recipe-example" >}} + {{< foundation_tab active="true" panel-link="guards-yaml-recipe-example" tab-text="YAML">}} + {{< foundation_tab panel-link="guards-json-recipe-example" tab-text="JSON" >}} +{{< /foundation_tabs >}} + +{{< foundation_tabs_panels tabs-id="guards-json-yaml-recipe-example" >}} +{{< foundation_tabs_panel active="true" panel-id="guards-yaml-recipe-example" >}} + +```yaml +resources: +- type: "directory" + name: "/var/www/html" + only_if: "which apache2" +``` + +{{< /foundation_tabs_panel >}} + +{{< foundation_tabs_panel panel-id="guards-json-recipe-example" >}} + +```json +{ + "resources": [ + { + "type": "directory", + "name": "/var/www/html", + "only_if": "which apache2" + } + ] +} +``` + +{{< /foundation_tabs_panel >}} +{{< /foundation_tabs_panels >}} + +Ruby blocks aren't supported: + +```yaml +# Can't be expressed in YAML - Ruby blocks not supported +resources: +- type: "directory" + name: "/var/www/html" + only_if: "{ ::File.exist?('/usr/sbin/apache2') }" +``` + +## Convert a YAML recipe to Ruby + +Use the `knife yaml convert` command to convert YAML recipes to Ruby: + +```shell +knife yaml convert recipes/default.yml recipes/default.rb +``` + +Converting from Ruby to YAML or JSON isn't supported due to their limitations. + +## YAML and JSON recipe limitations + +Chef Infra YAML and JSON recipes have the following limitations. + +### No Ruby code blocks + +YAML and JSON recipes can't include Ruby code blocks, which limits their functionality compared to Ruby recipes: + +```ruby +# Can't be expressed in YAML - Ruby blocks not supported +template "/etc/nginx/nginx.conf" do + source "nginx.conf.erb" + variables({ + worker_processes: node['cpu']['total'] + }) + notifies :restart, "service[nginx]", :delayed + only_if { node['platform'] == 'ubuntu' } +end +``` + +### No conditional logic + +YAML and JSON recipes can't include conditional logic like `if`, `unless`, `only_if`, or `not_if` with Ruby expressions: + +```yaml +# Can't include complex conditionals +resources: + - type: "package" + name: "nginx" + # Can't do: only_if { node['platform'] == 'ubuntu' } +``` + +### No node attribute access + +YAML and JSON recipes can't directly access node attributes or perform Ruby evaluations: + +```yaml +# Can't access node attributes dynamically +resources: + - type: "user" + name: "webapp" + # Can't do: home "/home/#{node['webapp']['user']}" + home: "/home/webapp" # Must be static +``` + +### No resource notifications + +YAML and JSON recipes can't express complex resource relationships and notifications: + +```yaml +# Can't express notifications between resources +resources: + - type: "template" + name: "/etc/nginx/nginx.conf" + source: "nginx.conf.erb" + # Can't do: notifies :restart, "service[nginx]", :delayed +``` + +### No include or require functionality + +YAML and JSON recipes can't include other recipes or libraries: + +```yaml +# Can't include other recipes +# include_recipe "cookbook::other_recipe" +``` + +## Troubleshooting + +### Missing `resources` key + +Chef Infra Client returns this error if a recipe is missing the top-level `resources` hash. + +```text +ArgumentError: YAML recipe 'recipes/default.yml' must contain a top-level 'resources' hash (YAML sequence), i.e. 'resources:' +``` + +### Single document limitation + +YAML recipes support only one YAML document in each file. Multiple documents separated by `---` aren't allowed: + +```yaml +--- +resources: + - type: "file" + name: "/tmp/file1.txt" +--- +resources: + - type: "file" + name: "/tmp/file2.txt" +``` + +Chef Infra Client returns the following error with multiple documents in one file: + +```text +ArgumentError: YAML recipe 'recipes/default.yml' contains multiple documents, only one is supported +``` + +### Ambiguous file extensions + +Chef Infra Client returns this error if two recipes have the same filename with different file extensions. For example, `default.yaml` and `default.yml`. + +```text +Chef::Exceptions::AmbiguousYAMLFile: Found both default.yml and default.yaml in cookbook, update the cookbook to remove one +``` diff --git a/content/cookbooks/templates.md b/content/cookbooks/templates.md new file mode 100644 index 0000000..ae2cea6 --- /dev/null +++ b/content/cookbooks/templates.md @@ -0,0 +1,90 @@ ++++ +title = "About Templates" +draft = false + +[menu] + [menu.cookbooks] + title = "Templates" + identifier = "cookbooks/templates.md Templates" + parent = "cookbooks" + weight = 100 ++++ + +{{< readfile file="content/reusable/md/template.md" >}} + +The `templates` directory doesn't exist by default in a cookbook. +Generate the `templates` directory and a template file from the `chef-repo/cookbooks` directory with the command: + +```bash +chef generate template PATH_TO_COOKBOOK TEMPLATE_NAME +``` + +For example, this command generates a `httpd` template in the `custom_web` cookbook: + +```bash +chef generate template cookbooks/custom_web httpd +``` + +The `custom_web` cookbook directory with a template has the structure: + +```text +. cookbooks +├── README.md +└── custom_web + ├── CHANGELOG.md + ├── LICENSE + ├── Policyfile.rb + ├── README.md + ├── chefignore + ├── compliance + │ ├── README.md + │ ├── inputs + │ ├── profiles + │ └── waivers + ├── kitchen.yml + ├── metadata.rb + ├── recipes + │ └── default.rb + ├── templates + │ └── httpd.erb + └── test + └── integration + └── default + └── default_test.rb +``` + +## Requirements + +{{< readfile file="content/reusable/md/template_requirements.md" >}} + +## Variables + +{{< readfile file="content/reusable/md/template_variables.md" >}} + +## File Specificity + +{{< readfile file="content/reusable/md/template_specificity.md" >}} + +{{< readfile file="content/reusable/md/template_specificity_pattern.md" >}} + +{{< readfile file="content/reusable/md/template_specificity_example.md" >}} + +## Host Notation + +{{< readfile file="content/reusable/md/template_host_notation.md" >}} + +## Transfer Frequency + +{{< readfile file="content/reusable/md/template_transfer_frequency.md" >}} + +## Partial Templates + +{{< readfile file="content/reusable/md/template_partials.md" >}} + +### variables Attribute + +{{< readfile file="content/reusable/md/template_partials_variables_attribute.md" >}} + +### render Method + +{{< readfile file="content/reusable/md/template_partials_render_method.md" >}} diff --git a/content/extension_apis/_index.md b/content/extension_apis/_index.md new file mode 100644 index 0000000..1f75574 --- /dev/null +++ b/content/extension_apis/_index.md @@ -0,0 +1,5 @@ ++++ +title = "Extension APIs" + +list_pages = true ++++ \ No newline at end of file diff --git a/content/extension_apis/community_plugins.md b/content/extension_apis/community_plugins.md new file mode 100644 index 0000000..cf4112c --- /dev/null +++ b/content/extension_apis/community_plugins.md @@ -0,0 +1,102 @@ ++++ +title = "Community Plugins" +draft = false + +[menu] + [menu.extension_apis] + title = "Community Plugins" + identifier = "extension_apis/ohai_plugins/Community Plugins" + parent = "extension_apis/ohai_plugins" + weight = 20 ++++ + + +This page lists plugins for Ohai plugins and Chef Infra Client handlers +that are developed and maintained by the Chef community. + +## Ohai + +{{< readfile file="content/reusable/md/ohai_summary.md" >}} + +The following Ohai plugins are available from the open source community: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PluginDescription
dell.rbAdds some useful Dell server information to Ohai. For example, service tag, express service code, storage info, or RAC info. To use this plugin, OMSA and SMBIOS applications need to be installed.
ipmi.rbAdds a MAC address and an IP address to Ohai, where available.
kvm_extensions.rbAdds extensions for virtualization attributes to provide additional host and guest information for KVM.
ladvd.rbAdds ladvd information to Ohai, when it exists.
lxc_virtualization.rbAdds extensions for virtualization attributes to provide host and guest information for Linux containers.
network_addr.rbAdds extensions for network attributes with additional ipaddrtype_iface attributes to make it semantically easier to retrieve addresses.
network_ports.rbAdds extensions for network attributes so that Ohai can detect to which interfaces TCP and UDP ports are bound.
parse_host_plugin.rbAdds the ability to parse a host name using three top-level attribute and five nested attributes.
r.rbAdds the ability to collect basic information about the R Project.
sysctl.rbAdds sysctl information to Ohai.
vserver.rbAdds extensions for virtualization attributes to allow a Linux virtual server host and guest information to be used by Ohai.
wtf.rbAdds the irreverent wtfismyip.com service so that Ohai can determine a machine's external IPv4 address and geographical location.
xenserver.rbAdds extensions for virtualization attributes to load up Citrix XenServer host and guest information.
win32_software.rbAdds the ability for Ohai to use Windows Management Instrumentation (WMI) to discover useful information about software that's installed on any node that's running Windows.
win32_svc.rbAdds the ability for Ohai to query using Windows Management Instrumentation (WMI) to get information about all services that are registered on a node that's running Windows.
+ +## Handlers + +{{< readfile file="content/reusable/md/handler.md" >}} + +{{< readfile file="content/reusable/md/handler_community_handlers.md" >}} diff --git a/content/extension_apis/custom_plugins.md b/content/extension_apis/custom_plugins.md new file mode 100644 index 0000000..74edd37 --- /dev/null +++ b/content/extension_apis/custom_plugins.md @@ -0,0 +1,599 @@ ++++ +title = "Writing Ohai Custom Plugins" +draft = false + +[menu] + [menu.extension_apis] + title = "Custom Plugins" + identifier = "extension_apis/ohai_plugins/ohai_custom.md Custom Plugins" + parent = "extension_apis/ohai_plugins" + weight = 10 ++++ + +You can write custom Ohai plugins to collect additional configuration attributes with Ohai to provide to Chef Infra Client during runs. + +Ohai plugins are written in Ruby with a plugin DSL documented below. Being written in Ruby provides access to all Ruby's built-in functionality, as well as 3rd party gem functionality. Plugins can parse the output of any local command on the node, or they can fetch data from external APIs. Examples of plugins that users have written: - A plugin to gather node information including data center, rack, and rack position from an inventory server - A plugin to gather additional RAID array information from a controller utility - A plugin to gather hardware +warranty information from a vendor API + +See [About Ohai](/features/ohai/) for information on Ohai configuration and usage. + +## Install Ohai Plugins + +Install custom Ohai plugins by creating an `ohai` directory in your cookbook and saving your plugin code to this location. + +To migrate custom Ohai plugins from the deprecated ohai cookbook: + +1. Create an `ohai` directory in your cookbook +1. Move your plugin into the `ohai` directory +1. Remove the outdated custom Ohai plugin installation code from your code + +Chef Infra Client will move the file into the correct location, load it, and return the data in the next configuration run. Chef Infra Client will provide other cookbooks that depend on the custom Ohai plugin with the correct data. + +## Syntax + +The syntax for an Ohai plugin is as follows: + +```ruby +Ohai.plugin(:Name) do + provides 'attribute', 'attribute/subattribute' + depends 'attribute', 'attribute' + + def shared_method + # some Ruby code that defines the shared method + attribute my_data + end + + collect_data(:default) do + # some Ruby code + attribute my_data + end + + collect_data(:platform...) do + # some Ruby code that defines platform-specific requirements + attribute my_data + end +end +``` + +where + +- Required. `(:Name)` is used to identify the plugin; when two plugins have the same `(:Name)`, those plugins are joined together and run as if they were a single plugin. This value must be a valid Ruby class name, starting with a capital letter and containing only alphanumeric characters +- Required. `provides` is a comma-separated list of one (or more) attributes that are defined by this plugin. This attribute will become an automatic attribute (`node['attribute']`) after it's collected by Ohai at the start of a Chef Infra Client run. An attribute can also be defined using an `attribute/subattribute` pattern +- `depends` is a comma-separated list of one (or more) attributes that are collected by another plugin; as long as the value is collected by another Ohai plugin, it can be used by any plugin +- `shared_method` defines code that can be shared among one (or more) `collect_data` blocks; for example, instead of defining a mash for each `collect_data` block, the code can be defined as a shared method, and then called from any `collect_data` block +- `collect_data` is a block of Ruby code that's called by Ohai when it runs; one (or more) `collect_data` blocks can be defined in a plugin, but only a single `collect_data` block is ever run. +- `collect_data(:default)` is the code block that runs when a node's platform isn't defined by a platform-specific `collect_data` block +- `collect_data(:platform)` is a platform-specific code block that's run when a match exists between the node's platform and this `collect_data` block; only one `collect_data` block may exist for each platform; possible values: `:aix`, `:darwin`, `:freebsd`, `:linux`, `:openbsd`, `:netbsd`, `:solaris2`, `:windows`, or any other value from `RbConfig::CONFIG['host_os']` +- `my_data` is string (`a string value`) or an empty mash (`{ :setting_a => 'value_a', :setting_b => 'value_b' }`). This is used to define the data that should be collected by the plugin + +For example, the following plugin looks up data on virtual machines hosted in Amazon EC2, Google Compute Engine, Rackspace, Eucalyptus, Linode, OpenStack, and Microsoft Azure: + +```ruby +Ohai.plugin(:Cloud) do + provides 'cloud' + + depends 'ec2' + depends 'gce' + depends 'rackspace' + depends 'eucalyptus' + depends 'linode' + depends 'openstack' + depends 'azure' + + def create_objects + cloud Mash.new + cloud[:public_ips] = [] + cloud[:private_ips] = [] + end + + ... + + def on_gce? + gce != nil + end + + def get_gce_values + cloud[:public_ipv4] = [] + cloud[:local_ipv4] = [] + + public_ips = gce['instance']['networkInterfaces'].collect do |interface| + if interface.has_key?('accessConfigs') + interface['accessConfigs'].collect{|ac| ac['externalIp']} + end + end.flatten.compact + + private_ips = gce['instance']['networkInterfaces'].collect do |interface| + interface['ip'] + end.compact + + cloud[:public_ips] += public_ips + cloud[:private_ips] += private_ips + cloud[:public_ipv4] += public_ips + cloud[:public_hostname] = nil + cloud[:local_ipv4] += private_ips + cloud[:local_hostname] = gce['instance']['hostname'] + cloud[:provider] = 'gce' + end + + ... + + # with following similar code blocks for each cloud provider +``` + +where + +- `provides` defines the `cloud` attribute, which is then turned into an object using the `create_objects` shared method, which then generates a hash based on public or private IP addresses +- For Google Compute Engine the `cloud` attribute data is populated into a hash based on the IP address for the node + +To see the rest of the code in this plugin, go to: . + +## Ohai Methods + +The Ohai DSL is a Ruby DSL that's used to define an Ohai plugin and to ensure that Ohai collects the right data at the start of every Chef Infra Client run. The Ohai DSL is a small DSL with a single method that's specific to Ohai plugins. Because the Ohai DSL is a Ruby DSL, anything that can be done using Ruby can also be done when defining an Ohai plugin. + +### collect_data + +The `collect_data` method is a block of Ruby code that's called by Ohai when it runs. One (or more) `collect_data` blocks can be defined in a plugin, but only a single `collect_data` block is ever run. The `collect_data` block that's run is determined by the platform on which the node is running, which is then matched up against the available `collect_data` blocks in the plugin. + +- A `collect_data(:default)` block is used when Ohai isn't able to match the platform of the node with a `collect_data(:platform)` block in the plugin +- A `collect_data(:platform)` block is required for each platform that requires non-default behavior + +When Ohai runs, if there isn't a matching `collect_data` block for a platform, the `collect_data(:default)` block is used. The syntax for the `collect_data` method is: + +```ruby +collect_data(:default) do + # some Ruby code +end +``` + +or: + +```ruby +collect_data(:platform) do + # some Ruby code +end +``` + +where: + +- `:default` is the name of the default `collect_data` block +- `:platform` is the name of a platform, such as `:aix` for AIX or `:windows` for Windows + +#### Use a Mash + +Use a mash to store data. This is done by creating a new mash, and then setting an attribute to it. For example: + +```ruby +provides 'name_of_mash' +name_of_mash Mash.new +name_of_mash[:attribute] = 'value' +``` + +#### Examples + +The following examples show how to use the `collect_data` block: + +```ruby +Ohai.plugin(:Azure) do + provides 'azure' + + collect_data do + azure_metadata_from_hints = hint?('azure') + if azure_metadata_from_hints + Ohai::Log.debug('azure_metadata_from_hints is present.') + azure Mash.new + azure_metadata_from_hints.each {|k, v| azure[k] = v } + else + Ohai::Log.debug('No hints present for azure.') + false + end + end +end +``` + +or: + +```ruby +require 'ohai/mixin/ec2_metadata' +extend Ohai::Mixin::Ec2Metadata + +Ohai.plugin do + provides 'openstack' + + collect_data do + if hint?('openstack') || hint?('hp') + Ohai::Log.debug('ohai openstack') + openstack Mash.new + if can_metadata_connect?(EC2_METADATA_ADDR,80) + Ohai::Log.debug('connecting to the OpenStack metadata service') + self.fetch_metadata.each {|k, v| openstack[k] = v } + case + when hint?('hp') + openstack['provider'] = 'hp' + else + openstack['provider'] = 'openstack' + end + else + Ohai::Log.debug('unable to connect to the OpenStack metadata service') + end + else + Ohai::Log.debug('NOT ohai openstack') + end + end +end +``` + +### require + +The `require` method is a standard Ruby method that can be used to list files that may be required by a platform, such as an external class library. As a best practice, even though the `require` method is often used at the top of a Ruby file, it's recommended that the use of the `require` method be used as part of the platform-specific `collect_data` block. For example, the Ruby WMI is required with Windows: + +```ruby +collect_data(:windows) do + require 'ruby-wmi' + WIN32OLE.codepage = WIN32OLE::CP_UTF8 + + kernel Mash.new + + host = WMI::Win32_OperatingSystem.find(:first) + kernel[:os_info] = Mash.new + host.properties_.each do |p| + kernel[:os_info][p.name.wmi_underscore.to_sym] = host.send(p.name) + end + + ... + +end +``` + +Ohai will attempt to fully qualify the name of any class by prepending `Ohai::` to the loaded class. For example both: + +```ruby +require Ohai::Mixin::ShellOut +``` + +and: + +```ruby +require Mixin::ShellOut +``` + +are both understood by the Ohai in the same way: `Ohai::Mixin::ShellOut`. + +When a class is an external class (and therefore shouldn't have `Ohai::` prepended), use `::` to let the Ohai know. For example: + +```ruby +::External::Class::Library +``` + +#### /common Directory + +The `/common` directory stores code that's used across all Ohai plugins. For example, a file in the `/common` directory named `virtualization.rb` that includes code like the following: + +```ruby +module Ohai + module Common + module Virtualization + + def host?(virtualization) + !virtualization.nil? && virtualization[:role].eql?('host') + end + + def open_virtconn(system) + begin + require 'libvirt' + require 'hpricot' + rescue LoadError => e + Ohai::Log.debug('Cannot load gem: #{e}.') + end + + emu = (system.eql?('kvm') ? 'qemu' : system) + virtconn = Libvirt::open_read_only('#{emu}:///system') + end + + ... + + def networks(virtconn) + networks = Mash.new + virtconn.list_networks.each do |n| + nv = virtconn.lookup_network_by_name n + networks[n] = Mash.new + networks[n][:xml_desc] = (nv.xml_desc.split('\n').collect {|line| line.strip}).join + ['bridge_name','uuid'].each {|a| networks[n][a] = nv.send(a)} + #xdoc = Hpricot networks[n][:xml_desc] + end + networks + end + + ... + + end + end +end +``` + +can then be leveraged in a plugin by using the `require` method to require the `virtualization.rb` file and then later calling each of the methods in the required module: + +```ruby +require 'ohai/common/virtualization' + +Ohai.plugin(:Virtualization) do + include Ohai::Common::Virtualization + + provides 'virtualization' + %w{ capabilities domains networks storage }.each do |subattr| + provides 'virtualization/#{subattr}' + end + + collect_data(:linux) do + virtualization Mash.new + + ... + + if host?(virtualization) + v = open_virtconn(virtualization[:system]) + + virtualization[:libvirt_version] = libvirt_version(v) + virtualization[:nodeinfo] = nodeinfo(v) + virtualization[:uri] = uri(v) + virtualization[:capabilities] = capabilities(v) + virtualization[:domains] = domains(v) + virtualization[:networks] = networks(v) + virtualization[:storage] = storage(v) + + close_virtconn(v) + end +``` + +### Shared Methods + +Use shared methods to define objects for use in `collect_data` blocks, such as a data structure, a hash, or a mash. The syntax for a shared method is: + +```ruby +def a_shared_method + # some Ruby code that defines the shared method +end +``` + +The following example declares a shared `cloud` method to collect data about cloud providers based on the type of IP address and then uses the `cloud` object to collect data from different cloud providers. + +Create `cloud` objects based on the type of IP address: + +```ruby +def create_objects + cloud Mash.new + cloud[:public_ips] = Array.new + cloud[:private_ips] = Array.new +end +``` + +Use `cloud` object to collect Linode data: + +```ruby +def get_linode_values + cloud[:public_ips] << linode['public_ip'] + cloud[:private_ips] << linode['private_ip'] + cloud[:public_ipv4] = linode['public_ipv4'] + cloud[:public_hostname] = linode['public_hostname'] + cloud[:local_ipv4] = linode['local_ipv4'] + cloud[:local_hostname] = linode['local_hostname'] + cloud[:provider] = 'linode' +end +``` + +Use the `cloud` object to collect Azure data: + +```ruby +def get_azure_values + cloud[:vm_name] = azure['vm_name'] + cloud[:public_ips] << azure['public_ip'] + cloud[:public_fqdn] = azure['public_fqdn'] + cloud[:public_ssh_port] = azure['public_ssh_port'] if azure['public_ssh_port'] + cloud[:public_winrm_port] = azure['public_winrm_port'] if azure['public_winrm_port'] + cloud[:provider] = 'azure' +end +``` + +## Logging + +Use the `Ohai::Log` class in an Ohai plugin to define log entries that are created by Ohai. The syntax for a log message is as follows: + +```ruby +Ohai::Log.log_type('message') +``` + +where + +- `log_type` can be `.debug`, `.info`, `.warn`, `.error`, or `.fatal` +- `'message'` is the message that's logged. + +For example: + +```ruby +Ohai.plugin do + provides 'openstack' + + collect_data do + if hint?('openstack') || hint?('hp') + Ohai::Log.debug('ohai openstack') + openstack Mash.new + if can_metadata_connect?(EC2_METADATA_ADDR,80) + Ohai::Log.debug('connecting to the OpenStack metadata service') + self.fetch_metadata.each {|k, v| openstack[k] = v } + case + when hint?('hp') + openstack['provider'] = 'hp' + else + openstack['provider'] = 'openstack' + end + else + Ohai::Log.debug('unable to connect to the OpenStack metadata service') + end + else + Ohai::Log.debug('NOT ohai openstack') + end + end +end +``` + +### rescue + +Use the `rescue` clause to make sure that a log message is always provided. For example: + +```ruby +rescue LoadError => e + Ohai::Log.debug('ip_scopes: can't load gem, plugin disabled: #{e}') +end +``` + +## Examples + +The following examples show different ways of building Ohai plugins. + +### collect_data Blocks + +The following Ohai plugin uses multiple `collect_data` blocks and shared methods to define platforms: + +```ruby +Ohai.plugin(:Hostname) do + provides 'domain', 'fqdn', 'hostname' + + def from_cmd(cmd) + so = shell_out(cmd) + so.stdout.split($/)[0] + end + + def collect_domain + if fqdn + fqdn =~ /.+?\.(.*)/ + domain $1 + end + end + + collect_data(:aix, :hpux) do + hostname from_cmd('hostname -s') + fqdn from_cmd('hostname') + domain collect_domain + end + + collect_data(:darwin, :netbsd, :openbsd) do + hostname from_cmd('hostname -s') + fqdn from_cmd('hostname') + domain collect_domain + end + + collect_data(:freebsd) do + hostname from_cmd('hostname -s') + fqdn from_cmd('hostname -f') + domain collect_domain + end + + collect_data(:linux) do + hostname from_cmd('hostname -s') + begin + fqdn from_cmd('hostname --fqdn') + rescue + Ohai::Log.debug('hostname -f returned an error, probably no domain is set') + end + domain collect_domain + end + + collect_data(:solaris2) do + require 'socket' + + hostname from_cmd('hostname') + + fqdn_lookup = Socket.getaddrinfo(hostname, nil, nil, nil, nil, Socket::AI_CANONNAME).first[2] + if fqdn_lookup.split('.').length > 1 + # we received an fqdn + fqdn fqdn_lookup + else + # default to assembling one + h = from_cmd('hostname') + d = from_cmd('domainname') + fqdn '#{h}.#{d}' + end + + domain collect_domain + end + + collect_data(:windows) do + require 'ruby-wmi' + require 'socket' + + host = WMI::Win32_ComputerSystem.find(:first) + hostname '#{host.Name}' + + info = Socket.gethostbyname(Socket.gethostname) + if info.first =~ /.+?\.(.*)/ + fqdn info.first + else + # host isn't in dns. optionally use: + # C:\WINDOWS\system32\drivers\etc\hosts + fqdn Socket.gethostbyaddr(info.last).first + end + + domain collect_domain + end +end +``` + +### Use a mixin Library + +The following Ohai example shows a plugin can use a `mixin` library and also depend on another plugin: + +```ruby +require 'ohai/mixin/os' + +Ohai.plugin(:Os) do + provides 'os', 'os_version' + depends 'kernel' + + collect_data do + os collect_os + os_version kernel[:release] + end +end +``` + +### Get Kernel Values + +The following Ohai example shows part of a file that gets initial kernel attribute values: + +```ruby +Ohai.plugin(:Kernel) do + provides 'kernel', 'kernel/modules' + + def init_kernel + kernel Mash.new + [['uname -s', :name], ['uname -r', :release], + ['uname -v', :version], ['uname -m', :machine]].each do |cmd, property| + so = shell_out(cmd) + kernel[property] = so.stdout.split($/)[0] + end + kernel + end + + ... + + collect_data(:darwin) do + kernel init_kernel + kernel[:os] = kernel[:name] + + so = shell_out('sysctl -n hw.optional.x86_64') + if so.stdout.split($/)[0].to_i == 1 + kernel[:machine] = 'x86_64' + end + + modules = Mash.new + so = shell_out('kextstat -k -l') + so.stdout.lines do |line| + if line =~ /(\d+)\s+(\d+)\s+0x[0-9a-f]+\s+0x([0-9a-f]+)\s+0x[0-9a-f]+\s+([a-zA-Z0-9\.]+) \(([0-9\.]+)\)/ + kext[$4] = { :version => $5, :size => $3.hex, :index => $1, :refcount => $2 } + end + end + + kernel[:modules] = modules + end + + ... +``` diff --git a/content/extension_apis/dsl_handler.md b/content/extension_apis/dsl_handler.md new file mode 100644 index 0000000..00738f6 --- /dev/null +++ b/content/extension_apis/dsl_handler.md @@ -0,0 +1,73 @@ ++++ +title = "About the Handler DSL" +draft = false + +[menu] + [menu.extension_apis] + title = "Handler DSL" + identifier = "extension_apis/handlers/dsl_handler.md Handler DSL" + parent = "extension_apis/handlers" + weight = 20 ++++ + +{{< readfile file="content/reusable/md/dsl_handler_summary.md" >}} + +## on Method + +{{< readfile file="content/reusable/md/dsl_handler_method_on.md" >}} + +## Event Types + +{{< readfile file="content/reusable/md/dsl_handler_event_types.md" >}} + +## Examples + +The following examples show ways to use the Handler DSL. + +### Send Email + +{{< readfile file="content/reusable/md/dsl_handler_slide_send_email.md" >}} + +#### Define How Email is Sent + +{{< readfile file="content/reusable/md/dsl_handler_slide_send_email_library.md" >}} + +#### Add the Handler + +{{< readfile file="content/reusable/md/dsl_handler_slide_send_email_handler.md" >}} + +#### Test the Handler + +{{< readfile file="content/reusable/md/dsl_handler_slide_send_email_test.md" >}} + +### etcd Locks + +{{< readfile file="content/reusable/md/dsl_handler_example_etcd_lock.md" >}} + +### HipChat Notifications + +{{< readfile file="content/reusable/md/dsl_handler_example_hipchat.md" >}} + +### `attribute_changed` event hook + +In a cookbook library file, you can add this to print out all +attribute changes in cookbooks: + +```ruby +Chef.event_handler do + on :attribute_changed do |precedence, key, value| + puts "setting attribute #{precedence}#{key.map { |n| "[\"#{n}\"]" }.join} = #{value}" + end +end +``` + +If you want to setup a policy that override attributes should never be +used: + +```ruby +Chef.event_handler do + on :attribute_changed do |precedence, key, value| + raise 'override policy violation' if precedence == :override + end +end +``` diff --git a/content/features/_index.md b/content/features/_index.md new file mode 100644 index 0000000..8fd114d --- /dev/null +++ b/content/features/_index.md @@ -0,0 +1,5 @@ ++++ +title = "Features" + +list_pages = true ++++ \ No newline at end of file diff --git a/content/agentless/_index.md b/content/features/agentless/_index.md similarity index 89% rename from content/agentless/_index.md rename to content/features/agentless/_index.md index a711f82..70682ec 100644 --- a/content/agentless/_index.md +++ b/content/features/agentless/_index.md @@ -1,12 +1,14 @@ +++ -title = "Chef Infra Agentless Mode" +title = "About Agentless Mode" +draft = false linkTitle = "Agentless" -[menu.agentless] -title = "Agentless overview" -identifier = "agentless/overview" -parent = "agentless" -weight = 10 +[menu] + [menu.features] + title = "About Agentless Mode" + identifier = "features/agentless/About" + parent = "features/agentless" + weight = 10 +++ {{< readfile file="content/reusable/md/agentless_summary.md" >}} @@ -29,7 +31,7 @@ Agentless Mode has the following requirements: - A network-enabled system to execute Agentless Mode. - The `chef-client` CLI. This is included with Chef Workstation. -- A [credentials file](#target-credentials-file) that provides the system with information to connect to a target node. +- A [target credentials file](#target-credentials-file) that provides the system with information to connect to a target node. - A recipe that only includes [Agentless Mode-enabled resources](#resources). ## Target credentials file @@ -171,37 +173,6 @@ Additional parameters: -### Retrieve secrets from HashiCorp Vault - -You can configure Agentless Mode to fetch secrets from HashiCorp Vault. - -In the `~/.chef/target_credentials` file, define the following: - -- your Vault authentication settings with the `default_secrets_provider` hash -- your secret name saved in Vault - -For example: - -```toml -default_secrets_provider = { - name = 'hashicorp-vault', - endpoint = '', - token = '' -} - -[''] -host = '' -user = '' -sudo = true -password = { secret = '', field = 'password' } -``` - -Replace: - -- `` with your Vault endpoint, for example: `http://127.0.0.1:8200`. -- `` with your Vault token, for example: `hvs.ewUEnIRVaKoBzs2...example...ewUEnIRVaKoBzs2`. -- `` with the name of the secret stored in Vault. - ## Resources All resources included in a Cookbook must be enabled in Agentless Mode to run in Agentless Mode. @@ -230,7 +201,7 @@ chef-client -t Replace `` with the name of the host as defined in the credentials file. For example, `HOST-1` in the [credential file example](#define-node-connections). -To execute a specific cookbook in Agentless Mode, run: +To execute a specific Cookbook in Agentless Mode, run: ```sh chef-client -t @@ -239,9 +210,9 @@ chef-client -t Replace the following: - `` with the name of the host as defined in the credentials file. -- `` with the path to the Cookbook on your system. For example, `/chef-repo/cookbooks/example_cookbook.rb` +- `` with the path to the Cookbook on your system. For example, `/chef-repo/cookbooks/example_cookbook`. This runs the default recipe in the cookbook. -### Run Agentless Mode in Local Mode +### Agentless Mode in Local Mode You can run Agentless Mode in Local Mode. Local Mode runs chef-zero locally as a lightweight instance of Chef Infra Server to execute a Client run on target nodes. @@ -252,10 +223,11 @@ Use `-z` and `-t` to run Agentless Mode in Local Mode: chef-client -z -t ``` -You can also run a specific cookbook in Local Mode: +Replace `` with the name of the host as defined in the credentials file. +For example, `HOST-1` in the [credential file example](#define-node-connections). ```sh -chef-client -z -t +chef-client -z -t ``` Replace: @@ -263,7 +235,7 @@ Replace: - `` with the name of the host as defined in the credentials file. For example, `HOST-1` in the [credential file example](#define-node-connections). -- `` with the cookbook file path. For example, `/chef-repo/cookbooks-dir/cookbook1.rb`. +- `` with the recipe file path inside a cookbook. For example, `/chef-repo/cookbooks/cookbook1/recipe1.rb`. You should see output similar to this: diff --git a/content/agentless/example.md b/content/features/agentless/example.md similarity index 79% rename from content/agentless/example.md rename to content/features/agentless/example.md index 0c90d62..9ff3bbd 100644 --- a/content/agentless/example.md +++ b/content/features/agentless/example.md @@ -1,22 +1,22 @@ +++ title = "Chef Infra Agentless Mode example" -[menu.agentless] +[menu.features] title = "Agentless Mode example" -identifier = "agentless/example" -parent = "agentless" +identifier = "features/agentless/example" +parent = "features/agentless" weight = 20 +++ This document provides a simplified, end-to-end guide to configure and run -Chef Infra Client 19 RC3 in Agentless (Target Mode) using Habitat (`hab`) +Chef Infra Client in Agentless (Target Mode) using Habitat (`hab`) for managing remote systems. ## Prerequisites - [Chef Infra Client is installed](/install/) - Your `HAB_AUTH_TOKEN` is exported -- a valid Progress Chef license key +- You have a valid Progress Chef license key ## Create a target credentials file @@ -37,10 +37,12 @@ user = 'root' password = '' ``` -For more information, see the [target credentials file documentation](/agentless/). +For more information, see the [target credentials file documentation](/features/agentless/). ## Create the test recipe + + On the host, create a test recipe file (`~/.chef/apply.rb`) with the test resources below. {{< foundation_tabs tabs-id="test-agentless-mode-recipe" >}} @@ -116,9 +118,11 @@ end {{< /foundation_tabs_panel >}} {{< /foundation_tabs_panels >}} -## Run the recipe in Agentless Mode + + +## Run Agentless Mode using Habitat -From your `.chef` directory, execute the recipe withe Chef Infra Client: +From your `.chef` directory, with `HAB_AUTH_TOKEN` exported and the license key available: ```sh cd ~/.chef @@ -129,6 +133,27 @@ Replace `` with the target name defined in the `target_credentials` Chef Infra Client executes the `apply.rb` recipe in local mode (`chef-client -z`) against the remote target (`-t `) over SSH using the credentials defined in `~/.chef/target_credentials`. +## Run a recipe using a run list in Agentless Mode + +Instead of specifying a recipe, you can run a recipe by specifying it in a run list using the `-r` option. +This requires the cookbook to be available locally in your cookbook path. + +For example, to run the `example_cookbook::default` recipe: + +```sh +chef-client -z -t -r 'recipe[example_cookbook::default]' +``` + +Replace `` with the target name defined in the `target_credentials` file. + +If the cookbook is uploaded to Chef Infra Server, you can upload the cookbook, add it to the node's run list, and then run Chef Infra Client in target mode: + +```sh +knife cookbook upload example_cookbook +knife node run_list add 'recipe[example_cookbook::default]' +chef-client -t +``` + ## Verify the output A successful Infra Client run returns something like this: diff --git a/content/features/agentless/resources/_index.md b/content/features/agentless/resources/_index.md new file mode 100644 index 0000000..de7ca42 --- /dev/null +++ b/content/features/agentless/resources/_index.md @@ -0,0 +1,107 @@ ++++ +title = "Supported Chef Infra resources in Agentless Mode" +linkTitle = "Supported resources" + +[menu.features] +title = "Supported resources" +identifier = "features/agentless/resources/overview" +parent = "features/agentless/resources" +weight = 10 ++++ + + + +The following Chef Infra resources are supported in Agentless Mode. + +| **Resources Name** | **Verified Platforms** | **Remarks** | +|---|---|---| +| [alternatives](/resources/bundled/alternatives/) | Ubuntu, Linux | | +| [apt_package](/resources/bundled/apt_package/) | Ubuntu | | +| [apt_preference](/resources/bundled/apt_preference/) | Ubuntu, Linux | | +| [apt_repository](/resources/bundled/apt_repository/) | Ubuntu, Linux | | +| [apt_update](/resources/bundled/apt_update/) | Ubuntu, Linux | | +| [bash](/resources/bundled/bash/) | Ubuntu, Linux, Solaris, Alpine, SUSE | | +| [breakpoint](/resources/bundled/breakpoint/) | Ubuntu, Linux | | +| [chef_acl](/resources/bundled/chef_acl/) | Ubuntu, Linux, CentOS 9 | | +| [chef_client](/resources/bundled/chef_client/) | Ubuntu 24.04, Linux Red Hat 9, Solaris, Alpine, SUSE | | +| [chef_client_config](/resources/bundled/chef_client_config/) | Ubuntu, Linux, Solaris, Alpine, SUSE | | +| [chef_container](/resources/bundled/chef_container/) | Ubuntu, Linux | | +| [chef_data_bag](/resources/bundled/chef_data_bag/) | Ubuntu, Linux | | +| [chef_environment](/resources/bundled/chef_environment/) | Ubuntu, Linux | | +| [chef_group](/resources/bundled/chef_group/) | Ubuntu 24.04 and 18.04, RHEL | | +| [chef_node](/resources/bundled/chef_node/) | Ubuntu 24.04, Linux Red Hat 9 | | +| [chef_organization](/resources/bundled/chef_organization/) | Ubuntu 24.04 and 18.04, RHEL | | +| [chef_role](/resources/bundled/chef_role/) | Ubuntu 24.04, Linux Red Hat 9, Solaris, Alpine, SUSE | | +| [chef_sleep](/resources/bundled/chef_sleep/) | Ubuntu, Linux | | +| [chef_user](/resources/bundled/chef_user/) | Ubuntu 24.04 and 18.04, RHEL, Solaris, Alpine, SUSE | | +| [cookbook_file](/resources/bundled/cookbook_file/) | Ubuntu, Linux, Solaris, Alpine, SUSE | | +| [cron](/resources/bundled/cron/) | Ubuntu, Linux, Solaris SunOS, Alpine | | +| [cron_access](/resources/bundled/cron_access/) | Ubuntu, Linux, Solaris SunOS, Alpine | | +| [cron_d](/resources/bundled/cron_d/) | Ubuntu, Linux | | +| [csh](/resources/bundled/csh/) | Ubuntu 24.04, Linux Red Hat 9, Alpine | | +| [directory](/resources/bundled/directory/) | Ubuntu, Linux, Solaris, Alpine, SUSE | | +| [execute](/resources/bundled/execute/) | Ubuntu, Linux, Solaris, Alpine, SUSE | | +| [file](/resources/bundled/file/) | Ubuntu, Linux, Solaris, Alpine, SUSE | | +| [freebsd_package](/resources/bundled/freebsd_package/) | FreeBSD 14 | Supported on FreeBSD. | +| [git](/resources/bundled/git/) | Ubuntu, Linux, Solaris, Alpine, SUSE | | +| [group](/resources/bundled/group/) | Ubuntu, Linux, Solaris, Alpine, SUSE | | +| [habitat_config](/resources/bundled/habitat_config/) | Ubuntu 24.04, Linux Red Hat 9, Solaris, Alpine, SUSE | | +| [habitat_install](/resources/bundled/habitat_install/) | Ubuntu, Linux, Solaris, Alpine, SUSE | | +| [habitat_package](/resources/bundled/habitat_package/) | Ubuntu, Linux, Solaris, Alpine, SUSE | | +| [habitat_service](/resources/bundled/habitat_service/) | Ubuntu, Linux | | +| [habitat_sup](/resources/bundled/habitat_sup/) | Ubuntu, Linux | | +| [hostname](/resources/bundled/hostname/) | Ubuntu, Linux | | +| [http_request](/resources/bundled/http_request/) | Ubuntu, Linux, , Solaris, Alpine, SUSE | | +| [ifconfig](/resources/bundled/ifconfig/) | Ubuntu, Linux | | +| [inspec_input](/resources/bundled/inspec_input/) | Ubuntu 24.04, Linux Red Hat 9 | | +| [inspec_waiver](/resources/bundled/inspec_waiver/) | Ubuntu, Linux | | +| [inspec_waiver_file_entry](/resources/bundled/inspec_waiver_file_entry/) | Ubuntu, Linux | | +| [kernel_module](/resources/bundled/kernel_module/) | Ubuntu, Linux | | +| [ksh](/resources/bundled/ksh/) | Ubuntu 24.04, Linux Red Hat 9, Solaris, Alpine, SUSE | | +| [link](/resources/bundled/link/) | Ubuntu, Linux, Solaris, Alpine, SUSE | | +| [locale](/resources/bundled/locale/) | Ubuntu | | +| [log](/resources/bundled/log/) | Ubuntu, Linux, Solaris, Alpine, SUSE | | +| [mount](/resources/bundled/mount/) | Ubuntu 24.04, CentOS 9 | | +| [notify_group](/resources/bundled/notify_group/) | Ubuntu, Linux | | +| [ohai](/resources/bundled/ohai/) | Ubuntu, Linux | | +| [ohai_hint](/resources/bundled/ohai_hint/) | Ubuntu, Linux | | +| [package](/resources/bundled/package/) | Ubuntu, Linux, CentOS 9, Solaris, Alpine, SUSE | | +| [perl](/resources/bundled/perl/) | Ubuntu | | +| [python](/resources/bundled/python/) | Ubuntu 24.04, Linux Red Hat 9, Solaris, Alpine, SUSE | | +| [reboot](/resources/bundled/reboot/) | Ubuntu, Linux | | +| [remote_file](/resources/bundled/remote_file/) | Ubuntu, Linux, CentOS 9, Solaris, Alpine, SUSE | | +| [rhsm_errata](/resources/bundled/rhsm_errata/) | Linux (redhat) | | +| [rhsm_errata_level](/resources/bundled/rhsm_errata_level/) | Linux (redhat) | | +| [rhsm_register](/resources/bundled/rhsm_register/) | Linux (redhat) | | +| [rhsm_repo](/resources/bundled/rhsm_repo/) | Linux (redhat) | | +| [rhsm_subscription](/resources/bundled/rhsm_subscription/) | Linux (redhat) | | +| [route](/resources/bundled/route/) | Ubuntu 24.04 / CentOS 9 | | +| [rpm_package](/resources/bundled/rpm_package/) | CentOS 9 | The RPM package must be locally available on the remote system. | +| [ruby_block](/resources/bundled/ruby_block/) | Ubuntu, Linux, CentOS 9 | | +| [script](/resources/bundled/script/) | Ubuntu 24.04, Linux Red Hat 9, , Solaris, Alpine | | +| [selinux_boolean](/resources/bundled/selinux_boolean/) | Ubuntu, Linux | | +| [selinux_fcontext](/resources/bundled/selinux_fcontext/) | Ubuntu, Linux | | +| [selinux_install](/resources/bundled/selinux_install/) | Ubuntu, Linux | | +| [selinux_login](/resources/bundled/selinux_login/) | Ubuntu, Linux | | +| [selinux_module](/resources/bundled/selinux_module/) | Ubuntu, Linux | | +| [selinux_permissive](/resources/bundled/selinux_permissive/) | Ubuntu, Linux | | +| [selinux_port](/resources/bundled/selinux_port/) | Ubuntu, Linux | | +| [selinux_state](/resources/bundled/selinux_state/) | Ubuntu, Linux | | +| [selinux_user](/resources/bundled/selinux_user/) | Ubuntu, Linux | | +| [service](/resources/bundled/service/) | Ubuntu, Linux, CentOS 9, Solaris, Alpine, SUSE | `crond` for Linux | +| [snap_package](/resources/bundled/snap_package/) | Ubuntu 24.04 | Supported on Linux. | +| [ssh_known_hosts_entry](/resources/bundled/ssh_known_hosts_entry/) | Ubuntu, Linux | | +| [subversion](/resources/bundled/subversion/) | Ubuntu 24.04, Linux Red Hat 9, CentOS 9 | The subversion resource has known bugs and may not work as expected. For more information, see the Chef GitHub issues [#4050](https://github.com/chef/chef/issues/4050) and [#4257](https://github.com/chef/chef/issues/4257). | +| [sudo](/resources/bundled/sudo/) | Ubuntu, Linux, CentOS 9, Solaris, Alpine, SUSE | | +| [swap_file](/resources/bundled/swap_file/) | Ubuntu, Linux | | +| [sysctl](/resources/bundled/sysctl/) | Ubuntu, Linux | | +| [systemd_unit](/resources/bundled/systemd_unit/) | Ubuntu, Linux | | +| [template](/resources/bundled/template/) | Ubuntu, Linux, CentOS 9, Solaris, Alpine, SUSE | Require absolute path for source attribute. | +| [timezone](/resources/bundled/timezone/) | Linux, Solaris, Alpine, SUSE | | +| [user](/resources/bundled/user/) | Ubuntu, Linux | | +| [user_ulimit](/resources/bundled/user_ulimit/) | Ubuntu, Linux | | +| [yum_package](/resources/bundled/yum_package/) | CentOS 9 | Supported on Linux. | +| [yum_repository](/resources/bundled/yum_repository/) | Linux | | +| [yum_repository](/resources/bundled/yum_repository/) | CentOS 9, RHEL 8 | Supported on Linux. | +| [zypper_package](/resources/bundled/zypper_package/) | SUSE Linux 15 | | +| [solaris_package](/resources/bundled/solaris_package/) | Solaris | | diff --git a/content/agentless/resources/custom.md b/content/features/agentless/resources/custom.md similarity index 96% rename from content/agentless/resources/custom.md rename to content/features/agentless/resources/custom.md index c23071f..3eedfc9 100644 --- a/content/agentless/resources/custom.md +++ b/content/features/agentless/resources/custom.md @@ -2,10 +2,10 @@ title = "Custom resource guide" [menu] - [menu.agentless] + [menu.features] title = "Custom resource guide" - identifier = "agentless/resources/custom" - parent = "agentless" + identifier = "features/agentless/resources/custom" + parent = "features/agentless/resources" weight = 10 +++ diff --git a/content/features/chef_compliance_phase.md b/content/features/chef_compliance_phase.md new file mode 100644 index 0000000..0f227c2 --- /dev/null +++ b/content/features/chef_compliance_phase.md @@ -0,0 +1,663 @@ ++++ +title = "About the Compliance Phase" +draft = false + +[menu] + [menu.features] + title = "Compliance Phase" + identifier = "features/chef_compliance_phase.md Compliance Phase" + parent = "features" + weight = 15 + ++++ + + +Chef Infra Client's Compliance Phase lets you automatically execute compliance audits and view the results as part of any Chef Infra Client run. The Compliance Phase of the Chef Infra Client run replaces the legacy [audit cookbook](https://supermarket.chef.io/cookbooks/audit) and works with your existing audit cookbook attributes, and you can also set it up for new cookbooks. This additional phase gives you the latest compliance capabilities without having to manage cookbook dependencies or juggle versions during Chef Infra Client updates. + +Existing audit cookbook users can migrate to the new Compliance Phase by removing the audit cookbook from their run_list and setting the `node['audit']['compliance_phase']` attribute to `true`. + +The Compliance Phase replaces the `audit cookbook` by integrating Chef InSpec compliance checks into the [Chef Infra Client run]({{< relref "/" >}}) +The Compliance Phase is designed to run on any node in your system that's set up--or [bootstrapped]({{< relref "install_bootstrap" >}})--for a `chef-client` run. + +Once turned on, the Compliance Phase always outputs its results in the CLI on manual runs. The output for automated runs is handled by [reporters]({{< relref "#reporters" >}}). + +## Upgrade to Compliance Phase from Audit Cookbook + +The Compliance Phase requires Chef Infra Client 17 or higher. + +If your system is configured to use the `audit cookbook`, make these changes to switch to the Compliance Phase: + +1. Set the `node['audit']['compliance_phase']` attribute to `true` through a Policyfile or cookbook attributes file. +1. Remove the `audit cookbook` from your [run-list]({{< relref "run_lists.md" >}}). + +1. On your next Chef Infra Client run, you should see the Compliance Phase results. + +## Set up the Compliance Phase in new Cookbooks + +### Turn on the Compliance Phase + +Turn on the Compliance Phase by setting the `node['audit']['compliance_phase']` attribute to `true` through cookbook attributes or Policyfiles. To turn on Compliance Phase using cookbook attributes add the following line to the `attributes/default.rb` file in your cookbook. + +```ruby +default['audit']['compliance_phase'] = true +``` + +### Set Chef InSpec Profiles + +Setting one or more Chef InSpec profiles turns on the Compliance Phase in a Chef Infra Client run. The presence of this configuration in your attributes file instructs Chef Infra Client to fetch and execute the specific Chef InSpec profiles and write the results to disk using the default `cli` and `json-file` reporters. + +Retrieve [Chef InSpec profiles](https://docs.chef.io/inspec/profiles/) from Chef Automate, Supermarket, a local file, GitHub, or over HTTP with the `node['audit']['profiles']` attribute. + +The following examples: + +- Retrieve profiles from Chef Automate, Supermarket, a local file, GitHub, or over HTTP. +- Display the results on the command line using the default `cli` reporter. +- Write the results to disk using the default `json-file` reporter to `/compliance_reports/compliance-.json`. + + + +{{< foundation_tabs tabs-id="compliance-phase-profile-panel" >}} + {{< foundation_tab active="true" panel-link="automate-panel" tab-text="Automate">}} + {{< foundation_tab panel-link="supermarket-panel" tab-text="Supermarket" >}} + {{< foundation_tab panel-link="local-path-panel" tab-text="File" >}} + {{< foundation_tab panel-link="git-panel" tab-text="GitHub" >}} + {{< foundation_tab panel-link="http-panel" tab-text="HTTP" >}} +{{< /foundation_tabs >}} +{{< foundation_tabs_panels tabs-id="compliance-phase-profile-panel" >}} + {{< foundation_tabs_panel active="true" panel-id="automate-panel" >}} + ```ruby + # Invoke the Compliance Phase + default['audit']['compliance_phase'] = true + # Set profile locations + default['audit']['profiles']['linux-baseline'] = { + 'compliance': 'user/linux-baseline', + 'version': '2.1.0' + } + ``` + {{< warning >}} + Fetching profiles from Chef Automate requires setting `data_collector.server_url` and `data_collector.token` in your `client.rb` to fetch profiles from Chef Automate. This configuration is described in more detail in the Chef Automate [data collector documentation](https://docs.chef.io/automate/data_collection/). + {{< /warning >}} + {{< /foundation_tabs_panel >}} + {{< foundation_tabs_panel panel-id="supermarket-panel" >}} + ```ruby + # Invoke the Compliance Phase + default['audit']['compliance_phase'] = true + # Set profile locations + default['audit']['profiles']['ssh'] = { + 'supermarket': 'hardening/ssh-hardening' + } + ``` + {{< /foundation_tabs_panel >}} + {{< foundation_tabs_panel panel-id="local-path-panel" >}} + ```ruby + # Invoke the Compliance Phase + default['audit']['compliance_phase'] = true + # Set profile locations + default['audit']['profiles']['4thcafe/win2012_audit'] = { + 'path': 'E:/profiles/win2012_audit' + } + ``` + {{< /foundation_tabs_panel >}} + {{< foundation_tabs_panel panel-id="git-panel" >}} + ```ruby + # Invoke the Compliance Phase + default['audit']['compliance_phase'] = true + # Set profile locations + default['audit']['profiles']['ssl'] = { + 'git': 'https://github.com/dev-sec/ssl-benchmark.git' + } + ``` + {{< /foundation_tabs_panel >}} + {{< foundation_tabs_panel panel-id="http-panel" >}} + ```ruby + # Invoke the Compliance Phase + default['audit']['compliance_phase'] = true + # Set profile locations + default['audit']['profiles']['ssh2'] = { + 'url': 'https://github.com/dev-sec/tests-ssh-hardening/archive/master.zip' + } + ``` + {{< /foundation_tabs_panel >}} +{{< /foundation_tabs_panels >}} + + + +### Fetch Profiles + +Set the fetcher attribute with `default['audit']['fetcher']` to retrieve Chef InSpec compliance profiles from either Chef Automate or Chef Infra Server in addition to the location defined by `default ['audit']['profile']`. Left unset, the Compliance Phase defaults to the [fetchers included in Chef InSpec](https://docs.chef.io/inspec/profiles#profile-dependencies). Chef Infra and Chef InSpec fetchers are mutually exclusive so, you can only use one of these configurations. + +The following examples: + +- Retrieve the 'ssh' profile from Chef Supermarket. +- Fetch additional profiles from Chef Automate or Chef Infra Server. +- Display the results on the command line using the default `cli` reporter. +- Write the results to disk using the default `json-file` reporter to `/compliance_reports/compliance-.json`. + + + +{{< foundation_tabs tabs-id="compliance-phase-fetcher-panel" >}} + {{< foundation_tab active="true" panel-link="automate-fetcher" tab-text="Automate">}} + {{< foundation_tab panel-link="server-fetcher" tab-text="Infra Server" >}} +{{< /foundation_tabs >}} +{{< foundation_tabs_panels tabs-id="compliance-phase-fetcher-panel" >}} + {{< foundation_tabs_panel active="true" panel-id="automate-fetcher" >}} + ```ruby + # Invoke the Compliance Phase + default['audit']['compliance_phase'] = true + # Set profile location + default['audit']['profiles']['ssh'] = { + 'supermarket': 'hardening/ssh-hardening' + } + # Fetch additional profiles + default['audit']['fetcher'] = 'chef-automate' + ``` + {{< warning >}} + Fetching profiles from Chef Automate requires setting `data_collector.server_url` and `data_collector.token` in your `client.rb` to fetch profiles from Chef Automate. This configuration is described in more detail in the Chef Automate [data collector documentation](https://docs.chef.io/automate/data_collection/). + {{< /warning >}} + {{< /foundation_tabs_panel >}} + {{< foundation_tabs_panel panel-id="server-fetcher" >}} + ```ruby + # Invoke the Compliance Phase + default['audit']['compliance_phase'] = true + # Set profile location + default['audit']['profiles']['ssh'] = { + 'supermarket': 'hardening/ssh-hardening' + } + # Fetch additional profiles + default['audit']['fetcher'] = 'chef-server' + ``` + {{< /foundation_tabs_panel >}} +{{< /foundation_tabs_panels >}} + + + +### Reporters + +Reporters control what's done with the resulting report after the Chef InSpec run. Either a single value or a list of multiple values is supported. The default is the `cli` and `json-file` reporters. + +Reporters can send Compliance Phase results to: + +- Chef Automate proxied by Chef Infra Server. +- Directly to Chef Automate (requires additional authentication). +- The terminal if Chef Infra Client is run interactively by a user. +- A file on disk. + +The following examples: + +- Retrieve the 'ssh' profile from Chef Supermarket +- Fetch additional profiles from Chef Automate +- Send the results to Chef Automate, Chef Automate proxied by Chef Infra Server, or to a file on disk. + + + +{{< foundation_tabs tabs-id="compliance-phase-reporter-panel" >}} + {{< foundation_tab active="true" panel-link="automate-reporter" tab-text="Automate">}} + {{< foundation_tab panel-link="server-reporter" tab-text="Automate using Infra Server" >}} + {{< foundation_tab panel-link="local-reporter" tab-text="File" >}} +{{< /foundation_tabs >}} +{{< foundation_tabs_panels tabs-id="compliance-phase-reporter-panel" >}} + {{< foundation_tabs_panel active="true" panel-id="automate-reporter" >}} + ```ruby + # Invoke the Compliance Phase + default['audit']['compliance_phase'] = true + # Set profile location + default['audit']['profiles']['ssh'] = { + 'supermarket': 'hardening/ssh-hardening' + } + # Fetch additional profiles + default['audit']['fetcher'] = 'chef-automate' + # Set reporter + default['audit']['reporter'] = 'chef-automate' + ``` + {{< warning >}} + Reporting Compliance Phase results directly to Chef Automate requires setting `data_collector.server_url` and `data_collector.token` in your `client.rb` to fetch profiles from Chef Automate. This configuration is described in more detail in the Chef Automate [data collector documentation](https://docs.chef.io/automate/data_collection/). + {{< /warning >}} + {{< /foundation_tabs_panel >}} + {{< foundation_tabs_panel panel-id="server-reporter" >}} + ```ruby + # Invoke the Compliance Phase + default['audit']['compliance_phase'] = true + # Set profile location + default['audit']['profiles']['ssh'] = { + 'supermarket': 'hardening/ssh-hardening' + } + # Fetch additional profiles + default['audit']['fetcher'] = 'chef-server' + # Set reporter + default['audit']['reporter'] = 'chef-server-automate' + ``` + + {{< /foundation_tabs_panel >}} + {{< foundation_tabs_panel panel-id="local-reporter" >}} + ```ruby + # Invoke the Compliance Phase + default['audit']['compliance_phase'] = true + # Set profile location + default['audit']['profiles']['ssh'] = { + 'supermarket': 'hardening/ssh-hardening' + } + # Fetch additional profiles + default['audit']['fetcher'] = 'chef-automate' + # Set two reporters + default['audit']['reporter'] = 'json-file', 'cli' + # Set the location of the json-file output + # Note that the location attribute uses json_file + default['audit']['json_file']['location'] = '/file/path/report.json' + ``` + + The default `json-file` path is: `/compliance_reports/compliance-.json`. + + The path will also be output to the Chef Infra Client log: + + ```bash + ['2017-08-29T00:22:10+00:00'] INFO: Reporting to json-file + ['2017-08-29T00:22:10+00:00'] INFO: Writing report to /opt/kitchen/cache/compliance-reports/compliance-20170829002210.json + ['2017-08-29T00:22:10+00:00'] INFO: Report handlers complete + ``` + + {{< /foundation_tabs_panel >}} +{{< /foundation_tabs_panels >}} + + + +## Customize Profiles + +You can upload profiles to Chef Automate using the [Chef Automate API](https://docs.chef.io/automate/api/#operation/Create) or the `inspec compliance` command. + +### Waivers + +Use [waivers](https://docs.chef.io/inspec/waivers/) to mark individual failing controls as administratively accepted, either on a temporary or permanent basis. + +To use waivers: + +1. Prepare a YAML waiver file. +1. Deliver the waiver file to the node in a [cookbook_file]({{< relref "/resources/bundled/cookbook_file" >}}) or [remote_file]({{< relref "/resources/bundled/remote_file" >}}). +1. Set the `waiver_file` attribute for the Compliance Phase to that location. For example: + +```ruby +default['audit']['waiver_file'] = "waivers.yaml" +``` + +### External Data + +Chef InSpec profiles should be self-contained and independent from external data. Sometimes, a profile's test may exhibit different behavior depending on aspects of the node being tested and in these cases, you may want to use external data. Chef InSpec profiles accept [inputs](https://docs.chef.io/inspec/inputs/) that let you customize the test. + +#### Chef InSpec Input + +You can pass [Chef InSpec inputs](https://docs.chef.io/inspec/inputs/) to the Chef InSpec runner. Chef InSpec inputs were previously called `attributes` and you will set them in an `['audit']['attributes']` hash in your attributes file. +Any data added to `['audit']['attributes']` as a hash is passed to Chef InSpec as individual attributes. + + ```ruby + default['audit']['attributes'] = { + first_input: 'some value', + second_input: 'another value', + } + ``` + +#### Chef Node Data + +There are two primary ways to pass Chef Infra node data to Chef InSpec run during the Compliance Phase. + +##### Explicitly pass necessary data (recommended) + +Any data added to the `node['audit']['attributes']` hash will be passed as individual Chef InSpec attributes. This provides a clean interface between the Chef Infra client run and Chef InSpec profile, allowing for easy assignment of default values in the Chef InSpec profile. This method is especially recommended if the Chef InSpec profile is expected to be used outside of the context of Compliance Phase so it's made explicit to profile consumers what attributes are necessary. Set the attributes in your cookbook attributes file and then use them in your Chef InSpec profile. + +Set the attributes in a cookbook attributes file: + +```ruby +node['audit']['attributes']{ + 'key1' = 'value1', + 'debug_enabled' = node['my_cookbook']['debug_enabled'], + 'environment' = node.chef_environment +} +``` + +Use the attributes in a Chef InSpec profile: + +```ruby +environment = attribute('environment', description: 'The Chef Infra environment for the node', default: 'dev') + +control 'debug-disabled-in-production' do + title 'Debug logs disabled in production' + desc 'Debug logs contain potentially sensitive information and shouldn't be on in production.' + impact 1.0 + + describe file('/path/to/my/app/config') do + its('content') { should_not include "debug=true" } + end + + only_if { environment == 'production' } +end +``` + +#### Use the Chef Infra Node Object + +Compliance Phase can be configured to pass the Chef Infra node object as a Chef InSpec attribute named `chef_node`. + +While using the `chef_node` object provides the ability to write more flexible profiles, it's difficult to reuse these profiles outside of the Compliance Phase. To reuse these profiles, you will need to understand how to pass in a single attribute containing Chef Infra-like data. Pass external data explicitly whenever possible. + +To use this option, first set it in a wrapper cookbook: + +```ruby +node.override['audit']['chef_node_attribute_enabled'] = true +``` + +And then use it in your profile: + +```ruby +chef_node = attribute('chef_node', description: 'Chef Node') + +control 'no-password-auth-in-prod' do + title 'No Password Authentication in Production' + desc 'Password authentication is allowed in all environments except production' + impact 1.0 + + describe sshd_config do + its('PasswordAuthentication') { should cmp 'No' } + end + + only_if { chef_node['chef_environment'] == 'production' } +end +``` + +## Useful Compliance Phase Attributes + +### audit-enforcer + +A special reporter that causes the compliance run to raise an error and immediately terminates the Chef Infra Client run if any control of any Chef InSpec profile fails. If you specify multiple reporters, place the `audit-enforcer` at the end of the list, allowing the other reporters to generate their output before run termination. Example: + +```ruby +# fail on error +default['audit']['reporter'] = 'audit-enforcer'. +``` + +### chef_node_attribute_enabled + +If set, a hash representation of the Chef Infra node object will be sent to an input named `chef_node`. Default: false + +```ruby +# send a hash representation of the Chef Infra node object +default['audit']['chef_node_attribute_enabled'] = true +``` + +### compliance_phase + +Turn on the built-in Compliance Phase run. Possible values: true, false, nil + +```ruby +# Turn on Compliance Phase +default['audit']['compliance_phase] = true +``` + +### control_results_limit + +The list of results for each control will be truncated to this amount to reduce the size of reports. A summary of removed results will be sent with each impacted control. Defaults to `50`. + +```ruby +# allow 100 results + default['audit']['control_results_limit'] = 100 +``` + +### fetcher + +Controls the location for additional profile locations for Chef InSpec profiles default fetch locations provided through the `[audit][profiles]` attribute. Accepted values: nil, 'chef-server', 'chef-automate'. + +```ruby +# fetch additional profiles from Chef Infra Server +default[audit][fetcher] = 'chef-server' +``` + +### insecure + +Setting the attribute `default['audit']['insecure']` to `true` will skip SSL certificate verification for the `chef-automate` and `chef-server-automate` reporters. This allows connections to HTTPS endpoints with self-signed ssl certificates. Default is `false` + +```ruby +# allow self-signed certificates +default['audit']['insecure'] = true +``` + +### interval + +You can control the frequency of Compliance Phase scans with the `default['audit']['interval']`, which means that control the frequency that the Compliance Phase runs with a Chef Infra Client run. This helps you control the impact of compliance scans on system performance in business environments that require compliance scans less frequently than Chef Infra Client Runs. + +`default['audit']['interval']['enabled']` +: Set to true to turn on interval runs. + + ```ruby + # Set independent Compliance Phase scans + default['audit']['interval']['enabled'] = true + ``` + +`default['audit']['interval']['time']` +: The time in minutes between Compliance Phase execution. Default: 1440 (once a day). + + ```ruby + # Define the timing of independent Compliance Phase scans + # Sets scan to twice daily + default['audit']['interval']['time'] = 1220 + ``` + +### json_file + +The location on disk that Chef InSpec's json reports are saved to when using the 'json-file' reporter. Defaults to: `/compliance_reports/compliance-.json` + +```ruby +default['audit']['reporter'] = 'json-file' +default['audit']['json_file']['location'] = '/path/to/file.json' +``` + +### inspec_backend_cache + +Chef InSpec caches the results of commands executed on the node during the Compliance Phase. Caching improves the Compliance Phase performance when slower-running commands are executed multiple times during a Chef Infra Client run. Disable this feature if your Chef InSpec profile runs a command multiple times expecting different output during the run. Default: true. Example: + +```ruby +# Disable caching of commands +default['audit']['inspec_backend_cache'] = false +``` + +### profiles + +Chef InSpec Compliance profiles to be used for scanning nodes. + +```ruby +# use the ssh-hardening profile from Supermarket +default['audit']['profiles']['ssh'] = { + 'supermarket': 'hardening/ssh-hardening' + } +``` + +### quiet + +Starting in Chef Infra Client 18.7, use `quiet` to suppress output of the Chef InSpec runner. Defaults to `false`. + +To suppress InSpec runner output, set to `true`: + +```ruby +# verbose +default['audit']['quiet'] = true +``` + +### reporter + +Controls what's done with the resulting report after the Chef InSpec run. Accepts a single string value or an array of multiple values. The 'cli' reporter mimics the Chef InSpec command line output in your terminal, which lets you see your system's compliance status at the end of the Compliance Phase. Accepted values: 'chef-server-automate', 'chef-automate', 'json-file', 'audit-enforcer', 'cli' + +```ruby +# set the reporter to Chef Automate +default['audit']['reporter'] = 'chef-automate', 'cli' +``` + +### run_time_limit + +Control results that have a `run_time` below this limit will be stripped of the `start_time` and `run_time` fields to reduce the size of reports. Defaults to `1.0`. Set this attribute with `default['audit']['run_time_limit']`. + +```ruby +# allow 5 minutes run time +default['audit']['run_time_limit'] = 5.0 +``` + +### result_include_backtrace + +When a Chef InSpec resource throws an exception, results contain a short error message and a detailed ruby stacktrace of the error. Default: false (doesn't send backtrace). Example: + +```ruby +# include backtrace +default['audit']['result_include_backtrace'] = true +``` + +### result_message_limit + +Truncates any control result messages exceeding this character limit. Chef Automate has a 4 MB report size limit and can't ingest reports exceeding this limitation. Chef InSpec will append this text at the end of any truncated messages: `[Truncated to 10000 characters]` Default: 10000. + +```ruby +default['audit']['result_message_limit] = 10000 +``` + +### server + +When reporting to a Chef Automate instance proxied over Chef Infra Server, the Compliance Phase can be configured to use a different URL than the `chef_server_url` configured in `client.rb`. Turn on with the attribute `default['audit']['server']`. + +```ruby +default['audit']['server'] = 'https://server.4thcafe.com'. +``` + +### waiver_file + +A string path or an array of paths to Chef InSpec waiver files. + +```ruby +default['audit']['waiver_file'] = 'path/to/waiver.yml'. +``` + +## Errors and Troubleshooting + +### Cache Results + +Chef InSpec caches the results of commands executed on the node during the Compliance Phase. Caching improves the Compliance Phase performance when slower-running commands are executed multiple times during a Chef Infra Client run. Disable this feature if your Chef InSpec profile runs a command multiple times expecting different output during the run. Default: true. Example: + +```ruby +# Disable caching of commands +default['audit']['inspec_backend_cache'] = false +``` + +### Chef InSpec Report Size Limits + +The size of the report being generated from running the Compliance Phase is influenced by a few factors like: + +- number of controls and tests in a profile +- number of profile failures for the node +- controls metadata (title, description, tags, etc) +- number of resources (users, processes, etc) that are being tested + +Depending on your setup, there are some limits you need to be aware of. A common one is Chef Infra Server default (1MB) request size. Exceeding this limit will reject the report with `ERROR: 413 "Request Entity Too Large"`. For more details about these limits, please refer to [the documentation on troubleshooting 413 errors](#413-request-entity-too-large). + +### HTTP Errors + +#### 401, 403 Unauthorized - bad clock + +Occasionally, the system date/time will drift between client and server. If this drift is greater than a couple of minutes, Chef Infra Server will throw a 401 unauthorized and the request won't be forwarded to the Chef Automate server. + +On Chef Infra Server you can see this in the following logs: + +```text +# chef-server-ctl tail + +==> /var/log/opscode/nginx/access.log <== +192.168.200.102 - - ['28/Aug/2016:14:57:36 +0000'] "GET /organizations/4thcafe/nodes/vagrant-c0971990 HTTP/1.1" 401 "0.004" 93 "-" "Chef Infra Client/12.14.38 (ruby-2.3.1-p112; ohai-8.19.2; x86_64-linux; +https://chef.io)" "127.0.0.1:8000" "401" "0.003" "12.14.38" "algorithm=sha1;version=1.1;" "vagrant-c0971990" "2013-09-25T15:00:14Z" "2jmj7l5rSw0yVb/vlWAYkK/YBwk=" 1060 + +==> /var/log/opscode/opscode-erchef/crash.log <== +2016-08-28 14:57:36 =ERROR REPORT==== +{<<"method=GET; path=/organizations/4thcafe/nodes/vagrant-c0971990; status=401; ">>,"Unauthorized"} + +==> /var/log/opscode/opscode-erchef/erchef.log <== +2016-08-28 14:57:36.521 ['error'] {<<"method=GET; path=/organizations/4thcafe/nodes/vagrant-c0971990; status=401; ">>,"Unauthorized"} + +==> /var/log/opscode/opscode-erchef/current <== +2016-08-28_14:57:36.52659 ['error'] {<<"method=GET; path=/organizations/4thcafe/nodes/vagrant-c0971990; status=401; ">>,"Unauthorized"} + +==> /var/log/opscode/opscode-erchef/requests.log.1 <== +2016-08-28T14:57:36Z erchef@127.0.0.1 method=GET; path=/organizations/4thcafe/nodes/vagrant-c0971990; status=401; req_id=g3IAA2QAEGVyY2hlZkAxMjcuMC4wLjEBAAOFrgAAAAAAAAAA; org_name=4thcafe; msg=bad_clock; couchdb_groups=false; couchdb_organizations=false; couchdb_containers=false; couchdb_acls=false; 503_mode=false; couchdb_associations=false; couchdb_association_requests=false; req_time=1; user=vagrant-c0971990; req_api_version=1; +``` + +Additionally, the chef_gate log will contain a similar message: + +```text +# /var/log/opscode/chef_gate/current +2016-08-28_15:01:34.88702 ['GIN'] 2016/08/28 - 15:01:34 | 401 | 13.650403ms | 192.168.200.102 | POST /compliance/organizations/4thcafe/inspec +2016-08-28_15:01:34.88704 Error #01: Authentication failed. Please check your system's clock. +``` + +#### 401 Token and Refresh Token Authentication + +In the event of a malformed or unset token, the Chef Automate server will log the token error: + +```text +==> /var/log/chef-compliance/core/current <== +2016-08-28_20:41:46.17496 20:41:46.174 ERR => Token authentication: %!(EXTRA *errors.errorString=malformed JWS, only 1 segments) +2016-08-28_20:41:46.17498 ['GIN'] 2016/08/28 - 20:41:46 | 401 | 53.824us | 192.168.200.102 | GET /owners/base/compliance/linux/tar + +==> /var/log/chef-compliance/nginx/compliance.access.log <== +192.168.200.102 - - ['28/Aug/2016:21:23:46 +0000'] "GET /api/owners/base/compliance/linux/tar HTTP/1.1" 401 0 "-" "Ruby" +``` + +#### 413 Request Entity Too Large + +This error indicates that you have exceeded limit the `erchef` request size in Chef Infra Server. The default for versions before 13.0 was 1MB. Starting with version 13.0 the default is 2MB. + +To resolve this error, set the `opscode_erchef['max_request_size']` in Chef Infra Server's `/etc/opscode/chef-server.rb` to a larger amount. This example sets the limit to 3MB: + +```ruby +opscode_erchef['max_request_size'] = 3000000 +``` + +Then run `chef-server-ctl reconfigure` to apply this change. + +##### 413 Error Logs + +The 413 "Request Entity Too Large" error appears in both the stacktrace and Chef Infra Server Nginx logs. + + + +{{< foundation_tabs tabs-id="compliance-413-panel" >}} + {{< foundation_tab active="true" panel-link="413-stacktrace" tab-text="Stacktrace">}} + {{< foundation_tab panel-link="413-server-nginx" tab-text="Nginx logs" >}} +{{< /foundation_tabs >}} +{{< foundation_tabs_panels tabs-id="compliance-413-panel" >}} + {{< foundation_tabs_panel active="true" panel-id="413-stacktrace" >}} + The stacktrace shows the 413 error: + ```text + Running handlers: + ['2017-12-21T16:21:15+00:00'] WARN: Compliance report size is 1.71 MB. + ['2017-12-21T16:21:15+00:00'] ERROR: 413 "Request Entity Too Large" (Net::HTTPServerException) + /opt/chef/embedded/lib/ruby/2.4.0/net/http/response.rb:122:in `error!' + /opt/chef/embedded/lib/ruby/gems/2.4.0/gems/chef-13.6.4/lib/chef/http.rb:152:in `request' + /opt/chef/embedded/lib/ruby/gems/2.4.0/gems/chef-13.6.4/lib/chef/http.rb:131:in `post' + /var/chef/cache/cookbooks/audit/libraries/reporters/cs_automate.rb:37:in `block in send_report' + ... + ``` + {{< /foundation_tabs_panel >}} + {{< foundation_tabs_panel panel-id="413-server-nginx" >}} + The Chef Infra Server Nginx log confirms the `413` error: + ```text + ==> /var/log/opscode/nginx/access.log <== + 192.168.56.40 - - ['21/Dec/2017:11:35:30 +0000'] "POST /organizations/eu_org/data-collector HTTP/1.1" 413 "0.803" 64 "-" "Chef Infra Client/13.6.4 (ruby-2.4.2-p198; ohai-13.6.0; x86_64-linux; +https://chef.io)" "-" "-" "-" "13.6.4" "algorithm=sha1;version=1.1;" "bootstrapped-node" "2017-12-21T11:35:31Z" "GR6RyPvKkZDaGyQDYCPfoQGS8G4=" 1793064 + ``` + {{< /foundation_tabs_panel >}} + +{{< /foundation_tabs_panels >}} + + + +## Troubleshooting + +Chef Automate sets the `logstash` limit to 10% of the system memory automatically as part of the `automate-ctl reconfigure` command execution. You have reached the java heap size(`-Xmx`) limit of `logstash` if a Chef InSpec report doesn't become available in Chef Automate and this error is in the `logstash` logs: + +```text +/var/log/delivery/logstash/current +2017-12-21_13:59:54.69949 DEBUG: Ruby filter is processing an 'inspec_profile' event +2017-12-21_14:00:16.51553 java.lang.OutOfMemoryError: Java heap space +2017-12-21_14:00:16.51556 Dumping heap to /opt/delivery/embedded/logstash/heapdump.hprof ... +2017-12-21_14:00:16.51556 Unable to create /opt/delivery/embedded/logstash/heapdump.hprof: File exists +2017-12-21_14:00:18.50676 Error: Your application used more memory than the safety cap of 383M. +2017-12-21_14:00:18.50694 Specify -J-Xmx####m to increase it (#### = cap size in MB). +2017-12-21_14:00:18.50703 Specify -w for full OutOfMemoryError stack trace +``` diff --git a/content/features/chef_search.md b/content/features/chef_search.md new file mode 100644 index 0000000..1777520 --- /dev/null +++ b/content/features/chef_search.md @@ -0,0 +1,384 @@ ++++ +title = "About Search" +draft = false + +[menu] + [menu.features] + title = "Search" + identifier = "features/chef_search.md Search" + parent = "features" + weight = 70 ++++ + +{{< readfile file="content/reusable/md/search.md" >}} + +Many of the examples in this section use knife, but the search indexes +and search query syntax can be used in many locations, including from +within recipes and when using the Chef Infra Server API. + +## Search Indexes + +A search index is a full-text list of objects that are stored on the +Chef Infra Server, against which search queries can be made. The +following search indexes are built: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Search Index NameDescription
clientAPI client
DATA_BAG_NAMEA data bag is a global variable that's stored as JSON data and is accessible from a Chef Infra Server. The name of the search index is the name of the data bag. For example, if the name of the data bag was "admins" then a corresponding search query might look something like search(:admins, "*:*").
environmentAn environment is a way to map an organization's real-life workflow to what can be configured and managed when using Chef Infra Server.
nodeA node is any server or virtual server that's configured to be maintained by a Chef Infra Client.
roleA role is a way to define certain patterns and processes that exist across nodes in an organization as belonging to a single job function.
+ +### Using Knife + +{{< readfile file="content/reusable/md/workstation/knife_search_summary.md" >}} + +#### Search by platform ID + +{{< readfile file="content/reusable/md/workstation/knife_search_by_platform_ids.md" >}} + +#### Search by instance type + +{{< readfile file="content/reusable/md/workstation/knife_search_by_platform_instance_type.md" >}} + +#### Search by recipe + +{{< readfile file="content/reusable/md/workstation/knife_search_by_recipe.md" >}} + +#### Search by cookbook, then recipe + +{{< readfile file="content/reusable/md/workstation/knife_search_by_cookbook.md" >}} + +#### Search by node + +{{< readfile file="content/reusable/md/workstation/knife_search_by_node.md" >}} + +#### Search by node and environment + +{{< readfile file="content/reusable/md/workstation/knife_search_by_node_and_environment.md" >}} + +#### Search for nested attributes + +{{< readfile file="content/reusable/md/workstation/knife_search_by_nested_attribute.md" >}} + +#### Search for multiple attributes + +{{< readfile file="content/reusable/md/workstation/knife_search_by_query_for_many_attributes.md" >}} + +#### Search for nested attributes using a search query + +{{< readfile file="content/reusable/md/workstation/knife_search_by_query_for_nested_attribute.md" >}} + +#### Use a test query + +{{< readfile file="content/reusable/md/workstation/knife_search_test_query_for_ssh.md" >}} + +## Query Syntax + +{{< readfile file="content/reusable/md/search_query_syntax.md" >}} + +{{< note >}} + +Search queries may not contain newlines. + +{{< /note >}} + +## Filter Search Results + +{{< readfile file="content/reusable/md/infra_lang_method_search_filter_result.md" >}} + +## Keys + +{{< readfile file="content/reusable/md/search_key.md" >}} + +### Nested Fields + +{{< readfile file="content/reusable/md/search_key_nested.md" >}} + +### Examples + +{{< readfile file="content/reusable/md/search_key_name.md" >}} + +{{< readfile file="content/reusable/md/search_key_wildcard_question_mark.md" >}} + +{{< readfile file="content/reusable/md/search_key_wildcard_asterisk.md" >}} + +{{< readfile file="content/reusable/md/search_key_nested_starting_with.md" >}} + +{{< readfile file="content/reusable/md/search_key_nested_range.md" >}} + +## Patterns + +{{< readfile file="content/reusable/md/search_pattern.md" >}} + +### Exact Matching + +{{< readfile file="content/reusable/md/search_pattern_exact.md" >}} + +{{< readfile file="content/reusable/md/search_pattern_exact_key_and_item.md" >}} + +{{< readfile file="content/reusable/md/search_pattern_exact_key_and_item_string.md" >}} + +### Wildcard Matching + +{{< readfile file="content/reusable/md/search_pattern_wildcard.md" >}} + +{{< readfile file="content/reusable/md/search_pattern_wildcard_any_node.md" >}} + +{{< readfile file="content/reusable/md/search_pattern_wildcard_node_contains.md" >}} + +### Range Matching + +{{< readfile file="content/reusable/md/search_pattern_range.md" >}} + +{{< readfile file="content/reusable/md/search_pattern_range_in_between.md" >}} + +{{< readfile file="content/reusable/md/search_pattern_range_exclusive.md" >}} + +### Fuzzy Matching + +{{< readfile file="content/reusable/md/search_pattern_fuzzy.md" >}} + +{{< readfile file="content/reusable/md/search_pattern_fuzzy_summary.md" >}} + +## Operators + +{{< readfile file="content/reusable/md/search_boolean_operators.md" >}} + +{{< readfile file="content/reusable/md/search_boolean_operators_andnot.md" >}} + +### AND + +{{< readfile file="content/reusable/md/search_boolean_and.md" >}} + +### NOT + +{{< readfile file="content/reusable/md/search_boolean_not.md" >}} + +### OR + +{{< readfile file="content/reusable/md/search_boolean_or.md" >}} + +## Special Characters + +{{< readfile file="content/reusable/md/search_special_characters.md" >}} + +## Targets + +A search target is any object that has been indexed on the Chef Infra +Server, including roles (and run-lists), nodes, environments, data bags, +and any API client. + +### Roles in Run-lists + +A search query can be made for roles that are at the top-level of a +run-list and also for a role that's part of an expanded run-list. + +{{< note >}} + +The `roles` field is updated with each Chef Infra Client run; changes to +a run-list won't affect `roles` until the next Chef Infra Client run +on the node. + +{{< /note >}} + + ++++ + + + + + + + + + + + + + + + + +
Role LocationDescription

Top-level

To find a node with a role in the top-level of its run-list, search within the role field (and escaping any special characters with the slash symbol) using the following syntax:

+
role:ROLE_NAME
+

where role (singular!) indicates the top-level run-list.

Expanded

To find a node with a role in an expanded run-list, search within the roles field (and escaping any special characters with the slash symbol) using the following syntax:

+
roles:ROLE_NAME
+

where roles (plural!) indicates the expanded run-list.

+ +To search a top-level run-list for a role named `load_balancer` use the +`knife search` subcommand from the command line or the `search` method +in a recipe. For example: + +```bash +knife search node role:load_balancer +``` + +and from within a recipe: + +```ruby +search(:node, 'role:load_balancer') +``` + +To search an expanded run-list for all nodes with the role +`load_balancer` use the `knife search` subcommand from the command line +or the `search` method in a recipe. For example: + +```bash +knife search node roles:load_balancer +``` + +and from within a recipe: + +```ruby +search(:node, 'roles:load_balancer') +``` + +### Nodes + +A node can be searched from a recipe by using the following syntax: + +```ruby +search(:node, "key:attribute") +``` + +A wildcard can be used to replace characters within the search query. + +Expanded lists of roles (all of the roles that apply to a node, +including nested roles) and recipes to the role and recipe attributes on +a node are saved on Chef Infra Server. The expanded lists of roles +allows for searching within nodes that run a given recipe, even if that +recipe is included by a role. + +{{< note >}} + +The `recipes` field is with each Chef Infra Client run; changes to a +run-list won't affect `recipes` until the next Chef Infra Client run +on the node. + +{{< /note >}} + + ++++ + + + + + + + + + + + + + + + + +
Node LocationDescription

In a specified recipe

To find a node with a specified recipe in the run-list, search within the run_list field (and escaping any special characters with the slash symbol) using the following syntax:

+
search(:node, 'run_list:recipe\[foo\:\:bar\]')
+

where recipe (singular!) indicates the top-level run-list. Variables can be interpolated into search strings using the Ruby alternate quoting syntax:

+
search(:node, %Q{run_list:"recipe[#{the_recipe}]"} )

In an expanded run-list

To find a node with a recipe in an expanded run-list, search within the recipes field (and escaping any special characters with the slash symbol) using the following syntax:

+
recipes:RECIPE_NAME
+

where recipes (plural!) indicates to search within an expanded run-list.

+ +If you just want to use each result of the search and don't care about +the aggregate result you can provide a code block to the search method. +Each result is then passed to the block: + +```ruby +# Print every node matching the search pattern +search(:node, "*:*").each do |matching_node| + puts matching_node.to_s +end +``` + +### API Clients + +An API client is any machine that has permission to use the Chef Infra +Server API to communicate with Chef Infra Server. An API client is +typically a node (that runs Chef Infra Client) or a workstation (that +runs knife), but can also be any other machine configured to use the +Chef Infra Server API. + +Sometimes when a role isn't fully defined (or implemented), it may be +necessary for a machine to connect to a database, search engine, or some +other service within an environment by using the settings located on +another machine, such as a host name, IP address, or private IP address. +The following example shows a simplified settings file: + +```ruby +username: "mysql" +password: "MoveAlong" +host: "10.40.64.202" +port: "3306" +``` + +where `host` is the private IP address of the database server. Use the +following knife query to view information about the node: + +```bash +knife search node "name:name_of_database_server" --long +``` + +To access these settings as part of a recipe that's run on the web +server, use code similar to: + +```ruby +db_server = search(:node, "name:name_of_database_server") +private_ip = "#{db_server[0][:rackspace][:private_ip]}" +puts private_ip +``` + +where the "\[0\]" is the 0 (zero) index for the `db_server` identifier. +A single document is returned because the node is being searched on its +unique name. The identifier `private_ip` will now have the value of the +private IP address of the database server (`10.40.64.202`) and can then +be used in templates as a variable, among other possible uses. + +### Environments + +{{< readfile file="content/reusable/md/environment.md" >}} + +{{< readfile file="content/reusable/md/search_environment.md" >}} + +### Data Bags + +{{< readfile file="content/reusable/md/data_bag.md" >}} + +{{< readfile file="content/reusable/md/search_data_bag.md" >}} diff --git a/content/features/chef_solo/_index.md b/content/features/chef_solo/_index.md new file mode 100644 index 0000000..ce01733 --- /dev/null +++ b/content/features/chef_solo/_index.md @@ -0,0 +1,162 @@ ++++ +title = "chef-solo" +draft = false + +[menu] + [menu.features] + title = "About Chef Solo" + identifier = "features/chef_solo/chef_solo.md About Chef Solo" + parent = "features/chef_solo" + weight = 10 ++++ + +{{< readfile file="content/reusable/md/chef_solo_summary.md" >}} + +## Cookbooks + +chef-solo supports two locations from which cookbooks can be run: + +- A local directory. +- A URL at which a tar.gz archive is located. + +Using a tar.gz archive is the more common approach, but requires that +cookbooks be added to an archive. For example: + +```bash +tar zcvf chef-solo.tar.gz ./cookbooks +``` + +If you use multiple cookbook directories, chef-solo expects the +tar.gz archive to have a directory structure similar to the following: + +```text +. cookbooks +├── cookbook-name-1 +│ └── attributes +└── cookbook-name-2 + └── attributes +``` + +The `cookbook_path` variable in the solo.rb file must include both +directories. For example: + +```bash +tar zcvf chef-solo.tar.gz ./cookbooks ./site-cookbooks +``` + +When the tar.gz archive contains all of the cookbooks required by +chef-solo, upload it to the web server from which chef-solo will access +the archive. + +## Nodes + +Unlike Chef Infra Client, where the node object is stored on the Chef +Infra Server, chef-solo stores its node objects as JSON files on local +disk. By default, chef-solo stores these files in a `nodes` folder in +the same directory as your `cookbooks` directory. You can control the +location of this directory using the `node_path` value in your +configuration file. + +## Attributes + +chef-solo doesn't interact with Chef Infra Server. Consequently, +node-specific attributes must be located in a JSON file on the target +system, a remote location (such as Amazon Simple Storage Service (S3)), +or a web server on the local network. + +The JSON file must also specify the recipes that are part of the +run-list. For example: + +```json +{ + "resolver": { + "nameservers": [ "10.0.0.1" ], + "search":"int.example.com" + }, + "run_list": [ "recipe[resolver]" ] +} +``` + +## Data bags + +A data bag is defined using JSON. chef-solo will look for data bags in +`/var/chef/data_bags`, but this location can be modified by changing the +setting in solo.rb. For example, the following setting in solo.rb: + +```ruby +data_bag_path '/var/chef-solo/data_bags' +``` + +Create a data bag by creating folders. For example: + +```bash +mkdir /var/chef-solo/data_bags +``` + +and: + +```bash +mkdir /var/chef-solo/data_bags/admins +``` + +and then create a JSON file in that location: + +```json +{ + "id": "ITEM_NAME" +} +``` + +where the name of the file is the `ITEM_NAME`, for example: + +```ruby +/var/chef-solo/data_bags/admins/ITEM_NAME.json +``` + +## Roles + +A role is defined using JSON or the Ruby DSL. chef-solo will look for +roles in `/var/chef/roles`, but this location can be modified by +changing the setting for `role_path` in solo.rb. For example, the +following setting in solo.rb: + +```ruby +role_path '/var/chef-solo/roles' +``` + +Role data looks like the following in JSON: + +```json +{ + "name": "test", + "default_attributes": { }, + "override_attributes": { }, + "json_class": "Chef::Role", + "description": "This is just a test role, no big deal.", + "chef_type": "role", + "run_list": [ "recipe[test]" ] +} +``` + +and like the following in the Ruby DSL: + +```ruby +name 'test' +description 'This is just a test role, no big deal.' +run_list 'recipe[test]' +``` + +and finally, JSON data passed to chef-solo: + +```ruby +{ 'run_list': 'role[test]' } +``` + +## Environments + +{{< readfile file="content/reusable/md/chef_solo_environments.md" >}} + +## chef-solo (executable) + +See [chef-solo (executable)](/features/chef_solo/ctl_chef_solo/) for complete CTL +documentation. diff --git a/content/features/chef_solo/config_rb_solo.md b/content/features/chef_solo/config_rb_solo.md new file mode 100644 index 0000000..68a5dec --- /dev/null +++ b/content/features/chef_solo/config_rb_solo.md @@ -0,0 +1,171 @@ ++++ +title = "solo.rb" +draft = false + +[menu] + [menu.features] + title = "solo.rb" + identifier = "features/chef_solo/config_rb_solo.md solo.rb Configuration" + parent = "features/chef_solo" + weight = 30 ++++ + +A solo.rb file is used to specify the configuration details for +chef-solo. + +- This file is loaded every time this executable is run +- The default location in which chef-solo expects to find this file is `/etc/chef/solo.rb`; use the `--config` option from the command line to change this location +- This file isn't created by default +- When a `solo.rb` file is present in this directory, the settings contained within that file will override the default configuration settings + +## Settings + +This configuration file has the following settings: + +`add_formatter` + +: A 3rd-party formatter. (See [nyan-cat](https://github.com/andreacampi/nyan-cat-chef-formatter) for an example of a 3rd-party formatter.) Each formatter requires its own entry. + +`checksum_path` + +: The location in which checksum files are stored. These are used to validate individual cookbook files, such as recipes. The checksum itself is stored in the Chef Infra Server database and is then compared to a file in the checksum path that has a filename identical to the checksum. + +`cookbook_path` + +: The Chef Infra Client sub-directory for cookbooks. This value can be a string or an array of file system locations, processed in the specified order. The last cookbook is considered to override local modifications. + +`data_bag_path` + +: The location from which a data bag is loaded. Default value: `/var/chef/data_bags`. + +`environment` + +: The name of the environment. + +`environment_path` + +: The path to the environment. Default value: `/var/chef/environments`. + +`file_backup_path` + +: The location in which backup files are stored. If this value is empty, backup files are stored in the directory of the target file. Default value: `/var/chef/backup`. + +`file_cache_path` + +: The location in which cookbooks (and other transient data) files are stored when they're synchronized. This value can also be used in recipes to download files with the **remote_file** resource. + +`json_attribs` + +: The path to a file that contains JSON data. + +`lockfile` + +: The location of the Chef Infra Client lock file. This value is typically platform-dependent, so should be a location defined by `file_cache_path`. The default location of a lock file shouldn't on an NF mount. Default value: a location defined by `file_cache_path`. + +`log_level` + +: The level of logging to be stored in a log file. Possible levels: `:auto` (default), `debug`, `info`, `warn`, `error`, or `fatal`. + +`log_location` + +: The location of the log file. Default value: `STDOUT`. + +`minimal_ohai` + +: Run the Ohai plugins for name detection and resource/provider selection and no other Ohai plugins. Set to `true` during integration testing to speed up test cycles. + +`node_name` + +: The unique identifier of the node. + +`recipe_url` + +: The URL location from which a remote cookbook tar.gz is to be downloaded. + +`rest_timeout` + +: The time (in seconds) after which an HTTP REST request is to time out. Default value: `300`. + +`role_path` + +: The location in which role files are located. Default value: `/var/chef/roles`. + +`run_lock_timeout` + +: The amount of time (in seconds) to wait for a Chef Infra Client lock file to be deleted. A Chef Infra Client run won't start when a lock file is present. If a lock file isn't deleted before this time expires, the pending Chef Infra Client run will exit. Default value: not set (indefinite). Set to `0` to cause a second Chef Infra Client to exit immediately. + +`sandbox_path` + +: The location in which cookbook files are stored (temporarily) during upload. + +`solo` + +: Run Chef Infra Client in chef-solo mode. This setting determines if Chef Infra Client is to attempt to communicate with Chef Infra Server. Default value: `false`. + +`syntax_check_cache_path` + +: All files in a cookbook must contain valid Ruby syntax. Use this setting to specify the location in which knife caches information about files that have been checked for valid Ruby syntax. + +`umask` + +: The file mode creation mask, or umask. Default value: `0022`. + +`verbose_logging` + +: Set the log level. Options: `true`, `nil`, and `false`. When this is set to `false`, notifications about individual resources being processed are suppressed (and are output at the `:info` logging level). Setting this to `false` can be useful when a Chef Infra Client is run as a daemon. Default value: `nil`. + +## Examples + +### Using Chef Automate Data Collector + +This example solo.rb file uses the `data_collector` settings to send data to an available Chef Automate system. Since Chef Automate generates a self-signed SSL certificate by default, you will need to add the certificate (located under `/var/opt/delivery/nginx/` on the Chef Automate server) to your `trusted_certs_dir` directory, as seen in this example: + +```ruby +chef_server_url "https://localhost:8989" +log_location STDOUT +node_name "YOUR_NODES_FQDN" +trusted_certs_dir "/etc/chef/trusted_certs" + +data_collector.server_url "https://YOUR_AUTOMATE_FQDN/data-collector/v0" +data_collector.mode :both +data_collector.token = "YOURTOKEN" +``` + +You can run it like this + +```ruby +chef-solo -c solo.rb +``` + +### All Options + +A sample solo.rb file that contains all possible settings (listed alphabetically): + +```ruby +add_formatter :nyan +add_formatter :foo +add_formatter :bar +checksum_path '/var/chef/checksums' +cookbook_path [ + '/var/chef/cookbooks', + '/var/chef/site-cookbooks' + ] +data_bag_path '/var/chef/data_bags' +environment 'production' +environment_path '/var/chef/environments' +file_backup_path '/var/chef/backup' +file_cache_path '/var/chef/cache' +json_attribs nil +lockfile nil +log_level :info +log_location STDOUT +node_name 'mynode.example.com' +recipe_url 'http://path/to/remote/cookbook' +rest_timeout 300 +role_path '/var/chef/roles' +sandbox_path 'path_to_folder' +solo false +syntax_check_cache_path +umask 0022 +verbose_logging nil +``` diff --git a/content/features/chef_solo/ctl_chef_solo.md b/content/features/chef_solo/ctl_chef_solo.md new file mode 100644 index 0000000..337506e --- /dev/null +++ b/content/features/chef_solo/ctl_chef_solo.md @@ -0,0 +1,181 @@ ++++ +title = "chef-solo (executable)" +draft = false + +[menu] + [menu.features] + title = "chef-solo (executable)" + identifier = "features/chef_solo/ctl_chef_solo.md chef-solo Commands" + parent = "features/chef_solo" + weight = 20 ++++ + +{{< readfile file="content/reusable/md/chef_solo_summary.md" >}} + +## Options + +This command has the following syntax: + +```bash +chef-solo OPTION VALUE OPTION VALUE ... +``` + +This command has the following options: + +`-c CONFIG`, `--config CONFIG` + +: The configuration file to use. + +`-d`, `--daemonize` + +: Run the executable as a daemon. This option may not be used in the same command with the `--[no-]fork` option. This option is only available on machines that run in UNIX or Linux environments. For machines that are running Windows that require similar functionality, use the `chef-client::service` recipe in the `chef-client` cookbook: . This will install a Chef Infra Client service under Windows using the Windows Service Wrapper. + +`-E ENVIRONMENT_NAME`, `--environment ENVIRONMENT_NAME` + +: The name of the environment. + +`-f`, `--[no-]fork` + +: Contains Chef Infra Client runs in a secondary process with dedicated RAM. When a Chef Infra Client run is complete, the RAM is returned to the primary process. This option helps ensure that a Chef Infra Client uses a steady amount of RAM over time because the primary process doesn't run recipes. This option also helps prevent memory leaks such as those that can be introduced by the code contained within a poorly designed cookbook. Use `--no-fork` to disable running Chef Infra Client in fork node. Default value: `--fork`. This option may not be used in the same command with the `--daemonize` and `--interval` options. + +`-F FORMAT`, `--format FORMAT` + +: {{< readfile file="content/reusable/md/workstation/ctl_chef_client_options_format.md" >}} + +`--force-formatter` + +: Show formatter output instead of logger output. + +`--force-logger` + +: Show logger output instead of formatter output. + +`-g GROUP`, `--group GROUP` + +: The name of the group that owns a process. This is required when starting any executable as a daemon. + +`-h`, `--help` + +: Show help for the command. + +`-i SECONDS`, `--interval SECONDS` + +: The frequency (in seconds) at which Chef Infra Client runs. When running Chef Infra Client at intervals, apply `--splay` and `--interval` values before a Chef Infra Client run. This option may not be used in the same command with the `--[no-]fork` option. + +`-j PATH`, `--json-attributes PATH` + +: The path to a file that contains JSON data. + + {{< readfile file="content/reusable/md/node_ctl_run_list.md" spaces=4 >}} + + {{< warning >}} + + {{< readfile file="content/reusable/md/node_ctl_attribute.md">}} + + {{< /warning >}} + +`-l LEVEL`, `--log_level LEVEL` + +: The level of logging to be stored in a log file. Possible levels: `auto` (default), `debug`, `error`, `fatal`, `info`, `trace`, or `warn`. Default value: `warn` (when a terminal is available) or `info` (when a terminal isn't available). + +`-L LOGLOCATION`, `--logfile c` + +: The location of the log file. This is recommended when starting any executable as a daemon. + +`--legacy-mode` + +: Cause Chef Infra Client to use the original chef-solo mode instead of chef local mode. This isn't recommended. **Removed in Chef Infra Client 14.** + +`--minimal-ohai` + +: Run the Ohai plugins for name detection and resource/provider selection and no other Ohai plugins. Set to `true` during integration testing to speed up test cycles. + +`--[no-]color` + +: View colored output. Default setting: `--color`. + +`-N NODE_NAME`, `--node-name NODE_NAME` + +: The unique identifier of the node. + +`-o RUN_LIST_ITEM`, `--override-runlist RUN_LIST_ITEM` + +: Replace the current run-list with the specified items. + +`-r RECIPE_URL`, `--recipe-url RECIPE_URL` + +: The URL of the remote cookbook `tar.gz` file that you want to download. + + In Chef Infra Client 14, the short `-r` form will be removed, as it conflicts with the ability to specify a run list. + +`--run-lock-timeout SECONDS` + +: The amount of time (in seconds) to wait for a Chef Infra Client lock file to be deleted. Default value: not set (indefinite). Set to `0` to cause a second Chef Infra Client to exit immediately. + +`-s SECONDS`, `--splay SECONDS` + +: A random number between zero and `splay` that's added to `interval`. Use splay to help balance the load on Chef Infra Server by ensuring that many Chef Infra Client runs aren't occurring at the same interval. When running Chef Infra Client at intervals, apply `--splay` and `--interval` values before a Chef Infra Client run. + +`-u USER`, `--user USER` + +: The user that owns a process. This is required when starting any executable as a daemon. + +`-v`, `--version` + +: The Chef Infra Client version. + +`-W`, `--why-run` + +: Run the executable in why-run mode, which is a type of Chef Infra Client run that does everything except modify the system. Use why-run mode to understand the decisions that Chef Infra Client makes during a run and to learn more about the current and proposed state of the system. + +## Run as Non-root User + +{{< warning >}} + +This configuration for the `chef` user provides root-level access through Chef script files that call system commands with `sudo` privileges. + +Use an alternative approach if your security profile forbids the `chef` user from having built-in root level access. + +{{< /warning >}} + +chef-solo may be run as a non-root user. For example, you can update the `sudoers` file: + +```ruby +# chef-solo privilege specification +chef ALL=(ALL) NOPASSWD: /usr/bin/chef-solo +``` + +where `chef` is the name of the non-root user. This would allow chef-solo to run any command on the node without requiring a password. + +## Examples + +### Run chef-solo using solo.rb settings + +```bash +chef-solo -c ~/chef/solo.rb +``` + +### Use a URL + +```bash +chef-solo -c ~/solo.rb -j ~/node.json -r http://www.example.com/chef-solo.tar.gz +``` + +The tar.gz is archived into the `file_cache_path`, and then extracted to +`cookbooks_path`. + +### Use a directory + +```bash +chef-solo -c ~/solo.rb -j ~/node.json +``` + +chef-solo will look in the `solo.rb` file to determine the directory in which cookbooks are located. + +### Use a URL for cookbook and JSON data + +```bash +chef-solo -c ~/solo.rb -j http://www.example.com/node.json --recipe-url http://www.example.com/chef-solo.tar.gz +``` + +where `--recipe-url` corresponds to `recipe_url` and `-j` corresponds to `json_attribs`, both of which are [configuration options](config_rb_solo) in `solo.rb`. diff --git a/content/features/handlers.md b/content/features/handlers.md new file mode 100644 index 0000000..7751322 --- /dev/null +++ b/content/features/handlers.md @@ -0,0 +1,547 @@ ++++ +title = "About Handlers" +draft = false + +[menu] + [menu.features] + title = "Handlers" + identifier = "features/handlers.md Handlers" + parent = "features" + weight = 40 ++++ + +{{< readfile file="content/reusable/md/handler.md" >}} + +{{< readfile file="content/reusable/md/handler_types.md" >}} + +## Exception/Report Handlers + +{{< readfile file="content/reusable/md/handler_type_exception_report.md" >}} + +### Run from Recipes + +{{< readfile file="content/reusable/md/handler_type_exception_report_run_from_recipe.md" >}} + +### Run from client.rb + +A simple exception or report handler may be installed and configured at run-time. This requires editing of a node's client.rb file to add the appropriate setting and information about that handler to the client.rb or solo.rb files. Depending on the handler type, one (or more) of the following settings must be added: + +`exception_handlers` + +: A list of exception handlers that are available to Chef Infra Client during a Chef Infra Client run. + +`report_handlers` + +: A list of report handlers that are available to Chef Infra Client during a Chef Infra Client run. + +When this approach is used, the client.rb file must also tell Chef Infra Client how to install and run the handler. There is no default install location for handlers. The simplest way to distribute and install them is using RubyGems, though other methods such as GitHub or HTTP will also work. Once the handler is installed on the system, enable it in the client.rb file by requiring it. After the handler is installed, it may require additional configuration. This will vary from handler to handler. If a handler is a simple handler, it may only require the creation of a new instance. For example, if a handler named `MyOrg::EmailMe` is hardcoded for all of the values required to send email, a new instance is required. And then the custom handler must be associated with each of the handler types for which it will run. + +For example: + +```ruby +require '/var/chef/handlers/email_me' # the installation path + +email_handler = MyOrg::EmailMe.new # a simple handler + +start_handlers << email_handler # run at the start of the run +report_handlers << email_handler # run at the end of a successful run +exception_handlers << email_handler # run at the end of a failed run +``` + +## Start Handlers + +{{< readfile file="content/reusable/md/handler_type_start.md" >}} + +### Run from Recipes + +{{< readfile file="content/reusable/md/handler_type_start_run_from_recipe.md" >}} + +### Run from client.rb + +A start handler can be configured in the client.rb file by adding the following setting: + + ++++ + + + + + + + + + + + + +
SettingDescription
start_handlersA list of start handlers that are available to Chef Infra Client at the start of a Chef Infra Client run.
+ +For example, the Reporting start handler adds the following code to the +top of the client.rb file: + +```ruby +begin + require 'chef_reporting' + start_handlers << Chef::Reporting::StartHandler.new() +rescue LoadError + Chef::Log.warn 'Failed to load #{lib}. This should be resolved after a chef run.' +end +``` + +This ensures that when a Chef Infra Client run begins the `chef_reporting` event handler is enabled. The `chef_reporting` event handler is part of a gem named `chef-reporting`. The **chef_gem** resource is used to install this gem: + +```ruby +chef_gem 'chef-reporting' do + action :install +end +``` + +## Event Handlers + +{{< readfile file="content/reusable/md/dsl_handler_summary.md" >}} + +### on Method + +{{< readfile file="content/reusable/md/dsl_handler_method_on.md" >}} + +### Event types + +{{< readfile file="content/reusable/md/dsl_handler_event_types.md" >}} + +### Examples + +The following examples show ways to use the Handler DSL. + +#### Send Email + +{{< readfile file="content/reusable/md/dsl_handler_slide_send_email.md" >}} + +##### Define How Email is Sent + +{{< readfile file="content/reusable/md/dsl_handler_slide_send_email_library.md" >}} + +##### Add the Handler + +{{< readfile file="content/reusable/md/dsl_handler_slide_send_email_handler.md" >}} + +##### Test the Handler + +{{< readfile file="content/reusable/md/dsl_handler_slide_send_email_test.md" >}} + +#### etcd Locks + +{{< readfile file="content/reusable/md/dsl_handler_example_etcd_lock.md" >}} + +#### HipChat Notifications + +{{< readfile file="content/reusable/md/dsl_handler_example_hipchat.md" >}} + +## Handlers and Cookbooks + +The following cookbooks can be used to load handlers during a Chef InfraClient run. + +### chef_handler + +Exception and report handlers can be distributed using the **chef_handler** resource. This resource is included with Chef 14 and above. It can be used to enable custom handlers from within recipes and to include product-specific handlers from cookbooks. + +See the [chef_handler Resource]({{< relref "/resources/bundled/chef_handler">}}) documentation for more information. + +### Chef Infra Client + +Start handlers can be distributed using the **chef-client** cookbook, which will install the handler on the target node during the initial configuration of the node. This ensures that the start handler is always present on the node so that it's available to Chef Infra Client at the start of every run. + +## Custom Handlers + +A custom handler can be created to support any situation. The easiest way to build a custom handler: + +1. Download the **chef_handler** cookbook +2. Create a custom handler +3. Write a recipe using the **chef_handler** resource +4. Add that recipe to a node's run-list, often as the first recipe in + that run-list + +### Syntax + +The syntax for a handler can vary depending on what the situations the handler is being asked to track, for example the handler type being used. All custom exception and report handlers are defined using Ruby and must be a subclass of the `Chef::Handler` class. + +```ruby +require 'chef/log' + +module ModuleName + class HandlerName < Chef::Handler + def report + # Ruby code goes here + end + end +end +``` + +where: + +- `require` ensures that the logging functionality of Chef Infra Client is available to the handler +- `ModuleName` is the name of the module as it exists within the `Chef` library +- `HandlerName` is the name of the handler as it's used in a recipe +- `report` is an interface that's used to define the custom handler + +For example, the following shows a custom handler that sends an email that contains the exception data when a Chef Infra Client run fails: + +```ruby +require 'net/smtp' + +module OrgName + class SendEmail < Chef::Handler + def report + if run_status.failed? + message = "From: sender_name \n" + message << "To: recipient_address \n" + message << "Subject: chef-client Run Failed\n" + message << "Date: #{Time.now.rfc2822}\n\n" + message << "Chef run failed on #{node.name}\n" + message << "#{run_status.formatted_exception}\n" + message << Array(backtrace).join('\n') + Net::SMTP.start('your.smtp.server', 25) do |smtp| + smtp.send_message message, 'sender@example', 'recipient@example' + end + end + end + end +end +``` + +and then is used in a recipe like: + +```ruby +send_email 'blah' do + # recipe code +end +``` + +### report Interface + +The `report` interface is used to define how a handler will behave and is a required part of any custom handler. The syntax for the `report` interface is as follows: + +```ruby +def report + # Ruby code +end +``` + +The Ruby code used to define a custom handler will vary significantly from handler to handler. Chef Infra Client includes two default handlers: `error_report` and `json_file`. Their use of the `report` interface is shown below. + +The [error_report](https://github.com/chef/chef/blob/main/lib/chef/handler/error_report.rb) handler: + +```ruby +require 'chef/handler' +require 'chef/resource/directory' + +class Chef + class Handler + class ErrorReport < ::Chef::Handler + def report + Chef::FileCache.store('failed-run-data.json', Chef::JSONCompat.to_json_pretty(data), 0640) + Chef::Log.fatal("Saving node information to #{Chef::FileCache.load('failed-run-data.json', false)}") + end + end + end +end +``` + +The [json_file](https://github.com/chef/chef/blob/main/lib/chef/handler/json_file.rb) handler: + +```ruby +require 'chef/handler' +require 'chef/resource/directory' + +class Chef + class Handler + class JsonFile < ::Chef::Handler + attr_reader :config + def initialize(config = {}) + @config = config + @config[:path] ||= '/var/chef/reports' + @config + end + + def report + if exception + Chef::Log.error('Creating JSON exception report') + else + Chef::Log.info('Creating JSON run report') + end + build_report_dir + savetime = Time.now.strftime('%Y%m%d%H%M%S') + File.open(File.join(config[:path], 'chef-run-report-#{savetime}.json'), 'w') do |file| + run_data = data + run_data[:start_time] = run_data[:start_time].to_s + run_data[:end_time] = run_data[:end_time].to_s + file.puts Chef::JSONCompat.to_json_pretty(run_data) + end + end + + def build_report_dir + unless File.exist?(config[:path]) + FileUtils.mkdir_p(config[:path]) + File.chmod(00700, config[:path]) + end + end + end + end +end +``` + +### Optional Interfaces + +The following interfaces may be used in a handler in the same way as the `report` interface to override the default handler behavior in Chef Infra Client. That said, the following interfaces aren't typically used in a handler and, for the most part, are completely unnecessary for a handler to work properly and/or as desired. + +#### data + +The `data` method is used to return the Hash representation of the `run_status` object. For example: + +```ruby +def data + @run_status.to_hash +end +``` + +#### run_report_safely + +The `run_report_safely` method is used to run the report handler, rescuing and logging errors that may arise as the handler runs and ensuring that all handlers get a chance to run during a Chef Infra Client run (even if some handlers fail during that run). In general, this method should never be used as an interface in a custom handler unless this default behavior simply must be overridden. + +```ruby +def run_report_safely(run_status) + run_report_unsafe(run_status) +rescue Exception => e + Chef::Log.error('Report handler #{self.class.name} raised #{e.inspect}') + Array(e.backtrace).each { |line| Chef::Log.error(line) } +ensure + @run_status = nil +end +``` + +#### run_report_unsafe + +The `run_report_unsafe` method is used to run the report handler without any error handling. This method should never be used directly in any handler, except during testing of that handler. For example: + +```ruby +def run_report_unsafe(run_status) + @run_status = run_status + report +end +``` + +### run_status Object + +The `run_status` object is initialized by Chef Infra Client before the `report` interface is run for any handler. The `run_status` object keeps track of the status of a Chef Infra Client run and will contain some (or all) of the following properties: + +`all_resources` + +: A list of all resources that are included in the `resource_collection` property for the current Chef Infra Client run. + +`backtrace` + +: A backtrace associated with the uncaught exception data that caused a Chef Infra Client run to fail, if present; `nil` for a successful Chef Infra Client run. + +`elapsed_time` + +: The amount of time between the start (`start_time`) and end (`end_time`) of a Chef Infra Client run. + +`end_time` + +: The time at which a Chef Infra Client run ended. + +`exception` + +: The uncaught exception data which caused a Chef Infra Client run to fail; `nil` for a successful Chef Infra Client run. + +`failed?` + +: Show that a Chef Infra Client run has failed when uncaught exceptions were raised during a Chef Infra Client run. An exception handler runs when the `failed?` indicator is `true`. + +`node` + +: The node on which a Chef Infra Client run occurred. + +`run_context` + +: An instance of the `Chef::RunContext` object; used by Chef Infra Client to track the context of the run; provides access to the `cookbook_collection`, `resource_collection`, and `definitions` properties. + +`start_time` + +: The time at which a Chef Infra Client run started. + +`success?` + +: Show that a Chef Infra Client run succeeded when uncaught exceptions weren't raised during a Chef Infra Client run. A report handler runs when the `success?` indicator is `true`. + +`updated_resources` + +: A list of resources that were marked as updated as a result of a Chef Infra Client run. + +{{< note >}} + +These properties aren't always available. For example, a start handler runs at the beginning of Chef Infra Client run, which means that properties like `end_time` and `elapsed_time` are still unknown and will be unavailable to the `run_status` object. + +{{< /note >}} + +## Examples + +The following sections show examples of handlers. + +### Cookbook versions + +Community member `juliandunn` created a custom [report handler that logs all of the cookbooks and cookbook versions](https://github.com/juliandunn/cookbook_versions_handler) that were used during a Chef Infra Client run, and then reports after the run is complete. This handler requires the **chef_handler** resource (which is available from the **chef_handler** cookbook). + +#### cookbook_versions.rb + +The following custom handler defines how cookbooks and cookbook versions that are used during a Chef Infra Client run will be compiled into a report using the `Chef::Log` class in Chef Infra Client: + +```ruby +require 'chef/log' + +module Opscode + class CookbookVersionsHandler < Chef::Handler + def report + cookbooks = run_context.cookbook_collection + Chef::Log.info('Cookbooks and versions run: #{cookbooks.keys.map {|x| cookbooks[x].name.to_s + ' ' + cookbooks[x].version} }') + end + end +end +``` + +#### default.rb + +The following recipe is added to the run-list for every node on which a list of cookbooks and versions will be generated as report output after every Chef Infra Client run. + +```ruby +include_recipe 'chef_handler' + +cookbook_file "#{node['chef_handler']['handler_path']}/cookbook_versions.rb" do + source 'cookbook_versions.rb' + owner 'root' + group 'root' + mode '0755' + action :create +end + +chef_handler 'Opscode::CookbookVersionsHandler' do + source "#{node['chef_handler']['handler_path']}/cookbook_versions.rb" + supports :report => true + action :enable +end +``` + +This recipe will generate report output similar to the following: + +```ruby +[2013-11-26T03:11:06+00:00] INFO: Chef Run complete in 0.300029878 seconds +[2013-11-26T03:11:06+00:00] INFO: Running report handlers +[2013-11-26T03:11:06+00:00] INFO: Cookbooks and versions run: ["chef_handler 1.1.4", "cookbook_versions_handler 1.0.0"] +[2013-11-26T03:11:06+00:00] INFO: Report handlers complete +``` + +### Reporting + +Start handler functionality was added when Chef started building add-ons for Chef Infra Server. The Reporting add-on is designed to create reporting data based on a Chef Infra Client run. And since Reporting needs to be able to collect data for the entire Chef Infra Client run, Reporting needs to be enabled before anything else happens at the start of a Chef Infra Client run. + +{{< note >}} + +The start handler used by the Reporting add-on for Chef Infra Server is always installed using the **chef-client** cookbook. + +{{< /note >}} + +#### start_handler.rb + +The following code shows the start handler used by the Reporting add-in for Chef Infra Server: + +```ruby +require 'chef/handler' +require 'chef/rest' +require 'chef/version_constraint' + +class Chef + class Reporting + class StartHandler < ::Chef::Handler + attr_reader :config + + def initialize(config = {}) + @config = config + end + + def report + version_checker = Chef::VersionConstraint.new('< 11.6.0') + if version_checker.include?(Chef::VERSION) + Chef::Log.info('Enabling backported resource reporting Handler') + rest = Chef::REST.new(Chef::Config[:chef_server_url], @run_status.node.name, Chef::Config[:client_key]) + resource_reporter = Chef::Reporting::ResourceReporter.new(rest) + @run_status.events.register(resource_reporter) + + resource_reporter.run_started(@run_status) + else + Chef::Log.debug('Chef Version already has new Resource Reporter - skipping startup of backport version') + end + end + end + end +end +``` + +### json_file Handler + +The [json_file](https://github.com/chef/chef/blob/main/lib/chef/handler/json_file.rb) handler is available from the **chef_handler** cookbook and can be used with exceptions and reports. It serializes run status data to a JSON file. This handler may be enabled in one of the following ways. + +By adding the following lines of Ruby code to either the client.rb file or the solo.rb file, depending on how Chef Infra Client is being run: + +```ruby +require 'chef/handler/json_file' +report_handlers << Chef::Handler::JsonFile.new(:path => '/var/chef/reports') +exception_handlers << Chef::Handler::JsonFile.new(:path => '/var/chef/reports') +``` + +By using the **chef_handler** resource in a recipe, similar to the +following: + +```ruby +chef_handler 'Chef::Handler::JsonFile' do + source 'chef/handler/json_file' + arguments :path => '/var/chef/reports' + action :enable +end +``` + +After it has run, the run status data can be loaded and inspected using Interactive Ruby (IRb): + +```ruby +irb(main):002:0> require 'json' => true +irb(main):003:0> require 'chef' => true +irb(main):004:0> r = JSON.parse(IO.read('/var/chef/reports/chef-run-report-20110322060731.json')) => ... output truncated +irb(main):005:0> r.keys => ['end_time', 'node', 'updated_resources', 'exception', 'all_resources', 'success', 'elapsed_time', 'start_time', 'backtrace'] +irb(main):006:0> r['elapsed_time'] => 0.00246 +``` + +### error_report Handler + +The [error_report](https://github.com/chef/chef/blob/main/lib/chef/handler/error_report.rb) handler is built into Chef Infra Client and can be used for both exceptions and reports. It serializes error report data to a JSON file. This handler may be enabled in one of the following ways. + +By adding the following lines of Ruby code to either the client.rb file or the solo.rb file, depending on how Chef Infra Client is being run: + +```ruby +require 'chef/handler/error_report' +report_handlers << Chef::Handler::ErrorReport.new() +exception_handlers << Chef::Handler::ErrorReport.new() +``` + +By using the [chef_handler](/resources/bundled/chef_handler/) resource in a recipe, similar to the following: + +```ruby +chef_handler 'Chef::Handler::ErrorReport' do + source 'chef/handler/error_report' + action :enable +end +``` + +### Community Handlers + +{{< readfile file="content/reusable/md/handler_community_handlers.md" >}} diff --git a/content/features/ohai/_index.md b/content/features/ohai/_index.md new file mode 100644 index 0000000..6d30a5b --- /dev/null +++ b/content/features/ohai/_index.md @@ -0,0 +1,285 @@ ++++ +title = "About Ohai" +draft = false +linkTitle = "Ohai" + +[menu] + [menu.features] + title = "About Ohai" + identifier = "features/ohai/ohai.md About Ohai" + parent = "features/ohai" + weight = 10 ++++ + +{{< readfile file="content/reusable/md/ohai_summary.md" >}} + +Ohai collects data for many platforms, including AIX, macOS, Linux, FreeBSD, Solaris, and any Windows operating systems. + +See the [Chef Infra Client release notes](https://docs.chef.io/release_notes/client/) for the latest information on Ohai. + +## Automatic Attributes + +{{< note >}} + +{{< readfile file="content/reusable/md/notes_see_attributes_overview.md" >}} + +{{< /note >}} + +{{< readfile file="content/reusable/md/ohai_automatic_attribute.md" >}} + +### Get a list of automatic attributes for a node + +{{< readfile file="content/reusable/md/ohai_attribute_list.md" >}} + +### Attributes Blocklist + +{{< warning >}} + +{{< readfile file="content/reusable/md/node_attribute_blocklist_warning.md" >}} + +{{< /warning >}} + +{{< readfile file="content/reusable/md/node_attribute_blocklist.md" >}} + +### Attribute Allowlist + +{{< warning >}} + +{{< readfile file="content/reusable/md/node_attribute_allowlist_warning.md" >}} + +{{< /warning >}} + +## Default Plugins + +The following list shows the type of plugins that are included with Ohai. See the `ohai/lib/ohai/plugins` directory in the version of Ohai installed on your system for the full list: + +### General Purpose Plugins + +```ruby +azure.rb +c.rb +chef.rb +cloud.rb +command.rb +cpu.rb +digital_ocean.rb +dmi.rb +docker.rb +ec2.rb +elixir.rb +erlang.rb +eucalyptus.rb +filesystem.rb +freebsd +gce.rb +go.rb +groovy.rb +haskell.rb +hostname.rb +init_package.rb +java.rb +joyent.rb +kernel.rb +keys.rb +languages.rb +libvirt.rb +linode.rb +lua.rb +mono.rb +network.rb +nodejs.rb +ohai_time.rb +ohai.rb +memory.rb +network.rb +platform.rb +openstack.rb +os.rb +packages.rb +perl.rb +php.rb +platform.rb +powershell.rb +ps.rb +python.rb +rackspace.rb +root_group.rb +ruby.rb +rust.rb +scala.rb +scaleway.rb +shard.rb +shells.rb +softlayer.rb +ssh_host_key.rb +timezone.rb +uptime.rb +virtualbox.rb +vmware.rb +zpools.rb +``` + +### Platform Specific Plugins + +```ruby +aix + kernel.rb + memory.rb + network.rb + platform.rb + uptime.rb + virtualization.rb +bsd + virtualization.rb +darwin + cpu.rb + filesystem.rb + hardware.rb + memory.rb + network.rb + platform.rb + system_profiler.rb + virtualization.rb +dragonflybsd + cpu.rb + memory.rb + network.rb + os.rb + platform.rb +freebsd + cpu.rb + memory.rb + network.rb + os.rb + platform.rb +linux + block_device.rb + cpu.rb + filesystem.rb + fips.rb + hostnamectl.rb + lsb.rb + machineid.rb + mdadm.rb + memory.rb + network.rb + platform.rb + sessions.rb + virtualization.rb +netbsd + cpu.rb + memory.rb + network.rb + platform.rb +openbsd + cpu.rb + memory.rb + network.rb + platform.rb +solaris2 + cpu.rb + dmi.rb + filesystem.rb + memory.rb + network.rb + platform.rb + virtualization.rb +windows + cpu.rb + drivers.rb + filesystem.rb + fips.rb + memory.rb + network.rb + platform.rb + system_enclosure.rb + virtualization.rb +``` + +## Optional Plugins + +Ohai ships several optional plugins that you can enable in the [client.rb configuration file](/install/config_rb_client/). + + `:Grub2` +: Information from the Linux Grub2 bootloader + + `:IPC` +: SysV IPC shmem information (New in Chef Infra Client 16) + + `:Interupts` +: Data from /proc/interrupts and /proc/irq (New in Chef Infra Client 16) + + `:Lspci` +: PCI device information on Linux hosts. + + `:Lsscsi` +: SCSI device information on Linux hosts. + + `:Passwd` +: User and Group information. This plugin can result in large node sizes if a system connects to Active Directory or LDAP. + + `:Sessions` +: Sessions data from loginctl on Linux hosts. + +`:Sysctl` + +: All sysctl values on Linux hosts. + +### Enabling Optional Plugins + +Optional plugins can be enabled in the [client.rb configuration file](/install/config_rb_client/): + +```ruby +ohai.optional_plugins = [ + :Sessions, + :Lspci, +] +``` + +{{< note >}} + +The Ohai optional_plugins config array must contain an array of plugin names as Symbols not Strings. + +{{< /note >}} + +## Ohai Settings in client.rb + +{{< readfile file="content/reusable/md/config_rb_ohai.md" >}} + +{{< readfile file="content/reusable/md/config_rb_ohai_settings.md" >}} + +## Custom Plugins + +Custom Ohai plugins can be written to collect additional information from systems as necessary. See the [Ohai Custom Plugins](/extension_apis/custom_plugins/) docs for more information. + +## Hints + +Ohai hints are used to tell Ohai something about the system that it's running on that it would not be able to discover itself. An Ohai hint exists if a JSON file exists in the hint directory with the same name as the hint. For example, calling `hint?('antarctica')` in an Ohai plugin would return an empty hash if the file `antarctica.json` existed in the hints directory, and return nil if the file doesn't exist. + +If the hint file contains JSON content, it will be returned as a hash from the call to `hint?`. + +```json +{ + "snow": true, + "penguins": "many" +} +``` + +```ruby +antarctica_hint = hint?('antarctica') +if antarctica_hint['snow'] + "There are #{antarctica_hint['penguins']} penguins here." +else + 'There is no snow here, and penguins like snow.' +end +``` + +Hint files are located in the `/etc/chef/ohai/hints/` directory by default. Use the `Ohai.config[:hints_path]` setting in the [client.rb configuration file](/install/config_rb_client/) to customize this location. + +## `ohai` Resource + +Chef Infra Client includes an `ohai` resource that allows you to reload the Ohai data on a node. This allows recipes or resources that change system attributes (like a recipe that adds a user) to refer to those attributes later on during a Chef Infra Client run. See the [ohai resource](/resources/bundled/ohai) for complete usage information. + +## ohai Command Line Tool + +Ohai can be run on the command line outside of the Chef Infra Client run. See [Ohai (executable)](ctl_ohai) for more information. diff --git a/content/features/ohai/ctl_ohai.md b/content/features/ohai/ctl_ohai.md new file mode 100644 index 0000000..00ddc51 --- /dev/null +++ b/content/features/ohai/ctl_ohai.md @@ -0,0 +1,128 @@ ++++ +title = "ohai (executable)" +draft = false + +[menu] + [menu.features] + title = "ohai (executable)" + identifier = "features/ohai/ctl_ohai.md ohai Commands" + parent = "features/ohai" + weight = 20 ++++ + + + +`ohai` is the command-line interface for Ohai, a tool that's used to +detect attributes on a node, and then provide these attributes to Chef +Infra Client at the start of every Chef Infra Client run. + +## Options + +This command has the following syntax: + +```bash +ohai OPTION +``` + +This tool has the following options: + +`ATTRIBUTE_NAME ATTRIBUTE NAME ...` + +: Use to have Ohai show only output for named attributes. To address attributes deeper in the tree, use a `/` delimiter between each level. For example: `memory/free`. + +`-c CONFIG`, `--config CONFIG` + +: The path to a configuration file to use. For example: + `/etc/ohai/config.rb`. + +`-d DIRECTORY`, `--directory DIRECTORY` + +: The directory in which additional Ohai plugins are located. For + example: `/my/extra/plugins`. + +`-h`, `--help` + +: Show help for the command. + +`-l LEVEL`, `--log_level LEVEL` + +: The level of logging to be stored in a log file. + +`-L LOGLOCATION`, `--logfile LOGLOCATION` + +: The location of the log file. + +`-v`, `--version` + +: The version of Ohai. + +## Examples + +The following examples show how to use the Ohai command-line tool: + +### Query for a specific attribute + +Pass an attribute as an argument to `ohai` to get the value of that attribute. For example: + +```bash +ohai os +``` + +This fetches the value of Chef Infra's node data at `node['os']` and returns something like: + +```json +[ + "linux" +] +``` + +To query for an attribute deeper in the node attribute tree, use a forward slash (`/`) as a delimiter between each level. +For example, to query for free memory: + +```bash +ohai memory/free +``` + +This returns the value of `node['memory']['free']`. + +### Run a plugin independently of a Chef Infra Client run + +An Ohai plugin can be run independently of a Chef Infra Client run. +First, ensure that the plugin is located in the `/plugins` directory and +then use the `-f` option when running Ohai from the command line. For +example, a plugin named `sl_installed` may look like the following: + +```ruby +Ohai.plugin(:Sl) do + provides "sl" + + collect_data(:default) do + sl Mash.new + + if ::File.exist?("/usr/games/sl") + sl[:installed] = true + else + sl[:installed] = false + end + + # sl[:installed] = ::File.exist?("/usr/games/sl") + + end +end +``` + +To run that plugin from the command line, use the following command: + +```bash +ohai --directory /path/to/directory sl +``` + +The command returns something similar to: + +```json +{ + "sl": { + "installed": true + } +} +``` diff --git a/content/infra_language/_index.md b/content/infra_language/_index.md new file mode 100644 index 0000000..60a7910 --- /dev/null +++ b/content/infra_language/_index.md @@ -0,0 +1,27 @@ ++++ +title = "About the Chef Infra Language" +draft = false +list_pages = true + +[menu] + [menu.infra_language] + title = "Language Overview" + identifier = "infra_language/ Language Overview" + parent = "infra_language" + weight = 10 ++++ + +{{< readfile file="content/reusable/md/infra_lang_summary.md" >}} + +{{< readfile file="content/reusable/md/infra_lang_ruby.md" >}} + +## Resources + +Resources are the cornerstone of the Chef Infra Language. Resources define the desired state of an object on a system. A resource can be as simple as a directory or as complex or a complete security policy. Chef Infra Client ships with over 150 resources for configuring components such as packages, files, directories, or firewalls. For more information on resources in Chef Infra Client including a complete list of those included out of the box see [Resources](/resources). + +## Helpers Methods + +The Chef Infra Language provides support for using attributes, data bags (and +encrypted data), and search results in a recipe, as well as four helper +methods that can be used to check for a node's platform from the recipe +to ensure that specific actions are taken for specific platforms. diff --git a/content/infra_language/checking_architectures.md b/content/infra_language/checking_architectures.md new file mode 100644 index 0000000..d1fcd76 --- /dev/null +++ b/content/infra_language/checking_architectures.md @@ -0,0 +1,63 @@ ++++ +title = "Chef Infra Language: Checking Architectures" +linkTitle = "Checking Architectures" +draft = false + +[menu] + [menu.infra_language] + title = "Checking Architectures" + identifier = "infra_language/checking_architectures.md Checking Architectures" + parent = "infra_language" ++++ + + + +Chef Infra Client 15.5 and later includes helper methods for checking the processor architecture of systems. These methods can be used in attribute files, recipes, and resources. + +## _32_bit? + +Determines if the current architecture is 32-bit. + +## _64_bit? + +Determines if the current architecture is 64-bit. + +## arm? + +Determines if the current architecture is arm. + +## armhf? + +Determines if the current architecture is 32-bit ARM hard float. + +## i386? + +Determines if the current architecture is i386. + +## intel? + +Determines if the current architecture is Intel. + +## powerpc? + +Determines if the current architecture is PowerPC. + +## ppc64? + +Determines if the current architecture is PowerPC 64bit Big Endian. + +## ppc64le? + +Determines if the current architecture is PowerPC 64bit Little Endian. + +## s390? + +Determines if the current architecture is s390. + +## s390x? + +Determines if the current architecture is s390x. + +## sparc? + +Determines if the current architecture is SPARC. diff --git a/content/infra_language/checking_clouds.md b/content/infra_language/checking_clouds.md new file mode 100644 index 0000000..7927e1d --- /dev/null +++ b/content/infra_language/checking_clouds.md @@ -0,0 +1,53 @@ ++++ +title = "Chef Infra Language: Checking Clouds" +linkTitle = "Checking Clouds" +draft = false + +[menu] + [menu.infra_language] + title = "Checking Clouds" + identifier = "infra_language/checking_clouds.md Checking Clouds" + parent = "infra_language" ++++ + +Chef Infra Client 15.8 and later includes helper methods for checking if a node is running in a public or private cloud. + +## cloud? + +Determine if the current node is running a known public or private cloud. + +## ec2? + +Determine if the current node is running in AWS EC2. + +## gce? + +Determine if the current node is running in Google Compute Engine (GCE) + +## rackspace? + +Determine if the current node is running in Rackspace. + +## eucalyptus? + +Determine if the current node is running in Eucalyptus. + +## linode? + +Determine if the current node is running in Linode. + +## openstack? + +Determine if the current node is running in OpenStack. + +## azure? + +Determine if the current node is running in Microsoft Azure. + +## digital_ocean? + +Determine if the current node is running in DigitalOcean. + +## softlayer? + +Determine if the current node is running in SoftLayer (IBM Cloud). diff --git a/content/infra_language/checking_hypervisors.md b/content/infra_language/checking_hypervisors.md new file mode 100644 index 0000000..24b105f --- /dev/null +++ b/content/infra_language/checking_hypervisors.md @@ -0,0 +1,100 @@ ++++ +title = "Chef Infra Language: Checking Hypervisors" +draft = false + +[menu] + [menu.infra_language] + title = "Checking Hypervisors" + identifier = "infra_language/checking_hypervisors.md Checking Hypervisors" + parent = "infra_language" ++++ + +Chef Infra Client 15.8 and later includes helper methods for checking if a hypervisor host or guest. + +## guest? + +Determine if the current node is running under any virtualization environment. + +## hypervisor? + +Determine if the current node supports running guests under any virtualization environment. + +## physical? + +Determine if the current node isn't running under any virtualization environment (bare-metal or hypervisor on metal). + +## hyperv? + +Determine if the current node is a Hyper-V guest. + +## kvm? + +Determine if the current node is a KVM guest. + +## kvm_host? + +Determine if the current node is a KVM host. + +## lxc? + +Determine if the current node is a LXC-based container. + +## lxc_host? + +Determine if the current node is a LXC host. + +## parallels? + +Determine if the current node is running under Parallels Desktop. + +## parallels_host? + +Determine if the current node is a Parallels Desktop host. + +## vbox? + +Determine if the current node is a VirtualBox guest. + +## vbox_host? + +Determine if the current node is a VirtualBox host. + +## vmware? + +Determine if the current node is a VMWare guest. + +## vmware_host? + +Determine if the current node is VMware host. + +## vmware_desktop? + +Determine if the current node is a guest on VMware desktop products (Fusion, Player, Workstation). + +## vmware_vsphere? + +Determine if the current node is a guest on VMware vSphere (aka ESXi). + +## openvz? + +Determine if the current node is an openvz guest. + +## openvz_host? + +Determine if the current node is an openvz host. + +## vagrant? + +Determine if the current node is running as a vagrant guest. + +## vagrant_key? + +Check if the `vagrant` key exists on the +node+ object. Note: This key is no longer populated by vagrant, but it's kept around for legacy purposes. + +## vagrant_domain? + +Check if `vagrantup.com` is included in the node's domain. + +## vagrant_user? + +Check if the system contains a `vagrant` user. diff --git a/content/infra_language/checking_platforms.md b/content/infra_language/checking_platforms.md new file mode 100644 index 0000000..71b669c --- /dev/null +++ b/content/infra_language/checking_platforms.md @@ -0,0 +1,468 @@ ++++ +title = "Chef Infra Language: Checking Platforms" +draft = false + +[menu] + [menu.infra_language] + title = "Checking Platforms" + identifier = "infra_language/checking_platforms.md Checking Platforms" + parent = "infra_language" ++++ + + + +## platform? + +Use the `platform?` helper method to ensure that certain actions are run for specific platforms. The `platform?` method will return true if one of the listed parameters matches the `node['platform']` attribute that's detected by [Ohai](/features/ohai) during every Chef Infra Client run. + +The syntax for the `platform?` method is as follows: + +```ruby +platform?('parameter', 'parameter') +``` + +where: + +- `parameter` is a comma-separated list, each specifying a platform, such as Red Hat, CentOS, or Fedora +- `platform?` method is typically used with an `if`, `elsif`, or `case` statement that contains Ruby code that's specific for the platform, if detected + +### Platform values + + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterPlatforms
aixIBM AIX
alibabalinuxAlibaba Cloud Linux
almalinuxAlmaLinux
amazonAmazon Linux
archArch Linux
clearosClearOS
cloudlinuxCloud Linux OS
cumulusNVIDIA Cumulus Linux
debianDebian GNU/Linux
fedoraFedora
freebsdFreeBSD
gentooGentoo Linux
linuxmintLinux Mint
mac_os_xmacOS
netbsdNetBSD
openbsdOpenBSD
openindianaOpenIndiana
opensuseleapopenSUSE leap
pidoraPidora
raspbianRaspberry Pi OS
redhatRed Hat Enterprise Linux
rockyRocky Linux
sangomaSangoma Linux
scientificScientific Linux
solaris2Oracle Solaris
suseSUSE Linux Enterprise Server.
ubuntuUbuntu Linux
virtuozzoVirtuozzo
windowsWindows
xenserverCitrix XenServer
+ +### Examples + +#### Installing the cron package on Debian systems + +```ruby +package 'cron' if platform?('debian') +``` + +#### Deleting a file on Red Hat and Debian systems + +```ruby +if platform?('redhat', 'debian') + file '/etc/some_config' do + action :remove + end +end +``` + +#### Installing the correct Firefox package + +The following example shows how an if statement can be used with the +`platform?` method in the Chef Infra Language to run code specific to Microsoft +Windows. The code is defined using the **ruby_block** resource: + +```ruby +if platform?('windows') + chocolatey_package 'firefox' +else + package 'firefox' +end +``` + +## platform_family? + +Use the `platform_family?` method to ensure that certain actions are run for specific platform families. The `platform_family?` method will return true if one of the listed parameters matches the `node['platform_family']` attribute that are detected by [Ohai](/features/ohai) during every Chef Infra Client run. + +The syntax for the `platform_family?` method is as follows: + +```ruby +platform_family?('parameter', 'parameter') +``` + +where: + +- `'parameter'` is a comma-separated list, each specifying a platform family, such as Debian, or Red Hat Enterprise Linux +- `platform_family?` method is typically used with an `if`, `elsif`, or `case` statement that contains Ruby code that's specific for the platform family, if detected + +### platform_family Values + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterPlatforms
aixaix platform.
alpinealpine platform.
amazonamazon platform.
archarch, manjaro, and antergos platforms.
debiandebian, ubuntu, linuxmint, raspbian, cumulus, kali, sangoma, and pop platforms.
fedorafedora, pidora, and arista_eos platforms
freebsdfreebsd platform
gentoogentoo platform
mac_os_xmac_os_x platform
netbsdnetbsd platform
openbsdopenbsd platform
openindianaopenindiana platform
rhelredhat, centos, oracle, almalinux, rocky, scientific, xenserver, clearos, bigip, parallels, xcp, virtuozzo, alibabalinux, and ibm_powerkvm platforms
solaris2solaris2 platform
suseopensuse_leap, suse, and sled platforms
windowswindows platform
+ +### Examples + +For example: + +```ruby +platform_family?('gentoo') +``` + +or: + +```ruby +platform_family?('slackware', 'suse', 'arch') +``` + +#### Use a Specific Binary For a Specific Platform + +The following is an example of using the `platform_family?` method in +the Chef Infra Language to create a variable that can be used with other +resources in the same recipe. In this example, `platform_family?` is +being used to ensure that a specific binary is used for a specific +platform before using the **remote_file** resource to download a file +from a remote location, and then using the **execute** resource to +install that file by running a command. + +```ruby +if platform_family?('rhel') + pip_binary = '/usr/bin/pip' +else + pip_binary = '/usr/local/bin/pip' +end + +remote_file "#{Chef::Config[:file_cache_path]}/distribute_setup.py" do + source 'http://python-distribute.org/distribute_setup.py' + mode '0755' + not_if { ::File.exist?(pip_binary) } +end + +execute 'install-pip' do + cwd Chef::Config[:file_cache_path] + command <<-EOF + # command for installing Python goes here + EOF + not_if { ::File.exist?(pip_binary) } +end +``` + +where a command for installing Python might look something like: + +```ruby +#{node['python']['binary']} distribute_setup.py +#{::File.dirname(pip_binary)}/easy_install pip +``` + +## value_for_platform + +Use the `value_for_platform` method in a recipe to select a value based on the `node['platform']` and `node['platform_version']` attributes. These values are detected by Ohai during every Chef Infra Client run. + +The syntax for the `value_for_platform` method is as follows: + +```ruby +value_for_platform( ['platform', ...] => { 'version' => 'value' } ) +``` + +where: + +- `'platform', ...` is a comma-separated list of platforms, such as Red Hat, openSUSE, or Fedora +- `version` specifies the version of that platform +- Version constraints---`>`, `<`, `>=`, `<=`, `~>`---may be used with `version`; an exception is raised if two version constraints match; an exact match will always take precedence over a match made from a version constraint +- `value` specifies the value that will be used if the node's platform matches the `value_for_platform` method + +When each value only has a single platform, use the following syntax: + +```ruby +value_for_platform( + 'platform' => { 'version' => 'value' }, + 'platform' => { 'version' => 'value' }, + 'platform' => 'value' +) +``` + +When each value has more than one platform, the syntax changes to: + +```ruby +value_for_platform( + ['platform', 'platform', ... ] => { + 'version' => 'value' + }, +) +``` + +### Operators + +{{< readfile file="content/reusable/md/cookbooks_version_constraints_operators.md" >}} + +### Examples + +The following example will set `package_name` to `httpd` for the Red Hat platform and to `apache2` for the Debian platform: + +```ruby +package_name = value_for_platform( + ['centos', 'redhat', 'suse', 'fedora' ] => { + 'default' => 'httpd' + }, + ['ubuntu', 'debian'] => { + 'default' => 'apache2' + } +) +``` + +The following example will set `package` to `apache-couchdb` for OpenBSD platforms, `dev-db/couchdb` for Gentoo platforms, and `couchdb` for all other platforms: + +```ruby +package = value_for_platform( + 'openbsd' => { 'default' => 'apache-couchdb' }, + 'gentoo' => { 'default' => 'dev-db/couchdb' }, + 'default' => 'couchdb' +) +``` + +The following example shows using version constraints to specify a value based on the version: + +```ruby +value_for_platform( + 'os1' => { '< 1.0' => 'less than 1.0', + '~> 2.0' => 'version 2.x', + '>= 3.0' => 'greater than or equal to version 3.0', + '3.0.1' => '3.0.1 will always use this value' } +) +``` + +## value_for_platform_family + +Use the `value_for_platform_family` method in a recipe to select a value based on the `node['platform_family']` attribute. This value is detected by Ohai during every Chef Infra Client run. + +The syntax for the `value_for_platform_family` method is as follows: + +```ruby +value_for_platform_family( 'platform_family' => 'value', ... ) +``` + +where: + +- `'platform_family' => 'value', ...` is a comma-separated list of platforms, such as Fedora, openSUSE, or Red Hat Enterprise Linux +- `value` specifies the value that will be used if the node's platform family matches the `value_for_platform_family` method + +When each value only has a single platform, use the following syntax: + +```ruby +value_for_platform_family( + 'platform_family' => 'value', + 'platform_family' => 'value', + 'platform_family' => 'value' +) +``` + +When each value has more than one platform, the syntax changes to: + +```ruby +value_for_platform_family( + ['platform_family', 'platform_family', 'platform_family', 'platform_family' ] => 'value', + ['platform_family', 'platform_family'] => 'value', + 'default' => 'value' +) +``` + +The following example will set `package` to `httpd-devel` for the Red Hat Enterprise Linux, Fedora, and openSUSE platforms and to `apache2-dev` for the Debian platform: + +```ruby +package = value_for_platform_family( + ['rhel', 'fedora', 'suse'] => 'httpd-devel', + 'debian' => 'apache2-dev' +) +``` diff --git a/content/infra_language/cookbook_execution.md b/content/infra_language/cookbook_execution.md new file mode 100644 index 0000000..73d6bd6 --- /dev/null +++ b/content/infra_language/cookbook_execution.md @@ -0,0 +1,160 @@ ++++ +title = "Chef Infra Language: Cookbook Execution" +draft = false + +[menu] + [menu.infra_language] + title = "Cookbook Execution" + identifier = "infra_language/cookbook_execution.md Cookbook Execution" + parent = "infra_language" ++++ + +The Chef Infra Language includes helper methods for gathering information on the execution of the Chef Infra Client recipe and resource code. This information can be used in recipes and resources to take specific actions. + +## Chef Infra Client State + +These helpers allow you to understand the state of the node that Chef Infra Client is executing on. + +### node + +Use the `node` method, often referred to as the node object, to access data collected on the system through [Ohai](/features/ohai) as well as node attributes set in cookbooks or Policyfiles. + +The syntax for the `node` method is as follows: + +```ruby +node['specific_attribute'] +``` + +### cookbook_name + +Use the `cookbook_name` method to return the name of a cookbook. + +The syntax for the `cookbook_name` method is as follows: + +```ruby +cookbook_name +``` + +This method is often used as part of a log entry. For example: + +```ruby +Chef::Log.info("I am a message from the #{recipe_name} recipe in the #{cookbook_name} cookbook.") +``` + +### recipe_name + +Use the `recipe_name` method to return the name of a recipe. + +The syntax for the `recipe_name` method is as follows: + +```ruby +recipe_name +``` + +This method is often used as part of a log entry. For example: + +```ruby +Chef::Log.info("I am a message from the #{recipe_name} recipe in the #{cookbook_name} cookbook.") +``` + +### resources + +Use the `resources` method to look up a resource in the resource collection. The `resources` method returns the value for the resource that it finds in the resource collection. The preferred syntax for the `resources` method is as follows: + +```ruby +resources('resource_type[resource_name]') +``` + +but the following syntax can also be used: + +```ruby +resources(resource_type: 'resource_name') +``` + +where in either approach `resource_type` is the name of a resource and `resource_name` is the name of a resource that can be configured by Chef Infra Client. + +The `resources` method can be used to modify a resource later on in a recipe. For example: + +```ruby +file '/etc/hosts' do + content '127.0.0.1 localhost.localdomain localhost' +end +``` + +and then later in the same recipe, or elsewhere: + +```ruby +f = resources('file[/etc/hosts]') +f.mode '0644' +``` + +where `file` is the type of resource, `/etc/hosts` is the name, and `f.mode` is used to set the `mode` property on the **file** resource. + +### attribute? + +Use the `attribute?` method to ensure that certain actions only execute in the presence of a particular node attribute. The `attribute?` method will return true if one of the listed node attributes matches a node attribute that's detected by Ohai during every Chef Infra Client run. + +The syntax for the `attribute?` method is as follows: + +```ruby +attribute?('name_of_attribute') +``` + +For example: + +```ruby +if node.attribute?('ipaddress') + # the node has an IP address +end +``` + +### reboot_pending? + +Use the `reboot_pending?` method to test if a node needs a reboot, or is expected to reboot. `reboot_pending?` returns `true` when the node needs a reboot. + +The syntax for the `reboot_pending?` method is as follows: + +```ruby +reboot_pending? +``` + +## Executing Code + +These helpers allow you to include recipes and impact how resources run on the system. + +### include_recipe + +{{< readfile file="content/reusable/md/cookbooks_recipe_include_in_recipe.md" >}} + +### with_run_context + +Use the `with_run_context` method to define a block that has a pointer to a location in the `run_context` hierarchy. Resources in recipes always run at the root of the `run_context` hierarchy, whereas custom resources and notification blocks always build a child `run_context` which contains their sub-resources. + +The syntax for the `with_run_context` method is as follows: + +```ruby +with_run_context :type do + # some arbitrary pure Ruby stuff goes here +end +``` + +where `:type` may be one of the following: + +- `:root` runs the block as part of the root `run_context` hierarchy +- `:parent` runs the block as part of the parent process in the `run_context` hierarchy + +For example: + +```ruby +action :run do + with_run_context :root do + edit_resource(:my_thing, "accumulated state") do + action :nothing + my_array_property << accumulate_some_stuff + end + end + log "kick it off" do + notifies :run, "my_thing[accumulated state]", :delayed + end +end +``` diff --git a/content/infra_language/editing_resources.md b/content/infra_language/editing_resources.md new file mode 100644 index 0000000..5092c4e --- /dev/null +++ b/content/infra_language/editing_resources.md @@ -0,0 +1,207 @@ ++++ +title = "Chef Infra Language: Editing Resources" +draft = false + +[menu] + [menu.infra_language] + title = "Editing Resources" + identifier = "infra_language/editing_resources.md Editing Resources" + parent = "infra_language" ++++ + +## declare_resource + +Use the `declare_resource` method to instantiate a resource and then add it to the resource collection. + +The syntax for the `declare_resource` method is as follows: + +```ruby +declare_resource(:resource_type, 'resource_name', resource_attrs_block) +``` + +where: + +- `:resource_type` is the resource type, such as `:file` (for the **file** resource) or `:template` (for the **template** resource). Any resource available to Chef may be declared. +- `resource_name` the property that's the default name of the resource, typically the string that appears in the `resource 'name' do` block of a resource (but not always); see the Syntax section for the resource to be declared to verify the default name property. +- `resource_attrs_block` is a block in which properties of the instantiated resource are declared. + +For example: + +```ruby +declare_resource(:file, '/x/y.txy', caller[0]) do + action :delete +end +``` + +is equivalent to: + +```ruby +file '/x/y.txt' do + action :delete +end +``` + +## delete_resource + +Use the `delete_resource` method to find a resource in the resource collection, and then delete it. + +The syntax for the `delete_resource` method is as follows: + +```ruby +delete_resource(:resource_type, 'resource_name') +``` + +where: + +- `:resource_type` is the resource type, such as `:file` (for the **file** resource) or `:template` (for the **template** resource). Any resource available to Chef may be declared. +- `resource_name` the property that's the default name of the resource, typically the string that appears in the `resource 'name' do` block of a resource (but not always); see the Syntax section for the resource to be declared to verify the default name property. + +For example: + +```ruby +delete_resource(:template, '/x/y.erb') +``` + +## delete_resource! + +Use the `delete_resource!` method to find a resource in the resource +collection, and then delete it. If the resource isn't found, an +exception is returned. + +The syntax for the `delete_resource!` method is as follows: + +```ruby +delete_resource!(:resource_type, 'resource_name') +``` + +where: + +- `:resource_type` is the resource type, such as `:file` (for the **file** resource) or `:template` (for the **template** resource). Any resource available to Chef Infra may be declared. +- `resource_name` the property that's the default name of the resource, typically the string that appears in the `resource 'name' do` block of a resource (but not always); see the Syntax section for the resource to be declared to verify the default name property. + +For example: + +```ruby +delete_resource!(:file, '/x/file.txt') +``` + +## edit_resource + +Use the `edit_resource` method to: + +- Find a resource in the resource collection, and then edit it. +- Define a resource block. If a resource block with the same name exists in the resource collection, it will be updated with the contents of the resource block defined by the `edit_resource` method. If a resource block doesn't exist in the resource collection, it will be created. + +The syntax for the `edit_resource` method is as follows: + +```ruby +edit_resource(:resource_type, 'resource_name', resource_attrs_block) +``` + +where: + +- `:resource_type` is the resource type, such as `:file` (for the **file** resource) or `:template` (for the **template** resource). Any resource available to Chef may be declared. +- `resource_name` the property that's the default name of the resource, typically the string that appears in the `resource 'name' do` block of a resource (but not always); see the Syntax section for the resource to be declared to verify the default name property. +- `resource_attrs_block` is a block in which properties of the instantiated resource are declared. + +For example: + +```ruby +edit_resource(:template, '/x/y.txy') do + cookbook 'cookbook_name' +end +``` + +and a resource block: + +```ruby +edit_resource(:template, '/etc/aliases') do + source 'aliases.erb' + cookbook 'aliases' + variables({:aliases => {} }) + notifies :run, 'execute[newaliases]' +end +``` + +## edit_resource! + +Use the `edit_resource!` method to: + +- Find a resource in the resource collection, and then edit it. +- Define a resource block. If a resource with the same name exists in the resource collection, its properties will be updated with the contents of the resource block defined by the `edit_resource` method. + +In both cases, if the resource isn't found, an exception is returned. + +The syntax for the `edit_resource!` method is as follows: + +```ruby +edit_resource!(:resource_type, 'resource_name') +``` + +where: + +- `:resource_type` is the resource type, such as `:file` (for the **file** resource) or `:template` (for the **template** resource). Any resource available to Chef may be declared. +- `resource_name` the property that's the default name of the resource, typically the string that appears in the `resource 'name' do` block of a resource (but not always); see the Syntax section for the resource to be declared to verify the default name property. +- `resource_attrs_block` is a block in which properties of the instantiated resource are declared. + +For example: + +```ruby +edit_resource!(:file, '/x/y.rst') +``` + +## find_resource + +Use the `find_resource` method to: + +- Find a resource in the resource collection. +- Define a resource block. If a resource block with the same name exists in the resource collection, it will be returned. If a resource block doesn't exist in the resource collection, it will be created. + +The syntax for the `find_resource` method is as follows: + +```ruby +find_resource(:resource_type, 'resource_name') +``` + +where: + +- `:resource_type` is the resource type, such as `:file` (for the **file** resource) or `:template` (for the **template** resource). Any resource available to Chef may be declared. +- `resource_name` the property that's the default name of the resource, typically the string that appears in the `resource 'name' do` block of a resource (but not always); see the Syntax section for the resource to be declared to verify the default name property. + +For example: + +```ruby +find_resource(:template, '/x/y.txy') +``` + +and a resource block: + +```ruby +find_resource(:template, '/etc/seapower') do + source 'seapower.erb' + cookbook 'seapower' + variables({:seapower => {} }) + notifies :run, 'execute[newseapower]' +end +``` + +## find_resource! + +Use the `find_resource!` method to find a resource in the resource collection. If the resource isn't found, an exception is returned. + +The syntax for the `find_resource!` method is as follows: + +```ruby +find_resource!(:resource_type, 'resource_name') +``` + +where: + +- `:resource_type` is the resource type, such as `:file` (for the **file** resource) or `:template` (for the **template** resource). Any resource available to Chef may be declared. +- `resource_name` the property that's the default name of the resource, typically the string that appears in the `resource 'name' do` block of a resource (but not always); see the Syntax section for the resource to be declared to verify the default name property. + +For example: + +```ruby +find_resource!(:template, '/x/y.erb') +``` diff --git a/content/infra_language/logging.md b/content/infra_language/logging.md new file mode 100644 index 0000000..c16f958 --- /dev/null +++ b/content/infra_language/logging.md @@ -0,0 +1,20 @@ ++++ +title = "Chef Infra Language: Logging" +draft = false + +[menu] + [menu.infra_language] + title = "Logging" + identifier = "infra_language/logging.md Logging" + parent = "infra_language" ++++ + +## Log Entries + +{{< readfile file="content/reusable/md/ruby_style_basics_chef_log.md" >}} + +### Examples + +{{< readfile file="content/reusable/md/ruby_class_chef_log_fatal.md" >}} + +{{< readfile file="content/reusable/md/ruby_class_chef_log_multiple.md" >}} diff --git a/content/infra_language/node_tags.md b/content/infra_language/node_tags.md new file mode 100644 index 0000000..a88ff65 --- /dev/null +++ b/content/infra_language/node_tags.md @@ -0,0 +1,14 @@ ++++ +title = "Chef Infra Language: Node Tags" +draft = false + +[menu] + [menu.infra_language] + title = "Node Tags" + identifier = "infra_language/node_tags.md Node Tags" + parent = "infra_language" ++++ + +{{< readfile file="content/reusable/md/chef_tags.md" >}} + +{{< readfile file="content/reusable/md/cookbooks_recipe_tags.md" >}} diff --git a/content/infra_language/reading_data_bags.md b/content/infra_language/reading_data_bags.md new file mode 100644 index 0000000..4655008 --- /dev/null +++ b/content/infra_language/reading_data_bags.md @@ -0,0 +1,80 @@ ++++ +title = "Chef Infra Language: Reading Data Bags" +draft = false + +[menu] + [menu.infra_language] + title = "Reading Data Bags" + identifier = "infra_language/reading_data_bags.md Reading Data Bags" + parent = "infra_language" ++++ + +## data_bag + +{{< readfile file="content/reusable/md/data_bag.md" >}} + +Use the `data_bag` method to get a list of the contents of a data bag. + +The syntax for the `data_bag` method is as follows: + +```ruby +data_bag(bag_name) +``` + +### Examples + +The following example shows how the `data_bag` method can be used in a recipe. + +#### Get a data bag, and then iterate through each data bag item + +{{< readfile file="content/reusable/md/infra_lang_data_bag.md" >}} + +## data_bag_item + +{{< readfile file="content/reusable/md/data_bag.md" >}} + +The `data_bag_item` method can be used in a recipe to get the contents of a data bag item. + +The syntax for the `data_bag_item` method is as follows: + +```ruby +data_bag_item(bag_name, item, secret) +``` + +where `secret` is the secret used to load an encrypted data bag. If `secret` isn't specified, Chef Infra Client looks for a secret at the path specified by the `encrypted_data_bag_secret` setting in the `client.rb` file. + +### Examples + +The following examples show how the `data_bag_item` method can be used in a recipe. + +#### Get a data bag, and then iterate through each data bag item + +{{< readfile file="content/reusable/md/infra_lang_data_bag.md" >}} + +#### Use the contents of a data bag in a recipe + +The following example shows how to use the `data_bag` and `data_bag_item` methods in a recipe, also using a data bag named `sea-power`): + +```ruby +package 'sea-power' do + action :install +end + +directory node['sea-power']['base_path'] do + # attributes for owner, group, mode +end + +gale_warnings = data_bag('sea-power').map do |viking_north| + data_bag_item('sea-power', viking_north)['source'] +end + +template '/etc/seattle/power.list' do + source 'seattle-power.erb' + # attributes for owner, group, mode + variables( + :base_path => node['sea-power']['base_path'], + # more variables + :repo_location => gale_warnings + ) +end +``` diff --git a/content/infra_language/registry_keys.md b/content/infra_language/registry_keys.md new file mode 100644 index 0000000..a75b62e --- /dev/null +++ b/content/infra_language/registry_keys.md @@ -0,0 +1,92 @@ ++++ +title = "Chef Infra Language: Reading Registry Keys" +draft = false + +[menu] + [menu.infra_language] + title = "Reading Registry Keys" + identifier = "infra_language/registry_key.md Reading Registry Keys" + parent = "infra_language" ++++ + +{{< readfile file="content/reusable/md/infra_lang_method_windows_methods.md" >}} + +{{< note >}} + +The recommended order in which registry key-specific methods should be +used within a recipe is: `key_exists?`, `value_exists?`, `data_exists?`, +`get_values`, `has_subkeys?`, and then `get_subkeys`. + +{{< /note >}} + +## registry_data_exists? + +{{< readfile file="content/reusable/md/infra_lang_method_registry_data_exists.md" >}} + +{{< note >}} + +{{< readfile file="content/reusable/md/notes_registry_key_not_if_only_if.md" >}} + +{{< /note >}} + +{{< readfile file="content/reusable/md/infra_lang_method_registry_data_exists_syntax.md" >}} + +## registry_get_subkeys + +{{< readfile file="content/reusable/md/infra_lang_method_registry_get_subkeys.md" >}} + +{{< note >}} + +{{< readfile file="content/reusable/md/notes_registry_key_not_if_only_if.md" >}} + +{{< /note >}} + +{{< readfile file="content/reusable/md/infra_lang_method_registry_get_subkeys_syntax.md" >}} + +## registry_get_values + +{{< readfile file="content/reusable/md/infra_lang_method_registry_get_values.md" >}} + +{{< note >}} + +{{< readfile file="content/reusable/md/notes_registry_key_not_if_only_if.md" >}} + +{{< /note >}} + +{{< readfile file="content/reusable/md/infra_lang_method_registry_get_values_syntax.md" >}} + +## registry_has_subkeys? + +{{< readfile file="content/reusable/md/infra_lang_method_registry_has_subkeys.md" >}} + +{{< note >}} + +{{< readfile file="content/reusable/md/notes_registry_key_not_if_only_if.md" >}} + +{{< /note >}} + +{{< readfile file="content/reusable/md/infra_lang_method_registry_has_subkeys_syntax.md" >}} + +## registry_key_exists? + +{{< readfile file="content/reusable/md/infra_lang_method_registry_key_exists.md" >}} + +{{< note >}} + +{{< readfile file="content/reusable/md/notes_registry_key_not_if_only_if.md" >}} + +{{< /note >}} + +{{< readfile file="content/reusable/md/infra_lang_method_registry_key_exists_syntax.md" >}} + +## registry_value_exists? + +{{< readfile file="content/reusable/md/infra_lang_method_registry_value_exists.md" >}} + +{{< note >}} + +{{< readfile file="content/reusable/md/notes_registry_key_not_if_only_if.md" >}} + +{{< /note >}} + +{{< readfile file="content/reusable/md/infra_lang_method_registry_value_exists_syntax.md" >}} diff --git a/content/infra_language/ruby.md b/content/infra_language/ruby.md new file mode 100644 index 0000000..e6a25e0 --- /dev/null +++ b/content/infra_language/ruby.md @@ -0,0 +1,689 @@ ++++ +title = "Ruby Guide" +draft = false + +[menu] + [menu.infra_language] + title = "Ruby Guide" + identifier = "infra_language/ruby.md Ruby Guide" + parent = "infra_language" ++++ + +{{< readfile file="content/reusable/md/ruby_summary.md" >}} + +## Ruby basics + +This section covers the basics of Ruby. + +### Verify syntax + +Many people who are new to Ruby often find that it doesn't take +long to get up to speed with the basics. For example, it's useful to +know how to check the syntax of a Ruby file, such as the contents of a +cookbook named `my_cookbook.rb`: + +```bash +ruby -c my_cookbook_file.rb +``` + +to return: + +```bash +Syntax OK +``` + +### Comments + +Use a comment to explain code that exists in a cookbook or recipe. +Anything after a `#` is a comment. + +```ruby +# This is a comment. +``` + +### Local variables + +Assign a local variable: + +```ruby +x = 1 +``` + +### Math + +Do some basic arithmetic: + +```ruby +1 + 2 # => 3 +2 * 7 # => 14 +5 / 2 # => 2 (because both arguments are whole numbers) +5 / 2.0 # => 2.5 (because one of the numbers had a decimal place) +1 + (2 * 3) # => 7 (you can use parentheses to group expressions) +``` + +### Strings + +Work with strings: + +```ruby +'single quoted' # => "single quoted" +"double quoted" # => "double quoted" +'It\'s alive!' # => "It's alive!" (the \ is an escape character) +'1 + 2 = 5' # => "1 + 2 = 5" (numbers surrounded by quotes behave like strings) +``` + +Convert a string to uppercase or lowercase. For example, a hostname +named "Foo": + +```ruby +node['hostname'].downcase # => "foo" +node['hostname'].upcase # => "FOO" +``` + +#### Ruby in strings + +Embed Ruby in a string: + +```ruby +x = 'Bob' +"Hi, #{x}" # => "Hi, Bob" +'Hello, #{x}' # => "Hello, \#{x}" Notice that single quotes don't work with #{} +``` + +#### Escape character + +Use the backslash character (`\`) as an escape character when quotes +must appear within strings. However, you don't need to escape single +quotes inside double quotes. For example: + +```ruby +'It\'s alive!' # => "It's alive!" +"Won\'t you read Grant\'s book?" # => "won't you read Grant's book?" +``` + +#### Interpolation + +When strings have quotes within quotes, use double quotes (`" "`) on the +outer quotes, and then single quotes (`' '`) for the inner quotes. For +example: + +```ruby +Chef::Log.info("Loaded from aws[#{aws['id']}]") +``` + +```ruby +"node['mysql']['secretpath']" +``` + +```ruby +"#{ENV['HOME']}/chef.txt" +``` + +```ruby +antarctica_hint = hint?('antarctica') +if antarctica_hint['snow'] + "There are #{antarctica_hint['penguins']} penguins here." +else + 'There is no snow here, and penguins like snow.' +end +``` + +### Truths + +Work with basic truths: + +```ruby +true # => true +false # => false +nil # => nil +0 # => true ( the only false values in Ruby are false + # and nil; in other words: if it exists in Ruby, + # even if it exists as zero, then it's true.) +1 == 1 # => true ( == tests for equality ) +1 == true # => false ( == tests for equality ) +``` + +#### Untruths + +Work with basic untruths (`!` means not!): + +```ruby +!true # => false +!false # => true +!nil # => true +1 != 2 # => true (1 isn't equal to 2) +1 != 1 # => false (1 isn't equal to itself) +``` + +#### Convert to boolean + +Convert a value to either `true` or `false` using the double negation operator (`!!`). +The first `!` converts the value to its opposite boolean, and the second `!` converts it back, resulting in the boolean representation of the original value: + +```ruby +!!true # => true +!!false # => false +!!nil # => false (nil evaluates to false) +!!0 # => true (zero evaluates to true) +``` + +### Arrays + +Create lists using arrays: + +```ruby +x = ['a', 'b', 'c'] # => ["a", "b", "c"] +x[0] # => "a" (zero is the first index) +x.first # => "a" (see?) +x.last # => "c" +x + ['d'] # => ["a", "b", "c", "d"] +x # => ["a", "b", "c"] ( x is unchanged) +x = x + ['d'] # => ["a", "b", "c", "d"] +x # => ["a", "b", "c", "d"] +``` + +#### Whitespace Arrays + +The `%w` syntax is a Ruby shortcut for creating an array without +requiring quotes and commas around the elements. + +For example: + +```ruby +if %w(debian ubuntu).include?(node['platform']) + # do debian/ubuntu things with the Ruby array %w() shortcut +end +``` + +{{< readfile file="content/reusable/md/ruby_style_patterns_string_quoting_vs_whitespace_array.md" >}} + +##### Example + +WiX includes several tools -- such as `candle` (preprocesses and +compiles source files into object files), `light` (links and binds +object files to an installer database), and `heat` (harvests files from +various input formats). The following example uses a whitespace array +and the Chef InSpec `file` audit resource to verify if these three tools +are present: + +```ruby +%w( + candle.exe + heat.exe + light.exe +).each do |utility| + describe file("C:/wix/#{utility}") do + it { should be_file } + end +end +``` + +### Hash + +A Hash is a list with keys and values. Sometimes hashes don't have a set +order: + +```ruby +h = { + 'first_name' => 'Bob', + 'last_name' => 'Jones', +} +``` + +And sometimes they do. For example, first name then last name: + +```ruby +h.keys # => ["first_name", "last_name"] +h['first_name'] # => "Bob" +h['last_name'] # => "Jones" +h['age'] = 23 +h.keys # => ["first_name", "age", "last_name"] +h.values # => ["Jones", "Bob", 23] +``` + +### Regular Expressions + +Use Perl-style regular expressions: + +```ruby +'I believe' =~ /I/ # => 0 (matches at the first character) +'I believe' =~ /lie/ # => 4 (matches at the 5th character) +'I am human' =~ /bacon/ # => nil (no match - bacon comes from pigs) +'I am human' !~ /bacon/ # => true (correct, no bacon here) +/give me a ([0-9]+)/ =~ 'give me a 7' # => 0 (matched) +``` + +### Statements + +Use conditions! For example, an `if` statement + +```ruby +if false + # this won't happen +elsif nil + # this won't either +else + # code here will run though +end +``` + +or a `case` statement: + +```ruby +x = 'dog' +case x +when 'fish' + # this won't happen +when 'dog', 'cat', 'monkey' + # this will run +else + # the else is an optional catch-all +end +``` + +#### if + +An `if` statement can be used to specify part of a recipe to be used +when certain conditions are met. `else` and `elsif` statements can be +used to handle situations where either the initial condition isn't met +or when there are other possible conditions that can be met. Since this +behavior is 100% Ruby, do this in a recipe the same way here as anywhere +else. + +For example, using an `if` statement with the `platform` node attribute: + +```ruby +if node['platform'] == 'ubuntu' + # do ubuntu things +end +``` + +##### if modifier + +`if` can be used as a modifier that executes the left side of an expression +if the right side of the expression is true. The `if` modifier expression must +be a single line, and `else` and `elsif` statements aren't supported. + +In the following example, the `do_ubuntu_thing` function will execute if the platform on a node is Ubuntu. + +```ruby +do_ubuntu_thing if platform?('ubuntu') +``` + +#### case + +A `case` statement can be used to handle a situation where there are a +lot of conditions. Use the `when` statement for each condition, as many +as are required. + +For example, using a `case` statement with the `platform` node +attribute: + +```ruby +case node['platform'] +when 'debian', 'ubuntu' + # do debian/ubuntu things +when 'redhat', 'centos', 'fedora' + # do redhat/centos/fedora things +end +``` + +For example, using a `case` statement with the `platform_family` node +attribute: + +```ruby +case node['platform_family'] +when 'debian' + # do things on debian-ish platforms (debian, ubuntu, linuxmint) +when 'rhel' + # do things on RHEL platforms (redhat, centos, scientific, etc) +end +``` + +### Call a Method + +Call a method on something with `.method_name()`: + +```ruby +x = 'My String' +x.split(' ') # => ["My", "String"] +x.split(' ').join(', ') # => "My, String" +``` + +### Define a Method + +Define a method (or a function, if you like): + +```ruby +def do_something_useless(first_argument, second_argument) + puts "You gave me #{first_argument} and #{second_argument}" +end + +do_something_useless('apple', 'banana') +# => "You gave me apple and banana" +do_something_useless 1, 2 +# => "You gave me 1 and 2" +# see how the parentheses are optional if there's no confusion about what to do +``` + +### Ruby Class + +Use the Ruby `File` class in a recipe. Because Chef has the **file** +resource, use `File` to use the Ruby `File` class. For example: + +```ruby +execute 'apt-get-update' do + command 'apt-get update' + ignore_failure true + not_if { ::File.exist?('/var/lib/apt/periodic/update-success-stamp') } +end +``` + +### Include a Class + +Use `:include` to include another Ruby class. For example: + +```ruby +::Chef::DSL::Recipe.include MyCookbook::Helpers +``` + +In non-Chef Ruby, the syntax is `include` (without the `:` prefix), but +without the `:` prefix Chef Infra Client will try to find a provider +named `include`. Using the `:` prefix tells Chef Infra Client to look +for the specified class that follows. + +### Include a Parameter + +The `include?` method can be used to ensure that a specific parameter is +included before an action is taken. For example, using the `include?` +method to find a specific parameter: + +```ruby +if %w(debian ubuntu).include?(node['platform']) + # do debian/ubuntu things +end +``` + +or: + +```ruby +if %w(rhel).include?(node['platform_family']) + # do RHEL things +end +``` + +## Patterns to follow + +This section covers best practices for cookbook and recipe authoring. + +### Git etiquette + +Although not strictly a Chef style thing, please always ensure your +`user.name` and `user.email` are set properly in your `.gitconfig` file. + +- `user.name` should be your given name (for example, "Julian Dunn") +- `user.email` should be an actual, working e-mail address + +This will prevent commit log entries similar to +`"guestuser "`, which are unhelpful. + +### Use of hyphens + +{{< readfile file="content/reusable/md/ruby_style_patterns_hyphens.md" >}} + +### Cookbook naming + +Use a short organizational prefix for application cookbooks that are +part of your organization. For example, if your organization is named +SecondMarket, use `sm` as a prefix: `sm_postgresql` or `sm_httpd`. + +### Cookbook versioning + +- Use semantic versioning when numbering cookbooks. +- Only upload stable cookbooks from the main or default branch. +- Only upload unstable cookbooks from a development branch. Merge to main and bump the version when stable. +- Always update CHANGELOG.md with any changes, with the JIRA ticket and a brief description. + +### Naming + +Name things uniformly for their system and component. For example: + +- attributes: `node['foo']['bar']` +- recipe: `foo::bar` +- role: `foo-bar` +- directories: `foo/bar` (if specific to component), `foo` (if not). + For example: `/var/log/foo/bar`. + +Name attributes after the recipe in which they're primarily used. for example +`node['postgresql']['server']`. + +### Parameter order + +Follow this order for information in each resource declaration: + +- Source +- Cookbook +- Resource ownership +- Permissions +- Notifications +- Action + +For example: + +```ruby +template '/tmp/foobar.txt' do + source 'foobar.txt.erb' + owner 'someuser' + group 'somegroup' + mode '0644' + variables( + foo: 'bar' + ) + notifies :reload, 'service[whatever]' + action :create +end +``` + +### File modes + +Always specify the file mode with a quoted 3 to 5 character string that +defines the octal mode: + +```ruby +mode '755' +``` + +```ruby +mode '0755' +``` + +Wrong: + +```ruby +mode 755 +``` + +### Specify resource action? + +A resource declaration doesn't require the action to be specified +because Chef Infra Client will apply the default action for a resource +automatically if it's not specified within the resource block. For +example: + +```ruby +package 'monit' +``` + +will install the `monit` package because the `:install` action is the +default action for the **package** resource. + +However, if readability of code is desired, such as ensuring that a +reader understands what the default action is for a custom resource or +stating the action for a resource whose default may not be immediately +obvious to the reader, specifying the default action is recommended: + +```ruby +ohai 'apache_modules' do + action :reload +end +``` + +### String quoting + +Use single-quoted strings in all situations where the string doesn't +need interpolation. + +#### Whitespace arrays + +{{< readfile file="content/reusable/md/ruby_style_patterns_string_quoting_vs_whitespace_array.md" >}} + +### Recipes + +A recipe should be clean and well-commented. For example: + +```ruby +########### +# variables +########### + +connection_info = { + host: '127.0.0.1', + port: '3306', + username: 'root', + password: 'm3y3sqlr00t', +} + +################# +# Mysql resources +################# + +mysql_service 'default' do + port '3306' + initial_root_password 'm3y3sqlr00t' + action [:create, :start] +end + +mysql_database 'wordpress_demo' do + connection connection_info + action :create +end + +mysql_database_user 'wordpress_user' do + connection connection_info + database_name 'wordpress_demo' + password 'w0rdpr3ssdem0' + privileges [:create, :delete, :select, :update, :insert] + action :grant +end + +################## +# Apache resources +################## + +httpd_service 'default' do + listen_ports %w(80) + mpm 'prefork' + action [:create, :start] +end + +httpd_module 'php' do + notifies :restart, 'httpd_service[default]' + action :create +end + +############### +# Php resources +############### + +package 'php-gd' do + action :install +end + +package 'php-mysql' do + action :install +end + +directory '/etc/php.d' do + action :create +end + +template '/etc/php.d/mysql.ini' do + source 'mysql.ini.erb' + action :create +end + +httpd_config 'php' do + source 'php.conf.erb' + notifies :restart, 'httpd_service[default]' + action :create +end + +##################### +# wordpress resources +##################### + +directory '/srv/wordpress_demo' do + user 'apache' + recursive true + action :create +end + +tar_extract 'https://wordpress.org/wordpress-4.1.tar.gz' do + target_dir '/srv/wordpress_demo' + tar_flags ['--strip-components 1'] + user 'apache' + creates '/srv/wordpress_demo/index.php' + action :extract +end + +directory '/srv/wordpress_demo/wp-content' do + user 'apache' + action :create +end + +httpd_config 'wordpress' do + source 'wordpress.conf.erb' + variables( + servername: 'wordpress', + server_aliases: %w(computers.biz www.computers.biz), + document_root: '/srv/wordpress_demo' + ) + notifies :restart, 'httpd_service[default]' + action :create +end + +template '/srv/wordpress_demo/wp-config.php' do + source 'wp-config.php.erb' + owner 'apache' + variables( + db_name: 'wordpress_demo', + db_user: 'wordpress_user', + db_password: 'w0rdpr3ssdem0', + db_host: '127.0.0.1', + db_prefix: 'wp_', + db_charset: 'utf8', + auth_key: 'You should probably use randomly', + secure_auth_key: 'generated strings. These can be hard', + logged_in_key: 'coded, pulled from encrypted databags,', + nonce_key: 'or a ruby function that accessed an', + auth_salt: 'arbitrary data source, such as a password', + secure_auth_salt: 'vault. Node attributes could work', + logged_in_salt: 'as well, but you take special care', + nonce_salt: 'so they're not saved to your chef-server.', + allow_multisite: 'false' + ) + action :create +end +``` + +## Cookstyle linting + +Chef Workstation includes Cookstyle for linting the Ruby-specific and +Chef-specific portions of your cookbook code. All cookbooks should pass +Cookstyle rules before being uploaded. + +```bash +cookstyle cookbook-name +``` + +This command should return `no offenses detected`. diff --git a/content/infra_language/search.md b/content/infra_language/search.md new file mode 100644 index 0000000..c36a319 --- /dev/null +++ b/content/infra_language/search.md @@ -0,0 +1,147 @@ ++++ +title = "Chef Infra Language: Search" +draft = false + +[menu] + [menu.infra_language] + title = "Search" + identifier = "infra_language/search.md Search" + parent = "infra_language" ++++ + +## search + +{{< readfile file="content/reusable/md/search.md" >}} + +Use the `search` method to perform a search query against Chef Infra Server from within a recipe. + +The syntax for the `search` method is as follows: + +```ruby +search(:index, 'query') +``` + +where: + +- `:index` is of name of the index on Chef Infra Server against which the search query will run: `:client`, `:data_bag_name`, `:environment`, `:node`, and `:role` +- `'query'` is a valid search query against an object on Chef Infra Server (see below for more information about how to build the query) + +For example, using the results of a search query within a variable: + +```ruby +webservers = search(:node, 'role:webserver') +``` + +and then using the results of that query to populate a template: + +```ruby +template '/tmp/list_of_webservers' do + source 'list_of_webservers.erb' + variables(:webservers => webservers) +end +``` + +### :filter_result + +{{< readfile file="content/reusable/md/infra_lang_method_search_filter_result.md" >}} + +### Query Syntax + +{{< readfile file="content/reusable/md/search_query_syntax.md" >}} + +#### Keys + +{{< readfile file="content/reusable/md/search_key.md" >}} + +#### Nested Fields + +{{< readfile file="content/reusable/md/search_key_nested.md" >}} + +#### Patterns + +{{< readfile file="content/reusable/md/search_pattern.md" >}} + +#### Exact Match + +{{< readfile file="content/reusable/md/search_pattern_exact.md" >}} + +#### Wildcard Match + +{{< readfile file="content/reusable/md/search_pattern_wildcard.md" >}} + +#### Range Match + +{{< readfile file="content/reusable/md/search_pattern_range.md" >}} + +#### Fuzzy Match + +{{< readfile file="content/reusable/md/search_pattern_fuzzy.md" >}} + +#### Operators + +{{< readfile file="content/reusable/md/search_boolean_operators.md" >}} + +#### Special Characters + +{{< readfile file="content/reusable/md/search_special_characters.md" >}} + +### Examples + +The following examples show how the `search` method can be used in a recipe. + +#### Use the search helper to find users + +The following example shows how to use the `search` method in the Recipe +DSL to search for users: + +```ruby +# the following code sample comes from the openvpn cookbook: https://github.com/chef-cookbooks/openvpn + +search("users", "*:*") do |u| + execute "generate-openvpn-#{u['id']}" do + command "./pkitool #{u['id']}" + cwd '/etc/openvpn/easy-rsa' + environment( + 'EASY_RSA' => '/etc/openvpn/easy-rsa', + 'KEY_CONFIG' => '/etc/openvpn/easy-rsa/openssl.cnf', + 'KEY_DIR' => node['openvpn']['key_dir'], + 'CA_EXPIRE' => node['openvpn']['key']['ca_expire'].to_s, + 'KEY_EXPIRE' => node['openvpn']['key']['expire'].to_s, + 'KEY_SIZE' => node['openvpn']['key']['size'].to_s, + 'KEY_COUNTRY' => node['openvpn']['key']['country'], + 'KEY_PROVINCE' => node['openvpn']['key']['province'], + 'KEY_CITY' => node['openvpn']['key']['city'], + 'KEY_ORG' => node['openvpn']['key']['org'], + 'KEY_EMAIL' => node['openvpn']['key']['email'] + ) + not_if { File.exist?("#{node['openvpn']['key_dir']}/#{u['id']}.crt") } + end + + %w{ conf ovpn }.each do |ext| + template "#{node['openvpn']['key_dir']}/#{u['id']}.#{ext}" do + source 'client.conf.erb' + variables :username => u['id'] + end + end + + execute "create-openvpn-tar-#{u['id']}" do + cwd node['openvpn']['key_dir'] + command <<-EOH + tar zcf #{u['id']}.tar.gz \ + ca.crt #{u['id']}.crt #{u['id']}.key \ + #{u['id']}.conf #{u['id']}.ovpn \ + EOH + not_if { File.exist?("#{node['openvpn']['key_dir']}/#{u['id']}.tar.gz") } + end +end +``` + +where + +- the search will use both of the **execute** resources, unless the + condition specified by the `not_if` commands are met +- the `environments` property in the first **execute** resource is + being used to define values that appear as variables in the OpenVPN + configuration +- the **template** resource tells Chef Infra Client which template to + use diff --git a/content/infra_language/secrets.md b/content/infra_language/secrets.md new file mode 100644 index 0000000..f26588f --- /dev/null +++ b/content/infra_language/secrets.md @@ -0,0 +1,223 @@ ++++ +title = "Chef Infra Language: Secrets" +draft = false + +[menu] + [menu.infra_language] + title = "Secrets Management Integrations" + identifier = "infra_language/secrets.md Secrets Management Integrations" + parent = "infra_language" ++++ + +The Secrets Management Integration helper is a beta feature starting in Chef Infra Client 17.5 and became a fully supported feature in Chef Infra Client 18. +This helper allows you to access secrets from the following secrets management systems within your Infra recipes or resources: + +- AWS Secrets Manager +- Akeyless Vault +- Azure Key Vault +- HashiCorp Vault + +## Syntax + +Use the following syntax to fetch secrets: + +```ruby +secret(name: '', version: '', service: , config: {key: value}) +``` + + + +Replace the following: + +`` +: The identifier or name for this secret. + +`` +: The secret version. If a service supports versions and you don't provide a version, the Secrets Management Integration helper fetches the latest version. + + Secret versions supported with: + + - AWS Secrets Manager + - Azure Key Vault + +`` +: The secret manager. + + Allowed values: + + - `:akeyless_vault` + - `:aws_secrets_manager` + - `:azure_key_vault` + - `:hashi_vault` + +`config` +: Use `config` to set key/value settings passed to a secrets manager. For example, to set the AWS region that a secret is stored in with AWS Secrets Manager, add `config: {region: 'us-west-2'}`. + + + +### Set defaults + +You can set a default service and service configuration and then the Secrets Management Integration helper will use those settings every time you request a secret. +This is useful if you want to request more than one secret from the same service. + +Use the `default_secret_service` and `default_secret_config` to define a default service and service configuration: + +```ruby +default_secret_service() +default_secret_config(key: "value") + +value1 = secret(name: "") +value2 = secret(name: "") +value3 = secret(name: "") +``` + +Or wrap your secret definitions using `with_secret_service` and `with_secret_config`: + +```ruby +with_secret_service() do + with_secret_config(key: "value") do + value1 = secret(name: "") + value2 = secret(name: "") + value3 = secret(name: "") + end +end +``` + +Define a default secret service and then fetch secrets with different configs: + +```ruby +default_secret_service() + +with_secret_config(key: "") do + secret_1 = secret(name: "") + secret_2 = secret(name: "") +end + +with_secret_config(key: "") do + secret_3 = secret(name: "") + secret_4 = secret(name: "") +end +``` + +## Examples + +### Akeyless Vault + +Fetch secrets from Akeyless Vault using the access key and access ID: + +```ruby +secret(name: '', + service: :akeyless_vault, + config: { + access_key: '', + access_id: '' + }) +``` + +### AWS Secrets Manager + +Fetch a secret from AWS Secrets Manager: + +```ruby +secret(name: '', service: :aws_secrets_manager) +``` + +Specify an AWS region: + +```ruby +secret(name: '', service: :aws_secrets_manager, config: { region: '' }) +``` + +### Azure Key Vault + +Fetch secrets from Azure Key Vault: + +```ruby +secret(name: '', service: :azure_key_vault) +``` + +Specify the vault name in the config: + +```ruby +secret(name: '', service: :azure_key_vault, config: { vault: '' }) +``` + +Fetch a specific version of an Azure Key Vault secret: + +```ruby +secret(name: '', version: 'v1', service: :azure_key_vault) +``` + +### HashiCorp Vault + +Fetch secrets from HashiCorp Vault using AWS IAM: + +```ruby +secret(name: '', + service: :hashi_vault, + config: { + vault_addr: 'vault.example.com', + role_name: '' + }) +``` + +Fetch secrets from HashiCorp Vault using tokens: + +```ruby +secret(name: '', + service: :hashi_vault, + config: { + vault_addr: 'vault.example.com', + auth_method: :token, + token: '' + }) +``` + +Fetch secrets from HashiCorp Vault using AppRole ID and an associated AppRole Secret ID: + +```ruby +secret(name: '', + service: :hashi_vault, + config: { + vault_addr: 'vault.example.com', + auth_method: :approle, + approle_id: "", + approle_secret_id: "" + }) +``` + +Fetch secrets using a token and an AppRole name creates a Secret ID associated with that AppRole: + +```ruby +secret(name: '', + service: :hashi_vault, + config: { + vault_addr: 'vault.example.com', + auth_method: :approle, + approle_name: "", + token: '' + }) +``` + +### Fetch secrets in cookbooks + +The secrets helper returns a text string, so you can use it anywhere in Chef Infra where you might hard code a value or access a value from a data bag. + +Write a secret to a file: + +```ruby +file '/home/ubuntu/aws-secret' do + content secret(name: '', service: :aws_secrets_manager) +end +``` + +Pass a secret to a template: + +```ruby +template '/etc/my_fancy_service/my_fancy_service.conf' do + source 'config.erb' + variables( + db_token: secret(name: 'db_token', service: :aws_secrets_manager) + ) +end +``` diff --git a/content/infra_language/shelling_out.md b/content/infra_language/shelling_out.md new file mode 100644 index 0000000..4e47e60 --- /dev/null +++ b/content/infra_language/shelling_out.md @@ -0,0 +1,36 @@ ++++ +title = "Chef Infra Language: Shelling Out" +draft = false + +[menu] + [menu.infra_language] + title = "Shelling Out" + identifier = "infra_language/shelling_out.md Shelling Out" + parent = "infra_language" ++++ + +In most cases when you need to run a particular command in a cookbook, you'll want to use the [execute resource](/resources/bundled/execute/). Helper methods for shelling out can be useful when writing custom resources or other more advanced Ruby code. + +## shell_out + +The `shell_out` method can be used to run a command against the node, and then display the output to the console when the log level is set to `debug`. + +The syntax for the `shell_out` method is as follows: + +```ruby +shell_out(command_args) +``` + +where `command_args` is the command that's run against the node. + +## shell_out! + +The `shell_out!` method can be used to run a command against the node, display the output to the console when the log level is set to `debug`, and then raise an error when the method returns `false`. + +The syntax for the `shell_out!` method is as follows: + +```ruby +shell_out!(command_args) +``` + +where `command_args` is the command that's run against the node. This method will return `true` or `false`. diff --git a/content/infra_language/windows.md b/content/infra_language/windows.md new file mode 100644 index 0000000..5666355 --- /dev/null +++ b/content/infra_language/windows.md @@ -0,0 +1,32 @@ ++++ +title = "Chef Infra Language: Windows" +draft = false + +[menu] + [menu.infra_language] + title = "Windows" + identifier = "infra_language/windows.md Windows" + parent = "infra_language" ++++ + +Chef Infra Client 15.8 and later include Windows-specific helpers for checking platform and package information. + +## windows_server_core? + +Determine if the current node is Windows Server Core. + +## windows_workstation? + +Determine if the current node is Windows Workstation. + +## windows_server? + +Determine if the current node is Windows Server. + +## windows_nt_version + +Determine the current Windows NT version. The NT version often differs from the marketing version, but offers a good way to find desktop and server releases that are based on the same codebase. For example NT 6.3 corresponds to Windows 8.1 and Windows 2012 R2. + +## powershell_version + +Determine the installed version of PowerShell. diff --git a/content/install/_index.md b/content/install/_index.md index a0d7255..981e617 100644 --- a/content/install/_index.md +++ b/content/install/_index.md @@ -2,10 +2,12 @@ title = "Install Chef Infra Client" linkTitle = "Install" -[menu.install] -title = "Overview" -parent = "install" -weight = 10 +[menu] + [menu.install] + title = "Overview" + identifier = "install/overview" + parent = "install" + weight = 10 +++ Use either a native installer or the Chef Infra Client migration tool to install or upgrade Chef Infra Client. @@ -28,7 +30,7 @@ The [Chef Infra Client migration tool](migration_tool) (`chef-migrate`) allows y **Key functions:** -- **Fresh installation:** Install Chef Infra Client 19 RC3 -- **Side-by-side installation:** Install Chef Infra Client 19 RC3 and remove or keep the previous Infra Client version. If you keep the previous version in side-by-side mode, the path to the most recent version takes precedence +- **Fresh installation:** Install Chef Infra Client +- **Side-by-side installation:** Install Chef Infra Client and remove or keep the previous Infra Client version. If you keep the previous version in side-by-side mode, the path to the most recent version takes precedence - **Omnibus upgrade:** Upgrade from Omnibus-based Chef Infra Client 17.x or 18.x versions -- **Habitat upgrade:** Upgrade from Habitat-packaged Chef Infra Client 19 RC releases +- **Habitat upgrade:** Upgrade from Habitat-packaged Chef Infra Client releases diff --git a/content/install/config_rb_client.md b/content/install/config_rb_client.md new file mode 100644 index 0000000..35b2005 --- /dev/null +++ b/content/install/config_rb_client.md @@ -0,0 +1,591 @@ ++++ +title = "client.rb" +draft = false + +[menu] + [menu.install] + title = "client.rb" + identifier = "install/config_rb_client.md client.rb Configuration" + parent = "install" + weight = 50 ++++ + + + +{{< readfile file="content/reusable/md/config_rb_client_summary.md" >}} + +## Settings + +This configuration file has the following settings: + +`add_formatter` +: A 3rd-party formatter. (See [nyan-cat](https://github.com/andreacampi/nyan-cat-chef-formatter) for an example of a 3rd-party formatter.) Each formatter requires its own entry. + +`allowed_automatic_attributes` +: An array that allows `automatic` attributes, preventing non-allowed attributes from being saved. + + For more information, see [Attribute Persistence](\{\{< relref "/cookbooks/attributes/attribute_persistence#attribute-allowlist" >}}). + +`allowed_default_attributes` +: An array that allows `default` attributes, preventing non-allowed attributes from being saved. + + For more information, see [Attribute Persistence](\{\{< relref "/cookbooks/attributes/attribute_persistence#attribute-allowlist" >}}). + +`allowed_normal_attributes` +: An array that allows `normal` attributes, preventing non-allowed attributes from being saved. + + For more information, see [Attribute Persistence](\{\{< relref "/cookbooks/attributes/attribute_persistence#attribute-allowlist" >}}). + +`allowed_override_attributes` +: An array that allows `override` attributes, preventing non-allowed attributes from being saved. + + For more information, see [Attribute Persistence](\{\{< relref "/cookbooks/attributes/attribute_persistence#attribute-allowlist" >}}). + +`authentication_protocol_version` +: Sets the authentication protocol that's used to communicate with Chef Infra Server. For example, specify protocol version 1.3 to enable support for SHA-256 algorithms: + + ```ruby + knife[:authentication_protocol_version] = '1.3' + ``` + + {{< note >}} + + Authentication protocol 1.3 is only supported on Chef Infra Server versions 12.4.0 and above. + + {{< /note >}} + +`automatic_attribute_blacklist` +: **EOL in Chef Infra Client 18**. Use `blocked_automatic_attributes`. +: An array that blocks `automatic` attributes, preventing blocked attributes from being saved. + +`automatic_attribute_whitelist` +: **EOL in Chef Infra Client 18**. Use `allowed_automatic_attributes`. +: An array that allows `automatic` attributes, preventing non-allowed attributes from being saved. + +`blocked_automatic_attributes` +: An array that blocks `automatic` attributes, preventing blocked attributes from being saved. + + For more information, see [Attribute Persistence](\{\{< relref "/cookbooks/attributes/attribute_persistence#attribute-blocklist" >}}). + +`blocked_default_attributes` +: An array that blocks `default` attributes, preventing block attributes from being saved. + + For more information, see [Attribute Persistence](\{\{< relref "/cookbooks/attributes/attribute_persistence#attribute-blocklist" >}}). + +`blocked_normal_attributes` +: An array allows `normal` attributes, preventing non-allowed attributes from being saved. + + For more information, see [Attribute Persistence](\{\{< relref "/cookbooks/attributes/attribute_persistence#attribute-blocklist" >}}). + +`blocked_override_attributes` +: An array blocks `override` attributes, preventing blocked attributes from being saved. + + For more information, see [Attribute Persistence](\{\{< relref "/cookbooks/attributes/attribute_persistence#attribute-blocklist" >}}). + +`cache_path` +: The home directory for the user that runs Chef Infra Client as a non-root user. + +`checksum_path` +: The location in which checksum files are stored. These are used to validate individual cookbook files, such as recipes. The checksum itself is stored in the Chef Infra Server database and is then compared to a file in the checksum path that has a filename identical to the checksum. + +`chef_guid` +: The node UUID used by Chef Automate. Setting this allows the node UUID to be specified, and can be carried across instances of a node. + +`chef_license` +: Used to accept the Chef license. Can be set to `accept` or `accept-no-persist`, which persists the license acceptance to disk. If passed to versions where the license isn't required this configuration option is a no-op. + +`chef_repo_path` +: The path to the chef-repo containing cookbooks and other files, such as environments or data bags, when running Chef Infra Client in local mode. + +`chef_server_url` +: The URL of Chef Infra Server. For example: + + ```ruby + https://localhost/organizations/ORG_NAME + ``` + +`chef_zero.enabled` +: Enable chef-zero. This setting requires `local_mode` to be set to `true`. + + Default value: `true` if running in local-mode, otherwise `false`. + +`chef_zero.port` +: The port on which chef-zero is to listen. If specified as a range, Chef Infra Client will take the first available port in the range. For example `10,20,30` or `10000-20000`. + + Default value: `8889-9999`. + +`clear_gem_sources` +: Globally sets the default of the `clear_sources` property on the `gem_package` and `chef_gem` resources. + + Default value: `false`. + +`client_fork` +: Contain Chef Infra Client runs in a secondary process with dedicated RAM. When a Chef Infra Client run is complete, the RAM is returned to the parent process. This setting helps ensure that a Chef Infra Client uses a steady amount of RAM over time because the parent process doesn't run recipes. This setting also helps prevent memory leaks such as those that can be introduced by the code contained within a poorly designed cookbook. + + Default value: `true`. Set to `false` to disable running Chef Infra Client in fork node. + + {{< note >}} + + Must be set to `false` up to Chef Infra Client 13.11.3 to gather the standard return code offered by `exit_status true`. Later versions run as expected without changes to the configuration file. + + {{< /note >}} + +`client_key` +: The location of the file that contains the client key. + + Default value: `/etc/chef/client.pem`. + +`client_registration_retries` +: The number of times a Chef Infra Client will attempt to register with a Chef Infra Server. + + Default value: `5`. + +`client_d_dir` +: A directory that contains additional configuration files for Chef Infra Client. + +`cookbook_path` +: The sub-directory for Chef Infra Client cookbooks. This value can be a string or an array of file system locations, processed in the specified order. The last cookbook is considered to override local modifications. + +`cookbook_sync_threads` +: The number of helper threads available for parallel cookbook synchronization. Increasing this value **may** increase the frequency of gateway errors from Chef Infra Server (503 and 504 errors). Decreasing this number reduces the frequency of gateway errors, if present. + + Default value: `10`. + +`data_bag_decrypt_minimum_version` +: The minimum required version of data bag encryption. Possible values: `1`, `2`, and `3`. + Use the default value of `3` for additional encrypted data bag security. + +`data_bag_path` +: The location from which a data bag is loaded. + + Default value: `/var/chef/data_bags`. + +`data_collector.server_url` +: The fully qualified URL to the data collector server API. + +`data_collector.token` +: The shared data collector security token. When configured, the token will be passed as an HTTP header named `x-data-collector-token` which the server can choose to accept or reject. + +`data_collector.mode` +: The Chef Infra Client mode in which the Data Collector will be enabled. Possible values: `:solo`, `:client`, or `:both`. The `:solo` value is used for Chef Infra Client operating in Chef Solo Mode or Chef Solo Legacy Mode. + + Default value: `both`. + +`data_collector.raise_on_failure` +: When enabled, Chef Infra Client raises an error if it can't successfully POST to the data collector server. + + Default value: `false`. + +`default_attribute_blacklist` +: **EOL in Chef Infra Client 18**. Use `blocked_default_attributes`. +: Normal that blocks `default` attributes, preventing block attributes from being saved. + +`default_attribute_whitelist` +: **EOL in Chef Infra Client 18**. Use `allowed_default_attributes`. +: Normal that allows `default` attributes, preventing non-allowed attributes from being saved. + +`diff_disabled` +: Cause Chef Infra Client to create a diff when changes are made to a file. + + Default value: `false`. + +`diff_filesize_threshold` +: The maximum size (in bytes) of a file for which Chef Infra Client can create a diff. + + Default value: `10000000`. + +`diff_output_threshold` +: The maximum size (in bytes) of a diff file Chef Infra Client can create. + + Default value: `1000000`. + +`disable_event_logger` +: Enable or disable sending Chef Infra Client internal state events to the Windows "Application" event log. Set to `false` to send events to the Windows "Application" event log at the start and end of a Chef Infra Client run, and also if a Chef Infra Client run fails. Use `log_location` to set the destination of your Chef Infra Client logs to the Windows event log. Set to `true` to disable event logging. + + Default value: `false`. + +`enable_reporting` +: Cause Chef Infra Client to send run data to Chef Automate server. + + Default value: `true` + +`enable_reporting_url_fatals` +: Cause a Chef Infra Client run to fail when run data can't be sent to the Chef Automate server (for any reason). + + Default value: `false` + +`enable_selinux_file_permission_fixup` +: SELinux environments only. Cause Chef Infra Client to attempt to apply the correct file permissions to an updated file using the `restorecon` command. Set to `false` to prevent Chef Infra Client from attempting this action. + +`encrypted_data_bag_secret` +: The path to a secrets file which can decrypt encrypted data bags. + +`enforce_default_paths` +: Turn on path sanity in resources that shellout so that expected paths like `/sbin` or `/bin` are added to the PATH. + + Disabled by default. + +`enforce_path_sanity` +: **EOL in Chef Infra Client 18**. Use `enforce_default_paths`. +: Turn on path sanity in resources that shellout so that expected paths like `/sbin` or `/bin` are added to the PATH. + + Disabled by default. + +`environment` +: The name of the Chef Infra environment. + +`environment_path` +: The path to the environment file. + + Default value: `/var/chef/environments`. + +`exit_status` +: When set to `:enabled`, Chef Infra Client will use [standardized exit codes](https://github.com/chef/chef/blob/main/docs/dev/design_documents/client_exit_codes.md#exit-codes-in-use) for the Chef Infra Client run status, and any non-standard exit codes will be converted to `1` or `GENERIC_FAILURE`. + This setting can also be set to `:disabled` to use the pre-Chef Infra Client 13 exit code behavior. + + Default value: `nil`. + +`file_atomic_update` +: Apply atomic file updates to all resources. Set to `true` for global atomic file updates. Set to `false` for global non-atomic file updates. (Use the `atomic_update` setting for each resource to override this setting.) + + Default value: `true`. + + {{< warning >}} + + Changing this setting to `false` may cause file corruption, data loss, or instability. Use the `atomic_update` property on the **cookbook_file**, **file**, **remote_file**, and **template** resources to tune this behavior at the recipe level. + + {{< /warning >}} + +`file_backup_path` +: The location in which backup files are stored. If this value is empty, backup files are stored in the directory of the target file. + + Default value: `/var/chef/backup`. + +`file_cache_path` +: The location in which cookbooks (and other transient data) files are stored when they're synchronized. This value can also be used in recipes to download files with the **remote_file** resource. + +`file_staging_uses_destdir` +: How file staging (using temporary files) is done. When `true`, temporary files are created in the directory in which files will reside. When `false`, temporary files are created under `ENV['TMP']`. + + Default value: `true`. + +`fips` +: Allows OpenSSL to enforce FIPS-validated security during a Chef Infra Client run. Set to `true` to enable FIPS-validated security. + +`force_formatter` +: Using `force_formatter` makes Chef Infra Client default to formatter output when STDOUT isn't a TTY. + +`force_logger` +: Using `force_logger` makes Chef Infra Client default to logger output when STDOUT is a TTY. + +`ftp_proxy` +: The proxy server for FTP connections. + +`ftp_proxy_pass` +: The password for the proxy server when the proxy server is using an FTP connection. + + Default value: `nil`. + +`ftp_proxy_user` +: The user name for the proxy server when the proxy server is using an FTP connection. + + Default value: `nil`. + +`group` +: The group that owns a process. This is required when starting any executable as a daemon. + + Default value: `nil`. + +`gem_installer_bundler_options` +: Additional options to pass to bundler when installing metadata for cookbook. + + Default value: `nil`. + + For example: + + ```ruby + gem_installer_bundler_options = [ + "--local", "--clean" + ] + ``` + + or + + ```ruby + gem_installer_bundler_options = "--local" + ``` + +`http_proxy` +: The proxy server for HTTP connections. + + Default value: `nil`. + +`http_proxy_pass` +: The password for the proxy server when the proxy server is using a HTTP connection. + + Default value: `nil`. + +`http_proxy_user` +: The user name for the proxy server when the proxy server is using a HTTP connection. + + Default value: `nil`. + +`http_retry_count` +: The number of retry attempts. + + Default value: `5`. + +`http_retry_delay` +: The delay (in seconds) between retry attempts. + + Default value: `5`. + +`https_proxy` +: The proxy server for HTTPS connections. + + Default value: `nil`. + +`https_proxy_pass` +: The password for the proxy server when the proxy server is using a HTTPS connection. + + Default value: `nil`. + +`https_proxy_user` +: The user name for the proxy server when the proxy server is using a HTTPS connection. + + Default value: `nil`. + +`interval` +: The frequency (in seconds) at which Chef Infra Client runs when running in daemonized mode. We don't recommend running in daemonized mode. Instead you should rely on scheduled execution from system schedulers like systemd timers, cron jobs, or Windows Scheduled Tasks. + + Default value: `1800`. + +`json_attribs` +: The path to a file that contains JSON data. + +`listen` +: Run chef-zero in socketless mode. Set to `false` to disable port binding and HTTP requests on localhost. + +`local_key_generation` +: Whether Chef Infra Server or Chef Infra Client generates the private/public key pair. When `true`, Chef Infra Client generates the key pair, and then sends the public key to Chef Infra Server. + + Default value: `true`. + +`local_mode` +: Run Chef Infra Client in local mode. This allows all commands that work against Chef Infra Server to also work against the local chef-repo. + +`lockfile` +: The location of the Chef Infra Client lock file. This value is typically platform dependent, so it should be a location defined by `file_cache_path`. The default location of a lock file shouldn't be on an NFS mount. + + Default value: a location defined by `file_cache_path`. + +`log_level` +: The level of logging to be stored in a log file. Possible levels: `:auto` (default), `:trace`, `:debug`, `:info`, `:warn`, `:error`, or `:fatal`. The `:auto` level will use `:warn` when a terminal is available or `:info` when a terminal isn't available. + +`log_location` +: The location of the log file. Possible values: `/path/to/log_location`, `STDOUT`, `STDERR`, `:win_evt` (Windows Event Logger), or `:syslog` (writes to the syslog daemon facility with the originator set as `chef-client`). The application log will specify the source as `Chef`. + + Default value: `STDOUT`. + +`migrate_key_to_keystore` +: Set to `true` to tell the Chef Infra Client to create a new key pair in a PFX certificate object and store that in the local machine certificate store. Chef Infra Client will check for the presence of that key when the headers to connect to Chef Infra Server are built and will use it if present. **Windows only.** + +`minimal_ohai` +: 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 plugins such as `cloud` or `packages`. Setting this to true may break cookbooks that assume all Ohai data will be present. + +`named_run_list` +: A specific named runlist defined in the node's applied Policyfile which should be used when running Chef Infra Client. + +`no_lazy_load` +: Download all cookbook files and templates at the beginning of a Chef Infra Client run. + + Default value: `true`. + +`no_proxy` +: A comma-separated list of URLs that don't need a proxy. + + Default value: `nil`. + +`node_name` +: The unique identifier of the node. This determines which configuration should be applied and sets the `client_name`, which is the name used when authenticating to a Chef Infra Server. By default, Chef Infra Client will use the system's FQDN as the node name. In general, Chef recommends that you leave this setting blank and let the client assign the FQDN of the node as the `node_name` during each Chef Infra Client run. + +`node_path` +: The location in which nodes are stored during a Chef Infra Client run in local mode. + + Default value: `/var/chef/node`. + +`normal_attribute_blacklist` +: **EOL in Chef Infra Client 18**. Use `blocked_normal_attributes`. +: An array that blocks `normal` attributes, preventing blocked attributes from being saved. + +`override_attribute_blacklist` +: **EOL in Chef Infra Client 18**. Use `blocked_override_attributes`. +: An array that blocks `override` attributes, preventing blocked attributes from being saved. + +`normal_attribute_whitelist` +: **EOL in Chef Infra Client 18**. Use `allowed_normal_attributes`. +: An array that allows `normal` attributes, preventing non-allowed attributes from being saved. + +`override_attribute_whitelist` +: **EOL in Chef Infra Client 18**. Use `allowed_override_attributes`. +: An array that allows `override` attributes, preventing non-allowed attributes from being saved. + +`pid_file` +: The location in which a process identification number (pid) is saved. An executable, when started as a daemon, writes the pid to the specified file. + + Default value: `/tmp/name-of-executable.pid`. + +`policy_group` +: The name of a policy group that exists on Chef Infra Server. `policy_name` must also be specified. + +`policy_group_path` +: The location of policy_groups on disk. + +`policy_name` +: The name of a policy, as identified by the `name` setting in a Policyfile.rb file. `policy_group` must also be specified. + +`policy_path` +: The location of policies on disk. + +`recipe_url` +: A URL to download recipes from when running in local mode. + +`rest_timeout` +: The time (in seconds) after which an HTTP REST request is to time out. + + Default value: `300`. + +`role_path` +: The location in which role files are located. + + Default value: `/var/chef/roles`. + +`rubygems_url` +: 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 setup an internal mirror of rubygems for "airgapped" environments. + + Default value: `https://www.rubygems.org`. If a `source` is specified in either `gem_package` of `chef_gem` resources it will be added to the values provided here. + +`run_lock_timeout` +: The amount of time (in seconds) to wait for a Chef Infra Client lock file to be deleted. + A Chef Infra Client run won't start when a lock file is present. + If a lock file isn't deleted before this time expires, the pending Chef Infra Client run exits. + + Default value: not set (indefinite). Set to `0` to cause a second Chef Infra Client to exit immediately. + +`script_path` +: An array of paths to search for knife exec scripts if they're not in the current directory + +`skip_gem_metadata_installation` +: when `skip_gem_metadata_installation` is set to true, cookbook gem installation will be skipped. + + Default value: `false` + +`splay` +: A random number between zero and `splay` that's added to `interval`. Use splay to help balance the load on Chef Infra Server by ensuring that many Chef Infra Client runs aren't occurring at the same interval. + + Default value: `nil`. + +`stream_execute_output` +: Always stream the output of `execute` resources even if the `live_stream` property isn't set to true. + + Default value: `false` + +`show_download_progress` +: Using show_download_progress will display the overall progress of a `remote_file` download. + + Default value: `false` + +`download_progress_interval` +: When `show_download_progress` is set to true this is the interval in seconds to write out download progress. + + Default value: `10` + +`ssl_ca_file` +: The file in which the OpenSSL key is saved. Chef Infra Client generates this setting automatically and most users don't need to modify it. + +`ssl_ca_path` +: The path to where the OpenSSL key is located. Chef Infra Client generates this setting automatically and most users don't need to modify it. + +`ssl_client_cert` +: The OpenSSL X.509 certificate used for mutual certificate validation. This setting is only necessary when mutual certificate validation is configured on Chef Infra Server. + + Default value:`nil`. + +`ssl_client_key` +: The OpenSSL X.509 key used for mutual certificate validation. This setting is only necessary when mutual certificate validation is configured on Chef Infra Server. + + Default value: `nil`. + +`ssl_verify_mode` +: Set the verify mode for HTTPS requests. + + - Use `:verify_none` for no validation of SSL certificates. + - Use `:verify_peer` for validation of all SSL certificates, including Chef Infra Server connections, S3 connections, and any HTTPS **remote_file** resource URLs used in Chef Infra Client runs. This is the recommended setting. + + Depending on how OpenSSL is configured, the `ssl_ca_path` may nee to be specified. + + Default value: `:verify_peer`. + +`trusted_certs_dir` +: A directory that contains additional SSL certificates to trust. Any certificates in this directory will be added to whatever CA bundle ruby is using. + Use this to add self-signed certs for your Chef Infra Server or local HTTP file servers. + + Default value: `trusted_certs` directory in your chef configuration directory. + +`umask` +: The file mode creation mask, or umask. + + Default value: `0022`. + +`use_policyfile` +: Chef Infra Client automatically checks the configuration, node JSON, and the stored node on Chef Infra Server to determine if Policyfile files are in use, and then automatically updates this flag. + + Default value: `false`. + +`user` +: The user that owns a process. This is required when starting any executable as a daemon. + + Default value: `nil`. + +`validation_client_name` +: The name of the chef-validator key that Chef Infra Client uses to access Chef Infra Server during the initial Chef Infra Client run. This is only used by the legacy validator based bootstrapping. + +`validation_key` +: The location of the file that contains the key used when a Chef Infra Client is registered with a Chef Infra Server. A validation key is signed using the `validation_client_name` for authentication. + + Default value: `/etc/chef/validation.pem`. This is only used by the legacy validator based bootstrapping. + +`verbose_logging` +: Set the log level. Options: `true`, `nil`, and `false`. When this is set to `false`, notifications about individual resources being processed are suppressed (and are output at the `:info` logging level). Setting this to `false` can be useful when a Chef Infra Client is run as a daemon. + + Default value: `nil`. + +`verify_api_cert` +: Verify the SSL certificate on Chef Infra Server. When `true`, Chef Infra Client always verifies the SSL certificate. When `false`, Chef Infra Client uses the value of `ssl_verify_mode` to determine if the SSL certificate requires verification. + + Default value: `false`. + +### Automatic Proxy Config + +{{< readfile file="content/reusable/md/proxy_env.md" >}} + +## .d Directories + +{{< readfile file="content/reusable/md/config_rb_client_dot_d_directories.md" >}} + +## Ohai Settings + +{{< readfile file="content/reusable/md/config_rb_ohai.md" >}} + +{{< readfile file="content/reusable/md/config_rb_ohai_settings.md" >}} + +## Example + +The following `client.rb` file shows the simplest way to connect to Chef Infra Server: + +```ruby +chef_server_url 'https://chef-server.example.com/organizations/ORGANIZATION' +validation_client_name '-validator' +validation_key '/etc/chef/validator.pem' +client_key '/etc/chef/client.pem' +``` diff --git a/content/install/install_bootstrap.md b/content/install/install_bootstrap.md new file mode 100644 index 0000000..550c649 --- /dev/null +++ b/content/install/install_bootstrap.md @@ -0,0 +1,457 @@ ++++ +title = "Bootstrap a node" +draft = false + +[menu] + [menu.install] + title = "Install using Bootstrap" + identifier = "install/install_bootstrap.md Install using Bootstrap" + parent = "install" + weight = 40 ++++ + +{{< readfile file="content/reusable/md/chef_client_bootstrap_node.md" >}} + +{{< readfile file="content/reusable/md/chef_client_bootstrap_stages.md" >}} + +## knife bootstrap + +{{< readfile file="content/reusable/md/install_chef_client.md" >}} + +### Run the bootstrap command + +The `knife bootstrap` command runs a bootstrap operation that installs Chef Infra Client on a target node. The following steps describe how to bootstrap a node using knife. + +1. Identify the FQDN or IP address of the target node. The `knife bootstrap` command requires the FQDN or the IP address for the node to complete the bootstrap operation. + +2. Once the workstation machine is configured, it can be used to install Chef Infra Client on one (or more) nodes across the organization using a knife bootstrap operation. The `knife bootstrap` command is used to SSH into the target machine, and then do what's needed to allow Chef Infra Client to run on the node. It will install the Chef Infra Client executable (if necessary), generate keys, and register the node with Chef Infra Server. The bootstrap operation requires the IP address or FQDN of the target system, the SSH credentials (username, password or identity file) for an account that has root access to the node, and (if the operating system isn't Ubuntu, which is the default distribution used by `knife bootstrap`) the operating system running on the target system. + + In a command window, enter the following: + + ```bash + knife bootstrap
-U --sudo + ``` + + Replace: + + - `
` the IP address or the FQDN of the node + - `` with the username used to connect to the node + + The `--sudo` option elevates privileges using the sudo command on UNIX-based systems. + + While the bootstrap operation is running, the command window returns something similar to the following: + + ```bash + Enter password for ubuntu@172.16.1.233: + + Connecting to 172.16.1.233 + Performing legacy client registration with the validation key at /Users/USERNAME/.chef/validator.pem... + Delete your validation key to use your user credentials for client registration instead. + Bootstrapping 172.16.1.233 + [172.16.1.233] -----> Installing Chef Omnibus (stable/16) + downloading https://omnitruck.chef.io/chef/install.sh + [172.16.1.233] to file /tmp/install.sh.1624/install.sh + [172.16.1.233] trying wget... + [172.16.1.233] ubuntu 20.04 aarch64 + [172.16.1.233] Getting information for chef stable 16 for ubuntu... + [172.16.1.233] downloading https://omnitruck.chef.io/stable/chef/metadata?v=16&p=ubuntu&pv=20.04&m=aarch64 + to file /tmp/install.sh.1628/metadata.txt + [172.16.1.233] trying wget... + [172.16.1.233] sha1 8d89f8ac2e7f52d170be8ec1c2a028a6449d7e3a + sha256 85cc73bed06e8d6699fc5c0b26c20d2837bf03831873444febccfc8bfa561f00 + url https://packages.chef.io/files/stable/chef/16.1.16/ubuntu/20.04/chef_16.1.16-1_arm64.deb + version 16.1.16 + [172.16.1.233] + [172.16.1.233] downloaded metadata file looks valid... + [172.16.1.233] downloading https://packages.chef.io/files/stable/chef/16.1.16/ubuntu/20.04/chef_16.1.16-1_arm64.deb + to file /tmp/install.sh.1628/chef_16.1.16-1_arm64.deb + [172.16.1.233] trying wget... + [172.16.1.233] Comparing checksum with sha256sum... + [172.16.1.233] Installing chef 16 + installing with dpkg... + [172.16.1.233] Selecting previously unselected package chef. + [172.16.1.233] (Reading database ... 99114 files and directories currently installed.) + [172.16.1.233] Preparing to unpack .../chef_16.1.16-1_arm64.deb ... + [172.16.1.233] Unpacking chef (16.1.16-1) ... + [172.16.1.233] Setting up chef (16.1.16-1) ... + [172.16.1.233] Thank you for installing Chef Infra Client! For help getting started visit https://learn.chef.io + [172.16.1.233] Starting the first Chef Infra Client Client run... + [172.16.1.233] +---------------------------------------------+ + ✓ 2 product licenses accepted. + +---------------------------------------------+ + [172.16.1.233] Starting Chef Infra Client, version 16.1.16 + [172.16.1.233] [2020-06-08T23:49:10+00:00] ERROR: shard_seed: Failed to get dmi property serial_number: is dmidecode installed? + [172.16.1.233] Creating a new client identity for name_of_node using the validator key. + [172.16.1.233] resolving cookbooks for run list: [] + [172.16.1.233] Synchronizing Cookbooks: + [172.16.1.233] Installing Cookbook Gems: + [172.16.1.233] Compiling Cookbooks... + [172.16.1.233] [2020-06-08T23:49:17+00:00] WARN: Node name_of_node has an empty run list. + [172.16.1.233] Converging 0 resources + [172.16.1.233] + [172.16.1.233] Running handlers: + [172.16.1.233] Running handlers complete + [172.16.1.233] Chef Infra Client finished, 0/0 resources updated in 11 seconds + ``` + +3. After the bootstrap operation has finished, verify that the node is recognized by Chef Infra Server. To show only the node that was just bootstrapped, run the following command: + + ```bash + knife client show NAME_OF_NODE + ``` + + where `NODE_NAME` is the name of the node that was just bootstrapped. Chef Infra Server will return something similar to: + + ```bash + admin: false + chef_type: client + name: NODE_NAME + validator: false + ``` + + and to show the full list of nodes (and workstations) that are registered with Chef Infra Server, run the following command: + + ```bash + knife client list + ``` + + Chef Infra Server will return something similar to: + + ```bash + workstation1 + workstation2 + ... + client1 + client2 + ``` + +## Validatorless and legacy validator bootstraps + +We recommended using "validatorless bootstrapping" to authenticate new nodes with Chef Infra Server. + +The legacy Chef Infra validator-based node bootstrapping process depended on using a shared "validatory" key throughout an organization for authenticating new nodes with Chef Infra Server. + +Shortcomings of the legacy validator process are: + +- All users share the same key for bootstrapping new systems +- Key sharing makes key rotation difficult, if it's compromised or if an employee leaves the organization. + +The "validatorless bootstrap" generates a key for each node, which is then transferred to the new node and used to authenticate with Chef Infra Server instead of relying on a shared "validator" key. + +The Chef Infra bootstrap process is validatorless by default. If you receive a warning during a bootstrap that a validator key is in use, remove the configuration for this legacy bootstrap mode. Edit your [config.rb (knife.rb)](https://docs.chef.io/workstation/config_rb/) file and remove any `validation_key` or `validation_client_name` entries. + +## Bootstrapping with chef-vault + +Use the following options with a validatorless bootstrap to specify items that are stored in chef-vault: + +`--bootstrap-vault-file VAULT_FILE` + +: The path to a JSON file that contains a list of vaults and items to be updated. + +`--bootstrap-vault-item VAULT_ITEM` + +: A single vault and item to update as `vault:item`. + +`--bootstrap-vault-json VAULT_JSON` + +: A JSON string that contains a list of vaults and items to be updated. `--bootstrap-vault-json '{ "vault1": \["item1", "item2"\], "vault2": "item2" }'` + +## Examples + +The `--bootstrap-vault-*` options add the client identify of the bootstrapping node to the permissions list of the specified vault item. This enables the newly-bootstrapped Chef Infra Client to be able to read items from the vault. Only a single client is authorized at a time for access to the vault. (The `-S` search query option with the `knife vault create` subcommand does the same.) + +### Recreate a data bag item + +The following example shows how to recreate a data bag item: + +```bash +knife vault delete sea power +Do you really want to delete sea/power? (Y/N) Y +Deleted chef_vault_item[sea/power] + +echo "{\"some\":\"content for them\"}" > sea-power-content.json + +cat sea-power-content.json +{"some":"content for them"} + +knife vault create sea power -M client -A sean_horn,angle -J sea-power-content.json +``` + +No clients, because the `-S` option wasn't specified while creating the vault. + +At this time, only the users `sean_horn` and `angle` are authorized to read and manage the vault. + +```bash +knife vault show sea power --mode client -p all +admins: + sean_horn + angle +clients: +id: power +search_query: +some: content for them +``` + +It's definitely an encrypted databag, see? + +```bash +knife data_bag show sea power +WARNING: Encrypted data bag detected, but no secret provided for decoding. Displaying encrypted data. +id: power +some: +cipher: aes-256-cbc +encrypted_data: c7Axnyg+1KDxBPOZdYN9QuIYx6dmSmK70unAQbn12Lygvsv2g9DPJJbueXVh ++yxL +iv: ONoVR7OjPZiAzaqOZ30bjg== +version: 1 +``` + +### Use --bootstrap-vault-file + +Use the `sea:power` recreation step above first, to follow the difference in the vault permissions. + +```bash +echo "{\"sea\":\"power\"}" > sea-power-bootstrap-vault-file.json + +knife bootstrap localhost -p 2200 -N ubuntu-20.04 -r 'role[group1]' --connection-user vagrant --sudo --bootstrap-vault-file sea-power-bootstrap-vault-file.json +Node ubuntu-20.04 exists, overwrite it? (Y/N) Y +Client ubuntu-20.04 exists, overwrite it? (Y/N) Y +Creating new client for ubuntu-20.04 +Creating new node for ubuntu-20.04 +Connecting to localhost +localhost -----> Existing Chef installation detected +localhost Starting first Chef Infra Client run... +localhost Starting Chef Infra Client, version 12.2.1 +localhost resolving cookbooks for run list: ["delay-test-reporting"] +localhost Synchronizing Cookbooks: +localhost - delay-test-reporting +localhost Compiling Cookbooks... +localhost Converging 1 resources +localhost Recipe: delay-test-reporting::default +localhost * execute[sleep 30] action run +localhost - execute sleep 30 +localhost +localhost Running handlers: +localhost Running handlers complete +localhost Chef Infra Client finished, 1/1 resources updated in 34.307257232 seconds +``` + +The client `ubuntu-20.04` was added to the `chef-vault` during the bootstrap. + +```bash +knife vault show sea power --mode client -p all +admins: + sean_horn + angle +clients: ubuntu-20.04 +id: power +search_query: +some: content for them +``` + +### Use --bootstrap-vault-item + +Use the `sea:power` re-creation step above first, to follow the difference in the vault permissions. + +```bash +knife bootstrap localhost -p 2200 -N ubuntu-20.04 -r 'role[group1]' --connection-user vagrant --sudo --bootstrap-vault-item sea:power +Node ubuntu-20.04 exists, overwrite it? (Y/N) Y +Client ubuntu-20.04 exists, overwrite it? (Y/N) Y +Creating new client for ubuntu-20.04 +Creating new node for ubuntu-20.04 +Connecting to localhost +localhost -----> Existing Chef installation detected +localhost Starting first Chef Infra Client run... +localhost Starting Chef Infra Client, version 12.2.1 +localhost resolving cookbooks for run list: ["delay-test-reporting"] +localhost Synchronizing Cookbooks: +localhost - delay-test-reporting +localhost Compiling Cookbooks... +localhost Converging 1 resources +localhost Recipe: delay-test-reporting::default +localhost * execute[sleep 30] action run +localhost - execute sleep 30 +localhost +localhost Running handlers: +localhost Running handlers complete +localhost Chef Infra Client finished, 1/1 resources updated in 34.322229474 +seconds +``` + +During the above run, the `sea:power` vault item was updated with the `ubuntu-20.04` client during the validatorless bootstrap. Previously, it only had the two admins authorized to view the content + +```bash +knife vault show sea power -p all +admins: + sean_horn + angle +clients: ubuntu-20.04 +id: power +search_query: role:stuff +some: secret stuff for them +``` + +Then, let's check the `ubuntu-20.04` client. The client itself can decrypt and read the encrypted databag contents as well using the embedded knife CLI in the Chef Infra Client package. + +```bash +sudo /opt/chef/bin/knife vault show sea power -c /etc/chef/client.rb -M client -p all +admins: + sean_horn + angle +clients: ubuntu-20.04 +id: power +search_query: role:group1 +some: secret stuff for them +``` + +Success! The client is authorized to view the content of the `sea:power` databag item + +### Use --bootstrap-vault-json + +Use the `sea:power` re-creation step above first, to follow the difference in the vault permissions. + +```bash +knife bootstrap localhost -p 2200 -N ubuntu-20.04 -r 'role[group1]' --connection-user vagrant --sudo --bootstrap-vault-json '{"sea": "power"}' +Node ubuntu-20.04 exists, overwrite it? (Y/N) Y +Client ubuntu-20.04 exists, overwrite it? (Y/N) Y +Creating new client for ubuntu-.04 +Creating new node for ubuntu-20.04 +Connecting to localhost +localhost -----> Existing Chef installation detected +localhost Starting first Chef Infra Client run... +localhost Starting Chef Infra Client, version 12.2.1 +localhost resolving cookbooks for run list: ["delay-test-reporting"] +localhost Synchronizing Cookbooks: +localhost - delay-test-reporting +localhost Compiling Cookbooks... +localhost Converging 1 resources +localhost Recipe: delay-test-reporting::default + +localhost * execute[sleep 30] action run +localhost - execute sleep 30 +localhost +localhost Running handlers: +localhost Running handlers complete +localhost Chef Infra Client finished, 1/1 resources updated in 33.732784033 seconds +``` + +```bash +knife vault show sea power -M client -p all +admins: + sean_horn + angle +clients: ubuntu-20.04 +id: power +search_query: +some: content for them +``` + +## Unattended installs + +Chef Infra Client can be installed using an unattended bootstrap. This allows Chef Infra Client to be installed from itself, without requiring SSH. For example, machines are often created using environments like AWS Auto Scaling, AWS CloudFormation, Rackspace Auto Scale, and PXE. In this scenario, using tooling for attended, single-machine installs like `knife bootstrap` or `knife CLOUD_PLUGIN create` isn't practical because the machines are created automatically and someone can't always be on-hand to initiate the bootstrap process. + +When Chef Infra Client is installed using an unattended bootstrap, remember that Chef Infra Client: + +- Must be able to authenticate to Chef Infra Server. +- Must be able to configure a run-list. +- May require custom attributes, depending on the cookbooks that are being used. +- Must be able to access the `chef-validator.pem` file so that it may create a new identity on Chef Infra Server. +- Must have a unique node name; Chef Infra Client will use the FQDN for the host system by default. + +When Chef Infra Client is installed using an unattended bootstrap, it may be built into an image that starts Chef Infra Client on boot, or installed using User Data or some other kind of post-deployment script. The type of image or User Data used depends on the platform on which the unattended bootstrap will take place. + +### Bootstrapping with user data + +The method used to inject a user data script into a server varies depending on the infrastructure platform being used. +For example, on AWS you can pass this data in as a text file using the command line. + +The following user data examples demonstrate the process of bootstrapping Windows and Linux nodes. + +#### PowerShell user data + +```powershell +## Set host file so the instance knows where to find chef-server +$hosts = "1.2.3.4 hello.example.com" +$file = "C:\Windows\System32\drivers\etc\hosts" +$hosts | Add-Content $file + +## Download Chef Infra Client +$clientURL = "https://chefdownload-commercial.chef.io/stable/client/download?p=windows>&pv=&m=&v=&license_id=" +$clientDestination = "C:\chef-client.msi" +Invoke-WebRequest $clientURL -OutFile $clientDestination + +## Install the Chef Infra Client +Start-Process msiexec.exe -ArgumentList @('/qn', '/lv C:\Windows\Temp\chef-log.txt', '/i C:\chef-client.msi', 'ADDLOCAL="ChefClientFeature,ChefSchTaskFeature,ChefPSModuleFeature"') -Wait + +## Create first-boot.json +$firstboot = @{ + "run_list" = @("role[base]") +} +Set-Content -Path c:\chef\first-boot.json -Value ($firstboot | ConvertTo-Json -Depth 10) + +## Create client.rb +$nodeName = "lab-win-{0}" -f (-join ((65..90) + (97..122) | Get-Random -Count 4 | % {[char]$_})) + +$clientrb = @" +chef_server_url 'https://chef-server/organizations/my-org' +validation_client_name 'validator' +validation_key 'C:\chef\validator.pem' +node_name '{0}' +"@ -f $nodeName + +Set-Content -Path c:\chef\client.rb -Value $clientrb + +## Run Chef +C:\opscode\chef\bin\chef-client.bat -j C:\chef\first-boot.json +``` + +#### Bash user data + +```bash +#!/bin/bash -xev + +# Do some chef pre-work +/bin/mkdir -p /etc/chef +/bin/mkdir -p /var/lib/chef +/bin/mkdir -p /var/log/chef + +# Setup hosts file correctly +cat >> "/etc/hosts" << EOF +10.0.0.5 compliance-server compliance-server.automate.com +10.0.0.6 infra-server infra-server.automate.com +10.0.0.7 automate-server automate-server.automate.com +EOF + +cd /etc/chef/ + +# Install chef +curl -L https://omnitruck.chef.io/install.sh | bash || error_exit "couldn't install chef" + +# Create first-boot.json +cat > "/etc/chef/first-boot.json" << EOF +{ + "run_list" :[ + "role[base]" + ] +} +EOF + +NODE_NAME=node-$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 4 | head -n 1) + +# Create client.rb +cat > '/etc/chef/client.rb' << EOF +log_location STDOUT +chef_server_url 'https://aut-chef-server/organizations/my-org' +validation_client_name 'my-org-validator' +validation_key '/etc/chef/my_org_validator.pem' +node_name "${NODE_NAME}" +EOF + +chef-client -j /etc/chef/first-boot.json +``` + +It's important that settings in the [client.rb file](/install/config_rb_client/)---for example `chef_server_url` and `http_proxy`---are used to ensure that configuration details are built into the unattended bootstrap process. + +##### Setting the initial run-list + +{{< readfile file="content/reusable/md/workstation/ctl_chef_client_bootstrap_initial_run_list.md" >}} diff --git a/content/install/install_chef_air_gap.md b/content/install/install_chef_air_gap.md new file mode 100644 index 0000000..785eb7c --- /dev/null +++ b/content/install/install_chef_air_gap.md @@ -0,0 +1,497 @@ ++++ +title = "Install Chef in an air-gapped environment" +draft = false + +[menu] + [menu.install] + title = "Air-gapped Installation" + identifier = "install/install_chef_air_gap.md Air-gapped Installation" + parent = "install" + weight = 40 ++++ + +This guide will show you how to run a fully functional Chef environment +within an [air-gapped](https://en.wikipedia.org/wiki/Air_gap_(networking)) +network. + +## Prerequisites + +Since a variety of different practices are used to create an air-gapped network, this guide focuses solely on the implementation of Chef software - as such, it makes the following assumptions: + + +- You have a way to get packages to your air-gapped machines +- Machines on your air-gapped network are able to resolve each other using DNS +- A server's Fully Qualified Domain Name (FQDN) is the name that will be used by other servers to access it +- You have a private Ruby gem mirror to supply gems as needed +- You have an artifact store for file downloads. At a minimum, it should have the following packages available: + + - Chef Workstation + - Chef Infra Client + - Chef Supermarket + - An [install script](#create-an-install-script) for Chef Infra Client + + +### Required cookbooks + +This guide will link to the required cookbooks for each piece of software in that software's respective section, but this is a full list of the cookbooks required to complete the entire guide: + +For Chef Supermarket: + +- [supermarket-omnibus-cookbook](https://supermarket.chef.io/cookbooks/supermarket-omnibus-cookbook) +- [chef-ingredient](https://supermarket.chef.io/cookbooks/chef-ingredient) +- [hostsfile](https://supermarket.chef.io/cookbooks/hostsfile) + +### Required gems + +The following Ruby gems are required to install private Supermarket using the supermarket-omnibus-cookbook: + +- mixlib-install +- mixlib-shellout +- mixlib-versioning +- artifactory + +These should be accessible from your Gem mirror. + +### Create an install script + +An install script is used to install Chef Infra Client when bootstrapping a new node. It simply pulls the Chef Infra Client package from your artifact store, and then installs it. For example, on Debian-based Linux systems, it would look similar to this: + +```bash +#!/bin/bash + +cd /tmp/ +wget http://packages.example.com/chef_13.2.20-1_amd64.deb +dpkg -i chef_13.2.20-1_amd64.deb +``` + +The install script should be accessible from your artifact store. + +## Chef Infra Server + +In this section you'll install Chef Infra Server, and create your +organization and user. Note that to configure Supermarket later +in this guide, you will need a user that's a member of the `admins` +group. + +1. Download the package from [Chef Downloads](https://www.chef.io/downloads). + +1. Upload the package to the machine that will run Chef Infra Server, and then record its location on the file system. The rest of these steps assume this location is in the `/tmp` directory. + +1. {{< readfile file="content/reusable/md/server/install_chef_server_install_package.md" >}} + +1. Run the following to start all of the services: + + ```bash + sudo chef-server-ctl reconfigure + ``` + + Because Chef Infra Server is composed of many different services + that work together to create a functioning system, this step may + take a few minutes to complete. + +1. {{< readfile file="content/reusable/md/server/ctl_chef_server_user_create_admin.md">}} + +1. {{< readfile file="content/reusable/md/server/ctl_chef_server_org_create_summary.md">}} + +## Chef Workstation + +### Install Chef Workstation + +1. First, install the Chef Workstation [installer + package](https://www.chef.io/downloads). Use the + appropriate tool to run the installer: + + ```bash + dpkg -i chef-workstation_0.14.16-1_amd64.deb + ``` + +1. Use the `chef generate repo` command to generate your Chef repo: + + ```bash + chef generate repo chef-repo + ``` + +1. Within your Chef repo, create a `.chef` directory: + + ```bash + mkdir /chef-repo/.chef + ``` + +1. Copy the `USER.pem` and `ORGANIZATION.pem` files from the server, + and move them into the `.chef` directory. + + ```bash + scp ssh-user@chef-server.example.com:/path/to/pem/files /chef-repo/.chef/ + ``` + +### Create a bootstrap template + +By default, `knife bootstrap` uses the `chef-full` template to bootstrap +a node. This template contains useful features, but it also +attempts to pull an installation script from `https://omnitruck.chef.io`. In +this section, you'll copy the contents of the `chef-full` template to a +custom template, and then modify the package and Ruby gem sources. + +1. Navigate to the `.chef` directory, and create a `bootstrap` + directory within it: + + ```bash + mkdir bootstrap + ``` + +1. Move to the `bootstrap` directory and create a blank template file; + this example will use `airgap.erb` for the template name: + + ```bash + touch airgap.erb + ``` + +1. Still in the `bootstrap` directory, issue the following command to copy the `chef-full` configuration to your new template: + + ```bash + find /opt/chef-workstation/embedded/lib/ruby -type f -name chef-full.erb -exec cat {} \; > airgap.erb + ``` + + This command searches for the `chef-full` template file under + `/opt/chef-workstation/embedded/lib/ruby`, and then outputs the + contents of the file to `airgap.erb`. If you used a different + template file name, be sure to replace `airgap.erb` with the + template file you created during the last step. + +1. Update `airgap.erb` to replace `omnitruck.chef.io` with the URL of `install.sh` on your artifact store: + + ```ruby + install_sh="<%= knife_config[:bootstrap_url] ? knife_config[:bootstrap_url] : "http://packages.example.com/install.sh" %>" + ``` + +1. Still in your text editor, locate the following line near the bottom + of your `airgap.erb` file: + + ```ruby + cat > /etc/chef/client.rb <<'EOP' + <%= config_content %> + EOP + ``` + + Beneath it, add the following, replacing `gems.example.com` with the + URL of your gem mirror: + + ```ruby + cat >> /etc/chef/client.rb <<'EOP' + rubygems_url "http://gems.example.com" + EOP + ``` + + This appends the appropriate `rubygems_url` setting to the + `/etc/chef/client.rb` file that's created during bootstrap, which + ensures that your nodes use your internal gem mirror. + +### Configure knife + +Within the `.chef` directory, create a `config.rb` file and replace +`USER` and `ORGANIZATION` with the user and organization that you +created on your Chef Infra Server; replace `chef-server.example.com` +with your Chef Infra Server URL: + +```ruby +current_dir = File.dirname(__FILE__) +node_name 'USER' +client_key "#{current_dir}/USER.pem" +validation_client_name 'ORGANIZATION-validator' +validation_key "#{current_dir}/ORGANIZATION.pem" +chef_server_url 'https://chef-server.example.com/organizations/ORGANIZATION' +cookbook_path ["#{current_dir}/../cookbooks"] +knife[:bootstrap_template] = "#{current_dir}/bootstrap/airgap.erb" +``` + +The `knife[:bootstrap_template]` option in this example allows you to +specify the template that `knife bootstrap` will use by default when +bootstrapping a node. It should point to your custom template within the +`bootstrap` directory. + +Now that `knife` is configured, copy the SSL certificates from your Chef +Infra Server to your trusted certificates: + +```ruby +knife ssl fetch +``` + +## Private Supermarket + +Private Supermarket allows you to host your own internal version of the +[Chef Supermarket](https://supermarket.chef.io) within your air-gapped +network. + +### Requirements + +In this section, you will use a wrapper around the +[supermarket-omnibus-cookbook](https://supermarket.chef.io/cookbooks/supermarket-omnibus-cookbook) +to install private Supermarket. The Supermarket cookbook depends upon +the following cookbooks: + +- [chef-ingredient](https://supermarket.chef.io/cookbooks/chef-ingredient) +- [hostsfile](https://supermarket.chef.io/cookbooks/hostsfile) + +The following Gems must be accessible using your Gem mirror: + +- mixlib-install +- mixlib-shellout +- mixlib-versioning +- artifactory + +Your `cookbooks` directory must have all three of these cookbooks +installed before you will be able to use the Supermarket cookbook +wrapper. In addition the necessary cookbooks, a private Chef Supermarket +has the following requirements: + +- An operational Chef Infra Server to act as the OAuth 2.0 provider +- A user account on Chef Infra Server with `admins` privileges +- A key for the user account on the Chef Infra Server +- An x86_64 Ubuntu, RHEL, or Amazon Linux host with at least 1 GB memory +- System clocks synchronized on Chef Infra Server and Supermarket hosts +- Sufficient disk space to meet project cookbook storage capacity or credentials to store cookbooks in an Amazon Simple Storage Service (S3) bucket + +### Configure credentials + +First, you'll configure Chef Identity credentials for Supermarket. Chef +Identity is an OAuth 2.0 service packaged with Chef Infra Server, +that allows you to use the same credentials to access both server and +Supermarket. + +1. Log on to Chef Infra Server using SSH and elevate to an + admin-level user. If running a multi-node Chef Infra Server cluster, + log on to the node acting as the primary node in the cluster. + +1. Update the `/etc/opscode/chef-server.rb` configuration file. + + {{< readfile file="content/reusable/md/server/config_ocid_application_hash_supermarket.md" >}} + +1. Reconfigure Chef Infra Server. + + ```bash + sudo chef-server-ctl reconfigure + ``` + +1. Retrieve Supermarket's OAuth 2.0 client credentials: + + Depending on your Chef Infra Server version and configuration (see + [chef-server.rb](https://docs.chef.io/server/config_rb_server_optional_settings/#config-rb-server-insecure-addon-compat)), + this can be retrieved using [chef-server-ctl oc-id-show-app + supermarket](https://docs.chef.io/server/ctl_chef_server/#ctl-chef-server-oc-id-show-app) + or is located in `/etc/opscode/oc-id-applications/supermarket.json`: + + ```json + { + "name": "supermarket", + "uid": "0bad0f2eb04e935718e081fb71asdfec3681c81acb9968a8e1e32451d08b", + "secret": "17cf1141cc971a10ce307611beda7ffadstr4f1bc98d9f9ca76b9b127879", + "redirect_uri": "https://supermarket.mycompany.com/auth/chef_oauth2/callback" + } + ``` + +### Create a Wrapper + +1. Generate the cookbook: + + ```bash + chef generate cookbook my_supermarket_wrapper + ``` + +1. Change directories into that cookbook: + + ```bash + cd my_supermarket_wrapper + ``` + +1. Defines the wrapper cookbook's dependency on the + `supermarket-omnibus-cookbook` cookbook. Open the `metadata.rb` file + of the newly-created cookbook, and then add the following line: + + ```ruby + depends 'supermarket-omnibus-cookbook' + ``` + +1. Save and close the `metadata.rb` file. + +1. Open the `/recipes/default.rb` recipe located within the + newly-generated cookbook and add the following content: + + ```ruby + include_recipe 'supermarket-omnibus-cookbook' + ``` + + This ensures that the `default.rb` file in the + `supermarket-omnibus-cookbook` is run. + +### Define Attributes + +Define the attributes for the Chef Supermarket installation and how it +connects to Chef Infra Server. One approach would be to hard-code +attributes in the wrapper cookbook's `default.rb` recipe. A better +approach is to place these attributes in a [data bag](/policy/data_bags/), +and then reference them from the recipe. For example, the data bag could +be named `apps` and then a data bag item within the data bag could be +named `supermarket`. The following attributes are required: + +- `chef_server_url`: the URL of your Chef Infra Server. +- `chef_oauth2_app_id`: the Chef Identity UID from + `/etc/opscode/oc-id-applications/supermarket.json` +- `chef_oauth2_secret`: The Chef Identity secret from + `/etc/opscode/oc-id-applications/supermarket.json` +- `package_url`: The location of the Supermarket package on your + artifact store + +To define these attributes, do the following: + +1. Open the `recipes/default.rb` file and add the following, **before** + the `include_recipe` line that was added in the previous step. This + example uses a data bag named `apps` and a data bag item named + `supermarket`: + + ```ruby + app = data_bag_item('apps', 'supermarket') + ``` + +1. Set the attributes from the data bag: + + ```ruby + node.override['supermarket_omnibus']['chef_server_url'] = app['chef_server_url'] + node.override['supermarket_omnibus']['chef_oauth2_app_id'] = app['chef_oauth2_app_id'] + node.override['supermarket_omnibus']['chef_oauth2_secret'] = app['chef_oauth2_secret'] + node.override['supermarket_omnibus']['package_url'] = app['package_url'] + ``` + + Note that the `['package_url']` setting points to the location of + the Supermarket package on your artifact store. When finished, the + `/recipes/default.rb` file should have code similar to: + + ```ruby + app = data_bag_item('apps', 'supermarket') + + node.override['supermarket_omnibus']['chef_server_url'] = app['chef_server_url'] + node.override['supermarket_omnibus']['chef_oauth2_app_id'] = app['chef_oauth2_app_id'] + node.override['supermarket_omnibus']['chef_oauth2_secret'] = app['chef_oauth2_secret'] + + include_recipe 'supermarket-omnibus-cookbook' + ``` + + Alternatively, if you chose not to use a data bag to store these + values, your `default.rb` should look similar to this: + + ```ruby + node.override['supermarket_omnibus']['chef_server_url'] = 'https://chef-server.example.com:443' + node.override['supermarket_omnibus']['chef_oauth2_app_id'] = '0bad0f2eb04e935718e081fb71asdfec3681c81acb9968a8e1e32451d08b' + node.override['supermarket_omnibus']['chef_oauth2_secret'] = '17cf1141cc971a10ce307611beda7ffadstr4f1bc98d9f9ca76b9b127879' + node.override['supermarket_omnibus']['package_url'] = 'http://packages.example.com/supermarket_3.1.22-1_amd64.deb' + + include_recipe 'supermarket-omnibus-cookbook' + ``` + +1. Save and close the `recipes/default.rb` file. + +1. Upload all of your cookbooks to Chef Infra Server: + + ```ruby + knife cookbook upload -a + ``` + +### Bootstrap Supermarket + +Bootstrap the node on which Chef Supermarket is to be installed. For +example, to bootstrap a node running Ubuntu on Amazon Web Services +(AWS), the command is similar to: + +```bash +knife bootstrap ip_address -N supermarket-node -x ubuntu --sudo +``` + +where: + +- `-N` defines the name of the Chef Supermarket node: + `supermarket-node` +- `-x` defines the (ssh) user name: `ubuntu` +- `--sudo` ensures that sudo is used while running commands on the + node during the bootstrap operation + +When the bootstrap operation is finished, do the following: + +1. Add the wrapper cookbook's `/recipes/default.rb` recipe to the + run-list: + + ```bash + knife node run_list set supermarket-node recipe[my_supermarket_wrapper::default] + ``` + + where `supermarket-node` is the name of the node that was just + bootstrapped. + +1. Start Chef Infra Client on the newly-bootstrapped Chef Supermarket + node. For example, using SSH: + + ```bash + ssh ubuntu@your-supermarket-node-public-dns + ``` + +1. After accessing the Chef Supermarket node, run Chef Infra Client: + + ```bash + sudo chef-client + ``` + +### Connect to Supermarket + +To reach the newly spun up private Chef Supermarket, the hostname must +be resolvable from a workstation. For production use, the hostname +should have a DNS entry in an appropriate domain that's trusted by each +user's workstation. + +1. Visit the Chef Supermarket hostname in the browser. A private Chef + Supermarket will generate and use a self-signed certificate, if a + certificate isn't supplied as part of the installation process (using + the wrapper cookbook). +1. If an SSL notice is shown due to your self-signed certificate while + connecting to Chef Supermarket using a web browser, accept the SSL + certificate. A trusted SSL certificate should be used for private + Chef Supermarket that's used in production. +1. After opening Chef Supermarket in a web browser, click the **Create + Account** link. A prompt to log in to Chef Infra Server is + shown. Authorize the Chef Supermarket to use the Chef Infra Server + account for authentication. + +{{< note >}} + +The redirect URL specified for Chef Identity **MUST** match the FQDN +hostname of the Chef Supermarket server. The URI must also be correct: +`/auth/chef_oauth2/callback`. Otherwise, an error message similar to +`The redirect uri included isn't valid.` will be shown. + +{{< /note >}} + +### Configuration updates + +#### Knife + +Update the `config.rb` file on your workstation to use your private +Supermarket: + +```ruby +knife[:supermarket_site] = 'https://supermarket.example.com' +``` + +#### Berkshelf + +If you're using Berkshelf, update your `Berksfile` to replace +`https://supermarket.chef.io` with the URL of your private Supermarket: + +```ruby +source 'https://supermarket.example.com' +``` + +### Upload cookbooks to Supermarket + +To upload new cookbooks to your private Supermarket, use the +`knife supermarket share` command on your workstation: + +```ruby +knife supermarket share chef-ingredient +``` diff --git a/content/install/installer/_index.md b/content/install/installer/_index.md index 875038f..4e86797 100644 --- a/content/install/installer/_index.md +++ b/content/install/installer/_index.md @@ -31,7 +31,7 @@ This installation process has the following prerequisites: ## Install Chef Infra Client -To install Chef Infra Client 19, follow these steps: +To install Chef Infra Client , follow these steps: 1. Download the Chef Infra Client installer. @@ -44,13 +44,13 @@ To install Chef Infra Client 19, follow these steps: - Using Wget: ```sh - wget -O "chef-ice-19.2.rc3-linux.deb" "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/chef-ice/19.2.RC3/linux/x86_64/chef-ice-19.2.rc3-linux.deb?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=9tqCmX%2F576Nrf6bdiZgK%2FRQP7%2BE%3D&Expires=1780533327" + wget -O "chef-ice-19.2.rc3-linux.deb" "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/chef-ice/19.2.RC3/linux/x86_64/chef-ice-19.2.rc3-linux.deb?AWSAccessKeyId=AKIAW4FPVFT6C42N3U6R&Signature=cmJmplCvrkVXK5MtqCmidrz3rds%3D&Expires=1776916085" ``` - Using curl: ```sh - curl -o "chef-ice-19.2.rc3-linux.deb" "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/chef-ice/19.2.RC3/linux/x86_64/chef-ice-19.2.rc3-linux.deb?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=9tqCmX%2F576Nrf6bdiZgK%2FRQP7%2BE%3D&Expires=1780533327" + curl -o "chef-ice-19.2.rc3-linux.deb" "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/chef-ice/19.2.RC3/linux/x86_64/chef-ice-19.2.rc3-linux.deb?AWSAccessKeyId=AKIAW4FPVFT6C42N3U6R&Signature=cmJmplCvrkVXK5MtqCmidrz3rds%3D&Expires=1776916085" ``` {{< /accordion-item >}} @@ -61,13 +61,13 @@ To install Chef Infra Client 19, follow these steps: - Using Wget: ```sh - wget -O chef-ice-19.2.rc3-linux.rpm "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/chef-ice/19.2.RC3/linux/x86_64/chef-ice-19.2.rc3-linux.rpm?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=gODj1%2BnbpBZ2VYbb3CYjZvU1JXQ%3D&Expires=1780533345" + wget -O chef-ice-19.2.rc3-linux.rpm "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/chef-ice/19.2.RC3/linux/x86_64/chef-ice-19.2.rc3-linux.rpm?AWSAccessKeyId=AKIAW4FPVFT6C42N3U6R&Signature=FUbFKD2qMux2TBK7ltNPLuExQGk%3D&Expires=1776916329" ``` - Using curl: ```sh - curl -o chef-ice-19.2.rc3-linux.rpm "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/chef-ice/19.2.RC3/linux/x86_64/chef-ice-19.2.rc3-linux.rpm?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=gODj1%2BnbpBZ2VYbb3CYjZvU1JXQ%3D&Expires=1780533345" + curl -o chef-ice-19.2.rc3-linux.rpm "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/chef-ice/19.2.RC3/linux/x86_64/chef-ice-19.2.rc3-linux.rpm?AWSAccessKeyId=AKIAW4FPVFT6C42N3U6R&Signature=FUbFKD2qMux2TBK7ltNPLuExQGk%3D&Expires=1776916329" ``` {{< /accordion-item >}} @@ -78,13 +78,13 @@ To install Chef Infra Client 19, follow these steps: - Using curl: ```sh - curl -o chef-ice-19.2.rc3-windows.msi "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/chef-ice/19.2.RC3/windows/x86_64/chef-ice-19.2.rc3-windows.msi?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=ugQFgpkB1TWtaN1mo4iRGGFtgeQ%3D&Expires=1780533357" + curl -o chef-ice-19.2.rc3-windows.msi "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/chef-ice/19.2.RC3/windows/x86_64/chef-ice-19.2.rc3-windows.msi?AWSAccessKeyId=AKIAW4FPVFT6C42N3U6R&Signature=rmb4GgaxE6oPEfVHiAugsg7xMBI%3D&Expires=1776916373" ``` - Using PowerShell: ```ps1 - Invoke-WebRequest -Uri "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/chef-ice/19.2.RC3/windows/x86_64/chef-ice-19.2.rc3-windows.msi?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=ugQFgpkB1TWtaN1mo4iRGGFtgeQ%3D&Expires=1780533357" -OutFile "chef-ice-19.2.rc3-windows.msi" + Invoke-WebRequest -Uri "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/chef-ice/19.2.RC3/windows/x86_64/chef-ice-19.2.rc3-windows.msi?AWSAccessKeyId=AKIAW4FPVFT6C42N3U6R&Signature=rmb4GgaxE6oPEfVHiAugsg7xMBI%3D&Expires=1776916373" -OutFile "chef-ice-19.2.rc3-windows.msi" ``` {{< /accordion-item >}} diff --git a/content/install/migration_tool/_index.md b/content/install/migration_tool/_index.md index f668e45..ae3462f 100644 --- a/content/install/migration_tool/_index.md +++ b/content/install/migration_tool/_index.md @@ -8,14 +8,14 @@ parent = "install/migration_tool" weight = 10 +++ -The Chef Infra Client migration tool (`chef-migrate`) allows you to install or upgrade Chef Infra Client to the latest version in both online and air-gapped environments. +The Chef Infra Client migration tool (`migrate-ice`) allows you to install or upgrade Chef Infra Client to the latest version in both online and air-gapped environments. ## Key functions -- **Fresh installation:** Install Chef Infra Client 19 RC3 -- **Side-by-side installation:** Install Chef Infra Client 19 RC3 and remove or keep the previous Infra Client version. If you keep the previous version in side-by-side mode, the path to the most recent version takes precedence +- **Fresh installation:** Install Chef Infra Client +- **Side-by-side installation:** Install Chef Infra Client and remove or keep the previous Infra Client version. If you keep the previous version in side-by-side mode, the path to the most recent version takes precedence - **Omnibus upgrade:** Upgrade from Omnibus-based Chef Infra Client 17.x or 18.x versions -- **Habitat upgrade:** Upgrade Habitat-packaged Chef Infra Client 19 RC releases +- **Habitat upgrade:** Upgrade Habitat-packaged Chef Infra Client releases ## Supported platforms @@ -29,4 +29,4 @@ To install or upgrade Chef Infra Client, see these guides: - [Install](install) - [Online upgrade](upgrade_online) - [Air-gapped upgrade](upgrade_airgap) -- [`chef-migrate` CLI reference](reference) +- [`migrate-ice` CLI reference](reference) diff --git a/content/install/migration_tool/install.md b/content/install/migration_tool/install.md index d6062f4..4a6fed6 100644 --- a/content/install/migration_tool/install.md +++ b/content/install/migration_tool/install.md @@ -12,7 +12,7 @@ This page documents how to install Chef Infra Client RC3 in an online environmen ## Supported platforms -Chef Infra Client 19 RC3 is supported on: +Chef Infra Client is supported on: - Linux x86-64 - Windows x86-64 @@ -31,46 +31,96 @@ To install Chef Infra Client on Linux, follow these steps: chef-client --version ``` -1. Download the Chef Infra Client migration tool. +1. Get the latest version number of the Infra Client migration tool (migrate-ice). - The migration tool is available for download as a zipped tar file using a pre-signed URL from an S3 bucket until April 23, 2026. + ```sh + curl "https://commercial-acceptance.downloads.chef.co/stable/migrate-ice/versions/latest?license_id=" + ``` + + Replace `` with your Progress Chef License ID. + + The response returns the latest version. + +1. Download the Chef Infra Client migration tool using curl or Wget. + + {{< accordion-list id="download-migration-tool-curl-wget-linux" data-allow-all-closed="true" >}} - Using curl: + {{< accordion-item accordion-title-link="download-migration-tool-with-curl-linux" accordion-title="Download migration tool with curl" >}} + + Download the migration tool using curl: ```sh - curl -o migration-tools-1.1.rc3-linux.tar.gz "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/migrate-ice/1.1.RC3/linux/migration-tools-1.1.rc3-linux.tar.gz?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=O8rQUc0jy%2BeP7U1WspJasr7qMTY%3D&Expires=1780533385" + curl -o migration-tools--linux.tar.gz "https://commercial-acceptance.downloads.chef.co/current/migrate-ice/packages?v=&license_id=" ``` - Using Wget: + Replace: + + - `` with the version number from the previous step + - `` with your Progress Chef License ID + + {{< /accordion-item >}} + + {{< accordion-item accordion-title-link="download-migration-tool-with-wget-linux" accordion-title="Download migration tool with Wget" >}} + + Download the migration tool using Wget: ```sh - wget -O "migration-tools-1.1.rc3-linux.tar.gz" "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/migrate-ice/1.1.RC3/linux/migration-tools-1.1.rc3-linux.tar.gz?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=O8rQUc0jy%2BeP7U1WspJasr7qMTY%3D&Expires=1780533385" + wget -O "migration-tools--linux.tar.gz" "https://commercial-acceptance.downloads.chef.co/current/migrate-ice/packages?v=&license_id=" ``` + Replace: + + - `` with the version number from the previous step + - `` with your Progress Chef License ID + + {{< /accordion-item >}} + + {{< /accordion-list >}} + 1. Extract the migration tool and make it executable. ```sh - tar -xvf migration-tools-1.1.rc3-linux.tar.gz -C /path/to/temp/folder + tar -xvf migration-tools--linux.tar.gz -C /path/to/temp/folder cd /path/to/temp/folder - chmod +x chef-migrate - mv chef-migrate /usr/local/bin/ + chmod +x migrate-ice + mv migrate-ice /usr/local/bin/ ``` 1. Optional: Verify that the migration tool is installed. ```sh - chef-migrate --help + migrate-ice --help ``` The migration tool returns available commands and usage guidelines. -1. Install Chef Infra Client using [`chef-migrate apply`](reference): +1. Install Chef Infra Client using [`migrate-ice apply`](reference): + + You can install Chef Infra Client using specifying a download URL or an Infra Client version number. + + {{< accordion-list id="migrate-ice-download-linux" data-allow-all-closed="true" >}} + {{< accordion-item accordion-title-link="migrate-ice-download-url-linux" accordion-title="Specify download URL" >}} + + ```sh + sudo migrate-ice apply online --fresh-install --download-url "" + ``` + + Replace `` with the Chef Infra Client package download URL. + + {{< /accordion-item >}} + {{< accordion-item accordion-title-link="migrate-ice-download-version-number-linux" accordion-title="Specify version number" >}} ```sh - sudo chef-migrate apply online --fresh-install --download-url "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/chef-ice/19.2.RC3/linux/x86_64/chef-ice-19.2.rc3-linux.tar.gz?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=htVtnPFhoan9wyXixccqDFp0jmU%3D&Expires=1780533226" --license-key "" + sudo migrate-ice apply online --fresh-install --chef-version --license-key "" ``` - Replace `` with your Progress Chef License key. + Replace: + + - `` with the Chef Infra Client version number (for example, `19.1.150`) + - `` with your Progress Chef License key + + {{< /accordion-item >}} + {{< /accordion-list >}} 1. Verify the Chef Infra Client installation. @@ -88,46 +138,96 @@ To install Chef Infra Client on Windows, follow these steps: chef-client --version ``` -1. Download the Chef Infra Client migration tool. +1. Get the latest version number of the Infra Client migration tool (migrate-ice): - The migration tool is available for download as a ZIP file using a pre-signed address from an S3 bucket until April 23, 2026. + ```powershell + curl "https://commercial-acceptance.downloads.chef.co/stable/migrate-ice/versions/latest?license_id=" + ``` + + Replace `` with your Progress Chef License ID. + + The response returns the latest version. + +1. Download the migration tool using curl or PowerShell: + + {{< accordion-list id="download-migration-tool-curl-powershell-windows" data-allow-all-closed="true" >}} - Using curl: + {{< accordion-item accordion-title-link="download-migration-tool-with-curl-windows" accordion-title="Download migration tool with curl" >}} + + Download the migration tool using curl: ```powershell - curl -o migration-tools-1.1.rc3-windows.zip "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/migrate-ice/1.1.RC3/windows/migration-tools-1.1.rc3-windows.zip?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=xyfZ7g7D5jLF5jY%2B8DfBkEedSUA%3D&Expires=1780533399" + curl -o migration-tools--windows.zip "https://commercial-acceptance.downloads.chef.co/current/migrate-ice/packages?v=&license_id=" ``` - Using PowerShell: + Replace: + + - `` with the version number from the previous step + - `` with your Progress Chef License ID + + {{< /accordion-item >}} + + {{< accordion-item accordion-title-link="download-migration-tool-with-powershell-windows" accordion-title="Download migration tool with PowerShell" >}} + + Download the migration tool using PowerShell: ```powershell - Invoke-WebRequest -Uri "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/migrate-ice/1.1.RC3/windows/migration-tools-1.1.rc3-windows.zip?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=xyfZ7g7D5jLF5jY%2B8DfBkEedSUA%3D&Expires=1780533399" -OutFile "migration-tools-1.1.rc3-windows.zip" + Invoke-WebRequest -Uri "https://commercial-acceptance.downloads.chef.co/current/migrate-ice/packages?v=&license_id=" -OutFile "migration-tools--windows.zip" ``` + Replace: + + - `` with the version number from the previous step + - `` with your Progress Chef License ID + + {{< /accordion-item >}} + + {{< /accordion-list >}} + 1. Extract the migration tool. ```powershell mkdir C:\migrate-tool - move "migration-tools-1.1.rc3-windows.zip" "C:\migrate-tool\" + move "migration-tools--windows.zip" "C:\migrate-tool\" cd C:\migrate-tool - Expand-Archive -Path "migration-tools-1.1.rc3-windows.zip" -DestinationPath "." + Expand-Archive -Path "migration-tools--windows.zip" -DestinationPath "." ``` 1. Optional: Verify that the migration tool works. ```powershell - .\chef-migrate --help + .\migrate-ice --help ``` The migration tool returns available commands and usage guidelines. -1. Install Chef Infra Client using [`chef-migrate apply`](reference): +1. Install Chef Infra Client using [`migrate-ice apply`](reference): + + You can install Chef Infra Client using specifying a download URL or an Infra Client version number. + + {{< accordion-list id="migrate-ice-download-windows" data-allow-all-closed="true" >}} + {{< accordion-item accordion-title-link="migrate-ice-download-url-windows" accordion-title="Specify download URL" >}} + + ```powershell + .\migrate-ice apply online --fresh-install --download-url "" + ``` + + Replace `` with the Chef Infra Client package download URL. + + {{< /accordion-item >}} + {{< accordion-item accordion-title-link="migrate-ice-download-version-number-windows" accordion-title="Specify version number" >}} ```powershell - .\chef-migrate apply online --fresh-install --download-url "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/chef-ice/19.2.RC3/windows/x86_64/chef-ice-19.2.rc3-windows.tar.gz?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=2jIjDACxF0EYf8yICEp698kt0xY%3D&Expires=1780533373" --license-key "" + .\migrate-ice apply online --fresh-install --chef-version --license-key "" ``` - Replace `` with your Progress Chef License key. + Replace: + + - `` with the Chef Infra Client version number (for example, `19.1.150`) + - `` with your Progress Chef License key + + {{< /accordion-item >}} + {{< /accordion-list >}} 1. Verify the Chef Infra Client installation. diff --git a/content/install/migration_tool/install_airgap.md b/content/install/migration_tool/install_airgap.md index 1937c0c..17f2745 100644 --- a/content/install/migration_tool/install_airgap.md +++ b/content/install/migration_tool/install_airgap.md @@ -13,7 +13,7 @@ This page documents how to do a fresh install of Chef Infra Client RC3 in an air ## Supported platforms -Chef Infra Client 19 RC3 is supported on Linux x86-64 systems. +Chef Infra Client is supported on Linux x86-64 systems. ## Prerequisites @@ -23,61 +23,126 @@ Chef Infra Client 19 RC3 is supported on Linux x86-64 systems. To install Chef Infra Client, follow these steps: -1. On an internet-connected machine, download the Chef Infra Client 19 RC3 tar file. +1. On an internet-connected machine, get the Chef Infra Client tar package download URL: - Chef Infra Client is available in a zipped tar file using a pre-signed URL from an S3 bucket until April 23, 2026. + ```sh + curl "https://commercial-acceptance.downloads.chef.co/current/chef-ice/packages?v=&license_id=" + ``` + + Replace: + + - `` with the Chef Infra Client version number (for example, 19.1.152) + - `` with your Progress Chef License ID + + The response returns download URLs for different platforms and package types. Use the URL from the `linux..tar.url` field in the JSON response (for example, `linux.x86_64.tar.url` if the architecture is x86-64). + +1. Download the Chef Infra Client package using curl or Wget: + + {{< accordion-list id="download-chef-infra-client-curl-wget" data-allow-all-closed="true" >}} + + {{< accordion-item accordion-title="Download Infra Client with curl" accordion-title-link="download-chef-infra-client-curl" >}} - Download using curl: + Download the tar file using curl: ```sh - curl -o chef-ice-19.2.rc3-linux.tar.gz "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/chef-ice/19.2.RC3/linux/x86_64/chef-ice-19.2.rc3-linux.tar.gz?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=htVtnPFhoan9wyXixccqDFp0jmU%3D&Expires=1780533226" + curl -o chef-ice--linux.tar.gz "" ``` + Replace: + + - `` with the URL from the `linux..tar.url` field + - `` with the Chef Infra Client version number + + {{< /accordion-item >}} + + {{< accordion-item accordion-title="Download Infra Client with Wget" accordion-title-link="download-chef-infra-client-wget" >}} + Download using Wget: ```sh - wget -O "chef-ice-19.2.rc3-linux.tar.gz" "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/chef-ice/19.2.RC3/linux/x86_64/chef-ice-19.2.rc3-linux.tar.gz?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=htVtnPFhoan9wyXixccqDFp0jmU%3D&Expires=1780533226" + wget -O "chef-ice--linux.tar.gz" "" + ``` + + Replace: + + - `` with the URL from the `linux..tar.url` field + - `` with the Chef Infra Client version number + + {{< /accordion-item >}} + + {{< /accordion-list >}} + +1. On an internet-connected machine, get the latest version of the Chef Infra Client migration tool (migrate-ice). + + ```sh + curl "https://commercial-acceptance.downloads.chef.co/stable/migrate-ice/versions/latest?license_id=" ``` -1. On an internet-connected machine, download the Chef Infra Client migration tool. + Replace `` with your Progress Chef License ID. - The migration tool is available for download as a zipped tar file using a pre-signed URL from an S3 bucket until April 23, 2026. + The response returns the latest version number. + +1. Download the migration tool: + + {{< accordion-list id="my-accordion" data-allow-all-closed="true" >}} + + {{< accordion-item accordion-title="Download migration tool with curl" accordion-title-link="download-migration-tool-curl" >}} Using curl: ```sh - curl -o migration-tools-1.1.rc3-linux.tar.gz "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/migrate-ice/1.1.RC3/linux/migration-tools-1.1.rc3-linux.tar.gz?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=O8rQUc0jy%2BeP7U1WspJasr7qMTY%3D&Expires=1780533385" + curl -o migration-tools--linux.tar.gz "https://commercial-acceptance.downloads.chef.co/current/migrate-ice/packages?v=&license_id=" ``` + Replace: + + - `` with the version number from the previous step + - `` with your Progress Chef License ID + + {{< /accordion-item >}} + + {{< accordion-item accordion-title="Download migration tool with Wget" accordion-title-link="download-migration-tool-wget" >}} + Using Wget: ```sh - wget -O "migration-tools-1.1.rc3-linux.tar.gz" "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/migrate-ice/1.1.RC3/linux/migration-tools-1.1.rc3-linux.tar.gz?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=O8rQUc0jy%2BeP7U1WspJasr7qMTY%3D&Expires=1780533385" + wget -O "migration-tools--linux.tar.gz" "https://commercial-acceptance.downloads.chef.co/current/migrate-ice/packages?v=&license_id=" ``` + Replace: + + - `` with the version number from the previous step + - `` with your Progress Chef License ID + + {{< /accordion-item >}} + + {{< /accordion-list >}} + 1. Extract the migration tool and make it executable. ```sh - tar -xvf migration-tools-1.1.rc3-linux.tar.gz -C /path/to/temp/folder + tar -xvf migration-tools--linux.tar.gz -C /path/to/temp/folder cd /path/to/temp/folder - chmod +x chef-migrate - mv chef-migrate /usr/local/bin/ + chmod +x migrate-ice + mv migrate-ice /usr/local/bin/ ``` 1. Optional: Verify that the migration tool is installed. ```sh - chef-migrate --help + migrate-ice --help ``` The migration tool returns available commands and usage guidelines. -1. Install Chef Infra CLient using [`chef-migrate apply`](reference): +1. Install Chef Infra CLient using [`migrate-ice apply`](reference): ```sh - sudo chef-migrate apply airgap --fresh-install --license-key "" + sudo migrate-ice apply airgap --fresh-install ``` + Replace `` with the path to the Chef Infra Client tar file. + 1. Verify that Chef Infra Client is installed. ```sh diff --git a/content/install/migration_tool/reference.md b/content/install/migration_tool/reference.md index 23830cb..4810d73 100644 --- a/content/install/migration_tool/reference.md +++ b/content/install/migration_tool/reference.md @@ -10,18 +10,18 @@ weight = 999 ## Syntax -The `chef-migrate apply` command upgrades or installs Chef Infra Client to version 19. +The `migrate-ice apply` command upgrades or installs Chef Infra Client to version 19. This command has the following basic syntax: ```sh -chef-migrate apply {airgap|online} [flags] +migrate-ice apply {airgap|online} [flags] ``` It supports two subcommands: -- `airgap`: Uses pre-downloaded air-gapped bundles to install or upgrade Chef Infra Client 19. -- `online`: Uses network-connected resources to download and install Chef Infra Client 19. +- `airgap`: Uses pre-downloaded air-gapped bundles to install or upgrade Chef Infra Client . +- `online`: Uses network-connected resources to download and install Chef Infra Client . ## Flags @@ -30,6 +30,20 @@ It supports two subcommands: `--debug` : Enable debug logs. Logs are available in `/var/log/chef19migrate.log`. Valid values are: `true` or `false`. +`--chef-version ` +: Specify the Chef Infra Client version to download and install. Only applicable for online mode. The `--license-key` option is required with `--chef-version`. + + The tool performs the following actions: + + - **Download**: Automatically downloads the specified Chef Infra Client package from the official repository + - **Validation**: Checks version format and ensures it's a supported Chef 19.x.x version + - **Package Path**: The downloaded package is stored at a predefined location for later use + - **Skip Option**: If `--chef-version` isn't provided, the flag is skipped (useful when using `--download-url` instead) + + Valid format: `19.x.x` (for example, `19.1.0`, `19.0.5`) + + This flag is mutually exclusive with `--download-url`. Use one or the other, not both. + `--download-url ` : Specify the Chef Infra Client download location. @@ -108,19 +122,35 @@ It supports two subcommands: ### Install Chef Infra Client -These examples show how to perform a fresh install of Chef Infra Client 19 RC3. +These examples show how to perform a fresh install of Chef Infra Client . -Standard online installation: +Install Chef Infra Client by specifying a download URL: ```sh -chef-migrate apply online --fresh-install --download-url "" --license-key "" +migrate-ice apply online --fresh-install --download-url "" --license-key "" ``` +Replace: + +- `` with the Chef Infra Client package download URL +- `` with a valid Progress Chef License key + +Install Chef Infra Client in an online environment by specifying a version number: + +```sh +migrate-ice apply online --fresh-install --chef-version --license-key "" +``` + +Replace: + +- `` with a valid Progress Chef License key +- `` the full three-part Chef Infra Client version number (for example, `19.1.0`) + @@ -131,13 +161,13 @@ These examples show how to upgrade Chef Infra Client to version 19 RC3 from an e Standard online upgrade: ```sh -chef-migrate apply online --download-url "" --license-key "" +migrate-ice apply online --download-url "" --license-key "" ``` Standard air-gapped upgrade: ```sh -chef-migrate apply airgap --license-key "" +migrate-ice apply airgap --license-key "" ``` ### Manage Omnibus-based Chef Infra Client @@ -145,31 +175,31 @@ chef-migrate apply airgap --license-key "" Preserve an Omnibus-based Chef Infra Client installation: ```sh -chef-migrate apply {airgap|online} --license-key "" --preserve-omnibus +migrate-ice apply {airgap|online} --license-key "" --preserve-omnibus ``` Log a warning if the `client.rb` config file references the Omnibus-based Chef Infra Client installation (`/opt/chef`): ```sh -chef-migrate apply {airgap|online} --license-key "" --process-config warn +migrate-ice apply {airgap|online} --license-key "" --process-config warn ``` Replace the existing Omnibus-based Chef binaries (for example, `ruby`, `chef-client`, and `openssl`) with symbolic links pointing to their Habitat-based equivalents. ```sh -chef-migrate apply {airgap|online} --license-key "" --preserve-omnibus --symlink +migrate-ice apply {airgap|online} --license-key "" --preserve-omnibus --symlink ``` Remount Chef Infra Client from `/opt/chef` to `/hab`: ```sh -chef-migrate apply {airgap|online} --license-key "" --fstab apply +migrate-ice apply {airgap|online} --license-key "" --fstab apply ``` Abort the migration process if `/opt/chef` is already mounted: ```sh -chef-migrate apply {airgap|online} --license-key "" --fstab fail +migrate-ice apply {airgap|online} --license-key "" --fstab fail ``` ### Manage Chef Habitat @@ -177,7 +207,7 @@ chef-migrate apply {airgap|online} --license-key "" --fstab fail Upgrade Chef Habitat while installing Chef Infra Client: ```sh -chef-migrate apply {airgap|online} --license-key "" --habitat-upgrade +migrate-ice apply {airgap|online} --license-key "" --habitat-upgrade ``` ### SELinux profiles @@ -185,11 +215,11 @@ chef-migrate apply {airgap|online} --license-key "" --habitat-upgra Install the default SELinux profile: ```sh -chef-migrate apply {airgap|online} --license-key "" --selinux-profile default --selinux-ignore-warnings +migrate-ice apply {airgap|online} --license-key "" --selinux-profile default --selinux-ignore-warnings ``` Install a custom SELinux profile: ```sh -chef-migrate apply {airgap|online} --license-key "" --selinux-profile +migrate-ice apply {airgap|online} --license-key "" --selinux-profile ``` diff --git a/content/install/migration_tool/upgrade_airgap.md b/content/install/migration_tool/upgrade_airgap.md index 43f6969..154d0c5 100644 --- a/content/install/migration_tool/upgrade_airgap.md +++ b/content/install/migration_tool/upgrade_airgap.md @@ -12,7 +12,7 @@ This page documents how to upgrade Chef Infra Client to version 19 RC3 in an air ## Supported platforms -Chef Infra Client 19 RC3 is supported on: +Chef Infra Client is supported on: - Linux x86-64 - Windows x86-64 @@ -21,69 +21,125 @@ Chef Infra Client 19 RC3 is supported on: - a valid Chef License key -## Upgrade to Chef Infra Client 19 RC3 on Linux +## Upgrade to Chef Infra Client on Linux To upgrade Chef Infra Client, follow these steps: -1. On an internet-connected machine, download the Chef Infra Client 19 RC3 tar file. +1. On an internet-connected machine, get the download URL for the Chef Infra Client tar package: - Chef Infra Client is available in a zipped tar file using a pre-signed URL from an S3 bucket until April 23, 2026. + ```sh + curl "https://commercial-acceptance.downloads.chef.co/current/chef-ice/packages?v=&license_id=" + ``` + + Replace `` with the Chef Infra Client version number (for example, 19.1.152) and `` with your Progress Chef License ID. + + The response returns download URLs for different platforms and package types. Use the URL from the `linux..tar.url` field in the JSON response (for example, `linux.x86_64.tar.url` if the architecture is x86_64). + +1. Download the Chef Infra Client tar file. - Download using curl: + {{< accordion-list id="download-chef-infra-client-curl-wget-linux" data-allow-all-closed="true" >}} + + {{< accordion-item accordion-title="Download using curl" accordion-title-link="download-chef-infra-client-curl-linux" >}} + + Download the tar file using curl: ```sh - curl -o chef-ice-19.2.rc3-linux.tar.gz "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/chef-ice/19.2.RC3/linux/x86_64/chef-ice-19.2.rc3-linux.tar.gz?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=htVtnPFhoan9wyXixccqDFp0jmU%3D&Expires=1780533226" + curl -o chef-ice--linux.tar.gz "" ``` + Replace: + + - `` with the URL from the `linux..tar.url` field + - `` with the Chef Infra Client version number + + {{< /accordion-item >}} + + {{< accordion-item accordion-title="Download using Wget" accordion-title-link="download-chef-infra-client-wget-linux" >}} + Download using Wget: ```sh - wget -O "chef-ice-19.2.rc3-linux.tar.gz" "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/chef-ice/19.2.RC3/linux/x86_64/chef-ice-19.2.rc3-linux.tar.gz?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=htVtnPFhoan9wyXixccqDFp0jmU%3D&Expires=1780533226" + wget -O "chef-ice--linux.tar.gz" "" ``` -1. On an internet-connected machine, download the Chef Infra Client migration tool. + Replace: + + - `` with the URL from the `linux..tar.url` field + - `` with the Chef Infra Client version number - The migration tool is available for download as a zipped tar file using a pre-signed URL from an S3 bucket until April 23, 2026. + {{< /accordion-item >}} - Using curl: + {{< /accordion-list >}} + +1. On an internet-connected machine, get the latest version of the Chef Infra Client migration tool (migrate-ice). + + ```sh + curl "https://commercial-acceptance.downloads.chef.co/stable/migrate-ice/versions/latest?license_id=" + ``` + + Replace `` with your Progress Chef License ID. + + The response returns the latest version number. + +1. Download the Chef Infra Client migration tool package. + + {{< accordion-list id="download-migration-tool-package-curl-wget-linux" data-allow-all-closed="true" >}} + + {{< accordion-item accordion-title="Download migration tool with curl" accordion-title-link="download-migration-tool-curl-linux" >}} + + Download migration tool using curl: ```sh - curl -o migration-tools-1.1.rc3-linux.tar.gz "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/migrate-ice/1.1.RC3/linux/migration-tools-1.1.rc3-linux.tar.gz?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=O8rQUc0jy%2BeP7U1WspJasr7qMTY%3D&Expires=1780533385" + curl -o migration-tools--linux.tar.gz "https://commercial-acceptance.downloads.chef.co/current/migrate-ice/packages?v=&license_id=" ``` - Using Wget: + Replace: + + - `` with the version number from the previous step + - `` with your Progress Chef License ID + + {{< /accordion-item >}} + + {{< accordion-item accordion-title="Download migration tool with Wget" accordion-title-link="download-migration-tool-wget-linux" >}} + + Download migration tool using Wget: ```sh - wget -O "migration-tools-1.1.rc3-linux.tar.gz" "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/migrate-ice/1.1.RC3/linux/migration-tools-1.1.rc3-linux.tar.gz?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=O8rQUc0jy%2BeP7U1WspJasr7qMTY%3D&Expires=1780533385" + wget -O "migration-tools--linux.tar.gz" "https://commercial-acceptance.downloads.chef.co/current/migrate-ice/packages?v=&license_id=" ``` + Replace: + - `` with the version number from the previous step + - `` with your Progress Chef License ID + + {{< /accordion-item >}} + + {{< /accordion-list >}} + 1. Extract the migration tool and make it executable. ```sh - tar -xvf migration-tools-1.1.rc3-linux.tar.gz -C /path/to/temp/folder + tar -xvf migration-tools--linux.tar.gz -C /path/to/temp/folder cd /path/to/temp/folder - chmod +x chef-migrate - mv chef-migrate /usr/local/bin/ + chmod +x migrate-ice + mv migrate-ice /usr/local/bin/ ``` 1. Optional: Verify that the migration tool is installed. ```sh - chef-migrate --help + migrate-ice --help ``` The migration tool returns available commands and usage guidelines. -1. Install Chef Infra Client by specifying the path to the tar file using [`chef-migrate apply`](reference). +1. Install Chef Infra Client by specifying the path to the tar file using [`migrate-ice apply`](reference). ```sh - sudo chef-migrate apply airgap --license-key "" + sudo migrate-ice apply airgap ``` - Replace: - - - `` with the path to the Chef Infra Client tar file. - - `` with your Progress Chef License key. + Replace `` with the path to the Chef Infra Client tar file. 1. Verify that Chef Infra Client is installed. @@ -91,67 +147,122 @@ To upgrade Chef Infra Client, follow these steps: chef-client --version ``` -## Upgrade to Chef Infra Client 19 RC3 on Windows +## Upgrade to Chef Infra Client on Windows To upgrade Chef Infra Client, follow these steps: -1. On an internet-connected machine, download the Chef Infra Client 19 RC3 tar file. +1. On an internet-connected machine, get the download URL for the Chef Infra Client tar package: + + ```powershell + curl "https://commercial-acceptance.downloads.chef.co/current/chef-ice/packages?v=&license_id=" + ``` + + Replace `` with the Chef Infra Client version number (for example, 19.1.152) and `` with your Progress Chef License ID. + + The response returns download URLs for different platforms and package types. Use the URL from the `windows..tar.url` field in the JSON response (for example, `windows.x86_64.tar.url` if the architecture is x86_64). + +1. Download the Chef Infra Client tar file. + + {{< accordion-list id="my-accordion" data-allow-all-closed="true" >}} - Chef Infra Client is available in a tar file using a pre-signed address from an S3 bucket until April 23, 2026. + {{< accordion-item accordion-title="Download Chef Infra Client with curl" accordion-title-link="download-chef-infra-client-curl-windows" >}} - Download using curl: + Download the tar file using curl: ```powershell - curl -o chef-ice-19.2.rc3-windows.tar.gz "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/chef-ice/19.2.RC3/windows/x86_64/chef-ice-19.2.rc3-windows.tar.gz?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=2jIjDACxF0EYf8yICEp698kt0xY%3D&Expires=1780533373" + curl -o chef-ice--windows.tar.gz "" ``` + {{< /accordion-item >}} + + {{< accordion-item accordion-title="Download Chef Infra Client with PowerShell" accordion-title-link="download-chef-infra-client-powershell-windows" >}} + Download using PowerShell: ```powershell - Invoke-WebRequest -Uri "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/chef-ice/19.2.RC3/windows/x86_64/chef-ice-19.2.rc3-windows.tar.gz?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=2jIjDACxF0EYf8yICEp698kt0xY%3D&Expires=1780533373" -OutFile "chef-ice-19.2.rc3-windows.tar.gz" + Invoke-WebRequest -Uri "" -OutFile "chef-ice--windows.tar.gz" ``` -1. On an internet-connected machine, download the Chef Infra Client migration tool. + Replace: + + - `` with the URL from the `windows..tar.url` field + - `` with the Chef Infra Client version number - The migration tool is available for download as a ZIP file using a pre-signed address from an S3 bucket until April 23, 2026. + {{< /accordion-item >}} + + {{< /accordion-list >}} + +1. On an internet-connected machine, get the latest version of the Chef Infra Client migration tool (migrate-ice). + + ```powershell + curl "https://commercial-acceptance.downloads.chef.co/stable/migrate-ice/versions/latest?license_id=" + ``` + + Replace `` with your Progress Chef License ID. + + The response returns the latest version number. Use this version to download the migration tool package. + +1. Download the Chef Infra Client migration tool package. + + {{< accordion-list id="download-migration-tool-curl-powershell-windows" data-allow-all-closed="true" >}} + + {{< accordion-item accordion-title="Download migration tool with curl" accordion-title-link="download-migration-tool-curl-windows" >}} Using curl: ```powershell - curl -o migration-tools-1.1.rc3-windows.zip "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/migrate-ice/1.1.RC3/windows/migration-tools-1.1.rc3-windows.zip?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=xyfZ7g7D5jLF5jY%2B8DfBkEedSUA%3D&Expires=1780533399" + curl -o migration-tools--windows.zip "https://commercial-acceptance.downloads.chef.co/current/migrate-ice/packages?v=&license_id=" ``` + Replace: + + - `` with the version number from the previous step + - `` with your Progress Chef License ID + + {{< /accordion-item >}} + + {{< accordion-item accordion-title="Download migration tool with PowerShell" accordion-title-link="download-migration-tool-powershell-windows" >}} + Using PowerShell: ```powershell - Invoke-WebRequest -Uri "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/migrate-ice/1.1.RC3/windows/migration-tools-1.1.rc3-windows.zip?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=xyfZ7g7D5jLF5jY%2B8DfBkEedSUA%3D&Expires=1780533399" -OutFile "migration-tools-1.1.rc3-windows.zip" + Invoke-WebRequest -Uri "https://commercial-acceptance.downloads.chef.co/current/migrate-ice/packages?v=&license_id=" -OutFile "migration-tools--windows.zip" ``` + Replace: + + - `` with the version number from the previous step + - `` with your Progress Chef License ID + + {{< /accordion-item >}} + + {{< /accordion-list >}} + 1. Extract the migration tool. ```powershell mkdir C:\migrate-tool - move "migration-tools-1.1.rc3-windows.zip" "C:\migrate-tool\" - move "chef-ice-19.2.rc3-windows.tar.gz" "C:\migrate-tool\" + move "migration-tools--windows.zip" "C:\migrate-tool\" + move "chef-ice--windows.tar.gz" "C:\migrate-tool\" cd C:\migrate-tool - Expand-Archive -Path "migration-tools-1.1.rc3-windows.zip" -DestinationPath "." + Expand-Archive -Path "migration-tools--windows.zip" -DestinationPath "." ``` 1. Optional: Verify that the migration tool works. ```powershell - .\chef-migrate --help + .\migrate-ice --help ``` The migration tool returns available commands and usage guidelines. -1. Upgrade Chef Infra Client by specifying the path to the tar file using [`chef-migrate apply`](reference). +1. Upgrade Chef Infra Client by specifying the path to the tar file using [`migrate-ice apply`](reference). ```powershell - .\chef-migrate apply airgap "C:\migrate-tool\chef-ice-19.2.rc3-windows.tar.gz" --license-key "" + .\migrate-ice apply airgap "C:\migrate-tool\chef-ice--windows.tar.gz" ``` - Replace `` with your Progress Chef License key. + Replace `` with the Chef Infra Client version. 1. Verify the Chef Infra Client upgrade. diff --git a/content/install/migration_tool/upgrade_online.md b/content/install/migration_tool/upgrade_online.md index 51c5751..c0ee96c 100644 --- a/content/install/migration_tool/upgrade_online.md +++ b/content/install/migration_tool/upgrade_online.md @@ -12,7 +12,7 @@ This page documents how to upgrade Chef Infra Client to version 19 RC3 in an onl ## Supported platforms -Chef Infra Client 19 RC3 is supported on: +Chef Infra Client is supported on: - Linux x86-64 - Windows x86-64 @@ -21,50 +21,103 @@ Chef Infra Client 19 RC3 is supported on: - a valid Chef License key -## Upgrade Chef Infra Client 19 RC3 on Linux +## Upgrade Chef Infra Client on Linux To upgrade Chef Infra Client, follow these steps: -1. Download the Chef Infra Client migration tool. +1. Get the latest version of the Chef Infra Client migration tool (migrate-ice). - The migration tool is available for download as a zipped tar file using a pre-signed URL from an S3 bucket until April 23, 2026. + ```sh + curl "https://commercial-acceptance.downloads.chef.co/stable/migrate-ice/versions/latest?license_id=" + ``` + + Replace `` with your Progress Chef License ID. + + The response returns the latest version number. Use this version to download the migration tool package. + +1. Download the migration tool using curl or Wget. + + {{< accordion-list id="download-migration-tool-curl-wget-linux" data-allow-all-closed="true" >}} + + {{< accordion-item accordion-title="Download migration tool with curl" accordion-title-link="download-migration-tool-curl-linux" >}} Using curl: ```sh - curl -o migration-tools-1.1.rc3-linux.tar.gz "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/migrate-ice/1.1.RC3/linux/migration-tools-1.1.rc3-linux.tar.gz?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=O8rQUc0jy%2BeP7U1WspJasr7qMTY%3D&Expires=1780533385" + curl -o migration-tools--linux.tar.gz "https://commercial-acceptance.downloads.chef.co/current/migrate-ice/packages?v=&license_id=" ``` + Replace: + + - `` with the version number from the previous step + - `` with your Progress Chef License ID + + {{< /accordion-item >}} + + {{< accordion-item accordion-title="Download migration tool with Wget" accordion-title-link="download-migration-tool-wget-linux" >}} + Using Wget: ```sh - wget -O "migration-tools-1.1.rc3-linux.tar.gz" "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/migrate-ice/1.1.RC3/linux/migration-tools-1.1.rc3-linux.tar.gz?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=O8rQUc0jy%2BeP7U1WspJasr7qMTY%3D&Expires=1780533385" + wget -O "migration-tools--linux.tar.gz" "https://commercial-acceptance.downloads.chef.co/current/migrate-ice/packages?v=&license_id=" ``` + Replace: + + - `` with the version number from the previous step + - `` with your Progress Chef License ID + + {{< /accordion-item >}} + + {{< /accordion-list >}} + 1. Extract the migration tool and make it executable. ```sh - tar -xvf migration-tools-1.1.rc3-linux.tar.gz -C /path/to/temp/folder + tar -xvf migration-tools--linux.tar.gz -C /path/to/temp/folder cd /path/to/temp/folder - chmod +x chef-migrate - mv chef-migrate /usr/local/bin/ + chmod +x migrate-ice + mv migrate-ice /usr/local/bin/ ``` 1. Optional: Verify that the migration tool is installed. ```sh - chef-migrate --help + migrate-ice --help ``` The migration tool returns available commands and usage guidelines. -1. Install Chef Infra Client using [`chef-migrate apply`](reference). +1. Upgrade Chef Infra Client using [`migrate-ice apply`](reference). + + You can upgrade Chef Infra Client by specifying a download URL or a version number. + + {{< accordion-list id="upgrade-chef-infra-client-linux" data-allow-all-closed="true" >}} + + {{< accordion-item accordion-title="Specify download URL" accordion-title-link="upgrade-chef-infra-client-url-linux" >}} ```sh - sudo chef-migrate apply online --download-url "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/chef-ice/19.2.RC3/linux/x86_64/chef-ice-19.2.rc3-linux.tar.gz?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=htVtnPFhoan9wyXixccqDFp0jmU%3D&Expires=1780533226" --license-key "" + sudo migrate-ice apply online --download-url "" ``` - Replace `` with your Progress Chef License key. + Replace `` with the Chef Infra Client package download URL. + + {{< /accordion-item >}} + + {{< accordion-item accordion-title="Specify version number" accordion-title-link="upgrade-chef-infra-client-version-linux" >}} + + ```sh + sudo migrate-ice apply online --chef-version --license-key "" + ``` + + Replace: + + - `` with the Chef Infra Client version number (for example, `19.1.150`) + - `` with your Progress Chef License key. + + {{< /accordion-item >}} + + {{< /accordion-list >}} 1. Verify that Chef Infra Client is installed. @@ -72,50 +125,103 @@ To upgrade Chef Infra Client, follow these steps: chef-client --version ``` -## Upgrade Chef Infra Client 19 RC3 on Windows +## Upgrade Chef Infra Client on Windows To upgrade Chef Infra Client, follow these steps: -1. Download the Chef Infra Client migration tool. +1. Get the latest version of the Chef Infra Client migration tool (migrate-ice). - The migration tool is available for download as a ZIP file using a pre-signed address from an S3 bucket until April 23, 2026. + ```powershell + curl "https://commercial-acceptance.downloads.chef.co/stable/migrate-ice/versions/latest?license_id=" + ``` + + Replace `` with your Progress Chef License ID. + + The response returns the latest version number. Use this version to download the migration tool package. + +1. Download the migration tool. + + {{< accordion-list id="download-migration-tool-curl-powershell-windows" data-allow-all-closed="true" >}} + + {{< accordion-item accordion-title="Download migration tool with curl" accordion-title-link="download-migration-tool-curl-windows" >}} Using curl: ```powershell - curl -o migration-tools-1.1.rc3-windows.zip "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/migrate-ice/1.1.RC3/windows/migration-tools-1.1.rc3-windows.zip?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=xyfZ7g7D5jLF5jY%2B8DfBkEedSUA%3D&Expires=1780533399" + curl -o migration-tools--windows.zip "https://commercial-acceptance.downloads.chef.co/current/migrate-ice/packages?v=&license_id=" ``` + Replace: + + - `` with the version number from the previous step + - `` with your Progress Chef License ID + + {{< /accordion-item >}} + + {{< accordion-item accordion-title="Download migration tool with PowerShell" accordion-title-link="download-migration-tool-powershell-windows" >}} + Using PowerShell: ```powershell - Invoke-WebRequest -Uri "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/migrate-ice/1.1.RC3/windows/migration-tools-1.1.rc3-windows.zip?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=xyfZ7g7D5jLF5jY%2B8DfBkEedSUA%3D&Expires=1780533399" -OutFile "migration-tools-1.1.rc3-windows.zip" + Invoke-WebRequest -Uri "https://commercial-acceptance.downloads.chef.co/current/migrate-ice/packages?v=&license_id=" -OutFile "migration-tools--windows.zip" ``` + Replace: + + - `` with the version number from the previous step + - `` with your Progress Chef License ID + + {{< /accordion-item >}} + + {{< /accordion-list >}} + 1. Extract the migration tool. ```powershell mkdir C:\migrate-tool - move "migration-tools-1.1.rc3-windows.zip" "C:\migrate-tool\" + move "migration-tools--windows.zip" "C:\migrate-tool\" cd C:\migrate-tool - Expand-Archive -Path "migration-tools-1.1.rc3-windows.zip" -DestinationPath "." + Expand-Archive -Path "migration-tools--windows.zip" -DestinationPath "." ``` 1. Optional: Verify that the migration tool works. ```powershell - .\chef-migrate --help + .\migrate-ice --help ``` The migration tool returns available commands and usage guidelines. -1. Upgrade Chef Infra Client using [`chef-migrate apply`](reference). +1. Upgrade Chef Infra Client using [`migrate-ice apply`](reference). + + You can upgrade Chef Infra Client by specifying the download URL or a version number. + + {{< accordion-list id="upgrade-chef-infra-client-windows" data-allow-all-closed="true" >}} + + {{< accordion-item accordion-title="Specify download URL" accordion-title-link="upgrade-chef-infra-client-url-windows" >}} ```powershell - .\chef-migrate apply online --download-url "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/chef-ice/19.2.RC3/windows/x86_64/chef-ice-19.2.rc3-windows.tar.gz?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=2jIjDACxF0EYf8yICEp698kt0xY%3D&Expires=1780533373" --license-key "" + .\migrate-ice apply online --download-url "" ``` - Replace `` with your Progress Chef License key. + Replace `` with the Chef Infra Client package download URL. + + {{< /accordion-item >}} + + {{< accordion-item accordion-title="Specify version number" accordion-title-link="upgrade-chef-infra-client-version-windows" >}} + + ```powershell + .\migrate-ice apply online --chef-version --license-key "" + ``` + + Replace: + + - `` with the Chef Infra Client version number (for example, `19.1.150`) + - `` with your Progress Chef License key + + {{< /accordion-item >}} + + {{< /accordion-list >}} 1. Verify the Chef Infra Client upgrade. diff --git a/content/install/proxies.md b/content/install/proxies.md new file mode 100644 index 0000000..3ca2934 --- /dev/null +++ b/content/install/proxies.md @@ -0,0 +1,192 @@ ++++ +title = "Working with proxies" +draft = false + +[menu] + [menu.install] + title = "Working with proxies" + identifier = "install/proxies.md Working with Proxies" + parent = "install" + weight = 55 ++++ + +In an environment that requires proxies to reach the Internet, many Chef +commands won't work until they're configured correctly. To configure +Chef to work in an environment that requires proxies, set the +`http_proxy`, `https_proxy`, `ftp_proxy`, and/or `no_proxy` environment +variables to specify the proxy settings using a lowercase value. + +## Windows + +{{< readfile file="content/reusable/md/proxy_windows.md" >}} + +## Linux + +To determine the current proxy server on the macOS and Linux platforms, +check the environment variables. Run the following: + +```bash +env | grep -i http_proxy +``` + +If an environment variable is set, it **MUST** be lowercase. If it's +not, add a lowercase version of that proxy variable to the shell (for example +`~/.bashrc`) using one (or more) the following commands. + +For HTTP: + +```bash +export http_proxy=http://myproxy.com:3168 +``` + +For HTTPS: + +```bash +export https_proxy=http://myproxy.com:3168 +``` + +For FTP: + +```bash +export ftp_proxy=ftp://myproxy.com:3168 +``` + +## Proxy Settings + +Proxy settings are defined in configuration files for Chef Infra Client +and for knife and may be specified for HTTP, HTTPS, and FTP. + +### HTTP + +Use the following settings in the client.rb or config.rb files for +environments that use an HTTP proxy: + + ++++ + + + + + + + + + + + + + + + + + + + + +
SettingDescription
http_proxyThe proxy server for HTTP connections. Default value: nil.
http_proxy_passThe password for the proxy server when the proxy server is using an HTTP connection. Default value: nil.
http_proxy_userThe user name for the proxy server when the proxy server is using an HTTP connection. Default value: nil.
+ +### HTTPS + +Use the following settings in the client.rb or config.rb files for +environments that use an HTTPS proxy: + + ++++ + + + + + + + + + + + + + + + + + + + + +
SettingDescription
https_proxyThe proxy server for HTTPS connections. Default value: nil.
https_proxy_passThe password for the proxy server when the proxy server is using an HTTPS connection. Default value: nil.
https_proxy_userThe user name for the proxy server when the proxy server is using an HTTPS connection. Default value: nil.
+ +### FTP + +Use the following settings in the client.rb or config.rb files for +environments that use an FTP proxy: + + ++++ + + + + + + + + + + + + + + + + + + + + +
SettingDescription
ftp_proxyThe proxy server for FTP connections.
ftp_proxy_passThe password for the proxy server when the proxy server is using an FTP connection. Default value: nil.
ftp_proxy_userThe user name for the proxy server when the proxy server is using an FTP connection. Default value: nil.
+ +### No Proxy + +The `no_proxy` setting is used to specify addresses for which the proxy +shouldn't be used. This can be a single address or a comma-separated +list of addresses. + +Example: + +```ruby +no_proxy 'test.example.com,test.example2.com,test.example3.com' +``` + +{{< note >}} + +Wildcard matching may be used in the `no_proxy` list---such as +`no_proxy '*.*.example.*'`---however, many situations require hostnames +to be specified explicitly (that's, "without wildcards"). + +{{< /note >}} + +## Environment Variables + +Consider the following for situations where environment variables are +used to set the proxy: + +- Proxy settings may not be honored by all applications. For example, + proxy settings may be ignored by the underlying application when + specifying a `ftp` source with a `remote_file` resource. Consider a + workaround. For example, in this situation try doing a `wget` with + an `ftp` URL instead. +- Proxy settings may be honored inconsistently by applications. For + example, the behavior of the `no_proxy` setting may not work with + certain applications when wildcards are specified. Consider + specifying the hostnames without using wildcards. + +### ENV + +{{< readfile file="content/reusable/md/proxy_env.md" >}} diff --git a/content/install/system_requirements.md b/content/install/system_requirements.md new file mode 100644 index 0000000..f50f38e --- /dev/null +++ b/content/install/system_requirements.md @@ -0,0 +1,37 @@ ++++ +title = "System requirements" +draft = false + +[menu] + [menu.install] + title = "System requirements" + identifier = "install/chef_system_requirements.md System Requirements" + parent = "install" + weight = 15 ++++ + +Before you bootstrap Chef Infra Client on nodes: + +1. Install and configure Chef Infra Server +1. Install and configure Chef Workstation on your local computer + +## Chef Infra Client requirements + +- The recommended amount of RAM available to Chef Infra Client during + a Chef Infra Client run is 512MB +- The Chef Infra Client binaries are stored in the `/opt/chef` + directory, which requires a minimum of 200MB of disk space. On + Windows, the Chef Infra Client binaries can be found in + `C:\opscode\`, and they require a minimum of 600MB of disk space. +- The processor must be [supported](https://docs.chef.io/platforms/). We recommend + a 1 gigahertz (GHz) or faster processor, but the processor speed + should be based on the other system loads. +- Chef Infra Client caches to `/var/chef/cache` during a Chef Infra + Client run. This is the location in which downloaded cookbooks, + packages required by those cookbooks, and other large files are + stored. This directory requires enough space to save all of this + data and should be generously sized. 5GB is a safe number as a + starting point, but tune the size of `/var/chef/cache` as necessary. + This location is tunable in a node's + [client.rb](/install/config_rb_client/) file using the + `file_cache_path` setting. diff --git a/content/integrations/azure_chef_cli.md b/content/integrations/azure_chef_cli.md new file mode 100644 index 0000000..598ef6f --- /dev/null +++ b/content/integrations/azure_chef_cli.md @@ -0,0 +1,332 @@ ++++ +title = "Microsoft Azure CLI" +draft = false + +[menu] + [menu.integrations] + title = "Microsoft Azure Chef Extension" + identifier = "integrations/azure/azure_chef_cli.md Microsoft Azure Chef Extension" + parent = "integrations/azure" + weight = 40 ++++ + +The Azure Chef Extension is an extension for Microsoft Azure to enable +Chef on virtual machine instances. The extension makes available two +Windows PowerShell cmdlets and two Microsoft Azure CLI commands. + +## Azure CLI + +If the Microsoft Azure [cross-platform command line tool +(Xplat-CLI)](https://github.com/Azure/azure-xplat-cli) is installed on +the workstation along with the Azure Chef Extension, you can use the `get-chef` and +`set-chef` extensions to manage Chef running on virtual +machines in Microsoft Azure. + +### get-chef + +Use the `get-chef` command to get the details for the Azure Chef +Extension that's running on the named virtual machine. + +#### Syntax + +This command has the following syntax: + +```bash +azure vm extension get-chef VM_NAME +``` + +### set-chef + +Use the `set-chef` command to enable Chef on any virtual machine running +on Microsoft Azure. + +#### Syntax + +This command has the following syntax: + +```bash +azure vm extension set-chef VM_NAME (options) +``` + +#### Options + +This command has the following options: + +`-a`, `--auto-update-client` + +: Automatically update Chef Infra Client. Set to `true` to automatically update the version of the Azure Chef Extension when the virtual machine is restarted. For example, if this option is enabled, a virtual machine that has version `1205.12.2.0` will be updated automatically to `1205.12.2.1` when it's published. Default value: `false`. + +`-b`, `--disable` + +: Disable the Azure Chef Extension extension. + +`-c PATH_TO_CONFIG`, `--client-config PATH_TO_CONFIG` + +: The path to the `client.rb` file. + +`-C CLIENT_PEM`, `--client-pem CLIENT_PEM` + +: The location of the file that contains the client key. Default value: `/etc/chef/client.pem`. + +`-D`, `--delete-chef-config` + +: Disable the Azure Chef Extension extension. + +`-j JSON`, `--bootstrap-options JSON` + +: A JSON string that's added to the first run of a Chef Infra Client. + For example: + + ```bash + -j '{"chef_node_name":"test_node"}' + ``` + + Supported options: `"chef_node_name"`, `"chef_server_url"`(required), `"environment"`, `"secret"`, and `"validation_client_name"` (required). + +`-O VALIDATOR_PEM`, `--validation-pem VALIDATOR_PEM` + +: The location of the file that contains the key used when a Chef Infra Client is registered with a Chef Infra Server. A validation key is signed using the `validation_client_name` for authentication. Default value: `/etc/chef/validation.pem`. + +`-R RUN_LIST`, `--run-list RUN_LIST` + +: A comma-separated list of roles and/or recipes to be applied. + +`-u`, `--uninstall` + +: Uninstall the Azure Chef Extension. + +`-V NUMBER`, `--version NUMBER` + +: Specify the version number for the Azure Chef Extension extension. Default is to use the latest extension's version number. + +#### Examples + +The following examples show how to use this knife subcommand: + +##### Create a virtual machine + +```bash +azure vm create your-vm-name MSFT__Windows-Server-2012 yourusername yourpassword --location "West US" -r +``` + +##### Set the Chef extension without a run-list + +```bash +azure vm extension set-chef your-vm-name --validation-pem ~/chef-repo/.chef/testorg-validator.pem --client-config ~/chef-repo/.chef/client.rb --version "1201.12" +``` + +##### Set the Chef extension with a run-list + +```bash +azure vm extension set-chef your-vm-name --validation-pem ~/chef-repo/.chef/testorg-validator.pem --client-config ~/chef-repo/.chef/client.rb --version "1201.12" -R 'recipe[your_cookbook_name::your_recipe_name]' +``` + +##### Azure Resource Manager (ARM) templates + +If you are using Azure Resource Manager templates to create your infrastructure you can use the Chef extension to have Azure handle the bootstrapping/configuration of your node to your Chef Infra Server. + +### Options + +The extension has the following options that can be provided in the +**settings** hash. + +`runlist` + +: A comma-separated list of roles and/or recipes to be applied. + +`client_rb` + +: A JSON escaped string containing the content of your `client.rb` file. + +`validation_key_format` + +: Tells the extension whether the supplied validation key is `plaintext` or `base64encoded`. + + {{< note >}} + + If using the Chef extension in an ARM template, it's recommended that you base64 encode your validation key and set this option to `base64encoded` + + {{< /note >}} + +`bootstrap_version` + +: The version of Chef Infra Client that will be installed on the system. **Linux only** + + {{< note >}} + Due to constraints in Azure, the `bootstrap_version` option is only available on the `LinuxChefClient` extension. + {{< /note >}} + +`bootstrap_channel` + +: Specify the [channel](https://docs.chef.io/packages/) for installing the Chef Infra Client version. Options are `stable`, `current` or `unstable` release channels. + +`chef_package_path` + +: Specifies a local path to install Chef Infra Client from. This feature is mainly used for cases where there are restrictions on internet access. + + {{< note >}} + Azure extensions have network access limitations. See the [Azure documentation](https://docs.microsoft.com/en-us/azure/virtual-machines/extensions/features-linux#network-access) for more information. + {{< /note >}} + +`CHEF_LICENSE` + +: Chef Infra Client 15+ requires accepting the CHEF EULA license. Set `CHEF_LICENSE` to one of these values `accept`, `accept-silent` or `accept-no-persist`. Refer to [CHEF EULA license](https://docs.chef.io/licensing/accept//#accept-the-chef-eula) + +`hints` + +: Specifies the [Ohai Hints](/features/ohai/#hints) to be set in the Ohai configuration of the target node. + +`chef_package_url` + +: Specifies a URL to download and install the Chef Infra Client package (.msi .rpm .deb) from. + +`bootstrap_options` + +: A hash of the following options: `chef_node_name`, `chef_server_url`, `environment`, `secret`, and `validation_client_name`. + + {{< note >}} + + Options that are supplied in the bootstrap items will take precedence over any conflicts found in the `client.rb` file. + + {{< /note >}} + +`chef_node_name` + +: Determines which configuration should be applied and sets the `client_name`, which is the name used when authenticating to a Chef Infra Server. The default value is the Chef Infra Client FQDN, as detected by Ohai. In general, Chef recommends that you leave this setting blank and let Ohai assign the FQDN of the node as the `node_name` during each Chef Infra Client run. + +`chef_server_url` + +: The URL for Chef Infra Server. + +`environment` + +: The environment this machine will be placed in on your Chef Infra Server. + +`secret` + +: The encryption key that's used for values contained within a data bag item. + +`validation_client_name` + +: The name of the chef-validator key that Chef Infra Client uses to access Chef Infra Server during the initial Chef Infra Client run. + +`node_ssl_verify_mode` + +: Set the verify mode for HTTPS requests. + +`node_verify_api_cert` + +: Verify the SSL certificate on Chef Infra Server. When `true`, Chef Infra Client always verifies the SSL certificate. When `false`, Chef Infra Client uses the value of `ssl_verify_mode` to determine if the SSL certificate requires verification. + +#### Protected settings + +The following options can be provided to the extension through the `protectedSettings` hash: + +`validation_key` + +: The contents of your organization validator key, the format is dependent on `validation_key_format`. + +`chef_server_crt` + +: The SSL certificate of your Chef Infra Server that will be added to the trusted certificates. + +`client_pem` + +: A client key that will be used to communication with Chef Infra Server. + +### Examples + +The following examples show how you can install and configure Chef Infra Client from an ARM template. + +#### Install the Azure Chef extension on a Linux system + +```json +{ + "type": "Microsoft.Compute/virtualMachines/extensions", + "name": "myVirtualMachine/LinuxChefClient", + "apiVersion": "2015-05-01-preview", + "location": "westus", + "properties": { + "publisher": "Chef.Bootstrap.WindowsAzure", + "type": "LinuxChefClient", + "typeHandlerVersion": "1210.12", + "settings": { + "bootstrap_options": { + "chef_node_name": "node1", + "chef_server_url": "https://api.chef.io/organizations/my-chef-organization", + "validation_client_name": "my-chef-organization-validator" + }, + "runlist": "recipe[awesome_customers_rhel],recipe[yum],role[base]", + "validation_key_format": "plaintext" + }, + "protectedSettings": { + "validation_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpQIB..\n67VT3Dg=\n-----END RSA PRIVATE KEY-----" + } + } + } +``` + +#### Install the Azure Chef extension on a Windows system + +```json +{ + "type": "Microsoft.Compute/virtualMachines/extensions", + "name": "myVirtualMachine/ChefClient", + "apiVersion": "2015-05-01-preview", + "location": "westus", + "properties": { + "publisher": "Chef.Bootstrap.WindowsAzure", + "type": "ChefClient", + "typeHandlerVersion": "1210.12", + "settings": { + "bootstrap_options": { + "chef_node_name": "node12", + "chef_server_url": "https://api.chef.io/organizations/my-chef-organization", + "validation_client_name": "my-chef-organization-validator" + }, + "runlist": "recipe[awesome_customers_windows],recipe[iis],role[windows_base]", + "chef_package_url" : "https://download.example.com/chef-client-15.11.8-1-x64.msi", + "validation_key_format": "plaintext" + }, + "protectedSettings": { + "validation_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpQIB..\n67VT3Dg=\n-----END RSA PRIVATE KEY-----" + } + } +} +``` + +#### Install the Azure Chef extension on a Linux system with SSL peer verification turned off and given a data bag secret + +```json +{ + "type": "Microsoft.Compute/virtualMachines/extensions", + "name": "myVirtualMachine/LinuxChefClient", + "apiVersion": "2015-05-01-preview", + "location": "westus", + "properties": { + "publisher": "Chef.Bootstrap.WindowsAzure", + "type": "LinuxChefClient", + "typeHandlerVersion": "1210.12", + "settings": { + "bootstrap_options": { + "chef_node_name": "node1", + "chef_server_url": "https://api.chef.io/organizations/my-chef-organization", + "validation_client_name": "my-chef-organization-validator", + "node_ssl_verify_mode": "none", + "secret": "KCYWGXxSrkgR..." + }, + "runlist": "recipe[awesome_customers_rhel],recipe[yum],role[base]", + "validation_key_format": "base64encoded" + }, + "protectedSettings": { + "validation_key": "LS0tLS1CRUdJTiBSU0EgUFJ...FIEtFWS0tLS0t" + } + } + } +``` + +{{< note >}} + +In this example the validator key is base64 encoded, which is a recommended approach when using the Azure Chef extension in an ARM template. + +{{< /note >}} diff --git a/content/integrations/azure_cwa_cloud_shell.md b/content/integrations/azure_cwa_cloud_shell.md new file mode 100644 index 0000000..49786d0 --- /dev/null +++ b/content/integrations/azure_cwa_cloud_shell.md @@ -0,0 +1,39 @@ ++++ +title = "Chef Workstation in Azure Cloud Shell" +draft = false + +[menu] + [menu.integrations] + title = "Chef Workstation in Azure Cloud Shell" + identifier = "integrations/azure/azure_cwa_cloud_shell.md Chef Workstation in Azure Cloud Shell" + parent = "integrations/azure" + weight = 20 ++++ + +Chef Workstation is available in Azure Cloud Shell, allowing users to +run ad-hoc configurations on target systems and any other Chef command +when connected to an Azure subscription. This makes all of the Chef +command line tools available, without installing software on a local +machine. + +Chef Workstation on Azure Cloud Shell lets you use: + +- [chef](https://docs.chef.io/workstation/ctl_chef/) +- [kitchen](https://docs.chef.io/workstation/ctl_kitchen/) +- [inspec](https://docs.chef.io/inspec/latest/cli/) +- [knife](https://docs.chef.io/workstation/knife/) +- [cookstyle](https://docs.chef.io/workstation/cookstyle/) +- [chef-run](https://docs.chef.io/workstation/chef_run/) + +Combine the Chef Workstation command utilities with the other tools +available in Cloud Shell, such as git, az-cli, terraform to write your +infrastructure and compliance automation from the browser--without the +need for a local shell. + +## Azure Cloud Shell Installation + +Ensure you have an accessible Azure Cloud Shell instance. You may need +to create a storage account to use Azure Cloud Shell if you haven't used +it before in this tenant. For more information on accessing, setting up, +and using Azure Cloud Shell, see the [Cloud Shell +Documentation](https://docs.microsoft.com/en-us/azure/cloud-shell/quickstart). diff --git a/content/integrations/azure_powershell.md b/content/integrations/azure_powershell.md new file mode 100644 index 0000000..e0a6135 --- /dev/null +++ b/content/integrations/azure_powershell.md @@ -0,0 +1,190 @@ ++++ +title = "Microsoft Azure PowerShell" +draft = false + +[menu] + [menu.integrations] +title = "Microsoft Azure PowerShell" +identifier = "integrations/azure/azure_powershell.md Microsoft Azure PowerShell" +parent = "integrations/azure" +weight = 30 ++++ + +## PowerShell Cmdlets + +If Windows PowerShell is installed on the workstation, along with the Azure Chef Extension, the `Get-AzureVMChefExtension` and `Set-AzureVMChefExtension` extensions may be used to manage Chef running +on virtual machines in Microsoft Azure. + +### Get-AzureVMChefExtension + +Use the `Get-AzureVMChefExtension` cmdlet to get the details for the +Azure Chef Extension that's running on the named virtual machine. + +#### Syntax + +This cmdlet has the following syntax: + +```bash +Get-AzureVMChefExtension -VM +``` + +#### Example + +The following examples show how to use the `Get-AzureVMChefExtension` +cmdlet: + +##### Get details for a virtual machine + +```bash +Get-AzureVM -ServiceName cloudservice1 -Name azurevm1 | Get-AzureVMExtension +``` + +### Set-AzureVMChefExtension + +Use the `Set-AzureVMChefExtension` cmdlet to enable Chef on any virtual +machine running on Microsoft Azure. + +#### Syntax + +This cmdlet has the following syntax. + +For Windows: + +```bash +Set-AzureVMChefExtension -ValidationPem -VM -Windows [-ChefServerUrl ] [-ClientRb ] [-OrganizationName ] [-RunList ] [-ValidationClientName ] [-Version ] [ ] +``` + +For Linux: + +```bash +Set-AzureVMChefExtension -Linux -ValidationPem -VM [-ChefServerUrl ] [-ClientRb ] [-OrganizationName ] [-RunList ] [-ValidationClientName ] [-Version ] [ ] +``` + +#### Options + +This cmdlet has the following options: + +`-AutoUpdateChefClient` + +: Automatically update . Set to `true` to automatically update the version of the Azure Chef Extension when the virtual machine is restarted. For example, if this option is enabled, a virtual machine that has version `1205.12.2.0` will be updated automatically to `1205.12.2.1` when it's published. + +`-BootstrapOptions ` + +: A JSON string that's added to the first run of a Chef Infra Client. + + For example: + + ```bash + -BootstrapOptions '{"chef_node_name":"test_node"}' + ``` + + Supported options: `"chef_node_name"`, `"chef_server_url"` (required), `"environment"`, `"secret"`, and `"validation_client_name"` (required). + +`-ChefServerUrl ` + +: The URL for Chef Infra Server. + +`-ClientRb ` + +: The path to the `client.rb` file. + +`-DeleteChefConfig` + +: Disable the Azure Chef Extension extension. + +`-Linux` + +: Sets the Azure Chef Extension to run Linux. + +`-OrganizationName ` + +: The name of the organization on Chef Infra Server. + +`-RunList ` + +: A comma-separated list of roles and/or recipes to be applied. + +`-ValidationClientName ` + +: The name of the chef-validator key Chef Infra Client uses to access Chef Infra Server during the initial Chef Infra Client run. + +`-ValidationPem ` + +: The location of the file that contains the key used when a Chef Infra Client is registered with a Chef Infra Server. A validation key is signed using the `validation_client_name` for authentication. Default value: `/etc/chef/validation.pem`. + +`-Version ` + +: Specify the version number for the Azure Chef Extension extension. Default is to use the latest extension's version number. + +`-Windows` + +: Sets the Azure Chef Extension to run Windows. + +#### Examples + +The following examples show how to use the `Set-AzureVMChefExtension` +cmdlet: + +##### Create Windows virtual machine + +```bash +$vm1 = "azurechefwin" +$svc = "azurechefwin" +$username = 'azure' +$password = 'azure@123' + +$img = "a699494373c04fc0bc8f2bb1389d6106__Windows-Server-2012-R2-201406.01-en.us-127GB.vhd" + +$vmObj1 = New-AzureVMConfig -Name $vm1 -InstanceSize Small -ImageName $img + +$vmObj1 = Add-AzureProvisioningConfig -VM $vmObj1 -Password $password -AdminUsername $username -Windows + +# set azure chef extension +$vmObj1 = Set-AzureVMChefExtension -VM $vmObj1 -ValidationPem "C:\\users\\azure\\msazurechef-validator.pem" -ClientRb +"C:\\users\\azure\\client.rb" -RunList "getting-started" -Windows + +New-AzureVM -Location 'West US' -ServiceName $svc -VM $vmObj1 +``` + +##### Create CentOS virtual machine + +```bash +$vm1 = "azurecheflnx" +$svc = "azurecheflnx" +$username = 'azure' +$password = 'azure@123' + +# CentOS image id +$img = "5112500ae3b842c8b9c604889f8753c3__OpenLogic-CentOS-71-20150605" + +$vmObj1 = New-AzureVMConfig -Name $vm1 -InstanceSize Small -ImageName $img + +$vmObj1 = Add-AzureProvisioningConfig -VM $vmObj1 -Password $password -Linux -LinuxUser $username + +# set azure chef extension +$vmObj1 = Set-AzureVMChefExtension -VM $vmObj1 -ValidationPem "C:\\users\\azure\\msazurechef-validator.pem" -ClientRb +"C:\\users\\azure\\client.rb" -RunList "getting-started" -Linux + +New-AzureVM -Location 'West US' -ServiceName $svc -VM $vmObj1 +``` + +##### Create Ubuntu virtual machine + +```bash +$vm1 = "azurecheflnx" +$svc = "azurecheflnx" +$username = 'azure' +$password = 'azure@123' + +$img = "b39f27a8b8c64d52b05eac6a62ebad85__ubuntu-20_04_5-LTS-amd64-server-20150127-en-us-30GB" + +$vmObj1 = New-AzureVMConfig -Name $vm1 -InstanceSize Small -ImageName $img + +$vmObj1 = Add-AzureProvisioningConfig -VM $vmObj1 -Password $password -Linux -LinuxUser $username + +# set azure chef extension +$vmObj1 = Set-AzureVMChefExtension -VM $vmObj1 -ValidationPem "C:\\users\\azure\\msazurechef-validator.pem" -ClientRb +"C:\\users\\azure\\client.rb" -RunList "getting-started" -Linux + +New-AzureVM -Location 'West US' -ServiceName $svc -VM $vmObj1 +``` diff --git a/content/integrations/google.md b/content/integrations/google.md new file mode 100644 index 0000000..a52164a --- /dev/null +++ b/content/integrations/google.md @@ -0,0 +1,122 @@ ++++ +title = "Chef and Google" +draft = false + +[menu] + [menu.integrations] + title = "Google Cloud Platform" + identifier = "integrations/google.md Google Cloud Platform" + parent = "integrations" + weight = 20 ++++ + +Google Cloud Platform is a suite of cloud computing services that run on +the same infrastructure that Google uses internally for its end-user +products, such as Google Search and YouTube. Alongside a set of +management tools, it provides a series of modular cloud services +including computing, data storage, data analytics, and machine learning. +This page outlines the different tools that can be used to integrate +Chef with the Google Cloud Platform. + +## knife-google + +[\[GitHub\]](https://github.com/chef/knife-google) + +This plugin gives knife the ability to create, bootstrap, and manage +Google Compute Engine (GCE) instances. + +### Authentication and Authorization + +`knife-google` relies on the Google Auth Library to handle +authentication to the Google Cloud API. The auth library expects to find +a JSON credentials file located under +`~/.config/gcloud/application_default_credentials.json`. + +The easiest way to create this is to download and install the [Google +Cloud SDK](https://cloud.google.com/sdk/) and run the +`gcloud auth application-default login` command, which will create the +credentials file for you. + +If you already have a file you'd like to use that's in a different +location, set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable +with the full path to that file. + +These are the necessary settings for your `config.rb` file: + +```ruby +knife[:gce_project] = 'my-test-project' +knife[:gce_zone] = 'us-east1-b' +``` + +### Usage Examples + +**Create a server:** + +```bash +knife google server create test-instance-1 --gce-image centos-7-v20160219 \ +--gce-machine-type n1-standard-2 --gce-public-ip ephemeral --connection-user myuser \ +--identity-file /Users/myuser/.ssh/google_compute_engine +``` + +**Delete multiple servers:** + +```bash +knife google server delete my-instance-1 my-instance-2 --purge +``` + +**List all servers:** + +```bash +knife google server list +``` + +## kitchen-google + +[\[GitHub\]](https://github.com/test-kitchen/kitchen-google) + +A test kitchen driver for Google Cloud Platform. + +### Usage Examples + +The following is a basic `kitchen.yml` example: + +```yaml +--- +driver: + name: gce + project: mycompany-test + zone: us-east1-c + email: me@mycompany.com + tags: + - devteam + - test-kitchen + service_account_scopes: + - devstorage.read_write + - userinfo.email + +provisioner: + name: chef_zero + +transport: + username: chefuser + +platforms: + - name: centos-7 + driver: + image_project: centos-cloud + image_name: centos-7-v20170124 + - name: ubuntu-18.04 + driver: + image_project: ubuntu-os-cloud + image_family: ubuntu-1804-lts + - name: windows + driver: + image_project: windows-cloud + image_name: windows-server-2012-r2-dc-v20170117 + disk_size: 50 +suites: + - name: default + run_list: + - recipe[COOKBOOK::default] + attributes: +``` diff --git a/content/integrations/install_windows.md b/content/integrations/install_windows.md new file mode 100644 index 0000000..5c8ceeb --- /dev/null +++ b/content/integrations/install_windows.md @@ -0,0 +1,51 @@ ++++ +title = "Install Chef Infra Client on Windows Nodes" +draft = false + +[menu] + [menu.integrations] + title = "Windows Installation Guide" + identifier = "integrations/windows/install_windows.md Chef Infra Client on Windows" + parent = "integrations/windows" + weight = 20 ++++ + +## Installation Methods + +There are several methods available to install Chef Infra Client depending on the needs of your organization. + +{{< readfile file="content/reusable/md/windows_install_overview.md" >}} + +### Use knife CLI + +{{< readfile file="content/reusable/md/workstation/knife_windows_summary.md" >}} + +#### Necessary Ports + +{{< readfile file="content/reusable/md/workstation/knife_windows_winrm_ports.md" >}} + +### Use MSI Installer + +A Microsoft Installer Package (MSI) is available for installing Chef Infra Client on a Windows machine at [Chef Downloads](https://www.chef.io/downloads). + +{{< readfile file="content/reusable/md/windows_msiexec.md" >}} + +#### ADDLOCAL Options + +{{< readfile file="content/reusable/md/windows_msiexec_addlocal.md" >}} + +#### Running as a Scheduled Task + +On Windows, run Chef Infra Client periodically as a scheduled task. Scheduled tasks provides visibility, configurability, and reliability around log rotation and permissions. You can configure the Chef Infra Client to run as a scheduled task using the [chef_client_scheduled_task](/resources/bundled/chef_client_scheduled_task/) resource. + +#### Scheduled Task Options + +{{< readfile file="content/reusable/md/install_chef_client_windows_as_scheduled_task.md" >}} + +### Use an Existing Process + +{{< readfile file="content/reusable/md/windows_install_system_center.md" >}} + +### PATH System Variable + +{{< readfile file="content/reusable/md/windows_environment_variable_path.md" >}} diff --git a/content/integrations/vmware.md b/content/integrations/vmware.md new file mode 100644 index 0000000..c4afc83 --- /dev/null +++ b/content/integrations/vmware.md @@ -0,0 +1,535 @@ ++++ +title = "Chef and VMware" +draft = false + +[menu] + [menu.integrations] + title = "VMware" + identifier = "integrations/vmware.md VMware" + parent = "integrations" + weight = 30 ++++ + +VMware, Inc. is a subsidiary of Dell Technologies that provides cloud +computing and platform virtualization software and services. This page +outlines the different tools that can be used to integrate Chef with the +VMware platform. + +For discussions on VMware and Chef, visit the +[VMware{code}](https://code.vmware.com/web/code/join) Slack team, +located in the **#chef** channel. + +## knife + +There are multiple knife plugins that interact with the VMware stack in +different ways. The following knife plugins are directly supported by +Chef: + +### knife-vsphere + +[[GitHub]](https://github.com/chef-partners/knife-vsphere) + +- Supports vCenter \> 5.0 +- Most VMware compute use cases are covered +- The main starting point for Chef and VMware + +These are the necessary settings for your `config.rb` file: + +```ruby +knife[:vsphere_host] = 'vcenter-hostname' +knife[:vsphere_user] = 'privileged username' # Domain logins may need to be "user@domain.com" +knife[:vsphere_pass] = 'password' # or %Q(mypasswordwithfunnycharacters) +knife[:vsphere_dc] = 'your-datacenter' +knife[:vsphere_insecure] = true # Set this if you have self signed certs +``` + +#### Usage Examples + +**Clone from a VMware template and bootstrap Chef with generic DHCP +options:** + +```bash +knife vsphere vm clone MACHINENAME --template TEMPLATENAME --bootstrap --cips dhcp +``` + +**Clone a virtual machine from a VMware template, use a customization +template called "SPEC" to assist the bootstrapping process, and specify +the SSH user and password:** + +```bash +knife vsphere vm clone MACHINENAME --template TEMPLATENAME --bootstrap --cips dhcp \ +--cspec SPEC --connection-user USER --connection-password PASSWORD +``` + +{{< note >}} + +Add a `-f FOLDERNAME` if you put your `--template` in a directory other +than the root folder. Use `--dest-folder FOLDERNAME` if you want your VM +created in `FOLDERNAME` instead of the root folder. + +{{< /note >}} + +**Clone from a folder into the data center root directory:** + +```bash +knife vsphere vm clone MACHINENAME --template TEMPLATENAME -f /path/to/template \ +--bootstrap --start --cips dhcp --dest-folder / +``` + +**List the available VMware templates:** + +```bash +knife vsphere template list +Template Name: ubuntu16-template +knife vsphere template list -f FOLDERNAME +Template Name: centos7-template +``` + +**Delete a machine:** + +```bash +knife vsphere vm delete MACHINENAME +``` + +This command can be used with the `-P` option to remove the machine from +Chef Infra Server. + +### knife-vcenter + +[[GitHub]](https://github.com/chef/knife-vcenter) + +- Supports vCenter >= 6.5 REST API +- Supports the main use cases of knife: `bootstrap`, `create`, + `destroy`, and `list` +- If you have the + [VCSA](https://docs.vmware.com/en/VMware-vSphere/6.5/com.vmware.vsphere.vcsa.doc/GUID-223C2821-BD98-4C7A-936B-7DBE96291BA4.html) + or are planning on upgrading to vCenter 6.5+, this is the plugin to + use + +The main settings for your `config.rb`: + +```ruby +knife[:vcenter_username] = 'USERNAME' +knife[:vcenter_password] = 'PASSWORD' +knife[:vcenter_host] = '172.16.20.2' +knife[:vcenter_disable_ssl_verify] = true # if you want to disable SSL checking +``` + +#### Usage Examples + +**Clone a machine:** + +```bash +knife vcenter vm clone example-01 --targethost 172.16.20.3 --folder example --connection-password \ +P@ssw0rd! --datacenter Datacenter --template ubuntu16-template -N example-01 +Creating new machine +Waiting for network interfaces to become available... +ID: vm-183 +Name: example-01 +Power State: POWERED_ON +Bootstrapping the server by using bootstrap_protocol: ssh and image_os_type: linux + +Waiting for sshd to host (10.0.0.167) +... +``` + +**Delete a machine:** + +```bash +knife vcenter vm delete example-01 -N example-01 --purge +``` + +The output is similar to the following: + +```bash +Creating new machine +Waiting for network interfaces to become available... +ID: vm-183 +Name: example-01 +Power State: POWERED_ON +Bootstrapping the server by using bootstrap_protocol: ssh and image_os_type: linux + +Waiting for sshd to host (10.0.0.167) +WARNING: Deleted node example-01 +WARNING: Deleted client example-01 +``` + +### knife-vrealize + +[[GitHub]](https://github.com/chef-partners/knife-vrealize) + +The knife-vrealize plugin supports both vRealize Automation and vRealize Orchestrator. + +{{< note >}} + +For knife-vrealize 6.0.4 and earlier, see the [documentation for knife-vrealize 6.0.4](https://github.com/chef/knife-vrealize/blob/v6.0.4/README.md) +and downgrade the [VMware vRA Gem](https://github.com/chef-partners/vmware-vra-gem) to version 1.7.0. + +{{< /note >}} + +{{< note >}} + +knife-vrealize 7.0.0 and later supports vRealize Automation 8.x. + +knife-vrealize 6.0.3 and earlier supports vRealize Automation 7.x. + +{{< /note >}} + +The knife-vrealize gem supports the main use cases of knife: `bootstrap`, `create`, `destroy`, and `list`. +It directly integrates with vRealize Automation to call out predetermined blueprints or catalogs, and +can integrate directly with vRealize Orchestrator to call out predetermined workflows. + +#### config.rb Settings + +The main settings for your config.rb file are: + +```ruby +knife[:vra_username] = 'USERNAME' +knife[:vra_password] = 'PASSWORD' +knife[:vra_base_url] = 'https://vra.example.local' +knife[:vra_tenant] = 'tenant' +knife[:vra_disable_ssl_verify] = true # if you want to disable SSL checking. +``` + +Additional `config.rb` settings are required to integrate with vRealize Orchestrator: + +```ruby +knife[:vro_username] = 'USERNAME' +knife[:vro_password] = 'PASSWORD' +knife[:vro_base_url] = 'https://vra.example.local:8281' +``` + +#### knife-vrealize Common Parameters + +`--image-mapping` +: The image mapping for the deployment which specifies the OS image for the virtual machine. + +`--flavor-mapping` +: The flavor mapping of the target deployment which specifies the CPU count and RAM of a VM. + +`--project-id` +: The project ID of the target deployment. + +`--name` +: The name of the newly created deployment. The name must be unique. + +`--version` +: The version of the catalog for the deployment. If left blank, the latest version will be used. + +`--ssh-password` +: If a Linux host, the password to use during bootstrap. + +`--winrm-password` +: If a Windows host, the password to use during bootstrap. + +`--image-os-type` +: Windows or Linux. + +`--bootstrap-protocol` +: WinRM or SSH + +`--server-create-timeout` +: The number of seconds to wait for the server to complete. Increase this if your vRealize Automation environments takes more than 10 minutes to give you a server. Default value: 600 seconds. + +`--bootstrap-version` +: Specify a specific Chef Infra Client version if your group isn't current. + +#### Usage Examples + +**Create a server from vRealize Automation:** + +If you want to create a server from a catalog blueprint, find the catalog ID with the +`knife vra catalog list` command. After the resource is created, knife will attempt to bootstrap it. + +Each blueprint may require different parameters to complete provisioning. See your vRealize Automation administrator with questions. knife will attempt to provide any helpful error messages from vRealize Automation if they're available. + +```bash +knife vra server create CATALOG_ID --name NAME --project-id PROJECT_ID \ + --image-mapping IMAGE_MAPPING --flavor-mapping FLAVOR_MAPPING --image-os-type OS_TYPE --connection-protocol PROTOCOL \ + -P PASSWORD --extra-param KEY=TYPE:VALUE +``` + +The output is similar to the following: + +```bash +Catalog request b1f13afe-d7c1-4647-8866-30681fc7f63d submitted. +Waiting for request to complete. +Current request status: CREATE_INPROGRESS............... +Catalog request complete. + +Request Status: CREATE_SUCCESSFUL + +Deployment ID: b1f13afe-d7c1-4647-8866-30681fc7f63d +Deployment Name: test_dep-2 +IP Address: 10.30.236.21 +Owner Names: USERNAME +Bootstrapping the server by using connection_protocol: ssh and image_os_type: linux + +Waiting for sshd to host (10.30.236.21)............ +... +``` + +**Delete a server from vRealize Automation:** + +```bash +knife vra server delete CATALOG_ID --purge +``` + +The output is similar to the following: + +```bash +Deployment ID: 2e1f6632-1613-41d1-a07c-6137c9639609 +Deployment Name: test_dep-2 +IP Address: 10.30.236.21 +Status: SUCCESS +Owner Names: USERNAME + +Do you really want to delete this server? (Y/N) y +Destroy request 5e390a9d-1340-489d-94be-b4eb1df98c53 submitted. +Waiting for request to complete. +Current request status: CHECKING_APPROVAL... +... +``` + +If you supply the `--purge` option, the server will also be removed from +the Chef Infra Server. + +**Execute a vRealize Orchestrator workflow:** + +This requires the workflow name. If your workflow name isn't unique in your vRealize Orchestrator workflow list, you +can specify a workflow ID with `--vro-workflow-id ID`. You can find the workflow ID from the vRealize Orchestrator UI; however, the workflow name is still required. + +```bash +knife vro workflow execute WORKFLOW_NAME KEY1=VALUE1 KEY2=VALUE2 +``` + +The output is similar to the following: + +```bash +Starting workflow execution... +Workflow execution 4028eece4effc046014f27da864d0187 started. Waiting for it to complete... +Workflow execution complete. + +Output Parameters: +outkey1: some value (string) + +Workflow Execution Log: +2015-08-13 09:17:57 -0700 info: cloudadmin: Workflow 'Knife Testing' has started +2015-08-13 09:17:58 -0700 info: cloudadmin: Workflow 'Knife Testing' has completed +``` + +## Test Kitchen + +The following Test Kitchen drivers for VMware are directly supported by +Chef: + +### kitchen-vsphere (chef-provisioning-vsphere) + +[[GitHub]](https://github.com/chef-partners/chef-provisioning-vsphere) + +- Built into the chef-provisioning-vsphere driver +- A community driven project, with Chef Partners maintaining the + releases +- Leverages the typical Test Kitchen workflow for vCenter \> 5.0+ +- There is a + [kitchen-vsphere](https://rubygems.org/gems/kitchen-vsphere) gem, + but it's not supported at this time + +#### Usage Examples + +There is an [example +cookbook](https://github.com/jjasghar/vsphere_testing) that attempts to +capture everything required. The following is a basic `kitchen.yml` +example: + +```yaml +--- +driver: +name: vsphere +driver_options: + host: FQDN or IP of vCenter + user: 'administrator@vsphere.local' + password: 'PASSWORD' + insecure: true +machine_options: + start_timeout: 600 + create_timeout: 600 + ready_timeout: 90 + bootstrap_options: + use_linked_clone: true + datacenter: 'Datacenter' + template_name: 'ubuntu16' + template_folder: 'Linux' + resource_pool: 'Cluster' + num_cpus: 2 + memory_mb: 4096 + ssh: + user: ubuntu + paranoid: false + password: PASSWORD + port: 22 + +provisioner: + name: chef_zero + sudo_command: sudo + +verifier: + name: inspec + +transport: + username: root or ssh enabled user + password: PASSWORD for root or user + +platforms: + - name: ubuntu-18.04 + - name: centos-8 + +suites: + - name: default + run_list: + - recipe[COOKBOOK::default] + attributes: +``` + +### kitchen-vcenter + +[[GitHub]](https://github.com/chef/kitchen-vcenter) + +- Supports vCenter \>= 6.5 REST API +- Leverages the typical Test Kitchen workflow for vCenter \>= 6.5+ +- If you have the + [VCSA](https://docs.vmware.com/en/VMware-vSphere/6.5/com.vmware.vsphere.vcsa.doc/GUID-223C2821-BD98-4C7A-936B-7DBE96291BA4.html) + or are planning on upgrading to vCenter 6.5+, use this plugin + +#### Usage Examples + +The following is a basic `kitchen.yml` for vCenter: + +```yaml +driver: + name: vcenter + vcenter_username: <%= ENV['VCENTER_USER'] || "administrator@vsphere.local" %> + vcenter_password: <%= ENV['VCENTER_PASSWORD'] || "password" %> + vcenter_host: vcenter.chef.io + vcenter_disable_ssl_verify: true + driver_config: + targethost: 172.16.20.41 + datacenter: "Datacenter" + +platforms: + - name: ubuntu-2004 + driver_config: + template: ubuntu16-template + - name: centos-8 + driver_config: + template: centos7-template +``` + +### kitchen-vra + +[[GitHub]](https://github.com/chef-partners/kitchen-vra) + +- An integration point with vRealize Automation and Test Kitchen +- For companies required to use vRealize Automation this is a natural progression for + Chef Development + +#### Usage Examples + +The following is a basic `kitchen.yml` example: + +```yaml +driver: + name: vra + username: user@corp.local + password: password + tenant: tenant + base_url: https://vra.corp.local + verify_ssl: true + +platforms: +- name: centos6 + driver: + catalog_id: e9db1084-d1c6-4c1f-8e3c-eb8f3dc574f9 +- name: centos7 + driver: + catalog_id: c4211950-ab07-42b1-ba80-8f5d3f2c8251 +``` + +### kitchen-vro + +[[GitHub]](https://github.com/chef-partners/kitchen-vro) + +- An integration point with vRealize Orchestrator and Test Kitchen +- Leverages specific Workflows in vRealize Orchestrator if it's required by VMware + admins + +#### Usage Examples + +The following is a basic `kitchen.yml` example: + +```yaml +driver: + name: vro + vro_username: user@domain.com + vro_password: password + vro_base_url: https://vra.corp.local:8281 + create_workflow_name: Create TK Server + destroy_workflow_name: Destroy TK Server + +platforms: + - name: centos + driver: + create_workflow_parameters: + os_name: centos + os_version: 6.7 + - name: windows + driver: + create_workflow_parameters: + os_name: windows + os_version: server2012 + cpus: 4 + memory: 4096 +``` + +## Chef InSpec + +The Chef InSpec VMware plugin is used to verify the vCenter and ESXi +VMware stack. + +### inspec-vmware + +[[GitHub]](https://github.com/chef/inspec-vmware) + +- Supports vCenter \> 5.0 +- 11 resources available at the time of writing, with more planned + +#### Usage Examples + +An example demo control: + +```ruby +control 'vmware-1' do + impact 0.7 + title 'Checks that soft power off is disabled' + describe vmware_vm_advancedsetting({ datacenter: 'ha-datacenter', vm: 'testvm' }) do + its('softPowerOff') { should cmp 'false' } + end +end +``` + +## Chef integrations inside of the VMware Suite + +### vRealize Automation Example Blueprints + +- [Linux](https://code.vmware.com/samples?id=1371) +- [Windows](https://code.vmware.com/samples?id=1390) + +### vRealize Orchestrator plugin + +- The [Chef plugin for vRealize + Orchestrator](https://solutionexchange.vmware.com/store/products/chef-plugin-for-vrealize-orchestrator) + (vRO) is a VMware-supplied plugin +- If you use vRealize Orchestrator, this provides the majority of the necessary features + +For more information, see the plugin demo on +[YouTube](https://www.youtube.com/watch?v=HlvoZ4Zdwc4). diff --git a/content/integrations/windows.md b/content/integrations/windows.md new file mode 100644 index 0000000..ea08b00 --- /dev/null +++ b/content/integrations/windows.md @@ -0,0 +1,268 @@ ++++ +title = "Chef for Windows" +draft = false + +[menu] + [menu.integrations] + title = "Chef for Windows" + identifier = "integrations/windows/windows.md Chef for Windows" + parent = "integrations/windows" + weight = 10 ++++ + +## Overview + +The Chef Infra Client has specific components that are designed to +support unique aspects of the Windows platform, including +PowerShell, PowerShell DSC, and Internet Information Services (IIS). + +{{< readfile file="content/reusable/md/windows_install_overview.md" >}} + +## Setting up Windows Workstations + +To set up your Windows workstation follow the steps on [Chef for +Windows](https://docs.chef.io/workstation/install_workstation/) + +## Install Chef Infra Client on Windows Nodes + +{{< readfile file="content/reusable/md/chef_client_summary.md" >}} + +This command has the following syntax: + +```bash +chef-client OPTION VALUE OPTION VALUE ... +``` + +This command has the following option specific to Windows: + +`-A`, `--fatal-windows-admin-check` + +: Cause a Chef Infra Client run to fail when Chef Infra Client does + not have administrator privileges in Windows. + +### System Requirements + +The recommended minimum amount of RAM available to Chef Infra Client +during a Chef Infra Client run is 512MB. Each node and workstation must +have access to Chef Infra Server using HTTPS. The Chef Infra Client can be +used to manage machines that run on the following versions of Microsoft +Windows: + + +++++ + + + + + + + + + + + + + + +
Operating SystemArchitectureVersion
Windowsx86, x648.1, 2012, 2012 R2, 2016, 10 (all channels except "insider" builds), 2019 (Long-term servicing channel (LTSC), both Desktop Experience and Server Core)
+ +After Chef Infra Client is installed, it's located at `C:\opscode`. The +main configuration file for Chef Infra Client is located at +`C:\chef\client.rb`. + +### Information for Windows Users + +#### Run With Elevated Privileges + +{{< readfile file="content/reusable/md/workstation/ctl_chef_client_elevated_privileges.md" >}} + +{{< readfile file="content/reusable/md/workstation/ctl_chef_client_elevated_privileges_windows.md" >}} + +#### Spaces and Directories + +{{< readfile file="content/reusable/md/windows_spaces_and_directories.md" >}} + +#### Top-level Directory Names + +{{< readfile file="content/reusable/md/windows_top_level_directory_names.md" >}} + +#### PATH System Variable + +{{< readfile file="content/reusable/md/windows_environment_variable_path.md" >}} + +#### Proxy Settings + +{{< readfile file="content/reusable/md/proxy_windows.md" >}} + +### Remotely administering nodes + +{{< readfile file="content/reusable/md/workstation/knife_windows_summary.md" >}} + +For more information, see the [`knife windows` documentation](https://docs.chef.io/workstation/knife_windows/). + +#### Ports + +{{< readfile file="content/reusable/md/workstation/knife_windows_winrm_ports.md" >}} + +### Install Chef Infra Client using the MSI Installer + +A Microsoft Installer Package (MSI) is available for installing Chef +Infra Client on a Windows machine from [Chef Downloads](https://www.chef.io/downloads). + +#### Msiexec.exe + +{{< readfile file="content/reusable/md/windows_msiexec.md" >}} + +#### ADDLOCAL Options + +{{< readfile file="content/reusable/md/windows_msiexec_addlocal.md" >}} + +#### Enable as a Scheduled Task + +{{< readfile file="content/reusable/md/install_chef_client_windows_as_scheduled_task.md" >}} + +### Install Chef Infra Client using an Existing Process + +{{< readfile file="content/reusable/md/windows_install_system_center.md" >}} + +## Windows Cookbooks + +Some of the most popular Chef-maintained cookbooks that contain custom +resources useful when configuring machines running Windows are +listed below: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CookbookDescription
iis CookbookThe iis cookbook is used to install and configure Internet Information Services (IIS).
iis_urlrewrite CookbookThis cookbook downloads and installs the IIS URL Rewrite 2.0 extension into Microsoft Internet Information Server.
PowerShell CookbookInstalls and configures PowerShell 2.0, 3.0, 4.0 or 5.0.
Microsoft Visual C++ Runtime CookbookInstalls Microsoft Visual C++ runtime version 6 (2005), 9 (2008), 10 (2010), 11 (2012), 12 (2013), 14 (2015) or 15 (2017) on Windows.
Mingw CookbookInstalls msys/mingw compiler toolchains on windows.
Webpi CookbookThe webpi cookbook is used to run the Microsoft Web Platform Installer (WebPI).
+ +### Community Supported Windows Projects + +Two community supports two provisioners for Kitchen: + +- [kitchen-dsc](https://github.com/test-kitchen/kitchen-dsc) +- [kitchen-pester](https://github.com/test-kitchen/kitchen-pester) + +## Windows Resources + +{{< readfile file="content/reusable/md/resources_common.md" >}} + +### Windows Resources + +Chef Infra provides a growing number of Windows-specific resources. + +- [cab_package](/resources/bundled/cab_package/) +- [chef_client_scheduled_task](/resources/bundled/chef_client_scheduled_task/) +- [chocolatey_config](/resources/bundled/chocolatey_config/) +- [chocolatey_feature](/resources/bundled/chocolatey_feature/) +- [chocolatey_package](/resources/bundled/chocolatey_package/) +- [chocolatey_source](/resources/bundled/chocolatey_package/) +- [dsc_resource](/resources/bundled/dsc_resource/) +- [dsc_script](/resources/bundled/dsc_script/) +- [msu_package](/resources/bundled/msu_package/) +- [powershell_package_source](/resources/bundled/powershell_package_source/) +- [powershell_package](/resources/bundled/powershell_package/) +- [powershell_script](/resources/bundled/powershell_script/) +- [registry_key](/resources/bundled/registry_key/) +- [windows_ad_join](/resources/bundled/windows_ad_join/) +- [windows_audit_policy](/resources/bundled/windows_audit_policy/) +- [windows_auto_run](/resources/bundled/windows_auto_run/) +- [windows_certificate](/resources/bundled/windows_certificate/) +- [windows_defender_exclusion](/resources/bundled/windows_defender_exclusion/) +- [windows_defender](/resources/bundled/windows_defender/) +- [windows_dfs_folder](/resources/bundled/windows_dfs_folder/) +- [windows_dfs_namespace](/resources/bundled/windows_dfs_namespace/) +- [windows_dfs_server](/resources/bundled/windows_dfs_server/) +- [windows_dns_record](/resources/bundled/windows_dns_record/) +- [windows_dns_zone](/resources/bundled/windows_dns_zone/) +- [windows_env](/resources/bundled/windows_env/) +- [windows_feature_dism](/resources/bundled/windows_feature_dism/) +- [windows_feature_powershell](/resources/bundled/windows_feature_powershell/) +- [windows_feature](/resources/bundled/windows_feature/) +- [windows_firewall_profile](/resources/bundled/windows_firewall_profile/) +- [windows_firewall_rule](/resources/bundled/windows_firewall_rule/) +- [windows_font](/resources/bundled/windows_font/) +- [windows_package](/resources/bundled/windows_package/) +- [windows_pagefile](/resources/bundled/windows_pagefile/) +- [windows_path](/resources/bundled/windows_path/) +- [windows_printer_port](/resources/bundled/windows_printer_port/) +- [windows_printer](/resources/bundled/windows_printer/) +- [windows_security_policy](/resources/bundled/windows_security_policy/) +- [windows_service](/resources/bundled/windows_service/) +- [windows_share](/resources/bundled/windows_share/) +- [windows_shortcut](/resources/bundled/windows_shortcut/) +- [windows_task](/resources/bundled/windows_task/) +- [windows_uac](/resources/bundled/windows_uac/) +- [windows_user_privilege](/resources/bundled/windows_user_privilege/) +- [windows_workgroup](/resources/bundled/windows_workgroup/) + +### Windows Compatible Resources + +The most popular core resources in Chef Infra Client work the same way +in Windows as they do on any UNIX or Linux-based platform. + + + +- [cookbook_file](/resources/bundled/cookbook_file/) +- [directory](/resources/bundled/directory/) +- [execute](/resources/bundled/execute/) +- [file](/resources/bundled/file/) +- [group](/resources/bundled/group/) +- [http_request](/resources/bundled/http_request/) +- [link](/resources/bundled/link/) +- [mount](/resources/bundled/mount/) +- [package](/resources/bundled/package/) +- [remote_directory](/resources/bundled/remote_directory/) +- [remote_file](/resources/bundled/remote_file/) +- [ruby_block](/resources/bundled/ruby_block/) +- [service](/resources/bundled/service/) +- [template](/resources/bundled/template/) +- [user](/resources/bundled/user/) + +The file-based resources have attributes that support unique +requirements within the Windows platform, including `inherits` +(for file inheritance), `mode` (for octal modes), and `rights` (for +access control lists, or ACLs). + +- [cookbook_file](/resources/bundled/cookbook_file/) +- [file](/resources/bundled/file/) +- [remote_file](/resources/bundled/remote_file/) +- [template](/resources/bundled/template/) diff --git a/content/license/_index.md b/content/license/_index.md index df5f19e..776c36e 100644 --- a/content/license/_index.md +++ b/content/license/_index.md @@ -9,58 +9,37 @@ parent = "licensing" weight = 11 +++ -This document outlines the licensing requirements and enforcement policies for Chef Infra Client 19. - -## Licensing requirements - -Chef Infra Client 19 has different licensing requirements depending on the distribution you download. - -### No license enforcement - -Chef Infra Client doesn't require a license to run if you download an official distribution. - -This includes: - -- Downloading Infra Client from the customer portal. -- Installing the Infra Client Habitat package. -- Installing Infra Client using the migration tool or native installer. - -### License required - -You need a license key to run Chef Infra Client when you: - -- Download it from unofficial sources (public Ruby gem). -- Use runtime installations and workflows. +Chef Infra Client requires a license to run. This document describes how to set a license and verify that it's accepted. ## Add a license -You can set a license in Chef Infra Client 19 using one of three methods: +Chef Infra Client has three ways to set a license: -- An environment variable -- A command line option -- The command line interactive dialog +- with an environment variable +- with a command line option +- with the command line interactive dialog -If you set a license key, Chef Infra Client validates it with Progress Chef's licensing service. +After setting a license key, Chef Infra Client validates it with Progress Chef's licensing service. ### Environment variable -To set the license key, add the `CHEF_LICENSE_KEY` environment variable: +- You can set the license key adding the `CHEF_LICENSE_KEY` environment variable: -```sh -export CHEF_LICENSE_KEY= -``` + ```sh + export CHEF_LICENSE_KEY= + ``` ### Command line option -To set the license key, use the `--chef-license-key` CLI option: +- You can set the license key using the `--chef-license-key` CLI option: -```sh -chef-client --chef-license-key= -``` + ```sh + chef-client --chef-license-key= + ``` ### Interactive license dialog -If you run a `chef-client` command and choose to set a license, Chef Infra Client can start an interactive licensing dialog. +If you run a `chef-client` command and a license key isn't already set, Chef Infra Client starts an interactive licensing dialog. To set a license key with the CLI interactive dialog, follow these steps: @@ -70,7 +49,7 @@ To set a license key with the CLI interactive dialog, follow these steps: chef-client --version ``` - This should return version 19.0.54 or greater for Infra Client RC 1. + It should return version 19.0.54 or greater for Infra Client RC 1. 1. Run `chef-client` in local mode and why-run mode: @@ -78,10 +57,9 @@ To set a license key with the CLI interactive dialog, follow these steps: chef-client --local-mode --why-run ``` - Local mode runs Chef Infra Client on your local machine as if it were running against Chef Infra Server. - Why-run mode shows you what Chef Infra Client would configure during a Chef Infra Client run. + Local mode runs Chef Infra Client on your local machine as if it were running against Chef Infra Server. why-run mode shows you what Chef Infra Client would configure if a Chef Infra Client run occurs. -1. At the first prompt, select **I already have a license ID**: +1. At the first prompt, select **I already have a license ID**. ```text Please choose one of the options below (Press ↑/↓ arrow to move and Enter to select) diff --git a/content/license/troubleshooting.md b/content/license/troubleshooting.md index e909329..aa86b54 100644 --- a/content/license/troubleshooting.md +++ b/content/license/troubleshooting.md @@ -8,10 +8,6 @@ parent = "licensing" weight = 20 +++ - - ## Support contact For any licensing issues, contact [Aditya V](mailto:aditya.v@progress.com) or [Ankur Mundhra](mailto:ankur.mundhra@progress.com) with your license details, error logs, and a description of the issue. diff --git a/content/overview/_index.md b/content/overview/_index.md new file mode 100644 index 0000000..9f853a6 --- /dev/null +++ b/content/overview/_index.md @@ -0,0 +1,5 @@ ++++ +title = "Chef Infra Client overview" +linkTitle = "Overview" +list_pages = true ++++ diff --git a/content/overview/chef_overview.md b/content/overview/chef_overview.md new file mode 100644 index 0000000..ba19129 --- /dev/null +++ b/content/overview/chef_overview.md @@ -0,0 +1,347 @@ ++++ +title = "Chef Infra overview" +draft = false +gh_repo = "chef-web-docs" + +[menu] + [menu.overview] + title = "Chef Infra overview" + identifier = "overview/chef_overview.md Chef Infra Overview" + parent = "overview" + weight = 10 ++++ + + +{{< readfile file="content/reusable/md/chef.md" >}} + +- **Chef Workstation** is the location where users interact with Chef + Infra. With Chef Workstation, users can author and test + [cookbooks](/cookbooks/) using tools such as [Test + Kitchen](https://docs.chef.io/workstation/kitchen/) and interact with the Chef Infra Server + using the [knife](https://docs.chef.io/workstation/knife/) and [chef](https://docs.chef.io/workstation/ctl_chef/) command + line tools. +- **Chef Infra Client** Chef Infra Client runs on systems that are managed by + Chef Infra. The Chef Infra Client executes on a schedule to configure a system to + the desired state. +- **Chef Infra Server** acts as [a hub for configuration + data](https://docs.chef.io/server/). Chef Infra Server stores cookbooks, + the policies that are applied to nodes, and metadata that describes + each registered node that's being managed by Chef. Nodes use the + Chef Infra Client to ask the Chef Infra Server for configuration + details, such as recipes, templates, and file distributions. + +## Chef Infra Components + +The following diagram shows the relationships between the various +elements of Chef Infra, including the nodes, the server, and the +workstation. These elements work together to provide the Chef Infra +Client the information and instruction that it needs so that it can do +its job. As you are reviewing the rest of this topic, use the icons in +the tables to refer back to this image. + +{{< figure src="/images/chef_overview_2020.svg" width=600 alt="Diagram of Chef Infra Client, Server, and Workstation">}} + +Chef Infra has the following major components: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ComponentDescription

One (or more) workstations are configured to allow users to author, test, and maintain cookbooks.

+

Workstation systems run the Chef Workstation package which includes tools such as Chef Infra Client, Chef InSpec, Test Kitchen, ChefSpec, Cookstyle, and other tools necessary for developing and testing your infrastructure with Chef products.

Cookbooks are uploaded to the Chef Infra Server from these workstations. Some cookbooks are custom to the organization and others are based on community cookbooks available from the Chef Supermarket.

Ruby is the programming language that's the authoring syntax for cookbooks. Most recipes are simple patterns (blocks that define properties and values that map to specific configuration items like packages, files, services, templates, and users. The full power of Ruby is available for when you need a programming language.

{{< readfile file="content/reusable/md/node.md" >}}

Chef Infra Client is installed on each node that's managed with Chef Infra. Chef Infra Client configures the node locally by performing the tasks specified in the run-list. Chef Infra Client will also pull down any required configuration data from the Chef Infra Server during a Chef Infra Client run.

The Chef Infra Server acts as a hub of information. Cookbooks and policy settings are uploaded to the Chef Infra Server by users from workstations.

+

The Chef Infra Client accesses the Chef Infra Server from the node on which it's installed to get configuration data, performs searches of historical Chef Infra Client run data, and then pulls down the necessary configuration data. After a Chef Infra Client run is finished, the Chef Infra Client uploads updated run data to the Chef Infra Server.

Chef Supermarket is the location in which community cookbooks are shared and managed. Cookbooks that are part of the Chef Supermarket may be used by any Chef user. How community cookbooks are used varies from organization to organization.
+ +Chef Infra Client run reporting, compliance reporting, high availability +configurations, and Chef Infra Server replication are available as part +of Chef Automate. + +The following sections discuss these elements (and their various +components) in more detail. + +## Workstations + +A workstation is your local computer running Chef Workstation that you +use to author cookbooks, interact with the Chef Infra Server, and +interact with nodes. + +The workstation is where users do most of their work, including: + +- Developing and testing cookbooks +- Keeping the Chef Infra repository synchronized with version source control +- Configuring organizational policy by including defining roles and applying Policyfiles or policy groups +- Interacting with nodes, as (or when) required, such as performing a bootstrap operation + +### Chef Workstation Components and Tools + +Some important tools and components of Chef Workstation include: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ComponentDescription

{{< readfile file="content/reusable/md/workstation/chef_workstation.md" >}}

+

Chef Workstation includes important command-line tools:

+
    +
  • Chef Infra: Use the chef command-line tool to work with items in a chef-repo, which is the primary location in which cookbooks are authored, tested, and maintained, and from which policy is uploaded to the Chef Infra Server
    • +
  • Knife: Use the knife command-line tool to interact with nodes or work with objects on the Chef Infra Server
    • +
  • Chef Infra Client: an agent that configures your nodes
    • +
  • Test Kitchen: a testing harness for rapid validation of Chef code
    • +
  • Chef InSpec: Chef's open source security & compliance automation framework
    • +
  • chef-run: a tool for running ad-hoc tasks
    • +
  • Chef Workstation App: for updating and managing your chef tools
    • +

The chef-repo is the repository structure in which cookbooks are authored, tested, and maintained:

+
    +
  • Cookbooks contain recipes, attributes, custom resources, libraries, files, templates, tests, and metadata
    • +
  • The chef-repo should be synchronized with a version control system (such as git), and then managed as if it were source code
    • +
+

The directory structure within the chef-repo varies. Some organizations prefer to keep all of their cookbooks in a single chef-repo, while other organizations prefer to use a chef-repo for every cookbook.

{{< readfile file="content/reusable/md/workstation/test_kitchen.md" >}}

{{< readfile file="content/reusable/md/chefspec_summary.md" >}}
+ +## Cookbooks + +{{< readfile file="content/reusable/md/cookbooks_summary.md" >}} + +The Chef Infra Client uses Ruby as its reference language for creating +cookbooks and defining recipes, with an extended DSL for specific +resources. A reasonable set of resources are available to the Chef Infra +Client, enough to support many of the most common infrastructure +automation scenarios; however, this DSL can also be extended when +additional resources and capabilities are required. + +### Components + +Cookbooks are comprised of the following components: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ComponentDescription

{{< readfile file="content/reusable/md/cookbooks_attribute.md" >}}

{{< readfile file="content/reusable/md/resource_cookbook_file_summary.md" >}}

{{< readfile file="content/reusable/md/libraries_summary.md" >}}

{{< readfile file="content/reusable/md/cookbooks_metadata.md" >}}

{{< readfile file="content/reusable/md/cookbooks_recipe.md" >}}

+

The Chef Infra Client will run a recipe only when asked. When the Chef Infra Client runs the same recipe more than once, the results will be the same system state each time. When a recipe is run against a system, but nothing has changed on either the system or in the recipe, the Chef Infra Client won't change anything.

+

{{< readfile file="content/reusable/md/infra_lang_summary.md" >}}

{{< readfile file="content/reusable/md/resources_common.md" >}}

+

Chef has many built-in resources that cover all of the most common actions across all of the most common platforms. You can build your own resources to handle any situation that's not covered by a built-in resource.

{{< readfile file="content/reusable/md/template.md" >}}

Testing cookbooks improves the quality of those cookbooks by ensuring they're doing what they're supposed to do and that they're authored in a consistent manner. Unit and integration testing validates the recipes in cookbooks. Syntax testing---often called linting---validates the quality of the code itself. The following tools are popular tools used for testing Chef recipes: Test Kitchen, ChefSpec, and Cookstyle.
+ +## Nodes + +{{< readfile file="content/reusable/md/node.md" >}} + +### Node Types + +{{< readfile file="content/reusable/md/node_types.md" >}} + +### Chef on Nodes + +The key components of nodes that are under management by Chef include: + + ++++ + + + + + + + + + + + + + + + + +
ComponentDescription

{{< readfile file="content/reusable/md/chef_client_summary.md" >}}

+

{{< readfile file="content/reusable/md/security_key_pairs_chef_client.md" >}}

{{< readfile file="content/reusable/md/ohai_summary.md" >}}
+ +## The Chef Infra Server + +{{< readfile file="content/reusable/md/server/chef_server.md" >}} + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
FeatureDescription

{{< readfile file="content/reusable/md/search.md" >}}

{{< readfile file="content/reusable/md/chef_manager.md" >}}

{{< readfile file="content/reusable/md/data_bag.md" >}}

Policy defines how business and operational requirements, processes, and production workflows map to objects that are stored on the Chef Infra Server. Policy objects on the Chef Infra Server include roles, environments, and cookbook versions.
+ +### Policy + +{{< readfile file="content/reusable/md/policy_summary.md" >}} + +Some important aspects of policy include: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
FeatureDescription

{{< readfile file="content/reusable/md/role.md" >}}

{{< readfile file="content/reusable/md/environment.md" >}}

{{< readfile file="content/reusable/md/cookbooks_version.md" >}}

{{< readfile file="content/reusable/md/node_run_list.md" >}}
+ +## Conclusion + +Chef is a thin DSL (domain-specific language) built on top of Ruby. This +approach allows Chef to provide just enough abstraction to make +reasoning about your infrastructure easy. Chef includes a built-in +taxonomy of all the basic resources one might configure on a system, +plus a defined mechanism to extend that taxonomy using the full power of +the Ruby language. Chef chose Ruby because it provides the flexibility +to use both the simple built-in taxonomy, as well as being able to +handle any customization path your organization requires. diff --git a/content/overview/nodes.md b/content/overview/nodes.md new file mode 100644 index 0000000..a2dfead --- /dev/null +++ b/content/overview/nodes.md @@ -0,0 +1,128 @@ ++++ +title = "About Nodes" +draft = false + +[menu] + [menu.overview] + title = "Nodes" + identifier = "overview/nodes.md Nodes" + parent = "overview" + weight = 30 ++++ + +{{< readfile file="content/reusable/md/node.md" >}} + +{{< readfile file="content/reusable/md/node_types.md" >}} + +The key components of nodes that are under management by Chef include: + + ++++ + + + + + + + + + + + + + + + + +
ComponentDescription

image

{{< readfile file="content/reusable/md/chef_client_summary.md" >}}

+

{{< readfile file="content/reusable/md/security_key_pairs_chef_client.md" >}}

image

{{< readfile file="content/reusable/md/ohai_summary.md" >}}
+ +## Node Names + +The name of a node is required as part of the authentication process to +Chef Infra Server. The name of each node must be unique within an +organization, but otherwise can be any string that matches the following +regular expression: + +```re + /^[\-[:alnum:]_:.]+$/ +``` + +The name of a node can be obtained from the `node_name` attribute in the +client.rb file or by allowing Ohai to collect this data during a Chef +Infra Client run. When Ohai collects this data during a Chef Infra +Client run, it uses the node's FQDN, which is always unique within an +organization, as the name of the node. + +Using the FQDN as the node name, and then allowing Ohai to collect this +information during each Chef Infra Client run, is the recommended +approach and the easiest way to ensure that the names of all nodes +across the organization are unique. + +## Node Objects + +For Chef Infra Client, two important aspects of nodes are groups of +attributes and run-lists. An attribute is a specific piece of data about +the node, such as a network interface, a file system, or the number of +clients a service running on a node is capable of accepting. +A run-list is an ordered list of recipes and/or roles that are run in an +exact order. The node object consists of the run-list and node +attributes, which is a JSON file that's stored on the Chef Infra +Server. Chef Infra Client gets a copy of the node object from the Chef +Infra Server during each Chef Infra Client run and places an updated +copy on Chef Infra Server at the end of each Chef Infra Client run. + +{{< readfile file="content/reusable/md/node_attribute.md" >}} + +### Attributes + +An attribute is a specific detail about a node, such as an IP address, a +host name, a list of loaded kernel modules, the versions of available +programming languages that are available. An attribute may be +unique to a specific node or it can be identical across every node in +the organization. Attributes are most commonly set from a cookbook, by +using knife, or are retrieved by Ohai from each node before every Chef +Infra Client run. All attributes are indexed for search on the Chef +Infra Server. Good candidates for attributes include: + +- any cross-platform abstraction for an application, such as the path + to a configuration file +- default values for tunable settings, such as the amount of memory + assigned to a process or the number of workers to spawn +- anything that may need to be persisted in node data between Chef + Infra Client runs + +In general, attribute precedence is set to enable cookbooks and roles to +define attribute defaults, for normal attributes to define the values +that should be specific for a node, and for override attributes to force +a certain value, even when a node already has that value specified. + +One approach is to set attributes at the same precedence level by +setting attributes in a cookbook's attribute files, and then also +setting the same default attributes (but with different values) using a +role. The attributes set in the role will be deep merged on top of the +attributes from the attribute file, and the attributes set by the role +will take precedence over the attributes specified in the cookbook's +attribute files. + +See [Attributes](/cookbooks/attributes) for detailed information on the different types of node attributes and how they're used to set policy on nodes. + +### Run-lists + +{{< readfile file="content/reusable/md/node_run_list.md" >}} + +#### Run-list Format + +{{< readfile file="content/reusable/md/node_run_list_format.md" >}} + +## Managing Nodes + +You can manage nodes directly using Knife, Chef Automate, or by using command-line tools that are specific to Chef Infra Client. + +- [Knife](https://docs.chef.io/workstation/knife/) can be used to create, edit, view, list, tag, and delete nodes. +- Knife plug-ins can be used to create, edit, and manage nodes that are located on cloud providers. +- Chef Infra Client can be used to manage node data using the command line and JSON files. Each JSON file contains a hash, the elements of which are added as node attributes. In addition, the `run_list` setting allows roles and/or recipes to be added to the node. +- The command line can also be used to edit JSON files and files that are related to third-party services, such as Amazon EC2, where the JSON files can contain metadata fore each instance that's stored in a file on-disk and then read by Chef Infra Client as required. diff --git a/content/policy/_index.md b/content/policy/_index.md new file mode 100644 index 0000000..3913795 --- /dev/null +++ b/content/policy/_index.md @@ -0,0 +1,47 @@ ++++ +title = "About Policy" +draft = false + +[menu] + [menu.policy] + title = "About Policy" + identifier = "policy/policy.md About Policy" + parent = "policy" + weight = 10 ++++ + +{{< readfile file="content/reusable/md/policy_summary.md" >}} + +## Cookbook Versions + +{{< readfile file="content/reusable/md/cookbooks_version.md" >}} + +For more information about cookbook versioning, see [About Cookbook +Versioning](/cookbooks/cookbook_versioning/) + +## Data Bags (Secrets) + +{{< readfile file="content/reusable/md/data_bag.md" >}} + +For more information about data bags, see [About Data +Bags](/policy/data_bags/) + +## Environments + +{{< readfile file="content/reusable/md/environment.md" >}} + +For more information about environments, see [About +Environments](environments) + +## Roles + +{{< readfile file="content/reusable/md/role.md" >}} + +For more information about roles, see [About Roles](roles) + +## Policyfile + +{{< readfile file="content/reusable/md/policyfile_summary.md" >}} + +For more information about Policyfile, see [About +Policyfile](/policy/policyfile/) diff --git a/content/policy/config_rb_policyfile.md b/content/policy/config_rb_policyfile.md new file mode 100644 index 0000000..7eec91f --- /dev/null +++ b/content/policy/config_rb_policyfile.md @@ -0,0 +1,33 @@ ++++ +title = "Policyfile.rb" +draft = false + +[menu] + [menu.policy] + title = "Policyfile.rb" + identifier = "policy/config_rb_policyfile.md Policyfile.rb Configuration" + parent = "policy" + weight = 30 ++++ + +{{< readfile file="content/reusable/md/policyfile_summary.md" >}} + +{{< readfile file="content/reusable/md/policyfile_rb.md" >}} + +{{< note >}} + +For more information, see the [Policyfile documentation](/policy/policyfile/). + +{{< /note >}} + +## Syntax + +{{< readfile file="content/reusable/md/policyfile_rb_syntax.md" >}} + +## Settings + +{{< readfile file="content/reusable/md/policyfile_rb_settings.md" >}} + +## Example + +{{< readfile file="content/reusable/md/policyfile_rb_example.md" >}} diff --git a/content/policy/data_bags.md b/content/policy/data_bags.md new file mode 100644 index 0000000..a911e75 --- /dev/null +++ b/content/policy/data_bags.md @@ -0,0 +1,515 @@ ++++ +title = "About Data Bags" +draft = false + +[menu] + [menu.policy] + title = "Data Bags" + identifier = "policy/data_bags.md Data Bags" + parent = "policy" + weight = 40 ++++ + +{{< readfile file="content/reusable/md/data_bag.md" >}} + +## Create a data bag + +You can create a data bag in two ways: using knife or manually. +We recommend using knife, but as long as you create the data bag folders and item JSON files correctly, +either method is safe and effective. + +### Create a data bag with knife + +Use the `knife data bag create` command to create data bags and data bag items. +For example: + +```bash +knife data bag create DATA_BAG_NAME (DATA_BAG_ITEM) +``` + +Use the `from file` argument to update data bag items: + +```bash +knife data bag from file BAG_NAME ITEM_NAME.json +``` + +As long as a file is in the correct directory structure, knife will be +able to find the data bag and data bag item with only the name of the +data bag and data bag item. For example: + +```bash +knife data bag from file BAG_NAME ITEM_NAME.json +``` + +will load the following file: + +```plain +data_bags/BAG_NAME/ITEM_NAME.json +``` + +Continuing the example above, if you are in the "admins" directory and +make changes to the file charlie.json, then to upload that change to the +Chef Infra Server use the following command: + +```bash +knife data bag from file admins charlie.json +``` + +In some cases, such as when knife isn't being run from the root +directory for the chef-repo, the full path to the data bag item may be +required. For example: + +```bash +knife data bag from file BAG_NAME /path/to/file/ITEM_NAME.json +``` + +### Manually + +One or more data bags and data bag items can be created manually under +the `data_bags` directory in the chef-repo. Any method can be used to +create the data bag folders and data bag item JSON files. For example: + +```bash +mkdir data_bags/admins +``` + +would create a data bag folder named `admins`. The equivalent command +for using knife is: + +```bash +knife data bag create admins +``` + +A data bag item can be created manually in the same way as the data bag, +but by also specifying the file name for the data bag item (this example +is using vi, a visual editor for UNIX): + +```bash +vi data_bags/admins/charlie.json +``` + +would create a data bag item named "charlie.json" under the "admins" +sub-directory in the `data_bags` directory of the chef-repo. The +equivalent command for using knife is: + +```bash +knife data bag create admins charlie +``` + +## Store data in a data bag + +When the chef-repo is cloned from GitHub, the following occurs: + +- A directory named `data_bags` is created. +- For each data bag, a sub-directory is created that has the same name + as the data bag. +- For each data bag item, a JSON file is created and placed in the + appropriate sub-directory. + +The `data_bags` directory can be placed under version source control. + +When deploying from a private repository using a data bag, use the +`deploy_key` option to ensure the private key is present: + +```ruby +{ + 'id': 'my_app', + ... (truncated) ... + 'deploy_key': 'ssh_private_key' +} +``` + +where `ssh_private_key` is the same SSH private key as used with a +private git repository and the new lines converted to `\n`. + +### Directory structure + +All data bags are stored in the `data_bags` directory of the chef-repo. +This directory structure is understood by knife so that the full path +doesn't need to be entered when working with data bags from the command +line. An example of the `data_bags` directory structure: + +```text +. chef-repo +└── data_bags + ├── README.md + ├─── admins + │ ├── README.md + │ ├── charlie.json + │ ├── bob.json + │ └── tom.json + ├─── db_users + │ ├── README.md + │ ├── charlie.json + │ ├── bob.json + │ └── sarah.json + └─── db_config + ├── README.md + ├── small.json + ├── medium.json + └── large.json +``` + +where `admins`, `db_users`, and `db_config` are the names of individual +data bags and all the files that end with `.json` are the individual +data bag items. + +### Data bag items + +{{< readfile file="content/reusable/md/data_bag_item.md" >}} + +## Encrypt a data bag item + +{{< readfile file="content/reusable/md/data_bag_encryption.md" >}} + +### Encryption versions + +The manner by which a data bag item is encrypted depends on the Chef +Infra Client version used. See the following: + +|Infra Client version|Encryption v0|Encryption v1|Encryption v2|Encryption v3| +|:--|:---:|:---:|:---:|:---:| +|10.x|`R` `W`|||| +|11.0+|`R`|`R` `W`||| +|11.6+|`R` `D`|`R` `D`|`R` `W`|| +|13.0|`R` `D`|`R` `D`|`R` `D`|`R` `W`| + +`R` = read +`W` = write +`D` = disable + +#### Version 0 + +Chef Infra Client 0.10+ + +- Uses YAML serialization format to encrypt data bag items +- Uses Base64 encoding to preserve special characters +- Uses AES-256-CBC encryption, as defined by the OpenSSL package in the Ruby Standard Library +- [Shared secret encryption](https://en.wikipedia.org/wiki/Symmetric-key_algorithm); an encrypted file can only be decrypted by a node or a user with the same shared secret +- Recipes load encrypted data with access to the shared secret in a file on the node or from a URI path +- Decrypts only data bag item values. Keys are encrypted but searchable +- Data bag `id` value is unencrypted for tracking data bag items + +#### Version 1 + +Chef Infra Client 11.0+ + +- Version 0 +- Uses JSON serialization format _instead of_ YAML to encrypt data bag items +- Adds random initialization vector encryption for each value to protect against cryptanalysis + +#### Version 2 + +Chef Infra Client 11.6+ + +- Version 1 +- Option to disable versions 0 and 1 +- Adds Encrypt-then-MAC(EtM) protection + +#### Version 3 + +Chef Infra Client 13.0+ + +- Option to disable version 0, 1, and 2 + +### Knife options + +knife can encrypt and decrypt data bag items when the `knife data bag` +subcommand is run with the `create`, `edit`, `from file`, or `show` +arguments and the following options: + +| Option | Description | +|--------------------|-------------------------------------------------------------| +| `--secret SECRET` | The encryption key that's used for values contained within a data bag item. If `secret` isn't specified, Chef Infra Client looks for a secret at the path specified by the `encrypted_data_bag_secret` setting in the client.rb file. | +| `--secret-file FILE` | The path to the file that contains the encryption key. | + +### Secret keys + +{{< readfile file="content/reusable/md/data_bag_encryption_secret_key.md" >}} + +### Encrypt + +A data bag item is encrypted using a knife command similar to: + +```bash +knife data bag create passwords mysql --secret-file /tmp/my_data_bag_key +``` + +where "passwords" is the name of the data bag, "mysql" is the name of +the data bag item, and "/tmp/my_data_bag_key" is the path to the +location in which the file that contains the secret-key is located. +knife will ask for user credentials before the encrypted data bag item +is saved. + +### Verify encryption + +When the contents of a data bag item are encrypted, they won't be +readable until they're decrypted. Encryption can be verified with a +knife command similar to: + +```bash +knife data bag show passwords mysql +``` + +where "passwords" is the name of the data bag and "mysql" is the name of +the data bag item. This will return something similar to: + +```bash +id: mysql +pass: +cipher: aes-256-cbc +encrypted_data: JZtwXpuq4Hf5ICcepJ1PGQohIyqjNX6JBc2DGpnL2WApzjAUG9SkSdv75TfKSjX4 +iv: VYY2qx9b4r3j0qZ7+RkKHg== +version: 1 +user: +cipher: aes-256-cbc +encrypted_data: 10BVoNb/plkvkrzVdybPgFFII5GThZ3Op9LNkwVeKpA= +iv: uIqKHZ9skJlN2gpJoml6rQ== +version: 1 +``` + +### Decrypt + +An encrypted data bag item is decrypted with a knife command similar to: + +```bash +knife data bag show --secret-file /tmp/my_data_bag_key passwords mysql +``` + +that will return JSON output similar to: + +```json +{ + "id": "mysql", + "pass": "thesecret123", + "user": "fred" +} +``` + +## Edit a data bag item + +A data bag can be edited in two ways: using knife or by using the Chef +management console. + +### Edit a data bag with knife + +{{< readfile file="content/reusable/md/workstation/knife_data_bag_edit.md" >}} + +{{< readfile file="content/reusable/md/workstation/knife_data_bag_edit_item.md" >}} + +## Use data bags + +Data bags can be accessed in the following ways: + +### Search + +{{< readfile file="content/reusable/md/data_bag.md" >}} + +{{< readfile file="content/reusable/md/search_data_bag.md" >}} + +### Environments + +Values that are stored in a data bag are global to the organization and +are available to any environment. The two main strategies that can +be used to store shared environment data within a data bag: by using a +top-level key that corresponds to the environment or by using separate +items for each environment. + +A data bag stores a top-level key for an environment might look +something like this: + +```json +{ + "id": "some_data_bag_item", + "production" : { + # Hash with all your data here + }, + "testing" : { + # Hash with all your data here + } +} +``` + +When using the data bag in a recipe, that data can be accessed from a +recipe using code similar to: + +```ruby +data_bag_item[node.chef_environment]['some_other_key'] +``` + +The other approach is to use separate items for each environment. +Depending on the amount of data, it may all fit nicely within a single +item. If this is the case, then creating different items for each +environment may be a simple approach to providing shared environment values +within a data bag. However, this approach is more time-consuming and may +not scale to large environments or when the data must be stored in +many data bag items. + +### Recipes + +Data bags can be accessed by a recipe in the following ways: + +- Loaded by name when using the Chef Infra Language. Use this approach when a + only single, known data bag item is required. +- Accessed through the search indexes. Use this approach when more + than one data bag item is required or when the contents of a data + bag are looped through. The search indexes will bulk-load all of the + data bag items, which will result in a lower overhead than if each + data bag item were loaded by name. + +#### Load with Chef Infra Language + +The Chef Infra Language provides access to data bags and data bag items +(including encrypted data bag items) with the following methods: + +- `data_bag(bag)`, where `bag` is the name of the data bag. +- `data_bag_item('bag_name', 'item', 'secret')`, where `bag` is the + name of the data bag and `item` is the name of the data bag item. If + `'secret'` isn't specified, Chef Infra Client will look for a + secret at the path specified by the `encrypted_data_bag_secret` + setting in the client.rb file. + +The `data_bag` method returns an array with a key for each of the data +bag items that are found in the data bag. + +Some examples: + +To load the secret from a file: + +```ruby +data_bag_item('bag', 'item', IO.read('secret_file')) +``` + +To load a single data bag item named `admins`: + +```ruby +data_bag('admins') +``` + +The contents of a data bag item named `justin`: + +```ruby +data_bag_item('admins', 'justin') +``` + +will return something similar to: + +```ruby +# => {'comment'=>'Justin Currie', 'gid'=>1005, 'id'=>'justin', 'uid'=>1005, 'shell'=>'/bin/zsh'} +``` + +If `item` is encrypted, `data_bag_item` will automatically decrypt it +using the key specified above, or (if none is specified) by the +`Chef::Config[:encrypted_data_bag_secret]` method, which defaults to +`/etc/chef/encrypted_data_bag_secret`. + +#### Create and edit + +Creating and editing the contents of a data bag or a data bag item from +a recipe isn't recommended. The recommended method of updating a data +bag or a data bag item is to use knife and the `knife data bag` +subcommand. If this action must be done from a recipe, please note the +following: + +- If two operations concurrently attempt to update the contents of a + data bag, the last-written attempt will be the operation to update + the contents of the data bag. This situation can lead to data loss, + so organizations should take steps to ensure that only one Chef + Infra Client is making updates to a data bag at a time. +- Altering data bags from the node when using the open source Chef + Infra Server requires the node's API client to be granted admin + privileges. In most cases, this isn't advisable. + +and then take steps to ensure that any subsequent actions are done +carefully. The following examples show how a recipe can be used to +create and edit the contents of a data bag or a data bag item using the +`Chef::DataBag` and `Chef::DataBagItem` objects. + +To create a data bag from a recipe: + +```ruby +users = Chef::DataBag.new +users.name('users') +users.create +``` + +To create a data bag item from a recipe: + +```ruby +sam = { + 'id' => 'sam', + 'Full Name' => 'Sammy', + 'shell' => '/bin/zsh', +} +databag_item = Chef::DataBagItem.new +databag_item.data_bag('users') +databag_item.raw_data = sam +databag_item.save +``` + +To edit the contents of a data bag item from a recipe: + +```ruby +sam = data_bag_item('users', 'sam') +sam['Full Name'] = 'Samantha' +sam.save +``` + +#### Create users + +Chef Infra Client can create users on systems based on the contents of a +data bag. For example, a data bag named "admins" can contain a data bag +item for each of the administrators that will manage the various systems +that each Chef Infra Client is maintaining. A recipe can load the data +bag items and then create user accounts on the target system with code +similar to the following: + +```ruby +# Load the keys of the items in the 'admins' data bag +admins = data_bag('admins') + +admins.each do |login| + # This causes a round-trip to the server for each admin in the data bag + admin = data_bag_item('admins', login) + homedir = '/home/#{login}' + + # for each admin in the data bag, make a user resource + # to ensure they exist + user(login) do + uid admin['uid'] + gid admin['gid'] + shell admin['shell'] + comment admin['comment'] + home homedir + manage_home true + end +end + +# Create an "admins" group on the system +# You might use this group in the /etc/sudoers file +# to provide sudo access to the admins +group 'admins' do + gid '999' + members 'admins' +end +``` + +### `chef-solo` + +chef-solo can load data from a data bag as long as the contents of that +data bag are accessible from a directory structure that exists on the +same machine as chef-solo. The location of this directory is +configurable using the `data_bag_path` option in the solo.rb file. The +name of each sub-directory corresponds to a data bag and each JSON file +within a sub-directory corresponds to a data bag item. Search isn't +available in recipes when they're run with chef-solo; use the +`data_bag()` and `data_bag_item()` functions to access data bags and +data bag items. + +{{< note >}} + +Use the `chef-solo-search` cookbook library to add data bag search +capabilities to a chef-solo environment: +. + +{{< /note >}} diff --git a/content/policy/environments.md b/content/policy/environments.md new file mode 100644 index 0000000..2433864 --- /dev/null +++ b/content/policy/environments.md @@ -0,0 +1,390 @@ ++++ +title = "About Environments" +draft = false + +[menu] + [menu.policy] + title = "Environments" + identifier = "policy/environments.md Environments" + parent = "policy" + weight = 60 ++++ + +{{< readfile file="content/reusable/md/environment.md" >}} + +## The `_default` environment + +Every Chef Infra Server organization must have at least one environment. +Each organization starts out with a single `_default` environment. The +`_default` environment can't be modified in any way. Nodes, roles, +run-lists, cookbooks (and cookbook versions), and attributes specific to +an organization can only be associated with a custom environment. +Additional environments can be created to reflect each organization's +patterns and workflow. For example, creating `production`, `staging`, +`testing`, and `development` environments. + +## Environment attributes + +{{< note >}} + +{{< readfile file="content/reusable/md/notes_see_attributes_overview.md" >}} + +{{< /note >}} + +{{< readfile file="content/reusable/md/environment_attribute.md" >}} + +### Environment attribute types + +There are two types of attributes that can be used with environments: + +`default` +: {{< readfile file="content/reusable/md/node_attribute_type_default.md" >}} + +`override` +: {{< readfile file="content/reusable/md/node_attribute_type_override.md" >}} + +## Pinning Cookbooks in environments + +Cookbook versions can be pinned in each environment, which allows you to +control the rollout of new cookbook releases through successive testing +environments before releasing new cookbook versions into production +environments. See the environment format examples below for the cookbook +pinning syntax. + +## Environment formats + +Environments may be stored on disk (any in source control) in two +formats: + +- As Ruby ( a file that ends with `.rb`); this format isn't available when running Chef Infra Client in local mode +- As JSON (a file that ends with `.json`) + +### Chef language + +Each environment is defined as a Ruby file (a file that ends with +`.rb`). Each environment file should contain the following +domain-specific attributes: + +`cookbook` +: A version constraint for a single cookbook. For example: + + ```ruby + cookbook 'couchdb', '< 11.0.0' + ``` + + or: + + ```ruby + cookbook 'my_rails_app', '= 1.2.0' + ``` + + or: + + ```ruby + cookbook 'gems', '~> 1.4' + ``` + +`cookbook_versions` +: A version constraint for a group of cookbooks. For example: + + ```ruby + cookbook_versions( + 'couchdb' => '= 11.0.0', + 'my_rails_app' => '~> 1.2.0' + ) + ``` + +`default_attributes` +: Optional. A set of attributes to be applied to all nodes, assuming the node doesn't already have a value for the attribute. This is useful for setting global defaults that can then be overridden for specific nodes. If more than one role attempts to set a default value for the same attribute, the last role applied is the role to set the attribute value. When nested attributes are present, they're preserved. For example, to specify that a node that has the attribute `apache2` should listen on ports 80 and 443 (unless ports are already specified): + + ```ruby + default_attributes 'apache2' => { 'listen_ports' => %w(80 443) } + ``` + +`description` +: A description of the functionality that's covered. For example: + + ```ruby + description 'The development environment' + ``` + +`name` +: A unique name within the organization. Each name must be made up of letters (uppercase and lowercase), numbers, underscores, and hyphens. Spaces aren't allowed. For example: + + ```ruby + name 'dev01-24' + ``` + +`override_attributes` +: Optional. A set of attributes to be applied to all nodes, even if the node already has a value for an attribute. This is useful for ensuring that certain attributes always have specific values. If more than one role attempts to set an override value for the same attribute, the last role applied wins. When nested attributes are present, they're preserved. For example: + + ```ruby + override_attributes 'apache2' => { 'max_children' => '50' } + ``` + + The parameters in a Ruby file are Ruby method calls, so parentheses can be used to provide clarity when specifying numerous or deeply-nested attributes. For example: + + ```ruby + override_attributes( + apache2: { + prefork: { min_spareservers: '5' }, + } + ) + ``` + + or: + + ```ruby + override_attributes( + apache2: { + prefork: { min_spareservers: '5' }, + }, + tomcat: { + worker_threads: '100', + } + ) + ``` + +A Ruby file for each non-default environment must exist in the +`environments/` subdirectory of the chef-repo. (If the chef-repo does +not have this subdirectory, then it should be created.) The complete +environment has the following syntax: + +```ruby +name 'environment_name' +description 'environment_description' +cookbook OR cookbook_versions 'cookbook' OR 'cookbook' => 'cookbook_version' +default_attributes 'node' => { 'attribute' => [ 'value', 'value', 'etc.' ] } +override_attributes 'node' => { 'attribute' => [ 'value', 'value', 'etc.' ] } +``` + +where both default and override attributes are optional and either a +cookbook or cookbook versions (one or more) are specified. For example, +an environment named `dev` that uses the `couchdb` cookbook (version +11.0.0 or higher) that listens on ports 80 and 443: + +```ruby +name 'dev' +description 'The development environment' +cookbook_versions 'couchdb' => '= 11.0.0' +default_attributes 'apache2' => { 'listen_ports' => %w(80 443) } +``` + +Or (using the same scenario) to specify a version constraint for only +one cookbook: + +```ruby +cookbook 'couchdb', '= 11.0.0' +``` + +More than one cookbook version can be specified: + +```ruby +cookbook_versions({ + 'couchdb' => '= 11.0.0', + 'my_rails_app' => '~> 1.2.0' +}) +``` + +Attributes are optional and can be set at the default and override +levels. These will be processed according to attribute precedence. An +environment attribute will be applied to all nodes within the +environment, except in places where it's overridden by an attribute +with higher precedence. For example: + +```ruby +default_attributes 'apache2' => { 'listen_ports' => %w(80 443) } +``` + +will have all nodes in the environment (`node[:apache2][:listen_ports]`) +set to `'80'` and `'443'` unless they were overridden by an attribute +with higher precedence. For example: + +```ruby +override_attributes 'apache2' => { 'listen_ports' => %w(80 443) } +``` + +### JSON + +The JSON format for environments maps directly to the domain-specific +Ruby format: the same settings, attributes, and values, and a similar +structure and organization, just formatted as JSON. When an environment +is defined as JSON the file that contains that data must be defined as a +file that ends with `.json`. For example: + +```json +{ + "name": "dev", + "default_attributes": { + "apache2": { + "listen_ports": [ + "80", + "443" + ] + } + }, + "json_class": "Chef::Environment", + "description": "", + "cookbook_versions": { + "couchdb": "= 11.0.0" + }, + "chef_type": "environment" +} +``` + +The JSON format has two additional settings: + +`chef_type` +: Always set this to `environment`. Use this setting for any custom process that consumes environment objects outside of Ruby. + +`json_class` +: Always set this to `Chef::Environment`. Chef Infra Client uses this setting to automatically inflate an environment object. If objects are being rebuilt outside of Ruby, ignore it. + +## Create environments + +An environment can be created in four different ways: + +- Create a Ruby file in the environments sub-directory of the + chef-repo and then push it to Chef Infra Server +- Create a JSON file directly in the chef-repo and then push it + to Chef Infra Server +- Using knife +- Using the Chef Infra Server REST API + +Once an environment exists on Chef Infra Server, a node can be +associated with that environment using the `chef_environment` method. + +## Manage environments + +Once created, an environment can be managed in several ways: + +- By using knife and passing the `-E ENVIRONMENT_NAME` option with + `knife cookbook upload` +- By using Ruby or JSON files that are stored in a version source + control system. These files are pushed to Chef Infra Server + using the `knife environment` subcommand and the `from file` + argument. This approach allows environment data to be dynamically + generated. This approach won't work unless these files are + defined in the proper format---Ruby file end with `.rb`; JSON files + end with `.json`. + +These workflows are mutually exclusive: only the most recent environment +changes will be kept on Chef Infra Server, regardless of the source +of those changes. All previous changes are overwritten when environment +data is updated. + +The settings for environments can be modified and environments can be +integrated into the larger infrastructure by associating them with nodes +and by using recipes to call specific environment settings. + +### Find environment from recipe + +Use the following syntax to find the current environment from a recipe: + +```ruby +node.environment +``` + +or: + +```ruby +node.chef_environment +``` + +### Save in a data bag + +Values that are stored in a data bag are global to the organization and +are available to any environment. There are two main strategies that can +be used to store environment data within a data bag: by using a +top-level key that corresponds to the environment or by using separate +items for each environment. + +A data bag that's storing a top-level key for an environment might look +something like this: + +```json +{ + "id": "some_data_bag_item", + "production" : { + // Hash with all your data here + }, + "testing" : { + // Hash with all your data here + } +} +``` + +When using the data bag in a recipe, that data can be accessed from a +recipe using code similar to: + +```ruby +bag_item[node.chef_environment]['some_other_key'] +``` + +The other approach is to use separate items for each environment. +Depending on the amount of data, it may all fit nicely within a single +item. If this is the case, then creating different items for each +environment may be a simple approach to providing values +within a data bag for each environment. However, this approach is more time-consuming and may +not scale to large environments or when the data must be stored in +many data bag items. + +### Override attributes in roles + +Environment attributes that are used with roles can be overridden. +Typically, this is done by using attribute precedence, but sometimes it +may be necessary to ensure that specific attributes are used based on +the presence of specific environments. This type of scenario is best +addressed in using a recipe that relies on a top-level key that's +stored in a data bag. + +For example, to retrieve a value from a data bag based on a specific +environment: + +```ruby +mything = data_bag_item('things', 'mything') +attribute_i_want = mything[node.chef_environment] +``` + +### Set for a node + +A node is considered to be associated with an environment when the +`chef_environment` attribute is set. The `chef_environment` attribute +can't be set with normal or override attributes (in a role) +because it's actually a method. An environment may be set explicitly +using the following methods: + +- By using the `knife edit` and `knife exec` subcommands + +- By editing the `environment` configuration details in the client.rb + file, and then using `knife bootstrap -e environment_name` to + bootstrap the changes to the specified environment + + {{< note >}} + + After the environment has been set using bootstrap, the environment is + set in the client.rb file and may not be modified using the `edit` argument of the `knife node` + subcommand. + + {{< /note >}} + +- By setting the `environment` configuration entry in the client.rb + file ; when Chef Infra Client runs, it will pick up the value and + then set the `chef_environment` attribute of the node + +### Move nodes + +Use the `knife exec` subcommand to move nodes between environments, such +as from a "dev" to a "production" environment. For example: + +```bash +knife exec -E 'nodes.transform("chef_environment:dev") { |n| n.chef_environment("production") }' +``` + +### Search environments + +{{< readfile file="content/reusable/md/search_environment.md" >}} + +## Environments in chef-solo + +{{< readfile file="content/reusable/md/chef_solo_environments.md" >}} diff --git a/content/policy/policyfile.md b/content/policy/policyfile.md new file mode 100644 index 0000000..3f54da0 --- /dev/null +++ b/content/policy/policyfile.md @@ -0,0 +1,407 @@ ++++ +title = "About Policyfiles" +draft = false + +[menu] + [menu.policy] + title = "About Policyfiles" + identifier = "policy/policyfile.md About Policyfiles" + parent = "policy" + weight = 20 ++++ + +{{< readfile file="content/reusable/md/policyfile_summary.md" >}} + +## Why Policyfiles? + +Policyfiles make it easier to test and promote code safely with a simpler interface. Using a Policyfile improves the user experience and resolves real-world problems that some workflows built around Chef Infra must deal with. The following sections discuss in more detail some of the good reasons to use Policyfile, including: + +* Focus the workflow on the entire system +* Safer development workflows +* Less expensive computation +* Code visibility +* Role mutability +* Cookbook mutability +* Replaces Berkshelf and the environment cookbook pattern + +### Focused System Workflows + +The knife command line tool maps closely to the Chef Infra Server API and the objects defined by it, such as roles, environments, run-lists, cookbooks, data bags, or nodes. Chef Infra Client assembles these pieces at run-time and configures a host to do useful work. + +Policyfile focuses that workflow onto the entire system, rather than the individual components. For example, Policyfile describes whole systems, whereas each individual revision of the `Policyfile.lock.json` file uploaded to Chef Infra Server describes a part of that system, inclusive of roles, environments, cookbooks, and the other Chef Infra Server objects necessary to configure that part of the system. + +### Safer Workflows + +Policyfile encourages safer workflows by making it easier to publish development versions of cookbooks to Chef Infra Server without the risk of mutating the production versions and without requiring a complicated versioning scheme to work around cookbook mutability issues. Roles are mutable and those changes are applied only to the nodes specified by the policy. Policyfile doesn't require any changes to your normal workflows. Use the same repositories you are already using, the same cookbooks, and workflows. Policyfile will prevent an updated cookbook or role from being applied immediately to all machines. + +### Code Visibility + +When running Chef Infra without a Policyfile, the exact set of cookbooks that are applied to a node is defined by: + +* The node's `run_list` property +* Any roles that are present in the node's run-list or recursively included by those roles +* The environment, which may restrict the set of valid cookbook versions for a node based on a variety of constraint operators +* Dependencies, as defined by each cookbook's metadata +* Dependency resolution picks the "best" set of cookbooks that meet dependency and environment criteria + +These conditions are re-evaluated every time Chef Infra Client runs, which can make it harder to know which cookbooks will be run by Chef Infra Client or what the effects of updating a role or uploading a new cookbook will be. + +Policyfile simplifies this behavior by computing the cookbook set on the workstation, and then producing a readable document of that solution: a `Policyfile.lock.json` file. This pre-computed file is uploaded to Chef Infra Server, and is then used in each Chef Infra Client run that's managed by that particular policy name and policy group. + +### Less Expensive Computation + +When running Chef Infra without Policyfile, Chef Infra Server loads dependency data for all known versions of all known cookbooks, and then runs an expensive computation to determine the correct set. + +Policyfile moves this computation to the workstation, where it's done less frequently. + +### Role and Environment Mutability + +When running Chef Infra without Policyfile roles and environments are global objects. Changes to roles and environments are applied immediately to any node that contains that role in its run-list or belong to a particular environment. This can make it hard to update roles and environments and in some use cases discourages using them at all. + +Policyfile effectively replaces roles and environments. Policyfile files are versioned automatically and new versions are applied to systems only when promoted. + +### Cookbook Mutability + +When running Chef without Policyfile, existing versions of cookbooks are mutable. This is convenient for many use cases, especially if users upload in-development cookbook revisions to Chef Infra Server. But this sometimes creates issues that are similar to role mutability by allowing those cookbook changes to be applied immediately to nodes that use that cookbook. Users account for this by rigorous testing processes to ensure that only fully integrated cookbooks are ever published. This process does enforce good development habits, but at the same time it shouldn't be a required part of a workflow that ends with publishing an in-development cookbook to Chef Infra Server for testing against real nodes. Policyfile solves this issue by using a cookbook publishing API for Chef Infra Server that doesn't provide cookbook mutability. Name collisions are prevented by storing cookbooks by name and an opaque identifier that's computed from the content of the cookbook itself. + +For example, name/version collisions can occur when users temporarily fork an upstream cookbook. Even if the user contributes their change and the maintainer is responsive, there may be a period of time where the user needs their fork to make progress. This situation presents a versioning dilemma: if the user doesn't update their own version, they must overwrite the existing copy of that cookbook on Chef Infra Server, wheres if they do update the version number it might conflict with the version number of the future release of that upstream cookbook. + +#### Opaque IDs + +The opaque identifier that's computed from the content of a cookbook is the only place where an opaque identifier is necessary. When working with Policyfile, be sure to: + +* Use the same names and version constraints as normal in the `Policyfile.rb` file +* Use the same references to cookbooks pulled from Chef Supermarket +* Use the same branch, tag, and revision patterns for cookbooks pulled from git +* Use the same paths for cookbooks pulled from disk + +Extra metadata about the cookbook is stored and included in Chef Infra Server API responses and in the `Policyfile.lock.json` file, including the source of a cookbook (Chef Supermarket, git, local disk, etc.), as well as any upstream identifiers, such as git revisions. For cookbooks that are loaded from the local disk that are in a git repo, the upstream URL, current revision ID, and the state of the repo are stored also. + +The opaque identifier is mostly behind the scenes and is only visible once published to Chef Infra Server. Cookbooks that are uploaded to Chef Infra Server may have extended version numbers such as `1.0.0-dev`. + +### Environment cookbooks + +Policyfile replaces the environment cookbook pattern that's often required by Berkshelf, along with a dependency solver and fetcher. That said, Policyfile doesn't replace all Berkshelf scenarios. + +## Knife commands + +The following knife commands used to set the policy group and policy name on Chef Infra Server. For example: + +```bash +knife node policy set test-node 'test-policy-group-name' 'test-policy-name' +``` + +## Policyfile.rb + +{{< readfile file="content/reusable/md/policyfile_rb.md" >}} + +### Syntax + +{{< readfile file="content/reusable/md/policyfile_rb_syntax.md" >}} + +### Settings + +{{< readfile file="content/reusable/md/policyfile_rb_settings.md" >}} + +### Example + +{{< readfile file="content/reusable/md/policyfile_rb_example.md" >}} + +## client.rb Settings + +The following settings may be configured in the client.rb file for use with Policyfile: + +`named_run_list` + +: The run-list associated with a Policyfile. + +`policy_group` + +: The name of a policy group that exists on Chef Infra Server. `policy_name` must also be specified. + +`policy_name` + +: The name of a policy, as identified by the `name` setting in a `Policyfile.rb` file. `policy_group` must also be specified. + +`use_policyfile` + +: Chef Infra Client automatically checks the configuration, node JSON, and the stored node on Chef Infra Server to determine if Policyfile files are being used, and then automatically updates this flag. Default value: `false`. + +## `knife bootstrap` + +A node may be bootstrapped to use Policyfile files. Use the following options as part of the bootstrap command: + +`--policy-group POLICY_GROUP` + +: The name of a policy group that exists on Chef Infra Server. + +`--policy-name POLICY_NAME` + +: The name of a policy, as identified by the `name` setting in a `Policyfile.rb` file. + +For a customized bootstrap process, add `policy_name` and `policy_group` to the first-boot JSON file that's passed to Chef Infra Client. + +## `knife search` + +The `policy_name` and `policy_group` settings for a node are stored as searchable attributes and as such are available when using a fuzzy matching search pattern. For example: `knife search dev` will return nodes that are part of the `dev` policy group. + +## Test w/Kitchen + +Kitchen may be used to test Policyfile files. Add the following to kitchen.yml: + +```yaml +provisioner: + name: chef_zero +``` + +A named run-list may be used for each suite: + +```yaml +suites: + - name: client + provisioner: + named_run_list: test_client_recipe + - name: server + provisioner: + named_run_list: test_server_recipe +``` + +or globally: + +```yaml +provisioner: + name: chef_zero + named_run_list: integration_test_run_list +``` + +or testing with policies for each suite, once the Policyfile files are available in your repo: + +```yaml +suites: + - name: defaultmega + provisioner: + policyfile: policies/default.rb + - name: defaultultra + provisioner: + policyfile: policies/defaulttwo.rb +``` + +{{< note >}} + +As `chef_zero` explicitly tests outside the context of a Chef Infra Server, the `policy_groups` concept isn't applicable. The value of `policy_group` during a converge will be set to `local`. + +{{< /note >}} + +## `chef` CLI commands + +{{< readfile file="content/reusable/md/policyfile_chef_commands.md" >}} + +### `chef clean-policy-cookbooks` + +{{< readfile file="content/reusable/md/workstation/ctl_chef_clean_policy_cookbooks.md" >}} + +#### Syntax + +{{< readfile file="content/reusable/md/workstation/ctl_chef_clean_policy_cookbooks_syntax.md" >}} + +#### Options + +{{< readfile file="content/reusable/md/workstation/ctl_chef_clean_policy_cookbooks_options.md" >}} + +### `chef clean-policy-revisions` + +{{< readfile file="content/reusable/md/workstation/ctl_chef_clean_policy_revisions.md" >}} + +#### Syntax + +{{< readfile file="content/reusable/md/workstation/ctl_chef_clean_policy_revisions_syntax.md" >}} + +#### Options + +{{< readfile file="content/reusable/md/workstation/ctl_chef_clean_policy_revisions_options.md" >}} + +### `chef delete-policy` + +{{< readfile file="content/reusable/md/workstation/ctl_chef_delete_policy.md" >}} + +#### Syntax + +{{< readfile file="content/reusable/md/workstation/ctl_chef_delete_policy_syntax.md" >}} + +#### Options + +{{< readfile file="content/reusable/md/workstation/ctl_chef_delete_policy_options.md" >}} + +### `chef delete-policy-group` + +{{< readfile file="content/reusable/md/workstation/ctl_chef_delete_policy_group.md" >}} + +#### Syntax + +{{< readfile file="content/reusable/md/workstation/ctl_chef_delete_policy_group_syntax.md" >}} + +#### Options + +{{< readfile file="content/reusable/md/workstation/ctl_chef_delete_policy_group_options.md" >}} + +### `chef diff` + +{{< readfile file="content/reusable/md/workstation/ctl_chef_diff.md" >}} + +#### Syntax + +{{< readfile file="content/reusable/md/workstation/ctl_chef_diff_syntax.md" >}} + +#### Options + +{{< readfile file="content/reusable/md/workstation/ctl_chef_diff_options.md" >}} + +#### Examples + +##### Compare current lock to latest commit on latest branch + +{{< readfile file="content/reusable/md/workstation/ctl_chef_diff_current_lock_latest_branch.md" >}} + +##### Compare current lock with latest commit on main branch + +{{< readfile file="content/reusable/md/workstation/ctl_chef_diff_current_lock_main_branch.md" >}} + +##### Compare current lock to specified revision + +{{< readfile file="content/reusable/md/workstation/ctl_chef_diff_current_lock_specified_revision.md" >}} + +##### Compare lock on main branch to lock on revision + +{{< readfile file="content/reusable/md/workstation/ctl_chef_diff_main_lock_revision_lock.md" >}} + +##### Compare lock for version with latest commit on main branch + +{{< readfile file="content/reusable/md/workstation/ctl_chef_diff_version_lock_main_branch.md" >}} + +##### Compare current lock with latest lock for policy group + +{{< readfile file="content/reusable/md/workstation/ctl_chef_diff_current_lock_policy_group.md" >}} + +##### Compare locks for two policy group + +{{< readfile file="content/reusable/md/workstation/ctl_chef_diff_two_policy_groups.md" >}} + +### `chef export` + +{{< readfile file="content/reusable/md/workstation/ctl_chef_export.md" >}} + +#### Syntax + +{{< readfile file="content/reusable/md/workstation/ctl_chef_export_syntax.md" >}} + +#### Options + +{{< readfile file="content/reusable/md/workstation/ctl_chef_export_options.md" >}} + +### `chef generate policyfile` + +{{< readfile file="content/reusable/md/workstation/ctl_chef_generate_policyfile.md" >}} + +#### Syntax + +{{< readfile file="content/reusable/md/workstation/ctl_chef_generate_policyfile_syntax.md" >}} + +#### Options + +{{< readfile file="content/reusable/md/workstation/ctl_chef_generate_policyfile_options.md" >}} + +### `chef generate repo` + +{{< readfile file="content/reusable/md/workstation/ctl_chef_generate_repo.md" >}} + +{{< note >}} + +This subcommand requires using one (or more) of the options (below) to support Policyfile files. + +{{< /note >}} + +#### Syntax + +{{< readfile file="content/reusable/md/workstation/ctl_chef_generate_repo_syntax.md" >}} + +#### Options + +{{< readfile file="content/reusable/md/workstation/ctl_chef_generate_repo_options.md" >}} + +### `chef install` + +{{< readfile file="content/reusable/md/workstation/ctl_chef_install.md" >}} + +#### Syntax + +{{< readfile file="content/reusable/md/workstation/ctl_chef_install_syntax.md" >}} + +#### Options + +{{< readfile file="content/reusable/md/workstation/ctl_chef_install_options.md" >}} + +#### Policyfile.lock.json + +{{< readfile file="content/reusable/md/policyfile_lock_json.md" >}} + +{{< readfile file="content/reusable/md/policyfile_lock_json_example.md" >}} + +### `chef push` + +{{< readfile file="content/reusable/md/workstation/ctl_chef_push.md" >}} + +#### Syntax + +{{< readfile file="content/reusable/md/workstation/ctl_chef_push_syntax.md" >}} + +#### Options + +{{< readfile file="content/reusable/md/workstation/ctl_chef_push_options.md" >}} + +### `chef push-archive` + +{{< readfile file="content/reusable/md/workstation/ctl_chef_push_archive.md" >}} + +#### Syntax + +{{< readfile file="content/reusable/md/workstation/ctl_chef_push_archive_syntax.md" >}} + +#### Options + +{{< readfile file="content/reusable/md/workstation/ctl_chef_push_archive_options.md" >}} + +### `chef show-policy` + +{{< readfile file="content/reusable/md/workstation/ctl_chef_show_policy.md" >}} + +#### Syntax + +{{< readfile file="content/reusable/md/workstation/ctl_chef_show_policy_syntax.md" >}} + +#### Options + +{{< readfile file="content/reusable/md/workstation/ctl_chef_show_policy_options.md" >}} + +### `chef undelete` + +{{< readfile file="content/reusable/md/workstation/ctl_chef_undelete.md" >}} + +#### Syntax + +{{< readfile file="content/reusable/md/workstation/ctl_chef_undelete_syntax.md" >}} + +#### Options + +{{< readfile file="content/reusable/md/workstation/ctl_chef_undelete_options.md" >}} + +### `chef update` + +{{< readfile file="content/reusable/md/workstation/ctl_chef_update.md" >}} + +#### Syntax + +{{< readfile file="content/reusable/md/workstation/ctl_chef_update_syntax.md" >}} + +#### Options + +{{< readfile file="content/reusable/md/workstation/ctl_chef_update_options.md" >}} diff --git a/content/policy/roles.md b/content/policy/roles.md new file mode 100644 index 0000000..88d6a45 --- /dev/null +++ b/content/policy/roles.md @@ -0,0 +1,303 @@ ++++ +title = "About Roles" +draft = false + +[menu] + [menu.policy] + title = "Roles" + identifier = "policy/roles.md Roles" + parent = "policy" + weight = 70 ++++ + +{{< readfile file="content/reusable/md/role.md" >}} + +## Role Attributes + +{{< note >}} + +{{< readfile file="content/reusable/md/notes_see_attributes_overview.md" >}} + +{{< /note >}} + +{{< readfile file="content/reusable/md/role_attribute.md" >}} + +### Attribute types + +There are two types of attributes that can be used with roles: + +`default` +: {{< readfile file="content/reusable/md/node_attribute_type_default.md" >}} + +`override` +: {{< readfile file="content/reusable/md/node_attribute_type_override.md" >}} + +## Role formats + +Role data is stored in two formats: as a Ruby file that contains +domain-specific language or as JSON data. + +### Chef Language + +{{< readfile file="content/reusable/md/ruby_summary.md" >}} + +Domain-specific Ruby attributes: + +`default_attributes` +: Optional. A set of attributes to be applied to all nodes, assuming the node doesn't already have a value for the attribute. This is useful for setting global defaults that can then be overridden for specific nodes. If more than one role attempts to set a default value for the same attribute, the last role applied is the role to set the attribute value. When nested attributes are present, they're preserved. For example, to specify that a node that has the attribute `apache2` should listen on ports 80 and 443 (unless ports are already specified): + + ```ruby + default_attributes 'apache2' => { + 'listen_ports' => [ '80', '443' ] + } + ``` + +`description` +: A description of the functionality that's covered. For example: + + ```ruby + description 'The base role for systems that serve HTTP traffic' + ``` + +`env_run_lists` +: Optional. A list of environments, each specifying a recipe or a role to be applied to that environment. This setting must specify the `_default` environment. If the `_default` environment is set to `[]` or `nil`, then the run-list is empty. For example: + + ```ruby + env_run_lists 'prod' => ['recipe[apache2]'], + 'staging' => ['recipe[apache2::staging]' + ``` + + {{< warning >}} + + Using `env_run_lists` with roles is discouraged as it can be difficult to maintain over time. Instead, consider using multiple roles to define the required behavior. + + {{< /warning >}} + +`name` +: A unique name within the organization. Each name must be made up of letters (uppercase and lowercase), numbers, underscores, and hyphens: Spaces aren't allowed. For example: + + ```ruby + name 'dev01-24' + ``` + +`override_attributes` +: Optional. A set of attributes to be applied to all nodes, even if the node already has a value for an attribute. This is useful for ensuring that certain attributes always have specific values. If more than one role attempts to set an override value for the same attribute, the last role applied wins. When nested attributes are present, they're preserved. For example: + + ```ruby + override_attributes 'apache2' => { + 'max_children' => '50' + } + ``` + + The parameters in a Ruby file are Ruby method calls, so parentheses can be used to provide clarity when specifying numerous or deeply-nested attributes. For example: + + ```ruby + override_attributes( + :apache2 => { + :prefork => { :min_spareservers => '5' } + } + ) + ``` + + Or: + + ```ruby + override_attributes( + :apache2 => { + :prefork => { :min_spareservers => '5' } + }, + :tomcat => { + :worker_threads => '100' + } + ) + ``` + +`run_list` +: A list of recipes and/or roles to be applied and the order in which they're to be applied. For example, the following run-list: + + ```ruby + run_list 'recipe[apache2]', + 'recipe[apache2::mod_ssl]', + 'role[monitor]' + ``` + + would apply the `apache2` recipe first, then the `apache2::mod_ssl` recipe, and then the `role[monitor]` recipe. + +Each role must be saved as a Ruby file in the `roles/` subdirectory of +the chef-repo. (If the repository doesn't have this subdirectory, then +create it using knife.) Each Ruby file should have the `.rb` suffix. A +complete role has the following syntax: + +```ruby +name "role_name" +description "role_description" +run_list "recipe[name]", "recipe[name::attribute]", "recipe[name::attribute]" +env_run_lists "name" => ["recipe[name]"], "environment_name" => ["recipe[name::attribute]"] +default_attributes "node" => { "attribute" => [ "value", "value", "etc." ] } +override_attributes "node" => { "attribute" => [ "value", "value", "etc." ] } +``` + +where both default and override attributes are optional and at least one +run-list (with at least one run-list item) is specified. For example, a +role named `webserver` that has a run-list that defines actions for +three different roles, and for certain roles takes extra steps (such as +the `apache2` role listening on ports 80 and 443): + +```ruby +name "webserver" +description "The base role for systems that serve HTTP traffic" +run_list "recipe[apache2]", "recipe[apache2::mod_ssl]", "role[monitor]" +env_run_lists "prod" => ["recipe[apache2]"], "staging" => ["recipe[apache2::staging]"], "_default" => [] +default_attributes "apache2" => { "listen_ports" => [ "80", "443" ] } +override_attributes "apache2" => { "max_children" => "50" } +``` + +### JSON + +The JSON format for roles maps directly to the domain-specific Ruby +format: same settings, attributes, and values, and a similar structure +and organization. For example: + +```json +{ + "name": "webserver", + "chef_type": "role", + "json_class": "Chef::Role", + "default_attributes": { + "apache2": { + "listen_ports": [ + "80", + "443" + ] + } + }, + "description": "The base role for systems that serve HTTP traffic", + "run_list": [ + "recipe[apache2]", + "recipe[apache2::mod_ssl]", + "role[monitor]" + ], + "env_run_lists" : { + "production" : [], + "preprod" : [], + "dev": [ + "role[base]", + "recipe[apache]", + "recipe[apache::copy_dev_configs]", + ], + "test": [ + "role[base]", + "recipe[apache]" + ] + }, + "override_attributes": { + "apache2": { + "max_children": "50" + } + } +} +``` + +The JSON format has two additional settings: + + ++++ + + + + + + + + + + + + + + + + +
SettingDescription
chef_typeAlways set this to role. Use this setting for any custom process that consumes role objects outside of Ruby.
json_classAlways set this to Chef::Role. The Chef Infra Client uses this setting to auto inflate a role object. If objects are being rebuilt outside of Ruby, ignore it.
+ +## Manage Roles + +There are several ways to manage roles: + +- knife can be used to create, edit, view, list, tag, and delete + roles. +- The Chef Infra Client can be used to manage role data using the + command line and JSON files (that contain a hash, the elements of + which are added as role attributes). In addition, the `run_list` + setting allows roles and/or recipes to be added to the role. +- The open source Chef Infra Server can be used to manage role data + using the command line and JSON files (that contain a hash, the + elements of which are added as role attributes). In addition, the + `run_list` setting allows roles and/or recipes to be added to the + role. +- The Chef Infra Server API can be used to create and manage roles + directly, although using knife directly is the most common way to manage roles. +- The command line can also be used with JSON files and third-party + services, such as Amazon EC2, where the JSON files can contain + metadata for each instance stored in a file on-disk and then read by + chef-solo or Chef Infra Client as required. + +By creating and editing files using the Chef Language (Ruby) or JSON, you can dynamically generate role data. Roles created and edited +using files are compatible with all versions of Chef, including +chef-solo. Roles created and edited using files can be kept in version +source control, which also keeps a history of what changed when. When +roles are created and edited using files, they shouldn't be managed +using knife, as changes will be +overwritten. + +A run-list that's associated with a role can be edited using the Chef +management console add-on. The canonical source of a role's data is +stored on Chef Infra Server, which means that keeping role data in +version source control can be challenging. + +If roles are created and managed using knife and then arbitrarily updated +uploaded through JSON data, that action will overwrite the previous work with knife. +It's strongly recommended to keep to one process and not switch back and forth. + +### Set Run-lists for Environments + +Associating a run-list with a role and a specific environment lets you use the run-list on different nodes that share the same environment. More than one environment can be specified in a role, but each specific environment may be associated with only one run-list. If a run-list isn't specified, the default run-list will be used. For example: + +```json +{ + "name": "webserver", + "default_attributes": { + }, + "json_class": "Chef::Role", + "env_run_lists": { + "production": [], + "preprod": [], + "test": [ "role[base]", "recipe[apache]", "recipe[apache::copy_test_configs]" ], + "dev": [ "role[base]", "recipe[apache]", "recipe[apache::copy_dev_configs]" ] + }, + "run_list": [ "role[base]", "recipe[apache]" ], + "description": "The webserver role", + "chef_type": "role", + "override_attributes": { + } +} +``` + +where: + +- `webserver` is the name of the role +- `env_run_lists` is a hash of environment run-lists for + `production`, `preprod`, `test`, and `dev` +- `production` and `preprod` use the default run-list because they do + not have a shared environment run-list +- `run_list` defines the default run-list + +### Delete from Run-list + +When an environment is deleted, it will remain within a run-list for a +role until it's removed from that run-list. If a new environment is +created that has an identical name to an environment that was deleted, a +run-list that contains an old environment name will use the new one. diff --git a/content/policy/run_lists.md b/content/policy/run_lists.md new file mode 100644 index 0000000..b8cb88a --- /dev/null +++ b/content/policy/run_lists.md @@ -0,0 +1,155 @@ ++++ +title = "About Run-lists" +draft = false + +[menu] + [menu.policy] + title = "Run-lists" + identifier = "policy/run_lists.md Run-lists" + parent = "policy" + weight = 50 ++++ + +{{< readfile file="content/reusable/md/node_run_list.md" >}} + +## Run-list Format + +{{< readfile file="content/reusable/md/node_run_list_format.md" >}} + +### Empty Run-lists + +{{< readfile file="content/reusable/md/node_run_list_empty.md" >}} + +## Knife Commands + +The following knife commands may be used to manage run-lists on the Chef +Infra Server. + +### Quotes, Windows + +{{< readfile file="content/reusable/md/workstation/knife_common_windows_quotes.md" >}} + +#### Import-Module chef + +{{< readfile file="content/reusable/md/workstation/knife_common_windows_quotes_module.md" >}} + +### run_list add + +{{< readfile file="content/reusable/md/workstation/knife_node_run_list_add.md" >}} + +{{< readfile file="content/reusable/md/node_run_list_format.md" >}} + +#### Syntax + +{{< readfile file="content/reusable/md/workstation/knife_node_run_list_add_syntax.md" >}} + +#### Options + +{{< readfile file="content/reusable/md/workstation/knife_node_run_list_add_options.md" >}} + +{{< note >}} + +{{< readfile file="content/reusable/md/workstation/knife_common_see_all_config_options.md" >}} + +{{< /note >}} + +#### Examples + +The following examples show how to use this knife subcommand: + +##### Add a role + +{{< readfile file="content/reusable/md/workstation/knife_node_run_list_add_role.md" >}} + +##### Add roles and recipes + +{{< readfile file="content/reusable/md/workstation/knife_node_run_list_add_roles_and_recipes.md" >}} + +##### Add a recipe with a FQDN + +{{< readfile file="content/reusable/md/workstation/knife_node_run_list_add_recipe_with_fqdn.md" >}} + +##### Add a recipe with a cookbook + +{{< readfile file="content/reusable/md/workstation/knife_node_run_list_add_recipe_with_cookbook.md" >}} + +##### Add the default recipe + +{{< readfile file="content/reusable/md/workstation/knife_node_run_list_add_default_recipe.md" >}} + +### run_list remove + +{{< readfile file="content/reusable/md/workstation/knife_node_run_list_remove.md" >}} + +#### Syntax + +{{< readfile file="content/reusable/md/workstation/knife_node_run_list_remove_syntax.md" >}} + +#### Options + +This command doesn't have any specific options. + +{{< note >}} + +{{< readfile file="content/reusable/md/workstation/knife_common_see_all_config_options.md" >}} + +{{< /note >}} + +#### Examples + +The following examples show how to use this knife subcommand: + +##### Remove a role + +{{< readfile file="content/reusable/md/workstation/knife_node_run_list_remove_role.md" >}} + +##### Remove a run-list + +{{< readfile file="content/reusable/md/workstation/knife_node_run_list_remove_run_list.md" >}} + +### run_list set + +{{< readfile file="content/reusable/md/workstation/knife_node_run_list_set.md" >}} + +#### Syntax + +{{< readfile file="content/reusable/md/workstation/knife_node_run_list_set_syntax.md" >}} + +#### Options + +This command doesn't have any specific options. + +#### Examples + +None. + +### status + +The following examples show how to use the `knife status` subcommand to +verify the status of run-lists. + +#### View status, include run-lists + +{{< readfile file="content/reusable/md/workstation/knife_status_include_run_lists.md" >}} + +#### View status using a query + +{{< readfile file="content/reusable/md/workstation/knife_status_returned_by_query.md" >}} + +## Run-lists, Applied + +A run-list will tell Chef Infra Client what to do when bootstrapping +that node for the first time, and then how to configure that node on +every subsequent Chef Infra Client run. + +### Bootstrap Operations + +{{< readfile file="content/reusable/md/install_chef_client.md" >}} + +{{< readfile file="content/reusable/md/chef_client_bootstrap_node.md" >}} + +{{< readfile file="content/reusable/md/chef_client_bootstrap_stages.md" >}} + +### The Chef Infra Client Run + +{{< readfile file="content/reusable/md/chef_client_run.md" >}} diff --git a/content/quickstart.md b/content/quickstart.md new file mode 100644 index 0000000..dfce8dc --- /dev/null +++ b/content/quickstart.md @@ -0,0 +1,50 @@ ++++ +title = "Chef Infra quickstart guide" +draft = false + +[menu] + [menu.quickstart] + title = "Quickstart" + identifier = "quick_start.md Quick Start" + weight = 10 ++++ + +The quickest way to get started using Chef Infra is to install Chef Workstation and create your first Chef Infra Cookbook: + +1. Install Chef Workstation from [Chef Downloads](https://www.chef.io/downloads). + +2. Generate a Chef Infra repository with an example cookbook: + + ```bash + chef generate repo my_first_repo + ``` + + where `my_first_repo` is an arbitrary name for your Chef Infra repository. + +3. Navigate to the `cookbooks/example` directory. + +4. Update the `cookbooks/example/recipes/default.rb` recipe in + the generated cookbook to contain: + + ```ruby + file "#{ENV['HOME']}/test.txt" do + content 'This file was created by Chef Infra!' + end + ``` + +5. Run Chef Infra Client using the `default.rb` recipe: + + ```bash + chef-client --local-mode --override-runlist example + ``` + +This creates a file named `test.txt` at the home path on your computer. Open that file and it will say `This file was created by Chef Infra!`. + +- Delete the file, run Chef Infra Client again, and Chef Infra will replace the file. +- Change the string in the file, run Chef Infra Client again, and Chef Infra will make the string in the file the same as the string in the recipe. +- Change the string in the recipe, run Chef Infra Client again, and Chef Infra will update that string to be the same as the one in the recipe. + +There's a lot more that Chef Infra can do, obviously, but that was super easy! + +- See for more detailed setup scenarios. +- Keep reading for more information about setting up a workstation, configuring Test Kitchen to run virtual environments, setting up a more detailed cookbook, resources, and more. diff --git a/content/reference.md b/content/reference.md deleted file mode 100644 index 421656d..0000000 --- a/content/reference.md +++ /dev/null @@ -1,32 +0,0 @@ -+++ -title = "Habitat command reference" - -[menu.reference] -title = "Habitat reference" -+++ - -With Habitat-based Chef Infra Client builds, you can use the following common functions for troubleshooting. - -## List the gems used with Habitat builds - -```sh -sudo hab pkg exec chef/chef-infra-client gem list -``` - -## List all the gems used with Habitat builds - -```sh -sudo hab pkg exec chef/chef-infra-client gem list --all -``` - -## Get the install path - -```sh -sudo hab pkg exec chef/chef-infra-client gem env -``` - -## Get Ruby version - -```sh -/hab/bin/hab pkg exec core/ruby3_1 ruby -v -``` diff --git a/content/reference/_index.md b/content/reference/_index.md new file mode 100644 index 0000000..f56d3e0 --- /dev/null +++ b/content/reference/_index.md @@ -0,0 +1,7 @@ ++++ +title = "Chef Infra Client reference" +draft = false +list_pages = true +LinkTitle = "Reference" +layout = "list" ++++ \ No newline at end of file diff --git a/content/reference/chef_deprecations_client/_index.md b/content/reference/chef_deprecations_client/_index.md new file mode 100644 index 0000000..de46c83 --- /dev/null +++ b/content/reference/chef_deprecations_client/_index.md @@ -0,0 +1,363 @@ ++++ +title = "Chef Deprecation Warnings" +draft = false + +[menu] + [menu.reference] + title = "Deprecations" + identifier = "reference/chef_deprecations_client.md Deprecations" + parent = "reference" + weight = 90 ++++ + + + +When we wish to remove a feature or an API in Chef, we try to first mark +it with a deprecation warning that contains a link to a description of +the change and how to fix it. For example: + +```ruby +Deprecated features used! + JSON auto inflation isn't supported (CHEF-1) at (irb):7:in `irb_binding`. + Please see /chef-client/deprecations/json_auto_inflate.html for further details and information on how to correct this problem. +``` + +## Testing for Deprecations + +To test your code for deprecations, you can put Test Kitchen in a mode +where any deprecations cause the chef run to fail. Ensure your +`kitchen.yml` includes: + +```yaml +provisioner: + deprecations_as_errors: true +``` + +and then run Test Kitchen as usual. Test Kitchen will fail if any +deprecation errors are issued. + +## Silencing deprecation warnings + +Deprecation warnings are great for ensuring cookbooks are kept +up-to-date and to prepare for major version upgrades, sometimes you just +can't fix a deprecation right away. Enabling +`treat_deprecation_warnings_as_errors` mode in Test Kitchen integration +tests often compounds the problem because it doesn't distinguish +between deprecations from community cookbooks and those in your own +code. + +Two new options are provided for silencing deprecation warnings: +`silence_deprecation_warnings` and inline `chef:silence_deprecation` +comments. + +The `silence_deprecation_warnings` configuration value can be set in +your `client.rb` or `solo.rb` config file, either to `true` to silence +all deprecation warnings or to an array of deprecations to silence. You +can specify which to silence either by the deprecation key name (for example, +`"internal_api"`), the numeric deprecation ID (for example, `25` or "CHEF-25"), or by specifying the filename and +line number where the deprecation is being raised from (for example, +`"default.rb:67"`). + +An example of setting the `silence_deprecation_warnings` option in your +`client.rb` or `solo.rb`: + +```ruby +silence_deprecation_warnings %w{deploy_resource chef-23 recipes/install.rb:22} +``` + +or in your \`kitchen.yml\`: + +```yaml +provisioner: + name: chef_solo + solo_rb: + treat_deprecation_warnings_as_errors: true + silence_deprecation_warnings: + - deploy_resource + - chef-23 + - recipes/install.rb:22 +``` + +You can also silence deprecations using a comment on the line that's +raising the warning: + +```ruby +erl_call 'something' do # chef:silence_deprecation +``` + +We advise caution in the use of this feature, as excessive or prolonged +silencing can lead to difficulty upgrading when the next major release +of Chef comes out. + +## All Deprecations + + ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IDDescriptionDeprecatedExpected Removal
CHEF-0Many internal APIs have been improved.variousvaries
CHEF-1Consumers of JSON are now required to be explicit in how it's turned in to a Chef object.12.713.0
CHEF-2Chef's exit codes are now defined so that it's easy to understand why Chef exited.12.1113.0
CHEF-3When using the chef_gem resource, the phase to install the gem in must be specified.12.113.0
CHEF-4Various improvements have been made to attribute syntax.variousvaries
CHEF-5Various improvements have been made to custom resource syntax.variousvaries
CHEF-6The easy_install resource will be removed.12.1013.0
CHEF-7The verify metaproperty's file substitution will be removed.12.513.0
CHEF-8The supports metaproperty will be removed.12.1413.0
CHEF-9The Chef::REST API will be removed.12.713.0
CHEF-10DNF package provider and resource don't require --allow-downgrade anymore.12.1813.0
CHEF-11An exception will be raised if a resource property conflicts with an already-existing property or method.12.1913.0
CHEF-12An exception will be raised whenever the hash property in the launchd resource is used.12.1913.0
CHEF-13Deprecated Chef::Platform methods12.1813.0
CHEF-14Deprecation of run_command12.1813.0
CHEF-18Deprecation of local mode listening.13.115.0
CHEF-19Deprecation of property_name within actions.13.214.0
CHEF-20Deprecation of the deploy resource.13.614.0
CHEF-21Deprecation of the :uninstall action in the chocolatey_package resource.13.714.0
CHEF-22Deprecation of the erl_call resource.13.714.0
CHEF-23Deprecation of legacy HWRP mixins.12.X14.0
CHEF-24Deprecation of epic_fail in favor of allow_failure13.714.0
CHEF-25Resources in a cookbook collide with the same resources now included in Chef Infra Client.XX.X15.0
CHEF-26Deprecation of legacy shell_out APIs.14.315.0
CHEF-27Deprecation of lc_all from locale resource15.016.0
CHEF-31Deprecation of resource_name declaration without provides15.1316.2
CHEF-33Enabling Unified Mode in custom resources17.0
CHEF-3694Resource Cloning will no longer work.10.1813.0
OHAI-1Ohai::Config removal.12.613.0
OHAI-2Sigar gem based plugins removal.12.1913.0
OHAI-3run_command and popen4 helper method removal.12.813.0
OHAI-4Libvirt plugin attributes changes.12.1914.0
OHAI-5Windows CPU plugin attribute changes.12.1913.0
OHAI-6DigitalOcean plugin attribute changes.12.1913.0
OHAI-7Amazon linux moved to the Amazon platform_family.13.013.0
OHAI-8Cloud plugin replaced by the Cloud_V2 plugin.13.013.0
OHAI-9Filesystem plugin replaced by the Filesystem V2 plugin.13.013.0
OHAI-10Removal of support for Ohai version 6 plugins.11.1214.0
OHAI-11Cloud_v2 attribute removal.13.114.0
OHAI-12Filesystem2 attribute removal.13.114.0
OHAI-13Removal of IpScopes plugin13.214.0
OHAI-14Removal of system_profile plugin14.615.0
diff --git a/content/reference/chef_deprecations_client/deprecations_attributes.md b/content/reference/chef_deprecations_client/deprecations_attributes.md new file mode 100644 index 0000000..845690e --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_attributes.md @@ -0,0 +1,72 @@ ++++ +title = "Deprecation: Some Attribute Methods (CHEF-4)" +draft = false + +gh_repo = "chef-web-docs" +sitemapExclude = true +robots = "noindex" + +aliases = "/deprecations_attributes.html" + ++++ + +We're continuously improving and streamlining the way attributes work +in Chef, to make it easier for users to reason about and safely +configure their servers. + +This page documents many deprecations over the course of many Chef +releases. + +## Method Access + +Setting and accessing node attributes has been standardized on "bracket" +syntax. The older "method" syntax is deprecated and will be removed in +Chef Infra Client 13. + +Removal: Chef Infra Client 13 + +### Example + +Both lines in the example will cause separate deprecation warnings. + +```ruby +node.chef.server = 'https://my.chef.server' +chef_server = node.chef.server +``` + +### Remediation + +Convert method syntax to bracket syntax by using brackets to denote +attribute names. The code below is identical in function to the example +above: + +```ruby +node['chef']['server'] = 'https://my.chef.server' +chef_server = node['chef']['server'] +``` + +## Set and Set_Unless + +Setting node attributes with `set` or `set_unless` has been deprecated +in favor of explicitly setting the precedence level. These methods will +be removed in Chef Infra Client 14. + +Removal: Chef Infra Client 14 + +### Example + +```ruby +node.set['chef']['server'] = 'https://my.chef.server' +node.set_unless['chef']['server'] = 'https://my.chef.server' +``` + +### Remediation + +Choose the appropriate [precedence +level](/cookbooks/attributes/attribute_precedence/), then replace `set` with +that precedence level. + +```ruby +node.default['chef']['server'] = 'https://my.chef.server' +node.default_unless['chef']['server'] = 'https://my.chef.server' +``` diff --git a/content/reference/chef_deprecations_client/deprecations_chef_gem_compile_time.md b/content/reference/chef_deprecations_client/deprecations_chef_gem_compile_time.md new file mode 100644 index 0000000..8768804 --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_chef_gem_compile_time.md @@ -0,0 +1,41 @@ ++++ +title = "Deprecation: Chef Gem Compile Time (CHEF-3)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_chef_gem_compile_time.html" + ++++ + +Originally, the [chef gem](/resources/bundled/chef_gem/) resource always ran +during the compile phase (see this +section on [Chef Infra Client runs](/#the-chef-infra-client-run) for further +details). It's now possible to control which phase the resource is run +in. Calling `chef_gem` without specifying the phase is now deprecated. + +This deprecation warning was added in Chef Infra Client 12.1.0, and using +`chef_gem` without specifying a phase will become an error in Chef +Client 13. + +## Remediation + +There are two possible remediations. + +The first is to set the `compile_time` property on the resource. To +maintain the same behavior as before, the property should be set to +`true`: + +```ruby +chef_gem 'etcd' do + compile_time true +end +``` + +The second, and preferred, is to add a [gem +dependency](/cookbooks/config_rb_metadata/) in your cookbook metadata. + +```ruby +gem 'etcd' +``` diff --git a/content/reference/chef_deprecations_client/deprecations_chef_platform_methods.md b/content/reference/chef_deprecations_client/deprecations_chef_platform_methods.md new file mode 100644 index 0000000..3133377 --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_chef_platform_methods.md @@ -0,0 +1,138 @@ ++++ +title = "Deprecation: Chef::Platform methods (CHEF-13)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_chef_platform_methods.html" ++++ + +Several methods under `Chef::Platform` that were previously public APIs +to control resolution of provider classes were replaced by the dynamic +`Chef::ProviderResolver` work and the `provides` keyword. + +This deprecation warning was added in Chef Infra Client 12.18.x, and using +these APIs will become a hard error in Chef Infra Client 13. + +## Remediation + +Code which used to use `Chef::Platform.provider_for_resource` or +`Chef::Platform.find_provider` to create providers for a resource: + +```ruby +resource = Chef::Resource::File.new("/tmp/foo.xyz", run_context) +provider = Chef::Platform.provider_for_resource(resource, :create) + +resource = Chef::Resource::File.new("/tmp/foo.xyz", run_context) +provider = Chef::Platform.find_provider("ubuntu", "16.04", resource) + +resource = Chef::Resource::File.new("/tmp/foo.xyz", run_context) +provider = Chef::Platform.find_provider_for_node(node, resource) +``` + +Should instead use the `Chef::Resource#provider_for_action` API on the +instance of the resource: + +```ruby +resource = Chef::Resource::File.new("/tmp/foo.xyz", run_context) +provider = resource.provider_for_action(:create) +``` + +As the internal resources and providers in core chef have been ported +over to use the `Chef::ProviderResolver` dynamic resolution the use of +the old Chef::Platform class methods have actually been broken. Tools +like `chefspec` and `chef-minitest-handler` were ported over to the new +APIs in Chef Infra Client 12.0. The `Chef::Resource#provider_for_action` API +dates back to before Chef Infra Client 11.0.0 and is fully backwards +compatible, any remaining code using the old APIs should be exceedingly +buggy at this point. + +Also, code which used to use `Chef::Platform.set` to register providers +for a platform/platform_version should use the `provides` keyword on +the provider instead: + +```ruby +Chef::Platform.set platform: :fedora, version: '>= 19', resource: :mysql_service, provider: Chef::Provider::MysqlServiceSystemd +``` + +Should be replaced by: + +```ruby +class Chef::Provider::MysqlServiceSystemd +provides :mysql_service, platform: "fedora", platform_version: ">= 19" +``` + +This can also be directly sent to the provider class in library code, +although this form is less encouraged (which doesn't mean the same +thing as discouraged -- but you gain better code organization with the +prior code): + +```ruby +Chef::Provider::MysqlSserviceSystemd.provides :mysql_service, platform: "fedora", platform_version: ">= 19" +``` + +The `provides` API on providers is only supported in Chef Infra Client 12.0 or +later. This change will create a hard backwards compatibility break +between Chef Infra Client 13 and Chef Infra Client 11 without the cookbook doing the +work to check the Chef::VERSION and switch between these APIs. This API +is supported back to Chef Infra Client 12.0, although some more advanced forms +of the `provides` syntax were only introduced in Chef Infra Client 12.5.1. + +Also you may have found this web page due to deprecation of +library-based resources and providers that don't declare provides in +which case your Chef Infra Client run is likely full of a compilation of +warnings and deprecations: + +```plain +* foo[it] action doit[2016-12-07T14:28:59-08:00] WARN: Class Chef::Provider::Foo doesn't declare 'provides :foo'. + [2016-12-07T14:28:59-08:00] WARN: This will no longer work in Chef Infra Client 13: you must use 'provides' to use the resource's DSL. + (up to date) + +Running handlers: +Running handlers complete + +Deprecated features used! +Class.find_provider_for_node is deprecated at 1 location: +- /Users/lamont/.rvm/rubies/ruby-2.3.1/lib/ruby/2.3.0/forwardable.rb:189:in 'execute_each_resource' + See /deprecations_chef_platform_methods.html for further details. +Class.find_provider is deprecated at 1 location: +- /Users/lamont/.rvm/rubies/ruby-2.3.1/lib/ruby/2.3.0/forwardable.rb:189:in 'execute_each_resource' + See /deprecations_chef_platform_methods.html for further details. +Class.find is deprecated at 1 location: +- /Users/lamont/.rvm/rubies/ruby-2.3.1/lib/ruby/2.3.0/forwardable.rb:189:in 'execute_each_resource' + See /deprecations_chef_platform_methods.html for further details. +``` + +In this case, the initial warning that +`Class Chef::Provider::Foo doesn't declare 'provides :foo'` is accurate +and gives the remediation. + +Code that looks like this: + +```ruby +class Chef::Provider::Foo < Chef::Provider::LWRPBase + use_inline_resources + + action :doit do + [ ... stuff ... ] + end +end +``` + +Must be changed to explicitly declare the resource it provides: + +```ruby +class Chef::Provider::Foo < Chef::Provider::LWRPBase + provides :foo + + use_inline_resources + + action :doit do + [ ... stuff ... ] + end +end +``` + +The use of custom resources over library class providers that inherit +from LWRPBase is also encouraged. diff --git a/content/reference/chef_deprecations_client/deprecations_chef_rest.md b/content/reference/chef_deprecations_client/deprecations_chef_rest.md new file mode 100644 index 0000000..a44a41c --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_chef_rest.md @@ -0,0 +1,29 @@ ++++ +title = "Deprecation: Chef REST (CHEF-9)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_chef_rest.html" + ++++ + +The `Chef::REST` class will be removed. + +`Chef::REST` was deprecated in Chef Infra Client 12.7.2, and will be removed +in Chef Infra Client 13. + +The [Cookstyle](https://docs.chef.io/workstation/cookstyle.html) cop +[ChefDeprecations/UsesChefRESTHelpers](https://github.com/chef/cookstyle/blob/main/docs/cops_chefdeprecations.md#chefdeprecationsuseschefresthelpers) +has been introduced to detect this deprecation. + +## Remediation + +If writing code designed to be run internally to Chef, for example in a +cookbook or a knife plugin, transition to using `Chef::ServerAPI`. In +most cases this is as simple as creating a `Chef::ServerAPI` instance +rather than a `Chef::REST` one. + +If writing code to interact with a Chef Infra Server from other code, +move to the [chef-api gem](https://rubygems.org/gems/chef-api). diff --git a/content/reference/chef_deprecations_client/deprecations_chocolatey_uninstall.md b/content/reference/chef_deprecations_client/deprecations_chocolatey_uninstall.md new file mode 100644 index 0000000..4757d8f --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_chocolatey_uninstall.md @@ -0,0 +1,41 @@ ++++ +title = "Deprecation: :uninstall Resource for chocolatey_package (CHEF-21)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_chocolatey_uninstall.html" + ++++ + +The Chocolatey cookbook's `chocolatey_package` resource originally +contained an `:uninstall` action. When +[chocolatey_package](/resources/bundled/chocolatey_package/) was moved into +core Chef, we made `:uninstall` an alias for `:remove`. In Chef Infra Client +14, `:uninstall` will no longer be a valid action. + +The [Cookstyle](https://docs.chef.io/workstation/cookstyle/) cop +[ChefDeprecations/ChocolateyPackageUninstallAction](https://github.com/chef/cookstyle/blob/main/docs/cops_chefdeprecations.md#chefdeprecationschocolateypackageuninstallaction) +has been introduced to detect and autocorrect this deprecation. + +## Remediation + +The `:uninstall` action must be replaced with the `:remove` action when +using the `chocolatey_package` resource in recipes that you intend to +use with Chef Infra Client 14. For example, where you might previously have +used the following code to uninstall `nginx`: + +```ruby +chocolatey_package 'nginx' do + action :uninstall +end +``` + +You would instead use: + +```ruby +chocolatey_package 'nginx' do + action :remove +end +``` diff --git a/content/reference/chef_deprecations_client/deprecations_custom_resource_cleanups.md b/content/reference/chef_deprecations_client/deprecations_custom_resource_cleanups.md new file mode 100644 index 0000000..4ea3726 --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_custom_resource_cleanups.md @@ -0,0 +1,167 @@ ++++ +title = "Deprecation: Custom Resource Cleanups (CHEF-5)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_custom_resource_cleanups.html" + ++++ + +We're continuously improving and streamlining the way custom resources +work in Chef, to make it easier for cookbook authors and Chef developers +to build resources. + +This page documents many deprecations over the course of many Chef +releases. + +## Nil Properties + +In current versions of Chef, `nil` was often used to mean that a +property had no good default, and needed to be set by the user. However, +it's often to useful to set a property to `nil`, meaning that it's not +set and should be ignored. In Chef Infra Client 13, it's an error to set +`default: nil` on a property if that property doesn't allow `nil` as a +valid value. + +### Remediation + +If it's valid for the property to be set to nil, then update the +property to include that. + +```ruby +property :my_nillable_property, [ String, nil ], default: nil +``` + +Otherwise, remove the `default: nil` statement from the property. + +## Invalid Defaults + +Current versions of Chef emit a warning when a property's default value +isn't valid. This is often because the type of the default value +doesn't match the specification of the property. For example: + +```ruby +property :my_property, [ String ], default: [] +``` + +sets the type of the property to be a String, but then sets the default +to be an Array. In Chef Infra Client 13, this will be an error. + +### Remediation + +Ensure that the default value of a property is correct. + +## Property Getters + +When writing a resource in Chef Infra Client 12, calling `some_property nil` +behaves as a getter, returning the value of `some_property`. In Chef +Client 13, this will change to set `some_property` to `nil`. + +### Remediation + +Simply write `some_property` when retrieving the value of +`some_property`. + +## Specifying both "default" and "name_property" on a resource + +Current versions of Chef emit a warning if the property declaration has +both `default` and `name_property` set. In Chef Infra Client 13, that will +become an error. For example: + +```ruby +property :my_property, [ String ], default: [], name_property: true +``` + +### Remediation + +A property can either have a default, or it can be a "name" property +(meaning that it will take the value of the resource's name if not +otherwise specified), but not both. + +## Overriding provides? + +Some providers override the `provides?` method, used to check whether +they're a valid provider on the current platform. In Chef Infra Client 13, +this will cause an error if the provider doesn't also register +themselves with the `provides` call. + +### Example + +```ruby +def provides? + true +end +``` + +### Remediation + +```ruby +provides :my_provider + +def provides? + true +end +``` + +## don't use the updated method + +The `updated=(true_or_false)` method is deprecated and will be removed +from Chef Infra Client 13. This method never performed its intended job, as +notifications from the resource would not fire, and in general its use +has always been buggy. The Chef Infra Client notification code checks +`updated_by_last_action?` instead, so setting that's recommended as a +substitute. See the +[updated_by_last_action](/resources/custom/custom_resources_notes/#updated_by_last_action) +documentation for more information. + +{{< note >}} + +Setting `updated_by_last_action` is almost always unnecessary, and +correct use of `use_inline_resources` (which is the default in Chef +Client 13 and above) makes the `updated_by_last_action` setting +redundant. Simply deleting this code is likely to be the correct +course of action in most cases. + +{{< /note >}} + +### Example + +```ruby +action :foo do + updated = true +end +``` + +### Remediation + +```ruby +action :foo do + new_resource.updated_by_last_action true +end +``` + +## don't use the dsl_name method + +The `dsl_name` method is deprecated and will be removed from Chef Infra Client. It has been replaced by `resource_name`. + +### Example + +```ruby +my_resource = MyResource.dsl_name +``` + +### Remediation + +```ruby +my_resource = MyResource.resource_name +``` + +## don't use the provider_base method + +The `Resource.provider_base` allows the developer to specify an +alternative module to load providers from, rather than `Chef::Provider`. +It's deprecated and will be removed in Chef Infra Client 13. Instead, the +provider should call `provides` to register itself, or the resource +should call `provider` to specify the provider to use. diff --git a/content/reference/chef_deprecations_client/deprecations_deploy_resource.md b/content/reference/chef_deprecations_client/deprecations_deploy_resource.md new file mode 100644 index 0000000..48fc0eb --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_deploy_resource.md @@ -0,0 +1,19 @@ ++++ +title = "Deprecation: Deploy Resource (CHEF-20)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_deploy_resource.html" ++++ + +The `deploy` and `deploy_revision` resources have been deprecated as of +Chef Infra Client 13.6, and will be removed in Chef Infra Client 14. + +## Remediation + +For users that require the `deploy` or `deploy_revision` resources, they +are now part of the +[deploy_resource](https://supermarket.chef.io/cookbooks/deploy_resource) +backwards compatibility cookbook available on the Supermarket. diff --git a/content/reference/chef_deprecations_client/deprecations_dnf_package_allow_downgrade.md b/content/reference/chef_deprecations_client/deprecations_dnf_package_allow_downgrade.md new file mode 100644 index 0000000..c29c65e --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_dnf_package_allow_downgrade.md @@ -0,0 +1,18 @@ ++++ +title = "Deprecation: DNF Package allow_downgrade Property (CHEF-10)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_dnf_package_allow_downgrade.html" ++++ + +The underlying `dnf` command in Red Hat based operating systems doesn't +require `--allow-downgrade` like the previous `yum` command did. This +property doesn't affect the `dnf_resource` resource execution and +should be removed. + +## Remediation + +Remove the `allow_downgrade` property on the `dnf_package` resource. diff --git a/content/reference/chef_deprecations_client/deprecations_easy_install.md b/content/reference/chef_deprecations_client/deprecations_easy_install.md new file mode 100644 index 0000000..6c1c2c1 --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_easy_install.md @@ -0,0 +1,24 @@ ++++ +title = "Deprecation: Easy Install Resource (CHEF-6)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_easy_install.html" ++++ + +The Python community recommends that users prefer `pip` rather than +`easy_install` to install python packages. + +The `easy_install` resource was deprecated in Chef Infra Client 12.10, and +will be removed in Chef Infra Client 13. + +The [Cookstyle](https://docs.chef.io/workstation/cookstyle/) cop +[ChefDeprecations/EasyInstallResource](https://github.com/chef/cookstyle/blob/main/docs/cops_chefdeprecations.md#chefdeprecationseasyinstallresource) +has been introduced to detect this deprecation. + +## Remediation + +There is no built-in replacement for `easy_install` in Chef Infra Client +at this time. diff --git a/content/reference/chef_deprecations_client/deprecations_epic_fail.md b/content/reference/chef_deprecations_client/deprecations_epic_fail.md new file mode 100644 index 0000000..686b269 --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_epic_fail.md @@ -0,0 +1,23 @@ ++++ +title = "Deprecation: epic_fail (CHEF-24)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_epic_fail.html" ++++ + +The original name for the `ignore_failure` property in resources was +`epic_fail`. Our documentation hasn't referred to `epic_fail` for years +and out of the 3500 cookbooks on the Supermarket only one uses +`epic_fail`. In Chef Infra Client 14 we will remove the `epic_fail` property +entirely. + +The [Cookstyle](https://docs.chef.io/workstation/cookstyle/) cop +[ChefDeprecations/EpicFail](https://github.com/chef/cookstyle/blob/main/docs/cops_chefdeprecations.md#chefdeprecationsepicfail) +has been introduced to detect and autocorrect this deprecation. + +## Remediation + +Replace any usage of `epic_fail` with `ignore_failure`. diff --git a/content/reference/chef_deprecations_client/deprecations_erl_call_resource.md b/content/reference/chef_deprecations_client/deprecations_erl_call_resource.md new file mode 100644 index 0000000..6642f60 --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_erl_call_resource.md @@ -0,0 +1,20 @@ ++++ +title = "Deprecation: Deprecation of the erl_call resource (CHEF-22)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_erl_call_resource.html" ++++ + +The erl_call resource was deprecated in Chef Infra Client 13.7 and removed +from Chef Infra Client 14.0 (April 2018). + +The [Cookstyle](https://docs.chef.io/workstation/cookstyle/) cop +[ChefDeprecations/ErlCallResource](https://github.com/chef/cookstyle/blob/main/docs/cops_chefdeprecations.md#chefdeprecationserlcallresource) +has been introduced to detect this deprecation. + +## Remediation + +Remove usage of the erl_call resource from all cookbooks. diff --git a/content/reference/chef_deprecations_client/deprecations_exit_code.md b/content/reference/chef_deprecations_client/deprecations_exit_code.md new file mode 100644 index 0000000..61081e5 --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_exit_code.md @@ -0,0 +1,35 @@ ++++ +title = "Deprecation: Old Exit Codes (CHEF-2)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_exit_code.html" ++++ + +In older versions of Chef Infra Client, it wasn't possible to discern why a +chef run exited simply by examining the error code. This makes it +tricky for tools such as Test Kitchen to reason about the status of a +Chef Infra Client run. Starting in Chef Infra Client 12.11, there are now well +defined exit codes that the Chef Infra Client can use to communicate the +status of the run. + +This deprecation was added in Chef Infra Client 12.11. In Chef Infra Client 13, only +the extended set of exit codes will be supported. For further +information on the list of defined error codes, please see [RFC 62, +which defines +them](https://github.com/chef/chef-rfc/blob/main/rfc062-exit-status.md). + +## Remediation + +If you have built automation that's dependent on the old behavior of +Chef Infra Client, we strongly recommend updating it to support the extended +set of exit codes. However, it's still possible to enable the old +behavior. Add the setting + +```ruby +exit_status :disabled +``` + +to the Chef config file. diff --git a/content/reference/chef_deprecations_client/deprecations_internal_api.md b/content/reference/chef_deprecations_client/deprecations_internal_api.md new file mode 100644 index 0000000..da9eb9e --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_internal_api.md @@ -0,0 +1,13 @@ ++++ +title = "Deprecation: Internal API Changes (CHEF-0)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_internal_api.html" ++++ + +During the lifecycle of a release, we realize that some APIs are no +longer fit for purpose, or are simply unused. We try to mark those APIs +for removal in the next major release. diff --git a/content/reference/chef_deprecations_client/deprecations_json_auto_inflate.md b/content/reference/chef_deprecations_client/deprecations_json_auto_inflate.md new file mode 100644 index 0000000..96874df --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_json_auto_inflate.md @@ -0,0 +1,37 @@ ++++ +title = "Deprecation: JSON Auto Inflate (CHEF-1)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_json_auto_inflate.html" ++++ + +Internally, the `Chef::REST` class attempts to guess which Chef class a +JSON document relates too, and then automatically turns the JSON in to +that class. + +This deprecation warning was added in Chef Infra Client 12.7.2, and JSON auto +inflation will be removed permanently in Chef Infra Client 13. + +## Example + +When loading an environment from the Chef Infra Server, you might +previously have written: + +```ruby +name = 'my_environment' +chef_server_rest.get("environments/#{name}") +``` + +and received a `Chef::Environment` object back. + +## Remediation + +You now need to explicitly create a new object of the desired type. + +```ruby +name = 'my_environment' +Chef::Environment.from_hash chef_server_rest.get("environments/#{name}") +``` diff --git a/content/reference/chef_deprecations_client/deprecations_launchd_hash_property.md b/content/reference/chef_deprecations_client/deprecations_launchd_hash_property.md new file mode 100644 index 0000000..db1d122 --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_launchd_hash_property.md @@ -0,0 +1,33 @@ ++++ +title = "Deprecation: Launchd hash Property (CHEF-12)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_launchd_hash_property.html" ++++ + +The launchd resource has a property called `hash` which conflicts with +the already-existing Ruby `hash` method that exists on every object. + +The [CHEF-11](deprecations_property_name_collision) deprecation +warns whenever a resource property is named the same as an existing Ruby +method. Chef's core `launchd` resource is guilty of this behavior. The +`hash` property accepts a Ruby Hash containing the data to be output to +the launchd property list. However, `hash` is an already-existing Ruby +method. + +A deprecation warning is logged when the `hash` property is used. In +Chef Infra Client 13, this will raise an exception and your Chef run will +fail. + +The [Cookstyle](https://docs.chef.io/workstation/cookstyle/) cop +[ChefDeprecations/LaunchdDeprecatedHashProperty](https://github.com/chef/cookstyle/blob/main/docs/cops_chefdeprecations.md#chefdeprecationslaunchddeprecatedhashproperty) +has been introduced to detect and autocorrect this deprecation. + +## Remediation + +When using the `launchd` resource and passing a hash for the launchd +property list, use the `plist_hash` property instead of the `hash` +property. diff --git a/content/reference/chef_deprecations_client/deprecations_legacy_hwrp_mixins.md b/content/reference/chef_deprecations_client/deprecations_legacy_hwrp_mixins.md new file mode 100644 index 0000000..1200faf --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_legacy_hwrp_mixins.md @@ -0,0 +1,23 @@ ++++ +title = "Deprecation: Legacy HWRP mixins (CHEF-23)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_legacy_hwrp_mixins.html" ++++ + +In Chef Infra Client 14 several legacy mixins will be removed. Usage of these +mixins has resulted in deprecation warnings for several years. They were +traditionally used in some HWRPs. + +The [Cookstyle](https://docs.chef.io/workstation/cookstyle/) cop +[ChefDeprecations/UsesDeprecatedMixins](https://github.com/chef/cookstyle/blob/main/docs/cops_chefdeprecations.md#chefdeprecationsusesdeprecatedmixins) +has been introduced to detect these mixins: + +- `Chef::Mixin::LanguageIncludeAttribute` +- `Chef::Mixin::RecipeDefinitionDSLCore` +- `Chef::Mixin::LanguageIncludeRecipe` +- `Chef::Mixin::Language` +- `Chef::DSL::Recipe::FullDSL` diff --git a/content/reference/chef_deprecations_client/deprecations_local_listen.md b/content/reference/chef_deprecations_client/deprecations_local_listen.md new file mode 100644 index 0000000..82728b7 --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_local_listen.md @@ -0,0 +1,27 @@ ++++ +title = "Deprecation: Local Mode Listen (CHEF-18)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_local_listen.html" ++++ + +When using chef-client Local Mode, there +are two ways to launch the internal Chef Zero server. Originally we +launched it as a normal network service on localhost and then connected +to it normally. This meant that any user or process +on the machine could also connect to the Zero server during the converge +and because Chef Zero has no authentication or authorization systems, +they could alter data mid-converge. We later added a +"socketless" mode, which runs the Zero server completely internally and +never exposes it on a real socket. + +## Remediation + +If you need to re-enable socket mode for now, you can run chef-client --local-mode --listen or set knife\[:listen\] = true in your .chef/knife.rb or .chef/config.rb. diff --git a/content/reference/chef_deprecations_client/deprecations_locale_lc_all.md b/content/reference/chef_deprecations_client/deprecations_locale_lc_all.md new file mode 100644 index 0000000..8ed3050 --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_locale_lc_all.md @@ -0,0 +1,62 @@ ++++ +title = "Deprecation: Deprecation of lc_all from locale resource (CHEF-27)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_locale_lc_all.html" ++++ + +Setting the `LC_ALL` variable isn't recommended. As a system-wide +setting, `LANG` should provide the desired behavior. `LC_ALL` is +intended to be used for temporarily troubleshooting issues rather than +an everyday system setting. Changing `LC_ALL` can break Chef's parsing +of command output in unexpected ways. Use one of the more specific `LC_` +properties as needed. This deprecation warning was added in Chef Infra +Client 15.0. Support for property `lc_all` will be removed for Chef +Infra Client 16.0. + +The [Cookstyle](https://docs.chef.io/workstation/cookstyle/) cop +[ChefDeprecations/LocaleDeprecatedLcAllProperty](https://github.com/chef/cookstyle/blob/main/docs/cops_chefdeprecations.md#chefdeprecationslocaledeprecatedlcallproperty) +has been introduced to detect and autocorrect this deprecation. + +## Remediation + +Set `LC_ALL` in current shell as: + +```bash +export LC_ALL="" +``` + +To check the `locale` value, run: + +```bash +locale -v +``` + +You can also use **file** Resource and add this variable in any other +file of your choice and then can source that file to reflect changes. + +```ruby +file "" do + content "LC_ALL=" +end +``` + +Where `path_to_file` could be any one of: + +* `/etc/default/locale` +* `/etc/sysconfig/i18n` +* `/etc/environment` + +Setting **LC_** variables varies by platform, but these are the common +locations to configure **LC_** variables. + +{{< warning >}} + +Using the **file** Resource or other manual management method of LC +configuration may overwrite settings from this resource and break your +system. + +{{< /warning >}} diff --git a/content/reference/chef_deprecations_client/deprecations_map_collision.md b/content/reference/chef_deprecations_client/deprecations_map_collision.md new file mode 100644 index 0000000..e56171f --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_map_collision.md @@ -0,0 +1,20 @@ ++++ +title = "Deprecation: Map Collision (CHEF-25)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_map_collision.html" ++++ + +The resources referenced in the error message has been loaded from a +cookbook. This resource is now included in Chef Infra Client and will +take precedence over the existing cookbook resource in the next major +release of Chef Infra Client (15.0, April 2019). Alternatively, there +may be a newer version of this cookbook without this resource. + +## Remediation + +Please upgrade your cookbook to the latest version, which may fix your +issue, or ignore this error message. diff --git a/content/reference/chef_deprecations_client/deprecations_namespace_collisions.md b/content/reference/chef_deprecations_client/deprecations_namespace_collisions.md new file mode 100644 index 0000000..af9c6aa --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_namespace_collisions.md @@ -0,0 +1,197 @@ ++++ +title = "Deprecation: Use of property_name inside of actions (CHEF-19)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_namespace_collisions.html" ++++ + +In Chef Infra Client 12.5.1, the custom resources API allowed specifying +property names as the short form of `property_name` inside of actions, +instead of the long form of `new_resource.property_name` (as was +previously required in provider code in LWRPs/HWRPs/etc). That change +caused unsolvable namespace clashes and will be removed in Chef Infra Client +14.0, and it will become mandatory to refer to properties as +`new_resource.property_name` in actions. + +## Example + +This code worked in Chef Infra Client 12.5.1 and later revisions up to Chef +Client 13.0: + +```ruby +property :my_content, String + +action :doit do + file '/tmp/file.xy' do + content my_content + end +end +``` + +## Remediation + +The `my_content` reference will no longer be wired up automatically to +the `new_resource` object and users will need to specify +`new_resource.my_content` explicitly: + +```ruby +property :my_content, String + +action :doit do + file '/tmp/file.xy' do + content new_resource.my_content + end +end +``` + +## Note + +In some edge cases, this deprecation warning may mention that the +property should be referred to as `current_resource.property_name` +instead of `new_resource.property_name`, which isn't a mistake; the +user should instead use the `current_resource.property_name` to preserve +prior behavior, or should modify their code to explicitly check the +`current_resource` if the `new_resource` isn't set. There are several +possible remediations to this in the order of least complicated to the +most compatible with the old behavior, and the user will need to select +what works best for their use case: + +```ruby +content_to_set = new_resource.property_name || current_resource.property_name +content_to_set = new_resource.property_name.nil? ? current_resource.property_name : new_resource.property_name +content_to_set = new_resource.property_is_set?(:property_name) ? new_resource.property_name : current_resource.property_name +``` + +Unfortunately, if you were reliant upon the old code's automatic +switching between the `new_resource` and `current_resource` you will +need to be explicit. Most users, however, weren't aware that this was +occurring and moving that uncommon logic explicitly into the action code +will produce more comprehensible code that's less reliant on subtle +tricks of the API. + +It's also entirely possible that the access of the `current_resource` +was never intended by the user. If this behavior was undesired, the +correct remediation would be to simply access the property through the +`new_resource.property_name`. We can't determine and accurately report +to the user when this deprecation message is incorrect, we can only +report on compatible behavior. The suggestion of the deprecation warning +to access the property through `current_resource.property_name` may be +incorrect, and it's up to the discretion of the user to choose the +appropriate remediation for their needs. + +The fact that this is confusing behavior to explain is why it's being +removed. + +## Rationale + +The change in Chef Infra Client 12.5.1 caused several insolvable problems. One +of the worst was that properties would override DSL commands so that +(for example) if a user had a `template` property they could no longer +use the template resource: + +```ruby +property :template, String + +action :doit do + template '/tmp/file.xy' do # this would NOT create a template resource but would pass a string and a block to the template property + source 'file.xy.erb' + variables({ stuff: 'whatever' }) + end +end +``` + +The highly confusing workaround for this problem was to use +`declare_resource` to avoid the use of the resource DSL: + +```ruby +property :template, String + +action :doit do + declare_resource(:template, '/tmp/file.xy') do # now there is no ambiguity and we create a template resource + source 'file.xy.erb' + variables({ stuff: 'whatever' }) + end +end +``` + +This also caused issues when properties conflicted with properties on +subresources, where this example is ambiguous as to if the `content` +argument to `content` refers to the file subresource `content` property, +or if it refers to the parent custom resource `content` property. + +```ruby +property :content, String + +action :doit do + puts "content: #{content}" + file '/tmp/file.xy' do + content content + end +end +``` + +In fact, the subprocess wins (because it has to) and this code will +result in the content always being nil and the file being empty. The +output of the `puts` debugging will be correct, however, since `content` +is being accessed outside of the file resource scope so it acquires it +from the `new_resource` implicitly (in Chef Infra Client 12.5.1 and Chef +Client 13.x) + +The way to remediate that's by specifying the `new_resource`: + +```ruby +property :content, String + +action :doit do + file '/tmp/file.xy' do + content new_resource.content + end +end +``` + +We're now enforcing this as the correct way to write resources. + +Note that this namespace collision between custom resources and +subresources occurs with properties that aren't also being immediately +used, and so this fails as well: + +```ruby +property :mode, String + +action :doit do + file '/tmp/file.xy' do + content mode # this accesses the mode property on the file resource rather than the mode property on the outer resource + end +end +``` + +This will also cause namespace collisions if at some point in the future +a new property is introduced to a subresource. + +```ruby +property :spiffyness, String + +action :doit do + file '/tmp/file.xy' do + content spiffyness + end +end +``` + +This will work fine today, but if at some point in the future the file +resource grows a `spiffyness` property, then this will cause a namespace +collision with the custom resource and will result in the custom +resource failing. This is avoided by the explicit use of `new_resource`: + +```ruby +property :spiffyness, String + +action :doit do + file '/tmp/file.xy' do + content new_resource.spiffyness # we're always referring to the outer custom resource's spiffiness property + end +end +``` diff --git a/content/reference/chef_deprecations_client/deprecations_ohai_amazon_linux.md b/content/reference/chef_deprecations_client/deprecations_ohai_amazon_linux.md new file mode 100644 index 0000000..8f01c15 --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_ohai_amazon_linux.md @@ -0,0 +1,52 @@ ++++ +title = "Deprecation: Amazon linux moved to the Amazon platform_family (OHAI-7)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_ohai_amazon_linux.html" ++++ + +In Ohai/Chef releases before Chef Infra Client 13, Amazon Linux was +identified as `platform_family 'rhel'`. In Ohai/Chef Infra Client 13 and +later, Amazon Linux will be identified as the +`platform_family 'amazon'`. When Amazon Linux was created it closely +mirrored the structure and package naming of RHEL 5, and with the +release of RHEL 6 Amazon Linux moved to closely resemble RHEL 6. With +the release of RHEL 7 Red Hat switched to the systemd init system, +however Amazon Linux hasn't yet decided to make that same switch. In +addition to the init system differences, Amazon Linux has added many +critical packages with their own unique naming conventions. This makes +it hard for users to write cookbooks for RHEL that will work on +Amazon Linux systems out of the box. To simplify multi-platform +cookbook code and to make it more clear when cookbooks actually support +Amazon Linux, we've created the '`amazon` platform family and removed +Amazon Linux from the `rhel` platform family. + +## Remediation + +If you have a cookbook that relies on `platform_family 'rhel'` to +support Red Hat based distributions as well as Amazon Linux, you'll need +to modify your code to specifically check for the `'amazon'` platform +family. + +Existing code only checking for the `rhel` platform family: + +```ruby +if platform_family?('rhel') + service 'foo' do + action :start + end +end +``` + +Updated code to check for both `rhel` and `amazon` platform families: + +```ruby +if platform_family?('rhel', 'amazon') + service 'foo' do + action :start + end +end +``` diff --git a/content/reference/chef_deprecations_client/deprecations_ohai_cloud.md b/content/reference/chef_deprecations_client/deprecations_ohai_cloud.md new file mode 100644 index 0000000..defd954 --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_ohai_cloud.md @@ -0,0 +1,56 @@ ++++ +title = "Deprecation: Cloud plugin replaced by the Cloud_V2 plugin (OHAI-8)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_ohai_cloud.html" ++++ + +In Ohai/Chef releases 13 we replaced the existing Cloud plugin with the +Cloud_v2 plugin. This was done by having the Cloud_v2 plugin populate +both `node['cloud']` and `node['cloud_v2']`. The Cloud_v2 plugin +includes a different data format that resolves many of the longstanding +bugs in the existing Cloud plugin. + +## Remediation + +If you have a cookbook that relies on data from `node['cloud']` you will +need to update the code to the new format in Chef Infra Client 13. On a Chef +Client 12 or earlier node you can compare the data formats by running +`ohai cloud` and `ohai cloud_v2`. + +Here are examples of the old and new format of the cloud data: + +```json +{ + "public_ips": [ + "52.88.253.144" + ], + "private_ips": [ + "172.31.37.209" + ], + "public_ipv4": "52.88.253.144", + "public_hostname": "ec2-52-88-253-144.us-west-2.compute.amazonaws.com", + "local_ipv4": "172.31.37.209", + "local_hostname": "ip-172-31-37-209.us-west-2.compute.internal", + "provider": "ec2" +} +``` + +```json +{ + "public_ipv4_addrs": [ + "52.88.253.144" + ], + "local_ipv4_addrs": [ + "172.31.37.209" + ], + "public_hostname": "ec2-52-88-253-144.us-west-2.compute.amazonaws.com", + "local_hostname": "ip-172-31-37-209.us-west-2.compute.internal", + "public_ipv4": "52.88.253.144", + "local_ipv4": "172.31.37.209", + "provider": "ec2" +} +``` diff --git a/content/reference/chef_deprecations_client/deprecations_ohai_cloud_v2.md b/content/reference/chef_deprecations_client/deprecations_ohai_cloud_v2.md new file mode 100644 index 0000000..9c928a2 --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_ohai_cloud_v2.md @@ -0,0 +1,23 @@ ++++ +title = "Deprecation: Cloud_v2 attribute removal (OHAI-11)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_ohai_cloud_v2.html" ++++ + +In Ohai/Chef Infra Client 13 we replaced the existing Cloud plugin with the +Cloud V2 plugin. That was done by having Ohai populate both +`node['cloud']` and `node['cloud_v2']` with the data previously found at +`node['cloud_v2']`. In Chef Infra Client 14 we will no longer populate +`node['cloud_v2']`. + +## Remediation + +If you have a cookbook that relies on data from `node['cloud_v2']` you +will need to update the code to instead use `node['cloud']` attributes. +Keep in mind that if you're attempting to support Chef \< 13 this data +will be different. Foodcritic's FC095 rule will detect any usage of the +`node['cloud_v2']` attributes. diff --git a/content/reference/chef_deprecations_client/deprecations_ohai_digitalocean.md b/content/reference/chef_deprecations_client/deprecations_ohai_digitalocean.md new file mode 100644 index 0000000..590f0a8 --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_ohai_digitalocean.md @@ -0,0 +1,111 @@ ++++ +title = "Deprecation: DigitalOcean plugin attribute changes (OHAI-6)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_ohai_digitalocean.html" ++++ + +Ohai's previous Digital Ocean plugin relied on hint data passed to Ohai +as well and the drop's internal network interface configuration. The +Digital Ocean plugin has been rewritten to poll information from the +Digital Ocean Metadata endpoint instead. This provides additional +Digital Ocean specific droplet configuration information as well as +external IP address information that was previously not available. With +the addition of new network configuration data, the format has changed +and users relying on the previous format will need to update their +cookbooks. + +## Remediation + +Update cookbooks to use the new network data format as seen below. + +Example of previous data format: + +```json +{ + "networks": { + "v4": [ + { + "ip_address": "138.68.99.253", + "type": "public", + "netmask": "255.255.240.0" + }, + { + "ip_address": "10.19.0.5", + "type": "private", + "netmask": "255.255.0.0" + } + ], + "v6": [ + { + "ip_address": "2a03:b0c0:0003:00d0:0000:0000:322a:3001", + "type": "public", + "cidr": "128" + }, + { + "ip_address": "fe80:0000:0000:0000:d4b1:9eff:fe61:8cce", + "type": "private", + "cidr": "128" + } + ] + } +} +``` + +Example of new data format: + +```json +{ + "droplet_id": 12345678, + "hostname": "mytestnode", + "public_keys": [ + "ssh-rsa SOMEKEY", + ], + "auth_key": "SOMEKEY", + "region": "fra1", + "interfaces": { + "public": [ + { + "ipv4": { + "ip_address": "138.68.99.253", + "netmask": "255.255.240.0", + "gateway": "138.68.96.1" + }, + "ipv6": { + "ip_address": "2A03:B0C0:0003:00D0:0000:0000:322A:3001", + "cidr": 64, + "gateway": "2A03:B0C0:0003:00D0:0000:0000:0000:0001" + }, + "anchor_ipv4": { + "ip_address": "10.19.0.5", + "netmask": "255.255.0.0", + "gateway": "10.19.0.1" + }, + "mac": "d6:b1:9e:61:8c:ce", + "type": "public" + } + ] + }, + "floating_ip": { + "ipv4": { + "active": false + } + }, + "dns": { + "nameservers": [ + "2001:4860:4860::8844", + "2001:4860:4860::8888", + "8.8.8.8" + ] + }, + "tags": null +} +``` + +As an example where you would previously use the attribute +`node['digital_ocean']['networks']['v4'][0]['ipaddress']` you would now +use +`node['digital_ocean']['interfaces']['public'][0]['ipv4']['ip_address']`. diff --git a/content/reference/chef_deprecations_client/deprecations_ohai_filesystem.md b/content/reference/chef_deprecations_client/deprecations_ohai_filesystem.md new file mode 100644 index 0000000..50d9aed --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_ohai_filesystem.md @@ -0,0 +1,30 @@ ++++ +title = "Deprecation: Filesystem plugin replaced by the Filesystem V2 plugin. (OHAI-9)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_ohai_filesystem.html" ++++ + +In Ohai/Chef Infra Client 13 we replaced the existing Filesystem plugin with +the Filesystem2 plugin. This was done by having the Filesystem2 plugin +populate both `node['filesystem2']` and `node['filesystem']`. The +Filesystem2 plugin includes a different data format that resolves many +of the longstanding bugs in the Filesystem plugin. + +## Remediation + +If you have a cookbook that relies on data from `node['filesystem']` you +will need to update the code to use data in the new format when +migrating to Chef Infra Client 13 or later. On a Chef Infra Client 12 or earlier +node you can view the new format by running ohai +filesystem2 or on a Chef Infra Client 13+ node you can run +`ohai filesystem`. + +The output of the filesystem plugin is too large to show the difference +here, but as an example code that may reference +`node['/dev/xvda1']['kb_size']` would need to be updated to reference +`node['by_device']['/dev/xvda1']['kb_size']` as filesystem data is now +displayed by both devices and mounts. diff --git a/content/reference/chef_deprecations_client/deprecations_ohai_filesystem_v2.md b/content/reference/chef_deprecations_client/deprecations_ohai_filesystem_v2.md new file mode 100644 index 0000000..3bf285e --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_ohai_filesystem_v2.md @@ -0,0 +1,24 @@ ++++ +title = "Deprecation: Filesystem2 attribute removal (OHAI-12)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_ohai_filesystem_v2.html" ++++ + +In Ohai/Chef Infra Client 13 we replaced the existing Filesystem plugin with +the Filesystem V2 plugin. That was done by having Ohai populate both +`node['filesystem']` and `node['filesystem_v2']` with the data +previously found at `node['filesystem2']`. In Chef Infra Client 14 we will no +longer populate `node['filesystem2']`. + +## Remediation + +If you have a cookbook that relies on data from `node['filesystem2']` +you will need to update the code to instead use `node['filesystem']`. +Keep in mind that if you're attempting to support releases earlier than +Chef Infra Client 13 the data structure of node\['filesystem'\] will be +different. Foodcritic's FC094 rule will detect any usage of the +`node['filesystem_v2']` attributes. diff --git a/content/reference/chef_deprecations_client/deprecations_ohai_ipscopes.md b/content/reference/chef_deprecations_client/deprecations_ohai_ipscopes.md new file mode 100644 index 0000000..d6808db --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_ohai_ipscopes.md @@ -0,0 +1,16 @@ ++++ +title = "Deprecation: Removal of IpScopes Plugin (OHAI-13)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_ohai_ipscopes.html" ++++ + +Chef/Ohai 14 (April 2018) will remove the IpScopes plugin. The data +returned by this plugin is almost identical to information already +returned by individual network plugins, and this plugin required the +inclusion of an additional gem into the Chef installation. We believe +that few users were installing the gem, and users would be better served +by the data returned from network plugins. diff --git a/content/reference/chef_deprecations_client/deprecations_ohai_legacy_config.md b/content/reference/chef_deprecations_client/deprecations_ohai_legacy_config.md new file mode 100644 index 0000000..08a3c6a --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_ohai_legacy_config.md @@ -0,0 +1,26 @@ ++++ +title = "Deprecation: Ohai::Config removal (OHAI-1)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_ohai_legacy_config.html" ++++ + +Ohai 8.8.0 (Chef Infra Client 12.6.0) introduced a new Ohai configuration +system as defined in +[RFC-053](https://github.com/chef/chef-rfc/blob/main/rfc053-ohai-config.md). +This system replaced the existing usage of `Ohai::Config` config system, +which will be removed in Chef Infra Client 13. + +## Remediation + +Previous Ohai configuration values in the `client.rb` file need to be +updated for the new configuration system format. For example, to +configure the `plugin_path` value previously you would set +`Ohai::Config[:plugin_path] = "/etc/chef/ohai/plugins.local"`, where as +you would now use `ohai.plugin_path = "/etc/chef/ohai/plugins.local"`. +See the [Ohai Configuration +Documentation](/features/ohai/#ohai-settings-in-clientrb) for additional +usage information. diff --git a/content/reference/chef_deprecations_client/deprecations_ohai_libvirt_plugin.md b/content/reference/chef_deprecations_client/deprecations_ohai_libvirt_plugin.md new file mode 100644 index 0000000..4928790 --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_ohai_libvirt_plugin.md @@ -0,0 +1,19 @@ ++++ +title = "Deprecation: Libvirt plugin attributes changes (OHAI-4)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_ohai_libvirt_plugin.html" ++++ + +The Ohai libvirt plugin no longer places libvirt attributes under +`node['virtualization']` and instead uses the `node['libvirt']` +namespace to match other virtualization plugins. + +## Remediation + +Cookbooks utilizing attributes from the libvirt plugin under +`node['virtualization']` will need to be updated to instead use those +same attributes from `node['libvirt']`. diff --git a/content/reference/chef_deprecations_client/deprecations_ohai_run_command_helpers.md b/content/reference/chef_deprecations_client/deprecations_ohai_run_command_helpers.md new file mode 100644 index 0000000..cdaa6c6 --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_ohai_run_command_helpers.md @@ -0,0 +1,42 @@ ++++ +title = "Deprecation: run_command and popen4 helper method removal (OHAI-3)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_ohai_run_command_helpers.html" ++++ + +Ohai ships a command mixin for use by plugin authors in shelling out to +external commands. This mixin originally included `run_command` and +`popen4` methods, which were deprecated in Ohai 8.11.1 (Chef Infra Client +12.8.1) in favor of the more robust `mixlib-shellout` gem functionality. +In Chef Infra Client 13 these deprecated methods will be removed, breaking any +Ohai plugins authored using the deprecated methods. + +## Remediation + +Plugins should be updated to use mixlib-shellout instead of the +run_command. + +Deprecated run_command based code: + +```ruby +status, stdout, stderr = run_command(command: 'myapp --version') +if status == 0 + version = stdout +end +``` + +Updated code for mixlib shellout: + +```ruby +so = shell_out('myapp --version') +if so.exitstatus == 0 + version = so.stdout +end +``` + +See the [mixlib-shellout repo](https://github.com/chef/mixlib-shellout) +for additional usage information. diff --git a/content/reference/chef_deprecations_client/deprecations_ohai_sigar_plugins.md b/content/reference/chef_deprecations_client/deprecations_ohai_sigar_plugins.md new file mode 100644 index 0000000..a17ea63 --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_ohai_sigar_plugins.md @@ -0,0 +1,20 @@ ++++ +title = "Deprecation: Sigar gem based plugins removal (OHAI-2)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_ohai_sigar_plugins.html" ++++ + +When Ohai was first released it depended on the sigar gem for +discovering system configuration details. As time went on Ohai was +expanded with built-in discovery methods for various platforms. The +sigar gem was still required by Ohai and used primarily for the HP-UX +platform. The SIGAR project is no longer active, and there is no longer +an active port of Ruby to HP-UX. Due to this we've chosen to remove the +sigar dependency and all sigar-based plugins from Ohai 13. There is no +anticipated impact for Chef Foundation Platforms or Secondary Platforms. +See the [Platforms](https://docs.chef.io/platforms/) page for a complete list of +platforms. diff --git a/content/reference/chef_deprecations_client/deprecations_ohai_system_profile.md b/content/reference/chef_deprecations_client/deprecations_ohai_system_profile.md new file mode 100644 index 0000000..369396d --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_ohai_system_profile.md @@ -0,0 +1,20 @@ ++++ +title = "Deprecation: System Profile plugin (OHAI-14)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true ++++ + +The system_profile plugin will be removed from Chef/Ohai 15 in April +2019. This plugin doesn't correctly return data on modern Mac systems. +Additionally the same data is provided by the hardware plugin, which has +a format that's simpler to consume. Removing this plugin will reduce +Ohai return by \~3 seconds and greatly reduce the size of the node +object on the Chef Infra Server. + +## Remediation + +If you relied on data in node\['system_profile'\], you should look at +the format in node\['hardware'\] and migrate to that new data format. diff --git a/content/reference/chef_deprecations_client/deprecations_ohai_v6_plugins.md b/content/reference/chef_deprecations_client/deprecations_ohai_v6_plugins.md new file mode 100644 index 0000000..c945df4 --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_ohai_v6_plugins.md @@ -0,0 +1,23 @@ ++++ +title = "Deprecation: Removal of support for Ohai version 6 plugins (OHAI-10)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_ohai_v6_plugins.html" ++++ + +Ohai 7.0 released with Chef Infra Client 11.12 introduced an improved plugin +DSL model. At the time we introduced deprecations for the existing +plugin DSL, which we referred to as V6 plugins. In Ohai/Chef Infra Client 14 +we will remove the support for Ohai V6 plugins, causing a runtime error +if they're used. + +## Remediation + +If you have custom Ohai V6 plugins installed using cookbook or bootstrap +you will need to update these plugins to the Ohai V7 plugin format. + +See the [Ohai Custom Plugins page](/extension_apis/custom_plugins/) for additional +information on writing V7 plugins. diff --git a/content/reference/chef_deprecations_client/deprecations_ohai_windows_cpu.md b/content/reference/chef_deprecations_client/deprecations_ohai_windows_cpu.md new file mode 100644 index 0000000..46d28ba --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_ohai_windows_cpu.md @@ -0,0 +1,22 @@ ++++ +title = "Deprecation: Windows CPU plugin attribute changes. (OHAI-5)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_ohai_windows_cpu.html" ++++ + +The Windows Ohai plugin has been updated to correctly return CPU +information. Previously the CPU plugin reported a `model_name` value, +which was actually the CPU's description and not the actual model name. +Ohai now reports the proper name value for `model_name` and provides +`description` with the previous description value. This behavior aligns +CPU plugin behavior between \*nix and Windows hosts in Chef. + +## Remediation + +If you rely on the format of a CPU model_name value such as +`node['cpu'['0']['model_name']` you will need to update your cookbook +code to reference `node['cpu']['0']['description']` instead. diff --git a/content/reference/chef_deprecations_client/deprecations_property_name_collision.md b/content/reference/chef_deprecations_client/deprecations_property_name_collision.md new file mode 100644 index 0000000..03137b7 --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_property_name_collision.md @@ -0,0 +1,31 @@ ++++ +title = "Deprecation: Resource Property Name Collision (CHEF-11)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_property_name_collision.html" ++++ + +A resource property, defined with the `property` method, conflicts with +an already-existing property or method. This could indicate an error +that could lead to unintended behavior. + +All Ruby objects have methods that are expected to always be +available. When a resource property is created, Ruby methods for setting +and getting the property value are created for you. If a resource +creates a property which is named the same as an existing method, the +original method will be overwritten. + +For example, every Ruby object has a `hash` method which is expected to +return a number. If a resource creates a property named `hash` and +stores a string instead, it could cause errors in your Chef run. + +A deprecation warning is logged when this occurs. In Chef Infra Client 13, +this will raise an exception and your Chef run will fail. + +## Remediation + +Modify the resource and choose a different name for the property that +doesn't conflict with an already-existing method name. diff --git a/content/reference/chef_deprecations_client/deprecations_resource_cloning.md b/content/reference/chef_deprecations_client/deprecations_resource_cloning.md new file mode 100644 index 0000000..23f9e71 --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_resource_cloning.md @@ -0,0 +1,56 @@ ++++ +title = "Deprecation: Resource Cloning (CHEF-3694)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_resource_cloning.html" ++++ + +Chef allows resources to be created with duplicate names, rather than +treating that as an error. This means that several cookbooks can request +the same package be installed, without needing to carefully create +unique names. This is problematic because having multiple resources with +the same name makes it impossible to safely deliver notifications to the +right resource. + +In Chef Infra Client 13, resources with the same name will be treated as +entirely separate, without any cloning of properties. + +The behavior in Chef Infra Client 12 and earlier, which is now deprecated, is +that we will try to clone the existing resource, and then apply any +properties from the new resource. For example: + +```ruby +file '/etc/my_file' do + owner 'ken' +end + +file '/etc/my_file' do + mode '0755' +end +``` + +will result in the second instance having the following properties: + +```ruby +file '/etc/my_file' do + owner 'ken' + mode '0755' +end +``` + +Resource cloning was deprecated in Chef Infra Client 10.18.0 and will be +removed in Chef Infra Client 13. + +{{< note >}} + +Chef will only emit a deprecation warning in the situation that a cloned +resource is significantly different from the existing one. + +{{< /note >}} + +## Remediation + +Ensure that resources you intend to notify are given unique names. diff --git a/content/reference/chef_deprecations_client/deprecations_resource_name_without_provides.md b/content/reference/chef_deprecations_client/deprecations_resource_name_without_provides.md new file mode 100644 index 0000000..17e5bd8 --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_resource_name_without_provides.md @@ -0,0 +1,93 @@ ++++ +title = "Deprecation: resource_name declaration without provides (CHEF-31)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true ++++ + +In Chef Infra Client 12.5.1 through 15, resources could be addressed from +recipe code using only the name of the resource, provided that no other +`provides` declaration was used in the same file. + +The intent was to fulfill the demands that "users should just be +able to name a resource and it should work" with the demands that, for +more complicated use cases, users should be able to use `provides` +lines to arbitrarily wire up resources to the Chef recipe language. + +This failed because it attempted to overly simplify user intent while +generating two separate constructs with confusing interactions. Most +users were entirely unaware that the `resource_name` statement implicitly +issued a `provides` statement which wired up a specially designated +`canonical` DSL entry, which was then removed behind the scenes if any +subsequent `provides` declaration followed. When this worked it was +easy to use, but when it failed the edge conditions were confusing and +required too much background knowledge to debug. + +An attempt was made to preserve more thorough backwards compatibility between +Chef Infra Client 16.0 and earlier versions by retaining some automatic +wiring of the `provides` statement with the `resource_name`. This failed +due to complicated interactions between cookbooks that used multiple +resources with the same name wired up using `provides` lines to different +resource implementations on different operating systems. This was a silent +error and dependent upon the parse order of the resources in the cookbook +for it to become apparent, and hindered detection and remediation. + +The solution eventually adopted in Chef Infra Client 16.2 was to require +all resources to declare a `provides` lines, and to make the `resource_name` +setting only affect the display output. As a result, any cookbook which +declares a resource with only a `resource_name` needs to add a `provides` +line for Chef Infra Client 16. While this is more disruptive to users it +is simple, it can be autocorrected using static analysis, and it results in +a much simpler end state where the `resource_name` is just a display name +and the `provides` statement is solely responsible for how the resource +is addressed in recipe mode. + +There is also the old standard that existed before resources could +declare what they provided. In that standard, the resource was addressed +by prepending the `cookbook_name` to the filename that the resource was declared in. +That has remained unchanged and isn't affected by this change. + +## Remediation + +A resource with only a `resource_name` property: + +```ruby +resource_name :my_custom_resource + +property :my_property, String + +action :run do + [ ...implementation of the action... ] +end +``` + +Should have a `provides` statement added: + +```ruby +resource_name :my_custom_resource +provides :my_custom_resource + +property :my_property, String + +action :run do + [ ...implementation of the action... ] +end +``` + +It also works to have the `provides` line come before the `resource_name`, +the order doesn't matter. + +For cookbooks which don't have to support Chef Infra Client 15 or before, the +`resource_name` can also be entirely omitted: + +```ruby +provides :my_custom_resource + +property :my_property, String + +action :run do + [ ...implementation of the action... ] +end +``` diff --git a/content/reference/chef_deprecations_client/deprecations_run_command.md b/content/reference/chef_deprecations_client/deprecations_run_command.md new file mode 100644 index 0000000..d9d9fe2 --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_run_command.md @@ -0,0 +1,32 @@ ++++ +title = "Deprecation: Deprecation of run_command (CHEF-14)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_run_command.html" ++++ + +The old run_command API has been replaced by shell_out (a wrapper +around Mixlib::ShellOut). + +This deprecation warning was added in Chef Infra Client 12.18.31, and +run_command will be removed permanently in Chef Infra Client 13. + +## Example + +Previously to run a command from Chef Infra Client code you might have +written: + +```ruby +run_command(command: '/sbin/ifconfig eth0') +``` + +## Remediation + +You now need to use shell_out! instead: + +```ruby +shell_out!('/sbin/ifconfig eth0') +``` diff --git a/content/reference/chef_deprecations_client/deprecations_shell_out.md b/content/reference/chef_deprecations_client/deprecations_shell_out.md new file mode 100644 index 0000000..87ec812 --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_shell_out.md @@ -0,0 +1,54 @@ ++++ +title = "Deprecation: Deprecation of legacy shell_out APIs (CHEF-26)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_shell_out.html" ++++ + +The functionality of multiple legacy shell_out APIs has been collapsed into the +shell_out API itself, and the legacy +methods have been deprecated. + +The shell_out_compact API has been +migrated into shell_out, so those +methods can be renamed. The functionality of shell_out_compact_timeout and shell_out_with_timeout have been migrated +into shell_out for internal resources, +and will be migrated into custom resources and LWRPs in Chef-15, in the +meantime consumers should use shell_out with a timeout: new_resource.timeout option. The +functionality of shell_out_with_systems_locale has been +replaced by the default_env: false flag. + +The "banged" versions of those APIs (for example shell_out_compact!) changes identically to +use shell_out!. + +## Example + +The following code examples need to be changed to the corresponding code +below: + +```ruby +shell_out_compact('rpm', '-qa') +shell_out_compact_timeout('rpm', '-qa') +shell_out_with_timeout('rpm', '-qa') +shell_out_with_systems_locale('rpm', '-qa') +``` + +## Remediation + +You now need to use shell_out! instead: + +```ruby +shell_out('rpm', '-qa') +shell_out('rpm', '-qa', timeout: new_resource.timeout) +shell_out('rpm', '-qa', timeout: new_resource.timeout) +shell_out('rpm', '-qa', default_env: false) +``` diff --git a/content/reference/chef_deprecations_client/deprecations_supports_property.md b/content/reference/chef_deprecations_client/deprecations_supports_property.md new file mode 100644 index 0000000..a13d739 --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_supports_property.md @@ -0,0 +1,40 @@ ++++ +title = "Deprecation: Supports metaproperty (CHEF-8)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_supports_property.html" ++++ + +The `user` resource previously allowed a cookbook author to set policy +for the resource in two ways. The `supports` metaproperty, which is now +deprecated, enabled the `manage_home` and `non_unique` properties to be +set. + +The `supports` metaproperty was deprecated in Chef Infra Client 12.14 and will +be removed in Chef Infra Client 13. + +## Example + +```ruby +user 'betty' do + supports({ + manage_home: true, + non_unique: true, + }) +end +``` + +## Remediation + +Make the `manage_home` and `non_unique` settings properties rather than +parts of the `supports` hash. + +```ruby +user 'betty' do + manage_home true + non_unique true +end +``` diff --git a/content/reference/chef_deprecations_client/deprecations_unified_mode.md b/content/reference/chef_deprecations_client/deprecations_unified_mode.md new file mode 100644 index 0000000..591b7ee --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_unified_mode.md @@ -0,0 +1,19 @@ ++++ +title = "Deprecation: Enabling Unified Mode (CHEF-33)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_unified_mode.html" ++++ + +{{< readfile file="content/reusable/md/unified_mode_overview.md" >}} + +{{< readfile file="content/reusable/md/unified_mode_client_releases.md" >}} + +{{< readfile file="content/reusable/md/unified_mode_enable.md" >}} + +{{< readfile file="content/reusable/md/unified_mode_actions_later_resources.md" >}} + +{{< readfile file="content/reusable/md/unified_mode_troubleshooting.md" >}} diff --git a/content/reference/chef_deprecations_client/deprecations_verify_file.md b/content/reference/chef_deprecations_client/deprecations_verify_file.md new file mode 100644 index 0000000..672b89e --- /dev/null +++ b/content/reference/chef_deprecations_client/deprecations_verify_file.md @@ -0,0 +1,35 @@ ++++ +title = "Deprecation: Verify File Expansion (CHEF-7)" +draft = false + +gh_repo = "chef-web-docs" +robots = "noindex" +sitemapExclude = true +aliases = "/deprecations_verify_file.html" ++++ + +The `verify` metaproperty allows the user to specify a `{path}` variable +that's expanded to the path of the file to be verified. Previously, it +was possible to use `{file}` as the variable, but that's now +deprecated. + +The `{file}` expansion was deprecated in Chef Infra Client 12.5, and will be +removed in Chef Infra Client 13. + +## Example + +```ruby +file '/etc/nginx.conf' do + verify 'nginx -t -c %{file}' +end +``` + +## Remediation + +Replace `%{file}` with `%{path}`: + +```ruby +file '/etc/nginx.conf' do + verify 'nginx -t -c %{path}' +end +``` diff --git a/content/reference/ctl_chef_client.md b/content/reference/ctl_chef_client.md new file mode 100644 index 0000000..0ce3005 --- /dev/null +++ b/content/reference/ctl_chef_client.md @@ -0,0 +1,892 @@ ++++ +title = "Chef Infra Client (executable)" +draft = false + +[menu] + [menu.reference] + title = "chef-client (executable)" + identifier = "reference/ctl_chef_client.md chef-client Commands" + parent = "reference" + weight = 10 ++++ + +{{< readfile file="content/reusable/md/chef_client_summary.md" >}} + +{{< note >}} + +The Chef Infra Client executable can be run as a daemon. + +{{< /note >}} + +The Chef Infra Client executable is run as a command-line tool. + +{{< note >}} + +{{< readfile file="content/reusable/md/config_rb_client_summary.md" >}} + +{{< /note >}} + +## Options + +This command has the following syntax: + +```bash +chef-client OPTION VALUE OPTION VALUE ... +``` + +This command has the following options: + +`-A`, `--fatal-windows-admin-check` + +: Cause a Chef Infra Client run to fail when the Chef Infra Client doesn't have administrator privileges in Windows. + +`-c CONFIG`, `--config CONFIG` + +: The configuration file to use. + +`--config-option OPTION` + +: Overrides a single configuration option. Can be used to override multiple configuration options by adding another `--config-option OPTION`. + +`--chef-zero-host HOST` + +: The host on which chef-zero is started. + +`--chef-zero-port PORT` + +: The port on which chef-zero listens. If a port isn't specified---individually, as range of ports, or from the `chef_zero.port` setting in the client.rb file---the Chef Infra Client will scan for ports between 8889--9999 and will pick the first port that's available. + +`-d SECONDS`, `--daemonize SECONDS` + +: Run the executable as a daemon. Use `SECONDS` to specify the number of seconds to wait before the first daemonized Chef Infra Client run. `SECONDS` is set to `0` by default. Left unset, the daemon uses the default `--interval` an `--splay` values. + + This option is only available on machines that run in UNIX or Linux environments. For machines that are running Windows that require similar functionality, use the `chef-client::service` recipe in the `chef-client` cookbook: . This will install a Chef Infra Client service under Windows using the Windows Service Wrapper. + +`--delete-entire-chef-repo` + +: This option deletes an entire repository. This option may only be used when running the Chef Infra Client in local mode, (`--local-mode`). This option requires `--recipe-url` to be specified. + +`--disable-config` + +: Use to run the Chef Infra Client using default settings. This will prevent the normally-associated configuration file from being used. This setting should only be used for testing purposes and should never be used in a production setting. + +`-E ENVIRONMENT_NAME`, `--environment ENVIRONMENT_NAME` + +: The name of the environment. + +`-f`, `--[no-]fork` + +: Contain Chef Infra Client runs in a secondary process with dedicated RAM. When a Chef Infra Client run is complete, the RAM is returned to the primary process. This option helps ensure that a Chef Infra Client uses a steady amount of RAM over time because the primary process doesn't run recipes. This option also helps prevent memory leaks such as those that can be introduced by the code contained within a poorly designed cookbook. Use `--no-fork` to disable running Chef Infra Client in fork node. Default value: `--fork`. + +`-F FORMAT`, `--format FORMAT` + +: {{< readfile file="content/reusable/md/workstation/ctl_chef_client_options_format.md" >}} + +`--force-formatter` + +: Show formatter output instead of logger output. + +`--force-logger` + +: Show logger output instead of formatter output. + +`-g GROUP`, `--group GROUP` + +: The name of the group that owns a process. This is required when starting any executable as a daemon. + +`-h`, `--help` + +: Show help for the command. + +`-i SECONDS`, `--interval SECONDS` + +: The frequency (in seconds) at which Chef Infra Client runs. When running Chef Infra Client at intervals, apply `--splay` and `--interval` values before a Chef Infra Client run. Default value: `1800`. + +`-j PATH`, `--json-attributes PATH` + +: The path to a file that contains JSON data. Used to setup the first client run. The attributes will persist on Chef Infra Server for all future runs with option `-j`. + + **Run-lists** + + {{< readfile file="content/reusable/md/node_ctl_run_list.md" >}} + + **Environments** + + Use this option to set the `chef_environment` value for a node. + + {{< note >}} + + Any environment specified for `chef_environment` by a JSON file will take precedence over an environment specified by the `--environment` option when both options are part of the same command. + + {{< /note >}} + + For example, run the following: + + ```bash + chef-client -j /path/to/file.json + ``` + + where `/path/to/file.json` is similar to: + + ```json + { + "chef_environment": "pre-production" + } + ``` + + This will set the environment for the node to `pre-production`. + + **All attributes are normal attributes** + + {{< readfile file="content/reusable/md/node_ctl_attribute.md" >}} + + {{< note >}} + + This has set the `normal` attribute + `node['override_attributes']['apptastic']`. + + {{< /note >}} + + **Specify a policy** + + Use this option to use Policyfiles by specifying a JSON file that + contains the following settings: + + + + + + + + + + + + + + + + + + + + + + +
SettingDescription
policy_groupThe name of a policy group that exists on Chef Infra Server.
policy_nameThe name of a policy, as identified by the name setting in a Policyfile.rb file.
+ + For example: + + ```json + { + "policy_name": "appserver", + "policy_group": "staging" + } + ``` + +`-k KEY_FILE`, `--client_key KEY_FILE` + +: The location of the file that contains the client key. Default + value: `/etc/chef/client.pem`. + +`-K KEY_FILE`, `--validation_key KEY_FILE` + +: The location of the file that contains the key used when a Chef + Infra Client is registered with a Chef Infra Server. A validation + key is signed using the `validation_client_name` for authentication. + Default value: `/etc/chef/validation.pem`. + +`-l LEVEL`, `--log_level LEVEL` + +: The level of logging to be stored in a log file. Possible levels: + `auto` (default), `debug`, `error`, `fatal`, `info`, `trace`, or `warn`. + Default value: `warn` (when a terminal is available) or `info` (when + a terminal isn't available). + +`-L LOGLOCATION`, `--logfile LOGLOCATION` + +: The location of the log file. This is recommended when starting any + executable as a daemon. Default value: `STDOUT`. + +`--lockfile LOCATION` + +: Use to specify the location of the lock file, which prevents + multiple Chef Infra Client processes from converging at the same + time. + +`--minimal-ohai` + +: Run the Ohai plugins for name detection and resource/provider + selection and no other Ohai plugins. Set to `true` during + integration testing to speed up test cycles. + +`--[no-]color` + +: View colored output. Default setting: `--color`. + +`--[no-]fips` + +: Allows OpenSSL to enforce FIPS-validated security during a Chef + Infra Client run. + +`--[no-]skip-cookbook-sync` + +: Not recommended. Use cached cookbooks without overwriting local differences from the server. Useful for patching a set of cookbooks on a machine when iterating during development. This option can cause unanticipated behavior. + +`--[no-]listen` + +: Run chef-zero in socketless mode. **This is the default behavior on + Chef Infra Client 13.1 and above.** + +`-n NAME`, `--named-run-list NAME` + +: The run-list associated with a Policyfile. + +`-N NODE_NAME`, `--node-name NODE_NAME` + +: The unique identifier of the node. + +`-o RUN_LIST_ITEM`, `--override-runlist RUN_LIST_ITEM` + +: Replace the current run-list with the specified items. This option + won't clear the list of cookbooks (and related files) that's + cached on the node. This option won't persist node data at the + end of the client run. + +`--once` + +: Make only one Chef Infra Client run and cancel `interval` and + `splay` options. + +`-P PID_FILE`, `--pid PID_FILE` + +: The location in which a process identification number (pid) is + saved. An executable, when started as a daemon, writes the pid to + the specified file. Default value: `/tmp/name-of-executable.pid`. + +`--profile-ruby` + +: Use the `--profile-ruby` option to dump a (large) profiling graph + into `/var/chef/cache/graph_profile.out`. Use the graph output to + help identify, and then resolve performance bottlenecks in a Chef + Infra Client run. This option: + + - Generates a large amount of data about a Chef Infra Client run. + - Has a dependency on the `ruby-prof` gem, which is packaged as + part of Chef and Chef Workstation. + - Increases the amount of time required to complete a Chef Infra + Client run. + - Should not be used in a production environment. + +`-r RUN_LIST_ITEM`, `--runlist RUN_LIST_ITEM` + +: Permanently replace the current run-list with the specified run-list + items. + +`-R`, `--enable-reporting` + +: Enable Reporting, which performs data collection during a Chef Infra + Client run. + +`RECIPE_FILE` + +: The path to a recipe. For example, if a recipe file is in the + current directory, use `recipe_file.rb`. This is typically used with + the `--local-mode` option. + +`--recipe-url=RECIPE_URL` + +: The location of a recipe when it exists at a URL. Use this option + only when running Chef Infra Client with the `--local-mode` option. + +`--run-lock-timeout SECONDS` + +: The amount of time (in seconds) to wait for a Chef Infra Client lock + file to be deleted. Default value: not set (indefinite). Set to `0` + to cause a second Chef Infra Client to exit immediately. + +`-s SECONDS`, `--splay SECONDS` + +: A random number between zero and `splay` that's added to + `interval`. Use splay to help balance the load on the Chef Infra + Server by ensuring that many Chef Infra Client runs aren't + occurring at the same interval. When running Chef Infra Client at + intervals, apply `--splay` and `--interval` values before a Chef + Infra Client run. + + Changed in Chef Infra Client 12.0 to be applied before the Chef Infra Client + run. + +`-S CHEF_SERVER_URL`, `--server CHEF_SERVER_URL` + +: The URL for Chef Infra Server. + +`-u USER`, `--user USER` + +: The user that owns a process. This is required when starting any + executable as a daemon. + +`-v`, `--version` + +: The Chef Infra Client version. + +`-W`, `--why-run` + +: Run the executable in why-run mode, which is a type of Chef Infra + Client run that does everything except modify the system. Use + why-run mode to understand why the Chef Infra Client makes the + decisions that it makes and to learn more about the current and + proposed state of the system. + +`-z`, `--local-mode` + +: Run the Chef Infra Client in local mode. This allows all commands + that work against Chef Infra Server to also work against the + local chef-repo. + +### Chef Infra Client Lock File + +The Chef Infra Client uses a lock file to ensure that only one Chef +Infra Client run is in progress at any time. A lock file is created at +the start of a Chef Infra Client run and is deleted at the end of a Chef +Infra Client run. A new Chef Infra Client run looks for the presence of +a lock file and, if present, will wait for that lock file to be deleted. +The location of the lock file can vary by platform. + +- Use the `lockfile` setting in the client.rb file to specify + non-default locations for the lock file. (The default location is + typically platform-dependent and is recommended.) +- Use the `run_lock_timeout` setting in the client.rb file to specify + the amount of time (in seconds) to wait for the lock file associated + with an in-progress Chef Infra Client run to be deleted. + +## Run in Local Mode + +Local mode is a way to run the Chef Infra Client against the chef-repo +on a local machine as if it were running against Chef Infra Server. +Local mode relies on chef-zero, which acts as a lightweight +instance of Chef Infra Server. chef-zero reads and writes to the +`chef_repo_path`, which allows all commands that normally work against +Chef Infra Server to be used against the local chef-repo. + +Local mode doesn't require a configuration file, instead it will look +for a directory named `/cookbooks` and will set `chef_repo_path` to be +just above that. (Local mode will honor the settings in a configuration +file, if desired.) If the client.rb file isn't found and no +configuration file is specified, local mode will search for a config.rb +file. + +Local mode will store temporary and cache files under the +`/.cache` directory by default. This allows a normal +user to run the Chef Infra Client in local mode without requiring root +access. + +### About why-run Mode + +why-run mode is a way to see what Chef Infra Client would have +configured, had an actual Chef Infra Client run occurred. This approach +is similar to the concept of "no-operation" (or "no-op"): decide what +should be done, but then don't actually do anything until it's done +right. This approach to configuration management can help identify where +complexity exists in the system, where inter-dependencies may be +located, and to verify that everything will be configured in the desired +manner. + +When why-run mode is enabled, a Chef Infra Client run will occur that +does everything up to the point at which configuration would normally +occur. This includes getting the configuration data, authenticating to +Chef Infra Server, rebuilding the node object, expanding the +run-list, getting the necessary cookbook files, resetting node +attributes, identifying the resources, and building the resource +collection, but doesn't include mapping each resource to a provider or +configuring any part of the system. + +{{< note >}} + +why-run mode isn't a replacement for running cookbooks in a test +environment that mirrors the production environment. Chef uses why-run +mode to learn more about what's going on, but also Kitchen on developer +systems, along with an internal OpenStack cloud and external cloud +providers for more thorough testing. + +{{< /note >}} + +When Chef Infra Client is run in why-run mode, certain assumptions are +made: + +- If the **service** resource can't find the appropriate command to + verify the status of a service, why-run mode will assume that the + command would have been installed by a previous resource and that + the service would not be running. +- For `not_if` and `only_if` properties, why-run mode will assume + these are commands or blocks that are safe to run. These conditions + aren't designed to be used to change the state of the system, but + rather to help facilitate idempotency for the resource itself. That + said, it may be possible that these attributes are being used in a + way that modifies the system state +- The closer the current state of the system is to the desired state, + the more useful why-run mode will be. For example, if a full + run-list is run against a fresh system, that run-list may not be + completely correct on the first try, but also that run-list will + produce more output than a smaller run-list + +For example, the **service** resource can be used to start a service. If +the action is `:start`, then the service will start if it's not running +and do nothing if it's running. If a service is installed from a +package, then Chef Infra Client can't check to see if the service is +running until after the package is installed. In that case, why-run mode +will indicate what Chef Infra Client would do about the state of the +service after installing a package. This is important because service +actions often trigger notifications to other resources, so it's +important to know that these notifications are triggered correctly. + +### About chef-zero + +chef-zero is a lightweight Chef Infra Server that runs in-memory on +the local machine. This allows the Chef Infra Client to be run against +the chef-repo as if it were running against Chef Infra Server. +chef-zero was [originally a standalone +tool](https://github.com/chef/chef-zero); it's enabled from within the +Chef Infra Client by using the `--local-mode` option. chef-zero is +useful for testing and validating the behavior of the Chef Infra +Client, cookbooks, recipes, and run-lists before uploading that data to +the actual Chef Infra Server. + +{{< note >}} + +chef-zero doesn't save data between restarts. Because it's intended to +be used locally, chef-zero doesn't perform input validation, +authentication, or authorization, as these security measures aren't +necessary for local testing. For these reasons, we strongly recommend +against using chef-zero as a persistent Chef Infra Server. + +{{< /note >}} + +Changed in Chef Infra Client 12.8, now chef-zero supports all Chef Infra Server API +version 12 endpoints, except `/universe`. + +### Use Encrypted Data Bags + +{{< readfile file="content/reusable/md/data_bag.md" >}} + +**Create an encrypted data bag for use with Chef Infra Client local +mode** + +{{< readfile file="content/reusable/md/workstation/knife_data_bag_from_file_create_encrypted_local_mode.md" >}} + +## Run in FIPS Mode + +{{< readfile file="content/reusable/md/fips_intro_client.md" >}} + +**Bootstrap a node using FIPS** + +{{< readfile file="content/reusable/md/workstation/knife_bootstrap_node_fips.md" >}} + +## Run as a Service + +Chef Infra Client can be run as a daemon. Use the **Chef Infra +Client** cookbook to configure the Chef Infra Client as a daemon. Add +the `default` recipe to a node's run-list, and then use attributes in +that cookbook to configure the behavior of the Chef Infra Client. For +more information about these configuration options, see the [Chef Infra +Client cookbook repository on +github](https://github.com/chef-cookbooks/chef-client/). + +When the Chef Infra Client is run as a daemon, the following signals may +be used: + +`HUP` + +: Use to reconfigure the Chef Infra Client. + +`INT` + +: Use to terminate immediately without waiting for the current Chef + Infra Client run to finish. + +`QUIT` + +: Use to dump a stack trace, and continue to run. + +`TERM` + +: Use to terminate but wait for the current Chef Infra Client run to + finish, and then exit. + +`USR1` + +: Use to wake up sleeping Chef Infra Client and trigger node + convergence. + +On Windows, both the `HUP` and `QUIT` signals aren't +supported. + +## Run with Elevated Privileges + +{{< readfile file="content/reusable/md/workstation/ctl_chef_client_elevated_privileges.md" >}} + +### Linux + +On Linux, the following error sometimes occurs when the permissions used +to run the Chef Infra Client are incorrect: + +```bash +chef-client +[Tue, 29 Nov 2015 19:46:17 -0800] INFO: *** Chef 12.X.X *** +[Tue, 29 Nov 2015 19:46:18 -0800] WARN: Failed to read the private key /etc/chef/client.pem: # +``` + +This can be resolved by running the command as root. There are a few +ways this can be done: + +- Log in as root and then run the Chef Infra Client + +- Use `su` to become the root user, and then run the Chef Infra + Client. For example: + + ```bash + su + ``` + + and then: + + ```bash + chef-client + ``` + +- Use the sudo utility + + ```bash + sudo chef-client + ``` + +- Give a user access to read `/etc/chef` and also the files accessed + by the Chef Infra Client. This requires super user privileges and, + as such, isn't a recommended approach + +### Windows + +{{< readfile file="content/reusable/md/workstation/ctl_chef_client_elevated_privileges_windows.md" >}} + +## Run as Non-root User + +In large, distributed organizations the ability to modify the +configuration of systems is sometimes segmented across teams, often with +varying levels of access to those systems. For example, core application +services may be deployed to systems by a central server provisioning +team, and then developers on different teams build tooling to support +specific applications. In this situation, a developer only requires +limited access to machines and only needs to perform the operations that +are necessary to deploy tooling for a specific application. + +The default configuration of the Chef Infra Client assumes that it's +run as the root user. This affords the Chef Infra Client the greatest +flexibility when managing the state of any object. However, the Chef +Infra Client may be run as a non-root user---that's, "run as a user with +limited system privileges"---which can be useful when the objects on the +system are available to other user accounts. + +When the Chef Infra Client is run as a non-root user the Chef Infra +Client can perform any action allowed to that user, as long as that +action doesn't also require elevated privileges (such as sudo or +pbrun). Attempts to manage any object that requires elevated privileges +will result in an error. For example, when the Chef Infra Client is run +as a non-root user that's unable to create or modify users, the +**user** resource won't work. + +### Set the Cache Path + +To run a Chef Infra Client in non-root mode, add the `file_cache_path` +setting to the client.rb file for the node that will run as the non-root +user. Set the value of `file_cache_path` to be the home directory for +the user that's running the Chef Infra Client. For example: + +```ruby +file_cache_path '~/.chef/cache' +``` + +or: + +```ruby +file_cache_path File.join(File.expand_path('~'), '.chef', 'cache') +``` + +{{< note >}} + +When running the Chef Infra Client using the `--local-mode` option, +`~/.chef/local-mode-cache` is the default value for `file_cache_path`. + +{{< /note >}} + +### Elevate Commands + +Another example of running the Chef Infra Client as a non-root user +involves using resources to pass sudo commands as as an attribute on the +resource. For example, the **service** resource uses a series of +`_command` attributes (like `start_command` or `stop_command`), +the **package**-based resources use the `options` attribute, and the +**script**-based resources use the `code` attribute. + +A command can be elevated similar to the following: + +```ruby +service 'apache2' do + start_command 'sudo /etc/init.d/apache2 start' + action :start +end +``` + +This approach can work well on a case-by-case basis. The challenge +with this approach is often around managing the size of the +`/etc/sudoers` file. + +## Run on IBM AIX + +The Chef Infra Client may now be used to configure nodes that are +running on the AIX platform, versions 7.1 (TL5 SP2 or higher, +recommended) and 7.2. The **service** resource supports starting, +stopping, and restarting services that are managed by System Resource +Controller (SRC), as well as managing all service states with BSD-based +init systems. + +**System Requirements** + +The Chef Infra Client has the [same system requirements](/install/system_requirements/#chef-infra-client-requirements) on the AIX platform as any other platform, with the following notes: + +- Expand the file system on the AIX platform using `chfs` or by + passing the `-X` flag to `installp` to automatically expand the + logical partition (LPAR) +- The EN_US (UTF-8) character set should be installed on the logical + partition before installing the Chef Infra Client + +**Install the Chef Infra Client on the AIX platform** + +The Chef Infra Client is distributed as a Backup File Format (BFF) +binary and is installed on the AIX platform using the following command +run as a root user: + +```text +# installp -aYgd chef-12.0.0-1.powerpc.bff all +``` + +**Increase system process limits** + +The out-of-the-box system process limits for maximum process memory size +(RSS) and number of open files are typically too low to run the Chef +Infra Client on a logical partition (LPAR). When the system process +limits are too low, the Chef Infra Client won't be able to create +threads. To increase the system process limits: + +1. Validate that the system process limits haven't already been increased. + +2. If they haven't been increased, run the following commands as a root user: + + ```bash + chsec -f /etc/security/limits -s default -a "rss=-1" + ``` + + and then: + + ```bash + chsec -f /etc/security/limits -s default -a "data=-1" + ``` + + and then: + + ```bash + chsec -f /etc/security/limits -s default -a "nofiles=50000" + ``` + + {{< note >}} + + The previous commands may be run against the root user, instead of + default. For example: + + ```bash + chsec -f /etc/security/limits -s root_user -a "rss=-1" + ``` + + {{< /note >}} + +3. Reboot the logical partition (LPAR) to apply the updated system process limits. + +When the system process limits are too low, an error is returned similar +to: + +```bash +Error Syncing Cookbooks: +================================================================== + +Unexpected Error: +----------------- +ThreadError: can't create Thread: Resource temporarily unavailable +``` + +**Install the UTF-8 character set** + +The Chef Infra Client uses the EN_US (UTF-8) character set. By default, +the AIX base operating system doesn't include the EN_US (UTF-8) +character set and it must be installed before installing the Chef +Infra Client. The EN_US (UTF-8) character set may be installed from the +first disc in the AIX media or may be copied from +`/installp/ppc/*EN_US*` to a location on the logical partition (LPAR). +This topic assumes this location to be `/tmp/rte`. + +Use `smit` to install the EN_US (UTF-8) character set. This ensures +that any workload partitions (WPARs) also have UTF-8 applied. + +Remember to point `INPUT device/directory` to `/tmp/rte` when not +installing from CD. + +1. From a root shell type: + + ```text + # smit lang + ``` + + A screen similar to the following is returned: + + ```bash + Manage Language Environment + + Move cursor to desired item and press Enter. + + Change/Show Primary Language Environment + Add Additional Language Environments + Remove Language Environments + Change/Show Language Hierarchy + Set User Languages + Change/Show Applications for a Language + Convert System Messages and Flat Files + + F1=Help F2=Refresh F3=Cancel F8=Image + F9=Shell F10=Exit Enter=Do + ``` + +2. Select `Add Additional Language Environments` and press `Enter`. A screen similar to the following is returned: + + ```bash + Add Additional Language Environments + + Type or select values in entry fields. Press Enter AFTER making + all desired changes. + + [Entry Fields] + + CULTURAL convention to install + LANGUAGE translation to + install + INPUT device/directory for software [/dev/cd0] + EXTEND file + systems if space needed? yes + WPAR Management + + Perform Operation in Global Environment yes + Perform + Operation on Detached WPARs no + Detached WPAR Names + [_all_wpars] + Remount Installation Device in WPARs + yes + Alternate WPAR Installation Device [] + + F1=Help F2=Refresh F3=Cancel F4=List F5=Reset F6=Command F7=Edit + F8=Image F9=Shell F10=Exit Enter=Do + ``` + +3. Cursor over the first two entries---`CULTURAL convention to install` and `LANGUAGE translation to install`---and use `F4` to navigate through the list until `UTF-8 English (United States) [EN_US]` is selected. (EN_US is in capital letters!) + +4. Press `Enter` to apply and install the language set. + +**Providers** + +The **service** resource has the following providers to support the AIX +platform: + + +++++ + + + + + + + + + + + + + + + + + + + +
Long nameShort nameNotes
Chef::Provider::Service::AixserviceThe provider that's used with the AIX platforms. Use the service short name to start, stop, and restart services with System Resource Controller (SRC).
Chef::Provider::Service::AixInitserviceThe provider that's used to manage BSD-based init services on AIX.
+ +**Enable a service on AIX using the mkitab command** + +The **service** resource doesn't support using the `:enable` and +`:disable` actions with resources that are managed using System Resource +Controller (SRC). This is because System Resource Controller (SRC) does +not have a standard mechanism for enabling and disabling services on +system boot. + +One approach for enabling or disabling services that are managed by +System Resource Controller (SRC) is to use the **execute** resource to +invoke `mkitab`, and then use that command to enable or disable the +service. + +The following example shows how to install a service: + +```ruby +execute "install #{node['chef_client']['svc_name']} in SRC" do + command "mkssys -s #{node['chef_client']['svc_name']} + -p #{node['chef_client']['bin']} + -u root + -S + -n 15 + -f 9 + -o #{node['chef_client']['log_dir']}/client.log + -e #{node['chef_client']['log_dir']}/client.log -a ' + -i #{node['chef_client']['interval']} + -s #{node['chef_client']['splay']}'" + not_if "lssrc -s #{node['chef_client']['svc_name']}" + action :run +end +``` + +and then enable it using the `mkitab` command: + +```ruby +execute "enable #{node['chef_client']['svc_name']}" do + command "mkitab '#{node['chef_client']['svc_name']}:2:once:/usr/bin/startsrc + -s #{node['chef_client']['svc_name']} > /dev/console 2>&1'" + not_if "lsitab #{node['chef_client']['svc_name']}" +end +``` + +## Configuring a Proxy Server + +See the [proxies](/install/proxies/) documentation for information on how to +configure Chef Infra Client to use a proxy server. + +## Examples + +**Run the Chef Infra Client** + +```bash +sudo chef-client +``` + +**Start a run when the Chef Infra Client is running as a daemon** + +A Chef Infra Client that's running as a daemon can be woken up and +started by sending the process a `SIGUSR1`. For example, to trigger a +Chef Infra Client run on a machine running Linux: + +```bash +sudo killall -USR1 chef-client +``` + +**Setting the initial run-list using a JSON file** + +{{< readfile file="content/reusable/md/workstation/ctl_chef_client_bootstrap_initial_run_list.md" >}} diff --git a/content/reference/glossary.md b/content/reference/glossary.md new file mode 100644 index 0000000..ca4a70c --- /dev/null +++ b/content/reference/glossary.md @@ -0,0 +1,130 @@ ++++ +title = "Glossary" +draft = false + +[menu] + [menu.reference] + title = "Glossary" + identifier = "reference/glossary.md Glossary" + parent = "reference" ++++ + +Berkshelf + +: The legacy tool for managing cookbook dependencies. Policyfiles should be used instead. + +chef + +: `chef` is the Chef Workstation command line tool for managing your Chef development environment including repositories, cookbooks, recipes, attributes, templates, custom resources, and Ruby dependencies. + +ChefDK + +: The legacy package of tools for developing Chef Infra cookbooks. This product has been superseded by Chef Workstation which should be used instead. + +ChefSpec + +: ChefSpec is a unit-testing framework for testing Chef Infra cookbooks. + +Chef Automate + +: A full suite of enterprise capabilities for maintaining continuous visibility into application, infrastructure, and security automation. + +Chef Infra Client + +: A command-line tool that that runs Chef. Also, the name of Chef as it's installed on a node. + +Chef Infra Server + +: Chef Infra Server acts as a hub for configuration data. Chef Infra Server stores cookbooks, the policies that are applied to nodes, and metadata that describes each registered node that's being managed by Chef Infra Client. Nodes use Chef Infra Client to ask Chef Infra Server for configuration details, such as recipes, templates, and file distributions. + +Chef Workstation + +: A collection of tools to aide in development of Chef Infra cookbooks. It uses the full stack installer to give you everything you need to get going in one package. You can download it at [Chef Downloads](https://www.chef.io/downloads). + +chef-client + +: The `chef-client` is the name for both the command line tool that runs on your local computer and the program that runs on nodes. The `chef-client` allows you to ensure the configuration compliance of your systems through policy code. You use the chef-client command line tool from your local computer to send instructions to the program on the node. You install the chef-client on nodes with the bootstrap process from your computer and then you configure it to run on an interval to ensure continuous configuration compliance. + +chef-repo + +: The repository structure in which cookbooks are authored, tested, and maintained. View [an example of the](https://github.com/chef/chef-repo) chef-repo. + +chef-zero + +: A lightweight Chef Infra Server that runs in-memory on the local machine during a Chef Infra Client run. Also known as local mode. + +cookbook + +: A cookbook is the fundamental unit of configuration and policy distribution in Chef Infra. + +Cookstyle + +: A linting tool that helps you write better Chef Infra cookbooks by detecting and automatically correcting style, syntax, and logic mistakes in your code. + +custom resource + +: An extension to Chef Infra Client that allows you to ship your own reusable resources within a cookbook. + +data bag + +: A data_bag is a global variable that's stored as JSON data and is accessible from a Chef Infra Server. + +environment + +: An environment is a way to map an organization's real-life workflow to what can be configured and managed when using Chef Infra Server. + +Foodcritic + +: A legacy linting tool for doing static code analysis on cookbooks. This tool has been replaced with Cookstyle which should be used instead. + +knife + +: A command-line tool that provides an interface between a local chef-repo and Chef Infra Server. Use it to manage nodes, cookbooks, recipes, roles, data bags, environments, bootstrapping nodes, searching Chef Infra Server, and more. + +library + +: A library allows arbitrary Ruby code to be included in a cookbook, either as a way of extending the classes that are built-in to Chef Infra Client or by implementing entirely new functionality. + +node + +: A node is any physical, virtual, or cloud device that's configured and maintained by an instance of Chef Infra Client. + +node object + +: A node object is a history of the attributes, run-lists, and roles that were used to configure a node that's under management by Chef Infra. + +ohai + +: Ohai is a tool that's used to detect attributes on a node, and then provide these attributes to Chef Infra Client at the start of every run. + +organization + +: An organization is a single instance of a Chef Infra Server, including all of the nodes that are managed by that Chef Infra Server and each of the workstations that will run knife and access Chef Infra Server using the Chef Infra Server API. + +policy + +: Policy settings can be used to map business and operational requirements, such as process and workflow, to settings and objects stored on Chef Infra Server. See roles, environments, and data bags. + +recipe + +: A recipe is a collection of resources that tells Chef Infra Client how to configure a node. + +resource + +: A resource is a statement of configuration policy that describes the desired state of an piece within your infrastructure, along with the steps needed to bring that item to the desired state. + +role + +: A role is a way to define certain patterns and processes that exist across nodes in an organization as belonging to a single job function. + +run-list + +: A run-list defines all of the configuration settings that are necessary for a node that's under management by Chef to be put into the desired state and the order in which these configuration settings are applied. + +Test Kitchen + +: Test Kitchen is an integration framework that's used to automatically test cookbook data across any combination of platforms and test suites. Test Kitchen is packaged in Chef Workstation. + +Unified Mode + +: Unified mode combines the compile and converge stages of the Chef Infra Client run into one phase. Unified mode means that the Chef Infra Client compiles and applies a custom resource in order, from top to bottom. Unified mode works only on custom resources and doesn't affect other resources or recipes. diff --git a/content/resources.md b/content/resources.md deleted file mode 100644 index 41c7bb7..0000000 --- a/content/resources.md +++ /dev/null @@ -1,118 +0,0 @@ -+++ -title = "Supported Chef Infra resources" - -[menu.resources] -title = "Supported resources" -+++ - -The following resources are supported in Chef Infra Client 19 RC3. -Agentless Mode is only supported on Linux nodes. - -| **Resources Name** | **Supported on Windows with regular Client runs** | **Platforms supported in Agentless Mode and regular Client runs** | **Remarks** | -|---|---|---|---| -| [alternatives](https://docs.chef.io/resources/alternatives/) | | Ubuntu, Linux | | -| [apt_package](https://docs.chef.io/resources/apt_package/) | | Ubuntu | | -| [apt_preference](https://docs.chef.io/resources/apt_preference/) | | Ubuntu, Linux | | -| [apt_repository](https://docs.chef.io/resources/apt_repository/) | | Ubuntu, Linux | | -| [apt_update](https://docs.chef.io/resources/apt_update/) | | Ubuntu, Linux | | -| [bash](https://docs.chef.io/resources/bash/) | | Ubuntu, Linux | | -| [breakpoint](https://docs.chef.io/resources/breakpoint/) | | Ubuntu, Linux | | -| [chef_acl](https://docs.chef.io/resources/chef_acl/) | | Ubuntu, Linux, CentOS 9 | | -| [chef_client](https://docs.chef.io/resources/chef_client/) | | Ubuntu 24.04, RHEL 9 | | -| [chef_client_config](https://docs.chef.io/resources/chef_client_config/) | | Ubuntu, Linux | | -| [chef_container](https://docs.chef.io/resources/chef_container/) | | Ubuntu, Linux | | -| [chef_data_bag](https://docs.chef.io/resources/chef_data_bag/) | | Ubuntu, Linux | | -| [chef_environment](https://docs.chef.io/resources/chef_environment/) | | Ubuntu, Linux | | -| [chef_gem](https://docs.chef.io/resources/chef_gem/) | Windows ||| -| [chef_group](https://docs.chef.io/resources/chef_group/) | | Ubuntu 24.04 and 18.04, RHEL | | -| [chef_node](https://docs.chef.io/resources/chef_node/) | | Ubuntu 24.04, RHEL 9 | | -| [chef_organization](https://docs.chef.io/resources/chef_organization/) | | Ubuntu 24.04 and 18.04, RHEL | | -| [chef_role](https://docs.chef.io/resources/chef_role/) | | Ubuntu 24.04, RHEL 9 | | -| [chef_sleep](https://docs.chef.io/resources/chef_sleep/) | Windows | Ubuntu, Linux | | -| [chef_user](https://docs.chef.io/resources/chef_user/) | | Ubuntu 24.04 and 18.04, RHEL | | -| [cookbook_file](https://docs.chef.io/resources/cookbook_file/) | Windows | Ubuntu, Linux | | -| [cron](https://docs.chef.io/resources/cron/) | | Ubuntu, Linux | | -| [cron_access](https://docs.chef.io/resources/cron_access/) | | Ubuntu, Linux | | -| [cron_d](https://docs.chef.io/resources/cron_d/) | | Ubuntu, Linux | | -| [csh](https://docs.chef.io/resources/csh/) | | Ubuntu 24.04, RHEL 9 | | -| [directory](https://docs.chef.io/resources/directory/) | Windows | Ubuntu, Linux | | -| [execute](https://docs.chef.io/resources/execute/) | Windows | Ubuntu, Linux | | -| [file](https://docs.chef.io/resources/file/) | | Ubuntu, Linux | | -| [freebsd_package](https://docs.chef.io/resources/freebsd_package/) | | FreeBSD 14 | Only supported on FreeBSD. | -| [git](https://docs.chef.io/resources/git/) | | Ubuntu, Linux | | -| [group](https://docs.chef.io/resources/group/) | | Ubuntu, Linux | | -| [habitat_config](https://docs.chef.io/resources/habitat_config/) | | Ubuntu 24.04, RHEL 9 | | -| [habitat_install](https://docs.chef.io/resources/habitat_install/) | | Ubuntu, Linux | | -| [habitat_package](https://docs.chef.io/resources/habitat_package/) | | Ubuntu, Linux | | -| [habitat_service](https://docs.chef.io/resources/habitat_service/) | | Ubuntu, Linux | | -| [habitat_sup](https://docs.chef.io/resources/habitat_sup/) | | Ubuntu, Linux | | -| [hostname](https://docs.chef.io/resources/hostname/) | Windows | Ubuntu, Linux | | -| [http_request](https://docs.chef.io/resources/http_request/) | | Ubuntu, Linux | | -| [ifconfig](https://docs.chef.io/resources/ifconfig/) | | Ubuntu, Linux | | -| [inspec_input](https://docs.chef.io/resources/inspec_input/) | | Ubuntu 24.04, RHEL 9 | | -| [inspec_waiver](https://docs.chef.io/resources/inspec_waiver/) | | Ubuntu, Linux | | -| [inspec_waiver_file_entry](https://docs.chef.io/resources/inspec_waiver_file_entry/) | Windows | Ubuntu, Linux | | -| [kernel_module](https://docs.chef.io/resources/kernel_module/) | | Ubuntu, Linux | | -| [ksh](https://docs.chef.io/resources/ksh/) | | Ubuntu 24.04, RHEL 9 | | -| [link](https://docs.chef.io/resources/link/) | | Ubuntu, Linux | | -| [locale](https://docs.chef.io/resources/locale/) | Windows | Ubuntu | | -| [log](https://docs.chef.io/resources/log/) | | Ubuntu, Linux | | -| [mount](https://docs.chef.io/resources/mount/) | | Ubuntu 24.04, CentOS 9 | | -| [notify_group](https://docs.chef.io/resources/notify_group/) | | Ubuntu, Linux | | -| [ohai](https://docs.chef.io/resources/ohai/) | | Ubuntu, Linux | | -| [ohai_hint](https://docs.chef.io/resources/ohai_hint/) | | Ubuntu, Linux | | -| [openssl_openssl_dhparam](https://docs.chef.io/resources/ohai_openssl_dhparam/) | Windows ||| -| [openssl_ec_private_key](https://docs.chef.io/resources/ohai_ec_private_key/) | Windows ||| -| [openssl_ec_public_key](https://docs.chef.io/resources/ohai_ec_public_key/) | Windows ||| -| [openssl_rsa_private_key](https://docs.chef.io/resources/ohai_rsa_private_key/) | Windows ||| -| [openssl_rsa_public_key](https://docs.chef.io/resources/ohai_rsa_public_key/) | Windows ||| -| [openssl_x509_certificate](https://docs.chef.io/resources/ohai_x509_certificate/) | Windows ||| -| [openssl_x509_crl](https://docs.chef.io/resources/ohai_x509_crl/) | Windows ||| -| [openssl_x509_request](https://docs.chef.io/resources/ohai_x509_request/) | Windows ||| -| [owner](https://docs.chef.io/resources/owner/) | | Ubuntu, Linux | | -| [package](https://docs.chef.io/resources/package/) | | Ubuntu, Linux, CentOS 9 | | -| [perl](https://docs.chef.io/resources/perl/) | | Ubuntu | | -| [powershell_script](https://docs.chef.io/resources/powershell_script/) | Windows ||| -| [python](https://docs.chef.io/resources/python/) | | Ubuntu 24.04, RHEL 9 | | -| [reboot](https://docs.chef.io/resources/reboot/) | | Ubuntu, Linux | | -| [remote_file](https://docs.chef.io/resources/remote_file/) | | Ubuntu, Linux, CentOS 9 | | -| [rhsm_errata](https://docs.chef.io/resources/rhsm_errata/) | | RHEL | | -| [rhsm_errata_level](https://docs.chef.io/resources/rhsm_errata_level/) | | RHEL | | -| [rhsm_register](https://docs.chef.io/resources/rhsm_register/) | | RHEL | | -| [rhsm_repo](https://docs.chef.io/resources/rhsm_repo/) | | RHEL | | -| [rhsm_subscription](https://docs.chef.io/resources/rhsm_subscription/) | | RHEL | | -| [route](https://docs.chef.io/resources/route/) | | Ubuntu 24.04, CentOS 9 | | -| [rpm_package](https://docs.chef.io/resources/rpm_package/) | | CentOS 9 | The RPM package must be locally available on the remote system. | -| [ruby_block](https://docs.chef.io/resources/ruby_block/) | | Ubuntu, Linux, CentOS 9 | | -| [script](https://docs.chef.io/resources/script/) | | Ubuntu 24.04, RHEL 9 | | -| [selinux_boolean](https://docs.chef.io/resources/selinux_boolean/) | | Ubuntu, Linux | | -| [selinux_fcontext](https://docs.chef.io/resources/selinux_fcontext/) | | Ubuntu, Linux | | -| [selinux_install](https://docs.chef.io/resources/selinux_install/) | | Ubuntu, Linux | | -| [selinux_login](https://docs.chef.io/resources/selinux_login/) | | Ubuntu, Linux | | -| [selinux_module](https://docs.chef.io/resources/selinux_module/) | | Ubuntu, Linux | | -| [selinux_permissive](https://docs.chef.io/resources/selinux_permissive/) | | Ubuntu, Linux | | -| [selinux_port](https://docs.chef.io/resources/selinux_port/) | | Ubuntu, Linux | | -| [selinux_state](https://docs.chef.io/resources/selinux_state/) | | Ubuntu, Linux | | -| [selinux_user](https://docs.chef.io/resources/selinux_user/) | | Ubuntu, Linux | | -| [service](https://docs.chef.io/resources/service/) | | Ubuntu, Linux, CentOS 9 | `crond` for Linux | -| [snap_package](https://docs.chef.io/resources/snap_package/) | | Ubuntu 24.04 | Only supported on Linux. | -| [ssh_known_hosts_entry](https://docs.chef.io/resources/ssh_known_hosts_entry/) | | Ubuntu, Linux | | -| [subversion](https://docs.chef.io/resources/subversion/) | | Ubuntu 24.04, RHEL 9, CentOS 9 | The subversion resource has known bugs and may not work as expected. For more information, see the Chef GitHub issues, particularly [#4050](https://github.com/chef/chef/issues/4050) and [#4257](https://github.com/chef/chef/issues/4257). | -| [sudo](https://docs.chef.io/resources/sudo/) | | Ubuntu, Linux, CentOS 9 | | -| [swap_file](https://docs.chef.io/resources/swap_file/) | | Ubuntu, Linux | | -| [sysctl](https://docs.chef.io/resources/sysctl/) | | Ubuntu, Linux | | -| [systemd_unit](https://docs.chef.io/resources/systemd_unit/) | | Ubuntu, Linux | | -| [template](https://docs.chef.io/resources/template/) | | Ubuntu, Linux, CentOS 9 | Require absolute path for source attribute. | | -| [timezone](https://docs.chef.io/resources/timezone/) | Windows | Linux | | -| [user](https://docs.chef.io/resources/user/) | | Ubuntu, Linux | | -| [user_ulimit](https://docs.chef.io/resources/user_ulimit/) | | Ubuntu, Linux | | -| [windows_audit_policy](https://docs.chef.io/resources/windows_audit_policy/) | Windows ||| -| [windows_certificate](https://docs.chef.io/resources/windows_certificate/) | Windows ||| -| [windows_feature_powershell](https://docs.chef.io/resources/windows_feature_powershell/) | Windows ||| -| [windows_firewall_profile](https://docs.chef.io/resources/windows_firewall_profile/) | Windows ||| -| [windows_security_policy](https://docs.chef.io/resources/windows_security_policy/) | Windows ||| -| [windows_update_settings](https://docs.chef.io/resources/windows_update_settings/) | Windows ||| -| [yum_package](https://docs.chef.io/resources/yum_package/) | | CentOS 9 | Only supported on Linux. | -| [yum_repository](https://docs.chef.io/resources/yum_repository/) | | Linux | | -| [yum_repository](https://docs.chef.io/resources/yum_repository/) | | CentOS 9, RHEL 8 | Only supported on Linux. | -| [zypper_package](https://docs.chef.io/resources/zypper_package/) | | SUSE Linux 15 | | diff --git a/content/resources/_index.md b/content/resources/_index.md new file mode 100644 index 0000000..43d0117 --- /dev/null +++ b/content/resources/_index.md @@ -0,0 +1,74 @@ ++++ +title = "About Resources" +draft = false +linkTitle = "Resources" + +[menu] + [menu.resources] + title = "About Resources" + identifier = "resources/resource.md About Resources" + parent = "resources" + weight = 10 ++++ + +{{< readfile file="content/reusable/md/resources_common.md" >}} + +## Resource Syntax + +A resource is a Ruby block with four components: a type, a name, one (or +more) properties (with values), and one (or more) actions. The syntax +for a resource is like this: + +```ruby +type 'name' do + attribute 'value' + action :type_of_action +end +``` + +Every resource has its own set of actions and properties. Most +properties have default values. Some properties are available to all +resources, for example those used to send notifications to other +resources and guards that help ensure that some resources are +idempotent. + +For example, a resource that's used to install a tar.gz package for +version 1.16.1 may look something like this: + +```ruby +package 'tar' do + version '1.16.1' + action :install +end +``` + +All actions have a default value. Only non-default behaviors of actions +and properties need to be specified. For example, the **package** +resource's default action is `:install` and the name of the package +defaults to the `name` of the resource. Therefore, it's possible to +write a resource block that installs the latest tar.gz package like +this: + +```ruby +package 'tar' +``` + +and a resource block that installs a tar.gz package for version 1.6.1 +like this: + +```ruby +package 'tar' do + version '1.16.1' +end +``` + +In both cases, Chef Infra Client will use the default action +(`:install`) to install the `tar` package. + +## Additional Information + +See these guides for additional information about resources: + +- **[Common resource properties](common_functionality)**: Provides a detailed list of the common properties that are available in all resources. +- **[Bundled resources reference](bundled)**: A reference guide that lists both the common and individual options available to every resource that's bundled into Chef. +- **[Custom resources](custom)**: Shows you how to create your own Chef resources. diff --git a/content/resources/bundled/_index.md b/content/resources/bundled/_index.md new file mode 100644 index 0000000..a1e98cc --- /dev/null +++ b/content/resources/bundled/_index.md @@ -0,0 +1,367 @@ ++++ +title = "All Infra Resources" +draft = false +description = "This reference describes each of the resources available to Chef Infra Client, including a list of actions, properties, and usage examples." +linkTitle = "Bundled resources" + + +data_path = ["infra","resources"] +layout = "infra_resources_all" +toc_layout = "infra_resources_all_toc" + +[menu] + [menu.resources] + title = "All Resources (Single Page)" + identifier = "resources/bundled/All Resources" + parent = "resources/bundled" + weight = 60 ++++ + + + + + + + + +This reference describes each of the resources available to Chef Infra Client, including a list of actions, properties, and usage examples. + +## Common Functionality + +The properties and actions in this section apply to all resources. + +### Actions + +The following actions may be used with any resource: + +`:nothing` + +: {{< readfile file="content/reusable/md/resources_common_actions_nothing.md" >}} + +#### Examples + +The following examples show how to use common actions in a recipe. + +**Use the :nothing action** + +{{< readfile file="content/reusable/md/resource_service_use_nothing_action.md" >}} + +### Properties + +The following properties are common to every resource: + +`ignore_failure` +: **Ruby Type:** true, false | **Default Value:** `false` + + Continue running a recipe if a resource fails for any reason. + +`retries` +: **Ruby Type:** Integer | **Default Value:** `0` + + The number of attempts to catch exceptions and retry the resource. + +`retry_delay` +: **Ruby Type:** Integer | **Default Value:** `2` + + The retry delay (in seconds). + +`sensitive` +: **Ruby Type:** true, false | **Default Value:** `false` + + Ensure that sensitive resource data isn't logged by Chef Infra Client. + +#### Examples + +The following examples show how to use common properties in a recipe. + +**Use the ignore_failure common property** + +{{< readfile file="content/reusable/md/resource_package_use_ignore_failure_attribute.md" >}} + +**Use the retries and retry_delay common properties** + +{{< readfile file="content/reusable/md/resource_service_use_retries_properties.md" >}} + +### Guards + +{{< readfile file="content/reusable/md/resources_common_guards.md" >}} + +#### Properties + +{{< readfile file="content/reusable/md/resources_common_guards_properties.md" >}} + +#### Arguments + +{{< readfile file="content/reusable/md/resources_common_guards_arguments.md" >}} + +#### not_if Examples + +The following examples show how to use `not_if` as a condition in a recipe: + +**Create a file, but not if an attribute has a specific value** + +The following example shows how to use the `not_if` condition to create +a file based on a template and using the presence of an attribute value +on the node to specify the condition: + +```ruby +template '/tmp/somefile' do + mode '0755' + source 'somefile.erb' + not_if { node['some_value'] } +end +``` + +**Create a file with a Ruby block, but not if "/etc/passwd" exists** + +The following example shows how to use the `not_if` condition to create +a file based on a template and then Ruby code to specify the condition: + +```ruby +template '/tmp/somefile' do + mode '0755' + source 'somefile.erb' + not_if do + ::File.exist?('/etc/passwd') + end +end +``` + + +**Create a file with Ruby block that has curly braces, but not if "/etc/passwd" exists** + +The following example shows how to use the `not_if` condition to create +a file based on a template and using a Ruby block (with curly braces) to +specify the condition: + +```ruby +template '/tmp/somefile' do + mode '0755' + source 'somefile.erb' + not_if { ::File.exist?('/etc/passwd') } +end +``` + +**Create a file using a string, but not if "/etc/passwd" exists** + +The following example shows how to use the `not_if` condition to create +a file based on a template and using a string to specify the condition: + +```ruby +template '/etc/some_config' do + mode '0640' + source 'some_config.erb' + not_if 'some_app --check-config' +end +``` + +#### only_if Examples + +The following examples show how to use `only_if` as a condition in a recipe: + +**Create a file, but only if an attribute has a specific value** + +The following example shows how to use the `only_if` condition to create +a file based on a template and using the presence of an attribute on the +node to specify the condition: + +```ruby +template '/tmp/somefile' do + mode '0755' + source 'somefile.erb' + only_if { node['some_value'] } +end +``` + +**Create a file with a Ruby block, but only if "/etc/passwd" doesn't exist** + +The following example shows how to use the `only_if` condition to create +a file based on a template, and then use Ruby to specify a condition: + +```ruby +template '/etc/some_app/some_config' do + mode '0640' + source 'some_config.erb' + only_if { ::File.exist?('/etc/some_app/') } +end +``` + +**Create a file using a string, but only if "/etc/passwd" exists** + +The following example shows how to use the `only_if` condition to create +a file based on a template and using a string to specify the condition: + +```ruby +template '/tmp/somefile' do + mode '0755' + source 'somefile.erb' + only_if 'test -f /etc/passwd' +end +``` + +### Guard Interpreters + +{{< readfile file="content/reusable/md/resources_common_guard_interpreter.md" >}} + +#### Attributes + +{{< readfile file="content/reusable/md/resources_common_guard_interpreter_attributes.md" >}} + +#### Inheritance + +{{< readfile file="content/reusable/md/resources_common_guard_interpreter_attributes_inherit.md" >}} + +#### Examples + +{{< readfile file="content/reusable/md/resources_common_guard_interpreter_example_default.md" >}} + +### Lazy Evaluation + +{{< readfile file="content/reusable/md/resources_common_lazy_evaluation.md" >}} + +### Notifications + +{{< readfile file="content/reusable/md/resources_common_notification.md" >}} + +#### Timers + +{{< readfile file="content/reusable/md/resources_common_notification_timers.md" >}} + +#### Notifies + +{{< readfile file="content/reusable/md/resources_common_notification_notifies.md" >}} + +{{< readfile file="content/reusable/md/resources_common_notification_notifies_syntax.md" >}} + +##### Examples + +The following examples show how to use the `notifies` notification in a recipe. + +**Delay notifications** + +{{< readfile file="content/reusable/md/resource_template_notifies_delay.md" >}} + +**Notify immediately** + +{{< readfile file="content/reusable/md/resource_template_notifies_run_immediately.md" >}} + +**Notify multiple resources** + +{{< readfile file="content/reusable/md/resource_template_notifies_multiple_resources.md" >}} + +**Notify in a specific order** + +{{< readfile file="content/reusable/md/resource_execute_notifies_specific_order.md" >}} + +**Reload a service** + +{{< readfile file="content/reusable/md/resource_template_notifies_reload_service.md" >}} + +**Restart a service when a template is modified** + +{{< readfile file="content/reusable/md/resource_template_notifies_restart_service_when_template_modified.md" >}} + +**Send notifications to multiple resources** + +{{< readfile file="content/reusable/md/resource_template_notifies_send_notifications_to_multiple_resources.md" >}} + +**Execute a command using a template** + +{{< readfile file="content/reusable/md/resource_execute_command_from_template.md" >}} + +**Restart a service, and then notify a different service** + +{{< readfile file="content/reusable/md/resource_service_restart_and_notify.md" >}} + +**Restart one service before restarting another** + +{{< readfile file="content/reusable/md/resource_before_notification_restart.md" >}} + +**Notify when a remote source changes** + +{{< readfile file="content/reusable/md/resource_remote_file_transfer_remote_source_changes.md" >}} + +#### Subscribes + +{{< readfile file="content/reusable/md/resources_common_notification_subscribes.md" >}} + +{{< readfile file="content/reusable/md/resources_common_notification_subscribes_syntax.md" >}} + +##### Examples + +The following examples show how to use the `subscribes` notification in a recipe. + +**Prevent restart and reconfigure if configuration is broken** + +{{< readfile file="content/reusable/md/resource_execute_subscribes_prevent_restart_and_reconfigure.md" >}} + +**Reload a service using a template** + +{{< readfile file="content/reusable/md/resource_service_subscribes_reload_using_template.md" >}} + +**Stash a file in a data bag** + +The following example shows how to use the **ruby_block** resource to +stash a BitTorrent file in a data bag so that it can be distributed to +nodes in the organization. + +```ruby +# the following code sample comes from the ``seed`` recipe +# in the following cookbook: https://github.com/mattray/bittorrent-cookbook + +ruby_block 'share the torrent file' do + block do + f = File.open(node['bittorrent']['torrent'], 'rb') + #read the .torrent file and base64 encode it + enc = Base64.encode64(f.read) + data = { + 'id' => bittorrent_item_id(node['bittorrent']['file']), + 'seed' => node['ipaddress'], + 'torrent' => enc, + } + item = Chef::DataBagItem.new + item.data_bag('bittorrent') + item.raw_data = data + item.save + end + action :nothing + subscribes :create, "bittorrent_torrent[#{node['bittorrent']['torrent']}]", :immediately +end +``` + +### Relative Paths + +{{< readfile file="content/reusable/md/resources_common_relative_paths.md" >}} + +#### Examples + +{{< readfile file="content/reusable/md/resource_template_use_relative_paths.md" >}} + +### Run in Compile Phase + +{{< readfile file="content/reusable/md/resources_common_compile.md" >}} + +#### run_action + +{{< readfile file="content/reusable/md/resources_common_compile_begin.md" >}} + +### Atomic File Updates + +{{< readfile file="content/reusable/md/resources_common_atomic_update.md" >}} + +### Windows File Security + +{{< readfile file="content/reusable/md/resources_common_windows_security.md" >}} + +**Access Control Lists (ACLs)** + +{{< readfile file="content/reusable/md/resources_common_windows_security_acl.md" >}} + +**Inheritance** + +{{< readfile file="content/reusable/md/resources_common_windows_security_inherits.md" >}} + +## Resources + +The following resources are built into the Chef Infra Client: diff --git a/content/resources/bundled/alternatives.md b/content/resources/bundled/alternatives.md new file mode 100644 index 0000000..137a305 --- /dev/null +++ b/content/resources/bundled/alternatives.md @@ -0,0 +1,19 @@ ++++ +title = "alternatives Resource" +draft = false +robots = "" + +data_path = ["infra","resources","alternatives"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "alternatives" + identifier = "resources/bundled/alternatives" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/apt_package.md b/content/resources/bundled/apt_package.md new file mode 100644 index 0000000..18f6b7a --- /dev/null +++ b/content/resources/bundled/apt_package.md @@ -0,0 +1,19 @@ ++++ +title = "apt_package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","apt_package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "apt_package" + identifier = "resources/bundled/apt_package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/apt_preference.md b/content/resources/bundled/apt_preference.md new file mode 100644 index 0000000..307abc0 --- /dev/null +++ b/content/resources/bundled/apt_preference.md @@ -0,0 +1,19 @@ ++++ +title = "apt_preference Resource" +draft = false +robots = "" + +data_path = ["infra","resources","apt_preference"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "apt_preference" + identifier = "resources/bundled/apt_preference" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/apt_repository.md b/content/resources/bundled/apt_repository.md new file mode 100644 index 0000000..edf4a28 --- /dev/null +++ b/content/resources/bundled/apt_repository.md @@ -0,0 +1,19 @@ ++++ +title = "apt_repository Resource" +draft = false +robots = "" + +data_path = ["infra","resources","apt_repository"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "apt_repository" + identifier = "resources/bundled/apt_repository" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/apt_update.md b/content/resources/bundled/apt_update.md new file mode 100644 index 0000000..bd4484b --- /dev/null +++ b/content/resources/bundled/apt_update.md @@ -0,0 +1,19 @@ ++++ +title = "apt_update Resource" +draft = false +robots = "" + +data_path = ["infra","resources","apt_update"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "apt_update" + identifier = "resources/bundled/apt_update" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/archive_file.md b/content/resources/bundled/archive_file.md new file mode 100644 index 0000000..d9102d1 --- /dev/null +++ b/content/resources/bundled/archive_file.md @@ -0,0 +1,19 @@ ++++ +title = "archive_file Resource" +draft = false +robots = "" + +data_path = ["infra","resources","archive_file"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "archive_file" + identifier = "resources/bundled/archive_file" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/bash.md b/content/resources/bundled/bash.md new file mode 100644 index 0000000..bf392b9 --- /dev/null +++ b/content/resources/bundled/bash.md @@ -0,0 +1,19 @@ ++++ +title = "bash Resource" +draft = false +robots = "" + +data_path = ["infra","resources","bash"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "bash" + identifier = "resources/bundled/bash" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/batch.md b/content/resources/bundled/batch.md new file mode 100644 index 0000000..197044c --- /dev/null +++ b/content/resources/bundled/batch.md @@ -0,0 +1,19 @@ ++++ +title = "batch Resource" +draft = false +robots = "" + +data_path = ["infra","resources","batch"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "batch" + identifier = "resources/bundled/batch" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/bff_package.md b/content/resources/bundled/bff_package.md new file mode 100644 index 0000000..b4673f7 --- /dev/null +++ b/content/resources/bundled/bff_package.md @@ -0,0 +1,19 @@ ++++ +title = "bff_package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","bff_package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "bff_package" + identifier = "resources/bundled/bff_package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/breakpoint.md b/content/resources/bundled/breakpoint.md new file mode 100644 index 0000000..e204e0d --- /dev/null +++ b/content/resources/bundled/breakpoint.md @@ -0,0 +1,19 @@ ++++ +title = "breakpoint Resource" +draft = false +robots = "" + +data_path = ["infra","resources","breakpoint"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "breakpoint" + identifier = "resources/bundled/breakpoint" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/build_essential.md b/content/resources/bundled/build_essential.md new file mode 100644 index 0000000..41cbca3 --- /dev/null +++ b/content/resources/bundled/build_essential.md @@ -0,0 +1,19 @@ ++++ +title = "build_essential Resource" +draft = false +robots = "" + +data_path = ["infra","resources","build_essential"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "build_essential" + identifier = "resources/bundled/build_essential" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/cab_package.md b/content/resources/bundled/cab_package.md new file mode 100644 index 0000000..2e79589 --- /dev/null +++ b/content/resources/bundled/cab_package.md @@ -0,0 +1,19 @@ ++++ +title = "cab_package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","cab_package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "cab_package" + identifier = "resources/bundled/cab_package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/chef_acl.md b/content/resources/bundled/chef_acl.md new file mode 100644 index 0000000..3c8ecd1 --- /dev/null +++ b/content/resources/bundled/chef_acl.md @@ -0,0 +1,19 @@ ++++ +title = "chef_acl Resource" +draft = false +robots = "" + +data_path = ["infra","resources","chef_acl"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "chef_acl" + identifier = "resources/bundled/chef_acl" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/chef_client.md b/content/resources/bundled/chef_client.md new file mode 100644 index 0000000..afb8ff1 --- /dev/null +++ b/content/resources/bundled/chef_client.md @@ -0,0 +1,19 @@ ++++ +title = "chef_client Resource" +draft = false +robots = "" + +data_path = ["infra","resources","chef_client"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "chef_client" + identifier = "resources/bundled/chef_client" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/chef_client_config.md b/content/resources/bundled/chef_client_config.md new file mode 100644 index 0000000..c95e830 --- /dev/null +++ b/content/resources/bundled/chef_client_config.md @@ -0,0 +1,19 @@ ++++ +title = "chef_client_config Resource" +draft = false +robots = "" + +data_path = ["infra","resources","chef_client_config"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "chef_client_config" + identifier = "resources/bundled/chef_client_config" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/chef_client_cron.md b/content/resources/bundled/chef_client_cron.md new file mode 100644 index 0000000..87743ac --- /dev/null +++ b/content/resources/bundled/chef_client_cron.md @@ -0,0 +1,19 @@ ++++ +title = "chef_client_cron Resource" +draft = false +robots = "" + +data_path = ["infra","resources","chef_client_cron"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "chef_client_cron" + identifier = "resources/bundled/chef_client_cron" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/chef_client_launchd.md b/content/resources/bundled/chef_client_launchd.md new file mode 100644 index 0000000..e0e658d --- /dev/null +++ b/content/resources/bundled/chef_client_launchd.md @@ -0,0 +1,19 @@ ++++ +title = "chef_client_launchd Resource" +draft = false +robots = "" + +data_path = ["infra","resources","chef_client_launchd"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "chef_client_launchd" + identifier = "resources/bundled/chef_client_launchd" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/chef_client_scheduled_task.md b/content/resources/bundled/chef_client_scheduled_task.md new file mode 100644 index 0000000..e05efa5 --- /dev/null +++ b/content/resources/bundled/chef_client_scheduled_task.md @@ -0,0 +1,19 @@ ++++ +title = "chef_client_scheduled_task Resource" +draft = false +robots = "" + +data_path = ["infra","resources","chef_client_scheduled_task"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "chef_client_scheduled_task" + identifier = "resources/bundled/chef_client_scheduled_task" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/chef_client_systemd_timer.md b/content/resources/bundled/chef_client_systemd_timer.md new file mode 100644 index 0000000..1dea7d6 --- /dev/null +++ b/content/resources/bundled/chef_client_systemd_timer.md @@ -0,0 +1,19 @@ ++++ +title = "chef_client_systemd_timer Resource" +draft = false +robots = "" + +data_path = ["infra","resources","chef_client_systemd_timer"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "chef_client_systemd_timer" + identifier = "resources/bundled/chef_client_systemd_timer" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/chef_client_trusted_certificate.md b/content/resources/bundled/chef_client_trusted_certificate.md new file mode 100644 index 0000000..a0c7ac8 --- /dev/null +++ b/content/resources/bundled/chef_client_trusted_certificate.md @@ -0,0 +1,19 @@ ++++ +title = "chef_client_trusted_certificate Resource" +draft = false +robots = "" + +data_path = ["infra","resources","chef_client_trusted_certificate"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "chef_client_trusted_certificate" + identifier = "resources/bundled/chef_client_trusted_certificate" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/chef_container.md b/content/resources/bundled/chef_container.md new file mode 100644 index 0000000..24e67f4 --- /dev/null +++ b/content/resources/bundled/chef_container.md @@ -0,0 +1,19 @@ ++++ +title = "chef_container Resource" +draft = false +robots = "" + +data_path = ["infra","resources","chef_container"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "chef_container" + identifier = "resources/bundled/chef_container" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/chef_data_bag.md b/content/resources/bundled/chef_data_bag.md new file mode 100644 index 0000000..2743953 --- /dev/null +++ b/content/resources/bundled/chef_data_bag.md @@ -0,0 +1,19 @@ ++++ +title = "chef_data_bag Resource" +draft = false +robots = "" + +data_path = ["infra","resources","chef_data_bag"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "chef_data_bag" + identifier = "resources/bundled/chef_data_bag" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/chef_data_bag_item.md b/content/resources/bundled/chef_data_bag_item.md new file mode 100644 index 0000000..136cb03 --- /dev/null +++ b/content/resources/bundled/chef_data_bag_item.md @@ -0,0 +1,19 @@ ++++ +title = "chef_data_bag_item Resource" +draft = false +robots = "" + +data_path = ["infra","resources","chef_data_bag_item"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "chef_data_bag_item" + identifier = "resources/bundled/chef_data_bag_item" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/chef_environment.md b/content/resources/bundled/chef_environment.md new file mode 100644 index 0000000..18244f4 --- /dev/null +++ b/content/resources/bundled/chef_environment.md @@ -0,0 +1,19 @@ ++++ +title = "chef_environment Resource" +draft = false +robots = "" + +data_path = ["infra","resources","chef_environment"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "chef_environment" + identifier = "resources/bundled/chef_environment" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/chef_gem.md b/content/resources/bundled/chef_gem.md new file mode 100644 index 0000000..439e5a5 --- /dev/null +++ b/content/resources/bundled/chef_gem.md @@ -0,0 +1,19 @@ ++++ +title = "chef_gem Resource" +draft = false +robots = "" + +data_path = ["infra","resources","chef_gem"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "chef_gem" + identifier = "resources/bundled/chef_gem" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/chef_group.md b/content/resources/bundled/chef_group.md new file mode 100644 index 0000000..a2d7426 --- /dev/null +++ b/content/resources/bundled/chef_group.md @@ -0,0 +1,19 @@ ++++ +title = "chef_group Resource" +draft = false +robots = "" + +data_path = ["infra","resources","chef_group"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "chef_group" + identifier = "resources/bundled/chef_group" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/chef_handler.md b/content/resources/bundled/chef_handler.md new file mode 100644 index 0000000..870e019 --- /dev/null +++ b/content/resources/bundled/chef_handler.md @@ -0,0 +1,19 @@ ++++ +title = "chef_handler Resource" +draft = false +robots = "" + +data_path = ["infra","resources","chef_handler"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "chef_handler" + identifier = "resources/bundled/chef_handler" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/chef_node.md b/content/resources/bundled/chef_node.md new file mode 100644 index 0000000..6bf3c09 --- /dev/null +++ b/content/resources/bundled/chef_node.md @@ -0,0 +1,19 @@ ++++ +title = "chef_node Resource" +draft = false +robots = "" + +data_path = ["infra","resources","chef_node"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "chef_node" + identifier = "resources/bundled/chef_node" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/chef_organization.md b/content/resources/bundled/chef_organization.md new file mode 100644 index 0000000..883f5d4 --- /dev/null +++ b/content/resources/bundled/chef_organization.md @@ -0,0 +1,19 @@ ++++ +title = "chef_organization Resource" +draft = false +robots = "" + +data_path = ["infra","resources","chef_organization"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "chef_organization" + identifier = "resources/bundled/chef_organization" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/chef_role.md b/content/resources/bundled/chef_role.md new file mode 100644 index 0000000..ca59e6d --- /dev/null +++ b/content/resources/bundled/chef_role.md @@ -0,0 +1,19 @@ ++++ +title = "chef_role Resource" +draft = false +robots = "" + +data_path = ["infra","resources","chef_role"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "chef_role" + identifier = "resources/bundled/chef_role" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/chef_sleep.md b/content/resources/bundled/chef_sleep.md new file mode 100644 index 0000000..d0d9be5 --- /dev/null +++ b/content/resources/bundled/chef_sleep.md @@ -0,0 +1,19 @@ ++++ +title = "chef_sleep Resource" +draft = false +robots = "" + +data_path = ["infra","resources","chef_sleep"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "chef_sleep" + identifier = "resources/bundled/chef_sleep" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/chef_user.md b/content/resources/bundled/chef_user.md new file mode 100644 index 0000000..45534e7 --- /dev/null +++ b/content/resources/bundled/chef_user.md @@ -0,0 +1,19 @@ ++++ +title = "chef_user Resource" +draft = false +robots = "" + +data_path = ["infra","resources","chef_user"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "chef_user" + identifier = "resources/bundled/chef_user" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/chef_vault_secret.md b/content/resources/bundled/chef_vault_secret.md new file mode 100644 index 0000000..6ac6c55 --- /dev/null +++ b/content/resources/bundled/chef_vault_secret.md @@ -0,0 +1,19 @@ ++++ +title = "chef_vault_secret Resource" +draft = false +robots = "" + +data_path = ["infra","resources","chef_vault_secret"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "chef_vault_secret" + identifier = "resources/bundled/chef_vault_secret" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/chocolatey_config.md b/content/resources/bundled/chocolatey_config.md new file mode 100644 index 0000000..677262d --- /dev/null +++ b/content/resources/bundled/chocolatey_config.md @@ -0,0 +1,19 @@ ++++ +title = "chocolatey_config Resource" +draft = false +robots = "" + +data_path = ["infra","resources","chocolatey_config"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "chocolatey_config" + identifier = "resources/bundled/chocolatey_config" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/chocolatey_feature.md b/content/resources/bundled/chocolatey_feature.md new file mode 100644 index 0000000..298f96e --- /dev/null +++ b/content/resources/bundled/chocolatey_feature.md @@ -0,0 +1,19 @@ ++++ +title = "chocolatey_feature Resource" +draft = false +robots = "" + +data_path = ["infra","resources","chocolatey_feature"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "chocolatey_feature" + identifier = "resources/bundled/chocolatey_feature" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/chocolatey_installer.md b/content/resources/bundled/chocolatey_installer.md new file mode 100644 index 0000000..8355c62 --- /dev/null +++ b/content/resources/bundled/chocolatey_installer.md @@ -0,0 +1,19 @@ ++++ +title = "chocolatey_installer Resource" +draft = false +robots = "" + +data_path = ["infra","resources","chocolatey_installer"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "chocolatey_installer" + identifier = "resources/bundled/chocolatey_installer" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/chocolatey_package.md b/content/resources/bundled/chocolatey_package.md new file mode 100644 index 0000000..c84eb23 --- /dev/null +++ b/content/resources/bundled/chocolatey_package.md @@ -0,0 +1,19 @@ ++++ +title = "chocolatey_package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","chocolatey_package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "chocolatey_package" + identifier = "resources/bundled/chocolatey_package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/chocolatey_source.md b/content/resources/bundled/chocolatey_source.md new file mode 100644 index 0000000..1f5e9d8 --- /dev/null +++ b/content/resources/bundled/chocolatey_source.md @@ -0,0 +1,19 @@ ++++ +title = "chocolatey_source Resource" +draft = false +robots = "" + +data_path = ["infra","resources","chocolatey_source"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "chocolatey_source" + identifier = "resources/bundled/chocolatey_source" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/cookbook_file.md b/content/resources/bundled/cookbook_file.md new file mode 100644 index 0000000..31317ae --- /dev/null +++ b/content/resources/bundled/cookbook_file.md @@ -0,0 +1,19 @@ ++++ +title = "cookbook_file Resource" +draft = false +robots = "" + +data_path = ["infra","resources","cookbook_file"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "cookbook_file" + identifier = "resources/bundled/cookbook_file" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/cron.md b/content/resources/bundled/cron.md new file mode 100644 index 0000000..478a700 --- /dev/null +++ b/content/resources/bundled/cron.md @@ -0,0 +1,19 @@ ++++ +title = "cron Resource" +draft = false +robots = "" + +data_path = ["infra","resources","cron"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "cron" + identifier = "resources/bundled/cron" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/cron_access.md b/content/resources/bundled/cron_access.md new file mode 100644 index 0000000..d2f6434 --- /dev/null +++ b/content/resources/bundled/cron_access.md @@ -0,0 +1,19 @@ ++++ +title = "cron_access Resource" +draft = false +robots = "" + +data_path = ["infra","resources","cron_access"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "cron_access" + identifier = "resources/bundled/cron_access" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/cron_d.md b/content/resources/bundled/cron_d.md new file mode 100644 index 0000000..ab6a18b --- /dev/null +++ b/content/resources/bundled/cron_d.md @@ -0,0 +1,19 @@ ++++ +title = "cron_d Resource" +draft = false +robots = "" + +data_path = ["infra","resources","cron_d"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "cron_d" + identifier = "resources/bundled/cron_d" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/csh.md b/content/resources/bundled/csh.md new file mode 100644 index 0000000..c89f71e --- /dev/null +++ b/content/resources/bundled/csh.md @@ -0,0 +1,19 @@ ++++ +title = "csh Resource" +draft = false +robots = "" + +data_path = ["infra","resources","csh"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "csh" + identifier = "resources/bundled/csh" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/directory.md b/content/resources/bundled/directory.md new file mode 100644 index 0000000..57cd933 --- /dev/null +++ b/content/resources/bundled/directory.md @@ -0,0 +1,19 @@ ++++ +title = "directory Resource" +draft = false +robots = "" + +data_path = ["infra","resources","directory"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "directory" + identifier = "resources/bundled/directory" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/dmg_package.md b/content/resources/bundled/dmg_package.md new file mode 100644 index 0000000..205db9f --- /dev/null +++ b/content/resources/bundled/dmg_package.md @@ -0,0 +1,19 @@ ++++ +title = "dmg_package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","dmg_package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "dmg_package" + identifier = "resources/bundled/dmg_package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/dnf_package.md b/content/resources/bundled/dnf_package.md new file mode 100644 index 0000000..2ce9edf --- /dev/null +++ b/content/resources/bundled/dnf_package.md @@ -0,0 +1,19 @@ ++++ +title = "dnf_package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","dnf_package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "dnf_package" + identifier = "resources/bundled/dnf_package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/dpkg_package.md b/content/resources/bundled/dpkg_package.md new file mode 100644 index 0000000..26d5218 --- /dev/null +++ b/content/resources/bundled/dpkg_package.md @@ -0,0 +1,19 @@ ++++ +title = "dpkg_package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","dpkg_package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "dpkg_package" + identifier = "resources/bundled/dpkg_package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/dsc_resource.md b/content/resources/bundled/dsc_resource.md new file mode 100644 index 0000000..48aa8fe --- /dev/null +++ b/content/resources/bundled/dsc_resource.md @@ -0,0 +1,19 @@ ++++ +title = "dsc_resource Resource" +draft = false +robots = "" + +data_path = ["infra","resources","dsc_resource"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "dsc_resource" + identifier = "resources/bundled/dsc_resource" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/dsc_script.md b/content/resources/bundled/dsc_script.md new file mode 100644 index 0000000..eb859d3 --- /dev/null +++ b/content/resources/bundled/dsc_script.md @@ -0,0 +1,19 @@ ++++ +title = "dsc_script Resource" +draft = false +robots = "" + +data_path = ["infra","resources","dsc_script"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "dsc_script" + identifier = "resources/bundled/dsc_script" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/execute.md b/content/resources/bundled/execute.md new file mode 100644 index 0000000..b8e8024 --- /dev/null +++ b/content/resources/bundled/execute.md @@ -0,0 +1,19 @@ ++++ +title = "execute Resource" +draft = false +robots = "" + +data_path = ["infra","resources","execute"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "execute" + identifier = "resources/bundled/execute" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/file.md b/content/resources/bundled/file.md new file mode 100644 index 0000000..92149f6 --- /dev/null +++ b/content/resources/bundled/file.md @@ -0,0 +1,19 @@ ++++ +title = "file Resource" +draft = false +robots = "" + +data_path = ["infra","resources","file"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "file" + identifier = "resources/bundled/file" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/freebsd_package.md b/content/resources/bundled/freebsd_package.md new file mode 100644 index 0000000..a548c3f --- /dev/null +++ b/content/resources/bundled/freebsd_package.md @@ -0,0 +1,19 @@ ++++ +title = "freebsd_package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","freebsd_package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "freebsd_package" + identifier = "resources/bundled/freebsd_package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/gem_package.md b/content/resources/bundled/gem_package.md new file mode 100644 index 0000000..f3a591a --- /dev/null +++ b/content/resources/bundled/gem_package.md @@ -0,0 +1,19 @@ ++++ +title = "gem_package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","gem_package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "gem_package" + identifier = "resources/bundled/gem_package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/git.md b/content/resources/bundled/git.md new file mode 100644 index 0000000..414663b --- /dev/null +++ b/content/resources/bundled/git.md @@ -0,0 +1,19 @@ ++++ +title = "git Resource" +draft = false +robots = "" + +data_path = ["infra","resources","git"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "git" + identifier = "resources/bundled/git" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/group.md b/content/resources/bundled/group.md new file mode 100644 index 0000000..cbe378f --- /dev/null +++ b/content/resources/bundled/group.md @@ -0,0 +1,19 @@ ++++ +title = "group Resource" +draft = false +robots = "" + +data_path = ["infra","resources","group"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "group" + identifier = "resources/bundled/group" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/habitat_config.md b/content/resources/bundled/habitat_config.md new file mode 100644 index 0000000..7b550b9 --- /dev/null +++ b/content/resources/bundled/habitat_config.md @@ -0,0 +1,19 @@ ++++ +title = "habitat_config Resource" +draft = false +robots = "" + +data_path = ["infra","resources","habitat_config"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "habitat_config" + identifier = "resources/bundled/habitat_config" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/habitat_install.md b/content/resources/bundled/habitat_install.md new file mode 100644 index 0000000..3920c59 --- /dev/null +++ b/content/resources/bundled/habitat_install.md @@ -0,0 +1,19 @@ ++++ +title = "habitat_install Resource" +draft = false +robots = "" + +data_path = ["infra","resources","habitat_install"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "habitat_install" + identifier = "resources/bundled/habitat_install" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/habitat_package.md b/content/resources/bundled/habitat_package.md new file mode 100644 index 0000000..60a8a5a --- /dev/null +++ b/content/resources/bundled/habitat_package.md @@ -0,0 +1,19 @@ ++++ +title = "habitat_package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","habitat_package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "habitat_package" + identifier = "resources/bundled/habitat_package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/habitat_service.md b/content/resources/bundled/habitat_service.md new file mode 100644 index 0000000..cfa4b55 --- /dev/null +++ b/content/resources/bundled/habitat_service.md @@ -0,0 +1,19 @@ ++++ +title = "habitat_service Resource" +draft = false +robots = "" + +data_path = ["infra","resources","habitat_service"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "habitat_service" + identifier = "resources/bundled/habitat_service" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/habitat_sup.md b/content/resources/bundled/habitat_sup.md new file mode 100644 index 0000000..3336404 --- /dev/null +++ b/content/resources/bundled/habitat_sup.md @@ -0,0 +1,19 @@ ++++ +title = "habitat_sup Resource" +draft = false +robots = "" + +data_path = ["infra","resources","habitat_sup"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "habitat_sup" + identifier = "resources/bundled/habitat_sup" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/habitat_user_toml.md b/content/resources/bundled/habitat_user_toml.md new file mode 100644 index 0000000..367c10a --- /dev/null +++ b/content/resources/bundled/habitat_user_toml.md @@ -0,0 +1,19 @@ ++++ +title = "habitat_user_toml Resource" +draft = false +robots = "" + +data_path = ["infra","resources","habitat_user_toml"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "habitat_user_toml" + identifier = "resources/bundled/habitat_user_toml" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/homebrew_cask.md b/content/resources/bundled/homebrew_cask.md new file mode 100644 index 0000000..8575cc9 --- /dev/null +++ b/content/resources/bundled/homebrew_cask.md @@ -0,0 +1,19 @@ ++++ +title = "homebrew_cask Resource" +draft = false +robots = "" + +data_path = ["infra","resources","homebrew_cask"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "homebrew_cask" + identifier = "resources/bundled/homebrew_cask" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/homebrew_package.md b/content/resources/bundled/homebrew_package.md new file mode 100644 index 0000000..81ec673 --- /dev/null +++ b/content/resources/bundled/homebrew_package.md @@ -0,0 +1,19 @@ ++++ +title = "homebrew_package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","homebrew_package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "homebrew_package" + identifier = "resources/bundled/homebrew_package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/homebrew_tap.md b/content/resources/bundled/homebrew_tap.md new file mode 100644 index 0000000..0f6c7be --- /dev/null +++ b/content/resources/bundled/homebrew_tap.md @@ -0,0 +1,19 @@ ++++ +title = "homebrew_tap Resource" +draft = false +robots = "" + +data_path = ["infra","resources","homebrew_tap"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "homebrew_tap" + identifier = "resources/bundled/homebrew_tap" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/homebrew_update.md b/content/resources/bundled/homebrew_update.md new file mode 100644 index 0000000..71daec9 --- /dev/null +++ b/content/resources/bundled/homebrew_update.md @@ -0,0 +1,19 @@ ++++ +title = "homebrew_update Resource" +draft = false +robots = "" + +data_path = ["infra","resources","homebrew_update"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "homebrew_update" + identifier = "resources/bundled/homebrew_update" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/hostname.md b/content/resources/bundled/hostname.md new file mode 100644 index 0000000..5998ef5 --- /dev/null +++ b/content/resources/bundled/hostname.md @@ -0,0 +1,19 @@ ++++ +title = "hostname Resource" +draft = false +robots = "" + +data_path = ["infra","resources","hostname"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "hostname" + identifier = "resources/bundled/hostname" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/http_request.md b/content/resources/bundled/http_request.md new file mode 100644 index 0000000..4f11ac2 --- /dev/null +++ b/content/resources/bundled/http_request.md @@ -0,0 +1,19 @@ ++++ +title = "http_request Resource" +draft = false +robots = "" + +data_path = ["infra","resources","http_request"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "http_request" + identifier = "resources/bundled/http_request" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/ifconfig.md b/content/resources/bundled/ifconfig.md new file mode 100644 index 0000000..58cf993 --- /dev/null +++ b/content/resources/bundled/ifconfig.md @@ -0,0 +1,19 @@ ++++ +title = "ifconfig Resource" +draft = false +robots = "" + +data_path = ["infra","resources","ifconfig"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "ifconfig" + identifier = "resources/bundled/ifconfig" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/inspec_input.md b/content/resources/bundled/inspec_input.md new file mode 100644 index 0000000..a2a27dc --- /dev/null +++ b/content/resources/bundled/inspec_input.md @@ -0,0 +1,19 @@ ++++ +title = "inspec_input Resource" +draft = false +robots = "" + +data_path = ["infra","resources","inspec_input"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "inspec_input" + identifier = "resources/bundled/inspec_input" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/inspec_waiver.md b/content/resources/bundled/inspec_waiver.md new file mode 100644 index 0000000..6ed05c5 --- /dev/null +++ b/content/resources/bundled/inspec_waiver.md @@ -0,0 +1,19 @@ ++++ +title = "inspec_waiver Resource" +draft = false +robots = "" + +data_path = ["infra","resources","inspec_waiver"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "inspec_waiver" + identifier = "resources/bundled/inspec_waiver" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/inspec_waiver_file_entry.md b/content/resources/bundled/inspec_waiver_file_entry.md new file mode 100644 index 0000000..9e828eb --- /dev/null +++ b/content/resources/bundled/inspec_waiver_file_entry.md @@ -0,0 +1,19 @@ ++++ +title = "inspec_waiver_file_entry Resource" +draft = false +robots = "" + +data_path = ["infra","resources","inspec_waiver_file_entry"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "inspec_waiver_file_entry" + identifier = "resources/bundled/inspec_waiver_file_entry" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/ips_package.md b/content/resources/bundled/ips_package.md new file mode 100644 index 0000000..7f99070 --- /dev/null +++ b/content/resources/bundled/ips_package.md @@ -0,0 +1,19 @@ ++++ +title = "ips_package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","ips_package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "ips_package" + identifier = "resources/bundled/ips_package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/kernel_module.md b/content/resources/bundled/kernel_module.md new file mode 100644 index 0000000..6016fb5 --- /dev/null +++ b/content/resources/bundled/kernel_module.md @@ -0,0 +1,19 @@ ++++ +title = "kernel_module Resource" +draft = false +robots = "" + +data_path = ["infra","resources","kernel_module"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "kernel_module" + identifier = "resources/bundled/kernel_module" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/ksh.md b/content/resources/bundled/ksh.md new file mode 100644 index 0000000..4c83422 --- /dev/null +++ b/content/resources/bundled/ksh.md @@ -0,0 +1,19 @@ ++++ +title = "ksh Resource" +draft = false +robots = "" + +data_path = ["infra","resources","ksh"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "ksh" + identifier = "resources/bundled/ksh" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/launchd.md b/content/resources/bundled/launchd.md new file mode 100644 index 0000000..363e949 --- /dev/null +++ b/content/resources/bundled/launchd.md @@ -0,0 +1,19 @@ ++++ +title = "launchd Resource" +draft = false +robots = "" + +data_path = ["infra","resources","launchd"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "launchd" + identifier = "resources/bundled/launchd" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/link.md b/content/resources/bundled/link.md new file mode 100644 index 0000000..35fafa6 --- /dev/null +++ b/content/resources/bundled/link.md @@ -0,0 +1,19 @@ ++++ +title = "link Resource" +draft = false +robots = "" + +data_path = ["infra","resources","link"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "link" + identifier = "resources/bundled/link" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/locale.md b/content/resources/bundled/locale.md new file mode 100644 index 0000000..d6f212b --- /dev/null +++ b/content/resources/bundled/locale.md @@ -0,0 +1,19 @@ ++++ +title = "locale Resource" +draft = false +robots = "" + +data_path = ["infra","resources","locale"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "locale" + identifier = "resources/bundled/locale" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/log.md b/content/resources/bundled/log.md new file mode 100644 index 0000000..2c39485 --- /dev/null +++ b/content/resources/bundled/log.md @@ -0,0 +1,19 @@ ++++ +title = "log Resource" +draft = false +robots = "" + +data_path = ["infra","resources","log"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "log" + identifier = "resources/bundled/log" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/macos_userdefaults.md b/content/resources/bundled/macos_userdefaults.md new file mode 100644 index 0000000..44e04cb --- /dev/null +++ b/content/resources/bundled/macos_userdefaults.md @@ -0,0 +1,19 @@ ++++ +title = "macos_userdefaults Resource" +draft = false +robots = "" + +data_path = ["infra","resources","macos_userdefaults"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "macos_userdefaults" + identifier = "resources/bundled/macos_userdefaults" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/macosx_service.md b/content/resources/bundled/macosx_service.md new file mode 100644 index 0000000..67fe055 --- /dev/null +++ b/content/resources/bundled/macosx_service.md @@ -0,0 +1,19 @@ ++++ +title = "macosx_service Resource" +draft = false +robots = "" + +data_path = ["infra","resources","macosx_service"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "macosx_service" + identifier = "resources/bundled/macosx_service" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/macports_package.md b/content/resources/bundled/macports_package.md new file mode 100644 index 0000000..8348499 --- /dev/null +++ b/content/resources/bundled/macports_package.md @@ -0,0 +1,19 @@ ++++ +title = "macports_package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","macports_package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "macports_package" + identifier = "resources/bundled/macports_package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/mdadm.md b/content/resources/bundled/mdadm.md new file mode 100644 index 0000000..82e1a58 --- /dev/null +++ b/content/resources/bundled/mdadm.md @@ -0,0 +1,19 @@ ++++ +title = "mdadm Resource" +draft = false +robots = "" + +data_path = ["infra","resources","mdadm"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "mdadm" + identifier = "resources/bundled/mdadm" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/mount.md b/content/resources/bundled/mount.md new file mode 100644 index 0000000..fa7c17d --- /dev/null +++ b/content/resources/bundled/mount.md @@ -0,0 +1,19 @@ ++++ +title = "mount Resource" +draft = false +robots = "" + +data_path = ["infra","resources","mount"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "mount" + identifier = "resources/bundled/mount" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/msu_package.md b/content/resources/bundled/msu_package.md new file mode 100644 index 0000000..2cb5afe --- /dev/null +++ b/content/resources/bundled/msu_package.md @@ -0,0 +1,19 @@ ++++ +title = "msu_package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","msu_package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "msu_package" + identifier = "resources/bundled/msu_package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/notify_group.md b/content/resources/bundled/notify_group.md new file mode 100644 index 0000000..d33b4a8 --- /dev/null +++ b/content/resources/bundled/notify_group.md @@ -0,0 +1,19 @@ ++++ +title = "notify_group Resource" +draft = false +robots = "" + +data_path = ["infra","resources","notify_group"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "notify_group" + identifier = "resources/bundled/notify_group" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/ohai.md b/content/resources/bundled/ohai.md new file mode 100644 index 0000000..ea86644 --- /dev/null +++ b/content/resources/bundled/ohai.md @@ -0,0 +1,19 @@ ++++ +title = "ohai Resource" +draft = false +robots = "" + +data_path = ["infra","resources","ohai"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "ohai" + identifier = "resources/bundled/ohai" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/ohai_hint.md b/content/resources/bundled/ohai_hint.md new file mode 100644 index 0000000..e627efb --- /dev/null +++ b/content/resources/bundled/ohai_hint.md @@ -0,0 +1,19 @@ ++++ +title = "ohai_hint Resource" +draft = false +robots = "" + +data_path = ["infra","resources","ohai_hint"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "ohai_hint" + identifier = "resources/bundled/ohai_hint" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/openbsd_package.md b/content/resources/bundled/openbsd_package.md new file mode 100644 index 0000000..cd1fc18 --- /dev/null +++ b/content/resources/bundled/openbsd_package.md @@ -0,0 +1,19 @@ ++++ +title = "openbsd_package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","openbsd_package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "openbsd_package" + identifier = "resources/bundled/openbsd_package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/openssl_dhparam.md b/content/resources/bundled/openssl_dhparam.md new file mode 100644 index 0000000..a66c33c --- /dev/null +++ b/content/resources/bundled/openssl_dhparam.md @@ -0,0 +1,19 @@ ++++ +title = "openssl_dhparam Resource" +draft = false +robots = "" + +data_path = ["infra","resources","openssl_dhparam"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "openssl_dhparam" + identifier = "resources/bundled/openssl_dhparam" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/openssl_ec_private_key.md b/content/resources/bundled/openssl_ec_private_key.md new file mode 100644 index 0000000..2e7018a --- /dev/null +++ b/content/resources/bundled/openssl_ec_private_key.md @@ -0,0 +1,19 @@ ++++ +title = "openssl_ec_private_key Resource" +draft = false +robots = "" + +data_path = ["infra","resources","openssl_ec_private_key"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "openssl_ec_private_key" + identifier = "resources/bundled/openssl_ec_private_key" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/openssl_ec_public_key.md b/content/resources/bundled/openssl_ec_public_key.md new file mode 100644 index 0000000..72d98a9 --- /dev/null +++ b/content/resources/bundled/openssl_ec_public_key.md @@ -0,0 +1,19 @@ ++++ +title = "openssl_ec_public_key Resource" +draft = false +robots = "" + +data_path = ["infra","resources","openssl_ec_public_key"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "openssl_ec_public_key" + identifier = "resources/bundled/openssl_ec_public_key" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/openssl_rsa_private_key.md b/content/resources/bundled/openssl_rsa_private_key.md new file mode 100644 index 0000000..d1a74a4 --- /dev/null +++ b/content/resources/bundled/openssl_rsa_private_key.md @@ -0,0 +1,19 @@ ++++ +title = "openssl_rsa_private_key Resource" +draft = false +robots = "" + +data_path = ["infra","resources","openssl_rsa_private_key"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "openssl_rsa_private_key" + identifier = "resources/bundled/openssl_rsa_private_key" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/openssl_rsa_public_key.md b/content/resources/bundled/openssl_rsa_public_key.md new file mode 100644 index 0000000..ad76df6 --- /dev/null +++ b/content/resources/bundled/openssl_rsa_public_key.md @@ -0,0 +1,19 @@ ++++ +title = "openssl_rsa_public_key Resource" +draft = false +robots = "" + +data_path = ["infra","resources","openssl_rsa_public_key"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "openssl_rsa_public_key" + identifier = "resources/bundled/openssl_rsa_public_key" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/openssl_x509_certificate.md b/content/resources/bundled/openssl_x509_certificate.md new file mode 100644 index 0000000..6aaed54 --- /dev/null +++ b/content/resources/bundled/openssl_x509_certificate.md @@ -0,0 +1,19 @@ ++++ +title = "openssl_x509_certificate Resource" +draft = false +robots = "" + +data_path = ["infra","resources","openssl_x509_certificate"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "openssl_x509_certificate" + identifier = "resources/bundled/openssl_x509_certificate" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/openssl_x509_crl.md b/content/resources/bundled/openssl_x509_crl.md new file mode 100644 index 0000000..1c3d776 --- /dev/null +++ b/content/resources/bundled/openssl_x509_crl.md @@ -0,0 +1,19 @@ ++++ +title = "openssl_x509_crl Resource" +draft = false +robots = "" + +data_path = ["infra","resources","openssl_x509_crl"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "openssl_x509_crl" + identifier = "resources/bundled/openssl_x509_crl" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/openssl_x509_request.md b/content/resources/bundled/openssl_x509_request.md new file mode 100644 index 0000000..5f687d0 --- /dev/null +++ b/content/resources/bundled/openssl_x509_request.md @@ -0,0 +1,19 @@ ++++ +title = "openssl_x509_request Resource" +draft = false +robots = "" + +data_path = ["infra","resources","openssl_x509_request"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "openssl_x509_request" + identifier = "resources/bundled/openssl_x509_request" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/osx_profile.md b/content/resources/bundled/osx_profile.md new file mode 100644 index 0000000..0b2a946 --- /dev/null +++ b/content/resources/bundled/osx_profile.md @@ -0,0 +1,19 @@ ++++ +title = "osx_profile Resource" +draft = false +robots = "" + +data_path = ["infra","resources","osx_profile"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "osx_profile" + identifier = "resources/bundled/osx_profile" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/package.md b/content/resources/bundled/package.md new file mode 100644 index 0000000..27217a2 --- /dev/null +++ b/content/resources/bundled/package.md @@ -0,0 +1,19 @@ ++++ +title = "package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "package" + identifier = "resources/bundled/package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/pacman_package.md b/content/resources/bundled/pacman_package.md new file mode 100644 index 0000000..7c4718f --- /dev/null +++ b/content/resources/bundled/pacman_package.md @@ -0,0 +1,19 @@ ++++ +title = "pacman_package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","pacman_package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "pacman_package" + identifier = "resources/bundled/pacman_package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/paludis_package.md b/content/resources/bundled/paludis_package.md new file mode 100644 index 0000000..67042c6 --- /dev/null +++ b/content/resources/bundled/paludis_package.md @@ -0,0 +1,19 @@ ++++ +title = "paludis_package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","paludis_package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "paludis_package" + identifier = "resources/bundled/paludis_package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/perl.md b/content/resources/bundled/perl.md new file mode 100644 index 0000000..51a0c35 --- /dev/null +++ b/content/resources/bundled/perl.md @@ -0,0 +1,19 @@ ++++ +title = "perl Resource" +draft = false +robots = "" + +data_path = ["infra","resources","perl"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "perl" + identifier = "resources/bundled/perl" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/plist.md b/content/resources/bundled/plist.md new file mode 100644 index 0000000..0b8219d --- /dev/null +++ b/content/resources/bundled/plist.md @@ -0,0 +1,19 @@ ++++ +title = "plist Resource" +draft = false +robots = "" + +data_path = ["infra","resources","plist"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "plist" + identifier = "resources/bundled/plist" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/portage_package.md b/content/resources/bundled/portage_package.md new file mode 100644 index 0000000..0787de9 --- /dev/null +++ b/content/resources/bundled/portage_package.md @@ -0,0 +1,19 @@ ++++ +title = "portage_package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","portage_package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "portage_package" + identifier = "resources/bundled/portage_package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/powershell_package.md b/content/resources/bundled/powershell_package.md new file mode 100644 index 0000000..e52e254 --- /dev/null +++ b/content/resources/bundled/powershell_package.md @@ -0,0 +1,19 @@ ++++ +title = "powershell_package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","powershell_package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "powershell_package" + identifier = "resources/bundled/powershell_package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/powershell_package_source.md b/content/resources/bundled/powershell_package_source.md new file mode 100644 index 0000000..d5144f5 --- /dev/null +++ b/content/resources/bundled/powershell_package_source.md @@ -0,0 +1,19 @@ ++++ +title = "powershell_package_source Resource" +draft = false +robots = "" + +data_path = ["infra","resources","powershell_package_source"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "powershell_package_source" + identifier = "resources/bundled/powershell_package_source" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/powershell_script.md b/content/resources/bundled/powershell_script.md new file mode 100644 index 0000000..ba1be0c --- /dev/null +++ b/content/resources/bundled/powershell_script.md @@ -0,0 +1,19 @@ ++++ +title = "powershell_script Resource" +draft = false +robots = "" + +data_path = ["infra","resources","powershell_script"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "powershell_script" + identifier = "resources/bundled/powershell_script" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/python.md b/content/resources/bundled/python.md new file mode 100644 index 0000000..729da3b --- /dev/null +++ b/content/resources/bundled/python.md @@ -0,0 +1,19 @@ ++++ +title = "python Resource" +draft = false +robots = "" + +data_path = ["infra","resources","python"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "python" + identifier = "resources/bundled/python" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/reboot.md b/content/resources/bundled/reboot.md new file mode 100644 index 0000000..414de7d --- /dev/null +++ b/content/resources/bundled/reboot.md @@ -0,0 +1,19 @@ ++++ +title = "reboot Resource" +draft = false +robots = "" + +data_path = ["infra","resources","reboot"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "reboot" + identifier = "resources/bundled/reboot" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/registry_key.md b/content/resources/bundled/registry_key.md new file mode 100644 index 0000000..bf7b020 --- /dev/null +++ b/content/resources/bundled/registry_key.md @@ -0,0 +1,19 @@ ++++ +title = "registry_key Resource" +draft = false +robots = "" + +data_path = ["infra","resources","registry_key"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "registry_key" + identifier = "resources/bundled/registry_key" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/remote_directory.md b/content/resources/bundled/remote_directory.md new file mode 100644 index 0000000..34453ec --- /dev/null +++ b/content/resources/bundled/remote_directory.md @@ -0,0 +1,19 @@ ++++ +title = "remote_directory Resource" +draft = false +robots = "" + +data_path = ["infra","resources","remote_directory"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "remote_directory" + identifier = "resources/bundled/remote_directory" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/remote_file.md b/content/resources/bundled/remote_file.md new file mode 100644 index 0000000..5d14160 --- /dev/null +++ b/content/resources/bundled/remote_file.md @@ -0,0 +1,19 @@ ++++ +title = "remote_file Resource" +draft = false +robots = "" + +data_path = ["infra","resources","remote_file"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "remote_file" + identifier = "resources/bundled/remote_file" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/rhsm_errata.md b/content/resources/bundled/rhsm_errata.md new file mode 100644 index 0000000..31148ea --- /dev/null +++ b/content/resources/bundled/rhsm_errata.md @@ -0,0 +1,19 @@ ++++ +title = "rhsm_errata Resource" +draft = false +robots = "" + +data_path = ["infra","resources","rhsm_errata"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "rhsm_errata" + identifier = "resources/bundled/rhsm_errata" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/rhsm_errata_level.md b/content/resources/bundled/rhsm_errata_level.md new file mode 100644 index 0000000..4856eaf --- /dev/null +++ b/content/resources/bundled/rhsm_errata_level.md @@ -0,0 +1,19 @@ ++++ +title = "rhsm_errata_level Resource" +draft = false +robots = "" + +data_path = ["infra","resources","rhsm_errata_level"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "rhsm_errata_level" + identifier = "resources/bundled/rhsm_errata_level" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/rhsm_register.md b/content/resources/bundled/rhsm_register.md new file mode 100644 index 0000000..9fba380 --- /dev/null +++ b/content/resources/bundled/rhsm_register.md @@ -0,0 +1,19 @@ ++++ +title = "rhsm_register Resource" +draft = false +robots = "" + +data_path = ["infra","resources","rhsm_register"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "rhsm_register" + identifier = "resources/bundled/rhsm_register" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/rhsm_repo.md b/content/resources/bundled/rhsm_repo.md new file mode 100644 index 0000000..2afbdd2 --- /dev/null +++ b/content/resources/bundled/rhsm_repo.md @@ -0,0 +1,19 @@ ++++ +title = "rhsm_repo Resource" +draft = false +robots = "" + +data_path = ["infra","resources","rhsm_repo"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "rhsm_repo" + identifier = "resources/bundled/rhsm_repo" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/rhsm_subscription.md b/content/resources/bundled/rhsm_subscription.md new file mode 100644 index 0000000..e2b01cc --- /dev/null +++ b/content/resources/bundled/rhsm_subscription.md @@ -0,0 +1,19 @@ ++++ +title = "rhsm_subscription Resource" +draft = false +robots = "" + +data_path = ["infra","resources","rhsm_subscription"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "rhsm_subscription" + identifier = "resources/bundled/rhsm_subscription" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/route.md b/content/resources/bundled/route.md new file mode 100644 index 0000000..d7c9f68 --- /dev/null +++ b/content/resources/bundled/route.md @@ -0,0 +1,19 @@ ++++ +title = "route Resource" +draft = false +robots = "" + +data_path = ["infra","resources","route"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "route" + identifier = "resources/bundled/route" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/rpm_package.md b/content/resources/bundled/rpm_package.md new file mode 100644 index 0000000..ad95e62 --- /dev/null +++ b/content/resources/bundled/rpm_package.md @@ -0,0 +1,19 @@ ++++ +title = "rpm_package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","rpm_package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "rpm_package" + identifier = "resources/bundled/rpm_package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/ruby.md b/content/resources/bundled/ruby.md new file mode 100644 index 0000000..b4d58de --- /dev/null +++ b/content/resources/bundled/ruby.md @@ -0,0 +1,19 @@ ++++ +title = "ruby Resource" +draft = false +robots = "" + +data_path = ["infra","resources","ruby"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "ruby" + identifier = "resources/bundled/ruby" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/ruby_block.md b/content/resources/bundled/ruby_block.md new file mode 100644 index 0000000..a1b7e3a --- /dev/null +++ b/content/resources/bundled/ruby_block.md @@ -0,0 +1,19 @@ ++++ +title = "ruby_block Resource" +draft = false +robots = "" + +data_path = ["infra","resources","ruby_block"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "ruby_block" + identifier = "resources/bundled/ruby_block" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/script.md b/content/resources/bundled/script.md new file mode 100644 index 0000000..d9ffc3c --- /dev/null +++ b/content/resources/bundled/script.md @@ -0,0 +1,19 @@ ++++ +title = "script Resource" +draft = false +robots = "" + +data_path = ["infra","resources","script"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "script" + identifier = "resources/bundled/script" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/selinux_boolean.md b/content/resources/bundled/selinux_boolean.md new file mode 100644 index 0000000..3104887 --- /dev/null +++ b/content/resources/bundled/selinux_boolean.md @@ -0,0 +1,19 @@ ++++ +title = "selinux_boolean Resource" +draft = false +robots = "" + +data_path = ["infra","resources","selinux_boolean"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "selinux_boolean" + identifier = "resources/bundled/selinux_boolean" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/selinux_fcontext.md b/content/resources/bundled/selinux_fcontext.md new file mode 100644 index 0000000..fde07db --- /dev/null +++ b/content/resources/bundled/selinux_fcontext.md @@ -0,0 +1,19 @@ ++++ +title = "selinux_fcontext Resource" +draft = false +robots = "" + +data_path = ["infra","resources","selinux_fcontext"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "selinux_fcontext" + identifier = "resources/bundled/selinux_fcontext" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/selinux_install.md b/content/resources/bundled/selinux_install.md new file mode 100644 index 0000000..980b55a --- /dev/null +++ b/content/resources/bundled/selinux_install.md @@ -0,0 +1,19 @@ ++++ +title = "selinux_install Resource" +draft = false +robots = "" + +data_path = ["infra","resources","selinux_install"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "selinux_install" + identifier = "resources/bundled/selinux_install" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/selinux_login.md b/content/resources/bundled/selinux_login.md new file mode 100644 index 0000000..436a09f --- /dev/null +++ b/content/resources/bundled/selinux_login.md @@ -0,0 +1,19 @@ ++++ +title = "selinux_login Resource" +draft = false +robots = "" + +data_path = ["infra","resources","selinux_login"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "selinux_login" + identifier = "resources/bundled/selinux_login" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/selinux_module.md b/content/resources/bundled/selinux_module.md new file mode 100644 index 0000000..4184bcf --- /dev/null +++ b/content/resources/bundled/selinux_module.md @@ -0,0 +1,19 @@ ++++ +title = "selinux_module Resource" +draft = false +robots = "" + +data_path = ["infra","resources","selinux_module"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "selinux_module" + identifier = "resources/bundled/selinux_module" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/selinux_permissive.md b/content/resources/bundled/selinux_permissive.md new file mode 100644 index 0000000..52de641 --- /dev/null +++ b/content/resources/bundled/selinux_permissive.md @@ -0,0 +1,19 @@ ++++ +title = "selinux_permissive Resource" +draft = false +robots = "" + +data_path = ["infra","resources","selinux_permissive"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "selinux_permissive" + identifier = "resources/bundled/selinux_permissive" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/selinux_port.md b/content/resources/bundled/selinux_port.md new file mode 100644 index 0000000..20bcc37 --- /dev/null +++ b/content/resources/bundled/selinux_port.md @@ -0,0 +1,19 @@ ++++ +title = "selinux_port Resource" +draft = false +robots = "" + +data_path = ["infra","resources","selinux_port"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "selinux_port" + identifier = "resources/bundled/selinux_port" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/selinux_state.md b/content/resources/bundled/selinux_state.md new file mode 100644 index 0000000..7cd8834 --- /dev/null +++ b/content/resources/bundled/selinux_state.md @@ -0,0 +1,19 @@ ++++ +title = "selinux_state Resource" +draft = false +robots = "" + +data_path = ["infra","resources","selinux_state"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "selinux_state" + identifier = "resources/bundled/selinux_state" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/selinux_user.md b/content/resources/bundled/selinux_user.md new file mode 100644 index 0000000..d172d56 --- /dev/null +++ b/content/resources/bundled/selinux_user.md @@ -0,0 +1,19 @@ ++++ +title = "selinux_user Resource" +draft = false +robots = "" + +data_path = ["infra","resources","selinux_user"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "selinux_user" + identifier = "resources/bundled/selinux_user" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/service.md b/content/resources/bundled/service.md new file mode 100644 index 0000000..73691f4 --- /dev/null +++ b/content/resources/bundled/service.md @@ -0,0 +1,19 @@ ++++ +title = "service Resource" +draft = false +robots = "" + +data_path = ["infra","resources","service"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "service" + identifier = "resources/bundled/service" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/smartos_package.md b/content/resources/bundled/smartos_package.md new file mode 100644 index 0000000..f9a6bbb --- /dev/null +++ b/content/resources/bundled/smartos_package.md @@ -0,0 +1,19 @@ ++++ +title = "smartos_package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","smartos_package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "smartos_package" + identifier = "resources/bundled/smartos_package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/snap_package.md b/content/resources/bundled/snap_package.md new file mode 100644 index 0000000..7a2f0fe --- /dev/null +++ b/content/resources/bundled/snap_package.md @@ -0,0 +1,19 @@ ++++ +title = "snap_package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","snap_package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "snap_package" + identifier = "resources/bundled/snap_package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/solaris_package.md b/content/resources/bundled/solaris_package.md new file mode 100644 index 0000000..1dfe53e --- /dev/null +++ b/content/resources/bundled/solaris_package.md @@ -0,0 +1,19 @@ ++++ +title = "solaris_package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","solaris_package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "solaris_package" + identifier = "resources/bundled/solaris_package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/ssh_known_hosts_entry.md b/content/resources/bundled/ssh_known_hosts_entry.md new file mode 100644 index 0000000..5fe561a --- /dev/null +++ b/content/resources/bundled/ssh_known_hosts_entry.md @@ -0,0 +1,19 @@ ++++ +title = "ssh_known_hosts_entry Resource" +draft = false +robots = "" + +data_path = ["infra","resources","ssh_known_hosts_entry"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "ssh_known_hosts_entry" + identifier = "resources/bundled/ssh_known_hosts_entry" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/subversion.md b/content/resources/bundled/subversion.md new file mode 100644 index 0000000..8fb96ad --- /dev/null +++ b/content/resources/bundled/subversion.md @@ -0,0 +1,19 @@ ++++ +title = "subversion Resource" +draft = false +robots = "" + +data_path = ["infra","resources","subversion"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "subversion" + identifier = "resources/bundled/subversion" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/sudo.md b/content/resources/bundled/sudo.md new file mode 100644 index 0000000..95442ce --- /dev/null +++ b/content/resources/bundled/sudo.md @@ -0,0 +1,19 @@ ++++ +title = "sudo Resource" +draft = false +robots = "" + +data_path = ["infra","resources","sudo"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "sudo" + identifier = "resources/bundled/sudo" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/swap_file.md b/content/resources/bundled/swap_file.md new file mode 100644 index 0000000..4d3e917 --- /dev/null +++ b/content/resources/bundled/swap_file.md @@ -0,0 +1,19 @@ ++++ +title = "swap_file Resource" +draft = false +robots = "" + +data_path = ["infra","resources","swap_file"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "swap_file" + identifier = "resources/bundled/swap_file" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/sysctl.md b/content/resources/bundled/sysctl.md new file mode 100644 index 0000000..d71c100 --- /dev/null +++ b/content/resources/bundled/sysctl.md @@ -0,0 +1,19 @@ ++++ +title = "sysctl Resource" +draft = false +robots = "" + +data_path = ["infra","resources","sysctl"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "sysctl" + identifier = "resources/bundled/sysctl" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/systemd_unit.md b/content/resources/bundled/systemd_unit.md new file mode 100644 index 0000000..e3074f5 --- /dev/null +++ b/content/resources/bundled/systemd_unit.md @@ -0,0 +1,19 @@ ++++ +title = "systemd_unit Resource" +draft = false +robots = "" + +data_path = ["infra","resources","systemd_unit"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "systemd_unit" + identifier = "resources/bundled/systemd_unit" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/template.md b/content/resources/bundled/template.md new file mode 100644 index 0000000..677fd86 --- /dev/null +++ b/content/resources/bundled/template.md @@ -0,0 +1,19 @@ ++++ +title = "template Resource" +draft = false +robots = "" + +data_path = ["infra","resources","template"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "template" + identifier = "resources/bundled/template" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/timezone.md b/content/resources/bundled/timezone.md new file mode 100644 index 0000000..1b067b7 --- /dev/null +++ b/content/resources/bundled/timezone.md @@ -0,0 +1,19 @@ ++++ +title = "timezone Resource" +draft = false +robots = "" + +data_path = ["infra","resources","timezone"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "timezone" + identifier = "resources/bundled/timezone" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/user.md b/content/resources/bundled/user.md new file mode 100644 index 0000000..f7e6091 --- /dev/null +++ b/content/resources/bundled/user.md @@ -0,0 +1,19 @@ ++++ +title = "user Resource" +draft = false +robots = "" + +data_path = ["infra","resources","user"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "user" + identifier = "resources/bundled/user" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/user_ulimit.md b/content/resources/bundled/user_ulimit.md new file mode 100644 index 0000000..d17f828 --- /dev/null +++ b/content/resources/bundled/user_ulimit.md @@ -0,0 +1,19 @@ ++++ +title = "user_ulimit Resource" +draft = false +robots = "" + +data_path = ["infra","resources","user_ulimit"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "user_ulimit" + identifier = "resources/bundled/user_ulimit" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_ad_join.md b/content/resources/bundled/windows_ad_join.md new file mode 100644 index 0000000..955adbd --- /dev/null +++ b/content/resources/bundled/windows_ad_join.md @@ -0,0 +1,19 @@ ++++ +title = "windows_ad_join Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_ad_join"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_ad_join" + identifier = "resources/bundled/windows_ad_join" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_audit_policy.md b/content/resources/bundled/windows_audit_policy.md new file mode 100644 index 0000000..477bcc0 --- /dev/null +++ b/content/resources/bundled/windows_audit_policy.md @@ -0,0 +1,19 @@ ++++ +title = "windows_audit_policy Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_audit_policy"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_audit_policy" + identifier = "resources/bundled/windows_audit_policy" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_auto_run.md b/content/resources/bundled/windows_auto_run.md new file mode 100644 index 0000000..aced901 --- /dev/null +++ b/content/resources/bundled/windows_auto_run.md @@ -0,0 +1,19 @@ ++++ +title = "windows_auto_run Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_auto_run"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_auto_run" + identifier = "resources/bundled/windows_auto_run" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_certificate.md b/content/resources/bundled/windows_certificate.md new file mode 100644 index 0000000..b793e76 --- /dev/null +++ b/content/resources/bundled/windows_certificate.md @@ -0,0 +1,19 @@ ++++ +title = "windows_certificate Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_certificate"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_certificate" + identifier = "resources/bundled/windows_certificate" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_defender.md b/content/resources/bundled/windows_defender.md new file mode 100644 index 0000000..b91173e --- /dev/null +++ b/content/resources/bundled/windows_defender.md @@ -0,0 +1,19 @@ ++++ +title = "windows_defender Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_defender"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_defender" + identifier = "resources/bundled/windows_defender" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_defender_exclusion.md b/content/resources/bundled/windows_defender_exclusion.md new file mode 100644 index 0000000..563f3e9 --- /dev/null +++ b/content/resources/bundled/windows_defender_exclusion.md @@ -0,0 +1,19 @@ ++++ +title = "windows_defender_exclusion Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_defender_exclusion"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_defender_exclusion" + identifier = "resources/bundled/windows_defender_exclusion" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_dfs_folder.md b/content/resources/bundled/windows_dfs_folder.md new file mode 100644 index 0000000..6ae564a --- /dev/null +++ b/content/resources/bundled/windows_dfs_folder.md @@ -0,0 +1,19 @@ ++++ +title = "windows_dfs_folder Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_dfs_folder"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_dfs_folder" + identifier = "resources/bundled/windows_dfs_folder" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_dfs_namespace.md b/content/resources/bundled/windows_dfs_namespace.md new file mode 100644 index 0000000..95f8944 --- /dev/null +++ b/content/resources/bundled/windows_dfs_namespace.md @@ -0,0 +1,19 @@ ++++ +title = "windows_dfs_namespace Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_dfs_namespace"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_dfs_namespace" + identifier = "resources/bundled/windows_dfs_namespace" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_dfs_server.md b/content/resources/bundled/windows_dfs_server.md new file mode 100644 index 0000000..f7987cc --- /dev/null +++ b/content/resources/bundled/windows_dfs_server.md @@ -0,0 +1,19 @@ ++++ +title = "windows_dfs_server Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_dfs_server"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_dfs_server" + identifier = "resources/bundled/windows_dfs_server" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_dns_record.md b/content/resources/bundled/windows_dns_record.md new file mode 100644 index 0000000..abf4bba --- /dev/null +++ b/content/resources/bundled/windows_dns_record.md @@ -0,0 +1,19 @@ ++++ +title = "windows_dns_record Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_dns_record"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_dns_record" + identifier = "resources/bundled/windows_dns_record" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_dns_zone.md b/content/resources/bundled/windows_dns_zone.md new file mode 100644 index 0000000..7aa5154 --- /dev/null +++ b/content/resources/bundled/windows_dns_zone.md @@ -0,0 +1,19 @@ ++++ +title = "windows_dns_zone Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_dns_zone"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_dns_zone" + identifier = "resources/bundled/windows_dns_zone" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_env.md b/content/resources/bundled/windows_env.md new file mode 100644 index 0000000..248598b --- /dev/null +++ b/content/resources/bundled/windows_env.md @@ -0,0 +1,19 @@ ++++ +title = "windows_env Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_env"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_env" + identifier = "resources/bundled/windows_env" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_feature.md b/content/resources/bundled/windows_feature.md new file mode 100644 index 0000000..91bfa37 --- /dev/null +++ b/content/resources/bundled/windows_feature.md @@ -0,0 +1,19 @@ ++++ +title = "windows_feature Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_feature"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_feature" + identifier = "resources/bundled/windows_feature" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_feature_dism.md b/content/resources/bundled/windows_feature_dism.md new file mode 100644 index 0000000..14af93f --- /dev/null +++ b/content/resources/bundled/windows_feature_dism.md @@ -0,0 +1,19 @@ ++++ +title = "windows_feature_dism Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_feature_dism"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_feature_dism" + identifier = "resources/bundled/windows_feature_dism" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_feature_powershell.md b/content/resources/bundled/windows_feature_powershell.md new file mode 100644 index 0000000..8bcdef8 --- /dev/null +++ b/content/resources/bundled/windows_feature_powershell.md @@ -0,0 +1,19 @@ ++++ +title = "windows_feature_powershell Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_feature_powershell"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_feature_powershell" + identifier = "resources/bundled/windows_feature_powershell" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_firewall_profile.md b/content/resources/bundled/windows_firewall_profile.md new file mode 100644 index 0000000..af06e53 --- /dev/null +++ b/content/resources/bundled/windows_firewall_profile.md @@ -0,0 +1,19 @@ ++++ +title = "windows_firewall_profile Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_firewall_profile"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_firewall_profile" + identifier = "resources/bundled/windows_firewall_profile" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_firewall_rule.md b/content/resources/bundled/windows_firewall_rule.md new file mode 100644 index 0000000..e481a71 --- /dev/null +++ b/content/resources/bundled/windows_firewall_rule.md @@ -0,0 +1,19 @@ ++++ +title = "windows_firewall_rule Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_firewall_rule"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_firewall_rule" + identifier = "resources/bundled/windows_firewall_rule" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_font.md b/content/resources/bundled/windows_font.md new file mode 100644 index 0000000..3962292 --- /dev/null +++ b/content/resources/bundled/windows_font.md @@ -0,0 +1,19 @@ ++++ +title = "windows_font Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_font"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_font" + identifier = "resources/bundled/windows_font" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_package.md b/content/resources/bundled/windows_package.md new file mode 100644 index 0000000..018e9c3 --- /dev/null +++ b/content/resources/bundled/windows_package.md @@ -0,0 +1,19 @@ ++++ +title = "windows_package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_package" + identifier = "resources/bundled/windows_package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_pagefile.md b/content/resources/bundled/windows_pagefile.md new file mode 100644 index 0000000..c001884 --- /dev/null +++ b/content/resources/bundled/windows_pagefile.md @@ -0,0 +1,19 @@ ++++ +title = "windows_pagefile Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_pagefile"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_pagefile" + identifier = "resources/bundled/windows_pagefile" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_path.md b/content/resources/bundled/windows_path.md new file mode 100644 index 0000000..8e3c17b --- /dev/null +++ b/content/resources/bundled/windows_path.md @@ -0,0 +1,19 @@ ++++ +title = "windows_path Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_path"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_path" + identifier = "resources/bundled/windows_path" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_printer.md b/content/resources/bundled/windows_printer.md new file mode 100644 index 0000000..3c02d5e --- /dev/null +++ b/content/resources/bundled/windows_printer.md @@ -0,0 +1,19 @@ ++++ +title = "windows_printer Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_printer"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_printer" + identifier = "resources/bundled/windows_printer" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_printer_port.md b/content/resources/bundled/windows_printer_port.md new file mode 100644 index 0000000..b23ec51 --- /dev/null +++ b/content/resources/bundled/windows_printer_port.md @@ -0,0 +1,19 @@ ++++ +title = "windows_printer_port Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_printer_port"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_printer_port" + identifier = "resources/bundled/windows_printer_port" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_security_policy.md b/content/resources/bundled/windows_security_policy.md new file mode 100644 index 0000000..559c0d9 --- /dev/null +++ b/content/resources/bundled/windows_security_policy.md @@ -0,0 +1,19 @@ ++++ +title = "windows_security_policy Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_security_policy"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_security_policy" + identifier = "resources/bundled/windows_security_policy" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_service.md b/content/resources/bundled/windows_service.md new file mode 100644 index 0000000..72ef2da --- /dev/null +++ b/content/resources/bundled/windows_service.md @@ -0,0 +1,19 @@ ++++ +title = "windows_service Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_service"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_service" + identifier = "resources/bundled/windows_service" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_share.md b/content/resources/bundled/windows_share.md new file mode 100644 index 0000000..d3bc5a1 --- /dev/null +++ b/content/resources/bundled/windows_share.md @@ -0,0 +1,19 @@ ++++ +title = "windows_share Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_share"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_share" + identifier = "resources/bundled/windows_share" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_shortcut.md b/content/resources/bundled/windows_shortcut.md new file mode 100644 index 0000000..109db42 --- /dev/null +++ b/content/resources/bundled/windows_shortcut.md @@ -0,0 +1,19 @@ ++++ +title = "windows_shortcut Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_shortcut"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_shortcut" + identifier = "resources/bundled/windows_shortcut" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_task.md b/content/resources/bundled/windows_task.md new file mode 100644 index 0000000..c05e66a --- /dev/null +++ b/content/resources/bundled/windows_task.md @@ -0,0 +1,19 @@ ++++ +title = "windows_task Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_task"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_task" + identifier = "resources/bundled/windows_task" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_uac.md b/content/resources/bundled/windows_uac.md new file mode 100644 index 0000000..3ec420f --- /dev/null +++ b/content/resources/bundled/windows_uac.md @@ -0,0 +1,19 @@ ++++ +title = "windows_uac Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_uac"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_uac" + identifier = "resources/bundled/windows_uac" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_update_settings.md b/content/resources/bundled/windows_update_settings.md new file mode 100644 index 0000000..7589656 --- /dev/null +++ b/content/resources/bundled/windows_update_settings.md @@ -0,0 +1,19 @@ ++++ +title = "windows_update_settings Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_update_settings"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_update_settings" + identifier = "resources/bundled/windows_update_settings" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_user_privilege.md b/content/resources/bundled/windows_user_privilege.md new file mode 100644 index 0000000..e47e816 --- /dev/null +++ b/content/resources/bundled/windows_user_privilege.md @@ -0,0 +1,19 @@ ++++ +title = "windows_user_privilege Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_user_privilege"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_user_privilege" + identifier = "resources/bundled/windows_user_privilege" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/windows_workgroup.md b/content/resources/bundled/windows_workgroup.md new file mode 100644 index 0000000..f78bb36 --- /dev/null +++ b/content/resources/bundled/windows_workgroup.md @@ -0,0 +1,19 @@ ++++ +title = "windows_workgroup Resource" +draft = false +robots = "" + +data_path = ["infra","resources","windows_workgroup"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "windows_workgroup" + identifier = "resources/bundled/windows_workgroup" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/yum_package.md b/content/resources/bundled/yum_package.md new file mode 100644 index 0000000..8aaf2ef --- /dev/null +++ b/content/resources/bundled/yum_package.md @@ -0,0 +1,19 @@ ++++ +title = "yum_package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","yum_package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "yum_package" + identifier = "resources/bundled/yum_package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/yum_repository.md b/content/resources/bundled/yum_repository.md new file mode 100644 index 0000000..f0a0326 --- /dev/null +++ b/content/resources/bundled/yum_repository.md @@ -0,0 +1,19 @@ ++++ +title = "yum_repository Resource" +draft = false +robots = "" + +data_path = ["infra","resources","yum_repository"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "yum_repository" + identifier = "resources/bundled/yum_repository" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/zypper_package.md b/content/resources/bundled/zypper_package.md new file mode 100644 index 0000000..6bb68bf --- /dev/null +++ b/content/resources/bundled/zypper_package.md @@ -0,0 +1,19 @@ ++++ +title = "zypper_package Resource" +draft = false +robots = "" + +data_path = ["infra","resources","zypper_package"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "zypper_package" + identifier = "resources/bundled/zypper_package" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/bundled/zypper_repository.md b/content/resources/bundled/zypper_repository.md new file mode 100644 index 0000000..3ce53da --- /dev/null +++ b/content/resources/bundled/zypper_repository.md @@ -0,0 +1,19 @@ ++++ +title = "zypper_repository Resource" +draft = false +robots = "" + +data_path = ["infra","resources","zypper_repository"] +layout = "infra_resource" +toc_layout = "infra_resource_toc" + +[menu] + [menu.resources] + title = "zypper_repository" + identifier = "resources/bundled/zypper_repository" + parent = "resources/bundled" ++++ + + + + diff --git a/content/resources/common_functionality.md b/content/resources/common_functionality.md new file mode 100644 index 0000000..ccf00a0 --- /dev/null +++ b/content/resources/common_functionality.md @@ -0,0 +1,339 @@ ++++ +title = "Common Resource Functionality" +draft = false + +[menu] + [menu.resources] + title = "Common Resource Functionality" + identifier = "resources/resource_common.md Common Resource Functionality" + parent = "resources" + weight = 40 ++++ + + +All resources (including custom resources) share a set of common +actions, properties, conditional executions, notifications, and relative +path options. + +## Actions + +The following actions may be used with any resource: + +`:nothing` + +: {{< readfile file="content/reusable/md/resources_common_actions_nothing.md" >}} + +### Examples + +The following examples show how to use common actions in a recipe. + +**Use the :nothing action** + +{{< readfile file="content/reusable/md/resource_service_use_nothing_action.md" >}} + +## Properties + +{{< readfile file="content/reusable/md/resources_common_properties.md" >}} + +### Examples + +The following examples show how to use common properties in a recipe. + +**Use the ignore_failure common property** + +{{< readfile file="content/reusable/md/resource_package_use_ignore_failure_attribute.md" >}} + +**Use the retries and retry_delay common properties** + +{{< readfile file="content/reusable/md/resource_service_use_retries_properties.md" >}} + +## Guards + +{{< readfile file="content/reusable/md/resources_common_guards.md" >}} + +{{< note >}} + +When using the `not_if` and `only_if` guards with the **execute** +resource, the guard's environment is inherited from the resource's +environment. For example: + +```ruby +execute 'bundle install' do + cwd '/myapp' + not_if 'bundle check' # This is run from /myapp +end +``` + +{{< /note >}} + +### Properties + +{{< readfile file="content/reusable/md/resources_common_guards_properties.md" >}} + +### Arguments + +{{< readfile file="content/reusable/md/resources_common_guards_arguments.md" >}} + +### not_if Examples + +**Update if not already updated** + +The following example shows how to use `not_if` to guard against running +the `apt-get-update` command when a file already exists that's the same +as the updated file: + +```ruby +execute 'apt-get-update' do + command 'apt-get update' + ignore_failure true + not_if { ::File.exist?('/var/lib/apt/periodic/update-success-stamp') } +end +``` + +**Ensure a node can resolve a host** + +The following example shows how to use a custom block of Ruby code to +ensure that a node can resolve the host. If the node can resolve the +host, Chef Infra Client will do nothing. If the node can't resolve the +host, Chef Infra Client will configure the host: + +```ruby +ruby_block 'ensure node can resolve API FQDN' do + block do + fe = Chef::Util::FileEdit.new('/etc/hosts') + fe.insert_line_if_no_match(/#{node['chef-server']['api_fqdn']}/, + "127.0.0.1 #{node['chef-server']['api_fqdn']}") + fe.write_file + end + not_if { Resolv.getaddress(node['chef-server']['api_fqdn']) rescue false } +end +``` + +**Prevent installs on older versions** + +The following example shows how to use `not_if` to prevent ZeroMQ from +being installed when the node on which the install is to occur has a +version of Red Hat Enterprise Linux that's older than version 6.0: + +```ruby +ark 'test_autogen' do + url 'https://github.com/zeromq/libzmq/tarball/master' + extension 'tar.gz' + action :configure + not_if { platform_family?('rhel') && node['platform_version'].to_f < 6.0 } +end +``` + +**Set the administrator if not already set** + +The following example shows how to set the administrator for Nagios on +multiple nodes, except when the package already exists on a node: + +```ruby +%w(adminpassword adminpassword-repeat).each do |setting| + execute "debconf-set-selections::#{node['nagios']['server']['vname']}-cgi::#{node['nagios']['server']['vname']}/#{setting}" do + command "echo #{node['nagios']['server']['vname']}-cgi #{node['nagios']['server']['vname']}/#{setting} password #{random_initial_password} | debconf-set-selections" + not_if "dpkg -l #{node['nagios']['server']['vname']}" + end +end +``` + +### only_if Examples + +**Install packages only when necessary** + +The following example shows how to use `only_if` with one (or more) +cookbook attributes to ensure that packages are only installed when +necessary. In this case, three attributes exist in the +`/attributes/default.rb` file: `use_openssl`, `use_pcre`, and +`use_zlib`. Each of these attributes are defined as `false` by default. +The `only_if` attributes are used to test for the presence of these +packages on the target node before then asking Chef Infra Client to +complete the process of installing these packages. If the packages are +already present, Chef Infra Client will do nothing. + +```ruby +package 'libpcre3-dev' do + only_if { node['haproxy']['source']['use_pcre'] } +end + +package 'libssl-dev' do + only_if { node['haproxy']['source']['use_openssl'] } +end + +package 'zlib1g-dev' do + only_if { node['haproxy']['source']['use_zlib'] } +end +``` + +**Remove a recipe if it belongs to a specific run-list** + +The following example shows how to use `only_if` to only remove a recipe +named `recipe[ntp::undo]`, but only when that recipe is part of the +`recipe[ntp::default]` run-list: + +```ruby +ruby_block 'remove ntp::undo from run list' do + block do + node.run_list.remove('recipe[ntp::undo]') + end + only_if { node.run_list.include?('recipe[ntp::default]') } +end +``` + +**Re-register ASP.Net if it's already installed** + +The following example shows how to use `only_if` to ensure that Chef +Infra Client will attempt to register ASP.NET only if the executable is +installed on the system, on both 32- and 64-bit systems: + +```ruby +aspnet_regiis = "#{ENV['WinDir']}\\Microsoft.NET\\Framework\\v4.0.30319\\aspnet_regiis.exe" +execute 'Register ASP.NET v4' do + command "#{aspnet_regiis} -i" + only_if { ::File.exist?(aspnet_regiis) } + action :nothing +end + +aspnet_regiis64 = "#{ENV['WinDir']}\\Microsoft.NET\\Framework64\\v4.0.30319\\aspnet_regiis.exe" +execute 'Register ASP.NET v4 (x64)' do + command "#{aspnet_regiis64} -i" + only_if { ::File.exist?(aspnet_regiis64) } + action :nothing +end +``` + +## Guard Interpreters + +{{< readfile file="content/reusable/md/resources_common_guard_interpreter.md" >}} + +### Attributes + +{{< readfile file="content/reusable/md/resources_common_guard_interpreter_attributes.md" >}} + +### Inheritance + +{{< readfile file="content/reusable/md/resources_common_guard_interpreter_attributes_inherit.md" >}} + +### Examples + +{{< readfile file="content/reusable/md/resources_common_guard_interpreter_example_default.md" >}} + +## Lazy Evaluation + +{{< readfile file="content/reusable/md/resources_common_lazy_evaluation.md" >}} + +## Notifications + +{{< readfile file="content/reusable/md/resources_common_notification.md" >}} + +### Timers + +{{< readfile file="content/reusable/md/resources_common_notification_timers.md" >}} + +### Notifies + +{{< readfile file="content/reusable/md/resources_common_notification_notifies.md" >}} + +{{< readfile file="content/reusable/md/resources_common_notification_notifies_syntax.md" >}} + +Changed in Chef Infra Client 12.6 to use `:before` timer with the `notifies` +and `subscribes` properties to specify that the action on a notified +resource should be run before processing the resource block in which the +notification is located. + +#### Examples + +The following examples show how to use the `notifies` notification in a +recipe. + +**Delay notifications** + +{{< readfile file="content/reusable/md/resource_template_notifies_delay.md" >}} + +**Notify immediately** + +{{< readfile file="content/reusable/md/resource_template_notifies_run_immediately.md" >}} + +**Notify multiple resources** + +{{< readfile file="content/reusable/md/resource_template_notifies_multiple_resources.md" >}} + +**Notify in a specific order** + +{{< readfile file="content/reusable/md/resource_execute_notifies_specific_order.md" >}} + +**Reload a service** + +{{< readfile file="content/reusable/md/resource_template_notifies_reload_service.md" >}} + +**Restart a service when a template is modified** + +{{< readfile file="content/reusable/md/resource_template_notifies_restart_service_when_template_modified.md" >}} + +**Send notifications to multiple resources** + +{{< readfile file="content/reusable/md/resource_template_notifies_send_notifications_to_multiple_resources.md" >}} + +**Execute a command using a template** + +{{< readfile file="content/reusable/md/resource_execute_command_from_template.md" >}} + +**Restart a service, and then notify a different service** + +{{< readfile file="content/reusable/md/resource_service_restart_and_notify.md" >}} + +**Restart one service before restarting another** + +{{< readfile file="content/reusable/md/resource_before_notification_restart.md" >}} + +**Notify when a remote source changes** + +{{< readfile file="content/reusable/md/resource_remote_file_transfer_remote_source_changes.md" >}} + +### Subscribes + +{{< readfile file="content/reusable/md/resources_common_notification_subscribes.md" >}} + +{{< readfile file="content/reusable/md/resources_common_notification_subscribes_syntax.md" >}} + +#### Examples + +The following examples show how to use the `subscribes` notification in +a recipe. + +**Verify a configuration update** + +{{< readfile file="content/reusable/md/resource_execute_subscribes_prevent_restart_and_reconfigure.md" >}} + +**Reload a service when a template is updated** + +{{< readfile file="content/reusable/md/resource_service_subscribes_reload_using_template.md" >}} + +## Relative Paths + +{{< readfile file="content/reusable/md/resources_common_relative_paths.md" >}} + +### Examples + +{{< readfile file="content/reusable/md/resource_template_use_relative_paths.md" >}} + +## Run in Compile Phase + +{{< readfile file="content/reusable/md/resources_common_compile.md" >}} + +### Using the compile_time property + +{{< readfile file="content/reusable/md/resources_common_compile_begin.md" >}} + +## Windows File Security + +{{< readfile file="content/reusable/md/resources_common_windows_security.md" >}} + +### Access Control Lists (ACLs) + +{{< readfile file="content/reusable/md/resources_common_windows_security_acl.md" >}} + +### Inheritance + +{{< readfile file="content/reusable/md/resources_common_windows_security_inherits.md" >}} diff --git a/content/resources/custom/_index.md b/content/resources/custom/_index.md new file mode 100644 index 0000000..9606521 --- /dev/null +++ b/content/resources/custom/_index.md @@ -0,0 +1,180 @@ ++++ +title = "Custom resource guide" + +linkTitle = "Custom resources" + +[menu] + [menu.resources] + title = "Custom resource guide" + identifier = "resources/custom/custom_resources.md custom resources" + parent = "resources/custom" + weight = 10 ++++ + +Chef Infra Client ships with over 150 [built-in resources](/resources/bundled/) for managing system configuration such as `directory`, `remote_file`, and `windows_firewall`. +With custom resources you can extend the built-in capabilities of Chef Infra Client to create reusable resources for use anywhere in your infrastructure. + +Custom resources: + +- Ship directly in cookbooks. +- Leverage Chef Infra Client built-in resources and any additional custom Ruby code (if needed). +- Behave the same as existing built-in resources in your recipes. + +## Write a custom resource + +Custom resources are written in Ruby and defined in a cookbook's `/resources` directory. + +The custom resource code: + +- Declares the properties of the custom resource. +- Loads the current state of properties for existing resources. +- Defines each action that the custom resource may take. + +Follow these steps to create a new custom resource: + +1. Generate a new custom resource. + + The `resources` directory doesn't exist by default in a cookbook. + Generate the `resources` directory and a resource file from the `chef-repo/cookbooks` directory with the command: + + ```bash + chef generate resource + ``` + + For example, this command generates a `site` custom resource in the `custom_web` cookbook: + + ```bash + chef generate resource cookbooks/custom_web site + ``` + + The `custom_web` cookbook directory with a custom resource has the following structure: + + ```text + . cookbooks + └── custom_web + ├── CHANGELOG.md + ├── LICENSE + ├── Policyfile.rb + ├── README.md + ├── chefignore + ├── kitchen.yml + ├── metadata.rb + ├── recipes + │ └── default.rb + ├── resources + │ └── site.rb + └── test + └── integration + └── default + └── default_test.rb + ``` + +1. Define the custom resources. + + The layout for a custom resource is: + + ```ruby + provides :resource_name + + property :property_name, RubyType, default: 'value' + + action :an_action_name do + # a mix of built-in Chef Infra resources and Ruby + end + + action :another_action_name do + # a mix of built-in Chef Infra resources and Ruby + end + ``` + + The first action listed is the default action. + + For more details on the contents of a custom resource, see the [custom resource glossary]({{< relref "custom_resource_glossary" >}}). + +1. Add the custom resource to a recipe. + + Call a resource in a recipe by its resource name. For example: + + ```ruby + resource_name 'foo' + ``` + +## Example custom resource + +This example creates a custom resource called `site`, which uses Chef Infra's built-in `file`, `service` and `package` resources, and includes `:create` and `:delete` actions. +It also assumes the existence of a [custom httpd template]({{< relref "templates.md" >}}). +The code in this custom resource is similar to a typical recipe because it uses built-in Chef Infra Client resources, with the addition of the property and actions definitions for this custom resource. + +```ruby +provides :site + +property :homepage, String, default: '

Hello world!

' + +action :create do + package 'httpd' + + service 'httpd' do + action [:enable, :start] + end + + file '/var/www/html/index.html' do + content new_resource.homepage + end +end + +action :delete do + package 'httpd' do + action :remove + end + + file '/var/www/html/index.html' do + action :delete + end +end +``` + +where: + +- `site` is the name of the custom resource. The `provides` statement makes the custom resource available for use recipes. +- `homepage` sets the default HTML for the `index.html` file with a default value of `'

Hello world!

'` +- the `action` block uses the built-in collection of resources to tell Chef Infra Client how to install Apache, start the service, and then create the contents of the file located at `/var/www/html/index.html` +- `action :create` is the default resource (because it's listed first); `action :delete` must be called specifically (because it's not the default action) + +Once written, you can use a custom resource in a recipe with the same syntax as Chef Infra Client built-in resources. + +### Syntax + +To add a custom resource to a recipe, call it by its resource name. For example, this adds a the `site` resource: + +```ruby +site 'foo' +``` + +## Agentless Mode + +{{< readfile file="content/reusable/md/agentless_summary.md" >}} For more information on Agentless Mode, see the [Agentless Mode documentation]({{< relref "/features/agentless.md" >}}). + +{{< readfile file="/content/reusable/md/agentless_custom_resource.md" >}} + +### Example + +{{< readfile file="/content/reusable/md/agentless_custom_resource_example.md" >}} + +## Unified Mode + +{{< readfile file="content/reusable/md/unified_mode_overview.md" >}} + +For more information on Unified Mode, see the [Unified Mode documentation]({{< relref "unified_mode.md" >}}). + +### Enable Unified Mode + +{{< readfile file="content/reusable/md/unified_mode_enable.md" >}} + +## Learn more + +See these resources to learn more about custom resources: + +- See the LearnChef interactive tutorial: [Extending Chef Infra: Custom Resources](https://www.chef.io/training/tutorials). +- For a description of available methods, see the [custom resources glossary]({{< relref "custom_resource_glossary" >}}). +- For running resources in Agentless Mode, see the [Agentless Mode documentation]({{< relref "agentless" >}}). +- For running resources in Unified Mode, see the [Unified Mode documentation]({{< relref "unified_mode" >}}). diff --git a/content/resources/custom/accumulators.md b/content/resources/custom/accumulators.md new file mode 100644 index 0000000..101ea89 --- /dev/null +++ b/content/resources/custom/accumulators.md @@ -0,0 +1,131 @@ ++++ +title = "Accumulators" + + +[menu] + [menu.resources] + title = "Accumulators" + identifier = "resources/custom/accumulators" + parent = "resources/custom" + weight = 20 ++++ + +This is an advanced topic. You should have already written a custom resource and be familiar with: + +- The built-in Chef Infra [`template`]({{< relref "/resources/bundled/template" >}}) resource +- Cookbook execution [`with_run_context`]({{< relref "infra_language/cookbook_execution/#with_run_context" >}}) + +## Overview + +An accumulator is a programming pattern that gathers multiple values together. + +In the context of Custom Resources, the accumulator pattern collects a set of properties from Custom Resources, and then applies the collection to a resource. + +The steps for setting up an accumulator pattern are: + +- Declare a resource +- Edit the resource +- Add both resources to the :root `run_context` +- Delay the actions on the resources + +## Example Accumulator: Samba + +Samba Linux tool systems for supporting sharing resources in a network with Windows systems. Samba uses a single file for configuration. To share more than one directory using this configuration file, you need to write multiple `samba_share` resources. + +The accumulator pattern lets you split out each configuration section into its own resource. + + + +{{< foundation_tabs tabs-id="tabs-panel-container" >}} +{{< foundation_tab active="true" panel-link="id-1" tab-text="Share Resource 1">}} +{{< foundation_tab panel-link="id-2" tab-text="Share Resource 2" >}} +{{< /foundation_tabs >}} + + + +{{< foundation_tabs_panels tabs-id="tabs-panel-container" >}} +{{< foundation_tabs_panel active="true" panel-id="id-1" >}} +```ruby +samba_share 'first_share' do + comment 'exported share 1' + path '/srv/export' + guest_ok true + printable false + write_list ['test_user_1'] + create_mask '0644' + directory_mask '0775' + options 'inherit permissions' => 'yes' +end +``` +{{< /foundation_tabs_panel >}} +{{< foundation_tabs_panel panel-id="id-2" >}} +```ruby +samba_share 'second_share' do + comment 'exported share 2' + path '/srv/export_2' + guest_ok false + printable false + write_list ['test_user_2'] + create_mask '0644' + directory_mask '0775' + create_directory false +end +``` +{{< /foundation_tabs_panel >}} +{{< /foundation_tabs_panels >}} + + + +## Example + +The following example shows how to: + +- Setup the template resource +- Set the `action` to `:nothing` +- Set the `delayed_action` to `:create`. +- Add the template resource to the `root` run context, which allows the `samba_share` resource to find it. +- Use `edit_resource` to find the template +- Use `edit_resource` to add new variables to the existing collection + +_Note_: This uses the `||=` Ruby method to add a new Hash if one doesn't exist already. + +```ruby +# action for the samba_server custom resource +action :create do + package 'samba' + + # We need to force both the server template and the + # share templates into the root context to find each other + with_run_context :root do + template new_resource.config_file do + source 'smb.conf.erb' + owner 'root' + group 'root' + mode '0644' + cookbook 'samba' + variables(samba_options: new_resource.options) + action :nothing + delayed_action :create + end + end +end + + +# action for the samba_share custom resource +action :add do + with_run_context :root do + edit_resource(:template, new_resource.config_file) do |new_resource| + variables[:shares] ||= {} + variables[:shares][new_resource.share_name] ||= {} + variables[:shares][new_resource.share_name]['comment'] = new_resource.comment + variables[:shares][new_resource.share_name]['path'] = new_resource.path + end + end +end +``` + +## Further reading + +- [Accumulators pattern issue in chef/chef repository](https://github.com/chef/chef/issues/5438#issuecomment-351153222) +- [DNSimple](https://blog.dnsimple.com/2017/10/chef-accumulators/) +- [HAProxy](https://github.com/sous-chefs/haproxy/blob/a9c24d336c01828fef52cedae8cc445d8dbc21dd/libraries/resource.rb#L22) diff --git a/content/resources/custom/custom_resource_glossary.md b/content/resources/custom/custom_resource_glossary.md new file mode 100644 index 0000000..a14a9b8 --- /dev/null +++ b/content/resources/custom/custom_resource_glossary.md @@ -0,0 +1,718 @@ ++++ +title = "Custom resources glossary" + + + + + +[menu] + [menu.resources] + title = "Glossary" + identifier = "resources/custom/glossary" + parent = "resources/custom" + weight = 200 ++++ + +The following domain-specific language (DSL) methods are available when writing custom resources. + +For further information about how to write custom resources please see [about custom resources]({{< relref "/resources/custom" >}}) + +## action_class + +`action_class` makes methods available to all actions within a single custom resource. + +For example, a template requires `'yes'` or `'no'` written as a string, but you would like the user to use `true` or `false` for convenience. +To allow both the `:add` and `:remove` actions to have access to this method, place the method in the `action_class` block. + +```ruby +property :example, [true, false], default: true + +action :add do + template "file.conf" do + source 'file.conf.erb' + variables( + chocolate: bool_to_string(new_resource.example) + ) + action :create + end +end + +action :remove do + template "file.conf" do + source 'file.conf.erb' + variables( + chocolate: bool_to_string(new_resource.example) + ) + action :delete + end +end + +action_class do + def bool_to_string(b) + b ? 'yes' : 'false' + end +end +``` + +## coerce + +`coerce` is used to transform user input into a canonical form. The +value is passed in, and the transformed value returned as output. Lazy +values will __not__ be passed to this method until after they're +evaluated. + +`coerce` is run in the context of the instance, which gives it access to +other properties. + +Here we transform,`true`/`false` in to `yes`, `no` for a template later on. + +```ruby +property :browseable, + [true, false, String], + default: true, + coerce: proc { |p| p ? 'yes' : 'no' }, +``` + +If you are modifying the properties type, you will also need to accept that Ruby type as an input. + +## converge_if_changed + +Use the `converge_if_changed` method inside an `action` block in a +custom resource to compare the desired property values against the +current property values (as loaded by the `load_current_value` method). +Use the `converge_if_changed` method to ensure that updates only occur +when property values on the system aren't the desired property values +and to otherwise prevent a resource from being converged. + +To use the `converge_if_changed` method, wrap it around the part of a +recipe or custom resource that should only be converged when the current +state isn't the desired state: + +```ruby +action :some_action do + converge_if_changed do + # some property + end +end +``` + +The `converge_if_changed` method may be used multiple times. The +following example shows how to use the `converge_if_changed` method to +compare the multiple desired property values against the current +property values (as loaded by the `load_current_value` method). + +```ruby +property :path, String +property :content, String +property :mode, String + +# Load the current value for content and mode +load_current_value do |new_resource| + if ::File.exist?(new_resource.path) + content IO.read(new_resource.path) + mode ::File.stat(new_resource.path).mode + end +end + +action :create do + # If the value of content has changed + # write file + converge_if_changed :content do + IO.write(new_resource.path, new_resource.content) + end + + # If the value of mode has changed then + # chmod file + converge_if_changed :mode do + ::File.chmod(new_resource.mode, new_resource.path) + end +end +``` + +Chef Infra Client will only update the property values that require +updates and won't make changes when the property values are already +in the desired state. + + + +## current_value_does_not_exist! + + + +When using the `load_current_value` block, use `current_value_does_not_exist!` to indicate that the value doesn't exist and that `current_resource` should therefore be `nil`. + +```ruby +load_current_value do |new_resource| + port_data = powershell_exec(%Q{Get-WmiObject -Class Win32_TCPIPPrinterPort -Filter "Name='#{new_resource.port_name}'"}).result + + if port_data.empty? + current_value_does_not_exist! + else + ipv4_address port_data["HostAddress"] + end + endo +end +``` + +## default_action + +The default action in a custom resource is, by default, the first action +listed in the custom resource. For example, action `aaaaa` is the +default resource: + +```ruby +property :property_name, RubyType, default: 'value' + +... + +action :aaaaa do + # the first action listed in the custom resource +end + +action :bbbbb do + # the second action listed in the custom resource +end +``` + +The `default_action` method may also be used to specify the default +action. For example: + +```ruby +property :property_name, RubyType, default: 'value' + +# Define bbbbb aas the default action +default_action :bbbbb + +action :aaaaa do + # the first action listed in the custom resource +end + +action :bbbbb do + # the second action listed in the custom resource +end +``` + +## deprecated + +### Deprecating a resource + +Deprecate resources that you no longer wish to maintain. +This allows you make breaking changes to enterprise or community cookbooks with friendly notifications to downstream cookbook consumers directly in the Chef Infra Client run. + +Use the `deprecated` method to deprecate a resource in a cookbook. For example: + +```ruby +deprecated 'The foo_bar resource has been deprecated and will be removed in the next major release of this cookbook scheduled for 25/01/2021!' + +property :thing, String, name_property: true + +action :create do + # Chef resource code +end +``` + +### Deprecating a property + +Deprecate the `badly_named` property in a resource: + +```ruby +property :badly_named, String, deprecated: 'The badly_named property has been deprecated and will be removed in the next major release of this cookbook scheduled for 12/25/2021!' +``` + +## deprecated_property_alias + +To rename a property with a deprecation warning for users of the old property name, use `deprecated_property_alias`: + +```ruby +deprecated_property_alias 'badly_named', 'really_well_named', 'The badly_named property was renamed really_well_named in the 2.0 release of this cookbook. Please update your cookbooks to use the new property name.' +``` + +## desired_state + +Add `desired_state:` to set the desired state property for a resource. + +| Allowed values | Default | +| -------------- | ------- | +| `true` `false` | `true` | + +- When `true`, the state of the property is determined by the state of + the system +- When `false`, the value of the property impacts how the resource + executes, but it's not determined by the state of the system. + +For example, if you were to write a resource to create volumes on a +cloud provider you would need define properties such as `volume_name`, +`volume_size`, and `volume_region`. The state of these properties would +determine if your resource needed to converge or not. For the resource +to function you would also need to define properties such as +`cloud_login` and `cloud_password`. These are necessary properties for +interacting with the cloud provider, but their state has no impact on +decision to converge the resource or not, so you would set +`desired_state` to `false` for these properties. + +```ruby +property :volume_name, String +property :volume_size, Integer +property :volume_region, String +property :cloud_login, String, desired_state: false +property :cloud_password, String, desired_state: false +``` + +## lazy + +When setting a node attribute as the default value for a custom resource property, wrap the node attribute in `lazy {}` so that its value is available when the resource executes. + +```ruby +property :thing, String, default: lazy { node['thingy'] } +``` + +## load_current_value + +Use the `load_current_value` method to load the specified property +values from the node, and then use those values when the resource is +converged. This method may take a block argument. + +```ruby +property :path, String +property :content, String +property :mode, String + +load_current_value do |new_resource| + if ::File.exist?(new_resource.path) + content IO.read(new_resource.path) + mode ::File.stat(new_resource.path).mode + end +end +``` + +Use the `load_current_value` method to guard against property value being replaced. For example: + +```ruby +property :homepage, String +property :page_not_found, String + +load_current_value do + if ::File.exist?('/var/www/html/index.html') + homepage IO.read('/var/www/html/index.html') + end + + if ::File.exist?('/var/www/html/404.html') + page_not_found IO.read('/var/www/html/404.html') + end +end +``` + +This ensures the values for `homepage` and `page_not_found` aren't +changed to the default values when Chef Infra Client configures the +node. + +## new_resource.property + +Custom resources are designed to use resources that are built into Chef Infra and external custom resources. +To disambiguate from the current resource being used and other resources, `new_resource.property` is required. + +For example: + +```ruby +property :command, String, name_property: true +property :version, String + +# Useful properties from the `execute` resource +property :cwd, String +property :environment, Hash, default: {} +property :user, [String, Integer] +property :sensitive, [true, false], default: false + +prefix = '/opt/languages/node' + +load_current_value do + current_value_does_not_exist! if node.run_state['nodejs'].nil? + version node.run_state['nodejs'][:version] +end + +action :run do + execute 'execute-node' do + cwd cwd + environment environment + user user + sensitive sensitive + # gsub replaces 10+ spaces at the beginning of the line with nothing + command <<-CODE.gsub(/^ {10}/, '') + #{prefix}/#{new_resource.version}/#{command} + CODE + end +end +``` + +The following properties are identical to the properties in the execute resource, which we're embedding in the custom resource. + +- `property :cwd` +- `property :environment` +- `property :user` +- `property :sensitive` + +Because both the custom properties and the __execute__ properties are identical, this +will result in an error message similar to: + +```ruby +ArgumentError +------------- +wrong number of arguments (0 for 1) +``` + +To prevent this behavior, use `new_resource.` to tell Chef Infra Client +to process the properties from the core resource instead of the +properties in the custom resource. For example: + +```ruby +property :command, String, name_property: true +property :version, String + +# Useful properties from the `execute` resource +property :cwd, String +property :environment, Hash, default: {} +property :user, [String, Integer] +property :sensitive, [true, false], default: false + +prefix = '/opt/languages/node' + +load_current_value do + current_value_does_not_exist! if node.run_state['nodejs'].nil? + version node.run_state['nodejs'][:version] +end + +action :run do + execute 'execute-node' do + cwd new_resource.cwd + environment new_resource.environment + user new_resource.user + sensitive new_resource.sensitive + # gsub replaces 10+ spaces at the beginning of the line with nothing + command <<-CODE.gsub(/^ {10}/, '') + #{prefix}/#{new_resource.version}/#{new_resource.command} + CODE + end +end +``` + +where: + +- `cwd new_resource.cwd` +- `environment new_resource.environment` +- `user new_resource.user` +- `sensitive new_resource.sensitive` + +Correctly use the properties of the __execute__ resource and not the identically-named override properties of the custom resource. + +## partial + +To DRY (don't repeat yourself) up code, custom resources can include partials from common files. + +For example, if all of your resources need the `version` property, you can add this to a `partial/_common.rb` file and include that Ruby code in your resource using the `use` directive. + +In `resources/partial/_common.rb`, define the `version` property: + +```ruby +# resources/partial/_common.rb +property :version, String, + name_property: true, + description: 'Java version to install' +``` + +And then in your custom resources, include that code with the `use` directive: + +```ruby +# resources/install_type_a.rb +provides :adoptopenjdk_install +unified_mode true +use 'partial/_common' + +property :variant, + String, + description: 'Install flavour', default: 'openj9' +``` + +```ruby +# resources/openjdk_install.rb +provides :openjdk_install +unified_mode true +use 'partial/_common' + +property :install_type, + String, + default: lazy { default_openjdk_install_method(version) }, + equal_to: %w( package source ), + description: 'Installation type' +``` + +## property + +Use the `property` method to define properties for the custom resource. +The syntax is: + +```ruby +property :property_name, ruby_type, default: 'value', parameter: 'value' +``` + +where + +- `:property_name` is the name of the property +- `ruby_type` is the optional Ruby type or array of types, such as + `String`, `Integer`, `true`, or `false` +- `default: 'value'` is the optional default value loaded into the + resource +- `parameter: 'value'` optional parameters + +For example, the following properties define `username` and `password` +properties with no default values specified: + +```ruby +property :username, String +property :password, String +``` + +## property_is_set? + +Use the `property_is_set?` method to check if the value for a property has been passed into the resource. + +The syntax is: + +```ruby +property_is_set?(:property_name) +``` + +The `property_is_set?` method will return `true` if the property is set. + +For example, the following custom resource creates and/or updates user +properties, but not their password. The `property_is_set?` method checks +if the user has specified a password and then tells Chef Infra Client +what to do if the password isn't identical: + +```ruby +action :create do + converge_if_changed do + shell_out!("rabbitmqctl create_or_update_user #{username} --prop1 #{prop1} ... ") + end + + if property_is_set?(:password) + if shell_out("rabbitmqctl authenticate_user #{username} #{password}").error? + converge_by "Updating password for user #{username} ..." do + shell_out!("rabbitmqctl update_user #{username} --password #{password}") + end + end + end +end +``` + +## provides + +Use the `provides` method to associate multiple custom resource files with the same resources name. +For example: + +```ruby +# Provide custom_resource_name to Red Hat 7 and above +provides :custom_resource_name, platform: 'redhat' do |node| + node['platform_version'].to_i >= 7 +end + +# Provide custom_resource_name to all Red Hat platforms +provides :custom_resource_name, platform: 'redhat' + +# Provide custom_resource_name to the Red Hat platform family +provides :custom_resource_name, platform_family: 'rhel' + +# Provide custom_resource_name to all linux machines +provides :custom_resource_name, os: 'linux' + +# Provide custom_resource_name, useful if your resource file isn't named the same as the resource you want to provide +provides :custom_resource_name +``` + +This allows you to use multiple custom resources files that provide the +same resource to the user, but for different operating systems or +operation system versions. With this you can eliminate the need for +platform or platform version logic within your resources. + +### Precedence + +Use the `provides` method to associate a custom resource with the recipe +DSL on different operating systems. When multiple custom resources use +the same DSL, specificity rules are applied to determine the priority, +from highest to lowest: + +1. `provides :custom_resource_name, platform_version: '0.1.2'` +2. `provides :custom_resource_name, platform: 'platform_name'` +3. `provides :custom_resource_name, platform_family: 'platform_family'` +4. `provides :custom_resource_name, os: 'operating_system'` +5. `provides :custom_resource_name` + +## reset_property + +Use the `reset_property` method to clear the value for a property as if +it had never been set, and then use the default value. For example, to +clear the value for a property named `password`: + +```ruby +reset_property(:password) +``` + +## resource_name + +{{< note >}} + +`resource_name` was deprecated in Chef Infra Client 15 and became EOL in 16.2.44. +Use the [`provides`](#provides) method instead of `resource_name`. + +For resources running on Chef Infra Client from 12.5 through 15, use `resource_name`: + +```ruby +resource_name :foo +``` + +For resources running on Chef Infra Client 15.13.8 to 16.1.16, use both methods to maintain backwards compatibility: + +```ruby +resource_name :foo +provides :foo +``` + +{{< /note >}} + +Use the `resource_name` method at the top of a custom resource to declare a custom name for that resource. For example: + +```ruby +resource_name :my_resource_name +``` + +## ruby_type + +The property ruby_type is a positional parameter. + +Use to ensure a property value is of a particular ruby class, such as: + +- `true` +- `false` +- `nil` +- `String` +- `Array` +- `Hash` +- `Integer` +- `Symbol` + +Use an array of Ruby classes to allow a value to be of more than one type. For example: + +```ruby +property :aaaa, String +property :bbbb, Integer +property :cccc, Hash +property :dddd, [true, false] +property :eeee, [String, nil] +property :ffff, [Class, String, Symbol] +property :gggg, [Array, Hash] +``` + +## run_context + +Chef loads and tracks the current run in the run context object. + +root_context + +## sensitive + +A property can be marked sensitive by specifying `sensitive: true` on +the property. This prevents the contents of the property from being +exported to data collection and sent to an Automate server or shown in the +logs of the Chef Infra Client run. + +## target_mode + +{{< readfile file="content/reusable/md/agentless_summary.md" >}} + +{{< readfile file="/content/reusable/md/agentless_custom_resource.md" >}} + +For more information on Agentless Mode, see the [Agentless Mode documentation]({{< relref "/features/agentless.md" >}}). + +## unified_mode + +{{< readfile file="content/reusable/md/unified_mode_overview.md" >}} + +To enable Unified Mode in a resource, declare it at the top of the resource. For example: + +```ruby +unified_mode true + +provides :resource_name + +``` + +For information, see the [Unified Mode documentation]({{< relref "unified_mode" >}}). + +## Validation parameters + +Use a validation parameter to add zero (or more) validation parameters to a property. + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterDescription

:callbacks

Use to define a collection of unique keys and values (a ruby hash) for which the key is the error message and the value is a lambda to validate the parameter. For example:

+
callbacks: {
+             'should be a valid non-system port' => lambda {
+               |p| p > 1024 && p < 65535
+             }
+           }

:default

Use to specify the default value for a property. For example:

+
default: 'a_string_value'
+
default: 123456789
+
default: []
+
default: ()
+
default: {}

:equal_to

Use to match a value with ==. Use an array of values to match any of those values with ==. For example:

+
equal_to: [true, false]
+
equal_to: ['php', 'perl']

:regex

Use to match a value to a regular expression. For example:

+
regex: [ /^([a-z]|[A-Z]|[0-9]|_|-)+$/, /^\d+$/ ]

:required

Indicates that a property is required. For example:

+
required: true

:respond_to

Use to ensure that a value has a given method. This can be a single method name or an array of method names. For example:

+
respond_to: valid_encoding?
+ + +Some examples of combining validation parameters: + +```ruby +property :spool_name, String, regex: /$\w+/ +``` + +```ruby +property :enabled, equal_to: [true, false, 'true', 'false'], default: true +``` diff --git a/content/resources/custom/custom_resources_notes.md b/content/resources/custom/custom_resources_notes.md new file mode 100644 index 0000000..ee92fe6 --- /dev/null +++ b/content/resources/custom/custom_resources_notes.md @@ -0,0 +1,229 @@ ++++ +title = "Custom Resources Notes" +draft = false + +[menu] + [menu.resources] + title = "Migration Notes" + identifier = "resources/custom/custom_resources_notes.md Custom Resource Guide" + parent = "resources/custom" + weight = 70 ++++ + +{{< warning >}} + +This page mentions multiple ways of building custom resources. Chef Software recommends you try the approach outlined in the [Custom Resource documentation]({{< relref "/resources/custom" >}}) first, before trying the resource/provider pair (older approach) or library type (pure Ruby) approaches. If you run into issues while designing 12.5-style custom resources, please ask for help in the [Chef Mailing List](https://discourse.chef.io) or [file a bug](https://github.com/chef/chef/issues/new) for Chef Infra Client. + +{{< /warning >}} + +## Custom resources + +This is the recommended way of writing resources for all users. There are two gotchas which we're working through: + +1. For helper functions that you used to write in your provider code or used to mixin to your provider code, you have to use an `action_class do ... end` block. +1. You can't subclass, and must use mixins for code-sharing (which is really a best practice anyway -- for example, see languages like rust which don't support sub-classing). + +in `resources/whatever.rb`: + +```ruby +resource_name :my_resource +provides :my_resource + +property :foo, String, name_property: true +extend MyResourceHelperFunctions # probably only used for common properties which is why you extend with class methods + +action :run do + # helpers must be defined inside the action_class block + a_helper() + # you will save yourself some pain by referring to properties with `new_resource.foo` and not `foo` + # since the latter works most of the time, but will troll you with odd scoping problems, while the + # former just works. + puts new_resource.foo +end + +action_class do + include MyProviderHelperFunctions + + def a_helper + end +end +``` + +## "Old school" LWRPS + +This method isn't recommended, but is preferable to writing library resources/providers (as described below). It has the same functionality as library providers, only you can't subclass and must use mixins for code sharing (which is good). + +in `resources/my_resource.rb`: + +```ruby +resource_name :my_resource +provides :my_resource + +property :foo, String, name_property: true +extend MyResourceHelperFunctions # probably only used for common properties which is why you extend with class methods +``` + +in `providers/my_resource.rb`: + +```ruby +# you have to worry about this +def whyrun_supported? + true +end + +include MyProviderHelperFunctions + +def a_helper +end + +action :run do + a_helper() + + # here you have to use new_resource.foo + puts new_resource.foo +end +``` + +## Library Resources/Providers + +Library resources are discouraged since you can shoot yourself in the foot. They used to be encouraged back before Chef Infra Client 12.0 `provides` was introduced since it allowed for renaming the resource so that it didn't have to be prefixed by the cookbook name. + +There are many ways to go wrong writing library providers. One of the biggest issues is that internal Chef Infra Client code superficially looks like a library provider, but it's not. Chef internal resources don't inherit from `LWRPBase` and we've had to manually create resources directly through `Chef::Resource::File.new()`, we also haven't been able to `use_inline_resources` and not had access to other niceties that cookbook authors have had access to for years now. We've got some modernization of internal Chef cookbook code now and resources like `apt_update` and `apt_repository` in core have started to be written more like cookbook code should be written, but core resources are actually behind the curve and are bad code examples. + +in `libraries/resource_my_resource.rb`: + +```ruby +class MyBaseClass + class Resource + class MyResource < Chef::Resource::LWRPBase # it's important to inherit from LWRPBase + resource_name :my_resource + provides :my_resource + + property :foo, String, name_property: true + extend MyResourceHelperFunctions # probably only used for common properties which is why you extend with class methods + end + end +end +``` + +in `libraries/resource_my_resource.rb`: + +```ruby +class MyBaseClass + class Resource + class MyProvider < Chef::Provider::LWRPBase # it's important to inherit from LWRPBase + # you have to worry about this + def whyrun_supported? + true + end + + include MyProviderHelperFunctions + + def a_helper + end + + # NEVER use `def action_run` here -- you defeat use_inline_resources and will break notifications if you do + # If you don't understand how use_inline_resources is built and why you have to use the `action` method, and what the implications are and how resource notifications + # break if use_inline_resources isn't used and/or is broken, then you should really not be using library providers+resources. You might feel "closer to the metal", + # but you're now using a chainsaw without any guard... + action :run do + a_helper() + + # here you have to use new_resource.foo + puts new_resource.foo + end + end + end +end +``` + +## updated_by_last_action + +Modern Chef Infra Client code (since Chef Infra Client version 11.0.0) should never have provider code which directly sets `updated_by_last_action` itself. + +THIS CODE IS WRONG: + +```ruby +action :run do + t = file '/tmp/foo' do + content 'foo' + end + t.run_action(:install) + # This is Chef Infra Client 10 code which fell through a timewarp into 2016 -- never use updated_by_last_action in modern Chef Infra Client 11.x/12.x code + t.new_resource.updated_by_last_action(true) if t.updated_by_last_action? +end +``` + +That used to be kinda-correct-code-with-awful-edge-cases back in Chef Infra Client version 10. If you're not using that version of Chef Infra Client, please stop writing actions this way. + +THIS IS CORRECT: + +```ruby +def whyrun_supported? + true +end + +action :run do + file '/tmp/foo' do + content 'foo' + end +end +``` + +That's the magic of `use_inline_resources` (and why `use_inline_resources` is turned on by default in Chef Infra Client 12.5 resources) The sub-resources are defined in a sub-resource collection which is compiled and converged as part of the provider executing. Any resources that update in the sub-resource collection cause the resource itself to be updated automatically. Notifications then fire normally off the resource. It also works to arbitrary levels of nesting of sub-sub-sub-resources being updating causing the wrapping resources to update and fire notifications. + +This also gets the why-run case correct. If all the work that you do in your resource is done by calling sub-resources, then why-run should work automatically. All your sub-resources will be NO-OP'd and will report what they would have done instead of doing it. + +If you do need to write code which mutates the system through pure-Ruby then you should do so like this: + +```ruby +def whyrun_supported? + true +end + +action :run do + unless ::File.exist?('/tmp/foo') + converge_by('touch /tmp/foo') do + ::FileUtils.touch '/tmp/foo' + end + end +end +``` + +When the `converge_by` block is run in why-run mode, it will only log `touch "/tmp/foo"` and won't run the code inside the block. + +A `converge_by` block that isn't wrapped in an idempotency check will always cause the resource to be updated, and will always cause notifications to fire. To prevent this, a properly written resource should wrap all `converge_by` checks with an idempotency check. The [`converge_if_changed`]({{< relref "/resources/custom.md#converge_if_changed" >}}) block may be used instead which will wrap a `converge_by` block with an idempotency check for you. + +```ruby +action :run do + # This code is bad, it lacks an idempotency check here. + # It will always be updated + # Chef Infra Client runs will always report a resource being updated + # It will run the code in the block on every run + converge_by('touch /tmp/foo') do + ::FileUtils.touch '/tmp/foo' + end +end +``` + +Of course it's simpler to just use Chef Infra Client resources when you can. Compare the equivalent implementations: + +```ruby +action :run do + file '/tmp/foo' +end +``` + +is basically the same as this: + +```ruby +action :run do + unless ::File.exist?('/tmp/foo') + converge_by('touch /tmp/foo') do + ::FileUtils.touch '/tmp/foo' + end + end +end +``` + +You may see a lot of `converge_by` and `updated_by_last_action` in the core chef resources. This is because Chef is written as a declarative language with an imperative language, which means someone has to take the first step and write the declarative file resources in imperative Ruby. As such, core Chef resources may not represent ideal code examples of custom resources. diff --git a/content/resources/custom/definitions_to_custom_resources.md b/content/resources/custom/definitions_to_custom_resources.md new file mode 100644 index 0000000..1295711 --- /dev/null +++ b/content/resources/custom/definitions_to_custom_resources.md @@ -0,0 +1,171 @@ ++++ +title = "Converting definitions to custom resources" + +[menu] + [menu.resources] + title = "Migrating from definitions" + identifier = "resources/custom/definitions.md Migrating from Definitions" + parent = "resources/custom" + weight = 50 ++++ + +The definitions feature in Chef Infra has been deprecated and will be removed in a future release. Please migrate existing definitions to custom resources. + +This guide describes how to migrate from an existing Definition to a custom resource. + +If you are creating a custom resource from scratch please see the [Custom resource getting started guide]({{< relref "/resources/custom" >}}) instead. + +## Definitions + +A definition behaved like a compile-time macro that was reusable across recipes. A definition was typically created by wrapping arbitrary code around Chef Infra resources that were declared as if they were in a recipe. A definition was then used in one (or more) actual recipes as if the definition were a resource. + +Though a definition looks like a resource, and at first glance seems like it could be used interchangeably, some important differences exist. + +Definitions: + +- Aren't true resources +- Are processed when resource collection is compiled, not when a node + is converged +- Don't support common resource properties, such as `notifies`, `compile_time`, + `subscribes`, `only_if`, `not_if`, and `sensitive` +- Don't support input validation in passed arguments, unlike a + resource which supports validation with properties +- Don't support `why-run` mode +- Can't report to Chef Automate +- Can't be tested with ChefSpec +- Some Definition parameters have known bugs, and won't be fixed + +## Syntax + +A definition had four components: + +- A resource name +- Zero or more arguments that define parameters and their default values; + if a default value wasn't specified, it was assumed to be `nil` +- A hash that could have been used within a definition's body to + provide access to parameters and their values +- The body of the definition + +The basic syntax of a definition was: + +```ruby +define :my_definition_name do + body +end +``` + +More commonly, the usage incorporated arguments to the definition: + +```ruby +define :my_definition_name, parameter: :argument, parameter: :argument do + body(likely referencing the params hash) +end +``` + +The following simple example shows a definition with no arguments (a parameter-less macro in the truest sense): + +```ruby +define :prime_file do + file '/etc/file' do + content 'some content' + end +end +``` + +An example showing the use of parameters, with a parameter named `port` that defaults to `4000` rendered into a **template** resource, would look like: + +```ruby +define :prime_file, port: 4000 do + template '/etc/file' do + source 'file.erb' + variables({ + port: params[:port], + }) + end +end +``` + +Or the following definition, which looks like a resource when used in a recipe, but also contained **directory** and **file** resources that were repeated, but with slightly different parameters: + +```ruby +define :host_porter, port: 4000, hostname: nil do + params[:hostname] ||= params[:name] + + directory '/etc/#{params[:hostname]}' do + recursive true + end + + file '/etc/#{params[:hostname]}/#{params[:port]}' do + content 'some content' + end +end +``` + +which was then used in a recipe like this: + +```ruby +host_porter node['hostname'] do + port 4000 +end + +host_porter 'www1' do + port 4001 +end +``` + +## Migrating to custom resources + +We highly recommend migrating existing definitions to custom resources to unlock the full feature set of Chef Infra resources. The following example shows a definition and that same definition rewritten as a custom resource. + +### Initial Definition Code + +The following definition processes unique hostnames and ports, passed on as parameters: + +```ruby +define :host_porter, port: 4000, hostname: nil do + params[:hostname] ||= params[:name] + + directory '/etc/#{params[:hostname]}' do + recursive true + end + + file '/etc/#{params[:hostname]}/#{params[:port]}' do + content 'some content' + end +end +``` + +### Migrated to a custom resource + +The definition is improved by rewriting it as a custom resource. This uses properties to accept input and has a single `:create` action: + +```ruby +property :port, Integer, default: 4000 +property :hostname, String, name_property: true + +action :create do + directory "/etc/#{hostname}" do + recursive true + end + + file "/etc/#{hostname}/#{port}" do + content 'some content' + end +end +``` + +Once written, a custom resource may be used in a recipe just like any resource that's built into Chef Infra. A custom resource gets its name from the cookbook and the name of its file in the `/resources` directory with an underscore (`_`) separating them. For example, a cookbook named `host` with a custom resource file named `porter.rb` in the `/resources` directory would be called `host_porter`. Use it in a recipe like this: + +```ruby +host_porter node['hostname'] do + port 4000 +end +``` + +or: + +```ruby +host_porter 'www1' do + port 4001 +end +``` diff --git a/content/resources/custom/helpers.md b/content/resources/custom/helpers.md new file mode 100644 index 0000000..18bc338 --- /dev/null +++ b/content/resources/custom/helpers.md @@ -0,0 +1,39 @@ ++++ +title = "Helpers" +draft = false + +[menu] + [menu.resources] + title = "Helpers" + identifier = "resources/custom/helpers Library Helpers" + parent = "resources/custom" + weight = 30 ++++ + +Helper classes enable users to share code between Custom Resources. Rspec method test are possible when code is abstracted into plain Ruby files. + +## Example + +To include the following helper from `libraries/helpers.rb` + +```ruby +#libraries/helpers.rb +module Haproxy + module cookbook + module ResourceHelpers + def haproxy_version + version = Mixlib::ShellOut.new("haproxy -v | grep version | awk '{ print $3 }'") + version.run_command.stdout.to_f + end + end + end +end +``` + +Within a Custom Resource file, use the include directive in the action_class, to include all methods in the specified module. + +```ruby +action_class do + include Haproxy::Cookbook::ResourceHelpers +end +``` diff --git a/content/resources/custom/lwrp_to_custom_resources.md b/content/resources/custom/lwrp_to_custom_resources.md new file mode 100644 index 0000000..6657abd --- /dev/null +++ b/content/resources/custom/lwrp_to_custom_resources.md @@ -0,0 +1,123 @@ ++++ +title = "Migrating from LWRPs to Custom Resources" + + + + +[menu] + [menu.resources] + title = "Migrating from LWRPs" + identifier = "resources/custom/lwrp" + parent = "resources/custom" + weight = 70 ++++ + +## Overview + +It's no longer recommended to write resources in the __Light Weight Resource Provider (LWRP)__ format. + +This guide describes how to migrate from an existing LWRP to a Custom Resource. + +If you are creating a Custom Resource from scratch please see the [Custom Resource Getting Started Guide]({{< relref "/resources/custom" >}}) instead. + +## Convert files to Custom Resources Layout + +LWRPs consist of two library files: a resource and a provider for that resource. + +```text +|- libraries + |- provider_rvm_ruby.rb + |- resource_rvm_ruby.rb +``` + +These files are merged into one, and moved into the resources directory. + +```text +|- resources + |- rvm_ruby.rb +``` + +## Drop LWRP classes + +LWRPs used classes to separate Provider and Resource behaviors, but Custom Resources don't need this distinction. This means that we remove the class definitions in their entirety, as shown in the following example: + +```ruby +#rvm/libraries/resource_rvm_ruby.rb +require 'chef/resource/lwrp_base' + +class Chef + class Resource + class RvmRuby < Chef::Resource::LWRPBase + provides :rvm_ruby + + self.resource_name = :rvm_ruby + default_action :install + end + end +end + +# rvm/libraries/provider_rvm_ruby.rb +require 'chef/provider/lwrp_base' + +class Chef + class Provider + class RvmRuby < Chef::Provider::LWRPBase + provides :rvm_ruby + + action :install do + remote_file 'rvm_installer' do + path "#{Chef::Config[:file_cache_path]}/rvm_installer.sh" + source node['rvm']['installer_url'] + mode '755' + not_if { ::File.exist?("#{Chef::Config[:file_cache_path]}/rvm_installer.sh") } + action :create + end + end + end + end +end +``` + +Replace the above files with a singular resource: + +```ruby +#rvm/resources/rvm_ruby.rb +provides :rvm_ruby +default_action :install + +action :install do + remote_file 'rvm_installer' do + path "#{Chef::Config[:file_cache_path]}/rvm_installer.sh" + source node['rvm']['installer_url'] + mode '755' + not_if { ::File.exist?("#{Chef::Config[:file_cache_path]}/rvm_installer.sh") } + action :create + end +end +``` + +## Remove Attributes + +It's best practice to use properties to change the behavior of resources. + +In the previous example example we used an attribute to change the `installer_url`. + +Instead, we should use a property that we can perform checks on. In this case, we can make sure we only accept a String. + +```ruby +#rvm/resources/rvm_ruby.rb +provides :rvm_ruby +default_action :install + +property installer_url, String, default: 'https://raw.githubusercontent.com/rvm/rvm/master/binscripts/rvm-installer' + +action :install do + remote_file 'rvm_installer' do + path "#{Chef::Config[:file_cache_path]}/rvm_installer.sh" + source new_resource.installer_url + mode '755' + not_if { ::File.exist?("#{Chef::Config[:file_cache_path]}/rvm_installer.sh") } + action :create + end +end +``` diff --git a/content/resources/custom/partials.md b/content/resources/custom/partials.md new file mode 100644 index 0000000..864f8ac --- /dev/null +++ b/content/resources/custom/partials.md @@ -0,0 +1,43 @@ ++++ +title = "Partials" + +[menu] + [menu.resources] + title = "Partials" + identifier = "resources/custom/partials" + parent = "resources/custom" + weight = 40 ++++ + +[InfoQ article](https://www.infoq.com/news/2020/05/chef-infra-16/) + +Resource partials are a way of allowing resources to share common code. We recommend using partials any time you need to share code across three or more resources. + +If you have three resources all which require the properties, `user` and `group` to be set. Instead of writing those property definitions in each of those files, you can write the property definition in one file and include it in the three resources. + +The `use` method works similarly to the Ruby `require_relative` command. + +Write the common properties and place them in a folder within the resources folder. This will stop Chef from considering them to be full resources. + +```ruby +# resources/_partial/_user.rb +property :user, + String, + default: 'haproxy' + +property :group, String + String, + default: 'haproxy' +``` + +Then include them in each of the three resources with the use directive: + +```ruby +# resources/backend.rb +use '_partial/_user' +``` + +```ruby +# resources/frontend.rb +use '_partial/_user' +``` diff --git a/content/resources/custom/unified_mode.md b/content/resources/custom/unified_mode.md new file mode 100644 index 0000000..d23ec05 --- /dev/null +++ b/content/resources/custom/unified_mode.md @@ -0,0 +1,165 @@ ++++ +title = "About Unified Mode" +draft = false + +[menu] + [menu.resources] + title = "Unified Mode" + identifier = "resources/custom/unified_mode.md Use Unified Mode" + parent = "resources/custom" + weight = 60 ++++ + +{{< readfile file="content/reusable/md/unified_mode_overview.md" >}} + +## Availability + +{{< readfile file="content/reusable/md/unified_mode_client_releases.md" >}} + +## Enable Unified Mode + +{{< readfile file="content/reusable/md/unified_mode_enable.md" >}} + +## Unified Mode isolation + +If a Unified Mode resource calls a non-Unified Mode resource, the called resource isn't executed in Unified Mode. +Each resource maintains its own state whether it's in Unified Mode or not. +You don't need to modify a custom resource that calls a Unified Mode resource since the calling context won't affect the resource's execution. +Resources using Unified Mode may call resources not using Unified Mode and vice versa. + +## Benefits of Unified Mode + +### Single-pass execution + +In Unified Mode, the Chef Infra Language executes from top to bottom, eliminating the compile and converge phases. + +With the deferred execution of resources to converge time, the user has to understand many different details of the Ruby parser to understand what constructs relate to Chef Infra resources and what constructs are parts of the core Ruby language to determine when those expression are executed. All that complexity is removed in Unified Mode. + +### Elimination of lazy blocks + +Several aspects of the Chef Infra Language still work but are no longer necessary in Unified Mode. +Unified Mode eliminates the need for lazy blocks and the need to lazy Ruby code through a Ruby block. + +### Rescue blocks and other Ruby constructs work correctly + +In Unified Mode, it's now easy to write a rescue wrapper around a Chef Infra resource: + +```ruby +begin + execute "a command that fails" do + command "/bin/false" + end +rescue Mixlib::ShellOut::ShellCommandFailed => e + raise "failing because /bin/false returned a failed exit status" +end +``` + +## Examples + +### Basic example + +A simple motivating example is to have a resource that downloads a JSON message using the [remote_file]({{< relref "/resources/bundled/remote_file" >}}) resource, parse the JSON using the [ruby_block]({{< relref "/resources/bundled/ruby_block" >}}), and then render a value into a [file]({{< relref "/resources/bundled/file" >}}) or [template]({{< relref "/resources/bundled/template" >}}) resource. + +Without Unified Mode, correctly writing this simple resource is complicated: + +```ruby +provides :downloader + +action :doit do + remote_file "/tmp/users.json" do + source "https://jsonplaceholder.typicode.com/users" + end + + array = nil + + ruby_block "convert" do + block do + array = FFI_Yajl::Parser.parse(IO.read("/tmp/users.json")) + end + end + + file "/tmp/phone" do + content lazy { array.last["phone"] } + end +end +``` + +Since the remote_file and file resources execute at converge time, the Ruby code to parse the JSON needs to be wrapped in a `ruby_block` resource, the local variable then needs to be declared outside of that scope (requiring a deep knowledge of Ruby variable scoping rules), and then the content rendered into the file resource must be wrapped with `lazy` since the Ruby parses all arguments of properties at compile time instead of converge time. + +Unified Mode simplifies this resource: + +```ruby +unified_mode true + +provides :downloader + +action :doit do + remote_file "/tmp/users.json" do + source "https://jsonplaceholder.typicode.com/users" + end + + array = FFI_Yajl::Parser.parse(IO.read("/tmp/users.json")) + + file "/tmp/phone" do + content array.last["phone"] + end +end +``` + +Unified Mode eliminates the need for the `ruby_block` resource, the `lazy` evaluation, and the variable declaration, simplifying how the cookbook is authored. + +### Recovery and exception handling + +Another advantage is in error recovery and the use of rescue. + +```ruby +unified_mode true + +provides :redis_install + +action :install do + version = "5.0.5" + + # the downloading of this file acts as a guard for all the later + # resources -- but if the download is successful while the later + # resources fail for some transient issue, will won't redownload on + # the next run -- we lose our edge trigger. + # + remote_file "/tmp/redis-#{version}.tar.gz" do + source "http://download.redis.io/releases/redis-#{version}.tar.gz" + notifies :run, "execute[unzip_redis_archive]", :immediately + end + + begin + execute "unzip_redis_archive" do + command "tar xzf redis-#{version}.tar.gz" + cwd "/tmp" + action :nothing + notifies :run, "execute[build_and_install_redis]", :immediately + end + + execute "build_and_install_redis" do + command 'make && make install' + cwd "/tmp/redis-#{version}" + action :nothing + end + rescue Exception + file "/tmp/redis-#{version}.tar.gz" do + action :delete + end + raise + end +end +``` + +This simplified example shows how to trap exceptions from resources using normal Ruby syntax and to clean up the resource. Without Unified Mode, this syntax is impossible. Normally when the [execute]({{< relref "/resources/bundled/execute" >}}) resources are parsed, they only create the objects in the `resource_collection` to later be evaluated so that no exception is thrown while Ruby is parsing the `action` block. Every action is delayed to the later converge phase. In Unified Mode, the resource runs when Ruby is done parsing its block, so exceptions happen in-line with Ruby parsing and the rescue clause now works as expected. + +This is useful because the TAR extraction throws an exception (for example, the node could be out of disk space), which deletes the TAR file. The next time Chef Infra Client runs, the TAR file will be redownload. If the resource didn't have file cleanup after an exception, the TAR file would remain on the client node even though the resource isn't complete and the extraction didn't happen, leaving the resource in a broken, indeterminate state. + +{{< readfile file="content/reusable/md/unified_mode_actions_later_resources.md" >}} + +### Notifications and accumulators + +The accumulator pattern works unchanged. Notifications to the `:root` run context still behave identically. Since the compile and converge phases of custom resources both fire in the converge time (typically) of the enclosing `run_context`, the effect of eliminating the separate compile and converge phases of the custom resource has no visible effect from the outer context. + +{{< readfile file="content/reusable/md/unified_mode_troubleshooting.md" >}} diff --git a/content/reusable/README.md b/content/reusable/README.md new file mode 100644 index 0000000..f12c644 --- /dev/null +++ b/content/reusable/README.md @@ -0,0 +1,9 @@ + +# Directory for reusable files + + +Files in this directory are used in *more than one place* within the Chef docs. + +Store all files in subdirectories organized by file type. For example, all Markdown files should be in `content/reusable/md/` and all Ruby files are stored in `content/reusable/rb/`. + +Call these files using the [`readfile` shortcode](https://docs.chef.io/style/reuse/#readfile-shortcode). diff --git a/content/reusable/md/agentless_custom_resource_example.md b/content/reusable/md/agentless_custom_resource_example.md index 0fdd61e..d3e0b87 100644 --- a/content/reusable/md/agentless_custom_resource_example.md +++ b/content/reusable/md/agentless_custom_resource_example.md @@ -1,26 +1,31 @@ -The following custom resource example runs in Agentless Mode and updates the content of a file defined by the `path` property. +The following custom resource example checks for and creates a new directory and runs in Agentless: ```ruby -# Create a new resource that's available in Target Mode -provides :file_update, target_mode: true +provides :example_directory, target_mode: true +unified_mode true -property :path, String, name_property: true -property :content, String, default: "" - -default_action :update +property: directory, String load_current_value do |new_resource| - # Prefix any IO calls with ::TargetIO to use the IO abstraction - if ::TargetIO::File.exist?(new_resource.path) - content ::TargetIO::IO.read(new_resource.path) + dir = new_resource.directory + parsed = dir.match(%r{([^/]+$)}) + path = '' + if parsed + path = dir[0..(dir.length - parsed[1].length - 1)] + dir = parsed[1] + end + + tmp = __transport_connection.run_command( sprintf('ls -l %s | grep %s || echo -n', path, dir) ) + + if tmp.match(Regexp.new(dir)) + directory new_resource.directory end end -action :update do - converge_if_changed :content do - TargetIO.write(new_resource.path, new_resource.content) - # You can also use shell_out() here without any prefix +action :create do + converge_if_changed do + __transport_connection.run_command( sprintf('mkdir %s', new_resource.directory) ) end end ``` diff --git a/content/reusable/md/agentless_summary.md b/content/reusable/md/agentless_summary.md index de252d7..8625e9f 100644 --- a/content/reusable/md/agentless_summary.md +++ b/content/reusable/md/agentless_summary.md @@ -1 +1 @@ -Agentless Mode executes Chef Infra Client runs on nodes that don't have Chef Infra Client installed on them. +Agentless executes Chef Infra Client runs on nodes that don't have Chef Infra Client installed on them. diff --git a/content/reusable/md/chef.md b/content/reusable/md/chef.md new file mode 100644 index 0000000..0dfc8b3 --- /dev/null +++ b/content/reusable/md/chef.md @@ -0,0 +1,10 @@ +Chef Infra is a powerful automation platform that transforms +infrastructure into code. Whether you're operating in the cloud, +on-premises, or in a hybrid environment, Chef Infra automates how +infrastructure is configured, deployed, and managed across your network, +no matter its size. + +This diagram shows how you develop, test, and deploy your Chef Infra +code. + +![Diagram showing Chef Workstation with Chef Infra Server and Chef Infra Client](/images/start_chef.svg) diff --git a/content/reusable/md/chef_client_bootstrap_node.md b/content/reusable/md/chef_client_bootstrap_node.md new file mode 100644 index 0000000..20621d3 --- /dev/null +++ b/content/reusable/md/chef_client_bootstrap_node.md @@ -0,0 +1,9 @@ +A node is any physical, virtual, or cloud device that's configured and +maintained by an instance of Chef Infra Client. Bootstrapping installs +Chef Infra Client on a target system so that it can run as a client and +sets the node up to communicate with a Chef Infra Server. There are two +ways to do this: + +- Run the `knife bootstrap` command from a workstation. +- Perform an unattended install to bootstrap from the node itself, + without requiring SSH or WinRM connectivity. diff --git a/content/reusable/md/chef_client_bootstrap_stages.md b/content/reusable/md/chef_client_bootstrap_stages.md new file mode 100644 index 0000000..1a6445e --- /dev/null +++ b/content/reusable/md/chef_client_bootstrap_stages.md @@ -0,0 +1,36 @@ +The following diagram shows the stages of the bootstrap operation, +and the list below the diagram describes each of those stages in greater detail. + +![image](/images/chef_bootstrap.png) + +When you run `knife bootstrap` on a node for the first time, Chef Workstation, Infra Client, and Infra Server handle the following tasks: + +1. **Run `knife bootstrap`** + + Run the [`knife bootstrap`](https://docs.chef.io/workstation/knife_bootstrap/) subcommand from a workstation. Include the hostname, IP address, or FQDN of the target node as part of this command. Knife establishes an SSH or WinRM connection with the target system and runs the bootstrap script. + + By default, the first Chef Infra Client run has an empty run list. You can add a [run list](/policy/run_lists/) to the initial bootstrap operation using the [`--run-list`](https://docs.chef.io/workstation/knife_bootstrap/#node-options) option. + +1. **Get the install script** + + A shell script gets the most recent version of the [Chef Infra Client install script](https://docs.chef.io/chef_install_script/) (`install.sh` or `install.ps1`) from Chef. + +1. **Get the Chef Infra Client package** + + The install script gathers system-specific information, determines the correct package for Chef Infra Client, and downloads that package from Chef's downloads API. + +1. **Install Chef Infra Client** + + Chef Infra Client is installed on the target node using a system native package (.rpm, .msi, etc). + +1. **Start a Chef Infra Client run** + + When you first run `knife bootstrap`, Chef Workstation creates a `first-boot.json` file with some initial settings. + + On UNIX and Linux-based machines, the second shell script executes the `chef-client` binary with the `first-boot.json` file on the node. + + On Windows machines, the batch file that's derived from the `windows-chef-client-msi.erb` bootstrap template executes the `chef-client` binary with the `first-boot.json` file on the node. + +1. **Complete the Chef Infra Client run** + + The Chef Infra Client run proceeds using HTTPS (port 443) and registers the node with Chef Infra Server. diff --git a/content/reusable/md/chef_client_run.md b/content/reusable/md/chef_client_run.md new file mode 100644 index 0000000..aefda0b --- /dev/null +++ b/content/reusable/md/chef_client_run.md @@ -0,0 +1,85 @@ +A _Chef Infra Client run_ describes the steps Chef Infra Client takes to configure a node when you run the `chef-client` command. +The following diagram shows the various stages that occur during a Chef Infra Client run. + + + +![Flowchart diagram illustrating the sequential stages of a Chef Infra Client run, starting with getting configuration data and ending with waiting for the next run, with arrows connecting each step in a vertical flow.](/images/chef_run.svg) + +During every Chef Infra Client run, the following happens: + +1. **Get configuration data** + + Chef Infra Client gets process configuration data from the [`client.rb`](/install/config_rb_client/) file on the [node](/overview/nodes/) and then gets node configuration data from Ohai. + The node name is an important piece of configuration data. + Chef Infra Client gets the node name from the `node_name` attribute in the `client.rb` file or from Ohai. + If Ohai provides the node name, it's typically the FQDN for the node, which is always unique within an organization. + +1. **Authenticate to Chef Infra Server** + + Chef Infra Client [authenticates](https://docs.chef.io/server/auth/) to Chef Infra Server using an RSA private key and the Chef Infra Server API. + Authentication with Infra Server requires the node name. + If this is the first Chef Infra Client run for a node, the chef-validator generates an RSA private key. + +1. **Get and rebuild the node object** + + Chef Infra Client pulls down the node object from Chef Infra Server and then rebuilds it. + A node object contains the system attributes discovered by Ohai, the attributes set in Policyfiles or Cookbooks, and the run-list of cookbooks. + The first time Chef Infra Client runs on a node, it creates a node object from the default run-list. + A node that hasn't yet had a Chef Infra Client run won't have a node object or a Chef Infra Server entry for a node object. + On any subsequent Chef Infra Client runs, the rebuilt node object also contains the run-list from the previous Chef Infra Client run. + +1. **Expand the run-list** + + Chef Infra Client expands the [run-list](/policy/run_lists/) from the rebuilt node object and compiles a complete list of recipes in the exact order that they will be applied to the node. + +1. **Synchronize cookbooks** + + Chef Infra Client requests all the [cookbook files](/cookbooks/) (including recipes, templates, resources, providers, attributes, and libraries) that it needs for every action identified in the run-list from Chef Infra Server. + Chef Infra Server responds to Chef Infra Client with the complete list of files. + Chef Infra Client compares the list of files to the files that already exist on the node from previous runs and then downloads a copy of every new or modified file from Chef Infra Server. + +1. **Reset node attributes** + + All attributes in the rebuilt node object are reset. + All attributes from attribute files, Policyfiles, and Ohai are loaded. + Attributes that are defined in attribute files are first loaded according to cookbook order. + For each cookbook, attributes in the `default.rb` file are loaded first, and then additional attribute files (if present) are loaded in lexical sort order. + If attribute files are found within any cookbooks that are listed as dependencies in the `metadata.rb` file, these are loaded as well. + All attributes in the rebuilt node object are updated with the attribute data according to attribute precedence. + When all the attributes are updated, the rebuilt node object is complete. + +1. **Compile the resource collection** + + Chef Infra Client identifies each resource in the node object and builds the resource collection. + Libraries are loaded first to ensure that all language extensions and Ruby classes are available to all resources. + Next, attributes are loaded, followed by custom resources. + Finally, all recipes are loaded in the order specified by the expanded run-list. + This is the _compile phase_. + +1. **Converge the node** + + Chef Infra Client configures the system based on the information that has been collected. + Each resource is executed in the order identified by the run-list and then by the order in which each resource is listed in each recipe. + Each resource defines an action to run, which configures a specific part of the system. + This process, called convergence, is also called the _execution phase_. + +1. **Update the node object and process exception and report handlers** + + When all the actions identified by resources in the resource collection have been completed and Chef Infra Client finishes successfully, Chef Infra Client updates the node object on Chef Infra Server with the node object built during the Chef Infra Client run. + Chef Infra Client will pull down this node object during the next Chef Infra Client run. + This makes the node object (and the data in the node object) available for search. + + Chef Infra Client always checks the resource collection for the presence of exception and report handlers. + If any are present, each one is processed appropriately. + +1. **Get and run Chef InSpec Compliance Profiles** + + After the Chef Infra Client run finishes, it begins the [Compliance Phase](/features/chef_compliance_phase/), which is a Chef InSpec run within the Chef Infra Client. Chef InSpec retrieves tests from either a legacy audit cookbook or a current InSpec profile. + +1. **Send or save Compliance Report** + + When all the InSpec tests finish running, Chef InSpec checks the reporting handlers defined in the legacy audit cookbook or in a current InSpec profile and processes them appropriately. + +1. **Stop and wait for the next run** + + When everything is configured and the Chef Infra Client run is complete, Chef Infra Client stops and waits until the next time it's asked to run. diff --git a/content/reusable/md/chef_client_summary.md b/content/reusable/md/chef_client_summary.md new file mode 100644 index 0000000..741ea66 --- /dev/null +++ b/content/reusable/md/chef_client_summary.md @@ -0,0 +1,7 @@ +Chef Infra Client is an agent that runs locally on every node that's under management by Chef Infra Server. When Chef Infra Client runs, it performs all of the steps required for bringing a node into the expected state, including: + +- Registering and authenticating the node with Chef Infra Server +- Synchronizing cookbooks from Chef Infra Server to the node +- Compiling the resource collection by loading each of the required cookbooks, including recipes, attributes, and all other dependencies +- Taking the appropriate and required actions to configure the node based on recipes and attributes +- Reporting summary information on the run to Chef Automate diff --git a/content/reusable/md/chef_manager.md b/content/reusable/md/chef_manager.md new file mode 100644 index 0000000..07a54d7 --- /dev/null +++ b/content/reusable/md/chef_manager.md @@ -0,0 +1,11 @@ +Chef management console is a web-based interface for the Chef Infra +Server that provides users a way to manage the following objects: + +- Nodes +- Cookbooks and recipes +- Roles +- Stores of JSON data (data bags), including encrypted data +- Environments +- Searching of indexed data +- User accounts and user data for the individuals who have permission + to log on to and access Chef Infra Server diff --git a/content/reusable/md/chef_repo_description.md b/content/reusable/md/chef_repo_description.md new file mode 100644 index 0000000..2a6a462 --- /dev/null +++ b/content/reusable/md/chef_repo_description.md @@ -0,0 +1,16 @@ +The chef-repo is a directory on your workstation that stores everything +you need to define your infrastructure with Chef Infra: + +- Cookbooks (including recipes, attributes, custom resources, libraries, and templates) +- Data bags +- Policyfiles + +The chef-repo directory should be synchronized with a version control +system, such as git. All of the data in the chef-repo should be treated +like source code. + +You'll use the `chef` and `knife` commands to upload data to the Chef +Infra Server from the chef-repo directory. Once uploaded, Chef Infra +Client uses that data to manage the nodes registered with the Chef Infra +Server and to ensure that it applies the right cookbooks, policyfiles, +and settings to the right nodes in the right order. diff --git a/content/reusable/md/chef_repo_many_users_same_knife.md b/content/reusable/md/chef_repo_many_users_same_knife.md new file mode 100644 index 0000000..86b331d --- /dev/null +++ b/content/reusable/md/chef_repo_many_users_same_knife.md @@ -0,0 +1,27 @@ +The config.rb configuration can include arbitrary Ruby code to extend +configuration beyond static values. This can be used to load +environmental variables from the workstation. This makes it possible to +write a single config.rb file that can be used by all users within your +organization. This single file can also be checked into your chef-repo, +allowing users to load different config.rb files based on which +chef-repo they execute the commands from. This can be especially useful +when each chef-repo points to a different Chef Infra Server or organization. + +Example config.rb: + +```ruby +current_dir = File.dirname(__FILE__) + user = ENV['CHEF_USER'] || ENV['USER'] + node_name user + client_key "#{ENV['HOME']}/chef-repo/.chef/#{user}.pem" + chef_server_url "https://api.opscode.com/organizations/#{ENV['ORGNAME']}" + syntax_check_cache_path "#{ENV['HOME']}/chef-repo/.chef/syntax_check_cache" + cookbook_path ["#{current_dir}/../cookbooks"] + cookbook_copyright "Your Company, Inc." + cookbook_license "Apache-2.0" + cookbook_email "cookbooks@yourcompany.com" + + # Amazon AWS + knife[:aws_access_key_id] = ENV['AWS_ACCESS_KEY_ID'] + knife[:aws_secret_access_key] = ENV['AWS_SECRET_ACCESS_KEY'] +``` diff --git a/content/reusable/md/chef_shell_advanced_debug.md b/content/reusable/md/chef_shell_advanced_debug.md new file mode 100644 index 0000000..992e65b --- /dev/null +++ b/content/reusable/md/chef_shell_advanced_debug.md @@ -0,0 +1,32 @@ +In chef-shell, it's possible to get verbose debugging using the tracing +feature in Interactive Ruby (IRb). chef-shell provides a shortcut for +turning tracing on and off. For example: + +```bash +chef > tracing on +tracing is on +=> nil +chef > +``` + +and: + +```bash +chef > tracing off +#0:(irb):2:Object:-: tracing off +#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:109:Shell::Extensions::ObjectCoreExtensions:>: def off +#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:110:Shell::Extensions::ObjectCoreExtensions:-: :off +#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:111:Shell::Extensions::ObjectCoreExtensions:<: end +#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:272:main:>: def tracing(on_or_off) +#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:273:main:-: conf.use_tracer = on_or_off.on_off_to_bool +#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:162:Shell::Extensions::Symbol:>: def on_off_to_bool +#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:163:Shell::Extensions::Symbol:-: to_s.on_off_to_bool +#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:149:Shell::Extensions::String:>: def on_off_to_bool +#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:150:Shell::Extensions::String:-: case self +#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:154:Shell::Extensions::String:-: false +#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:158:Shell::Extensions::String:<: end +#0:/opt/chef-workstation/embedded/lib/ruby/gems/2.6.0/gems/chef-15.8.23/lib/chef/shell/ext.rb:164:Shell::Extensions::Symbol:<: end +tracing is off +=> nil +chef > +``` diff --git a/content/reusable/md/chef_shell_breakpoints.md b/content/reusable/md/chef_shell_breakpoints.md new file mode 100644 index 0000000..1b631cd --- /dev/null +++ b/content/reusable/md/chef_shell_breakpoints.md @@ -0,0 +1,3 @@ +chef-shell allows the current position in a run-list to be manipulated +during a Chef Infra Client run. Add breakpoints to a recipe to take +advantage of this functionality. diff --git a/content/reusable/md/chef_shell_config.md b/content/reusable/md/chef_shell_config.md new file mode 100644 index 0000000..e9cec0c --- /dev/null +++ b/content/reusable/md/chef_shell_config.md @@ -0,0 +1,14 @@ +chef-shell determines which configuration file to load based on the +following: + +1. If a configuration file is specified using the `-c` option, + chef-shell will use the specified configuration file +1. If a NAMED_CONF is given, chef-shell will load + \~/.chef/NAMED_CONF/chef_shell.rb +1. If no NAMED_CONF is given chef-shell will load + \~/.chef/chef_shell.rb if it exists +1. If no chef_shell.rb can be found, chef-shell falls back to load: + - /etc/chef/client.rb if -z option is given. + - /etc/chef/solo.rb if --solo-legacy-mode option is given. + - .chef/config.rb if -s option is given. + - .chef/knife.rb if -s option is given. diff --git a/content/reusable/md/chef_shell_config_rb.md b/content/reusable/md/chef_shell_config_rb.md new file mode 100644 index 0000000..1875a22 --- /dev/null +++ b/content/reusable/md/chef_shell_config_rb.md @@ -0,0 +1,16 @@ +The chef-shell.rb file can be used to configure chef-shell in the same +way as the client.rb file is used to configure Chef Infra Client. For +example, to configure chef-shell to authenticate to the Chef Infra +Server, copy the `node_name`, `client_key`, and `chef_server_url` +settings from the config.rb file: + +```ruby +node_name 'your-knife-clientname' +client_key File.expand_path('~/.chef/my-client.pem') +chef_server_url 'https://api.opscode.com/organizations/myorg' +``` + +and then add them to the chef-shell.rb file. Other configuration +possibilities include disabling Ohai plugins (which will speed up the +chef-shell boot process) or including arbitrary Ruby code in the +chef-shell.rb file. diff --git a/content/reusable/md/chef_shell_debug_existing_recipe.md b/content/reusable/md/chef_shell_debug_existing_recipe.md new file mode 100644 index 0000000..4485d74 --- /dev/null +++ b/content/reusable/md/chef_shell_debug_existing_recipe.md @@ -0,0 +1,39 @@ +chef-shell can be used to debug existing recipes. The recipe first needs +to be added to a run-list for the node, so that it's cached when +starting chef-shell and then used for debugging. chef-shell will report +which recipes are being cached when it's started: + +```bash +loading configuration: none (standalone session) +Session type: standalone +Loading.............done. + +Welcome to the chef-shell 15.8.23 +For usage see https://docs.chef.io/chef_shell.html + +run `help' for help, `exit' or ^D to quit. + +chef (15.8.23)> +``` + +To just load one recipe from the run-list, go into the recipe and use +the `include_recipe` command. For example: + +```bash +chef > recipe_mode + chef:recipe > include_recipe "getting-started" + => [#< Chef::Recipe:0x10256f9e8 @cookbook_name="getting-started", + ... output truncated ... +``` + +To load all of the recipes from a run-list, use code similar to the +following: + +```ruby +node.run_list.expand(node.chef_environment).recipes.each do |r| + include_recipe r +end +``` + +After the recipes that are to be debugged have been loaded, use the +`run_chef` command to run them. diff --git a/content/reusable/md/chef_shell_manage.md b/content/reusable/md/chef_shell_manage.md new file mode 100644 index 0000000..cd42858 --- /dev/null +++ b/content/reusable/md/chef_shell_manage.md @@ -0,0 +1,131 @@ +When chef-shell is configured to access a Chef Infra Server, chef-shell +can list, show, search for and edit cookbooks, clients, nodes, roles, +environments, policyfiles, and data bags. + +The syntax for managing objects on Chef Infra Server is as follows: + +```bash +chef-shell -z named_configuration +``` + +Where: + +- `named_configuration` is an existing configuration file in + `~/.chef/named_configuration/chef_shell.rb`, such as `production`, + `staging`, or `test`. + +Once in chef-shell, commands can be run against objects as follows: + +```bash +chef (preprod) > items.command +``` + +Where: + +- `items` is the type of item to search for: `cookbooks`, `clients`, + `nodes`, `roles`, `environments` or a data bag. +- `command` is the command: `list`, `show`, `find`, or `edit`. + +For example, to list all of the nodes in a configuration named `preprod`, enter: + +```bash +chef (preprod) > nodes.list +``` + +Which will return something similar to: + +```bash +=> [node[i-f09a939b], node[i-049a936f], node[i-eaaaa581], node[i-9154b1fb], + node[i-6a213101], node[i-c2687aa9], node[i-7abeaa11], node[i-4eb8ac25], + node[i-9a2030f1], node[i-a06875cb], node[i-145f457f], node[i-e032398b], + node[i-dc8c98b7], node[i-6afdf401], node[i-f49b119c], node[i-5abfab31], + node[i-78b8ac13], node[i-d99678b3], node[i-02322269], node[i-feb4a695], + node[i-9e2232f5], node[i-6e213105], node[i-cdde3ba7], node[i-e8bfb083], + node[i-743c2c1f], node[i-2eaca345], node[i-aa7f74c1], node[i-72fdf419], + node[i-140e1e7f], node[i-f9d43193], node[i-bd2dc8d7], node[i-8e7f70e5], + node[i-78f2e213], node[i-962232fd], node[i-4c322227], node[i-922232f9], + node[i-c02728ab], node[i-f06c7b9b]] +``` + +The `list` command can take a code block, which will applied (but not +saved), to each object that's returned from the server. For example: + +```bash +chef (preprod) > nodes.list {|n| puts "#{n.name}: #{n.run_list}" } +``` + +will return something similar to: + +```bash +=> i-f09a939b: role[lb], role[preprod], recipe[aws] + i-049a936f: role[lb], role[preprod], recipe[aws] + i-9154b1fb: recipe[erlang], role[base], role[couchdb], role[preprod], + i-6a213101: role[chef], role[preprod] + # more... +``` + +The `show` command can be used to display a specific node. For example: + +```bash +chef (preprod) > load_balancer = nodes.show('i-f09a939b') +``` + +will return something similar to: + +```bash +=> node[i-f09a939b] +``` + +Or: + +```bash +chef (preprod) > load_balancer.ec2.public_hostname +``` + +will return something similar to: + +```bash +=> "ec2-111-22-333-44.compute-1.amazonaws.com" +``` + +The `find` command can be used to search Chef Infra Server from the +chef-shell. For example: + +```bash +chef (preprod) > pp nodes.find(:ec2_public_hostname => 'ec2*') +``` + +You can also format the results with a code block. For example: + +```bash +chef (preprod) > pp nodes.find(:ec2_public_hostname => 'ec2*') {|n| n.ec2.ami_id } and nil +``` + +will return something similar to: + +```bash +=> ["ami-f8927a91", + "ami-f8927a91", + "ami-a89870c1", + "ami-a89870c1", + "ami-a89870c1", + "ami-a89870c1", + "ami-a89870c1" + # and more... +``` + +Or: + +```bash +chef (preprod) > amis = nodes.find(:ec2_public_hostname => 'ec2*') {|n| n.ec2.ami_id } +chef (preprod) > puts amis.uniq.sort +``` + +will return something similar to: + +```bash +=> ami-4b4ba522 + ami-a89870c1 + ami-eef61587 + ami-f8927a91 +``` diff --git a/content/reusable/md/chef_shell_modes.md b/content/reusable/md/chef_shell_modes.md new file mode 100644 index 0000000..a2e8f9e --- /dev/null +++ b/content/reusable/md/chef_shell_modes.md @@ -0,0 +1,30 @@ +chef-shell is tool that's run using an Interactive Ruby (IRb) session. +chef-shell currently supports recipe and attribute file syntax, as well +as interactive debugging features. chef-shell has three run modes: + + ++++ + + + + + + + + + + + + + + + + + + + + +
ModeDescription
StandaloneDefault. No cookbooks are loaded, and the run-list is empty.
Solochef-shell acts as a Chef Solo Client. It attempts to load the chef-solo configuration file at ~/.chef/config.rb and any JSON attributes passed. If the JSON attributes set a run-list, it will be honored. Cookbooks will be loaded in the same way that chef-solo loads them. chef-solo mode is activated with the -s or --solo command line option, and JSON attributes are specified in the same way as for chef-solo, with -j /path/to/chef-solo.json.
Clientchef-shell acts as a Chef Infra Client. During startup, it reads the Chef Infra Client configuration file from ~/.chef/client.rb and contacts Chef Infra Server to get the node's run_list, attributes, and cookbooks. Chef Infra Client mode is activated with the -z or --client options. You can also specify the configuration file with -c CONFIG and the server URL with -S SERVER_URL.
diff --git a/content/reusable/md/chef_shell_run_as_chef_client.md b/content/reusable/md/chef_shell_run_as_chef_client.md new file mode 100644 index 0000000..239c656 --- /dev/null +++ b/content/reusable/md/chef_shell_run_as_chef_client.md @@ -0,0 +1,14 @@ +By default, chef-shell loads in standalone mode and doesn't connect to +Chef Infra Server. The chef-shell can be run as a Chef Infra Client +to verify functionality that's only available when Chef Infra Client +connects to Chef Infra Server, such as search functionality or +accessing data stored in data bags. + +chef-shell can use the same credentials as knife when connecting to a +Chef Infra Server. Make sure that the settings in chef-shell.rb are the +same as those in config.rb, and then use the `-z` option as part of the +command. For example: + +```bash +chef-shell -z +``` diff --git a/content/reusable/md/chef_shell_step_through_run_list.md b/content/reusable/md/chef_shell_step_through_run_list.md new file mode 100644 index 0000000..4cc6e31 --- /dev/null +++ b/content/reusable/md/chef_shell_step_through_run_list.md @@ -0,0 +1,89 @@ +To explore how using the **breakpoint** to manually step through a Chef +Infra Client run, create a simple recipe in chef-shell: + +```bash +chef > recipe_mode + chef:recipe > echo off + chef:recipe > file "/tmp/before-breakpoint" + chef:recipe > breakpoint "foo" + chef:recipe > file "/tmp/after-breakpoint" +``` + +and then run Chef Infra Client: + +```bash +chef:recipe > run_chef + [Fri, 15 Jan 2020 14:17:49 -0800] DEBUG: Processing file[/tmp/before-breakpoint] + [Fri, 15 Jan 2020 14:17:49 -0800] DEBUG: file[/tmp/before-breakpoint] using Chef::Provider::File + [Fri, 15 Jan 2020 14:17:49 -0800] INFO: Creating file[/tmp/before-breakpoint] at /tmp/before-breakpoint + [Fri, 15 Jan 2020 14:17:49 -0800] DEBUG: Processing [./bin/../lib/chef/mixin/recipe_definition_dsl_core.rb:56:in 'new'] + [Fri, 15 Jan 2020 14:17:49 -0800] DEBUG: [./bin/../lib/chef/mixin/recipe_definition_dsl_core.rb:56:in 'new'] using Chef::Provider::Breakpoint +``` + +Chef Infra Client ran the first resource before the breakpoint +(`file[/tmp/before-breakpoint]`), but then stopped after execution. Chef +Infra Client attempted to name the breakpoint after its position in the +source file, but Chef Infra Client was confused because the resource was +entered interactively. From here, chef-shell can resume the interrupted +Chef Infra Client run: + +```bash +chef:recipe > chef_run.resume + [Fri, 15 Jan 2020 14:27:08 -0800] INFO: Creating file[/tmp/after-breakpoint] at /tmp/after-breakpoint +``` + +A quick view of the `/tmp` directory shows that the following files were +created: + +```bash +after-breakpoint +before-breakpoint +``` + +You can rewind and step through a Chef Infra Client run: + +```bash +chef:recipe > Chef::Log.level = :debug # debug logging won't turn on automatically in this case + => :debug + chef:recipe > chef_run.rewind + => 0 + chef:recipe > chef_run.step + [Fri, 15 Jan 2020 14:40:52 -0800] DEBUG: Processing file[/tmp/before-breakpoint] + [Fri, 15 Jan 2020 14:40:52 -0800] DEBUG: file[/tmp/before-breakpoint] using Chef::Provider::File + => 1 + chef:recipe > chef_run.step + [Fri, 15 Jan 2020 14:40:54 -0800] DEBUG: Processing [./bin/../lib/chef/mixin/recipe_definition_dsl_core.rb:56:in 'new'] + [Fri, 15 Jan 2020 14:40:54 -0800] DEBUG: [./bin/../lib/chef/mixin/recipe_definition_dsl_core.rb:56:in 'new'] using Chef::Provider::Breakpoint + => 2 + chef:recipe > chef_run.step + [Fri, 15 Jan 2020 14:40:56 -0800] DEBUG: Processing file[/tmp/after-breakpoint] + [Fri, 15 Jan 2020 14:40:56 -0800] DEBUG: file[/tmp/after-breakpoint] using Chef::Provider::File + => 3 +``` + +From the output, the rewound run-list is shown, but when the resources +are executed again, they will repeat their checks for the existence of +files. If they exist, Chef Infra Client will skip creating them. If the +files are deleted, then: + +```bash +chef:recipe > ls("/tmp").grep(/breakpoint/).each {|f| rm "/tmp/#{f}" } + => ["after-breakpoint", "before-breakpoint"] +``` + +Rewind, and then resume your Chef Infra Client run to get the expected +results: + +```bash +chef:recipe > chef_run.rewind + chef:recipe > chef_run.resume + [Fri, 15 Jan 2020 14:48:56 -0800] DEBUG: Processing file[/tmp/before-breakpoint] + [Fri, 15 Jan 2020 14:48:56 -0800] DEBUG: file[/tmp/before-breakpoint] using Chef::Provider::File + [Fri, 15 Jan 2020 14:48:56 -0800] INFO: Creating file[/tmp/before-breakpoint] at /tmp/before-breakpoint + [Fri, 15 Jan 2020 14:48:56 -0800] DEBUG: Processing [./bin/../lib/chef/mixin/recipe_definition_dsl_core.rb:56:in 'new'] + [Fri, 15 Jan 2020 14:48:56 -0800] DEBUG: [./bin/../lib/chef/mixin/recipe_definition_dsl_core.rb:56:in 'new'] using Chef::Provider::Breakpoint + chef:recipe > chef_run.resume + [Fri, 15 Jan 2020 14:49:20 -0800] DEBUG: Processing file[/tmp/after-breakpoint] + [Fri, 15 Jan 2020 14:49:20 -0800] DEBUG: file[/tmp/after-breakpoint] using Chef::Provider::File + [Fri, 15 Jan 2020 14:49:20 -0800] INFO: Creating file[/tmp/after-breakpoint] at /tmp/after-breakpoint +``` diff --git a/content/reusable/md/chef_shell_summary.md b/content/reusable/md/chef_shell_summary.md new file mode 100644 index 0000000..6f17c25 --- /dev/null +++ b/content/reusable/md/chef_shell_summary.md @@ -0,0 +1,4 @@ +chef-shell is a recipe debugging tool that allows the use of breakpoints +within recipes. chef-shell runs as an Interactive Ruby (IRb) session. +chef-shell supports both recipe and attribute file syntax, as well as +interactive debugging features. diff --git a/content/reusable/md/chef_solo_environments.md b/content/reusable/md/chef_solo_environments.md new file mode 100644 index 0000000..a31263c --- /dev/null +++ b/content/reusable/md/chef_solo_environments.md @@ -0,0 +1,40 @@ +An environment is defined using JSON or the Ruby DSL. chef-solo will +look for environments in `/var/chef/environments`, but this location can +be modified by changing the setting for `environment_path` in solo.rb. +For example, the following setting in solo.rb: + +```ruby +environment_path '/var/chef-solo/environments' +``` + +Environment data looks like the following in JSON: + +```json +{ + "name": "dev", + "default_attributes": { + "apache2": { + "listen_ports": [ + "80", + "443" + ] + } + }, + "json_class": "Chef::Environment", + "description": "", + "cookbook_versions": { + "couchdb": "= 11.0.0" + }, + "chef_type": "environment" + } +``` + +and like the following in the Ruby DSL: + +```ruby +name 'environment_name' +description 'environment_description' +cookbook OR cookbook_versions 'cookbook' OR 'cookbook' => 'cookbook_version' +default_attributes 'node' => { 'attribute' => %w(value value etc.) } +override_attributes 'node' => { 'attribute' => %w(value value etc.) } +``` diff --git a/content/reusable/md/chef_solo_summary.md b/content/reusable/md/chef_solo_summary.md new file mode 100644 index 0000000..1bc681b --- /dev/null +++ b/content/reusable/md/chef_solo_summary.md @@ -0,0 +1,24 @@ +chef-solo is a command that executes Chef Infra Client in a way that +doesn't require Chef Infra Server to converge cookbooks. +chef-solo uses Chef Infra Client's [Chef local +mode](/reference/ctl_chef_client/#run-in-local-mode), and **doesn't support** +the following functionality present in Chef Infra Client / server +configurations: + +- Centralized distribution of cookbooks +- A centralized API that interacts with and integrates infrastructure + components +- Authentication or authorization + + + +
+

Note

+
+ +chef-solo can be run as a daemon. + +
+
+ +The chef-solo executable is run as a command-line tool. diff --git a/content/reusable/md/chef_tags.md b/content/reusable/md/chef_tags.md new file mode 100644 index 0000000..7e93a43 --- /dev/null +++ b/content/reusable/md/chef_tags.md @@ -0,0 +1,2 @@ +A tag is a custom description that's applied to a node. +A tag, once applied, can be helpful when managing nodes using knife or when building recipes by providing alternate methods of grouping similar types of information. diff --git a/content/reusable/md/chefspec_summary.md b/content/reusable/md/chefspec_summary.md new file mode 100644 index 0000000..6d0fb1e --- /dev/null +++ b/content/reusable/md/chefspec_summary.md @@ -0,0 +1,7 @@ +Use ChefSpec to simulate the convergence of resources on a node: + +- Is an extension of RSpec, a behavior-driven development (BDD) + framework for Ruby +- Is the fastest way to test resources and recipes + + diff --git a/content/reusable/md/config_rb_client_dot_d_directories.md b/content/reusable/md/config_rb_client_dot_d_directories.md new file mode 100644 index 0000000..29f568e --- /dev/null +++ b/content/reusable/md/config_rb_client_dot_d_directories.md @@ -0,0 +1,25 @@ +You can use multiple configuration files by putting them in `.d` configuration directories, +for example `/etc/chef/client.d`. + +To use a `.d` directory, create a directory with the same name as the configuration file but replace the `.rb` suffix with `.d`. + +The default locations for `.d` directories in Chef Infra are: + +- For Chef Infra Client, use `/etc/chef/client.d`. +- For Chef development tooling such as knife, use `~/.chef/config.d`. +- For Chef Solo, use `/etc/chef/solo.d`. + +The standard `.rb` configuration file and all configuration `.rb` files in the `.d` directory are merged as one file. +For example, knife would load and merge the following files: + +- `~/.chef/config.rb` +- `~/.chef/config.d/company_settings.rb` +- `~/.chef/config.d/ec2_configuration.rb` + +Non-`.rb` files in a `.d` directory are ignored, for example `old_settings.rb.bak`. + +{{< note >}} + +If you have the same setting in multiple configuration files, ensure that it has the same value in all files. + +{{< /note >}} diff --git a/content/reusable/md/config_rb_client_summary.md b/content/reusable/md/config_rb_client_summary.md new file mode 100644 index 0000000..a74f955 --- /dev/null +++ b/content/reusable/md/config_rb_client_summary.md @@ -0,0 +1,9 @@ +The `client.rb` file configures Chef Infra Client on a node and has the following characteristics: + +- This file is loaded every time the `chef-client` executable is run. +- On Windows machines, the default location for this file is + `C:\chef\client.rb`. On all other systems the default location for + this file is `/etc/chef/client.rb`. +- Use the `--config` option from the command line to override the + default location of the configuration file. +- This file isn't created by default diff --git a/content/reusable/md/config_rb_ohai.md b/content/reusable/md/config_rb_ohai.md new file mode 100644 index 0000000..fde65b8 --- /dev/null +++ b/content/reusable/md/config_rb_ohai.md @@ -0,0 +1 @@ +Ohai configuration settings can be added to the client.rb file. diff --git a/content/reusable/md/config_rb_ohai_settings.md b/content/reusable/md/config_rb_ohai_settings.md new file mode 100644 index 0000000..05e2cca --- /dev/null +++ b/content/reusable/md/config_rb_ohai_settings.md @@ -0,0 +1,76 @@ +`ohai.directory` + +: The directory in which Ohai plugins are located. + +`ohai.disabled_plugins` + +: An array of Ohai plugins to be disabled on a node. The list of + plugins included in Ohai can be found in the [ohai/lib/ohai/plugins](https://github.com/chef/ohai/tree/main/lib/ohai/plugins) + source. For example, disabling a single plugin: + + ```ruby + ohai.disabled_plugins = [ + :MyPlugin + ] + ``` + + or disabling multiple plugins: + + ```ruby + ohai.disabled_plugins = [ + :MyPlugin, + :MyPlugin2, + :MyPlugin3 + ] + ``` + + When a plugin is disabled, the Chef Infra Client log file will + contain entries similar to: + + ```ruby + [2014-06-13T23:49:12+00:00] DEBUG: Skipping disabled plugin MyPlugin + ``` + +`ohai.hints_path` + +: The path to the file that contains hints for Ohai. + +`ohai.log_level` + +: The level of logging to be stored in a log file. + +`ohai.log_location` + +: The location of the log file. + +`ohai.plugin_path` + +: An array of paths at which Ohai plugins are located. Default value: + `[/ohai-9.9.9/lib/ohai/plugins]`. When custom Ohai + plugins are added, the paths must be added to the array. For + example, a single plugin: + + ```ruby + ohai.plugin_path << '/etc/chef/ohai_plugins' + ``` + + and for multiple plugins: + + ```ruby + ohai.plugin_path += [ + '/etc/chef/ohai_plugins', + '/path/to/other/plugins' + ] + ``` + + + +
+

Note

+
+ +The Ohai executable ignores settings in the client.rb file when Ohai is +run independently of Chef Infra Client. + +
+
diff --git a/content/reusable/md/cookbooks_attribute.md b/content/reusable/md/cookbooks_attribute.md new file mode 100644 index 0000000..1151a6e --- /dev/null +++ b/content/reusable/md/cookbooks_attribute.md @@ -0,0 +1,10 @@ +An attribute can be defined in a cookbook (or a recipe) and then used to +override the default settings on a node. When a cookbook is loaded +during a Chef Infra Client run, these attributes are compared to the +attributes that are already present on the node. Attributes that are +defined in attribute files are first loaded according to cookbook order. +For each cookbook, attributes in the `default.rb` file are loaded first, +and then additional attribute files (if present) are loaded in lexical +sort order. When the cookbook attributes take precedence over the +default attributes, Chef Infra Client applies those new settings and +values during a Chef Infra Client run on the node. diff --git a/content/reusable/md/cookbooks_metadata.md b/content/reusable/md/cookbooks_metadata.md new file mode 100644 index 0000000..6c06a3e --- /dev/null +++ b/content/reusable/md/cookbooks_metadata.md @@ -0,0 +1,9 @@ +Every cookbook requires a small amount of metadata. +The contents of the `metadata.rb` file provides information that helps Chef Infra Client and Server correctly deploy cookbooks to each node. + +A `metadata.rb` file is: + +- Located at the top level of a cookbook's directory structure. +- Compiled whenever a cookbook is uploaded to Chef Infra Server or when the `knife cookbook metadata` subcommand is run, and then stored as JSON data. +- Created automatically by knife whenever the `knife cookbook create` subcommand is run. +- Edited using a text editor, and then re-uploaded to Chef Infra Server as part of a cookbook upload. diff --git a/content/reusable/md/cookbooks_recipe.md b/content/reusable/md/cookbooks_recipe.md new file mode 100644 index 0000000..e52d014 --- /dev/null +++ b/content/reusable/md/cookbooks_recipe.md @@ -0,0 +1,12 @@ +A recipe is the most fundamental configuration element within the +organization. A recipe: + +- Is authored using Ruby, which is a programming language designed to read and behave in a predictable manner +- Is mostly a collection of [resources](/resources/bundled/), defined using patterns (resource names, attribute-value pairs, and actions); helper code is added around this using Ruby, when needed +- Must define everything that's required to configure part of a system +- Must be stored in a cookbook +- May be included in another recipe +- May use the results of a search query and read the contents of a data bag (including an encrypted data bag) +- May have a dependency on one (or more) recipes +- Must be added to a run-list before it can be used by Chef Infra Client +- Is always executed in the same order as listed in a run-list diff --git a/content/reusable/md/cookbooks_recipe_include_in_recipe.md b/content/reusable/md/cookbooks_recipe_include_in_recipe.md new file mode 100644 index 0000000..ea309c1 --- /dev/null +++ b/content/reusable/md/cookbooks_recipe_include_in_recipe.md @@ -0,0 +1,28 @@ +A recipe can include one (or more) recipes from cookbooks by using the +`include_recipe` method. When a recipe is included, the resources found +in that recipe will be inserted (in the same exact order) at the point +where the `include_recipe` keyword is located. + +The syntax for including a recipe is like this: + +```ruby +include_recipe 'recipe' +``` + +For example: + +```ruby +include_recipe 'apache2::mod_ssl' +``` + +Multiple recipes can be included within a recipe. For example: + +```ruby +include_recipe 'cookbook::setup' +include_recipe 'cookbook::install' +include_recipe 'cookbook::configure' +``` + +If a specific recipe is included more than once with the +`include_recipe` method or elsewhere in the run_list directly, only the +first instance is processed and subsequent inclusions are ignored. diff --git a/content/reusable/md/cookbooks_recipe_tags.md b/content/reusable/md/cookbooks_recipe_tags.md new file mode 100644 index 0000000..62955f3 --- /dev/null +++ b/content/reusable/md/cookbooks_recipe_tags.md @@ -0,0 +1,46 @@ +You can add tags, remove tags, and check if nodes have a specific tag. + +To add a tag in your recipe, use `tag` with the tag name you want to apply to a node. + +```ruby +tag('tag-name') +``` + +To test if a machine is tagged with a specific tag, use `tagged?` with the tag name. + +```ruby +tagged?('tag-name') +``` + +This will return `true` or `false`. + +`tagged?` also accepts an array as an argument. + +Remove a tag using `untag`. + +```ruby +untag('tag-name') +``` + +For example: + +```ruby +tag('test_node') + +if tagged?('test_node') + Chef::Log.info("Hey I'm #{node['tags']}") +end + +untag('test_node') + +unless tagged?('test_node') + Chef::Log.info('I am not tagged') +end +``` + +Will return something like this: + +```plain +[Thu, 22 Jul 2010 18:01:45 +0000] INFO: Hey I'm test_node +[Thu, 22 Jul 2010 18:01:45 +0000] INFO: I am not tagged +``` diff --git a/content/reusable/md/cookbooks_summary.md b/content/reusable/md/cookbooks_summary.md new file mode 100644 index 0000000..985690f --- /dev/null +++ b/content/reusable/md/cookbooks_summary.md @@ -0,0 +1,10 @@ +A cookbook is the fundamental unit of configuration and policy distribution in Chef Infra. + +A cookbook defines a scenario and contains everything that's required to support that scenario: + +- Recipes that specify which Chef Infra built-in resources to use, as well as the order in which they're to be applied +- Attribute values, which allow environment-based configurations such as `dev` or `production`. +- Custom Resources for extending Chef Infra beyond the built-in resources. +- Files and Templates for distributing information to systems. +- Custom Ohai Plugins for extending system configuration collection beyond the Ohai defaults. +- The `metadata.rb` file, which describes the cookbook itself and any dependencies it may have. diff --git a/content/reusable/md/cookbooks_version.md b/content/reusable/md/cookbooks_version.md new file mode 100644 index 0000000..0099840 --- /dev/null +++ b/content/reusable/md/cookbooks_version.md @@ -0,0 +1,11 @@ +A cookbook version represents a set of functionality that's different +from the cookbook on which it's based. A version may exist for many +reasons, such as ensuring the correct use of a third-party component, +updating a bug fix, or adding an improvement. A cookbook version is +defined using syntax and operators, may be associated with environments, +cookbook metadata, and/or run-lists, and may be frozen (to prevent +unwanted updates from being made). + +A cookbook version is maintained just like a cookbook, with regard to +source control, uploading it to Chef Infra Server, and how Chef +Infra Client applies that cookbook when configuring nodes. diff --git a/content/reusable/md/cookbooks_version_constraints_operators.md b/content/reusable/md/cookbooks_version_constraints_operators.md new file mode 100644 index 0000000..09c44fe --- /dev/null +++ b/content/reusable/md/cookbooks_version_constraints_operators.md @@ -0,0 +1,19 @@ +You can use the following operators: + +`=` +: Equal to + +`>` +: Greater than + +`<` +: Less than + +`>=` +: Greater than or equal to (also known as "optimistically greater than" or "optimistic") + +`<=` +: Less than or equal to + +`~>` +: Approximately greater than (also known as "pessimistically greater than" or "pessimistic") diff --git a/content/reusable/md/data_bag.md b/content/reusable/md/data_bag.md new file mode 100644 index 0000000..e867a60 --- /dev/null +++ b/content/reusable/md/data_bag.md @@ -0,0 +1,2 @@ +Data bags store global variables as JSON data. Data bags are indexed for +searching and can be loaded by a cookbook or accessed during a search. diff --git a/content/reusable/md/data_bag_encryption.md b/content/reusable/md/data_bag_encryption.md new file mode 100644 index 0000000..3655efd --- /dev/null +++ b/content/reusable/md/data_bag_encryption.md @@ -0,0 +1,21 @@ +A data bag item may be encrypted using [shared secret +encryption](https://en.wikipedia.org/wiki/Symmetric-key_algorithm). This +allows each data bag item to store confidential information (such as a +database password) or to be managed in a source control system (without +plain-text data appearing in revision history). Each data bag item may +be encrypted individually; if a data bag contains multiple encrypted +data bag items, these data bag items aren't required to share the same +encryption keys. + + + +
+

Note

+
+ +Because the contents of encrypted data bag items aren't visible to the +Chef Infra Server, search queries against data bags with encrypted items +won't return any results. + +
+
diff --git a/content/reusable/md/data_bag_encryption_secret_key.md b/content/reusable/md/data_bag_encryption_secret_key.md new file mode 100644 index 0000000..21596a5 --- /dev/null +++ b/content/reusable/md/data_bag_encryption_secret_key.md @@ -0,0 +1,19 @@ +Encrypting a data bag item requires a secret key. A secret key can be +created in any number of ways. For example, OpenSSL can be used to +generate a random number, which can then be used as the secret key: + +```bash +openssl rand -base64 512 | tr -d '\r\n' > encrypted_data_bag_secret +``` + +where `encrypted_data_bag_secret` is the name of the file which will +contain the secret key. For example, to create a secret key named +"my_secret_key": + +```bash +openssl rand -base64 512 | tr -d '\r\n' > my_secret_key +``` + +The `tr` command eliminates any trailing line feeds. Doing so avoids key +corruption when transferring the file between platforms with different +line endings. diff --git a/content/reusable/md/data_bag_item.md b/content/reusable/md/data_bag_item.md new file mode 100644 index 0000000..12d4e36 --- /dev/null +++ b/content/reusable/md/data_bag_item.md @@ -0,0 +1,21 @@ +A data bag is a container of related data bag items, where each +individual data bag item is a JSON file. knife can load a data bag item +by specifying the name of the data bag to which the item belongs and +then the filename of the data bag item. The only structural requirement +of a data bag item is that it must have an `id`: + +```json +{ + /* This is a supported comment style */ + // This style is also supported + "id": "ITEM_NAME", + "key": "value" +} +``` + +where + +- `key` and `value` are the `key:value` pair for each additional + attribute within the data bag item +- `/* ... */` and `// ...` show two ways to add comments to the data + bag item diff --git a/content/reusable/md/dsl_handler_event_types.md b/content/reusable/md/dsl_handler_event_types.md new file mode 100644 index 0000000..e6db7bb --- /dev/null +++ b/content/reusable/md/dsl_handler_event_types.md @@ -0,0 +1,355 @@ +The following table describes the events that may occur during a Chef +Infra Client run. Each of these events may be referenced in an `on` +method block by declaring it as the event type. + +`:run_start` + +: The start of a Chef Infra Client run. + +`:run_started` + +: The Chef Infra Client run has started. + +`:run_completed` + +: The Chef Infra Client run has completed. + +`:run_failed` + +: The Chef Infra Client run has failed. + +`:ohai_completed` + +: The Ohai run has completed. + +`:skipping_registration` + +: The Chef Infra Client isn't registering with Chef Infra Server because it already has a private key or because it doesn't need one. + +`:registration_start` + +: The Chef Infra Client is attempting to create a private key with which to register to Chef Infra Server. + +`:registration_completed` + +: The Chef Infra Client created its private key successfully. + +`:registration_failed` + +: The Chef Infra Client encountered an error and was unable to register with Chef Infra Server. + +`:node_load_start` + +: The Chef Infra Client is attempting to load node data from Chef Infra Server. + +`:node_load_success` + +: The Chef Infra Client successfully loaded node data from the policy builder. + +`:node_load_failed` + +: The Chef Infra Client encountered an error and was unable to load node data from Chef Infra Server. + +`:run_list_expand_failed` + +: The Chef Infra Client failed to expand the run-list. + +`:node_load_completed` + +: The Chef Infra Client successfully loaded node data from Chef Infra Server. Default and override attributes for roles have been computed, but aren't yet applied. + +`:policyfile_loaded` + +: The Policyfile was loaded. + +`:cookbook_resolution_start` + +: The Chef Infra Client is attempting to pull down the cookbook collection from Chef Infra Server. + +`:cookbook_resolution_failed` + +: The Chef Infra Client failed to pull down the cookbook collection from Chef Infra Server. + +`:cookbook_resolution_complete` + +: The Chef Infra Client successfully pulled down the cookbook collection from Chef Infra Server. + +`:cookbook_clean_start` + +: The Chef Infra Client is attempting to remove unneeded cookbooks. + +`:removed_cookbook_file` + +: The Chef Infra Client removed a file from a cookbook. + +`:cookbook_clean_complete` + +: The Chef Infra Client is done removing cookbooks and/or cookbook files. + +`:cookbook_sync_start` + +: The Chef Infra Client is attempting to synchronize cookbooks. + +`:synchronized_cookbook` + +: The Chef Infra Client is attempting to synchronize the named cookbook. + +`:updated_cookbook_file` + +: The Chef Infra Client updated the named file in the named cookbook. + +`:cookbook_sync_failed` + +: The Chef Infra Client was unable to synchronize cookbooks. + +`:cookbook_sync_complete` + +: The Chef Infra Client is finished synchronizing cookbooks. + +`:cookbook_gem_start` + +: The Chef Infra Client is collecting gems from the cookbooks. + +`:cookbook_gem_installing` + +: The Chef Infra Client is installing a cookbook gem. + +`:cookbook_gem_using` + +: The Chef Infra Client is using a cookbook gem. + +`:cookbook_gem_finished` + +: The Chef Infra Client finished installing cookbook gems. + +`:cookbook_gem_failed` + +: The Chef Infra Client failed to install cookbook gems. + +`:cookbook_compilation_start` + +: The Chef Infra Client created the run\_context and is starting cookbook compilation. + +`:library_load_start` + +: The Chef Infra Client is loading library files. + +`:library_file_loaded` + +: The Chef Infra Client successfully loaded the named library file. + +`:library_file_load_failed` + +: The Chef Infra Client was unable to load the named library file. + +`:library_load_complete` + +: The Chef Infra Client is finished loading library files. + +`:lwrp_load_start` + +: The Chef Infra Client is loading custom resources. + +`:lwrp_file_loaded` + +: The Chef Infra Client successfully loaded the named custom resource. + +`:lwrp_file_load_failed` + +: The Chef Infra Client was unable to load the named custom resource. + +`:lwrp_load_complete` + +: The Chef Infra Client is finished loading custom resources. + +`:ohai_plugin_load_start` + +: Ohai has started loading plugins. + +`:ohai_plugin_file_loaded` + +: Ohai has loaded a plugin. + +`:ohai_plugin_file_load_failed` + +: Ohai failed to load a plugin. + +`:ohai_plugin_load_complete` + +: Ohai has completed loading plugins. + +`:attribute_load_start` + +: The Chef Infra Client is loading attribute files. + +`:attribute_file_loaded` + +: The Chef Infra Client successfully loaded the named attribute file. + +`:attribute_file_load_failed` + +: The Chef Infra Client was unable to load the named attribute file. + +`:attribute_load_complete` + +: The Chef Infra Client is finished loading attribute files. + +`:definition_load_start` + +: The Chef Infra Client is loading definitions. + +`:definition_file_loaded` + +: The Chef Infra Client successfully loaded the named definition. + +`:definition_file_load_failed` + +: The Chef Infra Client was unable to load the named definition. + +`:definition_load_complete` + +: The Chef Infra Client is finished loading definitions. + +`:recipe_load_start` + +: The Chef Infra Client is loading recipes. + +`:recipe_file_loaded` + +: The Chef Infra Client successfully loaded the named recipe. + +`:recipe_file_load_failed` + +: The Chef Infra Client was unable to load the named recipe. + +`:recipe_not_found` + +: The Chef Infra Client was unable to find the named recipe. + +`:recipe_load_complete` + +: The Chef Infra Client is finished loading recipes. + +`:cookbook_compilation_complete` + +: The Chef Infra Client completed all cookbook compilation phases. + +`:converge_start` + +: The Chef Infra Client run converge phase has started. + +`:action_collection_registration` + +: Provides a reference to the action\_collection before cookbooks are compiled. + +`:converge_complete` + +: The Chef Infra Client run converge phase is complete. + +`:converge_failed` + +: The Chef Infra Client run converge phase has failed. + +`:control_group_started` + +: The named control group is being processed. + +`:control_example_success` + +: The named control group has been processed. + +`:control_example_failure` + +: The named control group's processing has failed. + +`:resource_action_start` + +: A resource action is starting. + +`:resource_skipped` + +: A resource action was skipped. + +`:resource_current_state_loaded` + +: A resource's current state was loaded. + +`:resource_after_state_loaded` + +: A resource's after state was loaded. + +`:resource_current_state_load_bypassed` + +: A resource's current state wasn't loaded because the resource doesn't support why-run mode. + +`:resource_bypassed` + +: A resource action was skipped because the resource doesn't support why-run mode. + +`:resource_update_applied` + +: A change has been made to a resource. (This event occurs for each change made to a resource.) + +`:resource_update_progress` + +: A resource sent a progress notification to the user to indicate overall progress of a long running operation. + +`:resource_failed_retriable` + +: A resource action has failed and will be retried. + +`:resource_failed` + +: A resource action has failed and won't be retried. + +`:resource_updated` + +: A resource requires modification. + +`:resource_up_to_date` + +: A resource is already correct. + +`:resource_completed` + +: All actions for the resource are complete. + +`:stream_opened` + +: A stream has opened. + +`:stream_closed` + +: A stream has closed. + +`:stream_output` + +: A chunk of data from a single named stream. + +`:handlers_start` + +: The handler processing phase of a Chef Infra Client run has started. + +`:handler_executed` + +: The named handler was processed. + +`:handlers_completed` + +: The handler processing phase of a Chef Infra Client run is complete. + +`:provider_requirement_failed` + +: An assertion declared by a provider has failed. + +`:whyrun_assumption` + +: An assertion declared by a provider has failed, but execution is allowed to continue because the Chef Infra Client is running in why-run mode. + +`:deprecation` + +: A deprecation message has been emitted. + +`:attribute_changed` + +: Prints out all the attribute changes in cookbooks or sets a policy that override attributes should never be used. diff --git a/content/reusable/md/dsl_handler_example_etcd_lock.md b/content/reusable/md/dsl_handler_example_etcd_lock.md new file mode 100644 index 0000000..ac7749b --- /dev/null +++ b/content/reusable/md/dsl_handler_example_etcd_lock.md @@ -0,0 +1,18 @@ +The following example shows how to prevent concurrent Chef Infra Client +runs from both holding a lock on etcd: + +```ruby +lock_key = "#{node.chef_environment}/#{node.name}" + +Chef.event_handler do + on :converge_start do |run_context| + Etcd.lock_acquire(lock_key) + end +end + +Chef.event_handler do + on :converge_complete do + Etcd.lock_release(lock_key) + end +end +``` diff --git a/content/reusable/md/dsl_handler_example_hipchat.md b/content/reusable/md/dsl_handler_example_hipchat.md new file mode 100644 index 0000000..31a5bb3 --- /dev/null +++ b/content/reusable/md/dsl_handler_example_hipchat.md @@ -0,0 +1,22 @@ +Event messages can be sent to a team communication tool like HipChat. +For example, if a Chef Infra Client run fails: + +```ruby +Chef.event_handler do + on :run_failed do |exception| + hipchat_notify exception.message + end +end +``` + +or send an alert on a configuration change: + +```ruby +Chef.event_handler do + on :resource_updated do |resource, action| + if resource.to_s == 'template[/etc/nginx/nginx.conf]' + Helper.hipchat_message("#{resource} was updated by chef") + end + end +end +``` diff --git a/content/reusable/md/dsl_handler_method_on.md b/content/reusable/md/dsl_handler_method_on.md new file mode 100644 index 0000000..04643a3 --- /dev/null +++ b/content/reusable/md/dsl_handler_method_on.md @@ -0,0 +1,33 @@ +Use the `on` method to associate an event type with a callback. The +callback defines what steps are taken if the event occurs during a Chef +Infra Client run and is defined using arbitrary Ruby code. The syntax is +as follows: + +```ruby +Chef.event_handler do + on :event_type do + # some Ruby + end +end +``` + +where + +- `Chef.event_handler` declares a block of code within a recipe that + is processed when the named event occurs during a Chef Infra Client + run +- `on` defines the block of code that will tell Chef Infra Client how + to handle the event +- `:event_type` is a valid exception event type, such as `:run_start`, + `:run_failed`, `:converge_failed`, `:resource_failed`, or + `:recipe_not_found` + +For example: + +```bash +Chef.event_handler do + on :converge_start do + puts "Ohai! I have started a converge." + end +end +``` diff --git a/content/reusable/md/dsl_handler_slide_send_email.md b/content/reusable/md/dsl_handler_slide_send_email.md new file mode 100644 index 0000000..89f3d8a --- /dev/null +++ b/content/reusable/md/dsl_handler_slide_send_email.md @@ -0,0 +1,8 @@ +Use the `on` method to create an event handler that sends email when a +Chef Infra Client run fails. This will require: + +- A way to tell Chef Infra Client how to send email +- An event handler that describes what to do when the `:run_failed` + event is triggered +- A way to trigger the exception and test the behavior of the event + handler diff --git a/content/reusable/md/dsl_handler_slide_send_email_handler.md b/content/reusable/md/dsl_handler_slide_send_email_handler.md new file mode 100644 index 0000000..d5e2175 --- /dev/null +++ b/content/reusable/md/dsl_handler_slide_send_email_handler.md @@ -0,0 +1,17 @@ +Invoke the library helper in a recipe: + +```ruby +Chef.event_handler do + on :run_failed do + HandlerSendEmail::Helper.new.send_email_on_run_failure( + Chef.run_context.node.name + ) + end +end +``` + +- Use `Chef.event_handler` to define the event handler +- Use the `on` method to specify the event type + +Within the `on` block, tell Chef Infra Client how to handle the event +when it's triggered. diff --git a/content/reusable/md/dsl_handler_slide_send_email_library.md b/content/reusable/md/dsl_handler_slide_send_email_library.md new file mode 100644 index 0000000..28bfdb5 --- /dev/null +++ b/content/reusable/md/dsl_handler_slide_send_email_library.md @@ -0,0 +1,22 @@ +Use a library to define the code that sends email when a Chef Infra +Client run fails. Name the file `helper.rb` and add it to a cookbook's +`/libraries` directory: + +```ruby +require 'net/smtp' + +module HandlerSendEmail + class Helper + def send_email_on_run_failure(node_name) + message = "From: Chef \n" + message << "To: Grant \n" + message << "Subject: Chef run failed\n" + message << "Date: #{Time.now.rfc2822}\n\n" + message << "Chef run failed on #{node_name}\n" + Net::SMTP.start('localhost', 25) do |smtp| + smtp.send_message message, 'chef@chef.io', 'grantmc@chef.io' + end + end + end +end +``` diff --git a/content/reusable/md/dsl_handler_slide_send_email_test.md b/content/reusable/md/dsl_handler_slide_send_email_test.md new file mode 100644 index 0000000..d5a702d --- /dev/null +++ b/content/reusable/md/dsl_handler_slide_send_email_test.md @@ -0,0 +1,10 @@ +Use the following code block to trigger the exception and have the Chef +Infra Client send email to the specified email address: + +```ruby +ruby_block 'fail the run' do + block do + raise 'deliberately fail the run' + end +end +``` diff --git a/content/reusable/md/dsl_handler_summary.md b/content/reusable/md/dsl_handler_summary.md new file mode 100644 index 0000000..126e9ad --- /dev/null +++ b/content/reusable/md/dsl_handler_summary.md @@ -0,0 +1,6 @@ +Use the Handler DSL to attach a callback to an event. If the event +occurs during a Chef Infra Client run, the associated callback is +executed. For example: + +- Sending email if a Chef Infra Client run fails +- Aggregating statistics about resources updated during a Chef Infra Client runs to StatsD diff --git a/content/reusable/md/environment.md b/content/reusable/md/environment.md new file mode 100644 index 0000000..c76c68b --- /dev/null +++ b/content/reusable/md/environment.md @@ -0,0 +1,10 @@ +An environment is a way to map an organization's real-life workflow to +what can be configured and managed when using Chef Infra. This mapping +is accomplished by setting attributes and pinning cookbooks at the +environment level. With environments, you can change cookbook +configurations depending on the system's designation. For example, by +designating different staging and production environments, you can then +define the correct URL of a database server for each environment. +Environments also allow organizations to move new cookbook releases from +staging to production with confidence by stepping releases through +testing environments before entering production. diff --git a/content/reusable/md/environment_attribute.md b/content/reusable/md/environment_attribute.md new file mode 100644 index 0000000..28b3337 --- /dev/null +++ b/content/reusable/md/environment_attribute.md @@ -0,0 +1,10 @@ +Attributes can be defined in an environment and then used to override +the default attributes in a cookbook. When an environment is applied +during a Chef Infra Client run, environment attributes are compared to +the attributes that are already present on the node. When the +environment attributes take precedence over the default attributes, Chef +Infra Client applies those new settings and values during a Chef Infra +Client run. + +Environment attributes can be set to either `default` attribute level or +an `override` attribute level. diff --git a/content/reusable/md/fips_intro_client.md b/content/reusable/md/fips_intro_client.md new file mode 100644 index 0000000..2a02339 --- /dev/null +++ b/content/reusable/md/fips_intro_client.md @@ -0,0 +1,30 @@ + + + +Federal Information Processing Standards (FIPS) is a United States +government computer security standard that specifies security +requirements for cryptography. The current version of the standard is +FIPS 140-2. Chef Infra Client can be configured to allow OpenSSL to +enforce FIPS-validated security during a Chef Infra Client run. This +will disable cryptography that's explicitly disallowed in +FIPS-validated software, including certain ciphers and hashing +algorithms. Any attempt to use any disallowed cryptography will cause +Chef Infra Client to throw an exception during a Chef Infra Client run. + + + +
+

Note

+
+ +Chef uses MD5 hashes to uniquely identify files that are stored on the +Chef Infra Server. MD5 is used only to generate a unique hash identifier +and isn't used for any cryptographic purpose. + +
+
+ +Notes about FIPS: + +- May be enabled for nodes running on Windows and Enterprise Linux platforms +- Should only be enabled for environments that require FIPS 140-2 compliance diff --git a/content/reusable/md/handler.md b/content/reusable/md/handler.md new file mode 100644 index 0000000..a4d2309 --- /dev/null +++ b/content/reusable/md/handler.md @@ -0,0 +1,3 @@ +Use a handler to identify situations that arise during a Chef Infra +Client run, and then tell Chef Infra Client how to handle these +situations when they occur. diff --git a/content/reusable/md/handler_community_handlers.md b/content/reusable/md/handler_community_handlers.md new file mode 100644 index 0000000..ae63f1c --- /dev/null +++ b/content/reusable/md/handler_community_handlers.md @@ -0,0 +1,76 @@ +The following open source handlers are available from the Chef +community: + + + +[Airbrake](https://github.com/timops/ohai-plugins/blob/master/win32_svc.rb) + +: A handler that sends exceptions (only) to Airbrake, an application that collects data and aggregates it for review. + +[Asynchronous Resources](https://github.com/rottenbytes/chef/tree/master/async_handler) + +: A handler that asynchronously pushes exception and report handler data to a STOMP queue, from which data can be processed into data storage. + +[Campfire](https://github.com/ampledata/chef-handler-campfire) + +: A handler that collects exception and report handler data and reports it to Campfire, a web-based group chat tool. + +[Datadog](https://github.com/DataDog/chef-handler-datadog) + +: A handler that collects Chef Infra Client stats and sends them into a Datadog newsfeed. + +[Graphite](https://github.com/imeyer/chef-handler-graphite/wiki) + +: A handler that collects exception and report handler data and reports it to Graphite, a graphic rendering application. + +[Graylog2 GELF](https://github.com/jellybob/chef-gelf/) + +: A handler that provides exception and report handler status (including changes) to a Graylog2 server, so that the data can be viewed using Graylog Extended Log Format (GELF). + +[Growl](https://rubygems.org/gems/chef-handler-growl) + +: A handler that collects exception and report handler data and then sends it as a Growl notification. + +[HipChat](https://github.com/mojotech/hipchat/blob/master/lib/hipchat/chef.rb) + +: A handler that collects exception handler data and sends it to HipChat, a hosted private chat service for companies and teams. + +[IRC Snitch](https://rubygems.org/gems/chef-irc-snitch) + +: A handler that notifies administrators (using Internet Relay Chat (IRC)) when a Chef Infra Client run fails. + +[Journald](https://github.com/marktheunissen/chef-handler-journald) + +: A handler that logs an entry to the systemd journal with the Chef Infra Client run status, exception details, configurable priority, and custom details. + +[net/http](https://github.com/b1-systems/chef-handler-httpapi/) + +: A handler that reports the status of a Chef run to any API using net/HTTP. + +[Simple Email](https://rubygems.org/gems/chef-handler-mail) + +: A handler that collects exception and report handler data and then uses pony to send email reports that are based on \`.erb\` (Embedded Ruby ) templates. + +[SNS](http://onddo.github.io/chef-handler-sns/) + +: A handler that notifies exception and report handler data and sends it to a SNS topic. + +[Slack](https://github.com/rackspace-cookbooks/chef-slack_handler) + +: A handler to send Chef Infra Client run notifications to a Slack channel. + +[Splunk Storm](http://ampledata.org/splunk_storm_chef_handler.html) + +: A handler that supports exceptions and reports for Splunk Storm. + +[Syslog](https://github.com/jblaine/syslog_handler) + +: A handler that logs basic essential information, such as about the success or failure of a Chef Infra Client run. + +[Updated Resources](https://rubygems.org/gems/chef-handler-updated-resources) + +: A handler that provides a simple way to display resources that were updated during a Chef Infra Client run. + +[ZooKeeper](http://onddo.github.io/chef-handler-zookeeper/) + +: A Chef report handler to send Chef run notifications to ZooKeeper. diff --git a/content/reusable/md/handler_type_exception_report.md b/content/reusable/md/handler_type_exception_report.md new file mode 100644 index 0000000..3f33085 --- /dev/null +++ b/content/reusable/md/handler_type_exception_report.md @@ -0,0 +1,23 @@ +Exception and report handlers are used to trigger certain behaviors in +response to specific situations, typically identified during a Chef +Infra Client run. + +- An exception handler is used to trigger behaviors when a defined + aspect of a Chef Infra Client run fails. +- A report handler is used to trigger behaviors when a defined aspect + of a Chef Infra Client run is successful. + +Both types of handlers can be used to gather data about a Chef Infra +Client run and can provide rich levels of data about all types of usage, +which can be used later for trending and analysis across the entire +organization. + +Exception and report handlers are made available to a Chef Infra Client +run in one of the following ways: + +- By adding the **chef_handler** resource to a recipe, and then + adding that recipe to the run-list for a node. (The + **chef_handler** resource is available from the **chef_handler** + cookbook.) +- By adding the handler to one of the following settings in the node's + client.rb file: `exception_handlers` and/or `report_handlers` diff --git a/content/reusable/md/handler_type_exception_report_run_from_recipe.md b/content/reusable/md/handler_type_exception_report_run_from_recipe.md new file mode 100644 index 0000000..e844b96 --- /dev/null +++ b/content/reusable/md/handler_type_exception_report_run_from_recipe.md @@ -0,0 +1,32 @@ +The **chef_handler** resource allows exception and report handlers to +be enabled from within recipes, which can then added to the run-list for +any node on which the exception or report handler should run. The +**chef_handler** resource is available from the **chef_handler** +cookbook. + +To use the **chef_handler** resource in a recipe, add code similar to +the following: + +```ruby +chef_handler 'name_of_handler' do + source '/path/to/handler/handler_name' + action :enable +end +``` + +For example, a handler for Growl needs to be enabled at the beginning of +a Chef Infra Client run: + +```ruby +chef_gem 'chef-handler-growl' +``` + +and then is activated in a recipe by using the **chef_handler** +resource: + +```ruby +chef_handler 'Chef::Handler::Growl' do + source 'chef/handler/growl' + action :enable +end +``` diff --git a/content/reusable/md/handler_type_start.md b/content/reusable/md/handler_type_start.md new file mode 100644 index 0000000..d8eecd4 --- /dev/null +++ b/content/reusable/md/handler_type_start.md @@ -0,0 +1,15 @@ +A start handler isn't loaded into a Chef Infra Client run from a +recipe, but is instead listed in the client.rb file using the +`start_handlers` attribute. The start handler must be installed on the +node and be available to Chef Infra Client before the start of a Chef +Infra Client run. Use the **chef-client** cookbook to install the start +handler. + +Start handlers are made available to a Chef Infra Client run in one of +the following ways: + +- By adding a start handler to the **chef-client** cookbook, which + installs the handler on the node so that it's available to Chef + Infra Client at the start of a Chef Infra Client run +- By adding the handler to one of the following settings in the node's + client.rb file: `start_handlers` diff --git a/content/reusable/md/handler_type_start_run_from_recipe.md b/content/reusable/md/handler_type_start_run_from_recipe.md new file mode 100644 index 0000000..06c9bb3 --- /dev/null +++ b/content/reusable/md/handler_type_start_run_from_recipe.md @@ -0,0 +1,18 @@ +The **chef-client** cookbook can be configured to automatically install +and configure gems that are required by a start handler. For example: + +```ruby +node.override['chef_client']['load_gems']['chef-reporting'] = { + require_name: 'chef_reporting', + action: :install, +} + +node.override['chef_client']['config']['start_handlers'] = [ + { + class: 'Chef::Reporting::StartHandler', + arguments: [], + }, +] + +include_recipe 'chef-client::config' +``` diff --git a/content/reusable/md/handler_types.md b/content/reusable/md/handler_types.md new file mode 100644 index 0000000..fa21c64 --- /dev/null +++ b/content/reusable/md/handler_types.md @@ -0,0 +1,13 @@ +There are three types of handlers: + +exception + +: An exception handler is used to identify situations that have caused a Chef Infra Client run to fail. An exception handler can be loaded at the start of a Chef Infra Client run by adding a recipe that contains the **chef_handler** resource to a node's run-list. An exception handler runs when the `failed?` property for the `run_status` object returns `true`. + +report + +: A report handler is used when a Chef Infra Client run succeeds and reports back on certain details about that Chef Infra Client run. A report handler can be loaded at the start of a Chef Infra Client run by adding a recipe that contains the **chef_handler** resource to a node's run-list. A report handler runs when the `success?` property for the `run_status` object returns `true`. + +start + +: A start handler is used to run events at the beginning of a Chef Infra Client run. A start handler can be loaded at the start of a Chef Infra Client run by adding the start handler to the `start_handlers` setting in the client.rb file or by installing the gem that contains the start handler by using the **chef_gem** resource in a recipe in the **chef-client** cookbook. (A start handler may not be loaded using the `chef_handler` resource.) diff --git a/content/reusable/md/infra_lang_data_bag.md b/content/reusable/md/infra_lang_data_bag.md new file mode 100644 index 0000000..f088597 --- /dev/null +++ b/content/reusable/md/infra_lang_data_bag.md @@ -0,0 +1,14 @@ +```ruby +data_bag('users') #=> ['sandy', 'jill'] +``` + +Iterate over the contents of the data bag to get the associated +`data_bag_item`: + +```ruby +data_bag('users').each do |user| + data_bag_item('users', user) +end +``` + +The `id` for each data bag item will be returned as a string. diff --git a/content/reusable/md/infra_lang_method_registry_data_exists.md b/content/reusable/md/infra_lang_method_registry_data_exists.md new file mode 100644 index 0000000..0007a0e --- /dev/null +++ b/content/reusable/md/infra_lang_method_registry_data_exists.md @@ -0,0 +1,3 @@ +Use the `registry_data_exists?` method to find out if a Microsoft +Windows registry key contains the specified data of the specified type +under the value. diff --git a/content/reusable/md/infra_lang_method_registry_data_exists_syntax.md b/content/reusable/md/infra_lang_method_registry_data_exists_syntax.md new file mode 100644 index 0000000..4459215 --- /dev/null +++ b/content/reusable/md/infra_lang_method_registry_data_exists_syntax.md @@ -0,0 +1,36 @@ +The syntax for the `registry_data_exists?` method is as follows: + +```ruby +registry_data_exists?( + KEY_PATH, + { name: 'NAME', type: TYPE, data: DATA }, + ARCHITECTURE +) +``` + +where: + +- `KEY_PATH` is the path to the registry key value. The path must + include the registry hive, which can be specified either as its full + name or as the 3- or 4-letter abbreviation. For example, both + `HKLM\SECURITY` and `HKEY_LOCAL_MACHINE\SECURITY` are both valid and + equivalent. The following hives are valid: `HKEY_LOCAL_MACHINE`, + `HKLM`, `HKEY_CURRENT_CONFIG`, `HKCC`, `HKEY_CLASSES_ROOT`, `HKCR`, + `HKEY_USERS`, `HKU`, `HKEY_CURRENT_USER`, and `HKCU`. +- `{ name: 'NAME', type: TYPE, data: DATA }` is a hash that contains + the expected name, type, and data of the registry key value +- `type:` represents the values available for registry keys in + Windows. Use `:binary` for REG_BINARY, `:string` for + 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. +- `ARCHITECTURE` is one of the following values: `:x86_64`, `:i386`, + or `:machine`. Set to `:i386` to read or write 32-bit registry keys + on 64-bit machines running Windows. Set to`:x86_64` to + force write to a 64-bit registry location, however Chef Infra Client + returns an exception if `:x86_64` is used on a 32-bit machine. Set + to `:machine` to allow Chef Infra Client to allow Chef Infra Client + to use the appropriate key location based on your node's + architecture. Default value: `:machine`. + +This method will return `true` or `false`. diff --git a/content/reusable/md/infra_lang_method_registry_get_subkeys.md b/content/reusable/md/infra_lang_method_registry_get_subkeys.md new file mode 100644 index 0000000..ca06730 --- /dev/null +++ b/content/reusable/md/infra_lang_method_registry_get_subkeys.md @@ -0,0 +1,2 @@ +Use the `registry_get_subkeys` method to get a list of registry key +values that are present for a Windows registry key. diff --git a/content/reusable/md/infra_lang_method_registry_get_subkeys_syntax.md b/content/reusable/md/infra_lang_method_registry_get_subkeys_syntax.md new file mode 100644 index 0000000..ecdfb4f --- /dev/null +++ b/content/reusable/md/infra_lang_method_registry_get_subkeys_syntax.md @@ -0,0 +1,25 @@ +The syntax for the `registry_get_subkeys` method is as follows: + +```ruby +subkey_array = registry_get_subkeys(KEY_PATH, ARCHITECTURE) +``` + +where: + +- `KEY_PATH` is the path to the registry key. The path must include + the registry hive, which can be specified either as its full name or + as the 3- or 4-letter abbreviation. For example, both + `HKLM\SECURITY` and `HKEY_LOCAL_MACHINE\SECURITY` are both valid and + equivalent. The following hives are valid: `HKEY_LOCAL_MACHINE`, + `HKLM`, `HKEY_CURRENT_CONFIG`, `HKCC`, `HKEY_CLASSES_ROOT`, `HKCR`, + `HKEY_USERS`, `HKU`, `HKEY_CURRENT_USER`, and `HKCU`. +- `ARCHITECTURE` is one of the following values: `:x86_64`, `:i386`, + or `:machine`. Set to `:i386` to read or write 32-bit registry keys + on 64-bit machines running Windows. Set to`:x86_64` to + force write to a 64-bit registry location, however Chef Infra Client + returns an exception if `:x86_64` is used on a 32-bit machine. Set + to `:machine` to allow Chef Infra Client to allow Chef Infra Client + to use the appropriate key location based on your node's + architecture. Default value: `:machine`. + +This returns an array of registry key values. diff --git a/content/reusable/md/infra_lang_method_registry_get_values.md b/content/reusable/md/infra_lang_method_registry_get_values.md new file mode 100644 index 0000000..9a24cc0 --- /dev/null +++ b/content/reusable/md/infra_lang_method_registry_get_values.md @@ -0,0 +1,2 @@ +Use the `registry_get_values` method to get the registry key values +(name, type, and data) for a Windows registry key. diff --git a/content/reusable/md/infra_lang_method_registry_get_values_syntax.md b/content/reusable/md/infra_lang_method_registry_get_values_syntax.md new file mode 100644 index 0000000..d5518b9 --- /dev/null +++ b/content/reusable/md/infra_lang_method_registry_get_values_syntax.md @@ -0,0 +1,25 @@ +The syntax for the `registry_get_values` method is as follows: + +```ruby +subkey_array = registry_get_values(KEY_PATH, ARCHITECTURE) +``` + +where: + +- `KEY_PATH` is the path to the registry key. The path must include + the registry hive, which can be specified either as its full name or + as the 3- or 4-letter abbreviation. For example, both + `HKLM\SECURITY` and `HKEY_LOCAL_MACHINE\SECURITY` are both valid and + equivalent. The following hives are valid: `HKEY_LOCAL_MACHINE`, + `HKLM`, `HKEY_CURRENT_CONFIG`, `HKCC`, `HKEY_CLASSES_ROOT`, `HKCR`, + `HKEY_USERS`, `HKU`, `HKEY_CURRENT_USER`, and `HKCU`. +- `ARCHITECTURE` is one of the following values: `:x86_64`, `:i386`, + or `:machine`. Set to `:i386` to read or write 32-bit registry keys + on 64-bit machines running Windows. Set to`:x86_64` to + force write to a 64-bit registry location, however Chef Infra Client + returns an exception if `:x86_64` is used on a 32-bit machine. Set + to `:machine` to allow Chef Infra Client to allow Chef Infra Client + to use the appropriate key location based on your node's + architecture. Default value: `:machine`. + +This returns an array of registry key values. diff --git a/content/reusable/md/infra_lang_method_registry_has_subkeys.md b/content/reusable/md/infra_lang_method_registry_has_subkeys.md new file mode 100644 index 0000000..e98a3d9 --- /dev/null +++ b/content/reusable/md/infra_lang_method_registry_has_subkeys.md @@ -0,0 +1,2 @@ +Use the `registry_has_subkeys?` method to find out if a Microsoft +Windows registry key has one (or more) values. diff --git a/content/reusable/md/infra_lang_method_registry_has_subkeys_syntax.md b/content/reusable/md/infra_lang_method_registry_has_subkeys_syntax.md new file mode 100644 index 0000000..a1a783e --- /dev/null +++ b/content/reusable/md/infra_lang_method_registry_has_subkeys_syntax.md @@ -0,0 +1,25 @@ +The syntax for the `registry_has_subkeys?` method is as follows: + +```ruby +registry_has_subkeys?(KEY_PATH, ARCHITECTURE) +``` + +where: + +- `KEY_PATH` is the path to the registry key. The path must include + the registry hive, which can be specified either as its full name or + as the 3- or 4-letter abbreviation. For example, both + `HKLM\SECURITY` and `HKEY_LOCAL_MACHINE\SECURITY` are both valid and + equivalent. The following hives are valid: `HKEY_LOCAL_MACHINE`, + `HKLM`, `HKEY_CURRENT_CONFIG`, `HKCC`, `HKEY_CLASSES_ROOT`, `HKCR`, + `HKEY_USERS`, `HKU`, `HKEY_CURRENT_USER`, and `HKCU`. +- `ARCHITECTURE` is one of the following values: `:x86_64`, `:i386`, + or `:machine`. Set to `:i386` to read or write 32-bit registry keys + on 64-bit machines running Windows. Set to`:x86_64` to + force write to a 64-bit registry location, however Chef Infra Client + returns an exception if `:x86_64` is used on a 32-bit machine. Set + to `:machine` to allow Chef Infra Client to allow Chef Infra Client + to use the appropriate key location based on your node's + architecture. Default value: `:machine`. + +This method will return `true` or `false`. diff --git a/content/reusable/md/infra_lang_method_registry_key_exists.md b/content/reusable/md/infra_lang_method_registry_key_exists.md new file mode 100644 index 0000000..2ee7b11 --- /dev/null +++ b/content/reusable/md/infra_lang_method_registry_key_exists.md @@ -0,0 +1,2 @@ +Use the `registry_key_exists?` method to find out if a Windows +registry key exists at the specified path. diff --git a/content/reusable/md/infra_lang_method_registry_key_exists_syntax.md b/content/reusable/md/infra_lang_method_registry_key_exists_syntax.md new file mode 100644 index 0000000..4858953 --- /dev/null +++ b/content/reusable/md/infra_lang_method_registry_key_exists_syntax.md @@ -0,0 +1,26 @@ +The syntax for the `registry_key_exists?` method is as follows: + +```ruby +registry_key_exists?(KEY_PATH, ARCHITECTURE) +``` + +where: + +- `KEY_PATH` is the path to the registry key. The path must include + the registry hive, which can be specified either as its full name or + as the 3- or 4-letter abbreviation. For example, both + `HKLM\SECURITY` and `HKEY_LOCAL_MACHINE\SECURITY` are both valid and + equivalent. The following hives are valid: `HKEY_LOCAL_MACHINE`, + `HKLM`, `HKEY_CURRENT_CONFIG`, `HKCC`, `HKEY_CLASSES_ROOT`, `HKCR`, + `HKEY_USERS`, `HKU`, `HKEY_CURRENT_USER`, and `HKCU`. +- `ARCHITECTURE` is one of the following values: `:x86_64`, `:i386`, + or `:machine`. Set to `:i386` to read or write 32-bit registry keys + on 64-bit machines running Windows. Set to`:x86_64` to + force write to a 64-bit registry location, however Chef Infra Client + returns an exception if `:x86_64` is used on a 32-bit machine. Set + to `:machine` to allow Chef Infra Client to allow Chef Infra Client + to use the appropriate key location based on your node's + architecture. Default value: `:machine`. + +This method will return `true` or `false`. (Any registry key values that +are associated with this registry key are ignored.) diff --git a/content/reusable/md/infra_lang_method_registry_value_exists.md b/content/reusable/md/infra_lang_method_registry_value_exists.md new file mode 100644 index 0000000..a537c38 --- /dev/null +++ b/content/reusable/md/infra_lang_method_registry_value_exists.md @@ -0,0 +1,3 @@ +Use the `registry_value_exists?` method to find out if a registry key +value exists. Use `registry_data_exists?` to test for the type and data +of a registry key value. diff --git a/content/reusable/md/infra_lang_method_registry_value_exists_syntax.md b/content/reusable/md/infra_lang_method_registry_value_exists_syntax.md new file mode 100644 index 0000000..9865217 --- /dev/null +++ b/content/reusable/md/infra_lang_method_registry_value_exists_syntax.md @@ -0,0 +1,37 @@ +The syntax for the `registry_value_exists?` method is as follows: + +```ruby +registry_value_exists?( + KEY_PATH, + { name: 'NAME' }, + ARCHITECTURE +) +``` + +where: + +- `KEY_PATH` is the path to the registry key. The path must include + the registry hive, which can be specified either as its full name or + as the 3- or 4-letter abbreviation. For example, both + `HKLM\SECURITY` and `HKEY_LOCAL_MACHINE\SECURITY` are both valid and + equivalent. The following hives are valid: `HKEY_LOCAL_MACHINE`, + `HKLM`, `HKEY_CURRENT_CONFIG`, `HKCC`, `HKEY_CLASSES_ROOT`, `HKCR`, + `HKEY_USERS`, `HKU`, `HKEY_CURRENT_USER`, and `HKCU`. +- `{ name: 'NAME' }` is a hash that contains the name of the registry + key value; if either `type:` or `:value` are specified in the hash, + they're ignored +- `type:` represents the values available for registry keys in + Windows. Use `:binary` for REG_BINARY, `:string` for + 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. +- `ARCHITECTURE` is one of the following values: `:x86_64`, `:i386`, + or `:machine`. Set to `:i386` to read or write 32-bit registry keys + on 64-bit machines running Windows. Set to`:x86_64` to + force write to a 64-bit registry location, however Chef Infra Client + returns an exception if `:x86_64` is used on a 32-bit machine. Set + to `:machine` to allow Chef Infra Client to allow Chef Infra Client + to use the appropriate key location based on your node's + architecture. Default value: `:machine`. + +This method will return `true` or `false`. diff --git a/content/reusable/md/infra_lang_method_search_filter_result.md b/content/reusable/md/infra_lang_method_search_filter_result.md new file mode 100644 index 0000000..c866efa --- /dev/null +++ b/content/reusable/md/infra_lang_method_search_filter_result.md @@ -0,0 +1,43 @@ +Use `:filter_result` as part of a search query to filter the search +output based on the pattern specified by a Hash. Only attributes in the +Hash will be returned. + +The syntax for the `search` method that uses `:filter_result` is as +follows: + +```ruby +search(:index, 'query', + filter_result: { 'foo' => [ 'abc' ], + 'bar' => [ '123' ], + 'baz' => %w(sea power), + } +).each do |result| + puts result['foo'] + puts result['bar'] + puts result['baz'] +end +``` + +where: + +- `:index` is of name of the index on Chef Infra Server against + which the search query will run: `:client`, `:data_bag_name`, + `:environment`, `:node`, and `:role` +- `'query'` is a valid search query against an object on the Chef + server +- `:filter_result` defines a Hash of values to be returned + +For example: + +```ruby +search(:node, 'role:web', + filter_result: { 'name' => [ 'name' ], + 'ip' => [ 'ipaddress' ], + 'kernel_version' => %w(kernel version), + } +).each do |result| + puts result['name'] + puts result['ip'] + puts result['kernel_version'] +end +``` diff --git a/content/reusable/md/infra_lang_method_windows_methods.md b/content/reusable/md/infra_lang_method_windows_methods.md new file mode 100644 index 0000000..4721c58 --- /dev/null +++ b/content/reusable/md/infra_lang_method_windows_methods.md @@ -0,0 +1,6 @@ +Six methods are present in the Chef Infra Language to help verify the registry +during a Chef Infra Client run on the Windows +platform---`registry_data_exists?`, `registry_get_subkeys`, +`registry_get_values`, `registry_has_subkeys?`, `registry_key_exists?`, +and `registry_value_exists?`---these helpers ensure the +**powershell_script** resource is idempotent. diff --git a/content/reusable/md/infra_lang_ruby.md b/content/reusable/md/infra_lang_ruby.md new file mode 100644 index 0000000..625c2b4 --- /dev/null +++ b/content/reusable/md/infra_lang_ruby.md @@ -0,0 +1 @@ +The Chef Infra Language is based on Ruby, allowing you to utilize the power of Ruby when the built-in language doesn't meet your needs out of the box. If you'd like to learn more about extending your Chef Infra code by using Ruby see our [Ruby Guide](/infra_language/ruby/) for further information on Ruby functionality. diff --git a/content/reusable/md/infra_lang_summary.md b/content/reusable/md/infra_lang_summary.md new file mode 100644 index 0000000..8cf352b --- /dev/null +++ b/content/reusable/md/infra_lang_summary.md @@ -0,0 +1 @@ +The Chef Infra Language is a comprehensive systems configuration language with resources and helpers for configuring operating systems. The language is primarily used in Chef Infra recipes and custom resources to tell the Chef Infra Client what actions to take to configure a system. The Chef Infra Language provides resources for system-level components such as packages, users, or firewalls, and it also includes helpers to allow you to make configuration decisions based on operating systems, clouds, virtualization hypervisors, and more. diff --git a/content/reusable/md/install_chef_client.md b/content/reusable/md/install_chef_client.md new file mode 100644 index 0000000..0b807a0 --- /dev/null +++ b/content/reusable/md/install_chef_client.md @@ -0,0 +1,16 @@ +The `knife bootstrap` command is a common way to install Chef Infra +Client on a node. The default for this approach assumes that a node can +access the Chef website so that it may download the Chef Infra Client +package from that location. + +The Chef Infra Client installer will detect the version of the operating +system, and then install the appropriate Chef Infra Client version using +a single command to install Chef Infra Client and all of its dependencies, +including an embedded version of Ruby, OpenSSL, parsers, libraries, +and command line utilities. + +The Chef Infra Client installer puts everything into a unique directory +(`/opt/chef/`) so that Chef Infra Client won't interfere with other +applications that may be running on the target machine. Once installed, +Chef Infra Client requires a few more configuration steps before it can +perform its first Chef Infra Client run on a node. diff --git a/content/reusable/md/install_chef_client_windows_as_scheduled_task.md b/content/reusable/md/install_chef_client_windows_as_scheduled_task.md new file mode 100644 index 0000000..56aded1 --- /dev/null +++ b/content/reusable/md/install_chef_client_windows_as_scheduled_task.md @@ -0,0 +1,15 @@ + + +To run Chef Infra Client at periodic intervals (so that it can check in with Chef Infra Server automatically), configure Chef Infra Client to run as a scheduled task. +You can do this using the MSI by selecting the **Chef Unattended Execution Options** > **Chef Infra Client Scheduled Task** option on the **Custom Setup** page. +Alternatively, you can create a Windows scheduled task with Schtasks after you install Chef Infra Client. + +For example: + +```powershell +SCHTASKS.EXE /CREATE /TN ChefClientSchTask /SC MINUTE /MO 30 /F /RU "System" /RP /RL HIGHEST /TR "cmd /c \"C:\opscode\chef\embedded\bin\ruby.exe C:\opscode\chef\bin\chef-client -L C:\chef\chef-client.log -c C:\chef\client.rb\"" +``` + +For more information, see [Microsoft's Schtasks.exe documentation](https://docs.microsoft.com/en-us/windows/win32/taskschd/schtasks). + +After you configure Chef Infra Client to run as a scheduled task, the default log file path is `c:\chef\chef-client.log`. diff --git a/content/reusable/md/libraries_summary.md b/content/reusable/md/libraries_summary.md new file mode 100644 index 0000000..c31b8fb --- /dev/null +++ b/content/reusable/md/libraries_summary.md @@ -0,0 +1,7 @@ +A library allows arbitrary Ruby code to be included in a cookbook. The +most common use for libraries is to write helpers that are used +throughout recipes and custom resources. A library file is a Ruby file +that's located within a cookbook's `/libraries` directory. Because a +library is built using Ruby, anything that can be done with Ruby can be +done in a library file, including advanced functionality such as +extending built-in Chef classes. diff --git a/content/reusable/md/manage_webui_policy_validation_reset_key.md b/content/reusable/md/manage_webui_policy_validation_reset_key.md new file mode 100644 index 0000000..c81b98e --- /dev/null +++ b/content/reusable/md/manage_webui_policy_validation_reset_key.md @@ -0,0 +1,26 @@ +To reset a chef-validator key: + +1. Open the Chef management console. + +1. Click **Policy**. + +1. Click **Clients**. + +1. Select a chef-validator key. + +1. Click the **Details** tab. + +1. Click **Reset Key**. + +1. In the **Reset Key** dialog box, confirm that the key should be + regenerated and click the **Reset Key** button: + + ![image](/images/step_manage_webui_admin_organization_reset_key.png) + +1. Copy the private key: + + ![image](/images/step_manage_webui_policy_client_reset_key_copy.png) + + or download and save the private key locally: + + ![image](/images/step_manage_webui_policy_client_reset_key_download.png) diff --git a/content/reusable/md/nameless_apt_update.md b/content/reusable/md/nameless_apt_update.md new file mode 100644 index 0000000..7469b45 --- /dev/null +++ b/content/reusable/md/nameless_apt_update.md @@ -0,0 +1,12 @@ +This resource can be **nameless**. Add the resource itself to your +recipe to get the default behavior: + +```ruby +apt_update +``` + +will behave the same as: + +```ruby +apt_update 'update' +``` diff --git a/content/reusable/md/nameless_build_essential.md b/content/reusable/md/nameless_build_essential.md new file mode 100644 index 0000000..8b90ca3 --- /dev/null +++ b/content/reusable/md/nameless_build_essential.md @@ -0,0 +1,12 @@ +This resource can be **nameless**. Add the resource itself to your +recipe to get the default behavior: + +```ruby +build_essential +``` + +will behave the same as: + +```ruby +build_essential 'install tools' +``` diff --git a/content/reusable/md/node.md b/content/reusable/md/node.md new file mode 100644 index 0000000..5123429 --- /dev/null +++ b/content/reusable/md/node.md @@ -0,0 +1,2 @@ +A node is any device---physical, virtual, cloud, network device, +etc.---that's under management by Chef Infra. diff --git a/content/reusable/md/node_attribute.md b/content/reusable/md/node_attribute.md new file mode 100644 index 0000000..178ab01 --- /dev/null +++ b/content/reusable/md/node_attribute.md @@ -0,0 +1,22 @@ +An attribute is a specific detail about a node. Attributes are used by Chef Infra Client to understand: + +- The current state of the node +- What the state of the node was at the end of the previous Chef Infra Client run +- What the state of the node should be at the end of the current Chef Infra Client run + +Attributes are defined by: + +- The node as saved on Chef Infra Server +- Attributes passed using JSON on the command line +- Cookbooks (in attribute files and/or recipes) +- Policyfiles + +During every Chef Infra Client run, Chef Infra Client builds the attribute list using: + +- Attributes passed using JSON on the command line +- Data about the node collected by [Ohai](/features/ohai/). +- The node object that was saved to Chef Infra Server at the end of the previous Chef Infra Client run. +- The rebuilt node object from the current Chef Infra Client run, after it's updated for changes to cookbooks (attribute files and/or recipes) and/or Policyfiles, and updated for any changes to the state of the node itself. + +After the node object is rebuilt, all of the attributes are compared, and then the node is updated based on attribute precedence. At the end of every Chef Infra Client run, the node object that defines the current state of the node is uploaded to Chef Infra Server so that it can be +indexed for search. diff --git a/content/reusable/md/node_attribute_allowlist.md b/content/reusable/md/node_attribute_allowlist.md new file mode 100644 index 0000000..165bf81 --- /dev/null +++ b/content/reusable/md/node_attribute_allowlist.md @@ -0,0 +1,68 @@ +Attributes that should be saved by a node may be allowlisted in the client.rb file. The allowlist is a hash of keys that specifies each attribute to be saved. + +Attributes are allowlisted by attribute type, with each attribute type being allowlisted independently. Each attribute type---`automatic`, `default`, `normal`, and `override`---may define allowlists by using the following settings in the client.rb file: + +`allowed_automatic_attributes` + +: A hash that allowlists `automatic` attributes, preventing non-allowlisted attributes from being saved. For example: `['network/interfaces/eth0']`. Default value: `nil`, all attributes are saved. If the hash is empty, no attributes are saved. + +`allowed_default_attributes` + +: A hash that allowlists `default` attributes, preventing non-allowlisted attributes from being saved. For example: `['filesystem/dev/disk0s2/size']`. Default value: `nil`, all attributes are saved. If the hash is empty, no attributes are saved. + +`allowed_normal_attributes` + +: A hash that allowlists `normal` attributes, preventing non-allowlisted attributes from being saved. For example: `['filesystem/dev/disk0s2/size']`. Default value: `nil`, all attributes are saved. If the hash is empty, no attributes are saved. + +`allowed_override_attributes` + +: A hash that allowlists `override` attributes, preventing non-allowlisted attributes from being saved. For example: `['map - autohome/size']`. Default value: `nil`, all attributes are saved. If the hash is empty, no attributes are saved. + + + +#### Allowlisting Ohai (automatic) attributes + +The recommended practice is to use `allowed_automatic_attributes` to allow specific attributes populated by Ohai's system information gathering. Ohai gathers a large number of attributes that can consume a significant amount of storage space on Chef Infra Server. Many of these attributes may be considered highly valuable, while others could be skipped without any impact to data available in search. Normal, default, and override attributes are typically much more important attributes used within cookbooks and are more likely to cause issues if they're omitted from an allowlist incorrectly. + +For example, automatic attribute data similar to: + +```json +{ + "filesystem" => { + "/dev/disk0s2" => { + "size" => "10mb" + }, + "map - autohome" => { + "size" => "10mb" + } + }, + "network" => { + "interfaces" => { + "eth0" => {...}, + "eth1" => {...}, + } + } +} +``` + +To allowlist the `network` attributes and prevent the other attributes from being saved, update the client.rb file: + +```ruby +allowed_automatic_attributes ['network/interfaces/'] +``` + +When a allowlist is defined, any attribute of that type that isn't specified in that attribute allowlist **won't** be saved. Based on the previous allowlist for automatic attributes, the `filesystem` and `map - autohome` attributes won't be saved, but the `network` attributes will. + +Leave the value empty to prevent all attributes of that attribute type from being saved: + +```ruby +allowed_automatic_attributes [] +``` + + + +For attributes that contain slashes (`/`) within the attribute value, such as the `filesystem` attribute `'/dev/diskos2'`, use an array. For example: + +```ruby +allowed_automatic_attributes [['filesystem', '/dev/diskos2']] +``` diff --git a/content/reusable/md/node_attribute_allowlist_warning.md b/content/reusable/md/node_attribute_allowlist_warning.md new file mode 100644 index 0000000..29881cf --- /dev/null +++ b/content/reusable/md/node_attribute_allowlist_warning.md @@ -0,0 +1,2 @@ +When attribute allowlist settings are used, only the attributes defined in a allowlist will be saved and any attribute that isn't defined in a allowlist won't be saved. Each attribute type is allowlisted independently of the other attribute types. For example, if `automatic_attribute_allowlist` defines attributes to be saved, but `normal_attribute_allowlist`, `default_attribute_allowlist`, and +`override_attribute_allowlist` aren't defined, then all normal attributes, default attributes, and override attributes are saved, as well as the automatic attributes that were specifically included through allowlisting. diff --git a/content/reusable/md/node_attribute_blocklist.md b/content/reusable/md/node_attribute_blocklist.md new file mode 100644 index 0000000..871de0b --- /dev/null +++ b/content/reusable/md/node_attribute_blocklist.md @@ -0,0 +1,83 @@ +Attributes are blocklisted by attribute type, with each attribute type being blocklisted independently in the `client.rb` file. + +The four attribute types are: + +- `automatic` +- `default` +- `normal` +- `override` + +The blocklist settings are: + +`blocked_automatic_attributes` + +: An array that blocklists `automatic` attributes, preventing blocklisted attributes from being saved. For example: `['packages']`. + + Default value: `nil`, all attributes are saved. + + If the array is empty, all attributes are saved. + +`blocked_default_attributes` + +: An array that blocklists `default` attributes, preventing blocklisted attributes from being saved. For example: `['filesystem/dev/disk0s2/size']`. + + Default value: `nil`, all attributes are saved. + + If the array is empty, all attributes are saved. + +`blocked_normal_attributes` + +: An array that blocklists `normal` attributes, preventing blocklisted attributes from being saved. For example: `['filesystem/dev/disk0s2/size']`. + + Default value: `nil`, all attributes are saved. + + If the array is empty, all attributes are saved. + +`blocked_override_attributes` + +: An array that blocklists `override` attributes, preventing blocklisted attributes from being saved. For example: `['map - autohome/size']`. + + Default value: `nil`, all attributes are saved. + + If the array is empty, all attributes are saved. + + + +#### Blocklisting Ohai (automatic) attributes + +Use `blocked_automatic_attributes` to block attributes populated by Ohai's system information gathering. + +Ohai gathers a large number of attributes that can consume a significant amount of storage space on Chef Infra Server. +Many of these attributes may be considered highly valuable, while others could be blocklisted without any impact to data available in search. +Normal, default, and override attributes are typically much more important attributes used within cookbooks and are more likely to cause issues if they're blocklisted incorrectly. + +##### Example + +The following shows an example of automatic attribute data. + +```json +{ + "filesystem" => { + "/dev/disk0s2" => { + "size" => "10mb" + }, + "map - autohome" => { + "size" => "10mb" + } + }, + "network" => { + "interfaces" => { + "eth0" => {...}, + "eth1" => {...}, + } + } +} +``` + +To blocklist the `filesystem` attributes and allow Infra Client to save the other attributes, update the `client.rb`. + +```ruby +blocked_automatic_attributes ['filesystem'] +``` + +This blocklist blocks Chef Infra Client from saving the `filesystem` and `map - autohome` attributes, but saves the `network` attributes. diff --git a/content/reusable/md/node_attribute_blocklist_warning.md b/content/reusable/md/node_attribute_blocklist_warning.md new file mode 100644 index 0000000..af5a852 --- /dev/null +++ b/content/reusable/md/node_attribute_blocklist_warning.md @@ -0,0 +1 @@ +When attribute blocklist settings are used, any attribute defined in a blocklist won't be saved to Chef Infra Server and any attribute that isn't defined in a blocklist will be saved. Each attribute type must be blocklisted independently of the other attribute types. For example, if `blocked_automatic_attributes` defines attributes that won't be saved, but `blocked_normal_attributes`, `blocked_default_attributes`, and `blocked_override_attributes` aren't defined, then all normal attributes, default attributes, and override attributes will be saved, as well as the automatic attributes that weren't specifically excluded through blocklisting. diff --git a/content/reusable/md/node_attribute_type_automatic.md b/content/reusable/md/node_attribute_type_automatic.md new file mode 100644 index 0000000..fb6f40a --- /dev/null +++ b/content/reusable/md/node_attribute_type_automatic.md @@ -0,0 +1,3 @@ +An `automatic` attribute contains data that's identified by Ohai at the +beginning of every Chef Infra Client run. An `automatic` attribute +can't be modified and always has the highest attribute precedence. diff --git a/content/reusable/md/node_attribute_type_default.md b/content/reusable/md/node_attribute_type_default.md new file mode 100644 index 0000000..4ce8dca --- /dev/null +++ b/content/reusable/md/node_attribute_type_default.md @@ -0,0 +1,3 @@ +A `default` attribute is automatically reset at the start of every Chef +Infra Client run and has the lowest attribute precedence. Use `default` +attributes as often as possible in cookbooks. diff --git a/content/reusable/md/node_attribute_type_normal.md b/content/reusable/md/node_attribute_type_normal.md new file mode 100644 index 0000000..2a0bec6 --- /dev/null +++ b/content/reusable/md/node_attribute_type_normal.md @@ -0,0 +1,3 @@ +A `normal` attribute is a setting that persists in the node object. A +`normal` attribute has a higher attribute precedence than a `default` +attribute. diff --git a/content/reusable/md/node_attribute_type_override.md b/content/reusable/md/node_attribute_type_override.md new file mode 100644 index 0000000..f3095db --- /dev/null +++ b/content/reusable/md/node_attribute_type_override.md @@ -0,0 +1,7 @@ +An `override` attribute is automatically reset at the start of every +Chef Infra Client run and has a higher attribute precedence than +`default`, `force_default`, and `normal` attributes. An `override` +attribute is most often specified in a recipe, but can be specified in +an attribute file, for a role, and/or for an environment. A cookbook +should be authored so that it uses `override` attributes only when +required. diff --git a/content/reusable/md/node_ctl_attribute.md b/content/reusable/md/node_ctl_attribute.md new file mode 100644 index 0000000..44f4581 --- /dev/null +++ b/content/reusable/md/node_ctl_attribute.md @@ -0,0 +1,37 @@ +Any other attribute type that's contained in this JSON file will be +treated as a `normal` attribute. Setting attributes at other precedence +levels isn't possible. For example, attempting to update `override` +attributes using the `-j` option: + +```json +{ + "name": "dev-99", + "description": "Install some stuff", + "override_attributes": { + "apptastic": { + "enable_apptastic": "false", + "apptastic_tier_name": "dev-99.bomb.com" + } + } +} +``` + +will result in a node object similar to: + +```json +{ + "name": "maybe-dev-99", + "normal": { + "name": "dev-99", + "description": "Install some stuff", + "override_attributes": { + "apptastic": { + "enable_apptastic": "false", + "apptastic_tier_name": "dev-99.bomb.com" + } + } + } +} +``` + + \ No newline at end of file diff --git a/content/reusable/md/node_ctl_run_list.md b/content/reusable/md/node_ctl_run_list.md new file mode 100644 index 0000000..efee287 --- /dev/null +++ b/content/reusable/md/node_ctl_run_list.md @@ -0,0 +1,16 @@ +Use this option to define a `run_list` object. For example, a JSON file +similar to: + +```json +"run_list": [ + "recipe[base]", + "recipe[foo]", + "recipe[bar]", + "role[webserver]" +], +``` + +may be used by running `chef-client -j path/to/file.json`. + +In certain situations this option may be used to update `normal` +attributes. diff --git a/content/reusable/md/node_run_list.md b/content/reusable/md/node_run_list.md new file mode 100644 index 0000000..70f51eb --- /dev/null +++ b/content/reusable/md/node_run_list.md @@ -0,0 +1,11 @@ +A run-list defines all of the information necessary for Chef to +configure a node into the desired state. A run-list is: + +- An ordered list of roles and/or recipes that are run in the exact + order defined in the run-list; if a recipe appears more than once in + the run-list, Chef Infra Client won't run it twice +- Always specific to the node on which it runs; nodes may have a + run-list that's identical to the run-list used by other nodes +- Stored as part of the node object on Chef Infra Server +- Maintained using knife and then uploaded from the workstation to the + Chef Infra Server, or maintained using Chef Automate diff --git a/content/reusable/md/node_run_list_empty.md b/content/reusable/md/node_run_list_empty.md new file mode 100644 index 0000000..857a3dc --- /dev/null +++ b/content/reusable/md/node_run_list_empty.md @@ -0,0 +1,9 @@ +Use an empty run-list to determine if a failed Chef Infra Client run has +anything to do with the recipes that are defined within that run-list. +This is a quick way to discover if the underlying cause of a Chef Infra +Client run failure is a configuration issue. If a failure persists even +if the run-list is empty, check the following: + +- Configuration settings in the config.rb file +- Permissions for the user to both Chef Infra Server and to the + node on which a Chef Infra Client run is to take place diff --git a/content/reusable/md/node_run_list_format.md b/content/reusable/md/node_run_list_format.md new file mode 100644 index 0000000..458b184 --- /dev/null +++ b/content/reusable/md/node_run_list_format.md @@ -0,0 +1,20 @@ +A run-list must be in one of the following formats: fully qualified, +cookbook, or default. Both roles and recipes must be in quotes, for +example: + +```json +"role[NAME]" +``` + +or + +```json +"recipe[COOKBOOK::RECIPE]" +``` + +Use a comma to separate roles and recipes when adding more than one item +the run-list: + +```json +"recipe[COOKBOOK::RECIPE],COOKBOOK::RECIPE,role[NAME]" +``` diff --git a/content/reusable/md/node_types.md b/content/reusable/md/node_types.md new file mode 100644 index 0000000..15e1702 --- /dev/null +++ b/content/reusable/md/node_types.md @@ -0,0 +1,39 @@ +The types of nodes that can be managed by Chef include, but aren't +limited to, the following: + + + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Node TypeDescription

A physical node is typically a server or a virtual machine, but it can be any active device attached to a network that's capable of sending, receiving, and forwarding information over a communications channel. In other words, a physical node is any active device attached to a network that can run a Chef Infra Client and also allow that Chef Infra Client to communicate with a Chef Infra Server.

A cloud-based node is hosted in an external cloud-based service, such as Amazon Web Services (AWS), OpenStack, Rackspace, Google Compute Engine, or Microsoft Azure. Plugins are available for knife that provide support for external cloud-based services. knife can use these plugins to create instances on cloud-based services. Once created, Chef Infra Client can be used to deploy, configure, and maintain those instances.

A virtual node is a machine that runs only as a software implementation, but otherwise behaves much like a physical machine.

A network node is any networking device---a switch, a router---that's being managed by a Chef Infra Client, such as networking devices by Juniper Networks, Arista, Cisco, and F5. Use Chef to automate common network configurations, such as physical and logical Ethernet link properties and VLANs, on these devices.

Containers are an approach to virtualization that allows a single operating system to host many working configurations, where each working configuration---a container---is assigned a single responsibility that's isolated from all other responsibilities. Containers are popular as a way to manage distributed and scalable applications and services.
diff --git a/content/reusable/md/notes_registry_key_not_if_only_if.md b/content/reusable/md/notes_registry_key_not_if_only_if.md new file mode 100644 index 0000000..9934277 --- /dev/null +++ b/content/reusable/md/notes_registry_key_not_if_only_if.md @@ -0,0 +1,4 @@ +This method can be used in recipes and from within the `not_if` and +`only_if` blocks in resources. This method isn't designed to create or +modify a registry key. If a registry key needs to be modified, use the +**registry_key** resource. diff --git a/content/reusable/md/notes_resource_based_on_package.md b/content/reusable/md/notes_resource_based_on_package.md new file mode 100644 index 0000000..65f1f0f --- /dev/null +++ b/content/reusable/md/notes_resource_based_on_package.md @@ -0,0 +1,6 @@ +In many cases, it's better to use the **package** resource instead of +this one. This is because when the **package** resource is used in a +recipe, Chef Infra Client will use details that are collected by Ohai at +the start of a Chef Infra Client run to determine the correct package +application. Using the **package** resource allows a recipe to be +authored in a way that allows it to be used across many platforms. diff --git a/content/reusable/md/notes_see_attributes_overview.md b/content/reusable/md/notes_see_attributes_overview.md new file mode 100644 index 0000000..94cf913 --- /dev/null +++ b/content/reusable/md/notes_see_attributes_overview.md @@ -0,0 +1,5 @@ +Attributes can be configured in cookbooks (attribute files and recipes), +roles, and environments. In addition, Ohai collects attribute data about +each node at the start of a Chef Infra Client run. See +[Attributes](/cookbooks/attributes/) for more information about how all of +these attributes fit together. diff --git a/content/reusable/md/ohai_attribute_list.md b/content/reusable/md/ohai_attribute_list.md new file mode 100644 index 0000000..ddb335b --- /dev/null +++ b/content/reusable/md/ohai_attribute_list.md @@ -0,0 +1,6 @@ +Ohai collects a list of automatic attributes at the start of each Chef +Infra Client run. This list will vary from organization to organization, +by server type, and by the platform that runs those servers. All the +attributes collected by Ohai are unmodifiable by Chef Infra Client. Run +the `ohai` command on a system to see which automatic attributes Ohai +has collected for a particular node. diff --git a/content/reusable/md/ohai_automatic_attribute.md b/content/reusable/md/ohai_automatic_attribute.md new file mode 100644 index 0000000..8fe0d31 --- /dev/null +++ b/content/reusable/md/ohai_automatic_attribute.md @@ -0,0 +1,39 @@ + + +An automatic attribute is a specific detail about a node, such as an IP address, a host name, or a list of loaded kernel modules. +Ohai detects automatic attributes and Chef Infra Client uses them to ensure that they're handled properly during every Chef Infra Client run. + +The most commonly accessed automatic attributes are: + +`node['platform']` +: The platform on which a node is running. This attribute helps determine which providers Chef Infra Client uses. + +`node['platform_family']` +: The platform family is a Chef Infra specific grouping of similar platforms where cookbook code can often be shared. For example, `rhel` includes Red Hat Linux, Oracle Linux, CentOS, and several other platforms that are almost identical to Red Hat Linux. + +`node['platform_version']` +: The version of the platform. This attribute helps determine which providers Chef Infra Client uses. + +`node['ipaddress']` +: The IP address for a node. If the node has a default route, this is the IPv4 address for the interface. If the node doesn't have a default route, the value for this attribute should be `nil`. The IP address for the default route is the recommended default value. + +`node['macaddress']` +: The MAC address for a node, determined by the same interface used to detect the `node['ipaddress']`. + +`node['fqdn']` +: The fully qualified domain name for a node. Chef Infra Client uses this as the name of a node unless otherwise set. + +`node['hostname']` +: The host name for the node. + +`node['domain']` +: The domain for the node. + +`node['recipes']` +: A list of recipes associated with a node (and part of that node's run-list). + +`node['roles']` +: A list of roles associated with a node (and part of that node's run-list). + +`node['ohai_time']` +: The time at which Ohai was last run. This attribute isn't commonly used in recipes, but it's saved to Chef Infra Server and can be accessed using the `knife status` subcommand. diff --git a/content/reusable/md/ohai_summary.md b/content/reusable/md/ohai_summary.md new file mode 100644 index 0000000..ff75f14 --- /dev/null +++ b/content/reusable/md/ohai_summary.md @@ -0,0 +1,16 @@ +Ohai is a tool for collecting system configuration data, which it then provides to Chef Infra Client to use in cookbooks. Chef Infra Client runs Ohai at the start of every Chef Infra run to determine system state. The attributes that Ohai collects are called `automatic attributes`. Chef Infra Client uses these attributes to ensure that nodes are in the desired state after each configuration run. + +The types of attributes Ohai collects include but aren't limited to: + +- Operating System +- Network +- Memory +- Disk +- CPU +- Kernel +- Host names +- Fully qualified domain names +- Virtualization +- Cloud provider metadata + +Ohai includes required and optional plugins to detect common configuration information. Ohai has a plugin model and language to write [custom plugins](/extension_apis/custom_plugins/) to collect additional system state information. diff --git a/content/reusable/md/policy_summary.md b/content/reusable/md/policy_summary.md new file mode 100644 index 0000000..ffeee0c --- /dev/null +++ b/content/reusable/md/policy_summary.md @@ -0,0 +1,13 @@ +Policy maps business and operational requirements, process, and workflow +to the following settings and objects stored on Chef Infra Server: + +- Roles define server types, such as _web server_ or _database server_. +- Environments define process, such as _dev_, _staging_, or _production_. +- Attributes define environment-specific details about a node that are included in a Policyfile. +- Certain types of data---passwords, user account data, and other + sensitive items---can be placed in data bags, which are located in a + secure sub-area on Chef Infra Server that can only be accessed + by nodes that authenticate to Chef Infra Server with the correct + SSL certificates. +- The cookbooks (and cookbook versions) in which organization-specific + configuration policies are maintained. diff --git a/content/reusable/md/policyfile_chef_commands.md b/content/reusable/md/policyfile_chef_commands.md new file mode 100644 index 0000000..b21ddaf --- /dev/null +++ b/content/reusable/md/policyfile_chef_commands.md @@ -0,0 +1,2 @@ +The following commands are built into the `chef` executable and support +the use of Policyfile files. diff --git a/content/reusable/md/policyfile_lock_json.md b/content/reusable/md/policyfile_lock_json.md new file mode 100644 index 0000000..1a36e30 --- /dev/null +++ b/content/reusable/md/policyfile_lock_json.md @@ -0,0 +1,12 @@ +When the `chef install` command is run, Chef Workstation caches any +necessary cookbooks and emits a `Policyfile.lock.json` file that +describes: + +- The versions of cookbooks in use +- A hash of cookbook content +- The source for all cookbooks +- Attributes included with the Policyfile + +A `Policyfile.lock.json` file is associated with a specific policy +group, which means it's associated with one (or more) nodes that use the same +revision of a given policy. diff --git a/content/reusable/md/policyfile_lock_json_example.md b/content/reusable/md/policyfile_lock_json_example.md new file mode 100644 index 0000000..75d14f1 --- /dev/null +++ b/content/reusable/md/policyfile_lock_json_example.md @@ -0,0 +1,45 @@ +A `Policyfile.lock.json` file is similar to: + +```json +{ + "revision_id": "288ed244f8db8bff3caf58147e840bbe079f76e0", + "name": "jenkins", + "run_list": [ + "recipe[java::default]", + "recipe[jenkins::master]", + "recipe[policyfile_demo::default]" + ], + "cookbook_locks": { + "policyfile_demo": { + "version": "0.1.0", + "identifier": "f04cc40faf628253fe7d9566d66a1733fb1afbe9", + "dotted_decimal_identifier": "67638399371010690.23642238397896298.25512023620585", + "source": "cookbooks/policyfile_demo", + "cache_key": null, + "scm_info": null, + "source_options": { + "path": "cookbooks/policyfile_demo" + } + }, + "java": { + "version": "1.24.0", + "identifier": "4c24ae46a6633e424925c24e683e0f43786236a3", + "dotted_decimal_identifier": "21432429158228798.18657774985439294.16782456927907", + "cache_key": "java-1.24.0-supermarket.chef.io", + "origin": "https://supermarket.chef.io/api/v1/cookbooks/java/versions/1.24.0/download", + "source_options": { + "artifactserver": "https://supermarket.chef.io/api/v1/cookbooks/java/versions/1.24.0/download", + "version": "1.24.0" + } + "default_attributes": { + "audit": { + "reporter": [ + "chef-server-automate", + "cli" + ] + } + }, + "override_attributes": { + + }, +``` diff --git a/content/reusable/md/policyfile_rb.md b/content/reusable/md/policyfile_rb.md new file mode 100644 index 0000000..a7ebbd4 --- /dev/null +++ b/content/reusable/md/policyfile_rb.md @@ -0,0 +1,9 @@ +A Policyfile file allows you to specify in a single document the +cookbook revisions and recipes that Chef Infra Client will apply. A +Policyfile file is uploaded to Chef Infra Server, where it's +associated with a group of nodes. When these nodes are configured during +a Chef Infra Client run, Chef Infra Client will make decisions based on +your Policyfile settings and will build a run-list based on that +information. A Policyfile file may be versioned, and then promoted +through deployment stages to safely and reliably deploy new +configuration. diff --git a/content/reusable/md/policyfile_rb_example.md b/content/reusable/md/policyfile_rb_example.md new file mode 100644 index 0000000..1cd0f74 --- /dev/null +++ b/content/reusable/md/policyfile_rb_example.md @@ -0,0 +1,12 @@ +For example: + +```ruby +name 'jenkins-master' +run_list 'java', 'jenkins::master', 'recipe[policyfile_demo]' +default_source :supermarket, 'https://mysupermarket.example' +cookbook 'policyfile_demo', path: 'cookbooks/policyfile_demo' +cookbook 'jenkins', '~> 8.2' +cookbook 'mysql', github: 'sous-chefs/mysql', branch: 'master' +default['stage']['mysql']['install_s3'] = 'https://s3-eu-west-1.amazonaws.com/example/stage/file.rpm' +default['prod']['mysql']['install_s3'] = 'https://s3-eu-west-1.amazonaws.com/example/prod/file.rpm' +``` diff --git a/content/reusable/md/policyfile_rb_settings.md b/content/reusable/md/policyfile_rb_settings.md new file mode 100644 index 0000000..d806d2c --- /dev/null +++ b/content/reusable/md/policyfile_rb_settings.md @@ -0,0 +1,280 @@ +A `Policyfile.rb` file may contain the following settings: + + + +`name "name"` + +: Required. The name of the policy. Use a name that reflects the + purpose of the machines against which the policy will run, + such as _application server_, _chat server_, or _load balancer_. + +`run_list "ITEM", "ITEM", ...` + +: Required. The run-list Chef Infra Client will use to apply the + policy to one (or more) nodes. + +`default_source :SOURCE_TYPE, *args` + +: The location in which any cookbooks not specified by `cookbook` are + located. + + Possible values for `:SOURCE_TYPE` are: + + - `:artifactory` + - `:chef_repo` + - `:chef_server` + - `:supermarket` + + `:artifactory` + : Pulls cookbooks from an Artifactory server. + + For example, `default_source :artifactory, "https://artifactory.example/api/chef/my-supermarket"`. + + There are two ways to authenticate with the Artifactory server: + + - **API key**: Set `artifactory_api_key` in config.rb or use the `ARTIFACTORY_API_KEY` environment variable. + - **Identity token**: Set `artifactory_identity_token` in config.rb or use the `ARTIFACTORY_IDENTITY_TOKEN` environment variable. + + The Artifactory identity token is new in Chef Workstation v24.11. + + **Note**: If both `ARTIFACTORY_API_KEY` and `ARTIFACTORY_IDENTITY_TOKEN` are set, `ARTIFACTORY_IDENTITY_TOKEN` takes precedence. + + `:chef_repo` + : Pulls cookbooks from a monolithic cookbook repository. This may be a path to the top-level + of a cookbook repository or to the `/cookbooks` directory within that repository. + + For example, `default_source :chef_repo, "path/to/repo"`. + + `:chef_server` + : Pulls cookbooks from Chef Infra Server. + + For example, `default_source :chef_server, "https://chef-server.example/organizations/example"`. + + `:supermarket` + + : Pulls cookbooks from the public Chef Supermarket or a private Chef Supermarket. + + By default `:supermarket` pulls cookbooks from the public Chef + Supermarket. For example, `default_source :supermarket`. + + Specify the Supermarket URL to pull cookbooks from a private Supermarket. For example, + `default_source :supermarket, "https://supermarket-name.example"`. + + You can specify multiple cookbook sources. For example from the + public Chef Supermarket and a monolithic repository: + + ```ruby + default_source :supermarket + default_source :chef_repo, 'path/to/repo' + ``` + + or from both a public and private Chef Supermarket: + + ```ruby + default_source :supermarket + default_source :supermarket, 'https://supermarket.example' + ``` + +
+

Note

+
+ + If a run-list or any dependencies require a cookbook that's present + in more than one source, be explicit about which source is + preferred. This will ensure that a cookbook is always pulled from an + expected source. For example, an internally-developed cookbook named + `chef-client` will conflict with the public `chef-client` cookbook + that's maintained by Chef. To specify a named source for a + cookbook: + + ```ruby + default_source :supermarket + default_source :supermarket, 'https://supermarket.example' do |s| + s.preferred_for 'chef-client' + end + ``` + + List multiple cookbooks on the same line: + + ```ruby + default_source :supermarket + default_source :supermarket, 'https://supermarket.example' do |s| + s.preferred_for 'chef-client', 'nginx', 'mysql' + end + ``` + +
+
+ +`cookbook "NAME" [, "VERSION_CONSTRAINT"] [, SOURCE_OPTIONS]` + +: Add cookbooks to the policy, specify a version constraint, or + specify an alternate source location, such as Chef Supermarket. For + example, add a cookbook: + + ```ruby + cookbook 'apache2' + ``` + + Specify a version constraint: + + ```ruby + run_list 'jenkins::master' + + # Restrict the jenkins cookbook to version 2.x, greater than 2.1 + cookbook 'jenkins', '~> 2.1' + ``` + + Specify an alternate source: + + ```ruby + cookbook 'my_app', path: 'cookbooks/my_app' + ``` + + or: + + ```ruby + cookbook 'mysql', github: 'opscode-cookbooks/mysql', branch: 'master' + ``` + + or: + + ```ruby + cookbook 'chef-ingredient', git: 'https://github.com/chef-cookbooks/chef-ingredient.git', tag: 'v0.12.0' + ``` + +`named_run_list "NAME", "ITEM1", "ITEM2", ...` + +: Specify a named run-list to be used as an alternative to the + override run-list. This setting should be used carefully and for + specific use cases, like running a small set of recipes to quickly + converge configuration for a single application on a host or for + one-time setup tasks. For example: + + ```ruby + named_run_list :update_app, 'my_app_cookbook::default' + ``` + +`include_policy "NAME", *args` + +: Specify a Policyfile lock to be merged with this policy. Chef + Workstation supports pulling this lock from a local or remote file, + from a Chef Infra Server, or from a git repository. When the + Policyfile lock is included, its run-list will appear before the + current Policyfile's run-list. This setting requires that the solved + cookbooks appear as-is from the included Policyfile lock. If + conflicting attributes or cookbooks are provided, an error will be + presented. See + [RFC097](https://github.com/chef-boneyard/chef-rfc/blob/master/rfc097-policyfile-includes.md) + for the full specifications of this feature. + + Pull the Policyfile lock from `./NAME.lock.json`: + + ```ruby + include_policy 'NAME', path: '.' + ``` + + Pull the Policyfile lock from `./foo.lock.json`. + + ```ruby + include_policy 'NAME', path: './foo.lock.json' + ``` + + Pull the Policyfile lock `foo.lock.json` from the `example/foo` Git repository on the `git.example.com` Git server. + + ```ruby + include_policy 'NAME', git: 'https://git.example.com/example/foo', path: 'foo.lock.json' + ``` + + Pull the Policyfile lock from `./bar.lock.json` with revision ID + 'revision1'. + + ```ruby + include_policy 'NAME', policy_revision_id: 'revision1', path: './bar.lock.json' + ``` + + Pull the Policyfile lock from a remote server + `https://internal.example.com/foo.lock.json`. + + ```ruby + include_policy 'NAME', remote: 'https://internal.example.com/foo.lock.json' + ``` + + Pull the Policyfile lock from a remote server + `https://internal.example.com/bar.lock.json` and with revision ID + 'revision1'. + + ```ruby + include_policy 'NAME', policy_revision_id: 'revision1', remote: 'https://internal.example.com/foo.lock.json' + ``` + + Pull the policy `NAME` with revision ID `revision1` from the + `http://chef-server.example` Chef Infra Server: + + ```ruby + include_policy 'NAME', policy_revision_id: 'revision1', server: 'http://chef-server.example' + ``` + + Pull the policy `foo` with revision ID `revision1`: + + ```ruby + include_policy 'NAME', policy_name: 'foo', policy_revision_id: 'revision1', server: 'http://chef-server.example' + ``` + + Pull and lock the current revision for policy `foo` in policy group + `prod`: + + ```ruby + include_policy 'NAME', policy_name: 'foo', policy_group: 'prod', server: 'http://chef-server.example' + ``` + +`ATTRIBUTE_TYPE['attribute'] = 'value'` + +: Specify one or more attributes to be included with the policy. + This is similar to defining attributes using roles. + + Possible values for `ATTRIBUTE_TYPE` are: + + - `default` + - `override` + + `default` + : A `default` attribute is automatically reset at the start of every Chef + Infra Client run and has the lowest attribute precedence. + + For example: + + ```ruby + default['attribute'] = 'value' + default['attribute']['level2'] = 'another_value' + ``` + + `override` + : An `override` attribute is automatically reset at the start of every + Chef Infra Client run and has a higher attribute precedence than + a `default` attribute. + + ```ruby + override['attribute'] = 'value' + override['attribute']['level2'] = 'another_value' + ``` + + Attribute hoisting allows you to define attributes by policy group. + + Use the following syntax to define policy group-specific attributes: + + ```ruby + ATTRIBUTE_TYPE['POLICY_GROUP']['attribute'] = 'value' + ``` + + where: + + - `ATTRIBUTE_TYPE` is either `default` or `override` as described above. + - `POLICY_GROUP` is a user-defined policy group, such as _dev_, _test_ _staging_, or _production_. + + In the following example, the value of `default['attribute']` is set to either `dev_value` or `prod_value` depending on the policy group. + + ```ruby + default['dev']['attribute'] = 'dev_value' + default['prod']['attribute'] = 'prod_value' + ``` diff --git a/content/reusable/md/policyfile_rb_syntax.md b/content/reusable/md/policyfile_rb_syntax.md new file mode 100644 index 0000000..6253893 --- /dev/null +++ b/content/reusable/md/policyfile_rb_syntax.md @@ -0,0 +1,10 @@ +A `Policyfile.rb` is a Ruby file in which run-list and cookbook +locations are specified. The syntax is as follows: + +```ruby +name "name" +run_list "ITEM", "ITEM", ... +default_source :SOURCE_TYPE, *args +cookbook "NAME" [, "VERSION_CONSTRAINT"] [, SOURCE_OPTIONS] +ATTRIBUTE_TYPE['attribute'] = 'value' +``` diff --git a/content/reusable/md/policyfile_summary.md b/content/reusable/md/policyfile_summary.md new file mode 100644 index 0000000..1e310a8 --- /dev/null +++ b/content/reusable/md/policyfile_summary.md @@ -0,0 +1 @@ +A Policyfile is a way to create immutable collections of cookbooks, cookbook dependencies, and attributes defined in a single document that's uploaded to Chef Infra Server. The Policyfile is then associated with a group of nodes. When these nodes perform a Chef Infra Client run, they utilize recipes specified in the Policyfile. diff --git a/content/reusable/md/proxy_env.md b/content/reusable/md/proxy_env.md new file mode 100644 index 0000000..fbf2661 --- /dev/null +++ b/content/reusable/md/proxy_env.md @@ -0,0 +1,23 @@ +If `http_proxy`, `https_proxy`, `ftp_proxy`, or `no_proxy` is set in the +client.rb file but not set in the `ENV`, Chef Infra Client will +configure the `ENV` variable based on these (and related) settings. For +example: + +```ruby +http_proxy 'http://proxy.example.org:8080' +http_proxy_user 'myself' +http_proxy_pass 'Password1' +``` + +Or an alternative way to define the proxy (if the previous version does +not work): + +```ruby +http_proxy 'http://myself:Password1@proxy.example.org:8080' +``` + +will be set to: + +```ruby +ENV['http_proxy'] = 'http://myself:Password1@proxy.example.org:8080' +``` diff --git a/content/reusable/md/proxy_windows.md b/content/reusable/md/proxy_windows.md new file mode 100644 index 0000000..843654b --- /dev/null +++ b/content/reusable/md/proxy_windows.md @@ -0,0 +1,13 @@ +To determine the current proxy server on the Windows platform: + +1. Open **Internet Properties**. +1. Open **Connections**. +1. Open **LAN settings**. +1. View the **Proxy server** setting. If this setting is blank, then a proxy server may not be available. + +To configure proxy settings in Windows: + +1. Open **System Properties**. +1. Open **Environment Variables**. +1. Open **System variables**. +1. Set `http_proxy` and `https_proxy` to the location of your proxy server. This value **MUST** be lowercase. diff --git a/content/reusable/md/ps_credential_helper.md b/content/reusable/md/ps_credential_helper.md new file mode 100644 index 0000000..83c0204 --- /dev/null +++ b/content/reusable/md/ps_credential_helper.md @@ -0,0 +1,31 @@ +Use the `ps_credential` helper to embed a `PSCredential` object--- [a +set of security credentials, such as a user name or +password](https://learn.microsoft.com/en-us/previous-versions/technet-magazine/ff714574(v=msdn.10)) +---within a script, which allows that script to be run using security +credentials. + +For example, assuming the `CertificateID` is configured in the local +configuration manager, the `SeaPower1@3` object is created and embedded +within the `sea-power-user` script: + +```ruby +dsc_script 'sea-power-user' do + code <<-EOH + User AlbertAtom + { + UserName = 'AlbertAtom' + Password = #{ps_credential('SeaPower1@3')} + } + EOH + configuration_data <<-EOH + @{ + AllNodes = @( + @{ + NodeName = "localhost"; + CertificateID = 'A8D1234559F349F7EF19104678908F701D4167' + } + ) + } + EOH +end +``` diff --git a/content/reusable/md/recipes_yaml_json_overview.md b/content/reusable/md/recipes_yaml_json_overview.md new file mode 100644 index 0000000..a6f78fd --- /dev/null +++ b/content/reusable/md/recipes_yaml_json_overview.md @@ -0,0 +1,5 @@ +JSON and YAML recipes let you define Chef Infra resources using a no-code syntax instead of Ruby. This feature makes Chef Infra recipes more accessible to users who prefer declarative YAML or JSON syntax over Ruby code. + +YAML and JSON recipes simplify defining Chef resources for basic use cases. While they have significant limitations compared to Ruby recipes, they're valuable for teams that prefer YAML syntax and don't need advanced Chef DSL features. For complex scenarios involving dynamic logic, node attributes, or resource relationships, use Ruby recipes. + +For most production environments, use a hybrid approach: YAML or JSON recipes for simple static configurations and Ruby recipes for complex logic. This approach balances simplicity and functionality. diff --git a/content/reusable/md/remote_directory_recursive_directories.md b/content/reusable/md/remote_directory_recursive_directories.md new file mode 100644 index 0000000..ce93157 --- /dev/null +++ b/content/reusable/md/remote_directory_recursive_directories.md @@ -0,0 +1,44 @@ +The **remote_directory** resource can be used to recursively create the +path outside of remote directory structures, but the permissions of +those outside paths aren't managed. This is because the `recursive` +attribute only applies `group`, `mode`, and `owner` attribute values to +the remote directory itself and any inner directories the resource +copies. + +A directory structure: + +```plain +/foo + /bar + /baz +``` + +The following example shows a way create a file in the `/baz` directory: + +```ruby +remote_directory '/foo/bar/baz' do + owner 'root' + group 'root' + mode '0755' + action :create +end +``` + +But with this example, the `group`, `mode`, and `owner` attribute values +will only be applied to `/baz`. Which is fine, if that's what you want. +But most of the time, when the entire `/foo/bar/baz` directory structure +isn't there, you must be explicit about each directory. For example: + +```ruby +%w( /foo /foo/bar /foo/bar/baz ).each do |path| + remote_directory path do + owner 'root' + group 'root' + mode '0755' + end +end +``` + +This approach will create the correct hierarchy---`/foo`, then `/bar` in +`/foo`, and then `/baz` in `/bar`---and also with the correct attribute +values for `group`, `mode`, and `owner`. diff --git a/content/reusable/md/remote_directory_recursive_directories_example.md b/content/reusable/md/remote_directory_recursive_directories_example.md new file mode 100644 index 0000000..97d446c --- /dev/null +++ b/content/reusable/md/remote_directory_recursive_directories_example.md @@ -0,0 +1,100 @@ +This section contains a more detailed example of how Chef Infra Client +manages recursive directory structures: + +- A cookbook named `cumbria` that's used to build a website +- A subfolder in the `/files/default` directory named `/website` +- A file named `index.html`, which is the root page for the website +- Directories within `/website` named `/cities`, `/places`, and + `/football`, which contains pages about cities, places, and football + teams +- A directory named `/images`, which contains images + +These files are placed in the `/files/default` directory in the +`cumbria` cookbook, like this: + +```text +cumbria + /files + /default + /website + index.html + /cities + carisle.html + kendal.html + penrith.html + windermere.html + /football + carisle_united.html + /images + carisle_united.png + furness_abbey.png + hadrians_wall.png + kendal.png + /places + furness_abbey.html + hadrians_wall.html +``` + +The **remote_directory** resource can be used to build a website using +these files. This website is being run on an Apache web server. The +resource would be similar to the following: + +```ruby +remote_directory '/var/www/html' do + files_mode '0440' + files_owner 'yan' + mode '0770' + owner 'hamilton' + source 'website' +end +``` + +When Chef Infra Client runs, the **remote_directory** resource will +tell Chef Infra Client to copy the directory tree from the cookbook to +the file system using the structure defined in cookbook: + +```text +/var + /www + /html + index.html + /cities + carisle.html + kendal.html + penrith.html + windermere.html + /football + carisle_united.html + /images + carisle_united.png + furness_abbey.png + hadrians_wall.png + kendal.png + /places + furness_abbey.html + hadrians_wall.html +``` + +Chef Infra Client will manage the permissions of the entire directory +structure below `/html`, for a total of 12 files and 4 directories. For +example: + +```bash +dr-xr-xr-x 2 root root 4096 /var/www/html +dr--r----- 1 yan root 4096 /var/www/html/index.html +drwxrwx--- 2 hamilton root 4096 /var/www/html/cities +dr--r----- 1 yan root 4096 /var/www/html/cities/carlisle.html +dr--r----- 1 yan root 4096 /var/www/html/cities/kendal.html +dr--r----- 1 yan root 4096 /var/www/html/cities/penrith.html +dr--r----- 1 yan root 4096 /var/www/html/cities/windermere.html +drwxrwx--- 2 hamilton root 4096 /var/www/html/football +dr--r----- 1 yan root 4096 /var/www/html/football/carlisle_united.html +drwxrwx--- 2 hamilton root 4096 /var/www/html/images +dr--r----- 1 yan root 4096 /var/www/html/images/carlisle_united/png +dr--r----- 1 yan root 4096 /var/www/html/images/furness_abbey/png +dr--r----- 1 yan root 4096 /var/www/html/images/hadrians_wall.png +dr--r----- 1 yan root 4096 /var/www/html/images/kendal.png +drwxrwx--- 2 hamilton root 4096 /var/www/html/places +dr--r----- 1 yan root 4096 /var/www/html/places/furness_abbey.html +dr--r----- 1 yan root 4096 /var/www/html/places/hadrians_wall.html +``` diff --git a/content/reusable/md/remote_file_prevent_re_downloads.md b/content/reusable/md/remote_file_prevent_re_downloads.md new file mode 100644 index 0000000..1a4a959 --- /dev/null +++ b/content/reusable/md/remote_file_prevent_re_downloads.md @@ -0,0 +1,22 @@ +To prevent Chef Infra Client from re-downloading files that are already +present on a node, use one of the following attributes in a recipe: +`use_conditional_get` (default) or `checksum`. + +- The `use_conditional_get` attribute is the default behavior of Chef + Infra Client. If the remote file is located on a server that + supports ETag and/or If-Modified-Since headers, Chef Infra Client + will use a conditional `GET` to determine if the file has been + updated. If the file has been updated, Chef Infra Client will + re-download the file. +- The `checksum` attribute will ask Chef Infra Client to compare the + checksum for the local file to the one at the remote location. If + they match, Chef Infra Client won't re-download the file. Using a + local checksum for comparison requires that the local checksum be + the correct checksum. + +The desired approach just depends on the desired workflow. For example, +if a node requires a new file every day, using the checksum approach +would require that the local checksum be updated and/or verified every +day as well, to ensure that the local checksum was the correct +one. Using a conditional `GET` in this scenario will greatly simplify +the management required to ensure files are being updated accurately. diff --git a/content/reusable/md/remote_file_unc_path.md b/content/reusable/md/remote_file_unc_path.md new file mode 100644 index 0000000..1d99de7 --- /dev/null +++ b/content/reusable/md/remote_file_unc_path.md @@ -0,0 +1,62 @@ +The `remote_file` resource on Windows supports accessing files from a +remote SMB/CIFS share. The file name should be specified in the source +property as a UNC path for example `\server\share\directory\file.txt`. +This allows access to the file at that path location even if the Chef +Infra Client process identity doesn't have permission to access the +file. Credentials for authenticating to the remote system can be +specified using the `remote_user`, `remote_domain`, and +`remote_password` properties when the user that Chef Infra Client is +running doesn't have access to the remote file. See the "Properties" +section for more details on these options. + +**Note**: This is primarily for accessing remote files when the user +that Chef Infra Client is running as doesn't have sufficient access, +and alternative credentials need to be specified. If the user already +has access, the credentials don't need to be specified. In a case where +the local system and remote system are in the same domain, the +`remote_user` and `remote_password` properties often don't need to be +specified, as the user may already have access to the remote file share. + +Examples: + +**Access a file from a different domain account:** + +```ruby +remote_file 'E:/domain_test.txt' do + source '\\server\share\directory\file.txt' + remote_domain 'domain' + remote_user 'username' + remote_password 'password' +end +``` + +OR + +```ruby +remote_file 'E:/domain_test.txt' do + source '\\server\share\directory\file.txt' + remote_user 'domain\username' + remote_password 'password' +end +``` + +**Access a file using a local account on the remote machine:** + +```ruby +remote_file 'E:/domain_test.txt' do + source '\\server\share\directory\file.txt' + remote_domain '.' + remote_user 'username' + remote_password 'password' +end +``` + +OR + +```ruby +remote_file 'E:/domain_test.txt' do + source '\\server\share\directory\file.txt' + remote_user '.\username' + remote_password 'password' +end +``` diff --git a/content/reusable/md/resource_before_notification_restart.md b/content/reusable/md/resource_before_notification_restart.md new file mode 100644 index 0000000..4ee995e --- /dev/null +++ b/content/reusable/md/resource_before_notification_restart.md @@ -0,0 +1,13 @@ +This example uses the `:before` notification to restart the `php-fpm` +service before restarting `nginx`: + +```ruby +service 'nginx' do + action :restart + notifies :restart, 'service[php-fpm]', :before +end +``` + +With the `:before` notification, the action specified for the `nginx` +resource won't run until action has been taken on the notified +resource (`php-fpm`). diff --git a/content/reusable/md/resource_cookbook_file_summary.md b/content/reusable/md/resource_cookbook_file_summary.md new file mode 100644 index 0000000..ea662b8 --- /dev/null +++ b/content/reusable/md/resource_cookbook_file_summary.md @@ -0,0 +1,7 @@ +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's running 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. diff --git a/content/reusable/md/resource_execute_command_from_template.md b/content/reusable/md/resource_execute_command_from_template.md new file mode 100644 index 0000000..e4d8bc7 --- /dev/null +++ b/content/reusable/md/resource_execute_command_from_template.md @@ -0,0 +1,22 @@ +The following example shows how to set up IPv4 packet forwarding using +the **execute** resource to run a command named `forward_ipv4` that uses +a template defined by the **template** resource: + +```ruby +execute 'forward_ipv4' do + command 'echo > /proc/.../ipv4/ip_forward' + action :nothing +end + +template '/etc/file_name.conf' do + source 'routing/file_name.conf.erb' + notifies :run, 'execute[forward_ipv4]', :delayed +end +``` + +where the `command` property for the **execute** resource contains the +command that's to be run and the `source` property for the **template** +resource specifies which template to use. The `notifies` property for +the **template** specifies that the `execute[forward_ipv4]` (which is +defined by the **execute** resource) should be queued up and run at the +end of a Chef Infra Client run. diff --git a/content/reusable/md/resource_execute_notifies_specific_order.md b/content/reusable/md/resource_execute_notifies_specific_order.md new file mode 100644 index 0000000..81c7d9d --- /dev/null +++ b/content/reusable/md/resource_execute_notifies_specific_order.md @@ -0,0 +1,28 @@ +To notify multiple resources, and then have these resources run in a +certain order, do something like the following: + +```ruby +execute 'foo' do + command '...' + notifies :create, 'template[baz]', :immediately + notifies :install, 'package[bar]', :immediately + notifies :run, 'execute[final]', :immediately +end + +template 'baz' do + ... + notifies :run, 'execute[restart_baz]', :immediately +end + +package 'bar' + +execute 'restart_baz' + +execute 'final' do + command '...' +end +``` + +where the sequencing will be in the same order as the resources are +listed in the recipe: `execute 'foo'`, `template 'baz'`, +`execute [restart_baz]`, `package 'bar'`, and `execute 'final'`. diff --git a/content/reusable/md/resource_execute_subscribes_prevent_restart_and_reconfigure.md b/content/reusable/md/resource_execute_subscribes_prevent_restart_and_reconfigure.md new file mode 100644 index 0000000..6c55b14 --- /dev/null +++ b/content/reusable/md/resource_execute_subscribes_prevent_restart_and_reconfigure.md @@ -0,0 +1,11 @@ +Use the `:nothing` action (common to all resources) to prevent the test +from starting automatically, and then use the `subscribes` notification +to run a configuration test when a change to the template is detected: + +```ruby +execute 'test-nagios-config' do + command 'nagios3 --verify-config' + action :nothing + subscribes :run, 'template[/etc/nagios3/configures-nagios.conf]', :immediately +end +``` diff --git a/content/reusable/md/resource_log_properties copy.md b/content/reusable/md/resource_log_properties copy.md new file mode 100644 index 0000000..d4f9a64 --- /dev/null +++ b/content/reusable/md/resource_log_properties copy.md @@ -0,0 +1,16 @@ +The log resource has the following properties: + +`level` + +: **Ruby Type:** Symbol \| **Default Value:** `:info` + + The logging level for displaying this message. Options (in order of + priority): `:debug`, `:info`, `:warn`, `:error`, and `:fatal`. + +`message` + +: **Ruby Type:** String \| **Default Value:** + `The resource block's name` + + The message to be added to a log file. Default value: the `name` of + the resource block. See "Syntax" section above for more information. diff --git a/content/reusable/md/resource_log_properties.md b/content/reusable/md/resource_log_properties.md new file mode 100644 index 0000000..d4f9a64 --- /dev/null +++ b/content/reusable/md/resource_log_properties.md @@ -0,0 +1,16 @@ +The log resource has the following properties: + +`level` + +: **Ruby Type:** Symbol \| **Default Value:** `:info` + + The logging level for displaying this message. Options (in order of + priority): `:debug`, `:info`, `:warn`, `:error`, and `:fatal`. + +`message` + +: **Ruby Type:** String \| **Default Value:** + `The resource block's name` + + The message to be added to a log file. Default value: the `name` of + the resource block. See "Syntax" section above for more information. diff --git a/content/reusable/md/resource_log_set_debug.md b/content/reusable/md/resource_log_set_debug.md new file mode 100644 index 0000000..2d630de --- /dev/null +++ b/content/reusable/md/resource_log_set_debug.md @@ -0,0 +1,5 @@ +```ruby +log 'a debug string' do + level :debug +end +``` diff --git a/content/reusable/md/resource_log_syntax.md b/content/reusable/md/resource_log_syntax.md new file mode 100644 index 0000000..61335f3 --- /dev/null +++ b/content/reusable/md/resource_log_syntax.md @@ -0,0 +1,28 @@ +A **log** resource block adds messages to the log file based on events +that occur during a Chef Infra Client run: + +```ruby +log 'message' do + message 'A message add to the log.' + level :info +end +``` + +The full syntax for all of the properties that are available to the +**log** resource is: + +```ruby +log 'name' do + level Symbol # default value: :info + message String # default value: 'name' unless specified + action Symbol # defaults to :write if not specified +end +``` + +where: + +- `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. diff --git a/content/reusable/md/resource_package_install_gem_with_gemrc.md b/content/reusable/md/resource_package_install_gem_with_gemrc.md new file mode 100644 index 0000000..7c4fafd --- /dev/null +++ b/content/reusable/md/resource_package_install_gem_with_gemrc.md @@ -0,0 +1,35 @@ +A template named `gemrc.erb` is located in a cookbook's `/templates` +directory: + +```ruby +:sources: +- http://<%= node['gem_file']['host'] %>:<%= node['gem_file']['port'] %>/ +``` + +A recipe can be built that does the following: + +- Builds a `.gemrc` file based on a `gemrc.erb` template +- Runs a `Gem.configuration` command +- Installs a package using the `.gemrc` file + + + +```ruby +template '/root/.gemrc' do + source 'gemrc.erb' + action :create + notifies :run, 'ruby_block[refresh_gemrc]', :immediately +end + +ruby_block 'refresh_gemrc' do + action :nothing + block do + Gem.configuration = Gem::ConfigFile.new [] + end +end + +gem_package 'di-ruby-lvm' do + gem_binary '/opt/chef/embedded/bin/gem' + action :install +end +``` diff --git a/content/reusable/md/resource_package_install_gem_with_hash_options.md b/content/reusable/md/resource_package_install_gem_with_hash_options.md new file mode 100644 index 0000000..d48e3d3 --- /dev/null +++ b/content/reusable/md/resource_package_install_gem_with_hash_options.md @@ -0,0 +1,5 @@ +```ruby +gem_package 'bundler' do + options(prerelease: true, format_executable: false) +end +``` diff --git a/content/reusable/md/resource_package_install_gem_with_options_string.md b/content/reusable/md/resource_package_install_gem_with_options_string.md new file mode 100644 index 0000000..9fa5c8d --- /dev/null +++ b/content/reusable/md/resource_package_install_gem_with_options_string.md @@ -0,0 +1,6 @@ +```ruby +gem_package 'nokogiri' do + gem_binary('/opt/ree/bin/gem') + options('--prerelease --no-format-executable') +end +``` diff --git a/content/reusable/md/resource_package_options.md b/content/reusable/md/resource_package_options.md new file mode 100644 index 0000000..ef4cc0a --- /dev/null +++ b/content/reusable/md/resource_package_options.md @@ -0,0 +1,14 @@ +The RubyGems package provider attempts to use the RubyGems API to +install gems without spawning a new process, whenever possible. A gems +command to install will be spawned under the following conditions: + +- When a `gem_binary` property is specified (as a hash, a string, or + by a .gemrc file), Chef Infra Client will run that command to + examine its environment settings and then again to install the gem. +- When install options are specified as a string, Chef Infra Client + will span a gems command with those options when installing the gem. +- The Chef installer will search the `PATH` for a gem command rather + than defaulting to the current gem environment. As part of + `enforce_default_paths`, the `bin` directories area added to the + `PATH`, which means when there are no other proceeding RubyGems, the + installation will still be operated against it. diff --git a/content/reusable/md/resource_package_options_gemrc.md b/content/reusable/md/resource_package_options_gemrc.md new file mode 100644 index 0000000..6956882 --- /dev/null +++ b/content/reusable/md/resource_package_options_gemrc.md @@ -0,0 +1,5 @@ +Options can be specified in a .gemrc file. By default the `gem_package` +resource will use the Ruby interface to install gems which will ignore +the .gemrc file. The `gem_package` resource can be forced to use the +gems command instead (and to read the .gemrc file) by adding the +`gem_binary` attribute to a code block. diff --git a/content/reusable/md/resource_package_options_hash.md b/content/reusable/md/resource_package_options_hash.md new file mode 100644 index 0000000..d83fe17 --- /dev/null +++ b/content/reusable/md/resource_package_options_hash.md @@ -0,0 +1,17 @@ +You should provide the install options as a hash if you aren't using an explicit +`gem_binary` parameter with the `gem_package` resource. This approach allows the +provider to install the gem without needing to spawn an external gem process. + +The following RubyGems options are available for inclusion within a hash +and are passed to the RubyGems DependencyInstaller: + +- `:env_shebang` +- `:force` +- `:format_executable` +- `:ignore_dependencies` +- `:prerelease` +- `:security_policy` +- `:wrappers` + +For more information about these options, see the [RubyGems +DependencyInstaller documentation](https://docs.ruby-lang.org/en/2.2.0/Gem/DependencyInstaller.html). diff --git a/content/reusable/md/resource_package_options_string.md b/content/reusable/md/resource_package_options_string.md new file mode 100644 index 0000000..921b36c --- /dev/null +++ b/content/reusable/md/resource_package_options_string.md @@ -0,0 +1,7 @@ +When using an explicit `gem_binary`, options must be passed as a string. +When not using an explicit `gem_binary`, Chef Infra Client is forced to +spawn a gems process to install the gems (which uses more system +resources) when options are passed as a string. String options are +passed verbatim to the gems command and should be specified just as if +they were passed on a command line. For example, `--prerelease` for a +pre-release gem. diff --git a/content/reusable/md/resource_package_use_ignore_failure_attribute.md b/content/reusable/md/resource_package_use_ignore_failure_attribute.md new file mode 100644 index 0000000..b9c5115 --- /dev/null +++ b/content/reusable/md/resource_package_use_ignore_failure_attribute.md @@ -0,0 +1,6 @@ +```ruby +gem_package 'syntax' do + action :install + ignore_failure true +end +``` diff --git a/content/reusable/md/resource_remote_file_transfer_remote_source_changes.md b/content/reusable/md/resource_remote_file_transfer_remote_source_changes.md new file mode 100644 index 0000000..e09dcb8 --- /dev/null +++ b/content/reusable/md/resource_remote_file_transfer_remote_source_changes.md @@ -0,0 +1,16 @@ +```ruby +remote_file '/tmp/couch.png' do + source 'http://couchdb.apache.org/img/sketch.png' + action :nothing +end + +http_request 'HEAD http://couchdb.apache.org/img/sketch.png' do + message '' + url 'http://couchdb.apache.org/img/sketch.png' + action :head + if ::File.exist?('/tmp/couch.png') + headers 'If-Modified-Since' => File.mtime('/tmp/couch.png').httpdate + end + notifies :create, 'remote_file[/tmp/couch.png]', :immediately +end +``` diff --git a/content/reusable/md/resource_service_restart_and_notify.md b/content/reusable/md/resource_service_restart_and_notify.md new file mode 100644 index 0000000..a92dc78 --- /dev/null +++ b/content/reusable/md/resource_service_restart_and_notify.md @@ -0,0 +1,9 @@ +The following example shows how start a service named `example_service` +and immediately notify the Nginx service to restart. + +```ruby +service 'example_service' do + action :start + notifies :restart, 'service[nginx]', :immediately +end +``` diff --git a/content/reusable/md/resource_service_subscribes_reload_using_template.md b/content/reusable/md/resource_service_subscribes_reload_using_template.md new file mode 100644 index 0000000..a4ede04 --- /dev/null +++ b/content/reusable/md/resource_service_subscribes_reload_using_template.md @@ -0,0 +1,18 @@ +To reload a service that's based on a template, use the **template** +and **service** resources together in the same recipe, similar to the +following: + +```ruby +template '/tmp/somefile' do + mode '0755' + source 'somefile.erb' +end + +service 'apache' do + action :enable + subscribes :reload, 'template[/tmp/somefile]', :immediately +end +``` + +where the `subscribes` notification is used to reload the service +whenever the template is modified. diff --git a/content/reusable/md/resource_service_use_nothing_action.md b/content/reusable/md/resource_service_use_nothing_action.md new file mode 100644 index 0000000..dbaecc2 --- /dev/null +++ b/content/reusable/md/resource_service_use_nothing_action.md @@ -0,0 +1,5 @@ +```ruby +service 'memcached' do + action :nothing +end +``` diff --git a/content/reusable/md/resource_service_use_retries_properties.md b/content/reusable/md/resource_service_use_retries_properties.md new file mode 100644 index 0000000..492b678 --- /dev/null +++ b/content/reusable/md/resource_service_use_retries_properties.md @@ -0,0 +1,7 @@ +```ruby +service 'apache' do + action [ :enable, :start ] + retries 3 + retry_delay 5 +end +``` diff --git a/content/reusable/md/resource_template_inline_method.md b/content/reusable/md/resource_template_inline_method.md new file mode 100644 index 0000000..4c8d5ac --- /dev/null +++ b/content/reusable/md/resource_template_inline_method.md @@ -0,0 +1,45 @@ +A template helper method is always defined inline on a resource +basis. A simple example: + +```ruby +template '/path' do + helper(:hello_world) { 'hello world' } +end +``` + +Another way to define an inline helper method is to reference a node +object so that repeated calls to one (or more) cookbook attributes can +be done efficiently: + +```ruby +template '/path' do + helper(:app) { node['app'] } +end +``` + +An inline helper method can also take arguments: + +```ruby +template '/path' do + helper(:app_conf) { |setting| node['app'][setting] } +end +``` + +Once declared, a template can then use the helper methods to build a +file. For example: + +```ruby +Say hello: <%= hello_world %> +``` + +or: + +```ruby +node['app']['listen_port'] is: <%= app['listen_port'] %> +``` + +or: + +```ruby +node['app']['log_location'] is: <%= app_conf('log_location') %> +``` diff --git a/content/reusable/md/resource_template_inline_module.md b/content/reusable/md/resource_template_inline_module.md new file mode 100644 index 0000000..d3891e8 --- /dev/null +++ b/content/reusable/md/resource_template_inline_module.md @@ -0,0 +1,24 @@ +A template helper module can be defined inline on a resource basis. +This approach can be useful when a template requires more complex +information. For example: + +```ruby +template '/path' do + helpers do + def hello_world + 'hello world' + end + + def app + node['app'] + end + + def app_conf(setting) + node['app']['setting'] + end + end +end +``` + +where the `hello_world`, `app`, and `app_conf(setting)` methods comprise +the module that extends a template. diff --git a/content/reusable/md/resource_template_library_module copy.md b/content/reusable/md/resource_template_library_module copy.md new file mode 100644 index 0000000..4eb0b63 --- /dev/null +++ b/content/reusable/md/resource_template_library_module copy.md @@ -0,0 +1,10 @@ +A template helper module can be defined in a library. This is useful +when extensions need to be reused across recipes or to make it easier to +manage code that would otherwise be defined inline for each recipe +basis. + +```ruby +template '/path/to/template.erb' do + helpers(MyHelperModule) +end +``` diff --git a/content/reusable/md/resource_template_library_module.md b/content/reusable/md/resource_template_library_module.md new file mode 100644 index 0000000..4eb0b63 --- /dev/null +++ b/content/reusable/md/resource_template_library_module.md @@ -0,0 +1,10 @@ +A template helper module can be defined in a library. This is useful +when extensions need to be reused across recipes or to make it easier to +manage code that would otherwise be defined inline for each recipe +basis. + +```ruby +template '/path/to/template.erb' do + helpers(MyHelperModule) +end +``` diff --git a/content/reusable/md/resource_template_notifies_delay.md b/content/reusable/md/resource_template_notifies_delay.md new file mode 100644 index 0000000..1165ca1 --- /dev/null +++ b/content/reusable/md/resource_template_notifies_delay.md @@ -0,0 +1,6 @@ +```ruby +template '/etc/nagios3/configures-nagios.conf' do + # other parameters + notifies :run, 'execute[test-nagios-config]', :delayed +end +``` diff --git a/content/reusable/md/resource_template_notifies_multiple_resources.md b/content/reusable/md/resource_template_notifies_multiple_resources.md new file mode 100644 index 0000000..3d439a3 --- /dev/null +++ b/content/reusable/md/resource_template_notifies_multiple_resources.md @@ -0,0 +1,10 @@ +```ruby +template '/etc/chef/server.rb' do + source 'server.rb.erb' + owner 'root' + group 'root' + mode '0755' + notifies :restart, 'service[chef-elasticsearch]', :delayed + notifies :restart, 'service[chef-server]', :delayed +end +``` diff --git a/content/reusable/md/resource_template_notifies_reload_service.md b/content/reusable/md/resource_template_notifies_reload_service.md new file mode 100644 index 0000000..921b099 --- /dev/null +++ b/content/reusable/md/resource_template_notifies_reload_service.md @@ -0,0 +1,7 @@ +```ruby +template '/tmp/somefile' do + mode '0755' + source 'somefile.erb' + notifies :reload, 'service[apache]', :immediately +end +``` diff --git a/content/reusable/md/resource_template_notifies_restart_service_when_template_modified.md b/content/reusable/md/resource_template_notifies_restart_service_when_template_modified.md new file mode 100644 index 0000000..d5b7281 --- /dev/null +++ b/content/reusable/md/resource_template_notifies_restart_service_when_template_modified.md @@ -0,0 +1,5 @@ +```ruby +template '/etc/www/configures-apache.conf' do + notifies :restart, 'service[apache]', :immediately +end +``` diff --git a/content/reusable/md/resource_template_notifies_run_immediately.md b/content/reusable/md/resource_template_notifies_run_immediately.md new file mode 100644 index 0000000..02aa12d --- /dev/null +++ b/content/reusable/md/resource_template_notifies_run_immediately.md @@ -0,0 +1,19 @@ +By default, notifications are `:delayed`, that's they're queued up as +they're triggered, and then executed at the end of a Chef Infra +Client run. To run an action immediately, use `:immediately`: + +```ruby +template '/etc/nagios3/configures-nagios.conf' do + # other parameters + notifies :run, 'execute[test-nagios-config]', :immediately +end +``` + +and then Chef Infra Client would immediately run the following: + +```ruby +execute 'test-nagios-config' do + command 'nagios3 --verify-config' + action :nothing +end +``` diff --git a/content/reusable/md/resource_template_notifies_send_notifications_to_multiple_resources.md b/content/reusable/md/resource_template_notifies_send_notifications_to_multiple_resources.md new file mode 100644 index 0000000..0bd87a3 --- /dev/null +++ b/content/reusable/md/resource_template_notifies_send_notifications_to_multiple_resources.md @@ -0,0 +1,13 @@ +To send notifications to multiple resources, just use multiple +attributes. Multiple attributes will get sent to the notified resources +in the order specified. + +```ruby +template '/etc/netatalk/netatalk.conf' do + notifies :restart, 'service[afpd]', :immediately + notifies :restart, 'service[cnid]', :immediately +end + +service 'afpd' +service 'cnid' +``` diff --git a/content/reusable/md/resource_template_use_relative_paths.md b/content/reusable/md/resource_template_use_relative_paths.md new file mode 100644 index 0000000..77864f9 --- /dev/null +++ b/content/reusable/md/resource_template_use_relative_paths.md @@ -0,0 +1,6 @@ +```ruby +template "#{ENV['HOME']}/chef-getting-started.txt" do + source 'chef-getting-started.txt.erb' + mode '0755' +end +``` diff --git a/content/reusable/md/resources_common.md b/content/reusable/md/resources_common.md new file mode 100644 index 0000000..6979408 --- /dev/null +++ b/content/reusable/md/resources_common.md @@ -0,0 +1,9 @@ +A resource is a statement of configuration policy that: + +- Describes the desired state for a configuration item +- Declares the steps needed to bring that item to the desired state +- Specifies a resource type---such as `package`, `template`, or + `service` +- Lists additional details (also known as resource properties), as + necessary +- Are grouped into recipes, which describe working configurations diff --git a/content/reusable/md/resources_common_actions_nothing.md b/content/reusable/md/resources_common_actions_nothing.md new file mode 100644 index 0000000..45131b5 --- /dev/null +++ b/content/reusable/md/resources_common_actions_nothing.md @@ -0,0 +1,3 @@ +This resource block doesn't act unless notified by another resource to +take action. Once notified, this resource block either runs immediately +or is queued up to run at the end of a Chef Infra Client run. diff --git a/content/reusable/md/resources_common_atomic_update.md b/content/reusable/md/resources_common_atomic_update.md new file mode 100644 index 0000000..3136dc9 --- /dev/null +++ b/content/reusable/md/resources_common_atomic_update.md @@ -0,0 +1,26 @@ +Atomic updates are used with **file**-based resources to help ensure +that file updates can be made when updating a binary or if disk space +runs out. + +Atomic updates are enabled by default. They can be managed globally +using the `file_atomic_update` setting in the `client.rb` file. They can +be managed for each resource using the `atomic_update` property +that's available with the **cookbook_file**, **file**, +**remote_file**, and **template** resources. + + + +
+

Note

+
+ +On certain platforms, and after a file has been moved into place, Chef +Infra Client may modify file permissions to support features specific to +those platforms. On platforms with SELinux enabled, Chef Infra Client +will fix up the security contexts after a file has been moved into the +correct location by running the `restorecon` command. On the Microsoft +Windows platform, Chef Infra Client will create files so that ACL +inheritance works as expected. + +
+
diff --git a/content/reusable/md/resources_common_compile.md b/content/reusable/md/resources_common_compile.md new file mode 100644 index 0000000..7528ae1 --- /dev/null +++ b/content/reusable/md/resources_common_compile.md @@ -0,0 +1,28 @@ +Chef Infra Client processes recipes in two phases: + + + +1. First, each resource in the node object is identified and a resource + collection is built. All recipes are loaded in a specific order, and + then the actions specified within each of them are identified. This + is also referred to as the _compile phase_. +1. Next, Chef Infra Client configures the system based on the order of + the resources in the resource collection. Each resource then + examines the node and performs the necessary steps to complete the + action. This is also referred to as the _execution phase_. + +Typically, actions are processed during the execution phase of a Chef +Infra Client run. However, sometimes it's necessary to run an action +during the compile phase. For example, a resource can be configured to +install a package during the compile phase to ensure that application is +available to other resources during the execution phase. + +
+

Note

+
+ +Use the **chef_gem** resource to install gems that are needed by Chef +Infra Client during the execution phase. + +
+
diff --git a/content/reusable/md/resources_common_compile_begin.md b/content/reusable/md/resources_common_compile_begin.md new file mode 100644 index 0000000..ff9e733 --- /dev/null +++ b/content/reusable/md/resources_common_compile_begin.md @@ -0,0 +1,159 @@ +Use `.run_action(:some_action)` at the end of a resource block to run +the specified action during the compile phase. For example: + +```ruby +build_essential 'Install compilers' do + action :nothing +end.run_action(:install) +``` + +where `action` is set to `:nothing` to ensure the `run_action` is run +during the compile phase and not later during the execution phase. + +This can be simplified by using the `compile_time` flag in Chef Infra +Client 16 and later versions: + +```ruby +build_essential 'Install compilers' do + compile_time true +end +``` + +That flag both forces the resource to run at compile time and sets the +converge action to `:nothing`. + +The following examples show when (and when not) to use `run_action`. + + + +**Using Custom Resources preferred to forcing to compile time** + +Compile time execution is often used to install gems before requiring +them in recipe code. + +This is a poor pattern since gems may depend on native gems which +may require installing compilers at compile time. + +```ruby +build_essential 'Install compilers' do + compile_time true +end + +chef_gem 'aws-dsk' do + compile_time true +end + +require 'aws-sdk' +``` + +A better strategy is to move the code, which requires the gem, into +a custom resource. Since all the actions of custom resources run +at converge time, this defers requiring +the gem until later in the overall Chef Infra Client execution. [Unified +mode](/resources/custom/unified_mode/) can also be used in the resource to eliminate compile/converge +mode issues entirely: + +```ruby +unified_mode true + +action :run do + build_essential 'Install compilers' + + chef_gem 'aws-sdk' + + require 'aws-sdk' +end +``` + +**Download and parse a configuration file** + +A common use case is to download a configuration file, parse it, and then +use the values in templates and to control other configuration. + +An important distinction to make is that the downloaded configuration file +only exists in a temporary state to be used by the Chef Infra Client. It will +not be used directly by the system or applications that are managed by the +Chef Infra Client. + +To download and parse a JSON file and render it in a template, it makes sense +to download the file during compile time: + +```ruby + # the remote_file is being downloaded to a temporary file + remote_file "#{Chef::Config[:file_cache_path]}/users.json" do + source "https://jsonplaceholder.typicode.com/users" + compile_time true + end + + # this parsing needs to happen after the remote_file is downloaded, but will + # be executed at compile time. + array = JSON.parse(IO.read("#{Chef::Config[:file_cache_path]}/users.json") + + # the `array.last["phone"]` expression here will also be evaluated at compile + # time and must be lazied using wrapping the expresssion in `lazy {}` + file "/tmp/phone_number.txt" do + content array.last["phone"] + end +``` + +This is considerably cleaner than the alternative of lazy evaluating both the parsing of the +JSON and the rendering of the data into the file template, which will happen if +the `remote_file` resource isn't run at compile time: + +```ruby + # the execution of this is now deferred + remote_file "#{Chef::Config[:file_cache_path]}/users.json" do + source "https://jsonplaceholder.typicode.com/users" + end + + # it's necessary due to lexical scoping issues to create this variable here + array = nil + + # the parsing of the JSON is now deferred due to the ruby_block + ruby_block "parse JSON" do + block do + array = JSON.parse(IO.read("#{Chef::Config[:file_cache_path]}/users.json") + end + end + + # the argument to the content property must now also be deferred + file "/tmp/phone_number.txt" do + content lazy { array.last["phone"] } + end +``` + +This is an example of code that overuses deferred execution, uses more "lazy" evaluation, and is +considerably harder to understand and write correctly. + +**Notifications won't work** + +Resources that are executed during the compile phase can't notify other +resources. For example: + +```ruby +execute 'ifconfig' + +package 'vim-enhanced' do + compile_time true + notifies :run, 'execute[ifconfig]', :immediately +end +``` + +A better approach in this type of situation is to install the package +before the resource collection is built to ensure that it's available +to other resources later on. + +The best approach to this problem is to use [`unified mode`](/resources/custom/unified_mode/), which eliminates +the compile time and converge time distinction while allowing notifications +to work correctly. + +**Resources that are forced to compile time by default** + +The `ohai_hint` and `hostname` resources run at compile time by default. + +This is due to the fact that later resources may consume the node attributes which +are set by those resources leading to excessive use of `lazy` in subsequent +resources (and similar issues to the `remote_file` example above). + +The `chef_gem` resource used to execute at compile time by default, but now we +recommend that users move code that executes at compile time to custom resources. diff --git a/content/reusable/md/resources_common_guard_interpreter.md b/content/reusable/md/resources_common_guard_interpreter.md new file mode 100644 index 0000000..7f1cb4b --- /dev/null +++ b/content/reusable/md/resources_common_guard_interpreter.md @@ -0,0 +1,4 @@ +Any resource that passes a string command may also specify the +interpreter that will be used to evaluate that string command. This is +done by using the `guard_interpreter` property to specify a +**script**-based resource. diff --git a/content/reusable/md/resources_common_guard_interpreter_attributes.md b/content/reusable/md/resources_common_guard_interpreter_attributes.md new file mode 100644 index 0000000..90d8fb6 --- /dev/null +++ b/content/reusable/md/resources_common_guard_interpreter_attributes.md @@ -0,0 +1,38 @@ +The `guard_interpreter` property may be set to any of the following +values: + +`:bash` + +: Evaluates a string command using the **bash** resource. + +`:batch` + +: Evaluates a string command using the **batch** resource. Default + value (within a **batch** resource block): `:batch`. + +`:csh` + +: Evaluates a string command using the **csh** resource. + +`:default` + +: Default. Executes the default interpreter as identified by Chef + Infra Client. + +`:perl` + +: Evaluates a string command using the **perl** resource. + +`:powershell_script` + +: Evaluates a string command using the **powershell_script** + resource. Default value (within a **powershell_script** resource block): + `:powershell_script`. + +`:python` + +: Evaluates a string command using the **python** resource. + +`:ruby` + +: Evaluates a string command using the **ruby** resource. diff --git a/content/reusable/md/resources_common_guard_interpreter_attributes_inherit.md b/content/reusable/md/resources_common_guard_interpreter_attributes_inherit.md new file mode 100644 index 0000000..ac38d4e --- /dev/null +++ b/content/reusable/md/resources_common_guard_interpreter_attributes_inherit.md @@ -0,0 +1,66 @@ +The `guard_interpreter` property is set to `:default` by default for the +**bash**, **csh**, **perl**, **python**, and **ruby** resources. When +the `guard_interpreter` property is set to `:default`, `not_if` or +`only_if` guard statements **don't inherit** properties that are +defined by the **script**-based resource. + + + +
+

Warning

+
+ +The **batch** and **powershell_script** resources inherit properties by +default. The `guard_interpreter` property is set to `:batch` or +`:powershell_script` automatically when using a `not_if` or `only_if` +guard statement within a **batch** or **powershell_script** resource, +respectively. + +
+
+For example, the `not_if` guard statement in the following resource +example **doesn't inherit** the `environment` property: + +```ruby +bash 'javatooling' do + environment 'JAVA_HOME' => '/usr/lib/java/jdk1.7/home' + code 'java-based-daemon-ctl.sh -start' + not_if 'java-based-daemon-ctl.sh -test-started' +end +``` + +and requires adding the `environment` property to the `not_if` guard +statement so that it may use the `JAVA_HOME` path as part of its +evaluation: + +```ruby +bash 'javatooling' do + environment 'JAVA_HOME' => '/usr/lib/java/jdk1.7/home' + code 'java-based-daemon-ctl.sh -start' + not_if 'java-based-daemon-ctl.sh -test-started', :environment => 'JAVA_HOME' => '/usr/lib/java/jdk1.7/home' +end +``` + +To inherit properties, add the `guard_interpreter` property to the +resource block and set it to the appropriate value: + +- `:bash` for **bash** +- `:csh` for **csh** +- `:perl` for **perl** +- `:python` for **python** +- `:ruby` for **ruby** + +For example, using the same example as from above, but this time adding +the `guard_interpreter` property and setting it to `:bash`: + +```ruby +bash 'javatooling' do + guard_interpreter :bash + environment 'JAVA_HOME' => '/usr/lib/java/jdk1.7/home' + code 'java-based-daemon-ctl.sh -start' + not_if 'java-based-daemon-ctl.sh -test-started' +end +``` + +The `not_if` statement now inherits the `environment` property and will +use the `JAVA_HOME` path as part of its evaluation. diff --git a/content/reusable/md/resources_common_guard_interpreter_example_default.md b/content/reusable/md/resources_common_guard_interpreter_example_default.md new file mode 100644 index 0000000..906008f --- /dev/null +++ b/content/reusable/md/resources_common_guard_interpreter_example_default.md @@ -0,0 +1,10 @@ +For example, the following code block will ensure the command is +evaluated using the default interpreter as identified by Chef Infra +Client: + +```ruby +resource 'name' do + guard_interpreter :default + # code +end +``` diff --git a/content/reusable/md/resources_common_guards.md b/content/reusable/md/resources_common_guards.md new file mode 100644 index 0000000..3496433 --- /dev/null +++ b/content/reusable/md/resources_common_guards.md @@ -0,0 +1,19 @@ +A guard property can be used to evaluate the state of a node during the +execution phase of a Chef Infra Client run. Based on the results of this +evaluation, a guard property is then used to tell Chef Infra Client if +it should continue executing a resource. A guard property accepts either +a string value or a Ruby block value: + +- A string is executed as a shell command. If the command returns `0`, + the guard is applied. If the command returns any other value, then + the guard property isn't applied. String guards in a + **powershell_script** run Windows PowerShell commands and may + return `true` in addition to `0`. +- A block is executed as Ruby code that must return either `true` or + `false`. If the block returns `true`, the guard property is applied. + If the block returns `false`, the guard property isn't applied. + +A guard property is useful for ensuring that a resource is idempotent by +allowing that resource to test for the desired state as it's being +executed, and then if the desired state is present, for Chef Infra +Client to do nothing. diff --git a/content/reusable/md/resources_common_guards_arguments.md b/content/reusable/md/resources_common_guards_arguments.md new file mode 100644 index 0000000..0160f65 --- /dev/null +++ b/content/reusable/md/resources_common_guards_arguments.md @@ -0,0 +1,45 @@ +The following arguments can be used with the `not_if` or `only_if` guard +properties: + +`:user` + +: Specify the user that a command will run as. For example: + + ```ruby + not_if 'grep adam /etc/passwd', user: 'adam' + ``` + +`:group` + +: Specify the group that a command will run as. For example: + + ```ruby + not_if 'grep adam /etc/passwd', group: 'adam' + ``` + +`:environment` + +: Specify a Hash of environment variables to be set. For example: + + ```ruby + not_if 'grep adam /etc/passwd', environment: { + 'HOME' => '/home/adam', + } + ``` + +`:cwd` + +: Set the current working directory before running a command. For + example: + + ```ruby + not_if 'grep adam passwd', cwd: '/etc' + ``` + +`:timeout` + +: Set a timeout for a command. For example: + + ```ruby + not_if 'sleep 10000', timeout: 10 + ``` diff --git a/content/reusable/md/resources_common_guards_properties.md b/content/reusable/md/resources_common_guards_properties.md new file mode 100644 index 0000000..3e176d2 --- /dev/null +++ b/content/reusable/md/resources_common_guards_properties.md @@ -0,0 +1,10 @@ +The following properties can be used to define a guard that's evaluated +during the execution phase of a Chef Infra Client run: + +`not_if` + +: Prevent a resource from executing when the condition returns `true`. + +`only_if` + +: Allow a resource to execute only if the condition returns `true`. diff --git a/content/reusable/md/resources_common_lazy_evaluation.md b/content/reusable/md/resources_common_lazy_evaluation.md new file mode 100644 index 0000000..be2ed9b --- /dev/null +++ b/content/reusable/md/resources_common_lazy_evaluation.md @@ -0,0 +1,50 @@ +In some cases, the value for a property can't be known until the +execution phase of a Chef Infra Client run. In this situation, using +lazy evaluation of property values can be helpful. Instead of a property +being assigned a value, it may instead be assigned a code block. The +syntax for using lazy evaluation is as follows: + +```ruby +property_name lazy { code_block } +``` + +where `lazy` is used to tell Chef Infra Client to evaluate the contents +of the code block later on in the resource evaluation process (instead +of immediately) and `{ code_block }` is arbitrary Ruby code that +provides the value. + +For example, a resource that's **not** doing lazy evaluation: + +```ruby +template 'template_name' do + # some properties + path '/foo/bar' +end +``` + +and a resource block that's doing lazy evaluation: + +```ruby +template 'template_name' do + # some properties + path lazy { ' some Ruby code ' } +end +``` + +In the previous examples, the first resource uses the value `/foo/bar` +and the second resource uses the value provided by the code block, as +long as the contents of that code block are a valid resource property. + +The following example shows how to use lazy evaluation with template +variables: + +```ruby +template '/tmp/canvey_island.txt' do + source 'canvey_island.txt.erb' + variables( + lazy do + { canvey_island: node.run_state['sea_power'] } + end + ) +end +``` diff --git a/content/reusable/md/resources_common_multiple_packages.md b/content/reusable/md/resources_common_multiple_packages.md new file mode 100644 index 0000000..11134be --- /dev/null +++ b/content/reusable/md/resources_common_multiple_packages.md @@ -0,0 +1,72 @@ +A resource may specify multiple packages and/or versions for platforms +that use Apt, Chocolatey, DNF, Homebrew, Pacman, or Zypper package managers. +Specifying multiple packages and/or versions allows a single transaction +to: + +- Download the specified packages and versions using a single HTTP + transaction +- Update or install multiple packages with a single resource during a + Chef Infra Client run + +For example, installing multiple packages: + +```ruby +package %w(package1 package2) +``` + +Installing multiple packages with versions: + +```ruby +package %w(package1 package2) do + version [ '1.3.4-2', '4.3.6-1'] +end +``` + +Upgrading multiple packages: + +```ruby +package %w(package1 package2) do + action :upgrade +end +``` + +Removing multiple packages: + +```ruby +package %w(package1 package2) do + action :remove +end +``` + +Purging multiple packages: + +```ruby +package %w(package1 package2) do + action :purge +end +``` + +Notifications, using an implicit name: + +```ruby +package %w(package1 package2) do + action :nothing +end + +log 'call a notification' do + notifies :install, 'package[package1, package2]', :immediately +end +``` + + + +
+

Note

+
+ +Notifications and subscriptions don't need to be updated when packages +and versions are added or removed from the `package_name` or `version` +properties. + +
+
diff --git a/content/reusable/md/resources_common_notification.md b/content/reusable/md/resources_common_notification.md new file mode 100644 index 0000000..d3ba8d3 --- /dev/null +++ b/content/reusable/md/resources_common_notification.md @@ -0,0 +1,3 @@ +A notification is a property on a resource that listens to other +resources in the resource collection and then takes actions based on the +notification type (`notifies` or `subscribes`). diff --git a/content/reusable/md/resources_common_notification_notifies.md b/content/reusable/md/resources_common_notification_notifies.md new file mode 100644 index 0000000..43942ae --- /dev/null +++ b/content/reusable/md/resources_common_notification_notifies.md @@ -0,0 +1,9 @@ +A resource may notify another resource to take action when its state +changes. Specify a `'resource[name]'`, the `:action` that resource +should take, and then the `:timer` for that action. A resource may +notify more than one resource; use a `notifies` statement for each +resource to be notified. + +If the referenced resource doesn't exist, an error is raised. +In contrast, `subscribes` won't fail if the source +resource isn't found. diff --git a/content/reusable/md/resources_common_notification_notifies_syntax.md b/content/reusable/md/resources_common_notification_notifies_syntax.md new file mode 100644 index 0000000..a307b05 --- /dev/null +++ b/content/reusable/md/resources_common_notification_notifies_syntax.md @@ -0,0 +1,5 @@ +The syntax for `notifies` is: + +```ruby +notifies :action, 'resource[name]', :timer +``` diff --git a/content/reusable/md/resources_common_notification_subscribes.md b/content/reusable/md/resources_common_notification_subscribes.md new file mode 100644 index 0000000..0ab804f --- /dev/null +++ b/content/reusable/md/resources_common_notification_subscribes.md @@ -0,0 +1,29 @@ +A resource may listen to another resource, and then take action if the +state of the resource being listened to changes. Specify a +`'resource[name]'`, the `:action` to be taken, and then the `:timer` for +that action. + +Note that `subscribes` doesn't apply the specified action to the +resource that it listens to - for example: + +```ruby +file '/etc/nginx/ssl/example.crt' do + mode '0600' + owner 'root' +end + +service 'nginx' do + subscribes :reload, 'file[/etc/nginx/ssl/example.crt]', :immediately +end +``` + +In this case the `subscribes` property reloads the `nginx` service +whenever its certificate file, located under +`/etc/nginx/ssl/example.crt`, is updated. `subscribes` doesn't make any +changes to the certificate file itself, it merely listens for a change +to the file, and executes the `:reload` action for its resource (in this +example `nginx`) when a change is detected. + +If the other resource doesn't exist, the subscription won't raise an +error. Contrast this with the stricter semantics of `notifies`, which +will raise an error if the other resource doesn't exist. diff --git a/content/reusable/md/resources_common_notification_subscribes_syntax.md b/content/reusable/md/resources_common_notification_subscribes_syntax.md new file mode 100644 index 0000000..e7d4d81 --- /dev/null +++ b/content/reusable/md/resources_common_notification_subscribes_syntax.md @@ -0,0 +1,5 @@ +The syntax for `subscribes` is: + +```ruby +subscribes :action, 'resource[name]', :timer +``` diff --git a/content/reusable/md/resources_common_notification_timers.md b/content/reusable/md/resources_common_notification_timers.md new file mode 100644 index 0000000..31c8950 --- /dev/null +++ b/content/reusable/md/resources_common_notification_timers.md @@ -0,0 +1,18 @@ +A timer specifies the point during a Chef Infra Client run at which a +notification is run. The following timers are available: + +`:before` + +: Specifies that the action on a notified resource should be run + before processing the resource block in which the notification is + located. + +`:delayed` + +: Default. Specifies that a notification should be queued up, and then + executed at the end of a Chef Infra Client run. + +`:immediate`, `:immediately` + +: Specifies that a notification should be run immediately, for each + resource notified. diff --git a/content/reusable/md/resources_common_powershell.md b/content/reusable/md/resources_common_powershell.md new file mode 100644 index 0000000..98d3aaa --- /dev/null +++ b/content/reusable/md/resources_common_powershell.md @@ -0,0 +1,7 @@ +Windows PowerShell is a task-based command-line shell and scripting +language developed by Microsoft. Windows PowerShell uses a +document-oriented approach for managing Windows-based +machines, similar to the approach that's used for managing Unix and +Linux-based machines. Windows PowerShell is [a tool-agnostic +platform](https://docs.microsoft.com/en-us/powershell/scripting/powershell-scripting) +that supports using Chef for configuration management. diff --git a/content/reusable/md/resources_common_powershell_dsc.md b/content/reusable/md/resources_common_powershell_dsc.md new file mode 100644 index 0000000..c730d97 --- /dev/null +++ b/content/reusable/md/resources_common_powershell_dsc.md @@ -0,0 +1,9 @@ +Desired State Configuration (DSC) is a feature of Windows PowerShell +that provides [a set of language extensions, cmdlets, and +resources](https://docs.microsoft.com/en-us/powershell/dsc/overview) +that can be used to declaratively configure software. DSC is similar to +Chef, in that both tools are idempotent, take similar approaches to the +concept of resources, describe the configuration of a system, and then +take the steps required to do that configuration. The most important +difference between Chef and DSC is that Chef uses Ruby and DSC is +exposed as configuration data from within Windows PowerShell. diff --git a/content/reusable/md/resources_common_properties.md b/content/reusable/md/resources_common_properties.md new file mode 100644 index 0000000..2107ebd --- /dev/null +++ b/content/reusable/md/resources_common_properties.md @@ -0,0 +1,31 @@ +The following properties are common to every resource: + +`compile_time` + +: **Ruby Type:** true, false \| **Default Value:** `false` + + Control the phase during which the resource is run on the node. Set to true to run while the resource collection is being built (the `compile phase`). Set to false to run while Chef Infra Client is configuring the node (the `converge phase`). + +`ignore_failure` + +: **Ruby Type:** true, false, :quiet \| **Default Value:** `false` + + Continue running a recipe if a resource fails for any reason. `:quiet` won't display the full stack trace and the recipe will continue to run if a resource fails. + +`retries` + +: **Ruby Type:** Integer \| **Default Value:** `0` + + The number of attempts to catch exceptions and retry the resource. + +`retry_delay` + +: **Ruby Type:** Integer \| **Default Value:** `2` + + The delay in seconds between retry attempts. + +`sensitive` + +: **Ruby Type:** true, false \| **Default Value:** `false` + + Ensure that sensitive resource data isn't logged by Chef Infra Client. diff --git a/content/reusable/md/resources_common_relative_paths.md b/content/reusable/md/resources_common_relative_paths.md new file mode 100644 index 0000000..1d8ef4a --- /dev/null +++ b/content/reusable/md/resources_common_relative_paths.md @@ -0,0 +1,6 @@ +The following relative paths can be used with any resource: + +`#{ENV['HOME']}` + +: Use to return the `~` path in Linux and macOS or the `%HOMEPATH%` in + Windows. diff --git a/content/reusable/md/resources_common_windows_security.md b/content/reusable/md/resources_common_windows_security.md new file mode 100644 index 0000000..8201602 --- /dev/null +++ b/content/reusable/md/resources_common_windows_security.md @@ -0,0 +1,4 @@ +To support Windows security, the **template**, **file**, +**remote_file**, **cookbook_file**, **directory**, and +**remote_directory** resources support the use of inheritance and +access control lists (ACLs) within recipes. diff --git a/content/reusable/md/resources_common_windows_security_acl.md b/content/reusable/md/resources_common_windows_security_acl.md new file mode 100644 index 0000000..b391d7e --- /dev/null +++ b/content/reusable/md/resources_common_windows_security_acl.md @@ -0,0 +1,119 @@ +The `rights` property can be used in a recipe to manage access control +lists (ACLs), which allow permissions to be given to multiple users and +groups. Use the `rights` property can be used as many times as +necessary; Chef Infra Client will apply them to the file or directory as +required. The syntax for the `rights` property is as follows: + +```ruby +rights permission, principal, option_type => value +``` + +where + +`permission` + +: Use to specify which rights are granted to the `principal`. The + possible values are: `:read`, `:write`, `read_execute`, `:modify`, + `:full_control`, or an integer. + +: Integers used for permissions must match the following list + [FileSystemRights Enum](https://docs.microsoft.com/en-us/dotnet/api/system.security.accesscontrol.filesystemrights?view=windowsdesktop-5.0#fields) fields. + + These permissions are cumulative. If `:write` is specified, then it + includes `:read`. If `:full_control` is specified, then it includes + both `:write` and `:read`. + + (For those who know the Windows API: `:read` corresponds + to `GENERIC_READ`; `:write` corresponds to `GENERIC_WRITE`; + `:read_execute` corresponds to `GENERIC_READ` and `GENERIC_EXECUTE`; + `:modify` corresponds to `GENERIC_WRITE`, `GENERIC_READ`, + `GENERIC_EXECUTE`, and `DELETE`; `:full_control` corresponds to + `GENERIC_ALL`, which allows a user to change the owner and other + metadata about a file.) + +`principal` + +: Use to specify a group or user. The principal can be specified by + either name or SID. When using name, this is identical to what's + entered in the login box for Windows, such as `user_name`, + `domain\user_name`, or `user_name@fully_qualified_domain_name`. When + using a SID, you may use either the standard string representation of + a SID (S-R-I-S-S) or one of the [security descriptor definition language (SDDL) string constants](https://docs.microsoft.com/en-us/windows/win32/secauthz/sid-strings). Chef + Infra Client doesn't need to know if a principal is a user or a + group. + +`option_type` + +: A hash that contains advanced rights options. For example, the + rights to a directory that only applies to the first level of + children might look something like: + `rights :write, 'domain\group_name', :one_level_deep => true`. + + Possible option types: + + `:applies_to_children` + + : Specify how permissions are applied to children. Possible values: `true` to inherit both child directories and files; `false` to not inherit any child directories or files; `:containers_only` to inherit only child directories (and not files); `:objects_only` to recursively inherit files (and not child directories). + + `:applies_to_self` + + : Indicates whether a permission is applied to the parent directory. Possible values: `true` to apply to the parent directory or file and its children; `false` to not apply only to child directories and files. + + `:one_level_deep` + + : Indicates the depth to which permissions will be applied. Possible values: `true` to apply only to the first level of children; `false` to apply to all children. + +For example: + +```ruby +resource 'x.txt' do + rights :read, 'S-1-1-0' + rights :write, 'domain\group' + rights :full_control, 'group_name_or_user_name' + rights :full_control, 'user_name', applies_to_children: true +end +``` + +or: + +```ruby +rights :read, %w(Administrators Everyone) +rights :full_control, 'Users', applies_to_children: true +rights :write, 'Sally', applies_to_children: :containers_only, applies_to_self: false, one_level_deep: true +``` + +Some other important things to know when using the `rights` attribute: + +- Only inherited rights remain. All existing explicit rights on the + object are removed and replaced. +- If rights aren't specified, nothing will be changed. Chef Infra + Client doesn't clear out the rights on a file or directory if + rights aren't specified. +- Changing inherited rights can be expensive. Windows will + propagate rights to all children recursively due to inheritance. + This is a normal aspect of Windows, so consider the + frequency with which this type of action is necessary and take steps + to control this type of action if performance is the primary + consideration. + +Use the `deny_rights` property to deny specific rights to specific +users. The ordering is independent of using the `rights` property. For +example, it doesn't matter if rights are granted to everyone is placed +before or after `deny_rights :read, ['Julian', 'Lewis']`, both Julian +and Lewis will be unable to read the document. For example: + +```ruby +resource 'x.txt' do + rights :read, 'Everyone' + rights :write, 'domain\group' + rights :full_control, 'group_name_or_user_name' + rights :full_control, 'user_name', applies_to_children: true + deny_rights :read, %w(Julian Lewis) +end +``` + +or: + +```ruby +deny_rights :full_control, ['Sally'] +``` diff --git a/content/reusable/md/resources_common_windows_security_inherits.md b/content/reusable/md/resources_common_windows_security_inherits.md new file mode 100644 index 0000000..030481f --- /dev/null +++ b/content/reusable/md/resources_common_windows_security_inherits.md @@ -0,0 +1,51 @@ +By default, a file or directory inherits rights from its parent +directory. Most of the time this is the preferred behavior, but +sometimes it may be necessary to take steps to more specifically control +rights. The `inherits` property can be used to specifically tell Chef +Infra Client to apply (or not apply) inherited rights from its parent +directory. + +For example, the following example specifies the rights for a directory: + +```ruby +directory 'C:\mordor' do + rights :read, 'MORDOR\Minions' + rights :full_control, 'MORDOR\Sauron' +end +``` + +and then the following example specifies how to use inheritance to deny +access to the child directory: + +```ruby +directory 'C:\mordor\mount_doom' do + rights :full_control, 'MORDOR\Sauron' + inherits false # Sauron is the only person who should have any sort of access +end +``` + +If the `deny_rights` permission were to be used instead, something could +slip through unless all users and groups were denied. + +Another example also shows how to specify rights for a directory: + +```ruby +directory 'C:\mordor' do + rights :read, 'MORDOR\Minions' + rights :full_control, 'MORDOR\Sauron' + rights :write, 'SHIRE\Frodo' # Who put that there I didn't put that there +end +``` + +but then not use the `inherits` property to deny those rights on a child +directory: + +```ruby +directory 'C:\mordor\mount_doom' do + deny_rights :read, 'MORDOR\Minions' # Oops, not specific enough +end +``` + +Because the `inherits` property isn't specified, Chef Infra Client will +default it to `true`, which will ensure that security settings for +existing files remain unchanged. diff --git a/content/reusable/md/role.md b/content/reusable/md/role.md new file mode 100644 index 0000000..077a0d4 --- /dev/null +++ b/content/reusable/md/role.md @@ -0,0 +1,9 @@ +A role is a way to define certain patterns and processes that exist +across nodes in an organization as belonging to a single job function. +Each role consists of zero (or more) attributes and a run-list. Each +node can have zero (or more) roles assigned to it. When a role is run +against a node, the configuration details of that node are compared +against the attributes of the role, and then the contents of that role's +run-list are applied to the node's configuration details. When a Chef +Infra Client runs, it merges its own attributes and run-lists with those +contained within each assigned role. diff --git a/content/reusable/md/role_attribute.md b/content/reusable/md/role_attribute.md new file mode 100644 index 0000000..335bd75 --- /dev/null +++ b/content/reusable/md/role_attribute.md @@ -0,0 +1,12 @@ +An attribute can be defined in a role and then used to override the +default settings on a node. When a role is applied during a Chef Infra +Client run, these attributes are compared to the attributes that are +already present on the node. When the role attributes take precedence +over the default attributes, Chef Infra Client applies those new +settings and values during a Chef Infra Client run. + +A role attribute can only be set to be a default attribute or an +override attribute. A role attribute can't be set to be a normal +attribute. Use the `default_attribute` and `override_attribute` methods +in the `.rb` attributes file or the `default_attributes` and +`override_attributes` hashes in a JSON data file. diff --git a/content/reusable/md/ruby_class_chef_log_fatal.md b/content/reusable/md/ruby_class_chef_log_fatal.md new file mode 100644 index 0000000..d624558 --- /dev/null +++ b/content/reusable/md/ruby_class_chef_log_fatal.md @@ -0,0 +1,38 @@ +The following example shows a series of fatal `Chef::Log` entries: + +```ruby +unless node['splunk']['upgrade_enabled'] + Chef::Log.fatal('The chef-splunk::upgrade recipe was added to the node,') + Chef::Log.fatal('but the attribute `node["splunk"]["upgrade_enabled"]` wasn\'t set.') + Chef::Log.fatal('I am bailing here so this node doesn\'t upgrade.') + raise +end + +service 'splunk_stop' do + service_name 'splunk' + supports status: true + action :stop +end + +if node['splunk']['is_server'] + splunk_package = 'splunk' + url_type = 'server' +else + splunk_package = 'splunkforwarder' + url_type = 'forwarder' +end + +splunk_installer splunk_package do + url node['splunk']['upgrade']["#{url_type}_url"] +end + +if node['splunk']['accept_license'] + execute 'splunk-unattended-upgrade' do + command "#{splunk_cmd} start --accept-license --answer-yes" + end +else + Chef::Log.fatal('You didn\'t accept the license (set node["splunk"]["accept_license"] to true)') + Chef::Log.fatal('Splunk is stopped and can\'t be restarted until the license is accepted!') + raise +end +``` diff --git a/content/reusable/md/ruby_class_chef_log_multiple.md b/content/reusable/md/ruby_class_chef_log_multiple.md new file mode 100644 index 0000000..9e37444 --- /dev/null +++ b/content/reusable/md/ruby_class_chef_log_multiple.md @@ -0,0 +1,15 @@ +The following example shows using multiple `Chef::Log` entry types: + +```ruby +... + +begin + aws = Chef::DataBagItem.load(:aws, :main) + Chef::Log.info("Loaded AWS information from DataBagItem aws[#{aws['id']}]") +rescue + Chef::Log.fatal("Couldn't find the 'main' item in the 'aws' data bag") + raise +end + +... +``` diff --git a/content/reusable/md/ruby_style_basics_chef_log.md b/content/reusable/md/ruby_style_basics_chef_log.md new file mode 100644 index 0000000..eb6fac3 --- /dev/null +++ b/content/reusable/md/ruby_style_basics_chef_log.md @@ -0,0 +1,40 @@ +`Chef::Log` will print log entries to the default logger that's configured for the machine on which Chef Infra Client is running. (To create a log entry that's built into the resource collection, use the [log resource](/resources/bundled/log/) instead of `Chef::Log`.) + + + +### Supported log levels + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Log LevelSyntax
FatalChef::Log.fatal('string')
ErrorChef::Log.error('string')
WarnChef::Log.warn('string')
InfoChef::Log.info('string')
DebugChef::Log.debug('string')
diff --git a/content/reusable/md/ruby_style_patterns_hyphens.md b/content/reusable/md/ruby_style_patterns_hyphens.md new file mode 100644 index 0000000..2d5d29d --- /dev/null +++ b/content/reusable/md/ruby_style_patterns_hyphens.md @@ -0,0 +1,6 @@ +Cookbook and custom resource names should contain only alphanumeric +characters. A hyphen (`-`) is a valid character and may be used in +cookbook and custom resource names, but it's discouraged. Chef Infra +Client will return an error if a hyphen isn't converted to an +underscore (`_`) when referencing from a recipe the name of a custom +resource in which a hyphen is located. diff --git a/content/reusable/md/ruby_style_patterns_string_quoting_vs_whitespace_array.md b/content/reusable/md/ruby_style_patterns_string_quoting_vs_whitespace_array.md new file mode 100644 index 0000000..8b155bc --- /dev/null +++ b/content/reusable/md/ruby_style_patterns_string_quoting_vs_whitespace_array.md @@ -0,0 +1,24 @@ +When `%w` syntax uses a variable, such as `|foo|`, double quoted strings +should be used. + +Right: + +```ruby +%w(openssl.cnf pkitool vars Rakefile).each do |foo| + template "/etc/openvpn/easy-rsa/#{foo}" do + source "#{foo}.erb" + ... + end +end +``` + +Wrong: + +```ruby +%w(openssl.cnf pkitool vars Rakefile).each do |foo| + template '/etc/openvpn/easy-rsa/#{foo}' do + source '#{foo}.erb' + ... + end +end +``` diff --git a/content/reusable/md/ruby_summary.md b/content/reusable/md/ruby_summary.md new file mode 100644 index 0000000..80e8a77 --- /dev/null +++ b/content/reusable/md/ruby_summary.md @@ -0,0 +1,17 @@ +Ruby is a simple programming language: + +- Chef uses Ruby as its reference language to define the patterns that + are found in resources, recipes, and cookbooks +- Use these patterns to configure, deploy, and manage nodes across the + network + +Ruby is also a powerful and complete programming language: + +- Use the Ruby programming language to make decisions about what + should happen to specific resources and recipes +- Extend Chef in any manner that your organization requires + +To learn more about Ruby, see: + +- [Ruby Documentation](https://www.ruby-lang.org/en/documentation/) +- [Ruby Standard Library Documentation](https://www.ruby-doc.org/stdlib/) diff --git a/content/reusable/md/search.md b/content/reusable/md/search.md new file mode 100644 index 0000000..1b304dc --- /dev/null +++ b/content/reusable/md/search.md @@ -0,0 +1,10 @@ +Search indexes allow queries to be made for any type of data that's +indexed by Chef Infra Server, including data bags (and data bag +items), environments, nodes, and roles. A defined query syntax is used +to support search patterns like exact, wildcard, range, and fuzzy. A +search is a full-text query that can be done from several locations, +including from within a recipe, by using the `search` subcommand in +knife, the `search` method in the Chef Infra Language, the search box in the Chef +management console, and by using the `/search` or `/search/INDEX` +endpoints in the Chef Infra Server API. The search engine is based on +Elasticsearch and is run from Chef Infra Server. diff --git a/content/reusable/md/search_boolean_and.md b/content/reusable/md/search_boolean_and.md new file mode 100644 index 0000000..6d09bb0 --- /dev/null +++ b/content/reusable/md/search_boolean_and.md @@ -0,0 +1,54 @@ +To join queries using the `AND` boolean operator, enter the following: + +```bash +knife search sample "id:b* AND animal:dog" +``` + +to return something like: + +```bash +{ + "total": 1, + "start": 0, + "rows": [ + { + "comment": "an item named baz", + "id": "baz", + "animal": "dog" + } + ] +} +``` + +Or, to find all of the computers running on the Windows +platform that are associated with a role named `jenkins`, enter: + +```bash +knife search node 'platform:windows AND roles:jenkins' +``` + +to return something like: + +```bash +2 items found + +Node Name: windows-server-2012r2.domain.com +Environment: _default +FQDN: windows-server-2012r2 +IP: 0000::0000:0000:0000:0000 +Run List: role[jenkins-windows] +Roles: jenkins-windows, jenkins +Recipes: jenkins-client::windows, jenkins::node_windows +Platform: windows 6.3.9600 +Tags: + +Node Name: 123-windows-2012r2-amd64-builder +Environment: _default +FQDN: ABC-1234567890AB +IP: 123.45.6.78 +Run List: role[123-windows-2012r2-amd64-builder] +Roles: 123-windows-2012r2-amd64-builder, jenkins +Recipes: jenkins::node_windows, git_windows +Platform: windows 6.3.9600 +Tags: +``` diff --git a/content/reusable/md/search_boolean_not.md b/content/reusable/md/search_boolean_not.md new file mode 100644 index 0000000..7b0292a --- /dev/null +++ b/content/reusable/md/search_boolean_not.md @@ -0,0 +1,37 @@ +To negate search results using the `NOT` boolean operator, enter the +following: + +```bash +knife search sample "(NOT id:foo)" +``` + +to return something like: + +```bash +{ + "total": 4, + "start": 0, + "rows": [ + { + "comment": "an item named bar", + "id": "bar", + "animal": "cat" + }, + { + "comment": "an item named baz", + "id": "baz" + "animal": "dog" + }, + { + "comment": "an item named abc", + "id": "abc", + "animal": "unicorn" + }, + { + "comment": "an item named qux", + "id": "qux", + "animal", "penguin" + } + ] +} +``` diff --git a/content/reusable/md/search_boolean_operators.md b/content/reusable/md/search_boolean_operators.md new file mode 100644 index 0000000..6eff881 --- /dev/null +++ b/content/reusable/md/search_boolean_operators.md @@ -0,0 +1,31 @@ +An operator can be used to ensure that certain terms are included in the +results, are excluded from the results, or aren't included even when +other aspects of the query match. Searches can use the following +operators: + + ++++ + + + + + + + + + + + + + + + + + + + + +
OperatorDescription
ANDUse to find a match when both terms exist.
ORUse to find a match if either term exists.
NOTUse to exclude the term after NOT from the search results.
diff --git a/content/reusable/md/search_boolean_operators_andnot.md b/content/reusable/md/search_boolean_operators_andnot.md new file mode 100644 index 0000000..7c520b0 --- /dev/null +++ b/content/reusable/md/search_boolean_operators_andnot.md @@ -0,0 +1,25 @@ +Operators must be in ALL CAPS. Parentheses can be used to group clauses +and to form sub-queries. + + + +
+

Warning

+
+ +Using `AND NOT` together may trigger an error. For example: + +```bash +ERROR: knife search failed: invalid search query: +'datacenter%3A123%20AND%20NOT%20hostname%3Adev-%20AND%20NOT%20hostanem%3Asyslog-' +Parse error at offset: 38 Reason: Expected one of \ at line 1, column 42 (byte 42) after AND +``` + +Use `-` instead of `NOT`. For example: + +```bash +knife search sample "id:foo AND -id:bar" +``` + +
+
diff --git a/content/reusable/md/search_boolean_or.md b/content/reusable/md/search_boolean_or.md new file mode 100644 index 0000000..7a50d52 --- /dev/null +++ b/content/reusable/md/search_boolean_or.md @@ -0,0 +1,26 @@ +To join queries using the `OR` boolean operator, enter the following: + +```bash +knife search sample "id:foo OR id:abc" +``` + +to return something like: + +```bash +{ + "total": 2, + "start": 0, + "rows": [ + { + "comment": "an item named foo", + "id": "foo", + "animal": "pony" + }, + { + "comment": "an item named abc", + "id": "abc", + "animal": "unicorn" + } + ] +} +``` diff --git a/content/reusable/md/search_data_bag.md b/content/reusable/md/search_data_bag.md new file mode 100644 index 0000000..614428e --- /dev/null +++ b/content/reusable/md/search_data_bag.md @@ -0,0 +1,106 @@ +Any search for a data bag (or a data bag item) must specify the name of +the data bag and then provide the search query string that will be used +during the search. For example, to use knife to search within a data bag +named "admin_data" across all items, except for the "admin_users" +item, enter the following: + +```bash +knife search admin_data "(NOT id:admin_users)" +``` + +Or, to include the same search query in a recipe, use a code block +similar to: + +```ruby +search(:admin_data, 'NOT id:admin_users') +``` + +It may not be possible to know which data bag items will be needed. It +may be necessary to load everything in a data bag (but not know what +"everything" is). Using a search query is the ideal way to deal with +that ambiguity, yet still ensure that all of the required data is +returned. The following examples show how a recipe can use a series of +search queries to search within a data bag named `admins`. For example, +to find every administrator: + +```ruby +search(:admins, '*:*') +``` + +Or to search for an administrator named "charlie": + +```ruby +search(:admins, 'id:charlie') +``` + +Or to search for an administrator with a group identifier of "ops": + +```ruby +search(:admins, 'gid:ops') +``` + +Or to search for an administrator whose name begins with the letter "c": + +```ruby +search(:admins, 'id:c*') +``` + +Data bag items that are returned by a search query can be used as if +they were a hash. For example: + +```ruby +charlie = search(:admins, 'id:charlie').first +# => variable 'charlie' is set to the charlie data bag item +charlie['gid'] +# => "ops" +charlie['shell'] +# => "/bin/zsh" +``` + +The following recipe can be used to create a user for each administrator +by loading all of the items from the `admins` data bag, looping through +each admin in the data bag, and then creating a user resource so that +each of those admins exist: + +```ruby +admins = data_bag('admins') + +admins.each do |login| + admin = data_bag_item('admins', login) + home = "/home/#{login}" + + user(login) do + uid admin['uid'] + gid admin['gid'] + shell admin['shell'] + comment admin['comment'] + home home + manage_home true + end +end +``` + +And then the same recipe, modified to load administrators using a search +query (and using an array to store the results of the search query): + +```ruby +admins = [] + +search(:admins, '*:*').each do |admin| + login = admin['id'] + + admins << login + + home = "/home/#{login}" + + user(login) do + uid admin['uid'] + gid admin['gid'] + shell admin['shell'] + comment admin['comment'] + + home home + manage_home true + end +end +``` diff --git a/content/reusable/md/search_environment.md b/content/reusable/md/search_environment.md new file mode 100644 index 0000000..43ed771 --- /dev/null +++ b/content/reusable/md/search_environment.md @@ -0,0 +1,18 @@ +When searching, an environment is an attribute. This allows search +results to be limited to a specified environment by using Boolean +operators and extra search terms. For example, to use knife to search +for all of the servers running CentOS in an environment named `QA`, +enter the following: + +```bash +knife search node "chef_environment:QA AND platform:centos" +``` + +Or, to include the same search in a recipe, use a code block similar to: + +```ruby +qa_nodes = search(:node, 'chef_environment:QA') +qa_nodes.each do |qa_node| + # Do useful work specific to qa nodes only +end +``` diff --git a/content/reusable/md/search_key.md b/content/reusable/md/search_key.md new file mode 100644 index 0000000..46888d6 --- /dev/null +++ b/content/reusable/md/search_key.md @@ -0,0 +1,4 @@ +A field name/description pair is available in the JSON object. Use the +field name when searching for this information in the JSON object. Any +field that exists in any JSON description for any role, node, Chef Infra +Client, environment, or data bag can be searched. diff --git a/content/reusable/md/search_key_name.md b/content/reusable/md/search_key_name.md new file mode 100644 index 0000000..58d310b --- /dev/null +++ b/content/reusable/md/search_key_name.md @@ -0,0 +1,9 @@ +To see the available keys for a node, enter the following (for a node +named `staging`): + +```bash +knife node show staging -Fj | less +``` + +to return a full JSON description of the node and to view the available +keys with which any search query can be based. diff --git a/content/reusable/md/search_key_nested.md b/content/reusable/md/search_key_nested.md new file mode 100644 index 0000000..1c7ca64 --- /dev/null +++ b/content/reusable/md/search_key_nested.md @@ -0,0 +1,142 @@ +A nested field appears deeper in the JSON data structure. For example, +information about a network interface might be several layers deep: +`node['network']['interfaces']['en1']`. When nested fields are present +in a JSON structure, Chef Infra Client will extract those nested fields +to the top-level, flattening them into compound fields that support +wildcard search patterns. + +By combining wildcards with range-matching patterns and wildcard +queries, it's possible to perform powerful searches, such as using +the vendor part of the MAC address to find every node that has a network +card made by the specified vendor. + +Consider the following snippet of JSON data: + +```json +{"network": + [ + //snipped... + "interfaces", + {"en1": { + "number": "1", + "flags": [ + "UP", + "BROADCAST", + "SMART", + "RUNNING", + "SIMPLEX", + "MULTICAST" + ], + "addresses": { + "fe80::fa1e:dfff:fed8:63a2": { + "scope": "Link", + "prefixlen": "64", + "family": "inet6" + }, + "f8:1e:df:d8:63:a2": { + "family": "lladdr" + }, + "192.0.2.0": { + "netmask": "255.255.255.0", + "broadcast": "192.168.0.255", + "family": "inet" + } + }, + "mtu": "1500", + "media": { + "supported": { + "autoselect": { + "options": [ + + ] + } + }, + "selected": { + "autoselect": { + "options": [ + + ] + } + } + }, + "type": "en", + "status": "active", + "encapsulation": "Ethernet" + }, + //snipped... +``` + +Before this data is indexed on Chef Infra Server, the nested fields +are extracted into the top level, similar to: + +```ruby +"broadcast" => "192.168.0.255", +"flags" => ["UP", "BROADCAST", "SMART", "RUNNING", "SIMPLEX", "MULTICAST"] +"mtu" => "1500" +``` + +which allows searches like the following to find data that's present in +this node: + +```ruby +node "broadcast:192.168.0.*" +``` + +or: + +```ruby +node "mtu:1500" +``` + +or: + +```ruby +node "flags:UP" +``` + +This data is also flattened into various compound fields, which follow +the same pattern as the JSON hierarchy and use underscores (`_`) to +separate the levels of data, similar to: + +```ruby +# ...snip... +"network_interfaces_en1_addresses_192.0.2.0_broadcast" => "192.168.0.255", +"network_interfaces_en1_addresses_fe80::fa1e:tldr_family" => "inet6", +"network_interfaces_en1_addresses" => ["fe80::fa1e:tldr","f8:1e:df:tldr","192.0.2.0"] +# ...snip... +``` + +which allows searches like the following to find data that's present in +this node: + +```ruby +node "network_interfaces_en1_addresses:192.0.2.0" +``` + +This flattened data structure also supports using wildcard compound +fields, which allow searches to omit levels within the JSON data +structure that aren't important to the search query. In the following +example, an asterisk (`*`) is used to show where the wildcard can exist +when searching for a nested field: + +```ruby +"network_interfaces_*_flags" => ["UP", "BROADCAST", "SMART", "RUNNING", "SIMPLEX", "MULTICAST"] +"network_interfaces_*_addresses" => ["fe80::fa1e:dfff:fed8:63a2", "192.0.2.0", "f8:1e:df:d8:63:a2"] +"network_interfaces_en0_media_*" => ["autoselect", "none", "1000baseT", "10baseT/UTP", "100baseTX"] +"network_interfaces_en1_*" => ["1", "UP", "BROADCAST", "SMART", "RUNNING", "SIMPLEX", "MULTICAST", + "fe80::fa1e:dfff:fed8:63a2", "f8:1e:df:d8:63:a2", "192.0.2.0", + "1500", "supported", "selected", "en", "active", "Ethernet"] +``` + +For each of the wildcard examples above, the possible values are shown +contained within the brackets. When running a search query, the query +syntax for wildcards is to simply omit the name of the node (while +preserving the underscores), similar to: + +```ruby +network_interfaces__flags +``` + +This query will search within the `flags` node, within the JSON +structure, for each of `UP`, `BROADCAST`, `SMART`, `RUNNING`, `SIMPLEX`, +and `MULTICAST`. diff --git a/content/reusable/md/search_key_nested_range.md b/content/reusable/md/search_key_nested_range.md new file mode 100644 index 0000000..84d7e14 --- /dev/null +++ b/content/reusable/md/search_key_nested_range.md @@ -0,0 +1,8 @@ +To use a range search to find IP addresses within a subnet, enter the +following: + +```bash +knife search node 'ipaddress:[192.168.0.* TO 192.0.2.*]' +``` + +where `192.168.0.* TO 192.0.2.*` defines the subnet range. diff --git a/content/reusable/md/search_key_nested_starting_with.md b/content/reusable/md/search_key_nested_starting_with.md new file mode 100644 index 0000000..5611109 --- /dev/null +++ b/content/reusable/md/search_key_nested_starting_with.md @@ -0,0 +1,9 @@ +To find all IP address that are on the same network, enter the +following: + +```bash +knife search node 'ipaddress:192.168*' +``` + +where `192.168*` is the network address for which the search will be +run. diff --git a/content/reusable/md/search_key_wildcard_asterisk.md b/content/reusable/md/search_key_wildcard_asterisk.md new file mode 100644 index 0000000..b29fd76 --- /dev/null +++ b/content/reusable/md/search_key_wildcard_asterisk.md @@ -0,0 +1,6 @@ +To use an asterisk (`*`) to replace zero (or more) characters in a +wildcard search, enter the following: + +```bash +knife search node 'platfo*:ubuntu' +``` diff --git a/content/reusable/md/search_key_wildcard_question_mark.md b/content/reusable/md/search_key_wildcard_question_mark.md new file mode 100644 index 0000000..3a5b169 --- /dev/null +++ b/content/reusable/md/search_key_wildcard_question_mark.md @@ -0,0 +1,6 @@ +To use a question mark (`?`) to replace a single character in a wildcard +search, enter the following: + +```bash +knife search node 'platfor?:ubuntu' +``` diff --git a/content/reusable/md/search_pattern.md b/content/reusable/md/search_pattern.md new file mode 100644 index 0000000..f594cc2 --- /dev/null +++ b/content/reusable/md/search_pattern.md @@ -0,0 +1,4 @@ +A search pattern is a way to fine-tune search results by returning +anything that matches some type of incomplete search query. There are +four types of search patterns that can be used when searching the search +indexes on Chef Infra Server: exact, wildcard, range, and fuzzy. diff --git a/content/reusable/md/search_pattern_exact.md b/content/reusable/md/search_pattern_exact.md new file mode 100644 index 0000000..b9f4159 --- /dev/null +++ b/content/reusable/md/search_pattern_exact.md @@ -0,0 +1,8 @@ +An exact matching search pattern is used to search for a key with a name +that exactly matches a search query. If the name of the key contains +spaces, quotes must be used in the search pattern to ensure the search +query finds the key. The entire query must also be contained within +quotes, so as to prevent it from being interpreted by Ruby or a command +shell. The best way to ensure that quotes are used consistently is to +quote the entire query using single quotes (' ') and a search pattern +with double quotes (" "). diff --git a/content/reusable/md/search_pattern_exact_key_and_item.md b/content/reusable/md/search_pattern_exact_key_and_item.md new file mode 100644 index 0000000..0762f61 --- /dev/null +++ b/content/reusable/md/search_pattern_exact_key_and_item.md @@ -0,0 +1,21 @@ +To search in a specific data bag for a specific data bag item, enter the +following: + +```bash +knife search admins 'id:charlie' +``` + +where `admins` is the name of the data bag and `charlie` is the name of +the data bag item. Something similar to the following will be returned: + +```bash +1 items found +_rev: 1-39ff4099f2510f477b4c26bef81f75b9 +chef_type: data_bag_item +comment: Charlie the Unicorn +data_bag: admins +gid: ops +id: charlie +shell: /bin/zsh +uid: 1005 +``` diff --git a/content/reusable/md/search_pattern_exact_key_and_item_string.md b/content/reusable/md/search_pattern_exact_key_and_item_string.md new file mode 100644 index 0000000..0777c72 --- /dev/null +++ b/content/reusable/md/search_pattern_exact_key_and_item_string.md @@ -0,0 +1,22 @@ +To search in a specific data bag using a string to find any matching +data bag item, enter the following: + +```bash +knife search admins 'comment:"Charlie the Unicorn"' +``` + +where `admins` is the name of the data bag and `Charlie the Unicorn` is +the string that will be used during the search. Something similar to the +following will be returned: + +```bash +1 items found +_rev: 1-39ff4099f2510f477b4c26bef81f75b9 +chef_type: data_bag_item +comment: Charlie the Unicorn +data_bag: admins +gid: ops +id: charlie +shell: /bin/zsh +uid: 1005 +``` diff --git a/content/reusable/md/search_pattern_fuzzy.md b/content/reusable/md/search_pattern_fuzzy.md new file mode 100644 index 0000000..871fa88 --- /dev/null +++ b/content/reusable/md/search_pattern_fuzzy.md @@ -0,0 +1,12 @@ +A fuzzy matching search pattern is used to search based on the proximity +of two strings of characters. An (optional) integer may be used as part +of the search query to more closely define the proximity. A fuzzy +matching search pattern has the following syntax: + +```ruby +"search_query"~edit_distance +``` + +where `search_query` is the string that will be used during the search +and `edit_distance` is the proximity. A tilde ("\~") is used to separate +the edit distance from the search query. diff --git a/content/reusable/md/search_pattern_fuzzy_summary.md b/content/reusable/md/search_pattern_fuzzy_summary.md new file mode 100644 index 0000000..f27bb98 --- /dev/null +++ b/content/reusable/md/search_pattern_fuzzy_summary.md @@ -0,0 +1,25 @@ +To use a fuzzy search pattern enter something similar to: + +```bash +knife search client "name:boo~" +``` + +where `boo~` defines the fuzzy search pattern. This will return +something similar to: + +```json +{ + "total": 1, + "start": 0, + "rows": [ + { + "public_key": "too long didn't read", + "name": "foo", + "_rev": "1-f11a58043906e33d39a686e9b58cd92f", + "json_class": "Chef::ApiClient", + "admin": false, + "chef_type": "client" + } + ] +} +``` diff --git a/content/reusable/md/search_pattern_range.md b/content/reusable/md/search_pattern_range.md new file mode 100644 index 0000000..3682bfb --- /dev/null +++ b/content/reusable/md/search_pattern_range.md @@ -0,0 +1,12 @@ +A range matching search pattern is used to query for values that are +within a range defined by upper and lower boundaries. A range matching +search pattern can be inclusive or exclusive of the boundaries. Use +square brackets ("\[ \]") to denote inclusive boundaries and curly +braces ("{ }") to denote exclusive boundaries and with the following +syntax: + +```ruby +boundary TO boundary +``` + +where `TO` is required (and must be capitalized). diff --git a/content/reusable/md/search_pattern_range_exclusive.md b/content/reusable/md/search_pattern_range_exclusive.md new file mode 100644 index 0000000..ce5ad11 --- /dev/null +++ b/content/reusable/md/search_pattern_range_exclusive.md @@ -0,0 +1,11 @@ +A data bag named `sample` contains four data bag items: `abc`, `bar`, +`baz`, and `quz`. All of the items that are exclusive to `bar` and `foo` +can be searched for using an exclusive search pattern. + +To search using an exclusive range, enter the following: + +```bash +knife search sample "id:{bar TO foo}" +``` + +where curly braces (`{ }`) are used to define the range. diff --git a/content/reusable/md/search_pattern_range_in_between.md b/content/reusable/md/search_pattern_range_in_between.md new file mode 100644 index 0000000..4275429 --- /dev/null +++ b/content/reusable/md/search_pattern_range_in_between.md @@ -0,0 +1,11 @@ +A data bag named `sample` contains four data bag items: `abc`, `bar`, +`baz`, and `quz`. All of the items in-between `bar` and `foo`, +inclusive, can be searched for using an inclusive search pattern. + +To search using an inclusive range, enter the following: + +```bash +knife search sample "id:[bar TO foo]" +``` + +where square brackets (`[ ]`) are used to define the range. diff --git a/content/reusable/md/search_pattern_wildcard.md b/content/reusable/md/search_pattern_wildcard.md new file mode 100644 index 0000000..97825af --- /dev/null +++ b/content/reusable/md/search_pattern_wildcard.md @@ -0,0 +1,9 @@ +A wildcard matching search pattern is used to query for substring +matches that replace zero (or more) characters in the search pattern +with anything that could match the replaced character. There are two +types of wildcard searches: + +- A question mark (`?`) can be used to replace exactly one character + (as long as that character isn't the first character in the search + pattern) +- An asterisk (`*`) can be used to replace any number of characters (including zero) diff --git a/content/reusable/md/search_pattern_wildcard_any_node.md b/content/reusable/md/search_pattern_wildcard_any_node.md new file mode 100644 index 0000000..dc43166 --- /dev/null +++ b/content/reusable/md/search_pattern_wildcard_any_node.md @@ -0,0 +1,8 @@ +To search for any node that contains the specified key, enter the +following: + +```bash +knife search node 'foo:*' +``` + +where `foo` is the name of the node. diff --git a/content/reusable/md/search_pattern_wildcard_node_contains.md b/content/reusable/md/search_pattern_wildcard_node_contains.md new file mode 100644 index 0000000..a61aa9b --- /dev/null +++ b/content/reusable/md/search_pattern_wildcard_node_contains.md @@ -0,0 +1,26 @@ +To search for a node using a partial name, enter one of the following: + +```bash +knife search node 'name:app*' +``` + +or: + +```bash +knife search node 'name:app1*.example.com' +``` + +or: + +```bash +knife search node 'name:app?.example.com' +``` + +or: + +```bash +knife search node 'name:app1.example.???' +``` + +to return `app1.example.com` (and any other node that matches any of the +string searches above). diff --git a/content/reusable/md/search_query_syntax.md b/content/reusable/md/search_query_syntax.md new file mode 100644 index 0000000..dfc6178 --- /dev/null +++ b/content/reusable/md/search_query_syntax.md @@ -0,0 +1,15 @@ +A search query is comprised of two parts: the key and the search +pattern. A search query has the following syntax: + +```ruby +key:search_pattern +``` + +where `key` is a field name that's found in the JSON description of an +indexable object on Chef Infra Server (a role, node, client, +environment, or data bag) and `search_pattern` defines what will be +searched for, using one of the following search patterns: exact, +wildcard, range, or fuzzy matching. Both `key` and `search_pattern` are +case-sensitive; `key` has limited support for multiple character +wildcard matching using an asterisk ("\*") (and as long as it's not the +first character). diff --git a/content/reusable/md/search_special_characters.md b/content/reusable/md/search_special_characters.md new file mode 100644 index 0000000..21fae69 --- /dev/null +++ b/content/reusable/md/search_special_characters.md @@ -0,0 +1,15 @@ +A special character can be used to fine-tune a search query and to +increase the accuracy of the search results. The following characters +can be included within the search query syntax, but each occurrence of a +special character must be escaped with a backslash (`\`), also (`/`) +must be escaped against the Elasticsearch: + +```ruby ++ - && | | ! ( ) { } [ ] ^ " ~ * ? : \ / +``` + +For example: + +```ruby +\(1\+1\)\:2 +``` diff --git a/content/reusable/md/security_chef_validator.md b/content/reusable/md/security_chef_validator.md new file mode 100644 index 0000000..86411b0 --- /dev/null +++ b/content/reusable/md/security_chef_validator.md @@ -0,0 +1,5 @@ +Every request made by Chef Infra Client to Chef Infra Server must be +an authenticated request using the Chef Infra Server API and a private +key. When Chef Infra Client makes a request to Chef Infra Server, +Chef Infra Client authenticates each request using a private key located +in `/etc/chef/client.pem`. diff --git a/content/reusable/md/security_chef_validator_context.md b/content/reusable/md/security_chef_validator_context.md new file mode 100644 index 0000000..eed10e6 --- /dev/null +++ b/content/reusable/md/security_chef_validator_context.md @@ -0,0 +1,11 @@ +The private key doesn't yet exist the first time that Chef Infra Client runs from a new node. + +During the first Chef Infra Client run: + +1. Chef Infra Client uses the chef-validator private key, located in `/etc/chef/validation.pem` to register with Chef Infra Server +2. Chef Infra Server assigns Chef Infra Client a private key for all future authentication requests to Chef Infra Server +3. Chef Infra Client saves the private key on the node as `/etc/chef/client.pem` + +If the request to communicate with Chef Infra Server with the chef-validator key fails, then the entire first Chef Infra Client run fails. + +After the first completed Chef Infra Client run, delete the chef-validator private key at `/etc/chef/validation.pem` diff --git a/content/reusable/md/security_key_pairs_chef_client.md b/content/reusable/md/security_key_pairs_chef_client.md new file mode 100644 index 0000000..78c2399 --- /dev/null +++ b/content/reusable/md/security_key_pairs_chef_client.md @@ -0,0 +1,5 @@ +Chef Infra Client authenticates with Chef Infra Server using RSA +public key-pairs each time a Chef Infra Client needs access to data that +is stored on Chef Infra Server. This prevents any node from +accessing data that it shouldn't and it ensures that only nodes that are +properly registered with Chef Infra Server can be managed. diff --git a/content/reusable/md/server/chef_auth.md b/content/reusable/md/server/chef_auth.md new file mode 100644 index 0000000..aa6ad7e --- /dev/null +++ b/content/reusable/md/server/chef_auth.md @@ -0,0 +1 @@ +The Chef Infra Server API handles all communication between Chef Infra Client or Chef Workstation. The Chef Infra Server API is an authenticated REST API, which means all requests require authentication and authorization. The Chef Infra tools such as `knife` and `chef-server` commands use the Chef Infra Server API for you. diff --git a/content/reusable/md/server/chef_auth_authentication.md b/content/reusable/md/server/chef_auth_authentication.md new file mode 100644 index 0000000..dbd0682 --- /dev/null +++ b/content/reusable/md/server/chef_auth_authentication.md @@ -0,0 +1,8 @@ + +The authentication process ensures that Chef Infra Server only responds to requests made by trusted users or clients. Chef Infra Server uses public key encryption. You create the public and private keys when you configure [Chef Infra Client](/install/config_rb_client/) or setup [Chef Workstation](https://docs.chef.io/workstation/getting_started/#set-up-chef-credentials). + +* Chef Infra Server stores the public key +* Chef Workstation saves the private key in `~/.chef/` +* Chef Infra Client saves the private key in `/etc/chef` + +Both Chef Infra Client and Chef Workstation communicate with Chef Infra Server using the Chef Infra Server API. Each time that Chef Infra Client or Chef Workstation makes a request to Chef Infra Server, they use a special group of HTTP headers and sign the rest with their private key. Chef Infra Server then uses the public key to verify the headers and contents. diff --git a/content/reusable/md/server/chef_server.md b/content/reusable/md/server/chef_server.md new file mode 100644 index 0000000..8635186 --- /dev/null +++ b/content/reusable/md/server/chef_server.md @@ -0,0 +1,9 @@ +The Chef Infra Server acts as a hub for configuration data. The Chef +Infra Server stores cookbooks, the policies that are applied to nodes, +and the metadata that describes each registered node that's under management +by Chef Infra Client. Nodes use Chef Infra Client to ask the Chef Infra +Server for configuration details, such as recipes, templates, and file +distributions. Chef Infra Client then does as much of the configuration +work as possible on the nodes themselves (and not on the Chef Infra +Server). This scalable approach distributes the configuration effort +throughout the organization. diff --git a/content/reusable/md/server/config_ocid_application_hash_supermarket.md b/content/reusable/md/server/config_ocid_application_hash_supermarket.md new file mode 100644 index 0000000..6c90a45 --- /dev/null +++ b/content/reusable/md/server/config_ocid_application_hash_supermarket.md @@ -0,0 +1,8 @@ +To define OAuth 2 information for Chef Supermarket, create a Hash similar to: + +```ruby +oc_id['applications'] ||= {} +oc_id['applications']['supermarket'] = { + 'redirect_uri' => 'https://supermarket.mycompany.com/auth/chef_oauth2/callback', +} +``` diff --git a/content/reusable/md/server/ctl_chef_server_org_create_summary.md b/content/reusable/md/server/ctl_chef_server_org_create_summary.md new file mode 100644 index 0000000..cdebe8f --- /dev/null +++ b/content/reusable/md/server/ctl_chef_server_org_create_summary.md @@ -0,0 +1,26 @@ +Run the following command to create an organization: + +```bash +sudo chef-server-ctl org-create short_name 'full_organization_name' --association_user user_name --filename ORGANIZATION-validator.pem +``` + +For example: + +```bash +sudo chef-server-ctl org-create 4thcafe 'Fourth Cafe, Inc.' --association_user janedoe --filename /path/to/4thcafe-validator.pem +``` + +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: `4thcafe`. + +The full name must begin with a non-white space character and must be +between 1 and 1023 characters. For example: `'Fourth Cafe, Inc.'`. + +The `--association_user` option will associate the `user_name` with the +`admins` security group on the Chef Infra Server. + +An RSA private key is generated automatically. This is the +chef-validator key and should be saved to a safe location. The +`--filename` option will save the RSA private key to the specified +absolute path. diff --git a/content/reusable/md/server/ctl_chef_server_uninstall.md b/content/reusable/md/server/ctl_chef_server_uninstall.md new file mode 100644 index 0000000..0d80825 --- /dev/null +++ b/content/reusable/md/server/ctl_chef_server_uninstall.md @@ -0,0 +1,16 @@ +The `uninstall` subcommand is used to remove the Chef Infra Server +application, but without removing any of the data. This subcommand will +shut down all services (including the `runit` process supervisor). + +This subcommand has the following syntax: + +```bash +chef-server-ctl uninstall +``` + +{{< note >}} + +To revert the `uninstall` subcommand, run the `reconfigure` subcommand +(because the `start` subcommand is disabled by the `uninstall` command). + +{{< /note >}} diff --git a/content/reusable/md/server/ctl_chef_server_user_create_admin.md b/content/reusable/md/server/ctl_chef_server_user_create_admin.md new file mode 100644 index 0000000..ee786e1 --- /dev/null +++ b/content/reusable/md/server/ctl_chef_server_user_create_admin.md @@ -0,0 +1,15 @@ +Run the following command to create an administrator: + +```bash +sudo chef-server-ctl user-create USER_NAME FIRST_NAME LAST_NAME EMAIL 'PASSWORD' --filename FILE_NAME +``` + +An RSA private key is generated automatically. This is the user's +private key and should be saved to a safe location. The `--filename` +option will save the RSA private key to the specified absolute path. + +For example: + +```bash +sudo chef-server-ctl user-create janedoe Jane Doe janed@example.com 'abc123' --filename /path/to/janedoe.pem +``` diff --git a/content/reusable/md/server/install_chef_server_install_package.md b/content/reusable/md/server/install_chef_server_install_package.md new file mode 100644 index 0000000..1ef148f --- /dev/null +++ b/content/reusable/md/server/install_chef_server_install_package.md @@ -0,0 +1,15 @@ +As a root user, install the Chef Infra Server package on the server, +using the name of the package provided by Chef. For Red Hat Enterprise +Linux and CentOS: + +```bash +sudo rpm -Uvh /tmp/chef-server-core-.rpm +``` + +For Ubuntu: + +```bash +sudo dpkg -i /tmp/chef-server-core-.deb +``` + +After a few minutes, the Chef Infra Server will be installed. diff --git a/content/reusable/md/server/server_security_ssl_cert_client.md b/content/reusable/md/server/server_security_ssl_cert_client.md new file mode 100644 index 0000000..8bbfea3 --- /dev/null +++ b/content/reusable/md/server/server_security_ssl_cert_client.md @@ -0,0 +1,25 @@ +Chef Infra Server 12 and later enables SSL verification by default for all +requests made to the server, such as those made by knife and Chef Infra +Client. The certificate that's generated during the installation of the +Chef Infra Server is self-signed, which means the certificate isn't +signed by a trusted certificate authority (CA) recognized by Chef +Infra Client. The certificate generated by the Chef Infra Server must be +downloaded to any machine from which knife and/or Chef Infra Client will +make requests to the Chef Infra Server. + +For example, without downloading the SSL certificate, the following +knife command: + +```bash +knife client list +``` + +responds with an error similar to: + +```bash +ERROR: SSL Validation failure connecting to host: chef-server.example.com ... +ERROR: OpenSSL::SSL::SSLError: SSL_connect returned=1 errno=0 state=SSLv3 ... +``` + +This is by design and will occur until a verifiable certificate is added +to the machine from which the request is sent. diff --git a/content/reusable/md/template.md b/content/reusable/md/template.md new file mode 100644 index 0000000..6894fa1 --- /dev/null +++ b/content/reusable/md/template.md @@ -0,0 +1 @@ +A cookbook template is an Embedded Ruby (ERB) template that's used to dynamically generate static text files. Templates may contain Ruby expressions and statements, and are a great way to manage configuration files. Use the **template** resource to add cookbook templates to recipes; place the corresponding Embedded Ruby (ERB) template file in a cookbook's `/templates` directory. diff --git a/content/reusable/md/template_helpers.md b/content/reusable/md/template_helpers.md new file mode 100644 index 0000000..becbf66 --- /dev/null +++ b/content/reusable/md/template_helpers.md @@ -0,0 +1,10 @@ +A helper is a method or a module that can be used to extend a template. +There are three approaches: + +- An inline helper method +- An inline helper module +- A cookbook library module + +Use the `helper` attribute in a recipe to define an inline helper +method. Use the `helpers` attribute to define an inline helper module or +a cookbook library module. diff --git a/content/reusable/md/template_host_notation.md b/content/reusable/md/template_host_notation.md new file mode 100644 index 0000000..c58ad58 --- /dev/null +++ b/content/reusable/md/template_host_notation.md @@ -0,0 +1,4 @@ +The naming of folders within cookbook directories must literally match +the host notation used for template specificity matching. For example, +if a host is named `foo.example.com`, then the folder must be named +`host-foo.example.com`. diff --git a/content/reusable/md/template_partials.md b/content/reusable/md/template_partials.md new file mode 100644 index 0000000..4880372 --- /dev/null +++ b/content/reusable/md/template_partials.md @@ -0,0 +1,7 @@ +A template can be built in a way that allows it to contain references to +one (or more) smaller template files. (These smaller template files are +also referred to as partials.) A partial can be referenced from a +template file in one of the following ways: + +- By using the `render` method in the template file +- By using the **template** resource and the `variables` property. diff --git a/content/reusable/md/template_partials_render_method.md b/content/reusable/md/template_partials_render_method.md new file mode 100644 index 0000000..2471bde --- /dev/null +++ b/content/reusable/md/template_partials_render_method.md @@ -0,0 +1,46 @@ +Use the `render` method in a template to reference a partial template +file: + +```ruby +<%= render 'partial_name.txt.erb', :option => {} %> +``` + +where `partial_name` is the name of the partial template file and +`:option` is one (or more) of the following: + + ++++ + + + + + + + + + + + + + + + + + + + + + + + + +
OptionDescription
:cookbookBy default, a partial template file is assumed to be located in the cookbook that contains the top-level template. Use this option to specify the path to a different cookbook
:localIndicates that the name of the partial template file should be interpreted as a path to a file in the local file system or looked up in a cookbook using the normal rules for template files. Set to true to interpret as a path to a file in the local file system and to false to use the normal rules for template files
:sourceBy default, a partial template file is identified by its file name. Use this option to specify a different name or a local path to use (instead of the name of the partial template file)
:variablesA hash of variable_name => value that will be made available to the partial template file. When this option is used, any variables that are defined in the top-level template that are required by the partial template file must have them defined explicitly using this option
+ +For example: + +```ruby +<%= render 'simple.txt.erb', :variables => {:user => Etc.getlogin }, :local => true %> +``` diff --git a/content/reusable/md/template_partials_variables_attribute.md b/content/reusable/md/template_partials_variables_attribute.md new file mode 100644 index 0000000..e869622 --- /dev/null +++ b/content/reusable/md/template_partials_variables_attribute.md @@ -0,0 +1,22 @@ +The `variables` property of the **template** resource can be used to +reference a partial template file by using a Hash. For example: + +```ruby +template '/file/name.txt' do + variables partials: { + 'partial_name_1.txt.erb' => 'message', + 'partial_name_2.txt.erb' => 'message', + 'partial_name_3.txt.erb' => 'message', + } +end +``` + +where each of the partial template files can then be combined using +normal Ruby template patterns within a template file, such as: + +```ruby +<% @partials.each do |partial, message| %> + Here is <%= partial %> + <%= render partial, :variables => {:message => message} %> +<% end %> +``` diff --git a/content/reusable/md/template_requirements.md b/content/reusable/md/template_requirements.md new file mode 100644 index 0000000..65baded --- /dev/null +++ b/content/reusable/md/template_requirements.md @@ -0,0 +1,55 @@ +To use a template, two things must happen: + +1. A template resource must be added to a recipe +1. An Embedded Ruby (ERB) template must be added to a cookbook + +For example, the following template file and template resource settings +can be used to manage a configuration file named `/etc/sudoers`. Within +a cookbook that uses sudo, the following resource could be added to +`/recipes/default.rb`: + +```ruby +template '/etc/sudoers' do + source 'sudoers.erb' + mode '0440' + owner 'root' + group 'root' + variables(sudoers_groups: node['authorization']['sudo']['groups'], + sudoers_users: node['authorization']['sudo']['users']) +end +``` + +And then create a template called `sudoers.erb` and save it to +`templates/default/sudoers.erb`: + +```ruby +# +# /etc/sudoers +# +# Generated by Chef for <%= node['fqdn'] %> +# + +Defaults !lecture,tty_tickets,!fqdn + +# User privilege specification +root ALL=(ALL) ALL + +<% @sudoers_users.each do |user| -%> +<%= user %> ALL=(ALL) <%= "NOPASSWD:" if @passwordless %>ALL +<% end -%> + +# Members of the sysadmin group may gain root privileges +%sysadmin ALL=(ALL) <%= "NOPASSWD:" if @passwordless %>ALL + +<% @sudoers_groups.each do |group| -%> +# Members of the group '<%= group %>' may gain root privileges +<%= group %> ALL=(ALL) <%= "NOPASSWD:" if @passwordless %>ALL +<% end -%> +``` + +And then set the default attributes in `attributes/default.rb`: + +```ruby +default['authorization']['sudo']['groups'] = %w(sysadmin wheel admin) +default['authorization']['sudo']['users'] = %w(jerry greg) +``` diff --git a/content/reusable/md/template_specificity.md b/content/reusable/md/template_specificity.md new file mode 100644 index 0000000..cdda6ce --- /dev/null +++ b/content/reusable/md/template_specificity.md @@ -0,0 +1,5 @@ +A cookbook is frequently designed to work across many platforms and is +often required to distribute a specific template to a specific platform. +A cookbook can be designed to support the distribution of templates +across platforms, while ensuring that the correct template ends up on +each system. diff --git a/content/reusable/md/template_specificity_example.md b/content/reusable/md/template_specificity_example.md new file mode 100644 index 0000000..20fd5b8 --- /dev/null +++ b/content/reusable/md/template_specificity_example.md @@ -0,0 +1,33 @@ +A cookbook may have a `/templates` directory structure like this: + +```ruby +/templates/ + windows-10 + windows-6.3 + windows + default +``` + +and a resource that looks something like the following: + +```ruby +template 'C:\path\to\file\text_file.txt' do + source 'text_file.txt' + mode '0755' + owner 'root' + group 'root' +end +``` + +This resource would be matched in the same order as the `/templates` +directory structure. For a node named `host-node-desktop` that's +running Windows 8.1, the second item would be the matching item and the +location: + +```ruby +/templates + windows-10/text_file.txt + windows-6.3/text_file.txt + windows/text_file.txt + default/text_file.txt +``` diff --git a/content/reusable/md/template_specificity_pattern.md b/content/reusable/md/template_specificity_pattern.md new file mode 100644 index 0000000..70a2e10 --- /dev/null +++ b/content/reusable/md/template_specificity_pattern.md @@ -0,0 +1,46 @@ +The pattern for template specificity depends on two things: the lookup +path and the source. The first pattern that matches is used: + +1. `/host-$fqdn/$source` +1. `/$platform-$platform_version/$source` +1. `/$platform/$source` +1. `/default/$source` +1. `/$source` + + + +
+

Note

+
+ +To specify a particular Windows version, use the [operating system +version +number](https://docs.microsoft.com/en-us/windows/win32/sysinfo/operating-system-version). +For example, a template in `templates/windows-6.3` will be deployed on +systems installed with Windows 8.1. + +
+
+ +Use an array with the `source` property to define an explicit lookup +path. For example: + +```ruby +template '/test' do + source ["#{node.chef_environment}.erb", 'default.erb'] +end +``` + +The following example emulates the entire file specificity pattern by +defining it as an explicit path: + +```ruby +template '/test' do + source %W( + host-#{node['fqdn']}/test.erb + #{node['platform']}-#{node['platform_version']}/test.erb + #{node['platform']}/test.erb + default/test.erb + ) +end +``` diff --git a/content/reusable/md/template_transfer_frequency.md b/content/reusable/md/template_transfer_frequency.md new file mode 100644 index 0000000..868fe87 --- /dev/null +++ b/content/reusable/md/template_transfer_frequency.md @@ -0,0 +1,4 @@ +The Chef Infra Client caches a template when it's first requested. On +each subsequent request for that template, the Chef Infra Client +compares that request to the template located on Chef Infra Server. +If the templates are the same, no transfer occurs. diff --git a/content/reusable/md/template_variables.md b/content/reusable/md/template_variables.md new file mode 100644 index 0000000..5914aba --- /dev/null +++ b/content/reusable/md/template_variables.md @@ -0,0 +1,58 @@ +An Embedded Ruby (ERB) template allows Ruby code to be embedded inside a +text file within specially formatted tags. Ruby code can be embedded +using expressions and statements. An expression is delimited by `<%=` +and `%>`. For example: + +```ruby +<%= "my name is #{$ruby}" %> +``` + +A statement is delimited by a modifier, such as `if`, `elsif`, and +`else`. For example: + +```ruby +if false +# this won't happen +elsif nil + # this won't either + end +``` + +Using a Ruby expression is the most common approach for defining +template variables because this is how all variables that are sent to a +template are referenced. Whenever a template needs to use an `each`, +`if`, or `end`, use a Ruby statement. + +When a template is rendered, Ruby expressions and statements are +evaluated by Chef Infra Client. The variables listed in the **template** +resource's `variables` parameter and in the node object are evaluated. +Chef Infra Client then passes these variables to the template, where +they will be accessible as instance variables within the template. The +node object can be accessed just as if it were part of a recipe, using +the same syntax. + +For example, a simple template resource like this: + +```ruby +node['fqdn'] = 'latte' +template '/tmp/foo' do + source 'foo.erb' + variables(x_men: 'are keen') +end +``` + +And a simple Embedded Ruby (ERB) template like this: + +```ruby +The node <%= node[:fqdn] %> thinks the x-men <%= @x_men %> +``` + +Would render something like: + +```plain +The node latte thinks the x-men are keen +``` + +Even though this is a simple example, the full capabilities of Ruby +can be used to tackle even the most complex and demanding template +requirements. diff --git a/content/reusable/md/unified_mode_actions_later_resources.md b/content/reusable/md/unified_mode_actions_later_resources.md new file mode 100644 index 0000000..80ea220 --- /dev/null +++ b/content/reusable/md/unified_mode_actions_later_resources.md @@ -0,0 +1,70 @@ + +## Actions on Later Resources + +Since Unified Mode executes your resource as it's compiled, `:immediate` notifications that execute later resources are handled differently than in the past. + +### `:immediate` Notifications to Later Resources + +Unified mode delays immediate notifications to later resources. +In unified mode, the Chef Infra Client saves immediate notifications and executes them when the later resource is parsed. Immediate notifications to prior resources and delayed notifications behave the same as they did before unified mode. + +The result of sequentially chaining immediate notifications is the same as before unified mode. Instead of immediately notifying results, the notifications fire _in order_ as they're parsed, which has the same outcome. If the parse order and the intended execution order are different, then the results may be different and are a reflection of the parse order. + +The changes to sending immediate notification could result in subtle changes to behaviors in some resources, but it's not a breaking change to common patterns of writing resources. + +Chaining immediate notifications to later resources: + +```ruby +remote_file "#{Chef::Config[:file_cache_path]}/myservice.tgz" do + source "http://acme.com/myservice.tgz" + notifies :extract, "archive_file[myservice.tgz]", :immediately +end + +archive_file "#{Chef::Config[:file_cache_path]}/myservice.tgz" do + destination '/srv/myservice' + notifies :start, "service[myservice]", :immediately + action :nothing +end + +service "myservice" do + action :nothing +end +``` + +### `:before` Notifications to Later Resources + +In unified mode, you must declare a resource before sending a `before` notification to it. + +Resources that subscribe to a `before` notification to a later resource must be declared after the resource that triggers the notification. + +This resource declares a `before` notification to a later resource and will no longer work: + +```ruby +package "myservice" do + notifies :stop, "service[myservice]", :before + notifies :start, "service[myservice]", :immediately +end + +service "myservice" do + action :nothing +end +``` + +Instead, declare the resource and then declare actions. For example: + +```ruby +service "myservice" do + action :nothing +end + +package "myservice" do + notifies :stop, "service[myservice]", :before + notifies :start, "service[myservice]", :immediately +end +``` + +### Out of Order Execution + +Unified mode breaks custom resources that rely on the out-of-order execution of compile-time statements. Move any affected compile-time statements to the location in the code where they're intended to execute. + +Out-of-order execution is rare. Internally at Chef, none of our custom resources broke during our migration to unified mode. Instead, we discovered a few cases in which custom resource code was intended to run in order, but Chef Infra Client executed it out of order. In these cases, Unified Mode fixed errors instead of introducing bugs. diff --git a/content/reusable/md/unified_mode_client_releases.md b/content/reusable/md/unified_mode_client_releases.md new file mode 100644 index 0000000..3312237 --- /dev/null +++ b/content/reusable/md/unified_mode_client_releases.md @@ -0,0 +1,13 @@ +Unified Mode (`unified_mode true`) is the default behavior starting in Chef Infra Client 18 (April 2022). + +See the following table for Chef Infra Client versions where Unified Mode can be enabled in custom resources: + +| Chef Infra Client | Unified Mode | +|-------------------|-------------------------------| +| 18.x (2022) | Default: `unified_mode true` | +| 17.x (2021) | Default: `unified_mode false` | +| 16.x (2020) | Default: `unified_mode false` | +| 15.3 and higher | Default: `unified_mode false` | +| 15.0--15.2 | Not available | +| 14.14--14.15 | Default: `unified_mode false` | +| Lower than 14.14 | Not available | diff --git a/content/reusable/md/unified_mode_enable.md b/content/reusable/md/unified_mode_enable.md new file mode 100644 index 0000000..1f7d06f --- /dev/null +++ b/content/reusable/md/unified_mode_enable.md @@ -0,0 +1,14 @@ +Unified Mode is enabled by default starting in Chef Infra Client 18. + +In Chef Infra Client 17 (April 2021) and some earlier versions, you can enable Unified Mode in custom resources by adding `unified_mode true`. You can upgrade most custom resources to use Unified Mode without additional work other than testing and validation. See the following example: + +```ruby +# enable unified mode +unified_mode true + +provides :myresource + +actions :run do + [...] +end +``` diff --git a/content/reusable/md/unified_mode_overview.md b/content/reusable/md/unified_mode_overview.md new file mode 100644 index 0000000..d71b5c8 --- /dev/null +++ b/content/reusable/md/unified_mode_overview.md @@ -0,0 +1,2 @@ + +Unified mode is a setting that will compile and converge a custom resource's action block in one pass and in the order that the code inside that block is composed, from beginning to end. This replaces Chef Infra's two-pass parsing with single-pass parsing so that resources are executed as soon as they're declared. This results in clearer code and requires less Ruby knowledge to understand the order of operations. diff --git a/content/reusable/md/unified_mode_troubleshooting.md b/content/reusable/md/unified_mode_troubleshooting.md new file mode 100644 index 0000000..f1c030a --- /dev/null +++ b/content/reusable/md/unified_mode_troubleshooting.md @@ -0,0 +1,88 @@ + +## Troubleshooting Unified Mode + +Unified mode changes the execution of a custom resource to run in one phase, in the order that the code is written, from the first line of the code to the last. Custom resources designed to use two phases may need modification. These fall into three general types: + +- Resources with changes to internal sub-resources +- Resources with actions on later resources +- Resources that rely on the out-of-order execution + +When designing a custom resource for unified mode: + +- Declare a resource first and then declare actions on it +- Write resources in run-time order + +### Resources with changes to internal sub-resources + +Some custom resources are designed to create and edit other sub-resources as part of the resource declaration. In unified mode, Chef Infra Client parses a resource code block that creates or edits a sub-resource and immediately tries to apply that change, even though the sub-resource doesn't yet exist. This results in the execution of an incomplete resource. + +For example, with Unified Mode enabled, this code from the dhcp cookbook is designed to create and edit a shared `dhcp_subnet` resource, but it won't work as expected: + +```ruby +# 'edit_resource' results in an incomplete subresource +sr = edit_resource(:dhcp_subnet, "#{new_resource.name}_sharedsubnet_#{subnet}") do + owner new_resource.owner + group new_resource.group + mode new_resource.mode + + ip_version new_resource.ip_version + conf_dir new_resource.conf_dir + shared_network true +end + +properties.each do |property, value| + sr.send(property, value) +end +``` + +To correct custom resources that change sub-resources during their declaration, you can: + +- Apply properties in the code block (preferred) +- Run the resource explicitly (not preferred) + +#### Apply properties in the code block + +This pattern declares the sub-resource in one code block and then changes it in the next code block. This is the preferred pattern in Unified Mode because all resources execute in order at compile time. + +```ruby +dhcp_subnet "#{new_resource.name}_sharedsubnet_#{subnet}" do + owner new_resource.owner + group new_resource.group + mode new_resource.mode + + ip_version new_resource.ip_version + conf_dir new_resource.conf_dir + shared_network true + + properties.each do |property, value| + send(property, value) + end +end +``` + +#### Run the resource explicitly + +Another solution is to continue saving the resource as a variable, declare `action :nothing` within the codeblock, and then explicitly run the action in another code block. + +The pattern of saving a resource as a variable and then forcing it to run at compile time with an explicit `run_action` works as it has in the past, but it's not a preferred pattern. Unified mode forces resource execution to compile time by default, which makes this pattern redundant. + +```ruby +sr = edit_resource(:dhcp_subnet, "#{new_resource.name}_sharedsubnet_#{subnet}") do + owner new_resource.owner + group new_resource.group + mode new_resource.mode + + ip_version new_resource.ip_version + conf_dir new_resource.conf_dir + shared_network true + + action :nothing +end + +properties.each do |property, value| + sr.send(property, value) +end + +# Run the action explicitly +sr.run_action(:create) +``` diff --git a/content/reusable/md/unit_file_verification.md b/content/reusable/md/unit_file_verification.md new file mode 100644 index 0000000..183dacc --- /dev/null +++ b/content/reusable/md/unit_file_verification.md @@ -0,0 +1,5 @@ +The unit file is verified using a `systemd-analyze verify` call before +being written to disk. + +Be aware that the referenced commands and files need to already exist +before verification. diff --git a/content/reusable/md/windows_environment_variable_path.md b/content/reusable/md/windows_environment_variable_path.md new file mode 100644 index 0000000..637ab7d --- /dev/null +++ b/content/reusable/md/windows_environment_variable_path.md @@ -0,0 +1,11 @@ +On Windows, Chef Infra Client must have two entries added to +the `PATH` environment variable: + +- `C:\opscode\chef\bin` +- `C:\opscode\chef\embedded\bin` + +This is typically done during the installation of Chef Infra Client +automatically. If these values (for any reason) aren't in the `PATH` +environment variable, Chef Infra Client won't run properly. + +![image](/images/includes_windows_environment_variable_path.png) diff --git a/content/reusable/md/windows_install_overview.md b/content/reusable/md/windows_install_overview.md new file mode 100644 index 0000000..7f9d34b --- /dev/null +++ b/content/reusable/md/windows_install_overview.md @@ -0,0 +1,10 @@ +Chef Infra Client can be installed on machines running Windows +in the following ways: + +- By bootstrapping Chef Infra Client using [knife + bootstrap](https://docs.chef.io/workstation/knife_bootstrap/) from a local workstation using + WinRM +- By downloading Chef Infra Client to the target node, and then + running the Microsoft Installer Package (MSI) locally +- By using an existing process already in place for managing Microsoft + Windows machines, such as System Center diff --git a/content/reusable/md/windows_install_system_center.md b/content/reusable/md/windows_install_system_center.md new file mode 100644 index 0000000..9c88955 --- /dev/null +++ b/content/reusable/md/windows_install_system_center.md @@ -0,0 +1,4 @@ +Many organizations already have processes in place for managing the +applications and settings on various Windows machines. For +example, System Center. Chef Infra Client can be installed using this +method. diff --git a/content/reusable/md/windows_msiexec.md b/content/reusable/md/windows_msiexec.md new file mode 100644 index 0000000..32691dc --- /dev/null +++ b/content/reusable/md/windows_msiexec.md @@ -0,0 +1,15 @@ +Msiexec.exe installs Chef Infra Client on a node as part of a bootstrap operation. +The actual command that's run by the default bootstrap script is: + +```bash +msiexec /qn /i "%LOCAL_DESTINATION_MSI_PATH%" +``` + +where: + +- `/qn` sets the user interface level to "No UI" (silent installation with no prompts) +- `/i` defines the location where Chef Infra Client is installed +- `"%LOCAL_DESTINATION_MSI_PATH%"` is a variable defined in the default +[windows-chef-client-msi.erb](https://github.com/chef/chef/blob/main/knife/lib/chef/knife/bootstrap/templates/windows-chef-client-msi.erb) bootstrap template. + +For more information, see [Microsoft's MSI command line options documentation](https://docs.microsoft.com/en-us/windows/win32/msi/command-line-options). diff --git a/content/reusable/md/windows_msiexec_addlocal.md b/content/reusable/md/windows_msiexec_addlocal.md new file mode 100644 index 0000000..8201219 --- /dev/null +++ b/content/reusable/md/windows_msiexec_addlocal.md @@ -0,0 +1,36 @@ +The `ADDLOCAL` parameter adds two setup options specific to Chef Infra +Client. These options can be passed along with an Msiexec.exe command: + + ++++ + + + + + + + + + + + + + + + + + + + + +
OptionDescription
ChefClientFeatureUse to install Chef Infra Client.
ChefSchTaskFeatureUse to configure Chef Infra Client as a scheduled task in Windows.
ChefPSModuleFeatureUsed to install the chef PowerShell module. This will enable chef command line utilities within PowerShell.
+ +First install Chef Infra Client, and then enable it to run as a +scheduled task. For example: + +```bash +msiexec /qn /i C:\inst\chef-client-15.3.14-1-x64.msi ADDLOCAL="ChefClientFeature,ChefSchTaskFeature,ChefPSModuleFeature" +``` diff --git a/content/reusable/md/windows_registry_key_backslashes.md b/content/reusable/md/windows_registry_key_backslashes.md new file mode 100644 index 0000000..8268908 --- /dev/null +++ b/content/reusable/md/windows_registry_key_backslashes.md @@ -0,0 +1,25 @@ +A Windows registry key can be used as a string in Ruby code, +such as when a registry key is used as the name of a recipe. In Ruby, +when a registry key is enclosed in a double-quoted string (`" "`), the +same backslash character (`\`) that's used to define the registry key +path separator is also used in Ruby to define an escape character. +Therefore, the registry key path separators must be escaped when they +are enclosed in a double-quoted string. For example, the following +registry key: + +```ruby +HKCU\SOFTWARE\Policies\Microsoft\Windows\CurrentVersion\Themes +``` + +may be enclosed in a single-quoted string with a single backslash: + +```ruby +'HKCU\SOFTWARE\path\to\key\Themes' +``` + +or may be enclosed in a double-quoted string with an extra backslash as +an escape character: + +```ruby +"HKCU\\SOFTWARE\\path\\to\\key\\Themes" +``` diff --git a/content/reusable/md/windows_spaces_and_directories.md b/content/reusable/md/windows_spaces_and_directories.md new file mode 100644 index 0000000..94f17b7 --- /dev/null +++ b/content/reusable/md/windows_spaces_and_directories.md @@ -0,0 +1,4 @@ +Directories that are used by Chef products on Windows can't have +spaces. For example, `C:\Users\User Name` won't work, but +`C:\Users\UserName` will. Chef commands may fail if used against a +directory with a space in its name. diff --git a/content/reusable/md/windows_top_level_directory_names.md b/content/reusable/md/windows_top_level_directory_names.md new file mode 100644 index 0000000..a7f1353 --- /dev/null +++ b/content/reusable/md/windows_top_level_directory_names.md @@ -0,0 +1,6 @@ +Windows will throw errors when path name lengths are too long. For this +reason, it's often helpful to use a short top-level directory, much +like what's done in UNIX and Linux. For example, Chef uses `/opt/` to +install Chef Workstation on macOS. A similar approach can be done on +Windows, by creating a top-level directory with a short name. +For example: `C:\chef`. diff --git a/content/reusable/md/workstation/chef_workstation.md b/content/reusable/md/workstation/chef_workstation.md new file mode 100644 index 0000000..a0a3878 --- /dev/null +++ b/content/reusable/md/workstation/chef_workstation.md @@ -0,0 +1,10 @@ +Start your infrastructure automation with [Chef Workstation](https://docs.chef.io/workstation/). Chef Workstation gives you everything you need to get started with Chef - ad hoc remote execution, remote scanning, configuration tasks, cookbook creation tools as well as robust dependency and testing software - all in one easy-to-install package. + +Chef Workstation includes: + +- Chef Infra Client +- Chef InSpec +- Chef Habitat +- chef and knife command line tools +- Testing tools such as Test Kitchen and Cookstyle +- Everything else needed to author cookbooks and upload them to the Chef Infra Server diff --git a/content/reusable/md/workstation/ctl_chef_clean_policy_cookbooks.md b/content/reusable/md/workstation/ctl_chef_clean_policy_cookbooks.md new file mode 100644 index 0000000..61667eb --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_clean_policy_cookbooks.md @@ -0,0 +1,11 @@ +Use the `chef clean-policy-cookbooks` subcommand to delete cookbooks +that aren't used by Policyfile files. Cookbooks are considered unused +when they aren't referenced by any policy revisions on the Chef Infra +Server. + +{{< note >}} + +Cookbooks that are referenced by orphaned policy revisions aren't +removed. Use `chef clean-policy-revisions` to remove orphaned policies. + +{{< /note >}} diff --git a/content/reusable/md/workstation/ctl_chef_clean_policy_cookbooks_options.md b/content/reusable/md/workstation/ctl_chef_clean_policy_cookbooks_options.md new file mode 100644 index 0000000..df1141c --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_clean_policy_cookbooks_options.md @@ -0,0 +1,17 @@ +This subcommand has the following options: + +`-c CONFIG_FILE`, `--config CONFIG_FILE` + +: The path to the knife configuration file. + +`-D`, `--debug` + +: Enable stack traces and other debug output. Default value: `false`. + +`-h`, `--help` + +: Show help for the command. + +`-v`, `--version` + +: The Chef Infra Client version. diff --git a/content/reusable/md/workstation/ctl_chef_clean_policy_cookbooks_syntax.md b/content/reusable/md/workstation/ctl_chef_clean_policy_cookbooks_syntax.md new file mode 100644 index 0000000..03badb8 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_clean_policy_cookbooks_syntax.md @@ -0,0 +1,5 @@ +This subcommand has the following syntax: + +```bash +chef clean-policy-cookbooks (options) +``` diff --git a/content/reusable/md/workstation/ctl_chef_clean_policy_revisions.md b/content/reusable/md/workstation/ctl_chef_clean_policy_revisions.md new file mode 100644 index 0000000..6050d9b --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_clean_policy_revisions.md @@ -0,0 +1,6 @@ +Use the `chef clean-policy-revisions` subcommand to delete orphaned +policy revisions to Policyfile files from the Chef Infra Server. An +orphaned policy revision isn't associated to any policy group and +therefore isn't in active use by any node. Use +`chef show-policy --orphans` to view a list of orphaned policy +revisions. diff --git a/content/reusable/md/workstation/ctl_chef_clean_policy_revisions_options.md b/content/reusable/md/workstation/ctl_chef_clean_policy_revisions_options.md new file mode 100644 index 0000000..df1141c --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_clean_policy_revisions_options.md @@ -0,0 +1,17 @@ +This subcommand has the following options: + +`-c CONFIG_FILE`, `--config CONFIG_FILE` + +: The path to the knife configuration file. + +`-D`, `--debug` + +: Enable stack traces and other debug output. Default value: `false`. + +`-h`, `--help` + +: Show help for the command. + +`-v`, `--version` + +: The Chef Infra Client version. diff --git a/content/reusable/md/workstation/ctl_chef_clean_policy_revisions_syntax.md b/content/reusable/md/workstation/ctl_chef_clean_policy_revisions_syntax.md new file mode 100644 index 0000000..9069aa6 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_clean_policy_revisions_syntax.md @@ -0,0 +1,5 @@ +This subcommand has the following syntax: + +```bash +chef clean-policy-revisions (options) +``` diff --git a/content/reusable/md/workstation/ctl_chef_client_bootstrap_initial_run_list.md b/content/reusable/md/workstation/ctl_chef_client_bootstrap_initial_run_list.md new file mode 100644 index 0000000..9d470e9 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_client_bootstrap_initial_run_list.md @@ -0,0 +1,31 @@ +A node's initial run-list is specified using a JSON file on the host +system. When running Chef Infra Client as an executable, use the `-j` +option to tell Chef Infra Client which JSON file to use. For example: + +```bash +chef-client -j /etc/chef/file.json --environment _default +``` + +where `file.json` is similar to: + +```javascript +{ + "resolver": { + "nameservers": [ "10.0.0.1" ], + "search":"int.example.com" + }, + "run_list": [ "recipe[resolver]" ] +} +``` + +and where `_default` is the name of the environment that's assigned to +the node. + +{{< warning >}} + +This approach may be used to update +[normal](/cookbooks/attributes/attribute_types/) attributes, but should never +be used to update any other attribute type, as all attributes updated +using this option are treated as `normal` attributes. + +{{< /warning >}} diff --git a/content/reusable/md/workstation/ctl_chef_client_elevated_privileges.md b/content/reusable/md/workstation/ctl_chef_client_elevated_privileges.md new file mode 100644 index 0000000..ed10d9f --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_client_elevated_privileges.md @@ -0,0 +1,5 @@ +The Chef Infra Client may need to be run with elevated privileges in +order to get a recipe to converge correctly. On UNIX and UNIX-like +operating systems this can be done by running the command as root. On +Windows this can be done by running the command prompt as an +administrator. diff --git a/content/reusable/md/workstation/ctl_chef_client_elevated_privileges_windows.md b/content/reusable/md/workstation/ctl_chef_client_elevated_privileges_windows.md new file mode 100644 index 0000000..73ab4b6 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_client_elevated_privileges_windows.md @@ -0,0 +1,22 @@ +On Windows, running without elevated privileges (when they're +necessary) is an issue that fails silently. It will appear that Chef +Infra Client completed its run successfully, but the changes won't +have been made. When this occurs, do one of the following to run Chef +Infra Client as the administrator: + +- Log in to the administrator account. (This isn't the same as an + account in the administrator's security group.) + +- Run Chef Infra Client process from the administrator account while + being logged into another account. Run the following command: + + ```bash + runas /user:Administrator "cmd /C chef-client" + ``` + + This will prompt for the administrator account password. + +- Open a command prompt by right-clicking on the command prompt + application, and then selecting **Run as administrator**. After the + command window opens, Chef Infra Client can be run as the + administrator diff --git a/content/reusable/md/workstation/ctl_chef_client_options_format.md b/content/reusable/md/workstation/ctl_chef_client_options_format.md new file mode 100644 index 0000000..ef025a2 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_client_options_format.md @@ -0,0 +1,16 @@ +The output format: `doc` (default) or `min`. + +- Use `doc` to print the progress of a Chef Infra Client run using + full strings that display a summary of updates as they occur. +- Use `min` to print the progress of a Chef Infra Client run using + single characters. + +A summary of updates is printed at the end of a Chef Infra Client run. A +dot (`.`) is printed for events that don't have meaningful status +information, such as loading a file or synchronizing a cookbook. For +resources, a dot (`.`) is printed when the resource is up to date, an +`S` is printed when the resource is skipped by `not_if` or `only_if`, +and a `U` is printed when the resource is updated. + +Other formatting options are available when those formatters are +configured in the client.rb file using the `add_formatter` option. diff --git a/content/reusable/md/workstation/ctl_chef_delete_policy.md b/content/reusable/md/workstation/ctl_chef_delete_policy.md new file mode 100644 index 0000000..ba4dc61 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_delete_policy.md @@ -0,0 +1,4 @@ +Use the `chef delete-policy` subcommand to delete all revisions of the +named policy that exist on the Chef Infra Server. (The state of the +policy revision is backed up locally and may be restored using the +`chef undelete` subcommand.) diff --git a/content/reusable/md/workstation/ctl_chef_delete_policy_group.md b/content/reusable/md/workstation/ctl_chef_delete_policy_group.md new file mode 100644 index 0000000..5517420 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_delete_policy_group.md @@ -0,0 +1,5 @@ +Use the `chef delete-policy-group` subcommand to delete the named policy +group from the Chef Infra Server. Any policy revision associated with +that policy group isn't deleted. (The state of the policy group is +backed up locally and may be restored using the `chef undelete` +subcommand.) diff --git a/content/reusable/md/workstation/ctl_chef_delete_policy_group_options.md b/content/reusable/md/workstation/ctl_chef_delete_policy_group_options.md new file mode 100644 index 0000000..df1141c --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_delete_policy_group_options.md @@ -0,0 +1,17 @@ +This subcommand has the following options: + +`-c CONFIG_FILE`, `--config CONFIG_FILE` + +: The path to the knife configuration file. + +`-D`, `--debug` + +: Enable stack traces and other debug output. Default value: `false`. + +`-h`, `--help` + +: Show help for the command. + +`-v`, `--version` + +: The Chef Infra Client version. diff --git a/content/reusable/md/workstation/ctl_chef_delete_policy_group_syntax.md b/content/reusable/md/workstation/ctl_chef_delete_policy_group_syntax.md new file mode 100644 index 0000000..43e6aa4 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_delete_policy_group_syntax.md @@ -0,0 +1,5 @@ +This subcommand has the following syntax: + +```bash +chef delete-policy-group POLICY_GROUP (options) +``` diff --git a/content/reusable/md/workstation/ctl_chef_delete_policy_options.md b/content/reusable/md/workstation/ctl_chef_delete_policy_options.md new file mode 100644 index 0000000..df1141c --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_delete_policy_options.md @@ -0,0 +1,17 @@ +This subcommand has the following options: + +`-c CONFIG_FILE`, `--config CONFIG_FILE` + +: The path to the knife configuration file. + +`-D`, `--debug` + +: Enable stack traces and other debug output. Default value: `false`. + +`-h`, `--help` + +: Show help for the command. + +`-v`, `--version` + +: The Chef Infra Client version. diff --git a/content/reusable/md/workstation/ctl_chef_delete_policy_syntax.md b/content/reusable/md/workstation/ctl_chef_delete_policy_syntax.md new file mode 100644 index 0000000..49b8fbd --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_delete_policy_syntax.md @@ -0,0 +1,5 @@ +This subcommand has the following syntax: + +```bash +chef delete-policy POLICY_NAME (options) +``` diff --git a/content/reusable/md/workstation/ctl_chef_diff.md b/content/reusable/md/workstation/ctl_chef_diff.md new file mode 100644 index 0000000..2d44bf7 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_diff.md @@ -0,0 +1,2 @@ +Use the `chef diff` subcommand to display an itemized comparison of two +revisions of a `Policyfile.lock.json` file. diff --git a/content/reusable/md/workstation/ctl_chef_diff_current_lock_latest_branch.md b/content/reusable/md/workstation/ctl_chef_diff_current_lock_latest_branch.md new file mode 100644 index 0000000..66c586f --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_diff_current_lock_latest_branch.md @@ -0,0 +1,3 @@ +```bash +chef diff --git HEAD +``` diff --git a/content/reusable/md/workstation/ctl_chef_diff_current_lock_main_branch.md b/content/reusable/md/workstation/ctl_chef_diff_current_lock_main_branch.md new file mode 100644 index 0000000..8cf89b1 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_diff_current_lock_main_branch.md @@ -0,0 +1,3 @@ +```bash +chef diff --git main +``` diff --git a/content/reusable/md/workstation/ctl_chef_diff_current_lock_policy_group.md b/content/reusable/md/workstation/ctl_chef_diff_current_lock_policy_group.md new file mode 100644 index 0000000..d0ea97e --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_diff_current_lock_policy_group.md @@ -0,0 +1,3 @@ +```bash +chef diff staging +``` diff --git a/content/reusable/md/workstation/ctl_chef_diff_current_lock_specified_revision.md b/content/reusable/md/workstation/ctl_chef_diff_current_lock_specified_revision.md new file mode 100644 index 0000000..7c6d930 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_diff_current_lock_specified_revision.md @@ -0,0 +1,3 @@ +```bash +chef diff --git v1.0.0 +``` diff --git a/content/reusable/md/workstation/ctl_chef_diff_main_lock_revision_lock.md b/content/reusable/md/workstation/ctl_chef_diff_main_lock_revision_lock.md new file mode 100644 index 0000000..38ca799 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_diff_main_lock_revision_lock.md @@ -0,0 +1,3 @@ +```bash +chef diff --git main...dev +``` diff --git a/content/reusable/md/workstation/ctl_chef_diff_options.md b/content/reusable/md/workstation/ctl_chef_diff_options.md new file mode 100644 index 0000000..5f169e1 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_diff_options.md @@ -0,0 +1,35 @@ +This subcommand has the following options: + +`-c CONFIG_FILE`, `--config CONFIG_FILE` + +: The path to the knife configuration file. + +`-D`, `--debug` + +: Enable stack traces and other debug output. Default value: `false`. + +`-g GIT_REF`, `--git GIT_REF` + +: Compare the specified git reference against the current revision of + a `Policyfile.lock.json` file or against another git reference. + +`-h`, `--help` + +: Show help for the command. + +`--head` + +: A shortcut for `chef diff --git HEAD`. When a git-specific flag is + not provided, the on-disk `Policyfile.lock.json` file is compared to + one on the Chef Infra Server or (if a `Policyfile.lock.json` file is + not present on-disk) two `Policyfile.lock.json` files in the + specified policy group on the Chef Infra Server are compared. + +`--[no-]pager` + +: Use `--pager` to enable paged output for a `Policyfile.lock.json` + file. Default value: `--pager`. + +`-v`, `--version` + +: The Chef Infra Client version. diff --git a/content/reusable/md/workstation/ctl_chef_diff_syntax.md b/content/reusable/md/workstation/ctl_chef_diff_syntax.md new file mode 100644 index 0000000..8df1909 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_diff_syntax.md @@ -0,0 +1,5 @@ +This subcommand has the following syntax: + +```bash +chef diff POLICY_FILE --head | --git POLICY_GROUP | POLICY_GROUP...POLICY_GROUP (options) +``` diff --git a/content/reusable/md/workstation/ctl_chef_diff_two_policy_groups.md b/content/reusable/md/workstation/ctl_chef_diff_two_policy_groups.md new file mode 100644 index 0000000..4b226a1 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_diff_two_policy_groups.md @@ -0,0 +1,3 @@ +```bash +chef diff production...staging +``` diff --git a/content/reusable/md/workstation/ctl_chef_diff_version_lock_main_branch.md b/content/reusable/md/workstation/ctl_chef_diff_version_lock_main_branch.md new file mode 100644 index 0000000..08ec747 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_diff_version_lock_main_branch.md @@ -0,0 +1,3 @@ +```bash +chef diff --git v1.0.0...main +``` diff --git a/content/reusable/md/workstation/ctl_chef_export.md b/content/reusable/md/workstation/ctl_chef_export.md new file mode 100644 index 0000000..415c61b --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_export.md @@ -0,0 +1,5 @@ +Use the `chef export` subcommand to create a chef-zero-compatible +chef-repo that contains the cookbooks described by a +`Policyfile.lock.json` file. After a chef-zero-compatible chef-repo is +copied to a node, the policy can be applied locally on that machine by +running `chef-client -z` (local mode). diff --git a/content/reusable/md/workstation/ctl_chef_export_options.md b/content/reusable/md/workstation/ctl_chef_export_options.md new file mode 100644 index 0000000..de2212b --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_export_options.md @@ -0,0 +1,23 @@ +This subcommand has the following options: + +`-a`, `--archive` + +: Export an archive as a tarball, instead as a directory. Default + value: `false`. + +`-D`, `--debug` + +: Enable stack traces and other debug output. Default value: `false`. + +`-f`, `--force` + +: Remove the contents of the destination directory if that directory + isn't empty. Default value: `false`. + +`-h`, `--help` + +: Show help for the command. + +`-v`, `--version` + +: The Chef Infra Client version. diff --git a/content/reusable/md/workstation/ctl_chef_export_syntax.md b/content/reusable/md/workstation/ctl_chef_export_syntax.md new file mode 100644 index 0000000..c01b7a7 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_export_syntax.md @@ -0,0 +1,5 @@ +This subcommand has the following syntax: + +```bash +chef export POLICY_FILE DIRECTORY (options) +``` diff --git a/content/reusable/md/workstation/ctl_chef_generate_policyfile.md b/content/reusable/md/workstation/ctl_chef_generate_policyfile.md new file mode 100644 index 0000000..30746e0 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_generate_policyfile.md @@ -0,0 +1,2 @@ +Use the `chef generate policyfile` subcommand to generate a file to be +used with Policyfile. diff --git a/content/reusable/md/workstation/ctl_chef_generate_policyfile_options.md b/content/reusable/md/workstation/ctl_chef_generate_policyfile_options.md new file mode 100644 index 0000000..6eccb2a --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_generate_policyfile_options.md @@ -0,0 +1,9 @@ +This subcommand has the following options: + +`-h`, `--help` + +: Show help for the command. + +`-v`, `--version` + +: The Chef Infra Client version. diff --git a/content/reusable/md/workstation/ctl_chef_generate_policyfile_syntax.md b/content/reusable/md/workstation/ctl_chef_generate_policyfile_syntax.md new file mode 100644 index 0000000..db4527f --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_generate_policyfile_syntax.md @@ -0,0 +1,5 @@ +This subcommand has the following syntax: + +```bash +chef generate policyfile POLICY_NAME (options) +``` diff --git a/content/reusable/md/workstation/ctl_chef_generate_repo.md b/content/reusable/md/workstation/ctl_chef_generate_repo.md new file mode 100644 index 0000000..15d4523 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_generate_repo.md @@ -0,0 +1,3 @@ +Use the `chef generate repo` subcommand to create a chef-repo. By +default, the repo is a cookbook repo with options available to support +generating a cookbook that supports Policyfile. diff --git a/content/reusable/md/workstation/ctl_chef_generate_repo_options.md b/content/reusable/md/workstation/ctl_chef_generate_repo_options.md new file mode 100644 index 0000000..aa26c28 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_generate_repo_options.md @@ -0,0 +1,23 @@ +This subcommand has the following options: + +`-h`, `--help` + +: Show help for the command. + +`-p`, `--policy-only` + +: Create a repository that doesn't store cookbook files, only + Policyfile files. + +`-P`, `--policy` + +: Use Policyfile instead of Berkshelf. + +`-r`, `--roles` + +: Create directories for `/roles` and `/environments` instead of + creating directories for Policyfile. + +`-v`, `--version` + +: The Chef Infra Client version. diff --git a/content/reusable/md/workstation/ctl_chef_generate_repo_syntax.md b/content/reusable/md/workstation/ctl_chef_generate_repo_syntax.md new file mode 100644 index 0000000..6c5cf63 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_generate_repo_syntax.md @@ -0,0 +1,5 @@ +This subcommand has the following syntax: + +```bash +chef generate repo REPO_NAME (options) +``` diff --git a/content/reusable/md/workstation/ctl_chef_install.md b/content/reusable/md/workstation/ctl_chef_install.md new file mode 100644 index 0000000..29e9e13 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_install.md @@ -0,0 +1,7 @@ +Use the `chef install` subcommand to evaluate a Policyfile and find a +compatible set of cookbooks, build a run-list, cache it locally, and +then emit a `Policyfile.lock.json` file that describes the locked policy +set. The `Policyfile.lock.json` file may be used to install the locked +policy set to other machines and may be pushed to a policy group on the +Chef Infra Server to apply that policy to a group of nodes that are +under management by Chef. diff --git a/content/reusable/md/workstation/ctl_chef_install_options.md b/content/reusable/md/workstation/ctl_chef_install_options.md new file mode 100644 index 0000000..1436438 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_install_options.md @@ -0,0 +1,13 @@ +This subcommand has the following options: + +`-D`, `--debug` + +: Enable stack traces and other debug output. + +`-h`, `--help` + +: Show help for the command. + +`-v`, `--version` + +: The Chef Infra Client version. diff --git a/content/reusable/md/workstation/ctl_chef_install_syntax.md b/content/reusable/md/workstation/ctl_chef_install_syntax.md new file mode 100644 index 0000000..bc8e840 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_install_syntax.md @@ -0,0 +1,5 @@ +This subcommand has the following syntax: + +```bash +chef install POLICY_FILE (options) +``` diff --git a/content/reusable/md/workstation/ctl_chef_push.md b/content/reusable/md/workstation/ctl_chef_push.md new file mode 100644 index 0000000..2e224f4 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_push.md @@ -0,0 +1,5 @@ +Use the `chef push` subcommand to upload an existing +`Policyfile.lock.json` file to the Chef Infra Server, along with all of +the cookbooks that are contained in the file. The `Policyfile.lock.json` +file will be applied to the specified policy group, which is a set of +nodes that share the same run-list and cookbooks. diff --git a/content/reusable/md/workstation/ctl_chef_push_archive.md b/content/reusable/md/workstation/ctl_chef_push_archive.md new file mode 100644 index 0000000..b4eb6bb --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_push_archive.md @@ -0,0 +1,5 @@ +The `chef push-archive` subcommand is used to publish a policy archive +file to the Chef Infra Server. (A policy archive is created using the +`chef export` subcommand.) The policy archive is assigned to the +specified policy group, which is a set of nodes that share the same +run-list and cookbooks. diff --git a/content/reusable/md/workstation/ctl_chef_push_archive_options.md b/content/reusable/md/workstation/ctl_chef_push_archive_options.md new file mode 100644 index 0000000..df1141c --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_push_archive_options.md @@ -0,0 +1,17 @@ +This subcommand has the following options: + +`-c CONFIG_FILE`, `--config CONFIG_FILE` + +: The path to the knife configuration file. + +`-D`, `--debug` + +: Enable stack traces and other debug output. Default value: `false`. + +`-h`, `--help` + +: Show help for the command. + +`-v`, `--version` + +: The Chef Infra Client version. diff --git a/content/reusable/md/workstation/ctl_chef_push_archive_syntax.md b/content/reusable/md/workstation/ctl_chef_push_archive_syntax.md new file mode 100644 index 0000000..55732c6 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_push_archive_syntax.md @@ -0,0 +1,5 @@ +This subcommand has the following syntax: + +```bash +chef push-archive POLICY_GROUP ARCHIVE_FILE (options) +``` diff --git a/content/reusable/md/workstation/ctl_chef_push_options.md b/content/reusable/md/workstation/ctl_chef_push_options.md new file mode 100644 index 0000000..4cb875f --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_push_options.md @@ -0,0 +1,17 @@ +This subcommand has the following options: + +`-c CONFIG_FILE`, `--config CONFIG_FILE` + +: The path to the knife configuration file. + +`-D`, `--debug` + +: Enable stack traces and other debug output. + +`-h`, `--help` + +: Show help for the command. + +`-v`, `--version` + +: The Chef Infra Client version. diff --git a/content/reusable/md/workstation/ctl_chef_push_syntax.md b/content/reusable/md/workstation/ctl_chef_push_syntax.md new file mode 100644 index 0000000..568b1c8 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_push_syntax.md @@ -0,0 +1,5 @@ +This subcommand has the following syntax: + +```bash +chef push POLICY_GROUP POLICY_FILE (options) +``` diff --git a/content/reusable/md/workstation/ctl_chef_show_policy.md b/content/reusable/md/workstation/ctl_chef_show_policy.md new file mode 100644 index 0000000..2d92535 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_show_policy.md @@ -0,0 +1,5 @@ +Use the `chef show-policy` subcommand to display revisions for every +`Policyfile.rb` file that's on the Chef Infra Server. By default, only +active policy revisions are shown. When both a policy and policy group +are specified, the contents of the active `Policyfile.lock.json` file +for the policy group is returned. diff --git a/content/reusable/md/workstation/ctl_chef_show_policy_options.md b/content/reusable/md/workstation/ctl_chef_show_policy_options.md new file mode 100644 index 0000000..1a3fe06 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_show_policy_options.md @@ -0,0 +1,27 @@ +This subcommand has the following options: + +`-c CONFIG_FILE`, `--config CONFIG_FILE` + +: The path to the knife configuration file. + +`-D`, `--debug` + +: Enable stack traces and other debug output. Default value: `false`. + +`-h`, `--help` + +: Show help for the command. + +`-o`, `--orphans` + +: Show policy revisions that aren't currently assigned to any policy + group. + +`--[no-]pager` + +: Use `--pager` to enable paged output for a `Policyfile.lock.json` + file. Default value: `--pager`. + +`-v`, `--version` + +: The Chef Infra Client version. diff --git a/content/reusable/md/workstation/ctl_chef_show_policy_syntax.md b/content/reusable/md/workstation/ctl_chef_show_policy_syntax.md new file mode 100644 index 0000000..958ff52 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_show_policy_syntax.md @@ -0,0 +1,5 @@ +This subcommand has the following syntax: + +```bash +chef show-policy POLICY_NAME POLICY_GROUP (options) +``` diff --git a/content/reusable/md/workstation/ctl_chef_undelete.md b/content/reusable/md/workstation/ctl_chef_undelete.md new file mode 100644 index 0000000..34a1554 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_undelete.md @@ -0,0 +1,9 @@ +Use the `chef undelete` subcommand to recover a deleted policy or policy +group. This command: + +- Doesn't detect conflicts. If a deleted item has been recreated, + running this command will overwrite it +- Doesn't include cookbooks that may be referenced by Policyfiles; + cookbooks that are cleaned after running this command may not be + fully restorable to their previous state +- Doesn't store access control data diff --git a/content/reusable/md/workstation/ctl_chef_undelete_options.md b/content/reusable/md/workstation/ctl_chef_undelete_options.md new file mode 100644 index 0000000..ead139e --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_undelete_options.md @@ -0,0 +1,29 @@ +This subcommand has the following options: + +`-c CONFIG_FILE`, `--config CONFIG_FILE` + +: The path to the knife configuration file. + +`-D`, `--debug` + +: Enable stack traces and other debug output. + +`-h`, `--help` + +: Show help for the command. + +`-i ID`, `--id ID` + +: Undo the delete operation specified by `ID`. + +`-l`, `--last` + +: Undo the most recent delete operation. + +`--list` + +: Default. Return a list of available operations. + +`-v`, `--version` + +: The Chef Infra Client version. diff --git a/content/reusable/md/workstation/ctl_chef_undelete_syntax.md b/content/reusable/md/workstation/ctl_chef_undelete_syntax.md new file mode 100644 index 0000000..5746ba8 --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_undelete_syntax.md @@ -0,0 +1,7 @@ +This subcommand has the following syntax: + +```bash +chef undelete (options) +``` + +When run with no arguments, returns a list of available operations. diff --git a/content/reusable/md/workstation/ctl_chef_update.md b/content/reusable/md/workstation/ctl_chef_update.md new file mode 100644 index 0000000..5c77f8a --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_update.md @@ -0,0 +1,6 @@ +Use the `chef update` subcommand to read the `Policyfile.rb` file, and +then apply any changes. This will resolve dependencies and will create a +`Policyfile.lock.json` file. The locked policy will reflect any changes +to the run-list and will pull in any cookbook updates that are +compatible with any version constraints defined in the `Policyfile.rb` +file. diff --git a/content/reusable/md/workstation/ctl_chef_update_options.md b/content/reusable/md/workstation/ctl_chef_update_options.md new file mode 100644 index 0000000..005244d --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_update_options.md @@ -0,0 +1,17 @@ +This subcommand has the following options: + +`-a`, `--attributes` + +: Update attributes. Default value: `false`. + +`-D`, `--debug` + +: Enable stack traces and other debug output. Default value: `false`. + +`-h`, `--help` + +: Show help for the command. + +`-v`, `--version` + +: The Chef Infra Client version. diff --git a/content/reusable/md/workstation/ctl_chef_update_syntax.md b/content/reusable/md/workstation/ctl_chef_update_syntax.md new file mode 100644 index 0000000..70ba5fd --- /dev/null +++ b/content/reusable/md/workstation/ctl_chef_update_syntax.md @@ -0,0 +1,5 @@ +This subcommand has the following syntax: + +```bash +chef update POLICY_FILE (options) +``` diff --git a/content/reusable/md/workstation/knife_bootstrap_node_fips.md b/content/reusable/md/workstation/knife_bootstrap_node_fips.md new file mode 100644 index 0000000..05a7319 --- /dev/null +++ b/content/reusable/md/workstation/knife_bootstrap_node_fips.md @@ -0,0 +1,11 @@ +```bash +knife bootstrap 192.0.2.0 -P vanilla -x root -r 'recipe[apt],recipe[xfs],recipe[vim]' --fips +``` + +which shows something similar to: + +```none +OpenSSL FIPS 140 mode enabled +... +192.0.2.0 Chef Infra Client finished, 12/12 resources updated in 78.942455583 seconds +``` diff --git a/content/reusable/md/workstation/knife_common_see_all_config_options.md b/content/reusable/md/workstation/knife_common_see_all_config_options.md new file mode 100644 index 0000000..102d690 --- /dev/null +++ b/content/reusable/md/workstation/knife_common_see_all_config_options.md @@ -0,0 +1,3 @@ +See [config.rb](https://docs.chef.io/workstation/config_rb_optional_settings/) for more information +about how to add certain knife options as settings in the config.rb +file. diff --git a/content/reusable/md/workstation/knife_common_windows_quotes.md b/content/reusable/md/workstation/knife_common_windows_quotes.md new file mode 100644 index 0000000..d2d49d4 --- /dev/null +++ b/content/reusable/md/workstation/knife_common_windows_quotes.md @@ -0,0 +1,18 @@ +When running knife in Windows, a string may be interpreted as +a wildcard pattern when quotes aren't present in the command. The +number of quotes to use depends on the shell from which the command is +being run. + +When running knife from the command prompt, a string should be +surrounded by single quotes (`' '`). For example: + +```bash +knife node run_list set test-node 'recipe[iptables]' +``` + +When running knife from Windows PowerShell, a string should be +surrounded by triple single quotes (`''' '''`). For example: + +```bash +knife node run_list set test-node '''recipe[iptables]''' +``` diff --git a/content/reusable/md/workstation/knife_common_windows_quotes_module.md b/content/reusable/md/workstation/knife_common_windows_quotes_module.md new file mode 100644 index 0000000..963fa84 --- /dev/null +++ b/content/reusable/md/workstation/knife_common_windows_quotes_module.md @@ -0,0 +1,53 @@ +The Chef Infra Client 12.4 release adds an optional feature to the Microsoft +Installer Package (MSI) for Chef. This feature enables the ability to +pass quoted strings from the Windows PowerShell command line without the +need for triple single quotes (`''' '''`). This feature installs a +Windows PowerShell module (typically in `C:\opscode\chef\modules`) that +is also appended to the `PSModulePath` environment variable. This +feature isn't enabled by default. To activate this feature, run the +following command from within Windows PowerShell: + +```bash +Import-Module chef +``` + +or add `Import-Module chef` to the profile for Windows PowerShell +located at: + +```bash +~\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1 +``` + +This module exports cmdlets that have the same name as the command-line +tools---chef-client, knife---that are built into Chef. + +For example: + +```bash +knife exec -E 'puts ARGV' """&s0meth1ng""" +``` + +is now: + +```bash +knife exec -E 'puts ARGV' '&s0meth1ng' +``` + +and: + +```bash +knife node run_list set test-node '''role[ssssssomething]''' +``` + +is now: + +```bash +knife node run_list set test-node 'role[ssssssomething]' +``` + +To remove this feature, run the following command from within Windows +PowerShell: + +```bash +Remove-Module chef +``` diff --git a/content/reusable/md/workstation/knife_data_bag_edit.md b/content/reusable/md/workstation/knife_data_bag_edit.md new file mode 100644 index 0000000..27f649c --- /dev/null +++ b/content/reusable/md/workstation/knife_data_bag_edit.md @@ -0,0 +1,4 @@ +Use the `edit` argument to edit the data contained in a data bag. If +encryption is being used, the data bag will be decrypted, the data will +be made available in the \$EDITOR, and then encrypted again before +saving it to the Chef Infra Server. diff --git a/content/reusable/md/workstation/knife_data_bag_edit_item.md b/content/reusable/md/workstation/knife_data_bag_edit_item.md new file mode 100644 index 0000000..33fcf2a --- /dev/null +++ b/content/reusable/md/workstation/knife_data_bag_edit_item.md @@ -0,0 +1,25 @@ +To edit an item named `charlie` that's contained in a data bag named `admins`, enter: + +```bash +knife data bag edit admins charlie +``` + +Once opened in the \$EDITOR, update the data before saving it to Chef Infra Server. For example, by changing: + +```javascript +{ + "id": "charlie" +} +``` + +to: + +```javascript +{ + "id": "charlie", + "uid": 1005, + "gid": "ops", + "shell": "/bin/zsh", + "comment": "Crazy Charlie" +} +``` diff --git a/content/reusable/md/workstation/knife_data_bag_from_file_create_encrypted_local_mode.md b/content/reusable/md/workstation/knife_data_bag_from_file_create_encrypted_local_mode.md new file mode 100644 index 0000000..d3e7b75 --- /dev/null +++ b/content/reusable/md/workstation/knife_data_bag_from_file_create_encrypted_local_mode.md @@ -0,0 +1,9 @@ +To generate an encrypted data bag item in a JSON file for use when Chef +Infra Client is run in local mode (using the `--local-mode` option), +enter: + +```bash +knife data bag from file my_data_bag /path/to/data_bag_item.json -z --secret-file /path/to/encrypted_data_bag_secret +``` + +This creates an encrypted JSON file in `data_bags/my_data_bag/data_bag_item.json` diff --git a/content/reusable/md/workstation/knife_node_run_list_add.md b/content/reusable/md/workstation/knife_node_run_list_add.md new file mode 100644 index 0000000..b096098 --- /dev/null +++ b/content/reusable/md/workstation/knife_node_run_list_add.md @@ -0,0 +1,2 @@ +Use the `run_list add` argument to add run-list items (roles or recipes) +to a node. diff --git a/content/reusable/md/workstation/knife_node_run_list_add_default_recipe.md b/content/reusable/md/workstation/knife_node_run_list_add_default_recipe.md new file mode 100644 index 0000000..8639961 --- /dev/null +++ b/content/reusable/md/workstation/knife_node_run_list_add_default_recipe.md @@ -0,0 +1,5 @@ +To add the default recipe of a cookbook to a run-list, enter: + +```bash +knife node run_list add NODE_NAME 'COOKBOOK' +``` diff --git a/content/reusable/md/workstation/knife_node_run_list_add_options.md b/content/reusable/md/workstation/knife_node_run_list_add_options.md new file mode 100644 index 0000000..ed925d6 --- /dev/null +++ b/content/reusable/md/workstation/knife_node_run_list_add_options.md @@ -0,0 +1,9 @@ +This argument has the following options: + +`-a ITEM`, `--after ITEM` + +: Add a run-list item after the specified run-list item. + +`-b ITEM`, `--before ITEM` + +: Add a run-list item before the specified run-list item. diff --git a/content/reusable/md/workstation/knife_node_run_list_add_recipe_with_cookbook.md b/content/reusable/md/workstation/knife_node_run_list_add_recipe_with_cookbook.md new file mode 100644 index 0000000..f3b5be0 --- /dev/null +++ b/content/reusable/md/workstation/knife_node_run_list_add_recipe_with_cookbook.md @@ -0,0 +1,5 @@ +To add a recipe to a run-list using the cookbook format, enter: + +```bash +knife node run_list add NODE_NAME 'COOKBOOK::RECIPE_NAME' +``` diff --git a/content/reusable/md/workstation/knife_node_run_list_add_recipe_with_fqdn.md b/content/reusable/md/workstation/knife_node_run_list_add_recipe_with_fqdn.md new file mode 100644 index 0000000..9628590 --- /dev/null +++ b/content/reusable/md/workstation/knife_node_run_list_add_recipe_with_fqdn.md @@ -0,0 +1,5 @@ +To add a recipe to a run-list using the fully qualified format, enter: + +```bash +knife node run_list add NODE_NAME 'recipe[COOKBOOK::RECIPE_NAME]' +``` diff --git a/content/reusable/md/workstation/knife_node_run_list_add_role.md b/content/reusable/md/workstation/knife_node_run_list_add_role.md new file mode 100644 index 0000000..0df0188 --- /dev/null +++ b/content/reusable/md/workstation/knife_node_run_list_add_role.md @@ -0,0 +1,5 @@ +To add a role to a run-list, enter: + +```bash +knife node run_list add NODE_NAME 'role[ROLE_NAME]' +``` diff --git a/content/reusable/md/workstation/knife_node_run_list_add_roles_and_recipes.md b/content/reusable/md/workstation/knife_node_run_list_add_roles_and_recipes.md new file mode 100644 index 0000000..bd0e5e8 --- /dev/null +++ b/content/reusable/md/workstation/knife_node_run_list_add_roles_and_recipes.md @@ -0,0 +1,5 @@ +To add roles and recipes to a run-list, enter: + +```bash +knife node run_list add NODE_NAME 'recipe[COOKBOOK::RECIPE_NAME],recipe[COOKBOOK::RECIPE_NAME],role[ROLE_NAME]' +``` diff --git a/content/reusable/md/workstation/knife_node_run_list_add_syntax.md b/content/reusable/md/workstation/knife_node_run_list_add_syntax.md new file mode 100644 index 0000000..31ce047 --- /dev/null +++ b/content/reusable/md/workstation/knife_node_run_list_add_syntax.md @@ -0,0 +1,5 @@ +This argument has the following syntax: + +```bash +knife node run_list add NODE_NAME RUN_LIST_ITEM (options) +``` diff --git a/content/reusable/md/workstation/knife_node_run_list_remove.md b/content/reusable/md/workstation/knife_node_run_list_remove.md new file mode 100644 index 0000000..53ea202 --- /dev/null +++ b/content/reusable/md/workstation/knife_node_run_list_remove.md @@ -0,0 +1,7 @@ +Use the `run_list remove` argument to remove run-list items (roles or +recipes) from a node. A recipe must be in one of the following formats: +fully qualified, cookbook, or default. Both roles and recipes must be in +quotes, for example: `'role[ROLE_NAME]'` or +`'recipe[COOKBOOK::RECIPE_NAME]'`. Use a comma to separate roles and +recipes when removing more than one, like this: +`'recipe[COOKBOOK::RECIPE_NAME],COOKBOOK::RECIPE_NAME,role[ROLE_NAME]'`. diff --git a/content/reusable/md/workstation/knife_node_run_list_remove_role.md b/content/reusable/md/workstation/knife_node_run_list_remove_role.md new file mode 100644 index 0000000..a3ceba8 --- /dev/null +++ b/content/reusable/md/workstation/knife_node_run_list_remove_role.md @@ -0,0 +1,5 @@ +To remove a role from a run-list, enter: + +```bash +knife node run_list remove NODE_NAME 'role[ROLE_NAME]' +``` diff --git a/content/reusable/md/workstation/knife_node_run_list_remove_run_list.md b/content/reusable/md/workstation/knife_node_run_list_remove_run_list.md new file mode 100644 index 0000000..5910567 --- /dev/null +++ b/content/reusable/md/workstation/knife_node_run_list_remove_run_list.md @@ -0,0 +1,6 @@ +To remove a recipe from a run-list using the fully qualified format, +enter: + +```bash +knife node run_list remove NODE_NAME 'recipe[COOKBOOK::RECIPE_NAME]' +``` diff --git a/content/reusable/md/workstation/knife_node_run_list_remove_syntax.md b/content/reusable/md/workstation/knife_node_run_list_remove_syntax.md new file mode 100644 index 0000000..b7b29a9 --- /dev/null +++ b/content/reusable/md/workstation/knife_node_run_list_remove_syntax.md @@ -0,0 +1,5 @@ +This argument has the following syntax: + +```bash +knife node run_list remove NODE_NAME RUN_LIST_ITEM +``` diff --git a/content/reusable/md/workstation/knife_node_run_list_set.md b/content/reusable/md/workstation/knife_node_run_list_set.md new file mode 100644 index 0000000..5c5d86c --- /dev/null +++ b/content/reusable/md/workstation/knife_node_run_list_set.md @@ -0,0 +1,6 @@ +Use the `run_list set` argument to set the run-list for a node. A recipe +must be in one of the following formats: fully qualified, cookbook, or +default. Both roles and recipes must be in quotes, for example: +`"role[ROLE_NAME]"` or `"recipe[COOKBOOK::RECIPE_NAME]"`. Use a comma to +separate roles and recipes when setting more than one, like this: +`"recipe[COOKBOOK::RECIPE_NAME],COOKBOOK::RECIPE_NAME,role[ROLE_NAME]"`. diff --git a/content/reusable/md/workstation/knife_node_run_list_set_syntax.md b/content/reusable/md/workstation/knife_node_run_list_set_syntax.md new file mode 100644 index 0000000..31ed0ed --- /dev/null +++ b/content/reusable/md/workstation/knife_node_run_list_set_syntax.md @@ -0,0 +1,5 @@ +This argument has the following syntax: + +```bash +knife node run_list set NODE_NAME RUN_LIST_ITEM +``` diff --git a/content/reusable/md/workstation/knife_search_by_cookbook.md b/content/reusable/md/workstation/knife_search_by_cookbook.md new file mode 100644 index 0000000..e781c28 --- /dev/null +++ b/content/reusable/md/workstation/knife_search_by_cookbook.md @@ -0,0 +1,7 @@ +To search for cookbooks on a node, use the `recipes` attribute followed +by the `cookbook::recipe` pattern, escaping both of the `:` characters. +For example: + +```bash +knife search node 'recipes:cookbook_name\:\:recipe_name' +``` diff --git a/content/reusable/md/workstation/knife_search_by_nested_attribute.md b/content/reusable/md/workstation/knife_search_by_nested_attribute.md new file mode 100644 index 0000000..a160fe6 --- /dev/null +++ b/content/reusable/md/workstation/knife_search_by_nested_attribute.md @@ -0,0 +1,5 @@ +To find a nested attribute, use a pattern similar to the following: + +```bash +knife search node -a . +``` diff --git a/content/reusable/md/workstation/knife_search_by_node.md b/content/reusable/md/workstation/knife_search_by_node.md new file mode 100644 index 0000000..65d9d91 --- /dev/null +++ b/content/reusable/md/workstation/knife_search_by_node.md @@ -0,0 +1,5 @@ +To search for all nodes running Ubuntu, enter: + +```bash +knife search node 'platform:ubuntu' +``` diff --git a/content/reusable/md/workstation/knife_search_by_node_and_environment.md b/content/reusable/md/workstation/knife_search_by_node_and_environment.md new file mode 100644 index 0000000..54a1e39 --- /dev/null +++ b/content/reusable/md/workstation/knife_search_by_node_and_environment.md @@ -0,0 +1,6 @@ +To search for all nodes running CentOS in the production environment, +enter: + +```bash +knife search node 'chef_environment:production AND platform:centos' +``` diff --git a/content/reusable/md/workstation/knife_search_by_platform_ids.md b/content/reusable/md/workstation/knife_search_by_platform_ids.md new file mode 100644 index 0000000..8d0f84f --- /dev/null +++ b/content/reusable/md/workstation/knife_search_by_platform_ids.md @@ -0,0 +1,20 @@ +To search for the IDs of all nodes running on the Amazon EC2 platform, +enter: + +```bash +knife search node 'ec2:*' -i +``` + +to return something like: + +```bash +4 items found + +ip-0A7CA19F.ec2.internal + +ip-0A58CF8E.ec2.internal + +ip-0A58E134.ec2.internal + +ip-0A7CFFD5.ec2.internal +``` diff --git a/content/reusable/md/workstation/knife_search_by_platform_instance_type.md b/content/reusable/md/workstation/knife_search_by_platform_instance_type.md new file mode 100644 index 0000000..0437c78 --- /dev/null +++ b/content/reusable/md/workstation/knife_search_by_platform_instance_type.md @@ -0,0 +1,24 @@ +To search for the instance type (flavor) of all nodes running on the +Amazon EC2 platform, enter: + +```bash +knife search node 'ec2:*' -a ec2.instance_type +``` + +to return something like: + +```bash +4 items found + +ec2.instance_type: m1.large +id: ip-0A7CA19F.ec2.internal + +ec2.instance_type: m1.large +id: ip-0A58CF8E.ec2.internal + +ec2.instance_type: m1.large +id: ip-0A58E134.ec2.internal + +ec2.instance_type: m1.large +id: ip-0A7CFFD5.ec2.internal +``` diff --git a/content/reusable/md/workstation/knife_search_by_query_for_many_attributes.md b/content/reusable/md/workstation/knife_search_by_query_for_many_attributes.md new file mode 100644 index 0000000..8264da3 --- /dev/null +++ b/content/reusable/md/workstation/knife_search_by_query_for_many_attributes.md @@ -0,0 +1,7 @@ +To build a search query to use more than one attribute, use an +underscore (`_`) to separate each attribute. For example, the following +query will search for all nodes running a specific version of Ruby: + +```bash +knife search node "languages_ruby_version:2.7.0" +``` diff --git a/content/reusable/md/workstation/knife_search_by_query_for_nested_attribute.md b/content/reusable/md/workstation/knife_search_by_query_for_nested_attribute.md new file mode 100644 index 0000000..1e89264 --- /dev/null +++ b/content/reusable/md/workstation/knife_search_by_query_for_nested_attribute.md @@ -0,0 +1,5 @@ +To build a search query that can find a nested attribute: + +```bash +knife search node name: -a kernel.machine +``` diff --git a/content/reusable/md/workstation/knife_search_by_recipe.md b/content/reusable/md/workstation/knife_search_by_recipe.md new file mode 100644 index 0000000..e2a8a30 --- /dev/null +++ b/content/reusable/md/workstation/knife_search_by_recipe.md @@ -0,0 +1,12 @@ +To search for recipes that are used by a node, use the `recipes` +attribute to search for the recipe names, enter something like: + +```bash +knife search node 'recipes:recipe_name' +``` + +or: + +```bash +knife search node '*:*' -a recipes | grep 'recipe_name' +``` diff --git a/content/reusable/md/workstation/knife_search_summary.md b/content/reusable/md/workstation/knife_search_summary.md new file mode 100644 index 0000000..397b196 --- /dev/null +++ b/content/reusable/md/workstation/knife_search_summary.md @@ -0,0 +1,2 @@ +Use the `knife search` subcommand to run a search query for information +that's indexed on a Chef Infra Server. diff --git a/content/reusable/md/workstation/knife_search_test_query_for_ssh.md b/content/reusable/md/workstation/knife_search_test_query_for_ssh.md new file mode 100644 index 0000000..d29367f --- /dev/null +++ b/content/reusable/md/workstation/knife_search_test_query_for_ssh.md @@ -0,0 +1,8 @@ +To test a search query that will be used in a `knife ssh` subcommand: + +```bash +knife search node "role:web NOT name:web03" +``` + +where the query in the previous example will search all servers that +have the `web` role, but not on the server named `web03`. diff --git a/content/reusable/md/workstation/knife_ssl_check_bad_ssl_certificate.md b/content/reusable/md/workstation/knife_ssl_check_bad_ssl_certificate.md new file mode 100644 index 0000000..c67849c --- /dev/null +++ b/content/reusable/md/workstation/knife_ssl_check_bad_ssl_certificate.md @@ -0,0 +1,42 @@ +If the SSL certificate can't be verified, the response to + +```bash +knife ssl check +``` + +is similar to: + +```bash +Connecting to host chef-server.example.com:443 +ERROR: The SSL certificate of chef-server.example.com could not be verified +Certificate issuer data: + /C=US/ST=WA/L=S/O=Corp/OU=Ops/CN=chef-server.example.com/emailAddress=you@example.com + +Configuration Info: + +OpenSSL Configuration: +* Version: OpenSSL 1.0.2u 20 Dec 2019 +* Certificate file: /opt/chef-workstation/embedded/ssl/cert.pem +* Certificate directory: /opt/chef-workstation/embedded/ssl/certs +Chef SSL Configuration: +* ssl_ca_path: nil +* ssl_ca_file: nil +* trusted_certs_dir: "/Users/grantmc/Downloads/chef-repo/.chef/trusted_certs" + +TO FIX THIS ERROR: + +If the server you are connecting to uses a self-signed certificate, +you must configure chef to trust that certificate. + +By default, the certificate is stored in the following location on the +host where your Chef Infra Server runs: + + /var/opt/opscode/nginx/ca/SERVER_HOSTNAME.crt + +Copy that file to your trusted_certs_dir (currently: + + /Users/grantmc/Downloads/chef-repo/.chef/trusted_certs) + +using SSH/SCP or some other secure method, then re-run this command to +confirm that the certificate is now trusted. +``` diff --git a/content/reusable/md/workstation/knife_ssl_check_verify_server_config.md b/content/reusable/md/workstation/knife_ssl_check_verify_server_config.md new file mode 100644 index 0000000..9d7513b --- /dev/null +++ b/content/reusable/md/workstation/knife_ssl_check_verify_server_config.md @@ -0,0 +1,12 @@ +If the SSL certificate can be verified, the response to + +```bash +knife ssl check +``` + +is similar to: + +```bash +Connecting to host chef-server.example.com:443 +Successfully verified certificates from 'chef-server.example.com' +``` diff --git a/content/reusable/md/workstation/knife_ssl_fetch_verify_certificate.md b/content/reusable/md/workstation/knife_ssl_fetch_verify_certificate.md new file mode 100644 index 0000000..4f92438 --- /dev/null +++ b/content/reusable/md/workstation/knife_ssl_fetch_verify_certificate.md @@ -0,0 +1,30 @@ +The SSL certificate that's downloaded to the `/.chef/trusted_certs` +directory should be verified to ensure that it's, in fact, the same +certificate as the one located on the Chef Infra Server. This can be +done by comparing the SHA-256 checksums. + +1. View the checksum on the Chef Infra Server: + + ```bash + ssh ubuntu@chef-server.example.com sudo sha256sum /var/opt/opscode/nginx/ca/chef-server.example.com.crt + ``` + + The response is similar to: + + ```bash + /var/opt/opscode/nginx/ca/chef-server.example.com.crt + ``` + +2. View the checksum on the workstation: + + ```bash + gsha256sum .chef/trusted_certs/chef-server.example.com.crt + ``` + + The response is similar to: + + ```bash + .chef/trusted_certs/chef-server.example.com.crt + ``` + +3. Verify that the checksum values are identical. diff --git a/content/reusable/md/workstation/knife_status_include_run_lists.md b/content/reusable/md/workstation/knife_status_include_run_lists.md new file mode 100644 index 0000000..43dd116 --- /dev/null +++ b/content/reusable/md/workstation/knife_status_include_run_lists.md @@ -0,0 +1,16 @@ +To include run-lists in the status, enter: + +```bash +knife status --run-list +``` + +to return something like: + +```bash +20 hours ago, dev-vm.chisamore.com, ubuntu 10.04, dev-vm.chisamore.com, 10.66.44.126, role[lb]. +3 hours ago, i-225f954f, ubuntu 10.04, ec2-67-202-63-102.compute-1.amazonaws.com, 67.202.63.102, role[web]. +3 hours ago, i-a45298c9, ubuntu 10.04, ec2-174-129-127-206.compute-1.amazonaws.com, 174.129.127.206, role[web]. +3 hours ago, i-5272a43f, ubuntu 10.04, ec2-184-73-9-250.compute-1.amazonaws.com, 184.73.9.250, role[web]. +3 hours ago, i-226ca64f, ubuntu 10.04, ec2-75-101-240-230.compute-1.amazonaws.com, 75.101.240.230, role[web]. +3 hours ago, i-f65c969b, ubuntu 10.04, ec2-184-73-60-141.compute-1.amazonaws.com, 184.73.60.141, role[web]. +``` diff --git a/content/reusable/md/workstation/knife_status_returned_by_query.md b/content/reusable/md/workstation/knife_status_returned_by_query.md new file mode 100644 index 0000000..0458cff --- /dev/null +++ b/content/reusable/md/workstation/knife_status_returned_by_query.md @@ -0,0 +1,16 @@ +To show the status of a subset of nodes that are returned by a specific +query, enter: + +```bash +knife status "role:web" --run-list +``` + +to return something like: + +```bash +3 hours ago, i-225f954f, ubuntu 10.04, ec2-67-202-63-102.compute-1.amazonaws.com, 67.202.63.102, role[web]. +3 hours ago, i-a45298c9, ubuntu 10.04, ec2-174-129-127-206.compute-1.amazonaws.com, 174.129.127.206, role[web]. +3 hours ago, i-5272a43f, ubuntu 10.04, ec2-184-73-9-250.compute-1.amazonaws.com, 184.73.9.250, role[web]. +3 hours ago, i-226ca64f, ubuntu 10.04, ec2-75-101-240-230.compute-1.amazonaws.com, 75.101.240.230, role[web]. +3 hours ago, i-f65c969b, ubuntu 10.04, ec2-184-73-60-141.compute-1.amazonaws.com, 184.73.60.141, role[web]. +``` diff --git a/content/reusable/md/workstation/knife_windows_summary.md b/content/reusable/md/workstation/knife_windows_summary.md new file mode 100644 index 0000000..c56a8f6 --- /dev/null +++ b/content/reusable/md/workstation/knife_windows_summary.md @@ -0,0 +1,5 @@ +The `knife windows` subcommand is used to interact with Windows systems +managed by Chef Infra. Nodes are configured using WinRM, which allows +external applications to call native objects like batch scripts, Windows +PowerShell scripts, or scripting library variables. The `knife windows` +subcommand supports NTLM and Kerberos methods of authentication. diff --git a/content/reusable/md/workstation/knife_windows_winrm_ports.md b/content/reusable/md/workstation/knife_windows_winrm_ports.md new file mode 100644 index 0000000..4153449 --- /dev/null +++ b/content/reusable/md/workstation/knife_windows_winrm_ports.md @@ -0,0 +1,2 @@ +WinRM requires that a target node be accessible using the ports configured +to support access using HTTP or HTTPS. diff --git a/content/reusable/md/workstation/test_kitchen.md b/content/reusable/md/workstation/test_kitchen.md new file mode 100644 index 0000000..9b8b08e --- /dev/null +++ b/content/reusable/md/workstation/test_kitchen.md @@ -0,0 +1,10 @@ +Use [Test Kitchen](https://kitchen.ci/) to automatically test cookbooks +across any combination of platforms and test suites: + +- Test suites are defined in a kitchen.yml file. See the + [configuration](https://docs.chef.io/workstation/config_yml_kitchen/) documentation for options + and syntax information. +- Supports cookbook testing across many cloud providers and + virtualization technologies. +- Uses a comprehensive set of operating system base images from Chef's + [Bento](https://github.com/chef/bento) project. diff --git a/content/reusable/md/workstation_modularize.md b/content/reusable/md/workstation_modularize.md deleted file mode 100644 index 7e49793..0000000 --- a/content/reusable/md/workstation_modularize.md +++ /dev/null @@ -1,3 +0,0 @@ -Chef Workstation is modularized to improve user experience and simplify interactions with its components. -This divides Chef Workstation into independent parts, enabling users to install, upgrade, and manage specific components individually using Chef Habitat. -This approach reduces the complexity of maintaining the entire package. diff --git a/content/ruby_gem_server.md b/content/ruby_gem_server.md deleted file mode 100644 index ed893f4..0000000 --- a/content/ruby_gem_server.md +++ /dev/null @@ -1,52 +0,0 @@ -+++ -title = "Chef's Ruby gem server" -draft = true - -[menu.chef_gem_server] -title = "Chef's Ruby gem server" -+++ - -Chef's Ruby gem server distributes Chef's commercial and licensed Ruby gems. The server is hosted at . - -## Add Chef's gem server as a source - -Before you begin, you will need your valid [Progress Chef license key](https://docs.chef.io/licensing/license_key/). - -- Add Chef's Ruby gem server using `gem source --add`: - - ```sh - gem sources --add https://v1:@rubygems.chef.io - ``` - - It returns a message that `rubygems.chef.io` has been added as a gem source. - -## Install a Ruby gem - -1. Optional: Verify that you've added Chef's Ruby gem server as a source: - - ```sh - gem sources -l - ``` - - This returns a list of Ruby gem servers that should include `rubygems.chef.io`: - - ```sh - *** CURRENT SOURCES *** - - https://rubygems.org/ - https://v1:@rubygems.chef.io - ``` - -1. Install a gem: - - ```sh - gem install - ``` - - This installs the gem and displays a success message. - - For testing purposes, you can try installing `chef-test` or 'inspec-test' gem to verify that you can install from Chef's gem server: - - ```sh - gem install chef-test-0.1.0.gem - ``` diff --git a/content/security/chef_client_security.md b/content/security/chef_client_security.md new file mode 100644 index 0000000..5123f8c --- /dev/null +++ b/content/security/chef_client_security.md @@ -0,0 +1,141 @@ ++++ +title = "Chef Infra Client security" +draft = false + +[menu] + [menu.security] + title = "Chef Infra Client security" + identifier = "security/chef_client_security.md Security" + parent = "security" + weight = 10 ++++ + + +{{< readfile file="content/reusable/md/server/chef_auth.md" >}} + +## Authentication + +{{< readfile file="content/reusable/md/server/chef_auth_authentication.md" >}} + +### chef-validator + +{{< readfile file="content/reusable/md/security_chef_validator.md" >}} + +{{< readfile file="content/reusable/md/security_chef_validator_context.md" >}} + +## SSL certificates + +{{< readfile file="content/reusable/md/server/server_security_ssl_cert_client.md" >}} + +### trusted_certs directory + +You can use use a private certificate authority (CA) to generate SSL certificates or they may create self-signed SSL certificates to use on internal networks or during software development and testing. + +The `trusted_certs` directory on Chef Workstation and in Chef Infra Client works as a trusted certificate store for all communication in the Chef Infra system. Chef Infra trusts all SSL certificates stored in this directory---including certificates that aren't issued by a trusted certificate authority (CA). + +Place private and self-signed certificates in the `trusted_certs` directory to use them within Chef Infra Client and Workstation tools. + +Use the [`chef_client_trusted_certificate`]({{< relref "/resources/bundled/chef_client_trusted_certificate" >}}) Chef Infra Client resource to manage these certificates continuously. + +#### trusted_certs directory locations + +##### Chef Workstation + +When you install Chef Workstation, it creates a `trusted_certs` directory located at:. + +- Windows: `C:\.chef\trusted_certs` +- All other systems: `~/.chef/trusted_certs` + +##### Chef Infra Client nodes + +When you bootstrap a node, the Chef Infra Client copies the SSL certificates for Chef Infra Server onto the node. The `trusted_certs` directory on the node is located at: + +- Windows: `C:\chef\trusted_certs` +- All other systems: `/etc/chef/trusted_certs` + +### SSL_CERT_FILE + +Use the `SSL_CERT_FILE` environment variable to specify the location for the SSL certificate authority (CA) bundle for Chef Infra Client. + +A value for `SSL_CERT_FILE` isn't set by default. Unless updated, the locations in which Chef Infra will look for SSL certificates are: + +- Chef Infra Client: `/opt/chef/embedded/ssl/certs/cacert.pem` +- Chef Workstation: `/opt/chef-workstation/embedded/ssl/certs/cacert.pem` + +To use a custom CA bundle, update the environment variable to specify the path to the custom CA bundle. The first step to troubleshoot a failing SSL certificate is to verify the location of the `SSL_CERT_FILE`. + +### client.rb file settings + + + +Use following [`client.rb` file]({{< relref "config_rb_client" >}}) settings to manage SSL certificate preferences: + +`local_key_generation` +: Whether Chef Infra Server or Chef Infra Client generates the private/public key pair. + When `true`, Chef Infra Client generates the key pair and then sends the public key to Chef Infra Server. + + Default value: `true`. + +`ssl_ca_file` +: The file for the OpenSSL key. Chef Infra Client generates this setting automatically. + +`ssl_ca_path` +: The location of the OpenSSL key file. Chef Infra Client generates this setting automatically. + +`ssl_client_cert` +: The OpenSSL X.509 certificate for mutual certificate validation. Required for mutual certificate validation on Chef Infra Server. + + Default value: `nil`. + +`ssl_client_key` +: The OpenSSL X.509 key used for mutual certificate validation. Required for mutual certificate validation on Chef Infra Server. + + Default value: `nil`. + +`ssl_verify_mode` +: Set the verification mode for HTTPS requests. The recommended setting is `:verify_peer`. Depending on your OpenSSL configuration, you may need to set the `ssl_ca_path`. + + Allowed values: + + - Use `:verify_none` to run without validating any SSL certificates. + - Use `:verify_peer` to validate all SSL certificates, including Chef Infra Server connections, S3 connections, and any HTTPS `remote_file` resource URLs used in a Chef Infra Client run. + + Default value: `:verify_peer`. + +`verify_api_cert` +: Verify the SSL certificate on Chef Infra Server. + + If `true`, Chef Infra Client always verifies the SSL certificate. If `false`, Chef Infra Client uses `ssl_verify_mode` to determine if the SSL certificate requires verification. + + Default value: `false`. + + + +### knife CLI subcommands + +The Chef Infra Client includes two knife commands for managing SSL certificates: + +- Use [knife ssl check](https://docs.chef.io/workstation/knife_ssl_check/) to troubleshoot SSL certificate issues. +- Use [knife ssl fetch](https://docs.chef.io/workstation/knife_ssl_fetch/) to pull down a certificate from Chef Infra Server to the `/.chef/trusted_certs` directory on the workstation. + +After the workstation has the correct SSL certificate, bootstrap operations from that workstation uses the certificate in the `/.chef/trusted_certs` directory during the bootstrap operation. + +#### knife ssl check + +Run [`knife ssl check`](https://docs.chef.io/workstation/knife_ssl_check/) to verify the state of the SSL certificate, and then use the response to help troubleshoot any issues. + +##### Verified + +{{< readfile file="content/reusable/md/workstation/knife_ssl_check_verify_server_config.md" >}} + +##### Unverified + +{{< readfile file="content/reusable/md/workstation/knife_ssl_check_bad_ssl_certificate.md" >}} + +#### knife ssl fetch + +Run [`knife ssl fetch`](https://docs.chef.io/workstation/knife_ssl_fetch/) to download the self-signed certificate from Chef Infra Server to the `/.chef/trusted_certs` directory on a workstation. + +##### Verify checksums + +{{< readfile file="content/reusable/md/workstation/knife_ssl_fetch_verify_certificate.md" >}} diff --git a/content/security/fips.md b/content/security/fips.md new file mode 100644 index 0000000..eae80d4 --- /dev/null +++ b/content/security/fips.md @@ -0,0 +1,115 @@ ++++ +title = "FIPS (Federal Information Processing Standards)" +draft = false + +[menu] + [menu.security] + title = "FIPS" + identifier = "security/fips.md FIPS" + parent = "security" + weight = 30 ++++ + + + + +## What's FIPS? + +Federal Information Processing Standards (FIPS) are federal standards +for computer systems used by contractors of government agencies and +non-military government agencies. + +FIPS 140-2 is a specific federal government security standard used to +approve cryptographic modules. Chef Automate uses the OpenSSL FIPS +Object Module, which satisfies the requirements of software +cryptographic modules under the FIPS 140-2 standard. The OpenSSL Object +Module provides an API for invoking FIPS approved cryptographic +functions from calling applications. + +### Who should enable FIPS? + +You may be legally required to enable FIPS if you are a United States +non-military government agency, or are contracting with one. If you are +not sure if you need to enable FIPS, please check with your compliance +department. + +### Who shouldn't enable FIPS? + +You will only need to enable FIPS if you are a US non-military +government agency, or contracting with one, and you are contractually +obligated to meet federal government security standards. If you aren't +a US non-military governmental agency, or you aren't contracting with +one, and you aren't contractually obligated to meet federal government +security standards, then don't enable FIPS. Chef products have robust +security standards even without FIPS, and FIPS prevents the use of +certain hashing algorithms you might want to use, so we only recommend +enabling FIPS if it's contractually necessary. + +## Supported products + +**Supported:** + +- [Chef Infra Client](#how-to-enable-fips-mode-for-chef-infra-client) +- [Chef Workstation](https://docs.chef.io/workstation/knife_bootstrap/#fips-mode) +- [Chef Infra Server](#how-to-enable-fips-mode-for-chef-infra-server) + +**Unsupported:** + +FIPS mode isn't supported for Chef Infra Server add-ons. This includes Chef Manage. + +## How to enable FIPS mode in the operating system + +### FIPS kernel settings + +Windows and Red Hat Enterprise Linux can both be configured for FIPS +mode using a kernel-level setting. After FIPS mode is enabled at the +kernel level, the operating system will only use FIPS approved +algorithms and keys during operation. + +All of the tools Chef produces that have FIPS support read this kernel +setting and default their mode of operation to match it with the +exception of the workstation, which requires designating a port in the +`fips_git_port` setting of the `cli.toml`. For the other Chef Infra tools, +Chef Infra Client, for example, if `chef-client` is run on an operating +system configured into FIPS mode and you run, that Chef Infra run will +automatically be in FIPS mode unless the user disables it. + +To enable FIPS on your platform follow these instructions: + +- [Red Hat Enterprise Linux 6](https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Security_Guide/sect-Security_Guide-Federal_Standards_And_Regulations-Federal_Information_Processing_Standard.html) +- [Red Hat Enterprise Linux 7](https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Security_Guide/chap-Federal_Standards_and_Regulations.html#sec-Enabling-FIPS-Mode) +- [Red Hat Enterprise Linux 8](https://www.redhat.com/en/blog/how-rhel-8-designed-fips-140-2-requirements) +- [Windows](https://technet.microsoft.com/en-us/library/cc750357.aspx) +- [Ubuntu](https://security-certs.docs.ubuntu.com/en/fips) + +## How to enable FIPS mode for Chef Infra Server + +### Prerequisites + +- Supported Systems - CentOS or Red Hat Enterprise Linux 6 or greater +- Chef Infra Server version 12.13 or greater + +### Configuration + +If you have FIPS compliance enabled at the kernel level and install or +reconfigure Chef Infra Server then it will default to running in +FIPS mode. + +To enable FIPS manually for Chef Infra Server, can add `fips true` +to the `/etc/opscode/chef-server.rb` and reconfigure. For more +configuration information see [chef-server.rb Optional Settings](https://docs.chef.io/server/config_rb_server_optional_settings/). + +## How to enable FIPS mode for Chef Infra Client + +### Prerequisites + +- Supported Systems - CentOS, Oracle Linux, Red Hat Enterprise Linux 6 or later, and Ubuntu +- Chef Infra Client 16.13 or later for Ubuntu systems + +### Configuration + +If you have FIPS compliance enabled at the kernel level, Chef Infra Client will default to running in FIPS mode. Otherwise, add `fips true` to the `/etc/chef/client.rb` or `C:\\chef\\client.rb`. + +#### Bootstrap a node using FIPS + +{{< readfile file="content/reusable/md/workstation/knife_bootstrap_node_fips.md" >}} diff --git a/content/troubleshooting.md b/content/troubleshooting.md new file mode 100644 index 0000000..3529ad6 --- /dev/null +++ b/content/troubleshooting.md @@ -0,0 +1,542 @@ ++++ +title = "Troubleshooting" +draft = false + +[menu] + [menu.troubleshooting] + title = "Troubleshooting" + identifier = "Troubleshooting" ++++ + + + +The following sections describe how to troubleshoot Chef Infra Server, Chef Infra Client, and Chef Workstation. + +## 401 Unauthorized + +There are multiple causes of the Chef 401 "Unauthorized" error, so please use the sections below to find the error message that most closely matches your output. If you are unable to find a matching error, or if the provided steps are unhelpful, please [file a help ticket](https://getchef.zendesk.com/hc/en-us). + +### Failed to authenticate as ORGANIZATION-validator + +If you're receiving an error like the following it most likely means you'll need to regenerate the ORGANIZATION-validator.pem file: + +```bash +INFO: Client key /etc/chef/client.pem isn't present - registering +INFO: HTTP Request Returned 401 Unauthorized: Failed to authenticate as ORGANIZATION-validator. Ensure that your node_name and client key are correct. +FATAL: Stacktrace dumped to c:/chef/cache/chef-stacktrace.out +FATAL: Net::HTTPClientException: 401 "Unauthorized" +``` + +#### Troubleshooting steps + +1. Check if the ORGANIZATION-validator.pem file exists in one of the following locations: + + ```text + ~/.chef + ~/projects/current_project/.chef + /etc/chef + ``` + + If one is present, verify that it has the correct read permissions. + +2. If there's no ORGANIZATION-validator.pem file, regenerate it. + + Recreate this file by going to the Chef management console web user interface and selecting **Organizations** in the upper right side of the screen. + + You can then select **Reset Validation Key** next to the organization for which the key is to be reset. + +## Failed to authenticate to + +When the values for certain settings in the client.rb file---`node_name` and `client_key`---are incorrect, it won't be possible to authenticate to Chef Infra Server. An error similar to the following is shown: + +```bash +ERROR: Failed to authenticate to https://api.opscode.com/organizations/ORGANIZATION as USERNAME with key /path/to/USERNAME.pem +Response: Failed to authenticate as USERNAME. Ensure that your node_name and client key are correct. +``` + +### Troubleshooting steps + +- Verify you have the correct values in your config.rb file, especially for the `node_name` and `client_key` settings. + +- Check if the file referenced in the `client_key` setting (usually USER.pem) exists. Some common locations include: + + - `~/.chef` + - `~/projects/current_project/.chef` + - `/etc/chef` + + If one is present, verify that it has the correct read permissions. + +- If there's no client.rb file, regenerate it and ensure the values for the `node_name` and `client_key` settings are correct. + +### Organization not found + +If you see this error when trying to recreate the ORGANIZATION-validator.pem, it's possible that Chef Infra Client itself was deleted. In this situation, the ORGANIZATION-validator.pem will need to be recreated. In these directions, `ORGANIZATION` should be replaced with the name of your organization. + +{{< readfile file="content/reusable/md/manage_webui_policy_validation_reset_key.md" >}} + +### Synchronize the clock on your host + +If the system clock drifts more than 15 minutes from the actual time, the following type of error will be shown: + +```bash +INFO: Client key /etc/chef/client.pem isn't present - registering +INFO: HTTP Request Returned 401 Unauthorized: Failed to authenticate as ORGANIZATION-validator. Synchronize the clock on your host. +FATAL: Stacktrace dumped to /var/chef/cache/chef-stacktrace.out +FATAL: Net::HTTPClientException: 401 "Unauthorized" +``` + +To resolve this error, synchronize the clock with an NTP server. + +### All other 401 errors + +The general `Net::HTTPClientException: 401 "Unauthorized"` error will usually occur for one of two reasons. + +#### Troubleshooting steps + +1. Make sure your `client.pem` is valid. + + This can be fixed by deleting `client.pem` in `/etc/chef` and deleting the client and node with knife. + + On a management station: + + ```bash + # Dump the current node to JSON + knife node show NODE_NAME -fJ > NODE_NAME.json + + knife client delete FQDN -y + knife node delete FQDN -y + ``` + + On an affected node (as root): + + ```bash + rm /etc/chef/client.pem + chef-client + ``` + + When Chef Infra Client runs, it will register the API client and generate the correct key. + + After successfully running Chef Infra Client on the node, reload the `run_list` and node attributes: + + ```bash + knife node from file NODE_NAME.json + ``` + +2. Make sure to use the same `node_name` as the initial Chef Infra Client run. + + This can happen for several reasons. For example, if the + client.rb file doesn't specify the correct node name and the + system's hostname has changed. + + Running `chef-client -l debug` will identify the node name being + used by Chef Infra Client for authentication attempts: + + ```bash + DEBUG: Signing the request as SOME_NODE_NAME + ``` + + This can be fixed by explicitly setting `node_name` in the + client.rb file to match the name originally used to register. + + ```ruby + node_node 'mynode.mycompany.com' + ```` + + Alternatively, re-register the node using the method described + previously. + +## 403 Forbidden + +If you're seeing output like this: + +```bash +FATAL: Stacktrace dumped to /var/chef/cache/chef-stacktrace.out +FATAL: Net::HTTPClientException: 403 "Forbidden" +``` + +this is an indication that there is an issue with permissions on Chef Infra Server. + +### Troubleshooting steps + +In Chef, there are two different types of permissions issues, object specific and global permissions. To figure out which type of permission issue you're experiencing, run Chef Infra Client again using the `-l debug` options to see debugging output. + +You should see something like this up the stack trace: + +```bash +DEBUG: Sending HTTP Request to https://api.opscode.com/organizations/ORGNAME/nodes +ERROR: Running exception handlers +``` + +The URL will help identify the type of permission issue. If the URL is an index action (that's, operating on a collection of resources, like `/nodes`) then this is a global permission. If the URL is operating on an instance of a collection (`/nodes/NODENAME`) then this is an object permission issue. + +To fix the global permissions: + +1. Log in to the Chef management console and click on the failing object type (most likely **Nodes**). + +2. Click on the **Permissions** sub-tab. Which permission it needs, depends on which request that failed: + + GET - Under the group section, make sure it has the LIST permission checked POST - Under the group section, make sure it has the CREATE permission checked + +3. Check the checkboxes needed and save the updates. + +To fix object permissions: + +1. Log in to the Chef management console and click on the failing object type (most likely **Nodes**). + +2. Click on the object in the list that's causing the error. + +3. Click on the **Permissions** sub-tab. Which permission it needs, depends on the type of request that failed: + + GET - Make sure it has the READ permission checked PUT - Make sure it has the UPDATE permission checked DELETE - Make sure it has the DELETE permission checked + +4. Check the checkboxes needed and save the updates. + +## 500 (Unexpected) + +HTTP 500 is a non-specific error message. The full error message for the error Chef Infra Client is receiving can be found in one of the following log files: + +- `/var/log/opscode/opscode-account/current` +- `/var/log/opscode/opscode-erchef/current` + +The error will likely found in a stacktrace from the application error. In some cases the error message will clearly indicate a problem with another service which can be investigated further. For non-obvious errors, please contact Chef and attach the log files. + +## 502 / 504 (Gateway) + +Determine which API service is returning 504s using the Nginx access logs. API requests returning 504 can be found with the following command on a frontend: + +```bash +grep 'HTTP/1.1" 504' /var/log/opscode/nginx/access.log +``` + +The following will extract the URLs and sort them by `uniq` count: + +```bash +grep 'HTTP/1.1" 504' nginx-access.log | cut -d' ' -f8 | sort | uniq -c | sort +``` + +In a large installation, you may need to restrict this to a subset of the requests: + +```bash +tail -10000 nginx-access.log | grep 'HTTP/1.1" 504' | cut -d' ' -f8 | sort | uniq -c | sort +``` + +You can also use the `ntail` utility. + +If the problematic service is a Ruby-based service and the frontend machines have free RAM or CPU, consider increasing the number of worker processes. If the problematic service is **opscode-erchef**, use the request log to determine whether a particular component of requests is slow. + +## Workflow Problems + +In working with Chef, you'll most likely encounter issues in your regular workflow. This page is a collection of common errors our users have reported while working with Chef. Please use the accordion below to select the error message that most closely matches your output. If you are unable to find a matching error, or if the provided steps are unhelpful, please [file a help ticket](https://getchef.zendesk.com/hc/en-us). + +### No such file or directory + +If you're seeing an error like: + +```bash +Client key /etc/chef/client.pem isn'tresent - registering +WARN: Failed to read the private key /etc/che/validation.pem: # +FATAL: Stacktrace dumped to /etc/chef/cache/chef-stacktrace.out +FATAL: Chef::Exceptions::PrivateKeyMissing: I can't read /etc/chef/validation.pem, which you told me to use to sign requests +``` + +It means that Chef Infra Client couldn't find your validation.pem. + +#### Troubleshooting steps + +1. Make sure your `validation.pem` or `ORGANIZATION-validator.pem` is downloaded and accessible by the current user. +2. Make sure your client.rb points to the location of your validator pem. + +### Commit or stash your changes + +This isn't an error, but can be confusing to new users. When you try to install a cookbook with changes that you haven't committed to Git, you will get this error: + +```bash +Installing getting-started to /home/jes/chef-repo/.chef/../cookbooks +ERROR: You have uncommitted changes to your cookbook repo: + M cookbooks/getting-started/recipes/default.rb + ?? .chef/ + ?? log +Commit or stash your changes before importing cookbooks +``` + +#### Troubleshooting steps + +Solve this by committing the cookbook changes. For example, the following command would commit all new changes with a message. + +```bash +git commit -am "Updating so I can install a site cookbook" +``` + +Re-run the `knife supermarket install` subcommand again to install the community cookbook. + +### Can't find config file + +If you're seeing an error like: + +```bash +WARN: *************************************** +WARN: Can not find config file: /etc/chef/client.rb, using defaults. +WARN: No such file or directory - /etc/chef/client.rb +# ... output truncated ... # +FATAL: Chef::Exceptions::PrivateKeyMissing: I can't read /etc/chef/validation.pem, which you told me to use to sign requests! +``` + +#### Troubleshooting steps + +Work around this issue by supplying the full path to the client.rb file: + +```bash +chef-client -c /etc/chef/client.rb +``` + +### Pivotal.rb doesn't exist + +If you're seeing an error like: + +```bash +ERROR: CONFIGURATION ERROR:Specified config file /etc/opscode/pivotal.rb doesn't exist +``` + +#### Troubleshooting steps + +Run the following to restart all of the services: + +```bash +chef-server-ctl reconfigure +``` + +Because Chef Infra Server is composed of many different services that work together to create a functioning system, this step may take a few minutes to complete. + +## External PostgreSQL + +The following error messages may be present when configuring Chef Infra Server to use a remote PostgreSQL server. + +### CSPG001 (changed setting) + +#### Reason + +The value of `postgresql['external']` has been changed. + +#### Possible causes + +- This setting must be set before running + `chef-server-ctl reconfigure`, and may not be changed after + +{{< warning >}} + +Upgrading isn't supported at this time. + +{{< /warning >}} + +#### Resolution + +- Back up the data using `knife ec backup`, create a new backend instance, and then restore the data +- Re-point frontend machines at the new backend instance **or** assign the new backend instance the name/VIP of the old backend instance (including certificates and keys) + +### CSPG010 (can't connect) + +#### Reason + +Can't connect to PostgreSQL on the remote server. + +#### Possible causes + +- PostgreSQL isn't running on the remote server +- The port used by PostgreSQL is blocked by a firewall on the remote server +- Network routing configuration is preventing access to the host +- When using Amazon Web Services (AWS), rules for security groups are preventing Chef Infra Server from communicating with PostgreSQL + +### CSPG011 (can't authenticate) + +#### Reason + +Can't authenticate to PostgreSQL on the remote server. + +#### Possible causes + +- Incorrect password specified for `db_superuser_password` +- Incorrect user name specified for `db_superuser` + +### CSPG012 (incorrect rules) + +#### Reason + +Can't connect to PostgreSQL on the remote server because rules in +`pg_hba` are incorrect. + +#### Possible causes + +- No `pg_hba.conf` rule exists for the `db_superuser` in PostgreSQL +- A rule exists for the `db_superuser` in `pg_hba.conf`, but it doesn't specify `md5` access +- A rule in `pg_hba.conf` specifies an incorrect originating address + +#### Resolution + +Entries in the `pg_hba.conf` file should allow: + +- All user names that originate from any Chef Infra Server instance using `md5` authentication. +- A specific application names: `$db_superuser` (the configured superuser name in the chef-server.rb file), `oc_id`, `oc_id_ro`, `opscode_chef`, `opscode_chef_ro`, `bifrost`, and `bifrost_ro` + +##### pg_hba.conf User Names + +For example, a `pg_hba.conf` entry for a valid username and password from the 192.0.2.0 subnet: + +```bash +host postgres all 192.0.2.0/24 md5 +``` + +or, specific named users with a valid password originating from the 192.0.2.0 subnet. A file named `$PGDATA/chef_users` with the following content must be created: + +```bash +opscode_chef +opscode_chef_ro +bifrost +bifrost_ro +oc_id +oc_id_ro +``` + +where `CHEF-SUPERUSER-NAME` is replaced with the same user name specified by `postgresql['db_superuser']`. The corresponding `pg_hba.conf` entry is similar to: + +```bash +host postgres @chef_users 192.168.93.0/24 md5 +``` + +Or, using the same `$PGDATA/chef_users` file (from the previous example), the following example shows a way to limit connections to specific nodes that are running components of Chef Infra Server. This approach requires more maintenance because the `pg_hba.conf`file must be updated when machines are added to or removed from theChef Infra Server configuration. For example, a high availability configuration with four nodes: `backend-1` (192.0.2.100),`backend-2` (192.0.2.101), `frontend-1` (192.0.2.110), and`frontend-2` (192.0.2.111). + +The corresponding `pg_hba.conf` entry is similar to: + +```bash +host postgres @chef_users 192.0.2.100 md5 +host postgres @chef_users 192.0.2.101 md5 +host postgres @chef_users 192.0.2.110 md5 +host postgres @chef_users 192.0.2.111 md5 +``` + +These changes also require a configuration reload for PostgreSQL: + +```bash +pg_ctl reload +``` + +or: + +```bash +SELECT pg_reload_conf(); +``` + +##### pg_hba.conf Application names + +Rules in the `pg_hba.conf` file should allow only specific application names: + +- `$db_superuser` (the configured superuser name in the chef-server.rb file) +- `oc_id` +- `oc_id_ro` +- `opscode_chef` +- `opscode_chef_ro` +- `bifrost` +- `bifrost_ro` + +### CSPG013 (incorrect permissions) + +#### Reason + +The `db_superuser` account has incorrect permissions. + +#### Possible causes + +- The `db_superuser` account hasn't been granted `SUPERUSER` access + +- The `db_superuser` account hasn't been granted `CREATE DATABASE` and `CREATE ROLE` privileges + + ```bash + ALTER ROLE "$your_db_superuser_name" WITH SUPERUSER + ``` + + or: + + ```bash + ALTER ROLE "$your_db_superuser_name" WITH CREATEDB CREATEROLE + ``` + +### CSPG014 (incorrect version) + +#### Reason + +Bad version of PostgreSQL. + +#### Possible causes + +- The remote server isn't running PostgreSQL version 9.2.x + +### CSPG015 (missing database) + +#### Reason + +The database template `template1` doesn't exist. + +#### Possible causes + +- The `template1` database template has been removed from the remote + server + +#### Resolution + +- Run the following command (as a superuser): + + ```bash + CREATE DATABASE template1 TEMPLATE template0 + ``` + + or: + + ```bash + createdb -T template0 template1 + ``` + +### CSPG016 (database exists) + +#### Reason + +One (or more) of the PostgreSQL databases already exists. + +#### Possible causes + +- The `opscode_chef`, `oc_id`, and/or `bifrost` databases already exist on the remote machine +- The PostgreSQL database exists for another application + +#### Resolution + +- Verify that the `opscode_chef`, `oc_id`, and/or `bifrost` databases exist, and then verify that they're not being used by another internal application +- Back up the PostgreSQL data, remove the existing databases, and reconfigure the Chef Infra Server + +### CSPG017 (user exists) + +#### Reason + +One (or more) of the PostgreSQL predefined users already exists. + +#### Possible causes + +- The `opscode_chef`, `ospcode_chef_ro`, `bifrost`, `bifrost_ro`, `oc_id`, or `oc_id_ro` users already exist on the remote machine +- The `postgresql['vip']` setting is configured to a remote host, but `postgresql['external']` isn't set to `true`, which causes the `opscode_chef` and `ospcode_chef_ro` users to be created before the machine is reconfigured, which will return a permissions error +- Existing, valid naming conflicts are present, where the users were created independently of the Chef Infra Server + +#### Resolution + +- Run the following, if it's safe to do so, to update the user name that's specified in the error message: + + ```bash + DROP ROLE "name-of-user"; + ``` + + or change the name of the user by updating following settings in the chef-server.rb configuration file: + + ```ruby + oc_id['sql_user'] = 'alternative_username' + oc_id['sql_ro_user'] = 'alternative_username_for_ro_access' + opscode_erchef['sql_user'] = 'alternative_username' + opscode_erchef['sql_ro_user'] = 'alternative_username_for_ro_access' + oc_bifrost['sql_ro_user'] = 'alternative_username' + oc_bifrost['sql_ro_user'] = 'alternative_username_for_ro_access' + ``` diff --git a/content/workstation/_index.md b/content/workstation/_index.md deleted file mode 100644 index 2ce2f62..0000000 --- a/content/workstation/_index.md +++ /dev/null @@ -1,83 +0,0 @@ -+++ -title = "Chef Workstation 26 RC3" -linkTitle = "Workstation" - -[menu.workstation] -title = "Overview" -identifier = "workstation/overview" -parent = "workstation" -weight = 10 -+++ - -Chef Workstation 26 RC3 delivers a comprehensive, unified toolkit that empowers developers, operations teams, and system administrators to automate infrastructure management and compliance workflows. This release provides all essential tools required to efficiently build, test, and deploy infrastructure code, ensuring seamless configuration management across diverse environments. - -Chef Workstation represents a complete development environment for Chef, consolidating critical tools into a single, cohesive package that streamlines the infrastructure-as-code workflow from development through production deployment. - -## What's new in RC3 - -The RC3 release of Chef Workstation 26 represents a significant architectural evolution, featuring: - -- **Habitat-Based Architecture**: All core components have been migrated to Habitat packages, providing improved dependency management, isolation, and cross-platform consistency -- **Enhanced Knife Integration**: Full Habitat packaging of Knife and associated drivers, enabling more reliable plugin management and execution -- **InSpec Integration**: InSpec compliance and security testing framework is now included, providing comprehensive infrastructure and application auditing capabilities -- **Unified Package Distribution**: Consolidated delivery mechanism through Habitat, simplifying installation and updates across enterprise environments -- **Improved Tool Accessibility**: All included tools are accessible through standardized wrapper scripts for a consistent user experience - -This release builds upon the foundation established in Chef Workstation 26 RC2, with continued refinement of the Habitat-based packaging system and expanded tool support. - -This release builds upon the foundation established in RC2, with continued refinement of the Habitat-based packaging system and expanded tool support. - -## Included tools and components - -Chef Workstation RC3 includes the following fully integrated tools: - -### Core development tools - -- **Chef CLI (**`chef-cli`): Primary command-line interface for Chef development workflows, providing unified access to common Chef operations -- **Chef Infra Client RC3**: Latest release candidate of the Chef Infra Client, enabling infrastructure automation and configuration management -- **Knife**: Essential tool for interacting with Chef Infra Server, managing nodes, cookbooks, roles, and other Chef objects -- **InSpec**: Latest release candidate of InSpec 7, enabling compliance and security testing. - -### Testing and quality assurance - -- **Chef Test Kitchen Enterprise**: Comprehensive testing framework for validating infrastructure code across multiple platforms and environments -- **InSpec**: Compliance and security testing framework for auditing infrastructure and applications against security standards and regulations -- **Cookstyle**: Ruby and Chef cookbook linting tool that enforces style guidelines and best practices -- **Fauxhai**: Mock Ohai data generator for testing purposes, enabling rapid cookbook testing without requiring actual systems - -### Dependency and secret management - -- **Berkshelf**: Cookbook dependency manager that streamlines the process of managing and retrieving cookbook dependencies -- **Chef Vault**: Secure data management tool for encrypting and managing secrets within Chef workflows -- **Ohai**: System profiling tool that detects and reports system attributes for use in Chef recipes - -## Known limitations - -### `chef` command deprecation - -The legacy `chef` command is deprecated and isn't functional in this release. All users must transition to using `chef-cli` commands instead. This change aligns with Chef's strategic direction toward a more modular and maintainable command structure. - -```sh -# Deprecated (will not work) -chef generate cookbook my_cookbook - -# Correct usage -chef-cli generate cookbook my_cookbook -``` - -## Support and feedback - -As this is a release candidate, we actively encourage feedback from the community: - -- **Issues and Bugs**: Report issues through the official Chef GitHub repository -- **Feature Requests**: Submit enhancement requests through Chef's community forums -- **Documentation**: See the [Chef documentation](https://docs.chef.io) for comprehensive guides and tutorials -- **Community Support**: Join the [Chef Community Slack](https://community-slack.chef.io/) for real-time assistance - -## Additional resources - -- [Chef Workstation documentation](https://docs.chef.io/workstation/) -- [Chef Habitat documentation](https://docs.chef.io/habitat/) -- [Chef Infra Client documentation](https://docs.chef.io/chef_client_overview/) -- [Test Kitchen documentation](https://kitchen.ci/) -- [Cookstyle documentation](https://docs.chef.io/workstation/cookstyle/) diff --git a/content/workstation/configure.md b/content/workstation/configure.md deleted file mode 100644 index 924d596..0000000 --- a/content/workstation/configure.md +++ /dev/null @@ -1,86 +0,0 @@ -+++ -title = "Configure Chef Workstation and its components" - -[menu.workstation] -title = "Configure" -identifier = "workstation/config" -parent = "workstation" -weight = 30 -+++ - -This page describes how to configure Chef Workstation and Knife to connect to Chef Infra Server. - -## Configure Chef Workstation - -To configure Chef Workstation for your environment: - -```sh -chef-cli config -``` - -## Configure Knife - -Knife requires configuration to connect to Chef Infra Server. -You can configure Knife automatically or manually. - -### Configure Knife automatically - -To configure Knife to connect to Chef Infra Server: - -```sh -knife configure -``` - -This command prompts you for your Chef Infra Server credentials and creates the necessary configuration files. - -### Configure Knife manually - -To manually configure Knife to connect to Chef Infra Server: - -1. Create the `~/.chef/credentials` file: - - ```sh - mkdir -p ~/.chef - touch ~/.chef/credentials - ``` - -1. Add your Chef Infra Server credentials to the `~/.chef/credentials` file: - - ```toml - [default] - chef_server_url = "https://chef-server.example.com/organizations/org-name" - client_name = "username" - client_key = "~/.chef/certificate_file.pem" - ``` - - Replace the following: - - - `https://chef-server.example.com/organizations/org-name`: Your Chef Infra Server URL and organization name - - `username`: Your Chef Infra Server username - - `~/.chef/certificate_file.pem`: Path to your client certificate file - -## Configure self-signed certificates - -If you've configured Chef Infra Server with self-signed certificates, fetch and verify them: - -1. Fetch the Chef Infra Server SSL certificates: - - ```sh - knife ssl fetch - ``` - -1. Verify the certificates: - - ```sh - knife ssl check - ``` - -## Next step - -- [Add a Chef license](license) - -## More information - -- [Knife setup documentation](https://docs.chef.io/workstation/knife_setup/) -- [`knife ssl fetch` documentation](https://docs.chef.io/workstation/knife_ssl_fetch/) -- [`knife ssl check` documentation](https://docs.chef.io/workstation/knife_ssl_check/) diff --git a/content/workstation/install.md b/content/workstation/install.md deleted file mode 100644 index 420b6f2..0000000 --- a/content/workstation/install.md +++ /dev/null @@ -1,147 +0,0 @@ -+++ -title = "Install Chef Workstation and its components" - -[menu.workstation] -title = "Install" -identifier = "workstation/install" -parent = "workstation" -weight = 20 -+++ - -{{< readfile file="/content/reusable/md/workstation_modularize.md" >}} - -## System requirements - -Chef Workstation 26 RC3 has the following requirements: - -- Linux x86-64 (64-bit) systems only -- Chef Habitat 1.6.0 or later installed -- Minimum 2GB available disk space for installation -- Internet connectivity for package downloads (or access to internal Habitat Builder) - -## Prerequisites - -We use Chef Habitat to distribute and install Chef Workstation and its components. -See the following guides to install and configure Chef Habitat: - -- [Install Chef Habitat](https://docs.chef.io/habitat/install_habitat/) -- [Create a Chef Habitat Builder profile](https://docs.chef.io/habitat/builder_profile/) - -## Install Chef Workstation - -To install Chef Workstation, follow these steps: - -1. Install the Chef Workstation Habitat package: - - ```sh - sudo hab pkg install --binlink --force chef/chef-workstation --channel unstable - ``` - - - `--binlink`: Creates symbolic links in `/bin` for all included tools, making them accessible system-wide - - `--force`: Overwrites any existing binlinks from previous installations - - `--channel unstable`: Specifies the unstable channel where RC3 releases are published - - The installation process downloads the package and all dependencies, creates necessary binlinks, and configures the environment. - This may take several minutes depending on your network connection. - -1. Optional: Verify that Chef Workstation and its tools are installed: - - ```sh - chef-workstation -v - ``` - - Chef Workstation returns a list of installed packages and their versions. - -1. Optional: You can also verify each individual tool: - - ```sh - chef-cli --version - knife --version - kitchen --version - berks --version - cookstyle --version - ohai --version - chef-vault --version - inspec --version - ``` - -## Install Chef Workstation tools - -The following applications are included with Chef Workstation, -but they can be installed as standalone applications. - -Follow these instructions to install a Workstation tool. - -1. Install a package using [`hab pkg install`](https://docs.chef.io/habitat/habitat_cli/#hab-pkg-install): - - ```sh - sudo hab pkg install --channel unstable --binlink --force - ``` - - Replace `` with the package identifier: - - - `chef/berkshelf` - - `chef/chef-cli` - - `chef/chef-infra-client` - - `chef/chef-test-kitchen-enterprise` - - `chef/chef-vault` - - `chef/cookstyle` - - `chef/fauxhai` - - `chef/inspec` - - `chef/knife` - - `chef/ohai` - - The `--binlink --force` options overwrite any existing package symbolic links in the system's PATH directory with the new version so you can run it directly in the command line. - -1. Verify that the correct version runs: - - ```sh - berks -v - chef-cli -v - chef-client -v - chef-client -v - chef-vault - cookstyle -v - fauxhai -v - knife -v - ohai -v - ``` - -## Troubleshooting - -### Binlinks not found - -If commands aren't found after installation, verify that Chef Habitat created the binlinks: - -```sh -ls -la /bin | grep chef -``` - -If binlinks are missing, recreate them: - -```sh -sudo hab pkg binlink --force chef/chef-workstation -``` - -### Permission errors - -Ensure you're running installation commands with `sudo` for system-wide access. - -### Habitat channel issues - -If the package can't be found, verify channel availability: - -```sh -hab pkg search chef/chef-workstation --channel unstable -``` - -## Next step - -- [Configure Workstation](configure) -- [Add a license](license) - -## More information - -- [Chef Workstation documentation](https://docs.chef.io/workstation/) -- [Chef Habitat documentation](https://docs.chef.io/habitat/) -- [Upgrade Chef Workstation 26 RC3 and its components](upgrade) diff --git a/content/workstation/kitchen/_index.md b/content/workstation/kitchen/_index.md deleted file mode 100644 index 7636dbf..0000000 --- a/content/workstation/kitchen/_index.md +++ /dev/null @@ -1,41 +0,0 @@ -+++ -title = "Chef Test Kitchen Enterprise overview" -linkTitle = "Test Kitchen Enterprise" - -[menu.workstation] -title = "Overview" -identifier = "workstation/tke/overview" -parent = "workstation/tke" -weight = 10 -+++ - -Use Chef Test Kitchen Enterprise to automatically test cookbooks across any combination of platforms and test suites: - -- Test suites are defined in a kitchen.yml file. See the configuration documentation for options and syntax information. -- Supports cookbook testing across many cloud providers and virtualization technologies. -- Uses a comprehensive set of operating system base images from Chef's Bento project. - -The key concepts in Test Kitchen Enterprise are: - -- **Platform**: The operating system or target environment where a cookbook is tested. -- **Suite**: The Chef Infra Client configuration, including a Policyfile or run-list, and optionally, node attributes. -- **Instance**: The combination of a specific platform and suite, each with an autogenerated name. -- **Driver**: Manages the lifecycle actions for an instance, such as creating the instance, converging it (installing Chef Infra Client, uploading cookbooks, running Chef Infra Client, etc.), setting up testing, verifying suites post-converge, and destroying the instance. -- **Provisioner**: The component that runs the Chef Infra Client code, using either chef-zero or chef-solo with the chef_zero and chef_solo provisioners, respectively. - -## What's the difference between Test Kitchen and Chef Test Kitchen Enterprise? - -We forked the community version Test Kitchen and rebranded it as Chef Test Kitchen Enterprise starting with version 1.0.0. -The repository for Test Kitchen Enterprise is [chef/chef-test-kitchen-enterprise](https://github.com/chef/chef-test-kitchen-enterprise). - -This update focuses on branding changes and supports passing licenses to Chef Infra Client 19. These changes are only in Chef Test Kitchen Enterprise and aren't backported to the community version of Test Kitchen. - -The way you run Test Kitchen Enterprise remains unchanged. The [community Test Kitchen documentation](https://kitchen.ci/docs/getting-started/introduction/) and [Chef-hosted Test Kitchen documentation](https://docs.chef.io/workstation/kitchen/) are still accurate. - -We plan to add more drivers and features, which Chef will support, to Chef Test Kitchen Enterprise in future releases. - -{{< note >}} - -The only supported driver in Chef Infra Client 19 RC3 is the kitchen-dokken driver. - -{{< /note >}} diff --git a/content/workstation/kitchen/install.md b/content/workstation/kitchen/install.md deleted file mode 100644 index bef2b3b..0000000 --- a/content/workstation/kitchen/install.md +++ /dev/null @@ -1,56 +0,0 @@ -+++ -title = "Install Chef Test Kitchen Enterprise" - -[menu.workstation] -title = "Install Test Kitchen Enterprise" -identifier = "workstation/tke/install" -parent = "workstation/tke" -weight = 20 -+++ - -Chef Test Kitchen Enterprise is a component of Chef Workstation. -However, you can also install it as a standalone application or install a different version than the one bundled with Workstation. - -## Supported platforms - -Chef Test Kitchen Enterprise is supported on Linux x86-64 systems. - -## Install - -If you haven't already installed Chef Habitat, follow these steps to install and set it up. -For more information, see the [Chef Habitat install documentation](https://docs.chef.io/habitat/install_habitat/). - -1. Download and install Chef Habitat: - - ```sh - curl https://raw.githubusercontent.com/habitat-sh/habitat/main/components/hab/install.sh | sudo bash -s -- -c stable - ``` - -1. Verify Chef Habitat is installed. - - ```sh - hab --version - ``` - - Chef Habitat returns the installed version. - -1. Use Chef Habitat to install the Chef Test Kitchen Enterprise package: - - ```sh - sudo hab pkg install --binlink --force chef/chef-test-kitchen-enterprise --channel unstable - ``` - - Chef Habitat downloads and installs Chef Test Kitchen Enterprise, it's components, and the `chef-cli` and `kitchen` CLI tools. - -1. Verify these tools are installed: - - ```sh - chef-cli --version - kitchen --version - ``` - - You can also verify that the Test Kitchen Enterprise package is installed in `/hab/pkgs/chef/chef-test-kitchen-enterprise/1.0.5`. - -## Next steps - -After you've installed Chef Test Kitchen Enterprise, add your [Progress Chef license](/workstation/license). diff --git a/content/workstation/kitchen/run.md b/content/workstation/kitchen/run.md deleted file mode 100644 index 5d60ba2..0000000 --- a/content/workstation/kitchen/run.md +++ /dev/null @@ -1,68 +0,0 @@ -+++ -title = "Run Test Kitchen" -linkTitle = "Using Test Kitchen" - -[menu.workstation] -title = "Run Test Kitchen" -identifier = "workstation/tke/using_test_kitchen" -parent = "workstation/tke" -weight = 40 -+++ - -For the Chef Infra Client RC3 release, Chef Test Kitchen Enterprise only supports the kitchen-dokken driver. -This allows us to create containers, using Podman or Docker Desktop, of various realistic operating systems and configure Chef Infra Client 19 for converge and verify operations. -By default, this driver uses the chef/chef-hab container volume from Docker Hub to attach the Chef Infra Client 19 and Chef InSpec 7 (the default verifier) to the test container. - -## Example `kitchen.yaml` for Chef Infra Client 19 - -The following `kitchen.yaml` file example defines tests that run in Chef Infra Client 19: - -```yaml ---- -driver: - name: dokken - privileged: true - chef_version: unstable - -provisioner: - name: dokken - -transport: - name: dokken - -verifier: - name: inspec - -platforms: - - name: ubuntu-20.04 - - name: centos-8 - -suites: - - name: default - run_list: - - "cookbook" - verifier: - inspec_tests: - - test/integration/default -``` - -## Provision earlier versions of Chef Infra Client - -To provision containers to use Chef Infra Client version 18 or earlier, modify the driver configuration in the `kitchen.yml` file as shown below. -Set `chef_image` to `chef/chef` and set the version of Infra Client in `chef_version`. - -```yaml -driver: - name: dokken - privileged: true - chef_version: 18.3.0 - chef_image: "chef/chef" -``` - -## Run converge and verify tests - -The [Test Kitchen documentation](https://kitchen.ci/docs/getting-started/creating-cookbook/) describes the process for creating converge and verify tests. The Dokken driver documentation is in the [kitchen-dokken GitHub repository](https://github.com/chef/kitchen-dokken). - -## Habitat-based changes - -The Chef Infra Client 19 will be accessible using Habitat instead of the public Omnitruck APIs. Consequently, we've updated the provisioner to facilitate the installation of the Habitat-based Chef Infra Client, including passing through the license required from `kitchen.yml` file. diff --git a/content/workstation/knife/_index.md b/content/workstation/knife/_index.md deleted file mode 100644 index 102b374..0000000 --- a/content/workstation/knife/_index.md +++ /dev/null @@ -1,103 +0,0 @@ -+++ -title = "About Knife" -linkTitle = "Knife" - -[menu.workstation] -title = "About Knife" -identifier = "workstation/knife/about" -parent = "workstation/knife" -weight = 10 -+++ - -Knife 19, now integrated into Chef Workstation 26 RC3, represents a significant milestone in Chef's migration to Habitat-based packaging. -As the essential command-line interface for Chef Infra Server interactions, Knife 19 is completely repackaged as a Habitat package, providing enhanced dependency management, improved plugin architecture, and streamlined distribution across enterprise environments. - -This release delivers critical functionality for node management, cookbook operations, and infrastructure bootstrapping while maintaining full compatibility with existing Chef Infra Server deployments. -Knife 19 serves as the primary interface for Chef practitioners to manage their infrastructure-as-code workflows efficiently. - -## What's new in RC3 - -The RC3 release of Knife 19 introduces several architectural and functional enhancements: - -### Habitat-based architecture - -- Knife is packaged independently as a Habitat package for improved modularity and dependency isolation -- Clean separation of dependencies ensures consistent execution across different environments -- Ruby gem-based plugins integrate seamlessly within the Habitat package structure - -### Chef Infra Client 19 bootstrap support - -- Native support for Chef Infra Client 19 Enterprise Edition (`chef-ice`) as the default bootstrap product -- Purpose-built installation scripts optimized for RC3 pre-release deployment scenarios -- Secure package distribution through pre-signed URLs for controlled access to release candidate packages -- Unified bootstrap workflow supporting both Linux and Windows target nodes - -### Plugin ecosystem enhancement - -- Validated plugins for major cloud providers (AWS, GCP) and Windows environments -- Framework prepared for additional cloud provider plugins in upcoming releases -- Existing knife workflows remain fully functional with enhanced underlying infrastructure - -## What's the difference between Knife and Knife 19? - -Knife 19 is a major architectural update that migrates from traditional packaging to Habitat-based distribution. -This update focuses on improved dependency management and enhanced plugin architecture for enterprise environments. - -Key changes in Knife 19: - -- Knife 19 is released as a Habitat package for better modularity and dependency isolation -- Enhanced plugin management with better cloud provider support -- Optimized for enterprise deployment scenarios with improved security - -The way you use Knife remains largely unchanged. Existing knife commands and workflows continue to work with the enhanced underlying infrastructure. - -## Knife commands reference - -Knife 19 supports all the standard knife subcommands for managing Chef infrastructure. - -For bootstrapping nodes with Knife 19 and Chef Infra Client 19 RC3, see the [Knife 19 bootstrap documentation](bootstrap). - -For a complete reference of all available knife subcommands, syntax, and options, see the [Chef Workstation Knife documentation](https://docs.chef.io/workstation/knife/#knife-subcommands) - -## Supported cloud provider plugins - -Knife 19 includes plugins for major cloud providers to automate node provisioning and management: - -### knife-ec2 (Amazon Web Services) - -Manage EC2 instances directly from the knife command line: - -- Create and bootstrap EC2 instances with Chef Infra Client -- Configure security groups and networking settings -- Apply AWS resource tags for compliance and cost tracking -- Support for multiple AWS regions and instance types - -### knife-google (Google Cloud Platform) - -Provision and manage Google Compute Engine instances: - -- Create instances across GCP projects and zones -- Support for custom and public machine images -- Configure VPC networks and firewall rules -- Integrate with GCP resource hierarchies - -### knife-windows (Windows Management) - -Manage Windows nodes using WinRM protocol: - -- Bootstrap Windows servers with Chef Infra Client -- Execute PowerShell commands remotely -- Manage Chef Infra Client service on Windows systems -- Support for Active Directory domain-joined systems - -{{< note >}} - -The `knife windows cert install` command has a known limitation where it may fail to import `.pfx` certificates with the error `CertUtil: The requested operation is not supported.` - -{{< /note >}} - -## More information - -- [Knife 19 RC3 bootstrap documentation](bootstrap) -- [Chef Infra Client 18.x bootstrap documentation](https://docs.chef.io/install_bootstrap/) -- [Knife CLI documentation](https://docs.chef.io/workstation/knife/) diff --git a/content/workstation/knife/bootstrap.md b/content/workstation/knife/bootstrap.md deleted file mode 100644 index 78132e9..0000000 --- a/content/workstation/knife/bootstrap.md +++ /dev/null @@ -1,246 +0,0 @@ -+++ -title = "Bootstrap nodes with Knife" - -[menu.workstation] -title = "Bootstrap nodes" -identifier = "workstation/knife/bootstrap" -parent = "workstation/knife" -weight = 40 -+++ - - - -Bootstrapping installs Chef Infra Client on a target system and configures it to communicate with a Chef Infra Server. - -## Prerequisites - -Before bootstrapping nodes: - -- [Configure Knife 19](/workstation/configure/#configure-knife) -- For Chef Infra Client 18 or earlier, [configure your Progress Chef license with Knife](/workstation/license) - -Before bootstrapping Windows nodes with WinRM: - -- Enable and configure Windows Remote Management (WinRM): - - ```powershell - winrm quickconfig -q - ``` - -- Set the execution policy to allow remote script execution: - - ```powershell - Enable-PSRemoting -Force - ``` - -- Configure Windows Firewall to allow WinRM traffic on port 5985 (HTTP) or 5986 (HTTPS) - -## Bootstrap Chef Infra Client 19 RC3 on Linux - -To bootstrap Chef Infra Client 19 RC3 on a Linux node, run the following command: - -```sh -knife bootstrap \ - -U \ - -p \ - -N \ - --sudo \ - --bootstrap-url "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/workstation/install.sh?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=IDDVNrOTeKZnc%2Bxa9611MkK%2BZ2o%3D&Expires=1780533412" -``` - -Replace the following: - -- `` with the node's IP address -- `` with the SSH username -- `` with the SSH password -- `` with a unique node name - -The `--bootstrap-url` parameter installs a prerelease version of Chef Infra Client that's distributed through pre-signed URLs. - -## Bootstrap Chef Infra Client 19 RC3 on Windows - -To bootstrap Chef Infra Client 19 RC3 on a Windows node, run the following command: - -```powershell -knife bootstrap \ - -o winrm \ - -U \ - -P \ - -N \ - --winrm-port \ - --bootstrap-url "https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/workstation/install.ps1?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=4hQ0Ve5Rcd63oHZyTI7r%2FX9KltA%3D&Expires=1780533421" -``` - -Replace the following: - -- `` with the IP address of the Windows node -- `` with the WinRM username -- `` with the WinRM password -- `` with the Chef node name -- `` with the WinRM communication port (default: `5985`) - -To use HTTPS for WinRM on port 5986, use the `--winrm-ssl` option. - -## Bootstrap Chef Infra Client 18 - -To bootstrap Chef Infra Client 18.x, run the following command: - -```sh -knife bootstrap \ - -U \ - -p \ - -N \ - --sudo \ - --bootstrap-product chef -``` - -Replace the following: - -- `` with the node's IP address -- `` with the SSH username -- `` with the SSH password -- `` with a unique node name - -The `--bootstrap-product chef` option directs Knife to use Chef Infra Client 18.x from standard download channels. - -## Bootstrap an AWS EC2 instance - -The Knife EC2 plugin integrates with AWS EC2 to create and provision EC2 instances. - -To create an EC2 instance and bootstrap Chef Infra Client, run the following command: - -```sh -knife ec2 server create \ - --sudo \ - -I \ - --ssh-key \ - -f \ - -N \ - -U \ - --ssh-identity-file ~/.ssh/ \ - -g \ - --region \ - --subnet \ - --aws-tag = - --bootstrap-url "" -``` - -Replace the following: - -- `` with the Amazon Machine Image ID for the EC2 instance, for example, `ami-0c02fb55956c7d316` -- `` with the Name of your AWS SSH key pair -- `` with the Instance type specification, for example, `t3.medium`, `m5.xlarge`, or `c5.4xlarge` -- `` with the Chef Infra node name for identification within Chef Infra Server -- `` with the SSH username for the selected AMI, for example, `ec2-user`, `ubuntu`, or `centos` -- `` with the Path to SSH private key for authentication -- `` with the Security group ID for network access control, for example, `sg-0a1b2c3d4e5f67890` -- `` with the AWS region for instance deployment, for example, `us-east-1` or `eu-west-1` -- `` with the VPC subnet ID for network placement, for example, `subnet-0123456789abcdef0` -- `=` with the Resource tags for AWS compliance and management (repeatable). For example, `environment=production` -- `` with the RC3 installation script URL: - - For Windows nodes: - - ```text - https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/workstation/install.ps1?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=4hQ0Ve5Rcd63oHZyTI7r%2FX9KltA%3D&Expires=1780533421 - ``` - - For Linux nodes: - - ```text - https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/workstation/install.sh?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=IDDVNrOTeKZnc%2Bxa9611MkK%2BZ2o%3D&Expires=1780533412 - ``` - -## Bootstrap a GCP Compute Engine instance - -The knife-google plugin integrates with GCP Compute Engine to create and provision GCP instances. - -To create a GCP instance and bootstrap Chef Infra Client: - -```sh -knife google server create \ - --gce-project \ - --gce-zone \ - --gce-machine-type \ - --gce-image \ - --gce-image-project \ - --image-os-type \ - --connection-user \ - --ssh-identity-file ~/.ssh/ \ - --connection-port 22 \ - --connection-protocol \ - --gce-network \ - --gce-subnet \ - --gce-tags ,, \ - --bootstrap-url "" -``` - -Replace the following: - -- `` with the Name for the GCP instance -- `` with the Google Cloud project ID -- `` with the GCP availability zone, for example, `us-central1-a` or `europe-west1-b` -- `` with the Instance machine type, for example, `e2-standard-4` or `n1-highmem-8` -- `` with the Operating system image name, for example, `ubuntu-2204-jammy-v20251102` -- `` with the Source project containing the OS image, for example, `ubuntu-os-cloud` or `centos-cloud` -- `` with the Operating system type: `linux` or `windows` -- `` with the SSH username -- `` with the Filename of your SSH private key -- `` with the Communication protocol: `ssh` or `winrm` -- `` with the VPC network name -- `` with the Subnet name within the VPC -- `,,` with the Comma-separated instance tags for organization and firewall rules (optional) -- `` with the Installation script URL: - - For Windows nodes: - - ```text - https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/workstation/install.ps1?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=4hQ0Ve5Rcd63oHZyTI7r%2FX9KltA%3D&Expires=1780533421 - ``` - - For Linux nodes: - - ```text - https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/workstation/install.sh?AWSAccessKeyId=AKIAW4FPVFT6PA6EXTHQ&Signature=IDDVNrOTeKZnc%2Bxa9611MkK%2BZ2o%3D&Expires=1780533412 - ``` - -## Bootstrap Chef Infra Client 19 in an air-gapped environment - -You can bootstrap Chef Infra Client 19 in an air-gapped environment. -The following are example steps for modifying the install scripts in an air-gapped environment. - -1. On an internet-connected computer, download the Chef Infra Client 19 installation scripts and save them to an internal repository that's accessible to your target nodes. For example: - - ```sh - wget https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/workstation/install.sh \ - -O /var/www/internal-repo/chef/rc3/install.sh - - wget https://chef-hab-migration-tool-bucket.s3.amazonaws.com/Release-Candidate-3/workstation/install.ps1 \ - -O /var/www/internal-repo/chef/rc3/install.ps1 - ``` - -1. Modify the installation scripts to reference your internal package locations. For example: - - ```sh - sed -i 's|https://chef-hab-migration-tool-bucket.s3.amazonaws.com|https://internal-repo.example.com|g' \ - /var/www/internal-repo/chef/rc3/install.sh - - sed -i 's|https://chef-hab-migration-tool-bucket.s3.amazonaws.com|https://internal-repo.example.com|g' \ - /var/www/internal-repo/chef/rc3/install.ps1 - ``` - -1. Bootstrap Chef Infra Client 19 using the `--bootstrap-url` parameter to point to your internal resources: - - ```sh - knife bootstrap \ - -U \ - -p \ - -N \ - --sudo \ - --bootstrap-url "https://internal-repo.example.com/chef/rc3/install.sh" - ``` - -## More information - -- [Chef Infra Client 18.x bootstrap documentation](https://docs.chef.io/install_bootstrap/) -- [Knife CLI documentation](https://docs.chef.io/workstation/knife/) diff --git a/content/workstation/knife/install.md b/content/workstation/knife/install.md deleted file mode 100644 index 5aad303..0000000 --- a/content/workstation/knife/install.md +++ /dev/null @@ -1,45 +0,0 @@ -+++ -title = "Install Knife 19" - -[menu.workstation] -title = "Install" -identifier = "workstation/knife/install" -parent = "workstation/knife" -weight = 20 -+++ - -Knife 19 is included as a component of Chef Workstation 26 RC3, but you can also install it as a standalone package. -The Knife standalone installation doesn't include the Knife cloud provider plugins (knife-ec2, knife-google, knife-windows). -For that reason, Progress Chef recommends installing Chef Workstation, which includes Knife and the Knife cloud provider plugins. - -If you want to install Knife 19 as a standalone component, follow the steps below. - -## Requirements - -Knife 19 has the following requirements: - -- Supported on Linux (Ubuntu 18.04+, CentOS 7+, RHEL 7+), macOS 10.15+, or Windows 10/Server 2016+ -- Chef Habitat 1.6.0 or later installed -- Internet connectivity for package download and bootstrapping remote nodes -- SSH or WinRM to manage remote nodes - -## Install the Knife standalone package - -To install the Knife 19 standalone package, follow these steps: - -1. Install Knife 19: - - ```sh - sudo hab pkg install chef/knife --channel unstable --binlink --force - ``` - -1. Optional: After installation, verify Knife 19 is installed and working: - - ```sh - knife --version - ``` - -## Next steps - -- [Configure Knife](/workstation/configure/#configure-knife) -- [Add a license](/workstation/license) diff --git a/content/workstation/knife/troubleshooting.md b/content/workstation/knife/troubleshooting.md deleted file mode 100644 index 50bb6cf..0000000 --- a/content/workstation/knife/troubleshooting.md +++ /dev/null @@ -1,100 +0,0 @@ -+++ -title = "Knife troubleshooting" - -[menu.workstation] -title = "Troubleshooting" -identifier = "workstation/knife/troubleshooting" -parent = "workstation/knife" -weight = 100 -+++ - -This page provides solutions to common issues you may encounter when using Knife. - -## Permission errors during installation - -If you encounter permission errors during installation, change the ownership of Habitat directories to your user account: - -```sh -sudo chown -R $(whoami) /hab -``` - -## Missing plugins after standalone installation - -If you installed Knife as a standalone application, it doesn't include Knife cloud provider plugins (knife-ec2, knife-google, or knife-windows). - -To get the Knife plugins, install Chef Workstation, which includes Knife and the Knife plugins. - -## SSL certificate errors - -If you encounter SSL certificate errors, you can resolve them in the following ways: - -### Skip SSL verification in development - -In a development environment, you can skip SSL verification. - -To skip SSL verification globally, add the following to your `~/.chef/config.rb` file: - -```sh -echo "ssl_verify_mode :verify_none" >> ~/.chef/config.rb -``` - -To skip SSL verification for a single bootstrap operation, use the `--node-ssl-verify-mode none` option: - -```sh -knife bootstrap --node-ssl-verify-mode none -``` - -Replace `` with the IP address of the target node. - -### Fetch and verify Chef Infra Server certificates - -To fetch and verify the Chef Infra Server certificates: - -```sh -knife ssl fetch && knife ssl check -``` - -## Bootstrap operation times out - -If a bootstrap operation times out, increase the timeout value using the `--session-timeout` option: - -```sh -knife bootstrap --session-timeout 300 -``` - -Replace the following: - -- ``: IP address of the target node -- `300`: Timeout value in seconds (adjust as needed) - -## SSH key permission errors - -If you encounter SSH key permission errors, fix the key permissions: - -```sh -chmod 600 ~/.ssh/ -``` - -Replace `` with the name of your SSH key file, for example, `certificate.pem`. - -## WinRM connection failures - -If WinRM connections fail, test WinRM connectivity from your workstation: - -```powershell -winrs -r:http://:5985 -u: -p: cmd -``` - -Replace the following: - -- ``: Hostname or IP address of the Windows server -- ``: Administrator username -- ``: Administrator password - -If the connection test fails, verify that: - -- WinRM is enabled on the target Windows server -- Windows Firewall allows WinRM traffic on port 5985 (HTTP) or 5986 (HTTPS) -- The credentials are correct and have administrative privileges - -For more information on configuring WinRM, see [Bootstrap prerequisites](bootstrap#prerequisites). diff --git a/content/workstation/license.md b/content/workstation/license.md deleted file mode 100644 index d482411..0000000 --- a/content/workstation/license.md +++ /dev/null @@ -1,209 +0,0 @@ -+++ -title = "License Chef Workstation" - -[menu.workstation] -title = "License" -identifier = "workstation/license" -parent = "workstation" -weight = 30 -+++ - -Chef Workstation requires a valid Progress Chef license for certain operations. -This page describes licensing requirements and how to configure a license for Chef Workstation components. - -## Licensing requirements - -Different Chef Workstation components have different licensing requirements: - -- **Knife 19**: Requires a license for bootstrapping Chef Infra Client 18 and earlier -- **Test Kitchen Enterprise**: Uses a license to execute tests but doesn't enforce licensing - -## Get a license - -You can use any license that includes Chef Workstation entitlement. -This includes free, trial, or commercial licenses. - -To get a license, visit the [Progress Chef community portal](https://community.progress.com/s/products/chef). - -For more information, see the [Chef licensing documentation](https://docs.chef.io/licensing/). - -## Add a license to Workstation - -If you've set a license for Chef Workstation, Test Kitchen Enterprise and Knife 19 automatically read and use it to execute tests or during bootstrap operations. - -You can apply a license to Chef Workstation in two ways: - -- Set the license key in an environment variable -- Save the license key in the `licenses.yml` file - -### Set the license as an environment variable - -To configure the license key in your shell: - -```bash -export CHEF_LICENSE_KEY="" -``` - -Replace `` with your license key. - -### Save the license in the `licenses.yml` file - -You can add your license to the `~/.chef/licenses.yml` file. For example: - -```yaml ---- -:file_format_version: 4.0.0 -:licenses: -- :license_key: - :license_type: :free - :update_time: '2024-10-23T15:02:53+05:30' - :license_server_url: https://services.chef.io/licensing -``` - -Replace `` with your license key. - -## Add a license to Test Kitchen Enterprise - -Test Kitchen Enterprise doesn't enforce licensing, but it uses a license to execute tests. - -### How Test Kitchen Enterprise uses licenses - -During the converge phase, Test Kitchen Enterprise transfers the license to the virtual machine (VM) and adds it as an argument to Chef Infra Client. -Chef Infra Client validates the license and saves it on the provisioned VM for future use. - -During the verification phase, the kitchen-inspec plugin transmits the license to Chef InSpec, which validates it with Chef's licensing service. - -Chef Infra Client 19 and Chef InSpec 7 support optional licensing. -Test Kitchen Enterprise can prompt you for a license, activate it, and store it securely on disk. -The license can also be transmitted to the provisioned VM during the verification phase. - -### Add a license - -Test Kitchen Enterprise automatically reads a license that's configured for Chef Workstation through: - -- The `~/.chef/licenses.yml` file -- The `CHEF_LICENSE_KEY` environment variable - -You can also configure a license specifically for Test Kitchen Enterprise with: - -- The `kitchen.yml` configuration file -- The `test-kitchen` CLI - -#### Add a license with the kitchen.yml file - -To include the license in your `kitchen.yml` file: - -```yaml -provisioner: - name: chef_infra - product_name: chef - chef_license: accept-no-persist - chef_license_key: -``` - -Replace `` with your license key. - -The `chef_license` setting indicates acceptance of the [End User License Agreement](https://docs.chef.io/licensing/accept/#chef-workstation). - -#### Add a license using the CLI - -To add a license using the `test-kitchen` CLI: - -1. Run the license command: - - ```sh - sudo kitchen license - ``` - -1. At the first prompt, select **I already have a license ID**. - -1. Enter your license key at the second prompt. - - Test Kitchen Enterprise validates the license and saves it to disk. - -#### Verify your Test Kitchen Enterprise license - -To verify that a valid license is saved on disk: - -```sh -kitchen license -``` - -This command verifies that a license exists on disk, validates it with the licensing server, and displays the license details. -If there isn't a valid license, it prompts you to activate one. - -To display details of all licenses stored on disk: - -```sh -kitchen license list -``` - -## Add a license to Knife - -Knife 19 requires a license for bootstrapping Chef Infra Client 18 and earlier. -Chef Infra Client 19 RC3 doesn't require a license because it's distributed through pre-signed URLs. - -### How Knife uses licenses - -During bootstrap operations, Knife transfers the license to the target node and adds it as an argument to Chef Infra Client. -Chef Infra Client validates the license and saves it on the provisioned node for future use. - -### Add a license - -Knife automatically reads a license that's configured locally for Chef Workstation through: - -- The `~/.chef/licenses.yml` file -- The `CHEF_LICENSE_KEY` environment variable - -You can also configure a license specifically for Knife with: - -- The `knife license` CLI command -- The `--chef-license-key` command line option - -#### Add a license using the CLI - -To add a license using the `knife license` CLI: - -1. Run the license command: - - ```bash - knife license - ``` - -1. At the first prompt, select **I already have a license ID**. - -1. Enter your license key at the second prompt. - -Knife validates the license and saves it to disk. - -##### Verify your Knife license - -To verify that a valid license is saved on disk: - -```bash -knife license -``` - -This command verifies that a license exists on disk, validates it with the licensing server, and displays the license details. -If there isn't a valid license, it prompts you to activate one. - -To display details of all licenses stored on disk: - -```bash -knife license list -``` - -#### Add a license key with a command line option - -When bootstrapping a node, you can save the license key and pass it to Chef Infra Client with the `--chef-license-key` command line option. For example: - -```sh -knife bootrap \ - --chef-license-key - ... -``` - -## More information - -- [Chef licensing documentation](https://docs.chef.io/licensing/). -- [Progress Chef community portal](https://community.progress.com/s/products/chef) diff --git a/content/workstation/uninstall.md b/content/workstation/uninstall.md deleted file mode 100644 index 68f048a..0000000 --- a/content/workstation/uninstall.md +++ /dev/null @@ -1,52 +0,0 @@ -+++ -title = "Uninstall Chef Workstation and its tools" - -[menu.workstation] -title = "Uninstall" -identifier = "workstation/uninstall" -parent = "workstation" -weight = 50 -+++ - -The page documents how to uninstall Chef Workstation and its component tools. - -## Uninstall Chef Workstation - -To uninstall Chef Workstation, use the [`hab pkg uninstall`](https://docs.chef.io/habitat/habitat_cli/#hab-pkg-uninstall) command: - -```sh -sudo hab pkg uninstall chef/chef-workstation -``` - -## Uninstall Chef Workstation component packages - -To uninstall a Workstation tool, use the [`hab pkg uninstall`](https://docs.chef.io/habitat/habitat_cli/#hab-pkg-uninstall) command: - -```sh -sudo hab pkg uninstall -``` - -Replace `` with one of the following packages: - -- `chef/berkshelf` -- `chef/chef-cli` -- `chef/chef-infra-client` -- `chef/chef-test-kitchen-enterprise` -- `chef/chef-vault` -- `chef/cookstyle` -- `chef/fauxhai` -- `chef/knife` -- `chef/ohai` - -## Uninstall a specific package version - -You can uninstall a specific package version. For example: - -```sh -sudo hab pkg uninstall -``` - -Replace `` with one of the following: - -- the package and version, for example `chef//`. -- the package version and build, for example `chef///` diff --git a/content/workstation/upgrade.md b/content/workstation/upgrade.md deleted file mode 100644 index 0ba4a3d..0000000 --- a/content/workstation/upgrade.md +++ /dev/null @@ -1,42 +0,0 @@ -+++ -title = "Upgrade Chef Workstation and its components" - -[menu.workstation] -title = "Upgrade" -identifier = "workstation/upgrade" -parent = "workstation" -weight = 40 -+++ - -Use the following command to upgrade Chef Workstation or one of its components: - -```sh -sudo hab pkg install --binlink --force --channel unstable -``` - -Replace `` with the package identifier. - -To update to the latest version, specify the origin and package: - -- `chef/chef-workstation` -- `chef/berkshelf` -- `chef/chef-cli` -- `chef/chef-infra-client` -- `chef/chef-test-kitchen-enterprise` -- `chef/chef-vault` -- `chef/cookstyle` -- `chef/fauxhai` -- `chef/knife` -- `chef/ohai` - -To update to a specific package version, include the version. For example: - -- `chef//` - -To update to specific release build, include the package version and build timestamp. For example: - -- `chef//` - -The `--binlink --force` options overwrite existing package symbolic links in the system's PATH directory with the new version so you can run it directly in the command line. - -If you omit `--binlink --force`, Chef Habitat installs the new version alongside existing versions. To execute this version, you'd have to invoke the package's file path, for example `/hab/bin/hab pkg exec chef/ `. diff --git a/data/infra/resources/alternatives.yaml b/data/infra/resources/alternatives.yaml new file mode 100644 index 0000000..d72c961 --- /dev/null +++ b/data/infra/resources/alternatives.yaml @@ -0,0 +1,115 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: alternatives +resource_description_list: +- markdown: Use the **alternatives** resource to configure command alternatives in + Linux using the alternatives or update-alternatives packages. +resource_new_in: '16.0' +syntax_full_code_block: |- + alternatives 'name' do + link String # default value: "/usr/bin/LINK_NAME" + link_name String # default value: 'name' unless specified + path String + priority String, Integer + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`alternatives` 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." +- "`link`, `link_name`, `path`, and `priority` are the properties available to this + resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :install: + markdown: Install an alternative on the system including symlinks. (default) + :set: + markdown: Set the symlink for an alternative. + :remove: + markdown: Remove an alternative and all associated links. + :auto: + markdown: Set an alternative up in automatic mode with the highest priority automatically + selected. + :refresh: + markdown: Refresh alternatives. +properties_list: +- property: link + ruby_type: String + required: false + default_value: "/usr/bin/LINK_NAME" + description_list: + - markdown: The path to the alternatives link. +- property: link_name + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: The name of the link to create. This will be the command you type on + the command line such as `ruby` or `gcc`. +- property: path + ruby_type: String + required: false + description_list: + - markdown: The absolute path to the original application binary such as `/usr/bin/ruby27`. +- property: priority + ruby_type: String, Integer + required: false + description_list: + - markdown: The priority of the alternative. +target_mode: + support: full +examples: | + **Install an alternative**: + + ```ruby + alternatives 'python install 2' do + link_name 'python' + path '/usr/bin/python2.7' + priority 100 + action :install + end + ``` + + **Set an alternative**: + + ```ruby + alternatives 'python set version 3' do + link_name 'python' + path '/usr/bin/python3' + action :set + end + ``` + + **Set the automatic alternative state**: + + ```ruby + alternatives 'python auto' do + link_name 'python' + action :auto + end + ``` + + **Refresh an alternative**: + + ```ruby + alternatives 'python refresh' do + link_name 'python' + action :refresh + end + ``` + + **Remove an alternative**: + + ```ruby + alternatives 'python remove' do + link_name 'python' + path '/usr/bin/python3' + action :remove + end + ``` diff --git a/data/infra/resources/apt_package.yaml b/data/infra/resources/apt_package.yaml new file mode 100644 index 0000000..b6cef95 --- /dev/null +++ b/data/infra/resources/apt_package.yaml @@ -0,0 +1,181 @@ +--- +resource_reference: true +multi_package_resource: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: apt_package +resource_description_list: +- markdown: Use the **apt_package** resource to manage packages on Debian, Ubuntu, + and other platforms that use the APT package system. +- notes_resource_based_on_package: true +syntax_description: | + An **apt_package** resource block manages a package on a node, + typically by installing it. The simplest use of the **apt_package** resource is: + + ```ruby + apt_package 'package_name' + ``` + + 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 + end +syntax_properties_list: +syntax_full_properties_list: +- "`apt_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." +- "`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 + :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: Change the installed package. + :lock: + markdown: Locks the apt package to a specific version. + :unlock: + markdown: Unlocks the apt package so that it can be upgraded to a newer version. +properties_list: +- property: anchor_package_regex + ruby_type: true, false + required: false + default_value: 'false' + new_in: '18.3' + description_list: + - 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 + description_list: + - markdown: 'The default release. For example: `stable`.' +- 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: options + ruby_type: String, Array + required: false + description_list: + - markdown: 'One (or more) additional options that are passed to the command. For + example, common apt-get directives, such as `--no-install-recommends`. See the [apt-get man page](http://manpages.ubuntu.com/manpages/jammy/en/man8/apt-get.8.html) + for the full list.' +- property: overwrite_config_files + ruby_type: true, false + required: false + default_value: 'false' + new_in: '14.0' + description_list: + - markdown: Overwrite existing configuration files with those supplied by the package, + if prompted by APT. +- property: package_name + ruby_type: String, Array + required: false + description_list: + - markdown: An optional property to set the package name if it differs from the + resource block's name. +- property: response_file + ruby_type: String + required: false + description_list: + - markdown: The direct path to the file used to pre-seed a package. +- property: response_file_variables + ruby_type: Hash + required: false + 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 + description_list: + - markdown: The amount of time (in seconds) to wait before timing out. +- property: version + ruby_type: String, Array + 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**: + + ```ruby + apt_package 'name of package' do + action :install + end + ``` + + **Install a package without specifying the default action**: + + ```ruby + apt_package 'name of package' + ``` + + **Install multiple packages at once**: + + ```ruby + apt_package %w(package1 package2 package3) + ``` + + **Install without using recommend packages as a dependency**: + + ```ruby + package 'apache2' do + options '--no-install-recommends' + end + ``` + + **Prevent the apt_package resource from installing packages with pattern matching names**: + + By default, the apt_package resource will install the named package. + If it can't find a package with the exact same name, it will treat the package name as regular expression string and match with any package that matches that regular expression. + This may lead Chef Infra Client to install one or more packages with names that match that regular expression. + + In this example, `anchor_package_regex true` prevents the apt_package resource from installing matching packages if it can't find the `lua5.3` package. + + ```ruby + apt_package 'lua5.3' do + version '5.3.3-1.1ubuntu2' + anchor_package_regex true + end + ``` diff --git a/data/infra/resources/apt_preference.yaml b/data/infra/resources/apt_preference.yaml new file mode 100644 index 0000000..091c4a9 --- /dev/null +++ b/data/infra/resources/apt_preference.yaml @@ -0,0 +1,90 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: apt_preference +resource_description_list: +- markdown: Use the **apt_preference** resource to create APT [preference files](https://wiki.debian.org/AptPreferences). + Preference files are used to control which package versions and sources are prioritized + during installation. +resource_new_in: '13.3' +syntax_full_code_block: |- + apt_preference 'name' do + glob String + package_name String # default value: 'name' unless specified + pin String + pin_priority String, Integer + action Symbol # defaults to :add if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`apt_preference` 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." +- "`glob`, `package_name`, `pin`, and `pin_priority` are the properties available + to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :add: + markdown: Creates a preferences file under `/etc/apt/preferences.d`. (default) + :remove: + markdown: Removes the preferences file, thus unpinning the package. +properties_list: +- property: glob + ruby_type: String + required: false + description_list: + - markdown: Pin by a `glob()` expression or with a regular expression surrounded + by `/`. +- property: package_name + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the package name if it differs from the + resource block's name. +- property: pin + ruby_type: String + required: true + description_list: + - markdown: The package version or repository to pin. +- property: pin_priority + ruby_type: String, Integer + required: true + 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**: + + ```ruby + apt_preference 'libmysqlclient16' do + pin 'version 5.1.49-3' + pin_priority '700' + end + ``` + + Note: The `pin_priority` of `700` ensures that this version will be preferred over any other available versions. + + **Unpin a libmysqlclient16**: + + ```ruby + apt_preference 'libmysqlclient16' do + action :remove + end + ``` + + **Pin all packages to prefer the packages.dotdeb.org repository**: + + ```ruby + apt_preference 'dotdeb' do + glob '*' + pin 'origin packages.dotdeb.org' + pin_priority '700' + end + ``` diff --git a/data/infra/resources/apt_repository.yaml b/data/infra/resources/apt_repository.yaml new file mode 100644 index 0000000..bf31807 --- /dev/null +++ b/data/infra/resources/apt_repository.yaml @@ -0,0 +1,223 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: apt_repository +resource_description_list: +- markdown: Use the **apt_repository** resource to specify additional APT repositories. + Adding a new repository will update the APT package cache immediately. +resource_new_in: '12.9' +syntax_full_code_block: |- + apt_repository 'name' do + arch String, false + cache_rebuild true, false # default value: true + components Array # default value: `main` if using a PPA repository. + cookbook String, false + deb_src true, false # default value: false + distribution String, false # default value: The LSB codename of the node such as 'focal'. + key String, Array, false # default value: [] + key_proxy String, false + keyserver String, false # default value: "keyserver.ubuntu.com" + options String, Array # default value: [] + repo_name String # default value: 'name' unless specified + signed_by String, true, false # default value: true + trusted true, false # default value: false + uri String + action Symbol # defaults to :add if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`apt_repository` 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." +- "`arch`, `cache_rebuild`, `components`, `cookbook`, `deb_src`, `distribution`, `key`, + `key_proxy`, `keyserver`, `options`, `repo_name`, `signed_by`, `trusted`, and `uri` + are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :add: + markdown: Creates a repository file at `/etc/apt/sources.list.d/` and builds the + repository listing. (default) + :remove: + markdown: Removes the repository listing. +properties_list: +- property: arch + ruby_type: String, false + required: false + description_list: + - markdown: Constrain packages to a particular CPU architecture such as `i386` or + `amd64`. +- property: cache_rebuild + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Determines whether to rebuild the APT package cache. +- property: components + ruby_type: Array + required: false + default_value: "`main` if using a PPA repository." + description_list: + - markdown: Package groupings, such as 'main' and 'stable'. +- property: cookbook + ruby_type: String, false + required: false + description_list: + - markdown: If key should be a cookbook_file, specify a cookbook where the key is + located for files/default. Default value is nil, so it will use the cookbook + where the resource is used. +- property: deb_src + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Determines whether or not to add the repository as a source repo as + well. +- property: distribution + ruby_type: String, false + required: false + default_value: The LSB codename of the node such as 'focal'. + description_list: + - markdown: Usually a distribution's codename, such as `xenial`, `bionic`, or `focal`. +- property: key + ruby_type: String, Array, false + required: false + default_value: "[]" + description_list: + - markdown: If a keyserver is provided, this is assumed to be the fingerprint; otherwise + it can be either the URI of GPG key for the repo, or a cookbook_file. +- property: key_proxy + ruby_type: String, false + required: false + description_list: + - markdown: If set, a specified proxy is passed to GPG via `http-proxy=`. +- property: keyserver + ruby_type: String, false + required: false + default_value: keyserver.ubuntu.com + description_list: + - markdown: The GPG keyserver where the key for the repo should be retrieved. +- property: options + ruby_type: String, Array + required: false + default_value: "[]" + description_list: + - markdown: Additional options to set for the repository +- property: repo_name + ruby_type: String + required: false + default_value: The resource block's name + new_in: '14.1' + description_list: + - markdown: An optional property to set the repository name if it differs from the + resource block's name. The value of this setting must not contain spaces. +- property: signed_by + ruby_type: String, true, false + required: false + default_value: 'true' + description_list: + - markdown: If set to true, Signed-By authenticates with the value of the key property. + If set to a string that's a file path or fingerprint, Signed-By authenticates + with that file or fingerprint. +- property: trusted + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Determines whether you should treat all packages from this repository + as authenticated regardless of signature. +- property: uri + ruby_type: String + required: false + description_list: + - markdown: The base of the Debian distribution. +target_mode: + support: full +examples: | + **Add repository with basic settings**: + + ```ruby + apt_repository 'nginx' do + uri 'http://nginx.org/packages/ubuntu/' + components ['nginx'] + end + ``` + + **Enable Ubuntu multiverse repositories**: + + ```ruby + apt_repository 'security-ubuntu-multiverse' do + uri 'http://security.ubuntu.com/ubuntu' + distribution 'xenial-security' + components ['multiverse'] + deb_src true + end + ``` + + **Add the Nginx PPA, autodetect the key and repository url**: + + ```ruby + apt_repository 'nginx-php' do + uri 'ppa:nginx/stable' + end + ``` + + **Add the JuJu PPA, grab the key from the Ubuntu keyserver, and add source repo**: + + ```ruby + apt_repository 'juju' do + uri 'ppa:juju/stable' + components ['main'] + distribution 'xenial' + key 'C8068B11' + action :add + deb_src true + end + ``` + + **Add repository that requires multiple keys to authenticate packages**: + + ```ruby + apt_repository 'rundeck' do + uri 'https://dl.bintray.com/rundeck/rundeck-deb' + distribution '/' + key ['379CE192D401AB61', 'http://rundeck.org/keys/BUILD-GPG-KEY-Rundeck.org.key'] + keyserver 'keyserver.ubuntu.com' + action :add + end + ``` + + **Add the Cloudera Repo of CDH4 packages for Ubuntu 16.04 on AMD64**: + + ```ruby + apt_repository 'cloudera' do + uri 'http://archive.cloudera.com/cdh4/ubuntu/xenial/amd64/cdh' + arch 'amd64' + distribution 'xenial-cdh4' + components ['contrib'] + key 'http://archive.cloudera.com/debian/archive.key' + end + ``` + + **Add repository that needs custom options**: + ```ruby + apt_repository 'corretto' do + uri 'https://apt.corretto.aws' + arch 'amd64' + distribution 'stable' + components ['main'] + options ['target-=Contents-deb'] + key 'https://apt.corretto.aws/corretto.key' + end + ``` + + **Remove a repository from the list**: + + ```ruby + apt_repository 'zenoss' do + action :remove + end + ``` diff --git a/data/infra/resources/apt_update.yaml b/data/infra/resources/apt_update.yaml new file mode 100644 index 0000000..31d8b0f --- /dev/null +++ b/data/infra/resources/apt_update.yaml @@ -0,0 +1,56 @@ +--- +resource_reference: true +nameless_apt_update: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: apt_update +resource_description_list: +- markdown: Use the **apt_update** resource to manage APT repository updates on Debian + and Ubuntu platforms. +resource_new_in: '12.7' +syntax_full_code_block: |- + apt_update 'name' do + frequency Integer # default value: 86400 + action Symbol # defaults to :periodic if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`apt_update` 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." +- "`frequency` is the property available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :periodic: + markdown: Update the Apt repository at the interval specified by the `frequency` + property. (default) + :update: + markdown: Update the Apt repository at the start of a Chef Infra Client run. +properties_list: +- property: frequency + ruby_type: Integer + required: false + default_value: '86400' + 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**: + + ```ruby + apt_update 'all platforms' do + frequency 86400 + action :periodic + end + ``` + + **Update the Apt repository at the start of a Chef Infra Client run**: + + ```ruby + apt_update 'update' + ``` diff --git a/data/infra/resources/archive_file.yaml b/data/infra/resources/archive_file.yaml new file mode 100644 index 0000000..7f53825 --- /dev/null +++ b/data/infra/resources/archive_file.yaml @@ -0,0 +1,117 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: archive_file +resource_description_list: +- markdown: Use the **archive_file** resource to extract archive files to disk. This + resource uses the libarchive library to extract multiple archive formats including + tar, gzip, bzip, and zip formats. +resource_new_in: '15.0' +syntax_full_code_block: |- + archive_file 'name' do + destination String + group String + mode String, Integer # default value: "'755'" + options Array, Symbol + overwrite true, false, auto # default value: false + owner String + path String # default value: 'name' unless specified + strip_components Integer # default value: 0 + action Symbol # defaults to :extract if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`archive_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." +- "`destination`, `group`, `mode`, `options`, `overwrite`, `owner`, `path`, and `strip_components` + are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :extract: + markdown: Extract and archive file. (default) +properties_list: +- property: destination + ruby_type: String + required: true + description_list: + - markdown: The file path to extract the archive file to. +- property: group + ruby_type: String + required: false + description_list: + - markdown: The group of the extracted files. +- property: mode + ruby_type: String, Integer + required: false + default_value: "'755'" + description_list: + - markdown: The mode of the extracted files. Integer values are deprecated as octal + values (ex. 0755) would not be interpreted correctly. +- property: options + ruby_type: Array, Symbol + required: false + default_value: lazy default + description_list: + - markdown: 'An array of symbols representing extraction flags. Example: `:no_overwrite` + to prevent overwriting files on disk. By default, this properly sets `:time` + which preserves the modification timestamps of files in the archive when writing + them to disk.' +- property: overwrite + ruby_type: true, false, auto + required: false + default_value: 'false' + description_list: + - markdown: Should the resource overwrite the destination file contents if they + already exist? If set to `:auto` the date stamp of files within the archive + will be compared to those on disk and disk contents will be overwritten if they + differ. This may cause unintended consequences if disk date stamps are changed + between runs, which will result in the files being overwritten during each client + run. Make sure to properly test any change to this property. +- property: owner + ruby_type: String + required: false + description_list: + - markdown: The owner of the extracted files. +- property: path + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the file path to the archive to extract + if it differs from the resource block's name. +- property: strip_components + ruby_type: Integer + required: false + default_value: '0' + new_in: '17.5' + description_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**: + + ```ruby + archive_file 'Precompiled.zip' do + path '/tmp/Precompiled.zip' + destination '/srv/files' + end + ``` + + **Set specific permissions on the extracted files**: + + ```ruby + archive_file 'Precompiled.zip' do + owner 'tsmith' + group 'staff' + mode '700' + path '/tmp/Precompiled.zip' + destination '/srv/files' + end + ``` diff --git a/data/infra/resources/bash.yaml b/data/infra/resources/bash.yaml new file mode 100644 index 0000000..9a2e415 --- /dev/null +++ b/data/infra/resources/bash.yaml @@ -0,0 +1,321 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: bash +resource_description_list: +- markdown: Use the **bash** resource to execute scripts using the Bash interpreter. + This resource may also use any of the actions and properties that are available + to the **execute** resource. Commands that are executed with this resource are + (by their nature) not idempotent, as they are typically unique to the environment + in which they are run. Use `not_if` and `only_if` to guard this resource for idempotence. +syntax_full_code_block: |- + bash '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 + user String, Integer + action Symbol # defaults to :run if not specified + end +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." +- "`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 + description_list: + - markdown: Prevent a command from creating a file when that file already exists. +- property: cwd + ruby_type: String + 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 + description_list: + - 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: 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 + 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: 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: user + ruby_type: String, Integer + required: false + description_list: + - 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: | + **Compile an application** + + ```ruby + bash 'install_something' do + user 'root' + cwd '/tmp' + code <<-EOH + wget http://www.example.com/tarball.tar.gz + tar -zxf tarball.tar.gz + cd tarball + ./configure + make + make install + EOH + end + ``` + + **Using escape characters in a string of code** + + In the following example, the `find` command uses an escape character (`\`). Use a second escape character (`\\`) to preserve the escape character in the code string: + + ```ruby + bash 'delete some archives ' do + code <<-EOH + find ./ -name "*.tar.Z" -mtime +180 -exec rm -f {} \\; + EOH + ignore_failure true + end + ``` + + **Install a file from a remote location** + + The following is an example of how to install the foo123 module for Nginx. This module adds shell-style functionality to an Nginx configuration file and does the following: + + - Declares three variables + - Gets the Nginx file from a remote location + - Installs the file using Bash to the path specified by the `src_filepath` variable + + ```ruby + src_filename = "foo123-nginx-module-v#{node['nginx']['foo123']['version']}.tar.gz" + src_filepath = "#{Chef::Config['file_cache_path']}/#{src_filename}" + extract_path = "#{Chef::Config['file_cache_path']}/nginx_foo123_module/#{node['nginx']['foo123']['checksum']}" + + remote_file 'src_filepath' do + source node['nginx']['foo123']['url'] + checksum node['nginx']['foo123']['checksum'] + owner 'root' + group 'root' + mode '0755' + end + + bash 'extract_module' do + cwd ::File.dirname(src_filepath) + code <<-EOH + mkdir -p #{extract_path} + tar xzf #{src_filename} -C #{extract_path} + mv #{extract_path}/*/* #{extract_path}/ + EOH + not_if { ::File.exist?(extract_path) } + end + ``` + + **Install an application from git** + + ```ruby + 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 "#{Chef::Config[:file_cache_path]}/ruby-build" + user 'rbenv' + group 'rbenv' + code <<-EOH + ./install.sh + EOH + environment 'PREFIX' => '/usr/local' + end + ``` + + **Using Attributes in Bash Code** + + The following recipe shows how an attributes file can be used to store certain settings. An attributes file is located in the `attributes/`` directory in the same cookbook as the recipe which calls the attributes file. In this example, the attributes file specifies certain settings for Python that are then used across all nodes against which this recipe will run. + + Python packages have versions, installation directories, URLs, and checksum files. An attributes file that exists to support this type of recipe would include settings like the following: + + ```ruby + default['python']['version'] = '2.7.1' + + if python['install_method'] == 'package' + default['python']['prefix_dir'] = '/usr' + else + default['python']['prefix_dir'] = '/usr/local' + end + + default['python']['url'] = 'http://www.python.org/ftp/python' + default['python']['checksum'] = '80e387...85fd61' + ``` + + and then the methods in the recipe may refer to these values. A recipe that is used to install Python will need to do the following: + + - Identify each package to be installed (implied in this example, not shown) + - Define variables for the package `version` and the `install_path` + - Get the package from a remote location, but only if the package does not already exist on the target system + - Use the **bash** resource to install the package on the node, but only when the package is not already installed + + ```ruby + version = node['python']['version'] + install_path = "#{node['python']['prefix_dir']}/lib/python#{version.split(/(^\d+\.\d+)/)[1]}" + + remote_file "#{Chef::Config[:file_cache_path]}/Python-#{version}.tar.bz2" do + source "#{node['python']['url']}/#{version}/Python-#{version}.tar.bz2" + checksum node['python']['checksum'] + mode '0755' + not_if { ::File.exist?(install_path) } + end + + bash 'build-and-install-python' do + cwd Chef::Config[:file_cache_path] + code <<-EOF + tar -jxvf Python-#{version}.tar.bz2 + (cd Python-#{version} && ./configure #{configure_options}) + (cd Python-#{version} && make && make install) + EOF + not_if { ::File.exist?(install_path) } + end + ``` diff --git a/data/infra/resources/batch.yaml b/data/infra/resources/batch.yaml new file mode 100644 index 0000000..19a16ce --- /dev/null +++ b/data/infra/resources/batch.yaml @@ -0,0 +1,239 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: batch +resource_description_list: +- markdown: Use the **batch** resource to execute a batch script using the cmd.exe + interpreter on Windows. The batch resource creates and executes a temporary file + (similar to how the script resource behaves), rather than running the command + inline. Commands that are executed with this resource are (by their nature) not + idempotent, as they are typically unique to the environment in which they are + run. Use `not_if` and `only_if` to guard this resource for idempotence. +syntax_full_code_block: |- + batch '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 + user String, Integer + action Symbol # defaults to :run if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`batch` 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." +- "`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 + description_list: + - markdown: Prevent a command from creating a file when that file already exists. +- property: cwd + ruby_type: String + 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 + description_list: + - 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: 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 + 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: 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: user + ruby_type: String, Integer + required: false + description_list: + - 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. `domainuser` or `user@subdomain.dns.example.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 attribute. + On Windows only, if this property is specified, the password property must be specified.' +- property: password + ruby_type: String + required: false + 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: domain + ruby_type: String + required: false + description_list: + - markdown: '*Windows only*: The domain of the user specified by the `user` property. + 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 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.' +examples: " + Unzip a file, and then move it\n\n To run a batch file that unzips\ + \ and then moves Ruby, do something like:\n\n ```ruby\n batch 'unzip_and_move_ruby'\ + \ do\n code <<-EOH\n 7z.exe x #{Chef::Config[:file_cache_path]}/ruby-1.8.7-p352-i386-mingw32.7z\n\ + \ -oC:\\\\source -r -y\n xcopy C:\\\\source\\\\ruby-1.8.7-p352-i386-mingw32\ + \ C:\\\\ruby /e /y\n EOH\n end\n\n batch 'echo some env vars' do\n code\ + \ <<-EOH\n echo %TEMP%\n echo %SYSTEMDRIVE%\n echo %PATH%\n \ + \ echo %WINDIR%\n EOH\n end\n ```\n\n or:\n\n ```ruby\n batch 'unzip_and_move_ruby'\ + \ do\n code <<-EOH\n 7z.exe x #{Chef::Config[:file_cache_path]}/ruby-1.8.7-p352-i386-mingw32.7z\n\ + \ -oC:\\\\source -r -y\n xcopy C:\\\\source\\\\ruby-1.8.7-p352-i386-mingw32\ + \ C:\\\\ruby /e /y\n EOH\n end\n\n batch 'echo some env vars' do\n code\ + \ 'echo %TEMP%\\\\necho %SYSTEMDRIVE%\\\\necho %PATH%\\\\necho %WINDIR%'\n end\n\ + \ ```\n\n Run a command as an alternate user\n\n *Note*: When Chef is running\ + \ as a service, this feature requires that\n the user that Chef runs as has 'SeAssignPrimaryTokenPrivilege'\ + \ (aka\n 'SE_ASSIGNPRIMARYTOKEN_NAME') user right. By default only LocalSystem\n\ + \ and NetworkService have this right when running as a service. This is\n necessary\ + \ even if the user is an Administrator.\n\n This right can be added and checked\ + \ in a recipe using this example:\n\n ```ruby\n # Add 'SeAssignPrimaryTokenPrivilege'\ + \ for the user\n Chef::ReservedNames::Win32::Security.add_account_right('',\ + \ 'SeAssignPrimaryTokenPrivilege')\n\n # Check if the user has 'SeAssignPrimaryTokenPrivilege'\ + \ rights\n Chef::ReservedNames::Win32::Security.get_account_right('').include?('SeAssignPrimaryTokenPrivilege')\n\ + \ ```\n\n The following example shows how to run `mkdir test_dir` from a Chef\n\ + \ Infra Client run as an alternate user.\n\n ```ruby\n # Passing only username\ + \ and password\n batch 'mkdir test_dir' do\n code \"mkdir test_dir\"\n cwd\ + \ Chef::Config[:file_cache_path]\n user \"username\"\n password \"password\"\ + \n end\n\n # Passing username and domain\n batch 'mkdir test_dir' do\n code\ + \ \"mkdir test_dir\"\n cwd Chef::Config[:file_cache_path]\n domain \"domain\"\ + \n user \"username\"\n password \"password\"\n end\n\n # Passing username\ + \ = 'domain-name\\\\username'. No domain is passed\n batch 'mkdir test_dir' do\n\ + \ code \"mkdir test_dir\"\n cwd Chef::Config[:file_cache_path]\n user \"domain-name\\\ + \\username\"\n password \"password\"\n end\n\n # Passing username = 'username@domain-name'.\ + \ No domain is passed\n batch 'mkdir test_dir' do\n code \"mkdir test_dir\"\n\ + \ cwd Chef::Config[:file_cache_path]\n user \"username@domain-name\"\n password\ + \ \"password\"\n end\n ```\n" + diff --git a/data/infra/resources/bff_package.yaml b/data/infra/resources/bff_package.yaml new file mode 100644 index 0000000..2980198 --- /dev/null +++ b/data/infra/resources/bff_package.yaml @@ -0,0 +1,109 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: bff_package +resource_description_list: +- markdown: Use the **bff_package** resource to manage packages for the AIX platform + using the installp utility. When a package is installed from a local file, it + must be added to the node using the **remote_file** or **cookbook_file** resources. +- note: + markdown: A Backup File Format (BFF) package may not have a `.bff` file extension. + 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 + timeout String, Integer + version String + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`bff_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: 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 + description_list: + - markdown: One (or more) additional command options that are passed to the command. +- property: package_name + ruby_type: String + required: false + description_list: + - 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: The optional path to a package on the local file system. +- property: timeout + ruby_type: String, Integer + required: false + description_list: + - markdown: The amount of time (in seconds) to wait before timing out. +- property: version + ruby_type: String + 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. + + **Installing using the base package resource** + + ```ruby + package 'xlccmp.13.1.0' do + source '/var/tmp/IBM_XL_C_13.1.0/usr/sys/inst.images/xlccmp.13.1.0' + action :install + end + ``` + + **Installing using the bff_package resource** + + ```ruby + bff_package 'xlccmp.13.1.0' do + source '/var/tmp/IBM_XL_C_13.1.0/usr/sys/inst.images/xlccmp.13.1.0' + action :install + end + ``` diff --git a/data/infra/resources/breakpoint.yaml b/data/infra/resources/breakpoint.yaml new file mode 100644 index 0000000..6cf4522 --- /dev/null +++ b/data/infra/resources/breakpoint.yaml @@ -0,0 +1,87 @@ +--- +resource_reference: true +debug_recipes_chef_shell: true +resource: breakpoint +resource_description_list: +- markdown: Use the **breakpoint** resource to add breakpoints to recipes. Run the + chef-shell in Chef Infra Client mode, and then use those breakpoints to debug + recipes. Breakpoints are ignored by the chef-client during an actual chef-client + run. That said, breakpoints are typically used to debug recipes only when running + them in a non-production environment, after which they are removed from those + recipes before the parent cookbook is uploaded to the Chef server. +resource_new_in: '12.0' +syntax_full_code_block: |- + breakpoint 'name' do + action Symbol # defaults to :break if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`breakpoint` 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." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :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** + + ```ruby + yum_key node['yum']['elrepo']['key'] do + url node['yum']['elrepo']['key_url'] + action :add + end + + yum_repository 'elrepo' do + description 'ELRepo.org Community Enterprise Linux Extras Repository' + key node['yum']['elrepo']['key'] + mirrorlist node['yum']['elrepo']['url'] + includepkgs node['yum']['elrepo']['includepkgs'] + exclude node['yum']['elrepo']['exclude'] + action :create + end + ``` + + **The same recipe with breakpoints** + + In the following example, the name of each breakpoint is an arbitrary string. + + ```ruby + breakpoint "before yum_key node['yum']['repo_name']['key']" do + action :break + end + + yum_key node['yum']['repo_name']['key'] do + url node['yum']['repo_name']['key_url'] + action :add + end + + breakpoint "after yum_key node['yum']['repo_name']['key']" do + action :break + end + + breakpoint "before yum_repository 'repo_name'" do + action :break + end + + yum_repository 'repo_name' do + description 'description' + key node['yum']['repo_name']['key'] + mirrorlist node['yum']['repo_name']['url'] + includepkgs node['yum']['repo_name']['includepkgs'] + exclude node['yum']['repo_name']['exclude'] + action :create + end + + breakpoint "after yum_repository 'repo_name'" do + action :break + end + ``` + + In the previous examples, the names are used to indicate if the breakpoint is before or after a resource and also to specify which resource it is before or after. diff --git a/data/infra/resources/build_essential.yaml b/data/infra/resources/build_essential.yaml new file mode 100644 index 0000000..f13ca10 --- /dev/null +++ b/data/infra/resources/build_essential.yaml @@ -0,0 +1,62 @@ +--- +resource_reference: true +nameless_build_essential: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: build_essential +resource_description_list: +- markdown: Use the **build_essential** resource to install the packages required + for compiling C software from source. +resource_new_in: '14.0' +syntax_full_code_block: |- + build_essential 'name' do + raise_if_unsupported true, false # default value: false + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`build_essential` 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." +- "`raise_if_unsupported` is the property available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :install: + markdown: Install build essential packages. (default) + :upgrade: + markdown: Upgrade the Xcode CLI Tools on macOS hosts. **New in Chef Infra Client + 16** +properties_list: +- property: raise_if_unsupported + ruby_type: true, false + required: false + default_value: 'false' + new_in: '15.5' + description_list: + - markdown: Raise a hard error on platforms where this resource is unsupported. +target_mode: +examples: | + **Install compilation packages**: + + ```ruby + build_essential + ``` + + **Install compilation packages during the compilation phase**: + + ```ruby + build_essential 'Install compilation tools' do + compile_time true + end + ``` + + **Upgrade compilation packages on macOS systems**: + + ```ruby + build_essential 'Install compilation tools' do + action :upgrade + end + ``` diff --git a/data/infra/resources/cab_package.yaml b/data/infra/resources/cab_package.yaml new file mode 100644 index 0000000..1b9c353 --- /dev/null +++ b/data/infra/resources/cab_package.yaml @@ -0,0 +1,111 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: cab_package +resource_description_list: +- markdown: Use the **cab_package** resource to install or remove Microsoft Windows + cabinet (.cab) packages. +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. + timeout String, Integer + version String + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`cab_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: 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 + description_list: + - markdown: One (or more) additional command options that are passed to the command. +- property: package_name + ruby_type: String + required: false + description_list: + - 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 + default_value: The package name. + description_list: + - markdown: The local file path or URL for the CAB package. +- property: timeout + ruby_type: String, Integer + required: false + description_list: + - markdown: The amount of time (in seconds) to wait before timing out. +- property: version + ruby_type: String + required: false + description_list: + - markdown: The version of a package to be installed or upgraded. +target_mode: +examples: | + **Using local path in source** + + ```ruby + cab_package 'Install .NET 3.5 sp1 via KB958488' do + source 'C:\Users\xyz\AppData\Local\Temp\Windows6.1-KB958488-x64.cab' + action :install + end + + cab_package 'Remove .NET 3.5 sp1 via KB958488' do + source 'C:\Users\xyz\AppData\Local\Temp\Windows6.1-KB958488-x64.cab' + action :remove + end + ``` + + **Using URL in source** + + ```ruby + cab_package 'Install .NET 3.5 sp1 via KB958488' do + source 'https://s3.amazonaws.com/my_bucket/Windows6.1-KB958488-x64.cab' + action :install + end + + cab_package 'Remove .NET 3.5 sp1 via KB958488' do + source 'https://s3.amazonaws.com/my_bucket/Temp\Windows6.1-KB958488-x64.cab' + action :remove + end + ``` diff --git a/data/infra/resources/chef_client_config.yaml b/data/infra/resources/chef_client_config.yaml new file mode 100644 index 0000000..b98fcde --- /dev/null +++ b/data/infra/resources/chef_client_config.yaml @@ -0,0 +1,389 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: chef_client_config +resource_description_list: +- markdown: Use the **chef_client_config** resource to create a client.rb file in + the Chef Infra Client configuration directory. See the [client.rb docs](https://docs.chef.io/config_rb_client/) + for more details on options available in the client.rb configuration file. +resource_new_in: '16.6' +syntax_full_code_block: |- + chef_client_config 'name' do + additional_config String + chef_license String + chef_server_url String + config_directory String + data_collector_server_url String + data_collector_token String + event_loggers Array # default value: [] + exception_handlers Array # default value: [] + file_backup_path String + file_cache_path String + file_staging_uses_destdir String + formatters Array # default value: [] + ftp_proxy String + group String + http_proxy String + https_proxy String + log_level Symbol + log_location String, Symbol + minimal_ohai true, false # default value: false + named_run_list String + no_proxy String, Array # default value: [] + node_name String + ohai_disabled_plugins Array # default value: [] + ohai_optional_plugins Array # default value: [] + pid_file String + policy_group String + policy_name String + policy_persist_run_list true, false # default value: false + report_handlers Array # default value: [] + rubygems_url String, Array + ssl_verify_mode Symbol, String + start_handlers Array # default value: [] + user String + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`chef_client_config` 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." +- "`additional_config`, `chef_license`, `chef_server_url`, `config_directory`, `data_collector_server_url`, + `data_collector_token`, `event_loggers`, `exception_handlers`, `file_backup_path`, + `file_cache_path`, `file_staging_uses_destdir`, `formatters`, `ftp_proxy`, `group`, + `http_proxy`, `https_proxy`, `log_level`, `log_location`, `minimal_ohai`, `named_run_list`, + `no_proxy`, `node_name`, `ohai_disabled_plugins`, `ohai_optional_plugins`, `pid_file`, + `policy_group`, `policy_name`, `policy_persist_run_list`, `report_handlers`, `rubygems_url`, + `ssl_verify_mode`, `start_handlers`, and `user` are the properties available to + this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Create a client.rb config file and folders for configuring Chef Infra + Client. (default) + :remove: + markdown: Remove a client.rb config file for configuring Chef Infra Client. +properties_list: +- property: additional_config + ruby_type: String + required: false + description_list: + - markdown: Additional text to add at the bottom of the client.rb config. This can + be used to run custom Ruby or to add less common config options +- property: chef_license + ruby_type: String + required: false + allowed_values: '"accept", "accept-no-persist", "accept-silent"' + description_list: + - markdown: Accept the [Chef EULA](https://www.chef.io/end-user-license-agreement/) +- property: chef_server_url + ruby_type: String + required: true + description_list: + - markdown: The URL for the Chef Infra Server. +- property: config_directory + ruby_type: String + required: false + default_value: "`/etc/chef/` on *nix-like systems and `C:\\chef\\` on Windows" + description_list: + - markdown: The directory to store the client.rb in. +- property: data_collector_server_url + ruby_type: String + required: false + new_in: '17.8' + description_list: + - markdown: The data collector URL (typically automate) to send node, converge, + and compliance data. + - note: + markdown: If possible, use Chef Infra Server to do all data collection reporting, + as this removes the need to distribute tokens to individual nodes. +- property: data_collector_token + ruby_type: String + required: false + new_in: '17.8' + description_list: + - markdown: The data collector token to interact with the data collector server + URL (Automate). + - note: + markdown: If possible, use Chef Infra Server to do all data collection reporting, + as this removes the need to distribute tokens to individual nodes. +- property: event_loggers + ruby_type: Array + required: false + default_value: "[]" + description_list: [] +- property: exception_handlers + ruby_type: Array + required: false + default_value: "[]" + description_list: + - markdown: 'An array of hashes that contain a exception handler class and the arguments + to pass to that class on initialization. The hash should include `class` and + `argument` keys where `class` is a String and `argument` is an array of quoted + String values. For example: `[{''class'' => ''MyHandler'', %w(''"argument1"'', + ''"argument2"'')}]`' +- property: file_backup_path + ruby_type: String + required: false + description_list: + - markdown: The location in which backup files are stored. If this value is empty, + backup files are stored in the directory of the target file +- property: file_cache_path + ruby_type: String + required: false + description_list: + - markdown: The location in which cookbooks (and other transient data) files are + stored when they are synchronized. This value can also be used in recipes to + download files with the `remote_file` resource. +- property: file_staging_uses_destdir + ruby_type: String + required: false + description_list: + - markdown: How file staging (via temporary files) is done. When `true`, temporary + files are created in the directory in which files will reside. When `false`, + temporary files are created under `ENV['TMP']` +- property: formatters + ruby_type: Array + required: false + default_value: "[]" + description_list: + - markdown: Client logging formatters to load. +- property: ftp_proxy + ruby_type: String + required: false + description_list: + - markdown: The proxy server to use for FTP connections. +- property: group + ruby_type: String + required: false + description_list: + - markdown: The group that should own the client.rb file and the configuration directory + if it needs to be created. + - note: + 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. +- property: http_proxy + ruby_type: String + required: false + description_list: + - markdown: The proxy server to use for HTTP connections. +- property: https_proxy + ruby_type: String + required: false + description_list: + - markdown: The proxy server to use for HTTPS connections. +- property: log_level + ruby_type: Symbol + required: false + allowed_values: ":auto, :debug, :fatal, :info, :trace, :warn" + description_list: + - markdown: The level of logging performed by the Chef Infra Client. +- property: log_location + ruby_type: String, Symbol + required: false + description_list: + - markdown: The location to save logs to. This can either by a path to a log file + on disk `:syslog` to log to Syslog, `:win_evt` to log to the Windows Event Log, + or `'STDERR'`/`'STDOUT'` to log to the *nix text streams. +- 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 + to true may break cookbooks that assume all Ohai data will be present. +- property: named_run_list + ruby_type: String + required: false + description_list: + - markdown: A specific named runlist defined in the node's applied Policyfile, which + the should be used when running Chef Infra Client. +- property: no_proxy + ruby_type: String, Array + required: false + default_value: "[]" + description_list: + - markdown: A comma-separated list or an array of URLs that do not need a proxy. +- property: node_name + ruby_type: String + required: false + default_value: The `node.name` value reported by Chef Infra Client. + description_list: + - markdown: The name of the node. This configuration sets the `node.name` value + used in cookbooks and the `client_name` value used when authenticating to a + Chef Infra Server to determine what configuration to apply. + - note: + markdown: By default this configuration uses the `node.name` value which would + be set during bootstrap. Hard coding this value in the `client.rb` config + avoids logic within Chef Infra Server that performs DNS lookups and may fail + in the event of a DNS outage. To skip this default value and instead use the + built-in Chef Infra Server logic, set this property to `nil` +- property: ohai_disabled_plugins + ruby_type: Array + required: false + default_value: "[]" + description_list: + - markdown: Ohai plugins that should be disabled in order to speed up the Chef Infra + Client run and reduce the size of node data sent to Chef Infra Client +- property: ohai_optional_plugins + ruby_type: Array + required: false + default_value: "[]" + description_list: + - markdown: Optional Ohai plugins that should be enabled to provide additional Ohai + data for use in cookbooks. +- property: pid_file + ruby_type: String + required: false + description_list: + - markdown: The location in which a process identification number (pid) is saved. + An executable, when started as a daemon, writes the pid to the specified file. +- property: policy_group + ruby_type: String + required: false + description_list: + - markdown: The name of a `policy group` that exists on the Chef Infra Server. `policy_name` + must also be specified when setting this property. +- property: policy_name + ruby_type: String + required: false + description_list: + - markdown: The name of a policy, as identified by the `name` setting in a Policyfile.rb + file. `policy_group` when setting this property. +- 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 + on the Chef Infra Server. +- property: report_handlers + ruby_type: Array + required: false + default_value: "[]" + description_list: + - markdown: 'An array of hashes that contain a report handler class and the arguments + to pass to that class on initialization. The hash should include `class` and + `argument` keys where `class` is a String and `argument` is an array of quoted + String values. For example: `[{''class'' => ''MyHandler'', %w(''"argument1"'', + ''"argument2"'')}]`' +- property: rubygems_url + ruby_type: String, Array + required: false + 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 setup + an internal mirror of rubygems for “airgapped” environments. +- property: ssl_verify_mode + ruby_type: Symbol, String + required: false + allowed_values: ":verify_none, :verify_peer" + description_list: + - markdown: |- + Set the verify mode for HTTPS requests. + + * Use :verify_none for no validation of SSL certificates. + * Use :verify_peer for validation of all SSL certificates, including the Chef Infra Server connections, S3 connections, and any HTTPS remote_file resource URLs used in Chef Infra Client runs. This is the recommended setting. +- property: start_handlers + ruby_type: Array + required: false + default_value: "[]" + description_list: + - markdown: 'An array of hashes that contain a report handler class and the arguments + to pass to that class on initialization. The hash should include `class` and + `argument` keys where `class` is a String and `argument` is an array of quoted + String values. For example: `[{''class'' => ''MyHandler'', %w(''"argument1"'', + ''"argument2"'')}]`' +- property: user + ruby_type: String + required: false + description_list: + - markdown: The user that should own the client.rb file and the configuration directory + if it needs to be created. + - note: + 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**: + + The absolute minimum configuration necessary for a node to communicate with the Chef Infra Server is the URL of the Chef Infra Server. All other configuration options either have values at the server side (Policyfiles, Roles, Environments, etc) or have default values determined at client startup. + + ```ruby + chef_client_config 'Create client.rb' do + chef_server_url 'https://chef.example.dmz' + end + ``` + + **More complex Chef Infra Client client.rb**: + + ```ruby + chef_client_config 'Create client.rb' do + chef_server_url 'https://chef.example.dmz' + log_level :info + log_location :syslog + http_proxy 'proxy.example.dmz' + https_proxy 'proxy.example.dmz' + no_proxy %w(internal.example.dmz) + end + ``` + + **Adding additional config content to the client.rb**: + + This resource aims to provide common configuration options. Some configuration options are missing and some users may want to use arbitrary Ruby code within their configuration. For this we offer an `additional_config` property that can be used to add any configuration or code to the bottom of the `client.rb` file. Also keep in mind that within the configuration directory is a `client.d` directory where you can put additional `.rb` files containing configuration options. These can be created using `file` or `template` resources within your cookbooks as necessary. + + ```ruby + chef_client_config 'Create client.rb' do + chef_server_url 'https://chef.example.dmz' + additional_config <<~CONFIG + # Extra config code to safely load a gem into the client run. + # Since the config is Ruby you can run any Ruby code you want via the client.rb. + # It's a great way to break things, so be careful + begin + require 'aws-sdk' + rescue LoadError + Chef::Log.warn "Failed to load aws-sdk." + end + CONFIG + end + ``` + + **Setup two report handlers in the client.rb**: + + ```ruby + chef_client_config 'Create client.rb' do + chef_server_url 'https://chef.example.dmz' + report_handlers [ + { + 'class' => 'ReportHandler1Class', + 'arguments' => ["'FirstArgument'", "'SecondArgument'"], + }, + { + 'class' => 'ReportHandler2Class', + 'arguments' => ["'FirstArgument'", "'SecondArgument'"], + }, + ] + end + ``` + + **Report directly to the [Chef Automate data collector endpoint](https://docs.chef.io/automate/data_collection/#configure-chef-infra-client-to-use-the-data-collector-endpoint-in-chef-automate).** + + ```ruby + chef_client_config 'Create client.rb' do + chef_server_url 'https://chef.example.dmz' + data_collector_server_url 'https://automate.example.dmz' + data_collector_token 'TEST_TOKEN_TEST' + end + ``` diff --git a/data/infra/resources/chef_client_cron.yaml b/data/infra/resources/chef_client_cron.yaml new file mode 100644 index 0000000..d4aacf6 --- /dev/null +++ b/data/infra/resources/chef_client_cron.yaml @@ -0,0 +1,196 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: chef_client_cron +resource_description_list: +- markdown: Use the **chef_client_cron** resource to setup the Chef Infra Client to + run as a cron job. This resource will also create the specified log directory + if it doesn't already exist. +resource_new_in: '16.0' +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 + comment String + config_directory String # default value: "/etc/chef" + daemon_options Array # default value: [] + day Integer, String # default value: "*" + environment Hash # default value: {} + hour Integer, String # default value: "*" + job_name String # default value: "chef-client" + log_directory String + log_file_name String # default value: "client.log" + mailto String + minute Integer, String # default value: "0,30" + month Integer, String # default value: "*" + nice Integer, String + splay Integer, String # default value: 300 + user String # default value: "root" + weekday Integer, String # default value: "*" + action Symbol # defaults to :add if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`chef_client_cron` 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_chef_license`, `append_log_file`, `chef_binary_path`, `comment`, `config_directory`, + `daemon_options`, `day`, `environment`, `hour`, `job_name`, `log_directory`, `log_file_name`, + `mailto`, `minute`, `month`, `nice`, `splay`, `user`, and `weekday` are the properties + available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :add: + markdown: Add a cron job to run Chef Infra Client. (default) + :remove: + markdown: Remove a cron job for Chef Infra Client. +properties_list: +- property: accept_chef_license + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Accept the Chef Online Master License and Services Agreement. See +- property: append_log_file + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Append to the log file instead of overwriting the log file on each run. +- property: chef_binary_path + ruby_type: String + required: false + default_value: lazy default + description_list: + - markdown: The path to the chef-client binary. +- property: comment + ruby_type: String + required: false + description_list: + - markdown: A comment to place in the cron.d file. +- property: config_directory + ruby_type: String + required: false + default_value: "/etc/chef" + description_list: + - markdown: The path of the config directory. +- property: daemon_options + ruby_type: Array + required: false + default_value: "[]" + description_list: + - markdown: An array of options to pass to the chef-client command. +- property: day + ruby_type: Integer, String + required: false + default_value: "*" + description_list: + - markdown: The day of month at which Chef Infra Client is to run (1 - 31) or a + cron pattern such as '1,7,14,21,28'. +- property: environment + ruby_type: Hash + required: false + default_value: "{}" + description_list: + - markdown: A Hash containing additional arbitrary environment variables under which + the cron job will be run in the form of `({'ENV_VARIABLE' => 'VALUE'})`. +- property: hour + ruby_type: Integer, String + required: false + default_value: "*" + description_list: + - markdown: The hour at which Chef Infra Client is to run (0 - 23) or a cron pattern + such as '0,12'. +- property: job_name + ruby_type: String + required: false + default_value: chef-client + description_list: + - markdown: The name of the cron job to create. +- property: log_directory + ruby_type: String + required: false + default_value: "/Library/Logs/Chef on macOS and /var/log/chef otherwise" + description_list: + - markdown: The path of the directory to create the log file in. +- property: log_file_name + ruby_type: String + required: false + default_value: client.log + description_list: + - markdown: The name of the log file to use. +- property: mailto + ruby_type: String + required: false + description_list: + - markdown: The e-mail address to e-mail any cron task failures to. +- property: minute + ruby_type: Integer, String + required: false + default_value: '0,30' + description_list: + - markdown: The minute at which Chef Infra Client is to run (0 - 59) or a cron pattern + such as '0,30'. +- property: month + ruby_type: Integer, String + required: false + default_value: "*" + description_list: + - markdown: The month in the year on which Chef Infra Client is to run (1 - 12, + jan-dec, or *). +- property: nice + ruby_type: Integer, String + required: false + new_in: '16.5' + description_list: + - markdown: The process priority to run the chef-client process at. A value of -20 + is the highest priority and 19 is the lowest priority. +- property: splay + ruby_type: Integer, String + required: false + default_value: '300' + description_list: + - markdown: A random number of seconds between 0 and X to add to interval so that + all chef-client commands don't execute at the same time. +- property: user + ruby_type: String + required: false + default_value: root + description_list: + - markdown: The name of the user that Chef Infra Client runs as. +- property: weekday + ruby_type: Integer, String + required: false + default_value: "*" + 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**: + + ```ruby + chef_client_cron 'Run Chef Infra Client as a cron job' + ``` + + **Run Chef Infra Client twice a day**: + + ```ruby + chef_client_cron 'Run Chef Infra Client every 12 hours' do + minute 0 + hour '0,12' + end + ``` + + **Run Chef Infra Client with extra options passed to the client**: + + ```ruby + chef_client_cron 'Run an override recipe' do + daemon_options ['--override-runlist mycorp_base::default'] + end + ``` 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 0000000..446fc99 --- /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 new file mode 100644 index 0000000..10adc6e --- /dev/null +++ b/data/infra/resources/chef_client_launchd.yaml @@ -0,0 +1,143 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: chef_client_launchd +resource_description_list: +- markdown: Use the **chef_client_launchd** resource to configure the Chef Infra Client + to run on a schedule on macOS systems. +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 + config_directory String # default value: "/etc/chef" + daemon_options Array # default value: [] + environment Hash # default value: {} + interval Integer, String # default value: 30 + log_directory String # default value: "/Library/Logs/Chef" + log_file_name String # default value: "client.log" + low_priority_io true, false # default value: true + nice Integer, String + splay Integer, String # default value: 300 + user String # default value: "root" + working_directory String # default value: "/var/root" + action Symbol # defaults to :enable if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`chef_client_launchd` 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_chef_license`, `chef_binary_path`, `config_directory`, `daemon_options`, + `environment`, `interval`, `log_directory`, `log_file_name`, `low_priority_io`, + `nice`, `splay`, `user`, and `working_directory` are the properties available to + this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :enable: + markdown: Enable running Chef Infra Client on a schedule using launchd. (default) + :disable: + markdown: Disable running Chef Infra Client on a schedule using launchd +properties_list: +- property: accept_chef_license + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Accept the Chef Online Master License and Services Agreement. See +- property: chef_binary_path + ruby_type: String + required: false + default_value: lazy default + description_list: + - markdown: The path to the chef-client binary. +- property: config_directory + ruby_type: String + required: false + default_value: "/etc/chef" + description_list: + - markdown: The path of the config directory. +- property: daemon_options + ruby_type: Array + required: false + default_value: "[]" + description_list: + - markdown: An array of options to pass to the chef-client command. +- property: environment + ruby_type: Hash + required: false + default_value: "{}" + description_list: + - markdown: A Hash containing additional arbitrary environment variables under which + the launchd daemon will be run in the form of `({'ENV_VARIABLE' => 'VALUE'})`. +- property: interval + ruby_type: Integer, String + required: false + default_value: '30' + description_list: + - markdown: Time in minutes between Chef Infra Client executions. +- property: log_directory + ruby_type: String + required: false + default_value: "/Library/Logs/Chef" + description_list: + - markdown: The path of the directory to create the log file in. +- property: log_file_name + ruby_type: String + required: false + default_value: client.log + description_list: + - markdown: The name of the log file to use. +- property: low_priority_io + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Run the chef-client process with low priority disk IO +- property: nice + ruby_type: Integer, String + required: false + description_list: + - markdown: The process priority to run the chef-client process at. A value of -20 + is the highest priority and 19 is the lowest priority. +- property: splay + ruby_type: Integer, String + required: false + default_value: '300' + description_list: + - markdown: A random number of seconds between 0 and X to add to interval so that + all chef-client commands don't execute at the same time. +- property: user + ruby_type: String + required: false + default_value: root + description_list: + - markdown: The name of the user that Chef Infra Client runs as. +- property: working_directory + ruby_type: String + required: false + 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**: + + ```ruby + chef_client_launchd 'Setup the Chef Infra Client to run every 30 minutes' do + interval 30 + action :enable + end + ``` + + **Disable the Chef Infra Client running on a schedule**: + + ```ruby + chef_client_launchd 'Prevent the Chef Infra Client from running on a schedule' do + action :disable + end + ``` diff --git a/data/infra/resources/chef_client_scheduled_task.yaml b/data/infra/resources/chef_client_scheduled_task.yaml new file mode 100644 index 0000000..9ddf7c7 --- /dev/null +++ b/data/infra/resources/chef_client_scheduled_task.yaml @@ -0,0 +1,198 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: chef_client_scheduled_task +resource_description_list: +- markdown: Use the **chef_client_scheduled_task** resource to setup the Chef Infra + Client to run as a Windows scheduled task. This resource will also create the + specified log directory if it doesn't already exist. +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 + 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" + log_directory String # default value: "CONFIG_DIRECTORY/log" + log_file_name String # default value: "client.log" + password String + priority Integer # default value: 7 + run_on_battery true, false # default value: true + splay Integer, String # default value: 300 + start_date String + start_time String + task_name String # default value: "chef-client" + use_consistent_splay true, false # default value: false + user String # default value: "System" + action Symbol # defaults to :add if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`chef_client_scheduled_task` 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_chef_license`, `chef_binary_path`, `config_directory`, `daemon_options`, + `frequency`, `frequency_modifier`, `log_directory`, `log_file_name`, `password`, + `priority`, `run_on_battery`, `splay`, `start_date`, `start_time`, `task_name`, + `use_consistent_splay`, and `user` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :add: + markdown: Add a Windows Scheduled Task that runs Chef Infra Client. (default) + :remove: + markdown: Remove a Windows Scheduled Task that runs Chef Infra Client. +properties_list: +- property: accept_chef_license + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Accept the Chef Online Master License and Services Agreement. See +- property: chef_binary_path + ruby_type: String + required: false + default_value: lazy default + description_list: + - markdown: The path to the chef-client binary. +- property: config_directory + ruby_type: String + required: false + default_value: C:/chef + description_list: + - markdown: The path of the config directory. +- property: daemon_options + ruby_type: Array + required: false + default_value: "[]" + description_list: + - markdown: An array of options to pass to the chef-client command. +- property: frequency + ruby_type: String + required: false + default_value: minute + allowed_values: '"daily", "hourly", "minute", "monthly", "on_idle", "on_logon", + "once", "onstart"' + description_list: + - markdown: Frequency with which to run the task. +- property: frequency_modifier + ruby_type: Integer, String + required: false + default_value: 30 if frequency is 'minute', 1 otherwise + description_list: + - markdown: Numeric value to go with the scheduled task frequency +- property: log_directory + ruby_type: String + required: false + default_value: CONFIG_DIRECTORY/log + description_list: + - markdown: The path of the directory to create the log file in. +- property: log_file_name + ruby_type: String + required: false + default_value: client.log + description_list: + - markdown: The name of the log file to use. +- property: password + ruby_type: String + required: false + description_list: + - markdown: The password for the user that Chef Infra Client runs as. +- property: priority + ruby_type: Integer + required: false + default_value: '7' + new_in: '17.5' + description_list: + - markdown: Use to set Priority Levels range from 0 to 10. +- property: run_on_battery + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Run the Chef Infra Client task when the system is on batteries. +- property: splay + ruby_type: Integer, String + required: false + default_value: '300' + description_list: + - markdown: A random number of seconds between 0 and X to add to interval so that + all chef-client commands don't execute at the same time. +- property: start_date + ruby_type: String + required: false + description_list: + - markdown: 'The start date for the task in m:d:Y format (ex: 12/17/2020).' +- property: start_time + ruby_type: String + required: false + description_list: + - markdown: 'The start time for the task in HH:mm format (ex: 14:00). If the frequency + is minute default start time will be Time.now plus the frequency_modifier number + of minutes.' +- property: task_name + ruby_type: String + required: false + default_value: chef-client + description_list: + - markdown: The name of the scheduled task to create. +- property: use_consistent_splay + ruby_type: true, false + required: false + default_value: 'false' + new_in: '17.5' + description_list: + - markdown: Always use the same random splay amount for each node to ensure consistent + frequencies between chef-client execution. +- property: user + ruby_type: String + required: false + 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**: + + ```ruby + chef_client_scheduled_task 'Run Chef Infra Client as a scheduled task' + ``` + + **Run Chef Infra Client on system start**: + + ```ruby + chef_client_scheduled_task 'Chef Infra Client on start' do + frequency 'onstart' + end + ``` + + **Run Chef Infra Client with extra options passed to the client**: + + ```ruby + chef_client_scheduled_task 'Run an override recipe' do + daemon_options ['--override-runlist mycorp_base::default'] + end + ``` + + **Run Chef Infra Client daily at 01:00 am, specifying a named run-list**: + + ```ruby + chef_client_scheduled_task 'Run chef-client named run-list daily' do + frequency 'daily' + start_time '01:00' + daemon_options ['-n audit_only'] + end + ``` + + **Run Chef Infra Client with a persistent delay on every run calculated once, similar to how chef_client_cron resource works**: + + ```ruby + chef_client_scheduled_task 'Run chef-client with persistent splay' do + use_consistent_splay true + end + ``` diff --git a/data/infra/resources/chef_client_systemd_timer.yaml b/data/infra/resources/chef_client_systemd_timer.yaml new file mode 100644 index 0000000..ba9e505 --- /dev/null +++ b/data/infra/resources/chef_client_systemd_timer.yaml @@ -0,0 +1,165 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: chef_client_systemd_timer +resource_description_list: +- markdown: Use the **chef_client_systemd_timer** resource to setup the Chef Infra + Client to run as a systemd timer. +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 + config_directory String # default value: "/etc/chef" + cpu_quota Integer, String + daemon_options Array # default value: [] + delay_after_boot String # default value: "1min" + description String # default value: "Chef Infra Client periodic execution" + environment Hash # default value: {} + interval String # default value: "30min" + job_name String # default value: "chef-client" + run_on_battery true, false # default value: true + service_umask Integer, String + splay String # default value: "5min" + user String # default value: "root" + action Symbol # defaults to :add if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`chef_client_systemd_timer` 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_chef_license`, `chef_binary_path`, `config_directory`, `cpu_quota`, `daemon_options`, + `delay_after_boot`, `description`, `environment`, `interval`, `job_name`, `run_on_battery`, + `service_umask`, `splay`, and `user` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :add: + markdown: Add a systemd timer that runs Chef Infra Client. (default) + :remove: + markdown: Remove a systemd timer that runs Chef Infra Client. +properties_list: +- property: accept_chef_license + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Accept the Chef Online Master License and Services Agreement. See +- property: chef_binary_path + ruby_type: String + required: false + default_value: lazy default + description_list: + - markdown: The path to the chef-client binary. +- property: config_directory + ruby_type: String + required: false + default_value: "/etc/chef" + description_list: + - markdown: The path of the config directory. +- property: cpu_quota + ruby_type: Integer, String + required: false + new_in: '16.5' + description_list: + - markdown: The systemd CPUQuota to run the chef-client process with. This is a + percentage value of the total CPU time available on the system. If the system + has more than 1 core this may be a value greater than 100. +- property: daemon_options + ruby_type: Array + required: false + default_value: "[]" + description_list: + - markdown: An array of options to pass to the chef-client command. +- property: delay_after_boot + ruby_type: String + required: false + default_value: 1min + description_list: + - markdown: The time to wait after booting before the interval starts. This is expressed + as a systemd time span such as `300seconds`, `1hr`, or `1m`. See + for a complete list of allowed time span values. +- property: description + ruby_type: String + required: false + default_value: Chef Infra Client periodic execution + description_list: + - markdown: The description to add to the systemd timer. This will be displayed + when running `systemctl status` for the timer. +- property: environment + ruby_type: Hash + required: false + default_value: "{}" + description_list: + - markdown: A Hash containing additional arbitrary environment variables under which + the systemd timer will be run in the form of `({'ENV_VARIABLE' => 'VALUE'})`. +- property: interval + ruby_type: String + required: false + default_value: 30min + description_list: + - markdown: The interval to wait between executions. This is expressed as a systemd + time span such as `300seconds`, `1hr`, or `1m`. See + for a complete list of allowed time span values. +- property: job_name + ruby_type: String + required: false + default_value: chef-client + description_list: + - markdown: The name of the system timer to create. +- property: run_on_battery + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Run the timer for Chef Infra Client if the system is on battery. +- property: service_umask + ruby_type: Integer, String + required: false + new_in: '18.5' + description_list: + - markdown: Fix umask for hardened systems that have a changed default umask. This + changes the chef-client umask so any files or folders are created with new umask. + Recommend setting to stand install default of 0022. +- property: splay + ruby_type: String + required: false + default_value: 5min + description_list: + - markdown: A interval between 0 and X to add to the interval so that all chef-client + commands don't execute at the same time. This is expressed as a systemd time + span such as `300seconds`, `1hr`, or `1m`. See + for a complete list of allowed time span values. +- property: user + ruby_type: String + required: false + 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**: + + ```ruby + chef_client_systemd_timer 'Run Chef Infra Client as a systemd timer' + ``` + + **Run Chef Infra Client every 1 hour**: + + ```ruby + chef_client_systemd_timer 'Run Chef Infra Client every 1 hour' do + interval '1hr' + end + ``` + + **Run Chef Infra Client with extra options passed to the client**: + + ```ruby + chef_client_systemd_timer 'Run an override recipe' do + daemon_options ['--override-runlist mycorp_base::default'] + end + ``` diff --git a/data/infra/resources/chef_client_trusted_certificate.yaml b/data/infra/resources/chef_client_trusted_certificate.yaml new file mode 100644 index 0000000..d4df1e2 --- /dev/null +++ b/data/infra/resources/chef_client_trusted_certificate.yaml @@ -0,0 +1,77 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: chef_client_trusted_certificate +resource_description_list: +- markdown: Use the **chef_client_trusted_certificate** resource to add certificates + to Chef Infra Client's trusted certificate directory. This allows the Chef Infra + Client to communicate with internal encrypted resources without errors. +resource_new_in: '16.5' +syntax_full_code_block: |- + chef_client_trusted_certificate '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_trusted_certificate` 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 trusted certificate to Chef Infra Client's trusted certificate + directory (default) + :remove: + markdown: Remove a trusted certificate from Chef Infra Client's trusted certificate + directory +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 file on disk. 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_trusted_certificate '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_gem.yaml b/data/infra/resources/chef_gem.yaml new file mode 100644 index 0000000..581417f --- /dev/null +++ b/data/infra/resources/chef_gem.yaml @@ -0,0 +1,157 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: chef_gem +resource_description_list: +- markdown: |- + Use the **chef_gem** resource to install a gem only for the instance of Ruby that is dedicated to the Chef Infra Client. + When a gem is installed from a local file, it must be added to the node using the **remote_file** or **cookbook_file** resources. + + The **chef_gem** resource works with all of the same properties and options as the **gem_package** resource, but does not + accept the `gem_binary` property because it always uses the `CurrentGemEnvironment` under which the `chef-client` is + running. In addition to performing actions similar to the **gem_package** resource, the **chef_gem** resource does the + following: + - 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: + 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 + package_name String + source String, Array + timeout String, Integer + version String + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`chef_gem` 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." +- "`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. + :reconfig: + markdown: + :lock: + markdown: + :unlock: + markdown: +properties_list: +- property: clear_sources + ruby_type: true, false + required: false + default_value: false unless `clear_gem_sources` set to true in the `client.rb` config. + 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 + default_value: The `gem` binary included with Chef Infra Client. + description_list: + - markdown: The path of a gem binary to use for the installation. By default, the + same version of Ruby that is used by Chef Infra Client will be used. +- property: include_default_source + ruby_type: true, false + required: false + new_in: '13.0' + description_list: + - markdown: Set to `false` to not include `Chef::Config[:rubygems_url]` in the sources. +- property: options + ruby_type: String, Hash, Array + required: false + description_list: + - markdown: Options for the gem install, either a Hash or a String. When a hash + is given, the options are passed to `Gem::DependencyInstaller.new`, and the + gem will be installed via the gems API. When a String is given, the gem will + be installed by shelling out to the gem command. Using a Hash of options with + an explicit gem_binary will result in undefined behavior. +- property: package_name + ruby_type: String + required: false + description_list: + - markdown: An optional property to set the package name if it differs from the + resource block's name. +- property: source + ruby_type: String, Array + required: false + description_list: + - markdown: Optional. The URL, or list of URLs, at which the gem package is located. + This list is added to the source configured in `Chef::Config[:rubygems_url]` + (see also include_default_source) to construct the complete list of rubygems + sources. Users in an 'airgapped' environment should set Chef::Config[:rubygems_url] + to their local RubyGems mirror. +- property: timeout + ruby_type: String, Integer + required: false + description_list: + - markdown: The amount of time (in seconds) to wait before timing out. +- property: version + ruby_type: String + 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** + + To install a gem while Chef Infra Client is configuring the node (the converge phase), set the `compile_time` property to `false`: + ```ruby + chef_gem 'loofah' do + compile_time false + action :install + end + ``` + + To install a gem while the resource collection is being built (the compile phase), set the `compile_time` property to `true`: + ```ruby + chef_gem 'loofah' do + compile_time true + action :install + end + ``` + + **Install MySQL gem into Chef Infra Client** + ```ruby + apt_update + + build_essential 'install compilation tools' do + compile_time true + end + + chef_gem 'mysql' + ``` diff --git a/data/infra/resources/chef_handler.yaml b/data/infra/resources/chef_handler.yaml new file mode 100644 index 0000000..b8768eb --- /dev/null +++ b/data/infra/resources/chef_handler.yaml @@ -0,0 +1,228 @@ +--- +resource_reference: true +handler_custom: true +handler_types: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: chef_handler +resource_description_list: +- markdown: |- + Use the **chef_handler** resource to enable handlers during a Chef Infra Client run. The resource allows arguments to be passed to Chef Infra Client, which then applies the conditions defined by the custom handler to the node attribute data collected during a Chef Infra Client run, and then processes the handler based on that data. + The **chef_handler** resource is typically defined early in a node's run-list (often being the first item). This ensures that all of the handlers will be available for the entire Chef Infra Client run. +resource_new_in: '14.0' +syntax_description: "A **chef_handler** resource block enables handlers during a chef-client\n\ + run. Two handlers---`JsonFile` and `ErrorReport`---are built into Chef:\n\n```ruby\n\ + chef_handler 'Chef::Handler::JsonFile' do\n source 'chef/handler/json_file'\n \ + \ arguments :path => '/var/chef/reports'\n action :enable\nend\n```\n\nand:\n\n\ + ```ruby\nchef_handler 'Chef::Handler::ErrorReport' do\n source 'chef/handler/error_report'\n\ + \ action :enable\nend\n```\n\nshow how to enable those handlers in a recipe." +syntax_full_code_block: |- + chef_handler 'name' do + arguments Array, Hash # default value: [] + class_name String # default value: 'name' unless specified + source String + type Hash # default value: {"report"=>true, "exception"=>true} + action Symbol # defaults to :enable if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`chef_handler` 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." +- "`arguments`, `class_name`, `source`, and `type` are the properties available to + this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :enable: + markdown: Enables the handler for the current Chef Infra Client run on the current + node. (default) + :disable: + markdown: Disables the handler for the current Chef Infra Client run on the current + node. +properties_list: +- property: arguments + ruby_type: Array, Hash + required: false + default_value: "[]" + description_list: + - markdown: "An array of arguments that are passed to the initializer for the handler class. For example: + + ```ruby + + arguments :key1 => ''val1'' + + ``` + + or: + + ```ruby + + arguments [:key1 => ''val1'', :key2 => ''val2''] + + ```" +- property: class_name + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: The name of the handler class. This can be module name-spaced. +- property: source + ruby_type: String + required: false + description_list: + - markdown: The full path to the handler file. Can also be a gem path if the handler + ships as part of a Ruby gem. +- property: type + ruby_type: Hash + required: false + 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** + + The following example shows how to enable a fictional 'MyHandler' handler which is located on disk at `/etc/chef/my_handler.rb`. The handler will be configured to run with Chef Infra Client and will be passed values to the handler's initializer method: + + ```ruby + chef_handler 'MyHandler' do + source '/etc/chef/my_handler.rb' # the file should already be at this path + arguments path: '/var/chef/reports' + action :enable + end + ``` + + **Enable handlers during the compile phase** + + ```ruby + chef_handler 'Chef::Handler::JsonFile' do + source 'chef/handler/json_file' + arguments path: '/var/chef/reports' + action :enable + compile_time true + end + ``` + + **Handle only exceptions** + + ```ruby + chef_handler 'Chef::Handler::JsonFile' do + source 'chef/handler/json_file' + arguments path: '/var/chef/reports' + type exception: true + action :enable + end + ``` + + **Cookbook Versions (a custom handler)** + + [@juliandunn](https://github.com/juliandunn) created a custom report handler that logs all of the cookbooks and cookbook versions that were used during a Chef Infra Client run, and then reports after the run is complete. + + cookbook_versions.rb: + + The following custom handler defines how cookbooks and cookbook versions that are used during a Chef Infra Client run will be compiled into a report using the `Chef::Log` class in Chef Infra Client: + + ```ruby + require 'chef/log' + + module Chef + class CookbookVersionsHandler < Chef::Handler + def report + cookbooks = run_context.cookbook_collection + Chef::Log.info('Cookbooks and versions run: #{cookbooks.map {|x| x.name.to_s + ' ' + x.version }}') + end + end + end + ``` + + default.rb: + + The following recipe is added to the run-list for every node on which a list of cookbooks and versions will be generated as report output after every Chef Infra Client run. + + ```ruby + cookbook_file '/etc/chef/cookbook_versions.rb' do + source 'cookbook_versions.rb' + action :create + end + + chef_handler 'Chef::CookbookVersionsHandler' do + source '/etc/chef/cookbook_versions.rb' + type report: true + action :enable + end + ``` + + This recipe will generate report output similar to the following: + + ``` + [2013-11-26T03:11:06+00:00] INFO: Chef Infra Client Run complete in 0.300029878 seconds + [2013-11-26T03:11:06+00:00] INFO: Running report handlers + [2013-11-26T03:11:06+00:00] INFO: Cookbooks and versions run: ["cookbook_versions_handler 1.0.0"] + [2013-11-26T03:11:06+00:00] INFO: Report handlers complete + ``` + + **JsonFile Handler** + + The JsonFile handler is available from the `chef_handler` cookbook and can be used with exceptions and reports. It serializes run status data to a JSON file. This handler may be enabled in one of the following ways. + + By adding the following lines of Ruby code to either the client.rb file or the solo.rb file, depending on how Chef Infra Client is being run: + + ```ruby + require 'chef/handler/json_file' + report_handlers << Chef::Handler::JsonFile.new(path: '/var/chef/reports') + exception_handlers << Chef::Handler::JsonFile.new(path: '/var/chef/reports') + ``` + + By using the `chef_handler` resource in a recipe, similar to the following: + + ```ruby + chef_handler 'Chef::Handler::JsonFile' do + source 'chef/handler/json_file' + arguments path: '/var/chef/reports' + action :enable + end + ``` + + After it has run, the run status data can be loaded and inspected via Interactive Ruby (IRb): + + ``` + irb(main):002:0> require 'json' => true + irb(main):003:0> require 'chef' => true + irb(main):004:0> r = JSON.parse(IO.read('/var/chef/reports/chef-run-report-20110322060731.json')) => ... output truncated + irb(main):005:0> r.keys => ['end_time', 'node', 'updated_resources', 'exception', 'all_resources', 'success', 'elapsed_time', 'start_time', 'backtrace'] + irb(main):006:0> r['elapsed_time'] => 0.00246 + ``` + + Register the JsonFile handler + + ```ruby + chef_handler 'Chef::Handler::JsonFile' do + source 'chef/handler/json_file' + arguments path: '/var/chef/reports' + action :enable + end + ``` + + **ErrorReport Handler** + + The ErrorReport handler is built into Chef Infra Client and can be used for both exceptions and reports. It serializes error report data to a JSON file. This handler may be enabled in one of the following ways. + + By adding the following lines of Ruby code to either the client.rb file or the solo.rb file, depending on how Chef Infra Client is being run: + + ```ruby + require 'chef/handler/error_report' + report_handlers << Chef::Handler::ErrorReport.new + exception_handlers << Chef::Handler::ErrorReport.new + ``` + + By using the `chef_handler` resource in a recipe, similar to the following: + + ```ruby + chef_handler 'Chef::Handler::ErrorReport' do + source 'chef/handler/error_report' + action :enable + end + ``` diff --git a/data/infra/resources/chef_sleep.yaml b/data/infra/resources/chef_sleep.yaml new file mode 100644 index 0000000..cf62c23 --- /dev/null +++ b/data/infra/resources/chef_sleep.yaml @@ -0,0 +1,66 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: chef_sleep +resource_description_list: +- markdown: Use the **chef_sleep** resource to pause (sleep) for a number of seconds + during a Chef Infra Client run. Only use this resource when a command or service + exits successfully but is not ready for the next step in a recipe. +resource_new_in: '15.5' +syntax_full_code_block: |- + chef_sleep 'name' do + seconds String, Integer # default value: 'name' unless specified + action Symbol # defaults to :sleep if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`chef_sleep` 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." +- "`seconds` is the property available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :sleep: + markdown: Pause the Chef Infra Client run for a specified number of seconds. (default) +properties_list: +- property: seconds + ruby_type: String, Integer + required: false + 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**: + + ```ruby + chef_sleep '10' + ``` + + **Sleep for 10 seconds with a descriptive resource name for logging**: + + ```ruby + chef_sleep 'wait for the service to start' do + seconds 10 + end + ``` + + **Use a notification from another resource to sleep only when necessary**: + + ```ruby + service 'Service that is slow to start and reports as started' do + service_name 'my_database' + action :start + notifies :sleep, 'chef_sleep[wait for service start]' + end + + chef_sleep 'wait for service start' do + seconds 30 + action :nothing + end + ``` diff --git a/data/infra/resources/chef_vault_secret.yaml b/data/infra/resources/chef_vault_secret.yaml new file mode 100644 index 0000000..f4463c0 --- /dev/null +++ b/data/infra/resources/chef_vault_secret.yaml @@ -0,0 +1,106 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: chef_vault_secret +resource_description_list: +- markdown: Use the **chef_vault_secret** resource to store secrets in Chef Vault + items. Where possible and relevant, this resource attempts to map behavior and + functionality to the knife vault sub-commands. +resource_new_in: '16.0' +syntax_full_code_block: |- + chef_vault_secret 'name' do + admins String, Array + clients String, Array + data_bag String + environment String + id String # default value: 'name' unless specified + raw_data Hash, Mash (Hash-like) # default value: {} + search String # default value: "*:*" + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`chef_vault_secret` 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." +- "`admins`, `clients`, `data_bag`, `environment`, `id`, `raw_data`, and `search` + are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Creates the item, or updates it if it already exists. (default) + :create_if_missing: + markdown: Calls the create action unless it exists. + :delete: + markdown: Deletes the item and the item's keys ('id'_keys). +properties_list: +- property: admins + ruby_type: String, Array + required: true + description_list: + - markdown: A list of admin users who should have access to the item. Corresponds + to the 'admin' option when using the chef-vault knife plugin. Can be specified + as a comma separated string or an array. +- property: clients + ruby_type: String, Array + required: false + description_list: + - markdown: A search query for the nodes' API clients that should have access to + the item. +- property: data_bag + ruby_type: String + required: true + description_list: + - markdown: The data bag that contains the item. +- property: environment + ruby_type: String + required: false + description_list: + - markdown: The Chef environment of the data if storing per environment values. +- property: id + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: The name of the data bag item if it differs from the name of the resource + block +- property: raw_data + ruby_type: Hash, Mash (Hash-like) + required: false + default_value: "{}" + description_list: + - markdown: The raw data, as a Ruby Hash, that will be stored in the item. +- property: search + ruby_type: String + required: false + default_value: "*:*" + 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**: + + ```ruby + chef_vault_secret 'foo' do + data_bag 'bar' + raw_data({ 'auth' => 'baz' }) + admins 'jtimberman' + search '*:*' + end + ``` + + **To allow multiple admins access to an item**: + + ```ruby + chef_vault_secret 'root-password' do + admins 'jtimberman,paulmooring' + data_bag 'secrets' + raw_data({ 'auth' => 'DoNotUseThisPasswordForRoot' }) + search '*:*' + end + ``` diff --git a/data/infra/resources/chocolatey_config.yaml b/data/infra/resources/chocolatey_config.yaml new file mode 100644 index 0000000..080a58b --- /dev/null +++ b/data/infra/resources/chocolatey_config.yaml @@ -0,0 +1,66 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: chocolatey_config +resource_description_list: +- markdown: Use the **chocolatey_config** resource to add or remove Chocolatey configuration + keys. +- note: + markdown: The Chocolatey package manager is not installed on Windows by default. + You will need to install it prior to using this resource by adding the [Chocolatey + cookbook](https://supermarket.chef.io/cookbooks/chocolatey/) to your node's + run list. +resource_new_in: '14.3' +syntax_full_code_block: |- + chocolatey_config 'name' do + config_key String # default value: 'name' unless specified + value String + action Symbol # defaults to :set if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`chocolatey_config` 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." +- "`config_key` and `value` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :set: + markdown: Sets a Chocolatey config value. (default) + :unset: + markdown: Unsets a Chocolatey config value. +properties_list: +- property: config_key + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the config key name if it differs from the + resource block's name. +- property: value + ruby_type: String + required: false + description_list: + - markdown: The value to set. +target_mode: +examples: | + **Set the Chocolatey cacheLocation config**: + + ```ruby + chocolatey_config 'Set cacheLocation config' do + config_key 'cacheLocation' + value 'C:\temp\choco' + end + ``` + + **Unset a Chocolatey config**: + + ```ruby + chocolatey_config 'BogusConfig' do + action :unset + end + ``` diff --git a/data/infra/resources/chocolatey_feature.yaml b/data/infra/resources/chocolatey_feature.yaml new file mode 100644 index 0000000..6e358c5 --- /dev/null +++ b/data/infra/resources/chocolatey_feature.yaml @@ -0,0 +1,58 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: chocolatey_feature +resource_description_list: +- markdown: Use the **chocolatey_feature** resource to enable and disable Chocolatey + features. +- note: + markdown: The Chocolatey package manager is not installed on Windows by default. + You will need to install it prior to using this resource by adding the [Chocolatey + cookbook](https://supermarket.chef.io/cookbooks/chocolatey/) to your node's + run list. +resource_new_in: '15.1' +syntax_full_code_block: |- + chocolatey_feature 'name' do + feature_name String # default value: 'name' unless specified + action Symbol # defaults to :enable if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`chocolatey_feature` 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." +- "`feature_name` is the property available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :enable: + markdown: Enables a named Chocolatey feature. (default) + :disable: + markdown: Disables a named Chocolatey feature. +properties_list: +- property: feature_name + ruby_type: String + required: false + 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** + + ```ruby + chocolatey_feature 'checksumFiles' do + action :enable + end + ``` + + **Disable the checksumFiles Chocolatey feature** + + ```ruby + chocolatey_feature 'checksumFiles' do + action :disable + end + ``` diff --git a/data/infra/resources/chocolatey_installer.yaml b/data/infra/resources/chocolatey_installer.yaml new file mode 100644 index 0000000..97b7f06 --- /dev/null +++ b/data/infra/resources/chocolatey_installer.yaml @@ -0,0 +1,102 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: chocolatey_installer +resource_description_list: +- 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 + download_url String + ignore_proxy true, false # default value: false + proxy_password String + proxy_url String + proxy_user String + use_native_unzip true, false # default value: false + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`chocolatey_installer` 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." +- "`chocolatey_version`, `download_url`, `ignore_proxy`, `proxy_password`, `proxy_url`, + `proxy_user`, and `use_native_unzip` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :install: + markdown: Installs Chocolatey package manager (default) + :uninstall: + markdown: Uninstall Chocolatey package manager + :upgrade: + 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 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 + and causes the installer to choose an alternate download location. If this is + 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, 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 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 + description_list: + - markdown: Specifies the proxy URL to use during the download. +- property: proxy_user + ruby_type: String + required: false + description_list: + - 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 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 + with Parameters**\n\n```ruby\nchocolatey_installer 'latest' do\n action :install\n + \ download_url \"https://www.contoso.com/foo\"\n chocolatey_version '2.12.24'\nend\n```\n\n```ruby\nchocolatey_installer + 'latest' do\n action :install\n download_url \"c:\\foo\foo.nupkg\"\n chocolatey_version + '2.12.24'\nend\n```\n\n**Upgrade Chocolatey with Parameters**\n\n```ruby\nchocolatey_installer + 'latest' do\n action :upgrade\n chocolatey_version '2.12.24'\nend\n```\n" diff --git a/data/infra/resources/chocolatey_package.yaml b/data/infra/resources/chocolatey_package.yaml new file mode 100644 index 0000000..fed8ae6 --- /dev/null +++ b/data/infra/resources/chocolatey_package.yaml @@ -0,0 +1,155 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: chocolatey_package +resource_description_list: +- markdown: Use the **chocolatey_package** resource to manage packages using the Chocolatey + package manager on the Microsoft Windows platform. +- note: + markdown: The Chocolatey package manager is not installed on Windows by default. + You will need to install it prior to using this resource by adding the [chocolatey + cookbook](https://supermarket.chef.io/cookbooks/chocolatey/) to your node's + run list. +- warning: + markdown: The **chocolatey_package** resource must be specified as `chocolatey_package` + and cannot be shortened to `package` in a recipe. +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 + password String + returns Integer, Array # default value: [0, 2] + source String + timeout String, Integer + use_choco_list true, false # default value: false + user String + version String, Array + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`chocolatey_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." +- "`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 + :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: bulk_query + ruby_type: true, false + required: false + default_value: 'false' + description_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 + new_in: '15.3' + description_list: + - markdown: One (or more) additional list options that are passed to the command. +- property: options + ruby_type: String, Array + required: false + description_list: + - markdown: One (or more) additional 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.' +- property: password + ruby_type: String + required: false + new_in: '15.3' + description_list: + - markdown: The password to authenticate to the source. +- property: returns + ruby_type: Integer, Array + required: false + default_value: "[0, 2]" + new_in: '12.18' + description_list: + - markdown: The exit code(s) returned by the `choco` command that indicate a successful + action. See [Chocolatey Exit Codes](https://docs.chocolatey.org/en-us/choco/commands/info#exit-codes) + for a complete list of exit codes used by Chocolatey. +- 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 + description_list: + - markdown: The amount of time (in seconds) to wait before timing out. +- property: use_choco_list + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - 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 + new_in: '15.3' + description_list: + - markdown: The username to authenticate feeds. +- property: version + ruby_type: String, Array + required: false + description_list: + - markdown: The version of a package to be installed or upgraded. +target_mode: +examples: | + **Install a Chocolatey package**: + + ```ruby + chocolatey_package 'name of package' do + action :install + end + ``` + + **Install a package with options with Chocolatey's `--checksum` option**: + + ```ruby + chocolatey_package 'name of package' do + options '--checksum 1234567890' + action :install + end + ``` diff --git a/data/infra/resources/chocolatey_source.yaml b/data/infra/resources/chocolatey_source.yaml new file mode 100644 index 0000000..24b3365 --- /dev/null +++ b/data/infra/resources/chocolatey_source.yaml @@ -0,0 +1,131 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: chocolatey_source +resource_description_list: +- markdown: Use the **chocolatey_source** resource to add, remove, enable, or disable + Chocolatey sources. +- note: + markdown: The Chocolatey package manager is not installed on Windows by default. + You will need to install it prior to using this resource by adding the [Chocolatey + cookbook](https://supermarket.chef.io/cookbooks/chocolatey/) to your node's + run list. +resource_new_in: '14.3' +syntax_full_code_block: |- + chocolatey_source 'name' do + admin_only true, false # default value: false + allow_self_service true, false # default value: false + bypass_proxy true, false # default value: false + cert String + cert_password String + password String + priority Integer # default value: 0 + source String + source_name String # default value: 'name' unless specified + username String + action Symbol # defaults to :add if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`chocolatey_source` 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." +- "`admin_only`, `allow_self_service`, `bypass_proxy`, `cert`, `cert_password`, `password`, + `priority`, `source`, `source_name`, and `username` are the properties available + to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :add: + markdown: Adds a Chocolatey source (default) + :remove: + markdown: Removes a Chocolatey source. + :disable: + markdown: Disables a Chocolatey source. **New in Chef Infra Client 15.1.** + :enable: + markdown: Enables a Chocolatey source. **New in Chef Infra Client 15.1.** +properties_list: +- property: admin_only + ruby_type: true, false + required: false + default_value: 'false' + new_in: '15.1' + description_list: + - markdown: Whether or not to set the source to be accessible to only admins. +- property: allow_self_service + ruby_type: true, false + required: false + default_value: 'false' + new_in: '15.1' + description_list: + - markdown: Whether or not to set the source to be used for self service. +- property: bypass_proxy + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Whether or not to bypass the system's proxy settings to access the source. +- property: cert + ruby_type: String + required: false + new_in: '17.7' + description_list: + - markdown: The certificate to use when authenticating against the source +- property: cert_password + ruby_type: String + required: false + new_in: '17.7' + description_list: + - markdown: The password for the certificate to use when authenticating against + the source +- property: password + ruby_type: String + required: false + new_in: '17.7' + description_list: + - markdown: The password to use when authenticating against the source +- property: priority + ruby_type: Integer + required: false + default_value: '0' + description_list: + - markdown: The priority level of the source. +- property: source + ruby_type: String + required: false + description_list: + - markdown: The source URL. +- property: source_name + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the source name if it differs from the resource + block's name. +- property: username + ruby_type: String + required: false + new_in: '17.7' + description_list: + - markdown: The username to use when authenticating against the source +target_mode: +examples: | + **Add a Chocolatey source** + + ```ruby + chocolatey_source 'MySource' do + source 'http://example.com/something' + action :add + end + ``` + + **Remove a Chocolatey source** + + ```ruby + chocolatey_source 'MySource' do + action :remove + end + ``` diff --git a/data/infra/resources/cookbook_file.yaml b/data/infra/resources/cookbook_file.yaml new file mode 100644 index 0000000..4d2f898 --- /dev/null +++ b/data/infra/resources/cookbook_file.yaml @@ -0,0 +1,307 @@ +--- +resource_reference: true +cookbook_file_specificity: true +properties_resources_common_windows_security: true +resources_common_atomic_update: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: cookbook_file +resource_description_list: +- shortcode: resource_cookbook_file_summary.md +- markdown: |- + 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: +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`, `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 + :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. + :touch: + markdown: Touch a file. This updates the access (atime) and file modification +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: cookbook + ruby_type: String + required: false + default_value: The current cookbook name + description_list: + - markdown: The cookbook in which a file is located (if it is not located in the + current cookbook). +- 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 + 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: "(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 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: '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: source + ruby_type: String, Array + 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 + its extension. This can be used to distribute specific files depending upon + + files depending upon the platform used - see [File + + Specificity](#cookbook-file-specificity) for more information.' +- 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\ncookbook_file '/tmp/baz'\ + \ do\n verify { 1 == 1 }\nend\n```\n\nThis should return `true`:\n\n```ruby\n\ + cookbook_file '/etc/nginx.conf' do\n verify 'nginx -t -c %{path}'\nend\n```" + - markdown: "This should return `true`:\n\n```ruby\ncookbook_file '/tmp/bar' do\n\ + \ verify { 1 == 1}\nend\n```\n\nAnd this should return `true`:\n\n```ruby\n\ + cookbook_file '/tmp/foo' do\n verify do |path|\n true\n end\nend\n```\n\ + \nWhereas, this should return `false`:\n\n```ruby\ncookbook_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." +properties_multiple_packages: false +resource_directory_recursive_directories: false +remote_file_unc_path: false +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\ + \ the same recipe\n\n When a **cookbook_file** resource and a **package** resource\ + \ are both\n called from within the same recipe, use the `flush_cache` attribute\ + \ to\n dump the in-memory Yum cache, and then use the repository immediately to\n\ + \ ensure that the correct package is installed:\n\n ```ruby\n cookbook_file\ + \ '/etc/yum.repos.d/custom.repo' do\n source 'custom'\n mode '0755'\n end\n\ + \n package 'only-in-custom-repo' do\n action :install\n flush_cache [ :before\ + \ ]\n end\n ```\n\n Install repositories from a file, trigger a command, and\ + \ force the\n internal cache to reload\n\n The following example shows how to\ + \ install new Yum repositories from a\n file, where the installation of the repository\ + \ triggers a creation of\n the Yum cache that forces the internal cache for Chef\ + \ Infra Client to\n reload:\n\n ```ruby\n execute 'create-yum-cache' do\n \ + \ command 'yum -q makecache'\n action :nothing\n end\n\n ruby_block 'reload-internal-yum-cache'\ + \ do\n block do\n Chef::Provider::Package::Yum::YumCache.instance.reload\n\ + \ end\n action :nothing\n end\n\n cookbook_file '/etc/yum.repos.d/custom.repo'\ + \ do\n source 'custom'\n mode '0755'\n notifies :run, 'execute[create-yum-cache]',\ + \ :immediately\n notifies :create, 'ruby_block[reload-internal-yum-cache]', :immediately\n\ + \ end\n ```\n\n Use a case statement\n\n The following example shows how a case\ + \ statement can be used to handle a\n situation where an application needs to be\ + \ installed on multiple\n platforms, but where the install directories are different\ + \ paths,\n depending on the platform:\n\n ```ruby\n cookbook_file 'application.pm'\ + \ do\n path case node['platform']\n when 'centos','redhat'\n '/usr/lib/version/1.2.3/dir/application.pm'\n\ + \ when 'arch'\n '/usr/share/version/core_version/dir/application.pm'\n\ + \ else\n '/etc/version/dir/application.pm'\n end\n source \"\ + application-#{node['languages']['perl']['version']}.pm\"\n owner 'root'\n \ + \ group 'root'\n mode '0755'\n end\n ```\n\n Manage dotfiles\n\n The following\ + \ example shows using the **directory** and\n **cookbook_file** resources to manage\ + \ dotfiles. The dotfiles are\n defined by a JSON data structure similar to:\n\n\ + \ ```javascript\n \"files\": {\n \".zshrc\": {\n \"mode\": '0755',\n\ + \ \"source\": \"dot-zshrc\"\n },\n \".bashrc\": {\n \"mode\":\ + \ '0755',\n \"source\": \"dot-bashrc\"\n },\n \".bash_profile\": {\n\ + \ \"mode\": '0755',\n \"source\": \"dot-bash_profile\"\n },\n \ + \ }\n ```\n\n and then the following resources manage the dotfiles:\n\n ```ruby\n\ + \ if u.has_key?('files')\n u['files'].each do |filename, file_data|\n\n directory\ + \ \"#{home_dir}/#{File.dirname(filename)}\" do\n recursive true\n mode\ + \ '0755'\n end if file_data['subdir']\n\n cookbook_file \"#{home_dir}/#{filename}\"\ + \ do\n source \"#{u['id']}/#{file_data['source']}\"\n owner 'u['id']'\n\ + \ group 'group_id'\n mode 'file_data['mode']'\n ignore_failure true\n\ + \ backup 0\n end\n end\n ```\n" + diff --git a/data/infra/resources/cron.yaml b/data/infra/resources/cron.yaml new file mode 100644 index 0000000..2fdbe98 --- /dev/null +++ b/data/infra/resources/cron.yaml @@ -0,0 +1,217 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: cron +resource_description_list: +- markdown: Use the **cron** resource to manage cron entries for time-based job scheduling. + Properties for a schedule will default to * if not provided. The cron resource + requires access to a crontab program, typically cron. +- warning: + markdown: The cron resource should only be used to modify an entry in a crontab + file. The `cron_d` resource directly manages `cron.d` files. This resource ships + in Chef Infra Client 14.4 or later and can also be found in the [cron](https://github.com/chef-cookbooks/cron) + cookbook) for previous Chef Infra Client releases. +syntax_full_code_block: |- + cron 'name' do + command String + day Integer, String # default value: "*" + environment Hash # default value: {} + home String + hour Integer, String # default value: "*" + mailto String + minute Integer, String # default value: "*" + month Integer, String # default value: "*" + path String + shell String + time Symbol + time_out Hash # default value: {} + user String # default value: "root" + weekday Integer, String, Symbol # default value: "*" + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`cron` 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." +- "`command`, `day`, `environment`, `home`, `hour`, `mailto`, `minute`, `month`, `path`, + `shell`, `time`, `time_out`, `user`, and `weekday` are the properties available + to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Create an entry in a cron table file (crontab). If an entry already + exists (but does not match), update that entry to match. (default) + :delete: + markdown: Delete an entry from a cron table file (crontab). +properties_list: +- property: command + ruby_type: String + required: true + description_list: + - markdown: The command to be run, or the path to a file that contains the command + to be run. +- property: day + ruby_type: Integer, String + required: false + default_value: "*" + description_list: + - markdown: The day of month at which the cron entry should run (`1 - 31`). +- property: environment + ruby_type: Hash + required: false + default_value: "{}" + description_list: + - markdown: 'A Hash containing additional arbitrary environment variables under + which the cron job will be run in the form of `({''ENV_VARIABLE'' => ''VALUE''})`. + **Note**: These variables must exist for a command to be run successfully.' +- property: home + ruby_type: String + required: false + description_list: + - markdown: Set the `HOME` environment variable. +- property: hour + ruby_type: Integer, String + required: false + default_value: "*" + description_list: + - markdown: The hour at which the cron entry is to run (`0 - 23`). +- property: mailto + ruby_type: String + required: false + description_list: + - markdown: Set the `MAILTO` environment variable. +- property: minute + ruby_type: Integer, String + required: false + default_value: "*" + description_list: + - markdown: The minute at which the cron entry should run (`0 - 59`). +- property: month + ruby_type: Integer, String + required: false + default_value: "*" + description_list: + - markdown: The month in the year on which a cron entry is to run (`1 - 12`, `jan-dec`, + or `*`). +- property: path + ruby_type: String + required: false + description_list: + - markdown: Set the `PATH` environment variable. +- property: shell + ruby_type: String + required: false + description_list: + - markdown: Set the `SHELL` environment variable. +- property: time + ruby_type: Symbol + required: false + allowed_values: ":annually, :daily, :hourly, :midnight, :monthly, :reboot, :weekly, + :yearly" + description_list: + - markdown: A time interval. +- property: time_out + ruby_type: Hash + required: false + default_value: "{}" + new_in: '15.7' + description_list: + - markdown: |- + A Hash of timeouts in the form of `({'OPTION' => 'VALUE'})`. Accepted valid options are: + - `preserve-status` (BOOL, default: 'false'), + - `foreground` (BOOL, default: 'false'), + - `kill-after` (in seconds), + - `signal` (a name like 'HUP' or a number) +- property: user + ruby_type: String + required: false + default_value: root + description_list: + - markdown: The name of the user that runs the command. If the user property is + changed, the original user for the crontab program continues to run until that + crontab program is deleted. This property is not applicable on the AIX platform. +- property: weekday + ruby_type: Integer, String, Symbol + required: false + default_value: "*" + 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** + + ```ruby + cron 'noop' do + hour '5' + minute '0' + command '/bin/true' + end + ``` + + **Run an entry if a folder exists** + + ```ruby + cron 'ganglia_tomcat_thread_max' do + command "/usr/bin/gmetric + -n 'tomcat threads max' + -t uint32 + -v '/usr/local/bin/tomcat-stat --thread-max'" + only_if { ::File.exist?('/home/jboss') } + end + ``` + + **Run every Saturday, 8:00 AM** + + The following example shows a schedule that will run every hour at 8:00 each Saturday morning, and will then send an email to “admin@example.com” after each run. + + ```ruby + cron 'name_of_cron_entry' do + minute '0' + hour '8' + weekday '6' + mailto 'admin@example.com' + action :create + end + ``` + + **Run once a week** + + ```ruby + cron 'cookbooks_report' do + minute '0' + hour '0' + weekday '1' + user 'chefio' + mailto 'sysadmin@example.com' + home '/srv/supermarket/shared/system' + command %W{ + cd /srv/supermarket/current && + env RUBYLIB="/srv/supermarket/current/lib" + RAILS_ASSET_ID=`git rev-parse HEAD` RAILS_ENV="#{rails_env}" + bundle exec rake cookbooks_report + }.join(' ') + action :create + end + ``` + + **Run only in November** + + The following example shows a schedule that will run at 8:00 PM, every weekday (Monday through Friday), but only in November: + + ```ruby + cron 'name_of_cron_entry' do + minute '0' + hour '20' + day '*' + month '11' + weekday '1-5' + action :create + end + ``` diff --git a/data/infra/resources/cron_access.yaml b/data/infra/resources/cron_access.yaml new file mode 100644 index 0000000..b6684a1 --- /dev/null +++ b/data/infra/resources/cron_access.yaml @@ -0,0 +1,66 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: cron_access +resource_description_list: +- markdown: Use the **cron_access** resource to manage cron's cron.allow and cron.deny + files. +- note: + markdown: This resource previously shipped in the `cron` cookbook as `cron_manage`, + which it can still be used as for backwards compatibility with existing Chef + Infra Client releases. +resource_new_in: '14.4' +syntax_full_code_block: |- + cron_access 'name' do + user String # default value: 'name' unless specified + action Symbol # defaults to :allow if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`cron_access` 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." +- "`user` is the property available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :allow: + markdown: Add the user to the cron.allow file. (default) + :deny: + markdown: Add the user to the cron.deny file. +properties_list: +- property: user + ruby_type: String + required: false + default_value: The resource block's name + 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** + + ```ruby + cron_access 'mike' + ``` + + **Add the mike user to cron.deny** + + ```ruby + cron_access 'mike' do + action :deny + end + ``` + + **Specify the username with the user property** + + ```ruby + cron_access 'Deny the jenkins user access to cron for security purposes' do + user 'jenkins' + action :deny + end + ``` diff --git a/data/infra/resources/cron_d.yaml b/data/infra/resources/cron_d.yaml new file mode 100644 index 0000000..a4f7650 --- /dev/null +++ b/data/infra/resources/cron_d.yaml @@ -0,0 +1,252 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: cron_d +resource_description_list: +- markdown: Use the **cron_d** resource to manage cron job files in the `/etc/cron.d` + directory. +- warning: + markdown: Chef Infra Client also ships with the **cron** resource for managing + the monolithic `/etc/crontab` file on platforms that lack cron.d support. See + the [cron resource](/resources/bundled/cron/) for information on using that resource. +resource_new_in: '14.4' +syntax_description: | + A **cron_d** resource block manages cron.d files. For example, + to get a weekly cookbook report from the Chef Supermarket: + + ```ruby + cron_d 'cookbooks_report' do + action :create + minute '0' + hour '0' + weekday '1' + user 'getchef' + mailto 'sysadmin@example.com' + home '/srv/supermarket/shared/system' + command %W{ + cd /srv/supermarket/current && + env RUBYLIB='/srv/supermarket/current/lib' + RAILS_ASSET_ID=`git rev-parse HEAD` RAILS_ENV=\"#{rails_env}\" + bundle exec rake cookbooks_report + }.join(' ') + end + ``` +syntax_full_code_block: |- + cron_d 'name' do + command String + comment String + cron_name String # default value: 'name' unless specified + day Integer, String # default value: "*" + environment Hash # default value: {} + home String + hour Integer, String # default value: "*" + mailto String + minute Integer, String # default value: "*" + mode String, Integer # default value: "0600" + month Integer, String # default value: "*" + path String + predefined_value String + random_delay Integer + shell String + time_out Hash # default value: {} + user String # default value: "root" + weekday Integer, String, Symbol # default value: "*" + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`cron_d` 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." +- "`command`, `comment`, `cron_name`, `day`, `environment`, `home`, `hour`, `mailto`, + `minute`, `mode`, `month`, `path`, `predefined_value`, `random_delay`, `shell`, + `time_out`, `user`, and `weekday` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: " (default)" + :create_if_missing: + markdown: Add a cron definition file to `/etc/cron.d`, but do not update an existing + file. + :delete: + markdown: Remove a cron definition file from `/etc/cron.d` if it exists. +properties_list: +- property: command + ruby_type: String + required: true + description_list: + - markdown: The command to be run, or the path to a file that contains the command + to be run. +- property: comment + ruby_type: String + required: false + description_list: + - markdown: A comment to place in the cron.d file. +- property: cron_name + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the cron name if it differs from the resource + block's name. +- property: day + ruby_type: Integer, String + required: false + default_value: "*" + description_list: + - markdown: The day of month at which the cron entry should run (`1 - 31`). +- property: environment + ruby_type: Hash + required: false + default_value: "{}" + description_list: + - markdown: 'A Hash containing additional arbitrary environment variables under + which the cron job will be run in the form of `({''ENV_VARIABLE'' => ''VALUE''})`. + **Note**: These variables must exist for a command to be run successfully.' +- property: home + ruby_type: String + required: false + description_list: + - markdown: Set the `HOME` environment variable. +- property: hour + ruby_type: Integer, String + required: false + default_value: "*" + description_list: + - markdown: The hour at which the cron entry is to run (`0 - 23`). +- property: mailto + ruby_type: String + required: false + description_list: + - markdown: Set the `MAILTO` environment variable. +- property: minute + ruby_type: Integer, String + required: false + default_value: "*" + description_list: + - markdown: The minute at which the cron entry should run (`0 - 59`). +- property: mode + ruby_type: String, Integer + required: false + default_value: '0600' + description_list: + - markdown: The octal mode of the generated crontab file. +- property: month + ruby_type: Integer, String + required: false + default_value: "*" + description_list: + - markdown: The month in the year on which a cron entry is to run (`1 - 12`, `jan-dec`, + or `*`). +- property: path + ruby_type: String + required: false + description_list: + - markdown: Set the `PATH` environment variable. +- property: predefined_value + ruby_type: String + required: false + allowed_values: '"@annually", "@daily", "@hourly", "@midnight", "@monthly", "@reboot", + "@weekly", "@yearly"' + description_list: + - markdown: Schedule your cron job with one of the special predefined value instead + of ** * pattern. +- property: random_delay + ruby_type: Integer + required: false + description_list: + - markdown: Set the `RANDOM_DELAY` environment variable in the cron.d file. +- property: shell + ruby_type: String + required: false + description_list: + - markdown: Set the `SHELL` environment variable. +- property: time_out + ruby_type: Hash + required: false + default_value: "{}" + new_in: '15.7' + description_list: + - markdown: |- + A Hash of timeouts in the form of `({'OPTION' => 'VALUE'})`. Accepted valid options are: + - `preserve-status` (BOOL, default: 'false'), + - `foreground` (BOOL, default: 'false'), + - `kill-after` (in seconds), + - `signal` (a name like 'HUP' or a number) +- property: user + ruby_type: String + required: false + default_value: root + description_list: + - markdown: The name of the user that runs the command. +- property: weekday + ruby_type: Integer, String, Symbol + required: false + default_value: "*" + 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** + + ```ruby + cron_d 'noop' do + hour '5' + minute '0' + command '/bin/true' + end + ``` + + **Run an entry if a folder exists** + + ```ruby + cron_d 'ganglia_tomcat_thread_max' do + command "/usr/bin/gmetric + -n 'tomcat threads max' + -t uint32 + -v '/usr/local/bin/tomcat-stat + --thread-max'" + only_if { ::File.exist?('/home/jboss') } + end + ``` + + **Run an entry every Saturday, 8:00 AM** + + ```ruby + cron_d 'name_of_cron_entry' do + minute '0' + hour '8' + weekday '6' + mailto 'admin@example.com' + command '/bin/true' + action :create + end + ``` + + **Run an entry at 8:00 PM, every weekday (Monday through Friday), but only in November** + + ```ruby + cron_d 'name_of_cron_entry' do + minute '0' + hour '20' + day '*' + month '11' + weekday '1-5' + command '/bin/true' + action :create + end + ``` + + **Remove a cron job by name**: + + ```ruby + cron_d 'job_to_remove' do + action :delete + end + ``` diff --git a/data/infra/resources/csh.yaml b/data/infra/resources/csh.yaml new file mode 100644 index 0000000..3890be5 --- /dev/null +++ b/data/infra/resources/csh.yaml @@ -0,0 +1,192 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: csh +resource_description_list: +- markdown: Use the **csh** resource to execute scripts using the csh interpreter. + This resource may also use any of the actions and properties that are available + to the **execute** resource. Commands that are executed with this resource are + (by their nature) not idempotent, as they are typically unique to the environment + in which they are run. Use `not_if` and `only_if` to guard this resource for idempotence. +syntax_full_code_block: |- + csh '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 + user String, Integer + action Symbol # defaults to :run if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`csh` 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." +- "`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 + description_list: + - markdown: Prevent a command from creating a file when that file already exists. +- property: cwd + ruby_type: String + 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 + description_list: + - 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: 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 + 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: 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: user + ruby_type: String, Integer + required: false + description_list: + - 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 new file mode 100644 index 0000000..6f92086 --- /dev/null +++ b/data/infra/resources/directory.yaml @@ -0,0 +1,376 @@ +--- +resource_reference: true +properties_resources_common_windows_security: true +resource_directory_recursive_directories: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: directory +resource_description_list: +- markdown: Use the **directory** resource to manage a directory, which is a hierarchy + of folders that comprises all of the information stored on a computer. The root + directory is the top-level, under which the rest of the directory is organized. + The directory resource uses the name property to specify the path to a location + in a directory. Typically, permission to access that location in the directory + is required. +syntax_description: | + A **directory** resource block declares a directory and the permissions + needed on that directory. For example: + + ```ruby + directory '/etc/apache2' do + owner 'root' + group 'root' + mode '0755' + action :create + end + ``` +syntax_properties_list: +syntax_full_code_block: |- + directory 'name' do + group String, Integer + inherits true, false + mode String, Integer + owner String, Integer + path String # defaults to 'name' if not specified + recursive true, false + rights Hash + action Symbol # defaults to :create if not specified + end +syntax_full_properties_list: +- "`directory` 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." +- "`group`, `mode`, `owner`, `path`, and `recursive` 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. +properties_list: +- 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: 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 directory already exists, the existing mode on the + + directory is used. If `mode` is not specified, the directory 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 directory 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 path to the directory. Using a fully qualified path is recommended, + but is not always required. +- property: recursive + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Create parent directories recursively, or delete directory and all children + recursively. For the owner, group, and mode properties, the value of this property + 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.' +examples: | + Create a directory + + ```ruby + directory '/tmp/something' do + owner 'root' + group 'root' + mode '0755' + action :create + end + + ``` + + Create a directory in Microsoft Windows + + ```ruby + directory "C:\\tmp\\something" do + rights :full_control, "DOMAIN\\User" + inherits false + action :create + end + ``` + + or: + + ```ruby + directory 'C:\tmp\something' do + rights :full_control, 'DOMAIN\User' + inherits false + action :create + end + ``` + +
+

Note

+
+

The difference between the two previous examples is the single- versus + double-quoted strings, where if the double quotes are used, the backslash character + (\) must be escaped using the Ruby escape character (which is a + backslash).

+
+
+ + Create a directory recursively: + + ```ruby + %w{dir1 dir2 dir3}.each do |dir| + directory "/tmp/mydirs/#{dir}" do + mode '0755' + owner 'root' + group 'root' + action :create + recursive true + end + end + ``` + + Delete a directory: + + ```ruby + directory '/tmp/something' do + recursive true + action :delete + end + ``` + + Set directory permissions using a variable + + The following example + shows how read/write/execute permissions can be + set using a variable named + `user_home`, and then for owners and groups + on any matching node: + + ```ruby + user_home = "/#{node[:matching_node][:user]}" + + directory user_home do + owner 'node[:matching_node][:user]' + group 'node[:matching_node][:group]' + mode '0755' + action :create + end + ``` + + where `matching_node` represents + a type of node. For example, if the + `user_home` variable specified `{node[:nginx]...}`, + a recipe might look + similar to: + + ```ruby + user_home = "/#{node[:nginx][:user]}" + + directory user_home do + owner 'node[:nginx][:user]' + group 'node[:nginx][:group]' + mode '0755' + action :create + end + ``` + + Set directory permissions for a specific type of node + + The following example shows how permissions can be set for the + `/certificates` directory on any node that is running Nginx. In this + example, permissions are being set for the `owner` and `group` + properties as `root`, and then read/write permissions are granted to the + root. + + ```ruby + directory "#{node[:nginx][:dir]}/shared/certificates" do + owner 'root' + group 'root' + mode '0755' + recursive true + end + ``` + + + Reload the configuration + + The following example shows how to reload the configuration of a + chef-client using the **remote_file** resource to: + + - using an if statement to check whether the plugins on a node are the + latest versions + - identify the location from which Ohai plugins are stored + - using the `notifies` property and a **ruby_block** resource to + trigger an update (if required) and to then reload the client.rb + file. + + ```ruby + directory 'node[:ohai][:plugin_path]' do + owner 'chef' + recursive true + end + + ruby_block 'reload_config' do + block do + Chef::Config.from_file('/etc/chef/client.rb') + end + action :nothing + end + + if node[:ohai].key?(:plugins) + node[:ohai][:plugins].each do |plugin| + remote_file node[:ohai][:plugin_path] +"/#{plugin}" do + source plugin + owner 'chef' + notifies :run, 'ruby_block[reload_config]', :immediately + end + end + end + ``` + + Manage dotfiles + + The following example shows using the **directory** and + **cookbook_file** resources to manage dotfiles. The dotfiles are + defined by a JSON data structure similar to: + + ```javascript + "files": { + ".zshrc": { + "mode": '0755', + "source": "dot-zshrc" + }, + ".bashrc": { + "mode": '0755', + "source": "dot-bashrc" + }, + ".bash_profile": { + "mode": '0755', + "source": "dot-bash_profile" + }, + } + ``` + + and then the following resources manage the dotfiles: + + ```ruby + if u.has_key?('files') + u['files'].each do |filename, file_data| + + directory "#{home_dir}/#{File.dirname(filename)}" do + recursive true + mode '0755' + end if file_data['subdir'] + + cookbook_file "#{home_dir}/#{filename}" do + source "#{u['id']}/#{file_data['source']}" + owner 'u['id']' + group 'group_id' + mode 'file_data['mode']' + ignore_failure true + backup 0 + end + end + ``` diff --git a/data/infra/resources/dmg_package.yaml b/data/infra/resources/dmg_package.yaml new file mode 100644 index 0000000..9340c80 --- /dev/null +++ b/data/infra/resources/dmg_package.yaml @@ -0,0 +1,162 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: dmg_package +resource_description_list: +- markdown: Use the **dmg_package** resource to install a package from a .dmg file. + The resource will retrieve the dmg file from a remote URL, mount it using macOS' + `hdidutil`, copy the application (.app directory) to the specified destination + (`/Applications`), and detach the image using `hdiutil`. The dmg file will be + stored in the `Chef::Config[:file_cache_path]`. +resource_new_in: '14.0' +syntax_full_code_block: |- + dmg_package 'name' do + accept_eula true, false # default value: false + allow_untrusted true, false # default value: false + app String # default value: 'name' unless specified + checksum String + destination String # default value: "/Applications" + dmg_name String # default value: The value passed for the application name. + dmg_passphrase String + file String + headers Hash + owner String, Integer + package_id String + source String + type String # default value: "app" + volumes_dir String # default value: The value passed for the application name. + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`dmg_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_eula`, `allow_untrusted`, `app`, `checksum`, `destination`, `dmg_name`, + `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: +- property: accept_eula + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Specify whether to accept the EULA. Certain dmg files require acceptance + of EULA before mounting. +- property: allow_untrusted + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Allow installation of packages that do not have trusted certificates. +- property: app + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: The name of the application as it appears in the `/Volumes` directory + if it differs from the resource block's name. +- property: checksum + ruby_type: String + required: false + description_list: + - markdown: The sha256 checksum of the `.dmg` file to download. +- property: destination + ruby_type: String + required: false + default_value: "/Applications" + description_list: + - markdown: The directory to copy the `.app` into. +- property: dmg_name + ruby_type: String + required: false + default_value: The value passed for the application name. + description_list: + - markdown: The name of the `.dmg` file if it differs from that of the app, or if + the name has spaces. +- property: dmg_passphrase + ruby_type: String + required: false + description_list: + - markdown: Specify a passphrase to be used to decrypt the `.dmg` file during the + mount process. +- property: file + ruby_type: String + required: false + description_list: + - markdown: The absolute path to the `.dmg` 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: owner + ruby_type: String, Integer + required: false + description_list: + - markdown: The user that should own the package installation. +- property: package_id + ruby_type: String + required: false + description_list: + - markdown: The package ID that is registered with `pkgutil` when a `pkg` or `mpkg` + is installed. +- property: source + ruby_type: String + required: false + description_list: + - markdown: The remote URL that is used to download the `.dmg` file, if specified. +- property: type + ruby_type: String + required: false + default_value: app + allowed_values: '"app", "mpkg", "pkg"' + description_list: + - markdown: The type of package. +- property: volumes_dir + ruby_type: String + required: false + default_value: The value passed for the application name. + 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**: + + ```ruby + dmg_package 'Google Chrome' do + dmg_name 'googlechrome' + source 'https://dl-ssl.google.com/chrome/mac/stable/GGRM/googlechrome.dmg' + checksum '7daa2dc5c46d9bfb14f1d7ff4b33884325e5e63e694810adc58f14795165c91a' + action :install + end + ``` + + **Install VirtualBox from the .mpkg**: + + ```ruby + dmg_package 'Virtualbox' do + source 'http://dlc.sun.com.edgesuite.net/virtualbox/4.0.8/VirtualBox-4.0.8-71778-OSX.dmg' + type 'mpkg' + end + ``` + + **Install pgAdmin and automatically accept the EULA**: + + ```ruby + dmg_package 'pgAdmin3' do + source 'http://wwwmaster.postgresql.org/redir/198/h/pgadmin3/release/v1.12.3/osx/pgadmin3-1.12.3.dmg' + checksum '9435f79d5b52d0febeddfad392adf82db9df159196f496c1ab139a6957242ce9' + accept_eula true + end + ``` diff --git a/data/infra/resources/dnf_package.yaml b/data/infra/resources/dnf_package.yaml new file mode 100644 index 0000000..2cc66a9 --- /dev/null +++ b/data/infra/resources/dnf_package.yaml @@ -0,0 +1,164 @@ +--- +resource_reference: true +multi_package_resource: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: dnf_package +resource_description_list: +- markdown: Use the **dnf_package** resource to install, upgrade, and remove packages + with DNF for Fedora and RHEL 8+. The dnf_package resource is able to resolve provides + data for packages much like DNF can do when it is run from the command line. This + allows a variety of options for installing packages, like minimum versions, virtual + provides and library names. +- notes_resource_based_on_package: true +resource_new_in: '12.18' +syntax_description: | + A **dnf_package** resource block manages a package on a node, + typically by installing it. The simplest use of the **dnf_package** resource is: + + ```ruby + dnf_package ''package_name'' + ``` + + which will install the named package using all of the default options + and the default action (`:install`). +syntax_full_code_block: |- + dnf_package 'name' do + allow_downgrade true, false # default value: true + arch String, Array + environment Hash # default value: {} + flush_cache Hash # default value: {"before"=>false, "after"=>false} + options String, Array + package_name String, Array + source String + timeout String, Integer + version String, Array + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`dnf_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." +- "`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 + :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: Change the installed package. + :lock: + 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 + required: false + default_value: 'true' + description_list: + - markdown: Allow downgrading a package to satisfy requested version requirements. +- property: arch + ruby_type: String, Array + required: false + description_list: + - markdown: The architecture of the package to be installed or upgraded. This value + can also be passed as part of the package name. +- 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: Hash + required: false + default_value: '{"before"=>false, "after"=>false}' + description_list: + - markdown: | + Flush the in-memory cache before or after a DNF operation that installs, + upgrades, or removes a package. DNF automatically synchronizes remote metadata + to a local cache. The Chef Infra Client creates a copy of the local cache, and then + stores it in-memory during the Chef Infra Client run. The in-memory cache allows packages + to be installed during the Chef Infra Client run without the need to continue synchronizing + the remote metadata to the local cache while the Chef Infra Client run is in-progress. + + ```ruby + dnf_package 'some_package' do + #... + flush_cache [ :before] + #... + end + ``` + - note: + markdown: | + The `flush_cache` property does not flush the local DNF cache! Use + DNF tools to clean the local DNF cache. For example: + - `dnf clean metadata` + - `dnf clean packages` + - `dnf clean all` +- property: options + ruby_type: String, Array + required: false + description_list: + - 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: 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: The optional path to a package on the local file system. +- property: timeout + ruby_type: String, Integer + required: false + description_list: + - markdown: The amount of time (in seconds) to wait before timing out. +- property: version + ruby_type: String, Array + required: false + description_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\ + \ ```\n\n Install a minimum version using the default action\n\n ```ruby\n \ + \ dnf_package 'netpbm'\n ```\n\n To install a package\n\n ```ruby\n dnf_package\ + \ 'netpbm' do\n action :install\n end\n ```\n\n To install a partial minimum\ + \ version\n\n ```ruby\n dnf_package 'netpbm >= 10'\n ```\n\n To install a specific\ + \ architecture\n\n ```ruby\n dnf_package 'netpbm' do\n arch 'i386'\n end\n\ + \ ```\n\n or:\n\n ```ruby\n dnf_package 'netpbm.x86_64'\n ```\n\n To install\ + \ a specific version-release\n\n ```ruby\n dnf_package 'netpbm' do\n version\ + \ '10.35.58-8.el5'\n end\n ```\n\n To install a specific version (even when older\ + \ than the current)\n\n ```ruby\n dnf_package 'tzdata' do\n version '2011b-1.el5'\n\ + \ end\n ```\n\n Handle cookbook_file and dnf_package resources in the same recipe\n\ + \n When a **cookbook_file** resource and a **dnf_package** resource are\n both\ + \ called from within the same recipe, use the `flush_cache` attribute\n to dump\ + \ the in-memory DNF cache, and then use the repository immediately\n to ensure\ + \ that the correct package is installed:\n\n ```ruby\n cookbook_file '/etc/yum.repos.d/custom.repo'\ + \ do\n source 'custom'\n mode '0755'\n end\n\n dnf_package 'only-in-custom-repo'\ + \ do\n action :install\n flush_cache [ :before ]\n end\n ```\n" + diff --git a/data/infra/resources/dpkg_package.yaml b/data/infra/resources/dpkg_package.yaml new file mode 100644 index 0000000..19aa1f5 --- /dev/null +++ b/data/infra/resources/dpkg_package.yaml @@ -0,0 +1,121 @@ +--- +resource_reference: true +multi_package_resource: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: dpkg_package +resource_description_list: +- markdown: Use the **dpkg_package** resource to manage packages for the dpkg platform. + When a package is installed from a local file, it must be added to the node using + the **remote_file** or **cookbook_file** resources. +syntax_full_code_block: |- + dpkg_package 'name' do + allow_downgrade true, false # default value: true + environment Hash # default value: {} + options String, Array + package_name String, Array + response_file String + response_file_variables Hash # default value: {} + source String, Array + timeout String, Integer + version String, Array + action Symbol # defaults to :install if not specified + end +syntax_description: 'A **dpkg_package** resource block manages a package on a node, + typically by installing it. The simplest use of the **dpkg_package** + resource is: + + ```ruby + dpkg_package ''package_name'' + ``` + which will install the named package using all of the default options + and the default action (`:install`).' +syntax_properties_list: +syntax_full_properties_list: +- "`dpkg_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." +- "`allow_downgrade`, `environment`, `options`, `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 + :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 + 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: options + ruby_type: String, Array + required: false + description_list: + - 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: An optional property to set the package name if it differs from the + resource block's name. +- property: response_file + ruby_type: String + required: false + description_list: + - markdown: The direct path to the file used to pre-seed a package. +- property: response_file_variables + ruby_type: Hash + required: false + default_value: "{}" + description_list: + - markdown: A Hash of response file variables in the form of {'VARIABLE' => 'VALUE'}. +- property: source + ruby_type: String, Array + required: false + description_list: + - markdown: The path to a package in the local file system. +- property: timeout + ruby_type: String, Integer + required: false + description_list: + - markdown: The amount of time (in seconds) to wait before timing out. +- property: version + ruby_type: String, Array + 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\ + \ end\n ```\n" + diff --git a/data/infra/resources/dsc_resource.yaml b/data/infra/resources/dsc_resource.yaml new file mode 100644 index 0000000..8a5a802 --- /dev/null +++ b/data/infra/resources/dsc_resource.yaml @@ -0,0 +1,321 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: dsc_resource +resource_description_list: +- shortcode: resources_common_powershell.md +- shortcode: resources_common_powershell_dsc.md +- markdown: The dsc_resource resource allows any DSC resource to be used in a recipe, + as well as any custom resources that have been added to your Windows PowerShell + environment. Microsoft frequently adds new resources to the DSC resource collection. +- warning: + markdown: "Using the **dsc_resource** has the following requirements:\n\n- Windows\ + \ Management Framework (WMF) 5.0 (or higher)\n- The **dsc_resource** resource can only\ + \ use binary- or script-based\n resources. Composite DSC resources may not\ + \ be used.\n\n This is because composite resources aren't \"real\" resources\ + \ from the\n perspective of the Local Configuration Manager (LCM). Composite\n\ + \ resources are used by the \"configuration\" keyword from the\n `PSDesiredStateConfiguration`\ + \ module, and then evaluated in that\n context. When using DSC to create\ + \ the configuration document (the\n Managed Object Framework (MOF) file)\ + \ from the configuration command,\n the composite resource is evaluated.\ + \ Any individual resources from\n that composite resource are written into\ + \ the Managed Object\n Framework (MOF) document. As far as the Local Configuration\ + \ Manager\n (LCM) is concerned, there is no such thing as a composite resource.\n\ + \ Unless that changes, the **dsc_resource** resource and/or\n `Invoke-DscResource`\ + \ command cannot directly use them." +syntax_description: "A **dsc_resource** resource block allows DSC resources to be\ + \ used in a\nChef recipe. For example, the DSC `Archive` resource:\n\n```powershell\n\ + Archive ExampleArchive {\n Ensure = \"Present\"\n Path = \"C:\\Users\\Public\\\ + Documents\\example.zip\"\n Destination = \"C:\\Users\\Public\\Documents\\ExtractionPath\"\ + \n}\n```\n\nand then the same **dsc_resource** with Chef:\n\n```ruby\ndsc_resource\ + \ 'example' do\n resource :archive\n property :ensure, 'Present'\n property\ + \ :path, \"C:\\Users\\Public\\Documents\\example.zip\"\n property :destination,\ + \ \"C:\\Users\\Public\\Documents\\ExtractionPath\"\n end```" +resource_new_in: '12.2' +syntax_full_code_block: |- + dsc_resource 'name' do + module_version String + reboot_action Symbol # default value: :nothing + timeout Integer + action Symbol # defaults to :run if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`dsc_resource` 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." +- "`module_version`, `reboot_action`, and `timeout` are the properties available to + this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :run: + markdown: " (default)" +properties_list: +- property: module_name + ruby_type: String + required: false + description_list: + - markdown: 'The name of the module from which a DSC resource originates. If this + property is not specified, it will be inferred.' +- property: module_version + ruby_type: String + required: false + new_in: '12.21' + description_list: + - markdown: The version number of the module to use. PowerShell 5.0.10018.0 (or + higher) supports having multiple versions of a module installed. This should + be specified along with the `module_name` property. +- property: property + ruby_type: String + description_list: + - markdown: |- + A property from a Desired State Configuration (DSC) resource. + Use this property multiple times, one for each property in the Desired State Configuration (DSC) resource. + The format for this property must follow `property :dsc_property_name, "property_value"` for each DSC property added to the resource block. + The `:dsc_property_name` must be a symbol. + + Use the following Ruby types to define property_value: + + | **Ruby** | **PowerShell** | + |---------------------------------------|----------------| + | `:array` | `Object[]` | + | `Chef::Util::Powershell:PSCredential` | `PSCredential` | + | `False` | `bool($false)` | + | `Fixnum` | `Integer` | + | `Float` | `Double` | + | `Hash` | `Hashtable` | + | `True` | `bool($true)` | + + These are converted into the corresponding Windows PowerShell type during a Chef Infra Client run. + +- property: reboot_action + ruby_type: Symbol + required: false + default_value: ":nothing" + new_in: '12.6' + allowed_values: ":nothing, :reboot_now, :request_reboot" + description_list: + - markdown: Use to request an immediate reboot or to queue a reboot using the :reboot_now + (immediate reboot) or :request_reboot (queued reboot) actions built into the + reboot resource. +- property: resource + ruby_type: Symbol + required: false + description_list: + - markdown: 'The name of the DSC resource. This value is case-insensitive and + + must be a symbol that matches the name of the DSC resource. + + + For built-in DSC resources, use the following values: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription
:archiveUse to unpack + archive (.zip) files.
:environmentUse to manage + system environment variables.
:fileUse to manage + files and directories.
:groupUse to manage + local groups.
:logUse to log + configuration messages.
:packageUse to install + and manage packages.
:registryUse to manage + registry keys and registry key values.
:scriptUse to run + PowerShell script blocks.
:serviceUse to manage + services.
:userUse to manage + local user accounts.
:windowsfeatureUse to add + or remove Windows features and roles.
:windowsoptionalfeatureUse to configure Microsoft Windows optional features.
:windowsprocessUse to configure + Windows processes.
+ + + Any DSC resource may be used in a Chef recipe. For example, the DSC + + Resource Kit contains resources for [configuring Active Directory + + components](http://www.powershellgallery.com/packages/xActiveDirectory/2.8.0.0), + + such as `xADDomain`, `xADDomainController`, and `xADUser`. Assuming + + that these resources are available to Chef Infra Client, the + + corresponding values for the `resource` attribute would be: + + `:xADDomain`, `:xADDomainController`, and `xADUser`.' +- 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:\\\ + Users\\Public\\Documents\\example.zip'\n property :destination, 'C:\\Users\\\ + Public\\Documents\\ExtractionPath'\n end\n ```\n\n Manage users and groups\n\ + \n ```ruby\n dsc_resource 'demogroupadd' do\n resource :group\n property\ + \ :groupname, 'demo1'\n property :ensure, 'present'\n end\n\n dsc_resource\ + \ 'useradd' do\n resource :user\n property :username, 'Foobar1'\n property\ + \ :fullname, 'Foobar1'\n property :password, ps_credential('P@assword!')\n \ + \ property :ensure, 'present'\n end\n\n dsc_resource 'AddFoobar1ToUsers' do\n\ + \ resource :Group\n property :GroupName, 'demo1'\n property :MembersToInclude,\ + \ ['Foobar1']\n end\n ```\n\n Create and register a windows service\n\n The\ + \ following example creates a windows service, defines it's execution\n path, and\ + \ prevents windows from starting the service in case the\n executable is not at\ + \ the defined location:\n\n ```ruby\n dsc_resource 'NAME' do\n resource :service\n\ + \ property :name, 'NAME'\n property :startuptype, 'Disabled'\n property\ + \ :path, 'D:\\\\Sites\\\\Site_name\\file_to_run.exe'\n property :ensure, 'Present'\n\ + \ property :state, 'Stopped'\n end\n ```\n\n Create a test message queue\n\ + \n The following example creates a file on a node (based on one that is\n located\ + \ in a cookbook), unpacks the `MessageQueue.zip` Windows\n PowerShell module, and\ + \ then uses the **dsc_resource** to ensure that\n Message Queuing (MSMQ) sub-features\ + \ are installed, a test queue is\n created, and that permissions are set on the\ + \ test queue:\n\n ```ruby\n cookbook_file 'cMessageQueue.zip' do\n path \"\ + #{Chef::Config[:file_cache_path]}\\\\MessageQueue.zip\"\n action :create_if_missing\n\ + \ end\n\n windows_zipfile \"#{ENV['PROGRAMW6432']}\\\\WindowsPowerShell\\\\Modules\"\ + \ do\n source \"#{Chef::Config[:file_cache_path]}\\\\MessageQueue.zip\"\n \ + \ action :unzip\n end\n\n dsc_resource 'install-sub-features' do\n resource\ + \ :windowsfeature\n property :ensure, 'Present'\n property :name, 'msmq'\n\ + \ property :IncludeAllSubFeature, true\n end\n\n dsc_resource 'create-test-queue'\ + \ do\n resource :cPrivateMsmqQueue\n property :ensure, 'Present'\n property\ + \ :name, 'Test_Queue'\n end\n\n dsc_resource 'set-permissions' do\n resource\ + \ :cPrivateMsmqQueuePermissions\n property :ensure, 'Present'\n property :name,\ + \ 'Test_Queue_Permissions'\n property :QueueNames, 'Test_Queue'\n property\ + \ :ReadUsers, node['msmq']['read_user']\n end\n ```\n\n Example to show usage\ + \ of module properties\n\n ```ruby\n dsc_resource 'test-cluster' do\n resource\ + \ :xCluster\n module_name 'xFailOverCluster'\n module_version '1.6.0.0'\n\ + \ property :name, 'TestCluster'\n property :staticipaddress, '10.0.0.3'\n\ + \ property :domainadministratorcredential, ps_credential('abcd')\n end\n ```\n" diff --git a/data/infra/resources/dsc_script.yaml b/data/infra/resources/dsc_script.yaml new file mode 100644 index 0000000..a3b0db1 --- /dev/null +++ b/data/infra/resources/dsc_script.yaml @@ -0,0 +1,278 @@ +--- +resource_reference: true +ps_credential_helper: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: dsc_script +resource_description_list: +- shortcode: resources_common_powershell.md +- shortcode: resources_common_powershell_dsc.md +- markdown: |- + Many DSC resources are comparable to built-in Chef Infra Client resources. For example, both DSC and Chef Infra Client + have **file**, **package**, and **service** resources. The **dsc_script** resource is most useful for those DSC resources that do not have a direct comparison to a + resource in Chef Infra Client, such as the DSC Archive resource, a custom DSC resource, an existing DSC script that performs an important + task, and so on. Use the `dsc_script` resource to embed the code that defines a DSC configuration directly within a Chef Infra Client recipe. +- note: + markdown: 'Windows PowerShell 4.0 is required for using the **dsc_script** + resource with Chef Infra.' +- note: + markdown: 'The WinRM service must be enabled. (Use `winrm quickconfig` to enable + the service.)' +- warning: + markdown: The **dsc_script** resource may not be used in the same run-list with + the **dsc_resource**. This is because the **dsc_script** resource + requires that `RefreshMode` in the Local Configuration Manager be set to + `Push`, whereas the **dsc_resource** resource requires it to be set to + `Disabled`. +- warning: + markdown: The **dsc_script** resource is only available on 64-bit versions of Chef Infra Client. +syntax_description: | + A **dsc_script** resource block embeds the code that defines a DSC configuration directly within a Chef recipe: + + ```ruby + dsc_script 'get-dsc-resource-kit' do + code <<-EOH + Archive reskit + { + ensure = 'Present' + path = "#{Chef::Config[:file_cache_path]}\\DSCResourceKit620082014.zip" + destination = "#{ENV['PROGRAMW6432']}\\WindowsPowerShell\\Modules" + } + EOH + end + ``` + + where + + - the **remote_file** resource is first used to download the `DSCResourceKit620082014.zip` file. + + +syntax_full_code_block: |- + dsc_script 'name' do + cwd String + environment Hash + flags Hash + timeout Integer + action Symbol # defaults to :run if not specified + end +syntax_properties_list: +- 'the **remote_file** resource is first used to download the + `DSCResourceKit620082014.zip` file.' +syntax_full_properties_list: +- "`dsc_script` 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." +- "`cwd`, `environment`, `flags`, and `timeout` are the properties available to this + resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :run: + markdown: " (default)" +properties_list: +- property: code + ruby_type: String + required: false + description_list: + - markdown: 'The code for the DSC configuration script. This property may not be + + used in conjunction with the `command` property.' +- property: command + ruby_type: String + required: false + description_list: + - markdown: 'The path to a valid Windows PowerShell data file that contains the + + DSC configuration script. This data file must be capable of running + + independently of Chef and must generate a valid DSC configuration. + + This property may not be used in conjunction with the `code` + + property.' +- property: configuration_data + ruby_type: String + required: false + description_list: + - markdown: 'The configuration data for the DSC script. The configuration data + + must be [a valid Windows PowerShell data + + file](https://docs.microsoft.com/en-us/powershell/). + + This property may not be used in conjunction with the + + `configuration_data_script` property.' +- property: configuration_data_script + ruby_type: String + required: false + description_list: + - markdown: 'The path to a valid Windows PowerShell data file that also contains + + a node called `localhost`. This property may not be used in + + conjunction with the `configuration_data` property.' +- property: configuration_name + ruby_type: String + required: false + description_list: + - markdown: 'The name of a valid Windows PowerShell cmdlet. The name may only + + contain letter (a-z, A-Z), number (0-9), and underscore (_) + + characters and should start with a letter. The name may not be null + + or empty. This property may not be used in conjunction with the + + `code` property.' +- property: cwd + ruby_type: String + required: false + description_list: + - markdown: The current working directory. +- 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). +- property: flags + ruby_type: Hash + required: false + description_list: + - markdown: 'Pass parameters to the DSC script that is specified by the `command` + + property. Parameters are defined as key-value pairs, where the value + + of each key is the parameter to pass. This property may not be used + + in the same recipe as the `code` property. For example: + + `flags ({ :EditorChoice => ''emacs'', :EditorFlags => ''--maximized'' })`.' +- property: imports + ruby_type: Array + required: false + description_list: + - warning: + markdown: This property **MUST** be used with the `code` attribute. + - markdown: 'Use to import DSC resources from a module. + + + To import all resources from a module, specify only the module name: + + + ```ruby + + imports ''module_name'' + + ``` + + + To import specific resources, specify the module name, and then + + specify the name for each resource in that module to import: + + + ```ruby + + imports ''module_name'', ''resource_name_a'', ''resource_name_b'', ... + + ``` + + + For example, to import all resources from a module named + + `cRDPEnabled`: + + + ```ruby + + imports ''cRDPEnabled'' + + ``` + + + To import only the `PSHOrg_cRDPEnabled` resource: + + + ```ruby + + imports ''cRDPEnabled'', ''PSHOrg_cRDPEnabled'' + + ```' +- property: timeout + ruby_type: Integer + required: false + description_list: + - markdown: The amount of time (in seconds) a command is to wait before timing out. +properties_multiple_packages: false +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 +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\ + \ 'texteditor'\n {\n Name = 'EDITOR'\n Value = 'c:\\\\emacs\\\\bin\\\ + \\emacs.exe'\n }\n EOH\n end\n ```\n\n Specify DSC code using a Windows\ + \ PowerShell data file\n\n Use the `command` property to specify the path to a\ + \ Windows PowerShell\n data file. For example, the following Windows PowerShell\ + \ script defines\n the `DefaultEditor`:\n\n ```powershell\n Configuration 'DefaultEditor'\n\ + \ {\n Environment 'texteditor'\n {\n Name = 'EDITOR'\n Value\ + \ = 'c:\\emacs\\bin\\emacs.exe'\n }\n }\n ```\n\n Use the following recipe\ + \ to specify the location of that data file:\n\n ```ruby\n dsc_script 'DefaultEditor'\ + \ do\n command 'c:\\dsc_scripts\\emacs.ps1'\n end\n ```\n\n Pass parameters\ + \ to DSC configurations\n\n If a DSC script contains configuration data that takes\ + \ parameters, those\n parameters may be passed using the `flags` property. For\ + \ example, the\n following Windows PowerShell script takes parameters for the\n\ + \ `EditorChoice` and `EditorFlags` settings:\n\n ```powershell\n $choices =\ + \ @{'emacs' = 'c:\\emacs\\bin\\emacs';'vi' = 'c:\\vim\\vim.exe';'powershell' = 'powershell_ise.exe'}\n\ + \ Configuration 'DefaultEditor'\n {\n [CmdletBinding()]\n \ + \ param\n (\n $EditorChoice,\n $EditorFlags = ''\n\ + \ )\n Environment 'TextEditor'\n {\n Name = 'EDITOR'\n\ + \ Value = \"$($choices[$EditorChoice]) $EditorFlags\"\n }\n \ + \ }\n ```\n\n Use the following recipe to set those parameters:\n\n ```ruby\n\ + \ dsc_script 'DefaultEditor' do\n flags ({ :EditorChoice => 'emacs', :EditorFlags\ + \ => '--maximized' })\n command 'c:\\dsc_scripts\\editors.ps1'\n end\n ```\n\ + \n Use custom configuration data\n\n Configuration data in DSC scripts may be\ + \ customized from a recipe. For\n example, scripts are typically customized to\ + \ set the behavior for\n Windows PowerShell credential data types. Configuration\ + \ data may be\n specified in one of three ways:\n\n - By using the `configuration_data`\ + \ attribute\n - By using the `configuration_data_script` attribute\n - By\ + \ specifying the path to a valid Windows PowerShell data file\n\n The following\ + \ example shows how to specify custom configuration data\n using the `configuration_data`\ + \ property:\n\n ```ruby\n dsc_script 'BackupUser' do\n configuration_data\ + \ <<-EOH\n @{\n AllNodes = @(\n @{\n NodeName =\ + \ \"localhost\";\n PSDscAllowPlainTextPassword = $true\n })\n\ + \ }\n EOH\n code <<-EOH\n $user = 'backup'\n $password = ConvertTo-SecureString\ + \ -String \"YourPass$(random)\" -AsPlainText -Force\n $cred = New-Object -TypeName\ + \ System.Management.Automation.PSCredential -ArgumentList $user, $password\n\n \ + \ User $user\n {\n UserName = $user\n Password = $cred\n\ + \ Description = 'Backup operator'\n Ensure = \"Present\"\n \ + \ Disabled = $false\n PasswordNeverExpires = $true\n PasswordChangeRequired\ + \ = $false\n }\n EOH\n end\n ```\n\n The following example shows how\ + \ to specify custom configuration data\n using the `configuration_name` property.\ + \ For example, the following\n Windows PowerShell script defines the `vi` configuration:\n\ + \n ```powershell\n Configuration 'emacs'\n {\n Environment 'TextEditor'\n\ + \ {\n Name = 'EDITOR'\n Value = 'c:\\emacs\\bin\\emacs.exe'\n\ + \ }\n }\n\n Configuration 'vi'\n {\n Environment 'TextEditor'\n \ + \ {\n Name = 'EDITOR'\n Value = 'c:\\vim\\bin\\vim.exe'\n }\n\ + \ }\n ```\n\n Use the following recipe to specify that configuration:\n\n ```\ + \ ruby\n dsc_script 'EDITOR' do\n configuration_name 'vi'\n command 'C:\\\ + dsc_scripts\\editors.ps1'\n end\n ```\n\n Using DSC with other Chef resources\n\ + \n The **dsc_script** resource can be used with other resources. The\n following\ + \ example shows how to download a file using the\n **remote_file** resource, and\ + \ then uncompress it using the DSC\n `Archive` resource:\n\n ```ruby\n remote_file\ + \ \"#{Chef::Config[:file_cache_path]}\\\\DSCResourceKit620082014.zip\" do\n source\ + \ 'http://gallery.technet.microsoft.com/DSC-Resource-Kit-All-c449312d/file/124481/1/DSC%20Resource%20Kit%20Wave%206%2008282014.zip'\n\ + \ end\n\n dsc_script 'get-dsc-resource-kit' do\n code <<-EOH\n Archive\ + \ reskit\n {\n ensure = 'Present'\n path = \"#{Chef::Config[:file_cache_path]}\\\ + \\DSCResourceKit620082014.zip\"\n destination = \"#{ENV['PROGRAMW6432']}\\\ + \\WindowsPowerShell\\\\Modules\"\n }\n EOH\n end\n ```\n" + diff --git a/data/infra/resources/execute.yaml b/data/infra/resources/execute.yaml new file mode 100644 index 0000000..350297c --- /dev/null +++ b/data/infra/resources/execute.yaml @@ -0,0 +1,687 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: execute +resource_description_list: +- markdown: Use the **execute** resource to execute a single command. Commands that + are executed with this resource are (by their nature) not idempotent, as they + are typically unique to the environment in which they are run. Use `not_if` and + `only_if` to guard this resource for idempotence. +- note: + markdown: Use the **script** resource to execute a script using a specific interpreter + (Ruby, Python, Perl, csh, or Bash). +syntax_description: "An **execute** resource block typically executes a single command\ + \ that\nis unique to the environment in which a recipe will run. Some\n**execute**\ + \ resource commands are run by themselves, but often they are\nrun in combination\ + \ with other Chef resources. For example, a single\ncommand that is run by itself:\n\ + \n```ruby\nexecute 'apache_configtest' do\n command '/usr/sbin/apachectl configtest'\n\ + end\n```" +syntax_properties_list: +- '`''/usr/sbin/apachectl configtest''` is a command that tests if the + + configuration files for Apache are valid. + + + Commands are often run in combination with other Chef resources. The + + following example shows the **template** resource run with the + + **execute** resource to add an entry to a LDAP Directory Interchange + + Format (LDIF) file: + + + ```ruby + + execute ''slapadd'' do command ''slapadd < /tmp/something.ldif'' creates ''/var/lib/slapd/uid.bdb'' + action :nothing + + end + + + template ''/tmp/something.ldif'' do source ''something.ldif'' notifies :run, ''execute[slapadd]'', + :immediately + + end + + ``` + + + where' +- '`''/tmp/something.ldif''` specifies the location of the file' +- '`''something.ldif''` specifies template file from which `/tmp/something.ldif` is + created' +- '`''slapadd < /tmp/something.ldif''` is the command that is run' +- '`/var/lib/slapd/uid.bdb` prevents the **execute** resource block from running if + 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 + default_env true, false # default value: false + domain String + elevated true, false # default value: false + environment Hash + group String, Integer + input 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_full_properties_list: +- "`execute` 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." +- "`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: + :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: 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 + description_list: + - markdown: Prevent a command from creating a file when that file already exists. +- property: cwd + ruby_type: String + 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: 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: 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: 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 + 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: 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: user + ruby_type: String, Integer + required: false + description_list: + - 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 + introduced: '15.1' + updated: '19.0' +examples: | + **Run a command upon notification**: + + ```ruby + execute 'slapadd' do + command 'slapadd < /tmp/something.ldif' + creates '/var/lib/slapd/uid.bdb' + + action :nothing + end + + template '/tmp/something.ldif' do + source 'something.ldif' + + notifies :run, 'execute[slapadd]', :immediately + end + ``` + + **Run a touch file only once while running a command**: + + ```ruby + execute 'upgrade script' do + command 'php upgrade-application.php && touch /var/application/.upgraded' + + creates '/var/application/.upgraded' + action :run + end + ``` + + **Run a command which requires an environment variable**: + + ```ruby + execute 'slapadd' do + command 'slapadd < /tmp/something.ldif' + creates '/var/lib/slapd/uid.bdb' + + action :run + environment ({'HOME' => '/home/my_home'}) + end + ``` + + **Delete a repository using yum to scrub the cache**: + + ```ruby + # the following code sample thanks to gaffneyc @ https://gist.github.com/918711 + execute 'clean-yum-cache' do + command 'yum clean all' + action :nothing + end + + file '/etc/yum.repos.d/bad.repo' do + action :delete + notifies :run, 'execute[clean-yum-cache]', :immediately + end + ``` + + **Prevent restart and reconfigure if configuration is broken**: + + Use the `:nothing` action (common to all resources) to prevent the test from + starting automatically, and then use the `subscribes` notification to run a + configuration test when a change to the template is detected. + + ```ruby + execute 'test-nagios-config' do + command 'nagios3 --verify-config' + action :nothing + subscribes :run, 'template[/etc/nagios3/configures-nagios.conf]', :immediately + end + ``` + + **Notify in a specific order**: + + To notify multiple resources, and then have these resources run in a certain + order, do something like the following. + + ```ruby + execute 'foo' do + command '...' + notifies :create, 'template[baz]', :immediately + notifies :install, 'package[bar]', :immediately + notifies :run, 'execute[final]', :immediately + end + + template 'baz' do + #... + notifies :run, 'execute[restart_baz]', :immediately + end + + package 'bar' + execute 'restart_baz' + execute 'final' do + command '...' + end + ``` + + where the sequencing will be in the same order as the resources are listed in + the recipe: `execute 'foo'`, `template 'baz'`, `execute [restart_baz]`, + `package 'bar'`, and `execute 'final'`. + + **Execute a command using a template**: + + The following example shows how to set up IPv4 packet forwarding using the + **execute** resource to run a command named `forward_ipv4` that uses a template + defined by the **template** resource. + + ```ruby + execute 'forward_ipv4' do + command 'echo > /proc/.../ipv4/ip_forward' + action :nothing + end + + template '/etc/file_name.conf' do + source 'routing/file_name.conf.erb' + + notifies :run, 'execute[forward_ipv4]', :delayed + end + ``` + + where the `command` property for the **execute** resource contains the command + that is to be run and the `source` property for the **template** resource + specifies which template to use. The `notifies` property for the **template** + specifies that the `execute[forward_ipv4]` (which is defined by the **execute** + resource) should be queued up and run at the end of a Chef Infra Client run. + + **Add a rule to an IP table**: + + The following example shows how to add a rule named `test_rule` to an IP table + using the **execute** resource to run a command using a template that is defined + by the **template** resource: + + ```ruby + execute 'test_rule' do + command "command_to_run + --option value + --option value + --source #{node[:name_of_node][:ipsec][:local][:subnet]} + -j test_rule" + + action :nothing + end + + template '/etc/file_name.local' do + source 'routing/file_name.local.erb' + notifies :run, 'execute[test_rule]', :delayed + end + ``` + + where the `command` property for the **execute** resource contains the command + that is to be run and the `source` property for the **template** resource + specifies which template to use. The `notifies` property for the **template** + specifies that the `execute[test_rule]` (which is defined by the **execute** + resource) should be queued up and run at the end of a Chef Infra Client run. + + **Stop a service, do stuff, and then restart it**: + + The following example shows how to use the **execute**, **service**, and + **mount** resources together to ensure that a node running on Amazon EC2 is + running MySQL. This example does the following: + + - Checks to see if the Amazon EC2 node has MySQL + - If the node has MySQL, stops MySQL + - Installs MySQL + - Mounts the node + - Restarts MySQL + + ```ruby + # the following code sample comes from the ``server_ec2`` + # recipe in the following cookbook: + # https://github.com/chef-cookbooks/mysql + + if (node.attribute?('ec2') && !FileTest.directory?(node['mysql']['ec2_path'])) + service 'mysql' do + action :stop + end + + execute 'install-mysql' do + command "mv #{node['mysql']['data_dir']} #{node['mysql']['ec2_path']}" + not_if { ::File.directory?(node['mysql']['ec2_path']) } + end + + [node['mysql']['ec2_path'], node['mysql']['data_dir']].each do |dir| + directory dir do + owner 'mysql' + group 'mysql' + end + end + + mount node['mysql']['data_dir'] do + device node['mysql']['ec2_path'] + fstype 'none' + options 'bind,rw' + action [:mount, :enable] + end + + service 'mysql' do + action :start + end + end + ``` + + where + + - the two **service** resources are used to stop, and then restart the MySQL service + - the **execute** resource is used to install MySQL + - the **mount** resource is used to mount the node and enable MySQL + + **Use the platform_family? method**: + + The following is an example of using the `platform_family?` method in the Recipe + DSL to create a variable that can be used with other resources in the same + recipe. In this example, `platform_family?` is being used to ensure that a + specific binary is used for a specific platform before using the **remote_file** + resource to download a file from a remote location, and then using the + **execute** resource to install that file by running a command. + + ```ruby + if platform_family?('rhel') + pip_binary = '/usr/bin/pip' + else + pip_binary = '/usr/local/bin/pip' + end + + remote_file "#{Chef::Config[:file_cache_path]}/distribute_setup.py" do + source 'http://python-distribute.org/distribute_setup.py' + mode '0755' + not_if { ::File.exist?(pip_binary) } + end + + execute 'install-pip' do + cwd Chef::Config[:file_cache_path] + command <<~EOF + # command for installing Python goes here + EOF + not_if { ::File.exist?(pip_binary) } + end + ``` + + where a command for installing Python might look something like: + + ```ruby + #{node['python']['binary']} distribute_setup.py #{::File.dirname(pip_binary)}/easy_install pip + ``` + + **Control a service using the execute resource**: + +
+

Warning

+
+ This is an example of something that should NOT be done. Use the **service** + resource to control a service, not the **execute** resource. +
+
+ + Do something like this: + + ```ruby + service 'tomcat' do + action :start + end + ``` + + and NOT something like this: + + ```ruby + execute 'start-tomcat' do + command '/etc/init.d/tomcat start' + action :run + end + ``` + + There is no reason to use the **execute** resource to control a service because + the **service** resource exposes the `start_command` property directly, which + gives a recipe full control over the command issued in a much cleaner, more + direct manner. + + **Use the search Infra Language helper to find users**: + + The following example shows how to use the `search` method in the Chef Infra Language to + search for users: + + ```ruby + # the following code sample comes from the openvpn cookbook: + + search("users", "*:*") do |u| + execute "generate-openvpn-#{u['id']}" do + command "./pkitool #{u['id']}" + cwd '/etc/openvpn/easy-rsa' + end + + %w{ conf ovpn }.each do |ext| + template "#{node['openvpn']['key_dir']}/#{u['id']}.#{ext}" do + source 'client.conf.erb' + variables :username => u['id'] + end + end + end + ``` + + where + + - the search data will be used to create **execute** resources + - the **template** resource tells Chef Infra Client which template to use + + **Enable remote login for macOS**: + + ```ruby + execute 'enable ssh' do + command '/usr/sbin/systemsetup -setremotelogin on' + not_if '/usr/sbin/systemsetup -getremotelogin | /usr/bin/grep On' + action :run + end + ``` + + **Execute code immediately, based on the template resource**: + + By default, notifications are `:delayed`, that is they are queued up as they are + triggered, and then executed at the very end of a Chef Infra Client run. To run + an action immediately, use `:immediately`: + + ```ruby + template '/etc/nagios3/configures-nagios.conf' do + # other parameters + notifies :run, 'execute[test-nagios-config]', :immediately + end + ``` + + and then Chef Infra Client would immediately run the following: + + ```ruby + execute 'test-nagios-config' do + command 'nagios3 --verify-config' + action :nothing + end + ``` + + **Sourcing a file**: + + The **execute** resource cannot be used to source a file (e.g. `command 'source + filename'`). The following example will fail because `source` is not an + executable: + + ```ruby + execute 'foo' do + command 'source /tmp/foo.sh' + end + ``` + + + Instead, use the **script** resource or one of the **script**-based resources + (**bash**, **csh**, **perl**, **python**, or **ruby**). For example: + + ```ruby + bash 'foo' do + code 'source /tmp/foo.sh' + end + ``` + + **Run a Knife command**: + + ```ruby + execute 'create_user' do + command <<~EOM + knife user create #{user} + --admin + --password password + --disable-editing + --file /home/vagrant/.chef/user.pem + --config /tmp/knife-admin.rb + EOM + end + ``` + + **Run install command into virtual environment**: + + The following example shows how to install a lightweight JavaScript framework + into Vagrant: + + ```ruby + execute "install q and zombiejs" do + cwd "/home/vagrant" + user "vagrant" + environment ({'HOME' => '/home/vagrant', 'USER' => 'vagrant'}) + command "npm install -g q zombie should mocha coffee-script" + action :run + end + ``` + + **Run a command as a named user**: + + The following example shows how to run `bundle install` from a Chef Infra Client + run as a specific user. This will put the gem into the path of the user + (`vagrant`) instead of the root user (under which the Chef Infra Client runs): + + ```ruby + execute '/opt/chefdk/embedded/bin/bundle install' do + cwd node['chef_workstation']['bundler_path'] + user node['chef_workstation']['user'] + + environment ({ + 'HOME' => "/home/#{node['chef_workstation']['user']}", + 'USER' => node['chef_workstation']['user'] + }) + not_if 'bundle check' + end + ``` + + **Run a command as an alternate user**: + + *Note*: When Chef is running as a service, this feature requires that the user + that Chef runs as has 'SeAssignPrimaryTokenPrivilege' (aka + 'SE_ASSIGNPRIMARYTOKEN_NAME') user right. By default only LocalSystem and + 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 (will not take effect in the same Chef run): + + ```ruby + 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 + run as an alternate user. + + ```ruby + # Passing only username and password + execute 'mkdir test_dir' do + cwd Chef::Config[:file_cache_path] + + user "username" + password "password" + end + + # Passing username and domain + execute 'mkdir test_dir' do + cwd Chef::Config[:file_cache_path] + + domain "domain-name" + user "user" + password "password" + end + + # Passing username = 'domain-name\username'. No domain is passed + execute 'mkdir test_dir' do + cwd Chef::Config[:file_cache_path] + + user "domain-name\username" + password "password" + end + + # Passing username = 'username@domain-name'. No domain is passed + execute 'mkdir test_dir' do + cwd Chef::Config[:file_cache_path] + + user "username@domain-name" + password "password" + end + ``` + + **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 new file mode 100644 index 0000000..bfa4528 --- /dev/null +++ b/data/infra/resources/file.yaml @@ -0,0 +1,286 @@ +--- +resource_reference: true +properties_resources_common_windows_security: true +resources_common_atomic_update: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: file +resource_description_list: + - markdown: Use the **file** resource to manage files directly on a node. + - note: + markdown: >- + Use the **cookbook_file** resource to copy a file from a cookbook's + `/files` directory. Use the **template** resource to create a file based + on a template in a cookbook's `/templates` directory. And use the + **remote_file** resource to transfer a file to a node from a remote + location. +syntax_description: |- + A **file** resource block manages files that exist on nodes. For + example, to write the home page for an Apache website: + + ```ruby + file '/var/www/customers/public_html/index.php' do + content 'This is a placeholder for the home page.' + mode '0755' + owner 'web_admin' + group 'web_admin' + end + ``` +syntax_full_code_block: |- + file 'name' do + atomic_update true, false + backup Integer, false # default value: 5 + checksum String + content String + force_unlink true, false # default value: false + group Integer, String + inherits true, false # default value: true + manage_symlink_source true, false + mode Integer, String + owner Integer, String + path String # default value: 'name' unless specified + rights Integer, String + verify String, Block, Symbol + action Symbol # defaults to :create if not specified + end +syntax_properties_list: + - >- + `'/var/www/customers/public_html/index.php'` is path to the file and also + 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`, `manage_symlink_source`, + `mode`, `owner`, and `path` are the properties available to this resource." +actions_list: + ':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. +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: '' + 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 +remote_file_unc_path: false +ps_credential_helper: false +ruby_style_basics_chef_log: false +debug_recipes_chef_shell: false +examples: |2 + **Create a file** + + ```ruby + file '/tmp/something' do + owner 'root' + group 'root' + mode '0755' + action :create + end + ``` + + **Create a file in Microsoft Windows** + + To create a file in Microsoft Windows, be sure to add an escape + character---`\`---before the backslashes in the paths: + + ```ruby + file 'C:\\tmp\\something.txt' do + rights :read, 'Everyone' + rights :full_control, 'DOMAIN\\User' + action :create + end + ``` + + **Remove a file** + + ```ruby + file '/tmp/something' do + action :delete + end + ``` + + **Set file modes** + + ```ruby + file '/tmp/something' do + mode '0755' + end + ``` + + **Delete a repository using yum to scrub the cache** + + ```ruby + # the following code sample thanks to gaffneyc @ https://gist.github.com/918711 + + execute 'clean-yum-cache' do + command 'yum clean all' + action :nothing + end + + file '/etc/yum.repos.d/bad.repo' do + action :delete + notifies :run, 'execute[clean-yum-cache]', :immediately + notifies :create, 'ruby_block[reload-internal-yum-cache]', :immediately + end + ``` + + **Add the value of a data bag item to a file** + + The following example shows how to get the contents of a data bag item + named `impossible_things`, create a .pem file located at + `some/directory/path/`, and then use the `content` attribute to update + the contents of that file with the value of the `impossible_things` data + bag item: + + ```ruby + private_key = data_bag_item('impossible_things', private_key_name)['private_key'] + + file "some/directory/path/#{private_key_name}.pem" do + content private_key + owner 'root' + group 'group' + mode '0755' + end + ``` + + **Write a YAML file** + + The following example shows how to use the `content` property to write a + YAML file: + + ```ruby + file "#{app['deploy_to']}/shared/config/settings.yml" do + owner "app['owner']" + group "app['group']" + mode '0755' + content app.to_yaml + end + ``` + + **Write a string to a file** + + The following example specifies a directory, and then uses the `content` + property to add a string to the file created in that directory: + + ```ruby + status_file = '/path/to/file/status_file' + + file status_file do + owner 'root' + group 'root' + mode '0755' + content 'My favourite foremost coastal Antarctic shelf, oh Larsen B!' + end + ``` + + **Create a file from a copy** + + The following example shows how to copy a file from one directory to + another, locally on a node: + + ```ruby + file '/root/1.txt' do + content IO.read('/tmp/1.txt') + action :create + end + ``` + + where the `content` attribute uses the Ruby `IO.read` method to get the + contents of the `/tmp/1.txt` file. diff --git a/data/infra/resources/freebsd_package.yaml b/data/infra/resources/freebsd_package.yaml new file mode 100644 index 0000000..26c994a --- /dev/null +++ b/data/infra/resources/freebsd_package.yaml @@ -0,0 +1,88 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: freebsd_package +resource_description_list: +- markdown: Use the **freebsd_package** resource to manage packages for the FreeBSD + platform. +- notes_resource_based_on_package: true +syntax_description: | + A **freebsd_package** resource block manages a package on a node, + typically by installing it. The simplest use of the **freebsd_package** + resource is: + + ```ruby + freebsd_package 'package_name' + ``` + + which will install the named package using all of the default options + and the default action (`:install`). + +syntax_full_code_block: |- + freebsd_package 'name' do + environment Hash + options String, Array + package_name String, Array + source String + timeout String, Integer + version String, Array + action Symbol # defaults to :install if not specified + 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." +- "`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 + description_list: + - 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: 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: The optional path to a package on the local file system. +- property: timeout + ruby_type: String, Integer + required: false + description_list: + - markdown: The amount of time (in seconds) to wait before timing out. +- property: version + ruby_type: String, Array + 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 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 new file mode 100644 index 0000000..058f20a --- /dev/null +++ b/data/infra/resources/gem_package.yaml @@ -0,0 +1,143 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: gem_package +resource_description_list: +- markdown: |- + Use the **gem_package** resource to manage gem packages that are only included in recipes. + When a gem is installed from a local file, it must be added to the node using the **remote_file** or **cookbook_file** resources. +- note: + markdown: The **gem_package** resource must be specified as `gem_package` and + cannot be shortened to `package` in a recipe. +- warning: + 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 + package_name String + source String, Array + timeout String, Integer + version String + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`gem_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." +- "`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. + :reconfig: + markdown: + :lock: + markdown: + :unlock: + markdown: +properties_list: +- property: clear_sources + ruby_type: true, false + required: false + default_value: false unless `clear_gem_sources` set to true in the `client.rb` config. + 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 + description_list: + - markdown: The path of a gem binary to use for the installation. By default, the + same version of Ruby that is used by Chef Infra Client will be used. +- property: include_default_source + ruby_type: true, false + required: false + new_in: '13.0' + description_list: + - markdown: Set to `false` to not include `Chef::Config[:rubygems_url]` in the sources. +- property: options + ruby_type: String, Hash, Array + required: false + description_list: + - markdown: Options for the gem install, either a Hash or a String. When a hash + is given, the options are passed to `Gem::DependencyInstaller.new`, and the + gem will be installed via the gems API. When a String is given, the gem will + be installed by shelling out to the gem command. Using a Hash of options with + an explicit gem_binary will result in undefined behavior. +- property: package_name + ruby_type: String + required: false + description_list: + - markdown: An optional property to set the package name if it differs from the + resource block's name. +- property: source + ruby_type: String, Array + required: false + description_list: + - markdown: Optional. The URL, or list of URLs, at which the gem package is located. + This list is added to the source configured in `Chef::Config[:rubygems_url]` + (see also include_default_source) to construct the complete list of rubygems + sources. Users in an 'airgapped' environment should set Chef::Config[:rubygems_url] + to their local RubyGems mirror. +- property: timeout + ruby_type: String, Integer + required: false + description_list: + - markdown: The amount of time (in seconds) to wait before timing out. +- property: version + ruby_type: String + 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: + + **Install a gem file from the local file system** + + ```ruby + gem_package 'loofah' do + source '/tmp/loofah-2.7.0.gem' + action :install + end + ``` + + **Use the `ignore_failure` common attribute** + + ```ruby + gem_package 'syntax' do + action :install + ignore_failure true + end + ``` diff --git a/data/infra/resources/git.yaml b/data/infra/resources/git.yaml new file mode 100644 index 0000000..f7b84f9 --- /dev/null +++ b/data/infra/resources/git.yaml @@ -0,0 +1,276 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: git +resource_description_list: +- markdown: Use the **git** resource to manage source control resources that exist + in a git repository. git version 1.6.5 (or higher) is required to use all of the + functionality in the git resource. +syntax_description: "A **git** resource block manages source control resources that\ + \ exist in\na git repository:\n\n```ruby\ngit \"#{Chef::Config[:file_cache_path]}/app_name\"\ + \ do\n repository node[:app_name][:git_repository]\n revision node[:app_name][:git_revision]\n\ + \ action :sync\nend\n```" +syntax_full_code_block: |- + git 'name' do + additional_remotes Hash # default value: {} + checkout_branch String + depth Integer + destination String # default value: 'name' unless specified + enable_checkout true, false # default value: true + enable_submodules true, false # default value: false + environment Hash + group String, Integer + remote String # default value: "origin" + repository String + revision String # default value: "HEAD" + ssh_wrapper String + timeout Integer + user String, Integer + action Symbol # defaults to :sync if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`git` 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." +- "`additional_remotes`, `checkout_branch`, `depth`, `destination`, `enable_checkout`, + `enable_submodules`, `environment`, `group`, `remote`, `repository`, `revision`, + `ssh_wrapper`, `timeout`, and `user` are the properties available to this resource." +actions_list: + :checkout: + markdown: Clone or check out the source. When a checkout is available, this provider + does nothing. + :export: + markdown: Export the source, excluding or removing any version control artifacts. + :nothing: + shortcode: resources_common_actions_nothing.md + :sync: + markdown: (default) Update the source to the specified version, or get a new clone + or checkout. This action causes a hard reset of the index and working tree, + discarding any uncommitted changes. +properties_list: +- property: additional_remotes + ruby_type: Hash + required: false + default_value: "{}" + description_list: + - markdown: A Hash of additional remotes that are added to the git repository configuration. +- property: checkout_branch + ruby_type: String + required: false + description_list: + - markdown: Set this to use a local branch to avoid checking SHAs or tags to a detached + head state. +- property: depth + ruby_type: Integer + required: false + description_list: + - markdown: The number of past revisions to be included in the git shallow clone. + Unless specified the default behavior will do a full clone. +- property: destination + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: 'The location path to which the source is to be cloned, checked out, + or exported. Default value: the name of the resource block.' +- property: enable_checkout + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Check out a repo from master. Set to `false` when using the `checkout_branch` + attribute to prevent the git resource from attempting to check out `master` + from `master`. +- property: enable_submodules + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Perform a sub-module initialization and update. +- 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.)' + - note: + markdown: 'The **git** provider automatically sets the `ENV[''HOME'']` and + + `ENV[''GIT_SSH'']` environment variables. To override this behavior + + and provide different values, add `ENV[''HOME'']` and/or + + `ENV[''GIT_SSH'']` to the `environment` Hash.' +- property: group + ruby_type: String, Integer + required: false + description_list: + - markdown: The system group that will own the checked-out code. +- property: remote + ruby_type: String + required: false + default_value: origin + description_list: + - markdown: The remote repository to use when synchronizing an existing clone. +- property: repository + ruby_type: String + required: false + description_list: + - markdown: The URI of the code repository. +- property: revision + ruby_type: String + 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. See `checkout_branch`. + + + The value of the `revision` attribute may change over time. From one + + branch to another, to a tag, to a specific SHA for a commit, and + + then back to a branch. The `revision` attribute may even be changed + + in a way where history gets rewritten. + + + Instead of tracking a specific branch or doing a headless checkout, + + Chef Infra Client maintains its own branch (via the **git** + + resource) that does not exist in the upstream repository. Chef Infra + + Client is then free to forcibly check out this branch to any commit + + without destroying the local history of an existing branch. + + + For example, to explicitly track an upstream repository''s master + + branch: + + + ```ruby + + revision ''master'' + + ``` + + + Use the `git rev-parse` and `git ls-remote` commands to verify that + + Chef Infra Client is synchronizing commits correctly. (Chef Infra + + Client always runs `git ls-remote` on the upstream repository to + + verify the commit is made to the correct repository.)' +- property: ssh_wrapper + ruby_type: String + required: false + description_list: + - markdown: The path to the wrapper script used when running SSH with git. The `GIT_SSH` + environment variable is set to this. +- property: timeout + ruby_type: Integer + required: false + description_list: + - 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** + + ```ruby + git '/opt/my_sources/couch' do + repository 'git://git.apache.org/couchdb.git' + revision 'master' + action :sync + end + ``` + + **Use different branches** + + To use different branches, depending on the environment of the node: + + ```ruby + branch_name = if node.chef_environment == 'QA' + 'staging' + else + 'master' + end + + git '/home/user/deployment' do + repository 'git@github.com:git_site/deployment.git' + revision branch_name + action :sync + user 'user' + group 'test' + end + ``` + + Where the `branch_name` variable is set to staging or master, depending on the environment of the node. Once this is determined, the `branch_name` variable is used to set the revision for the repository. If the git status command is used after running the example above, it will return the branch name as `deploy`, as this is the default value. Run Chef Infra Client in debug mode to verify that the correct branches are being checked out: + + ``` + sudo chef-client -l debug + ``` + + **Install an application from git using bash** + + 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 "#{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 "#{Chef::Config[:file_cache_path]}/ruby-build" + user 'rbenv' + group 'rbenv' + code <<-EOH + ./install.sh + EOH + environment 'PREFIX' => '/usr/local' + end + ``` + + **Notify a resource post-checkout** + + ```ruby + git "#{Chef::Config[:file_cache_path]}/my_app" do + repository node['my_app']['git_repository'] + revision node['my_app']['git_revision'] + action :sync + notifies :run, 'bash[compile_my_app]', :immediately + end + ``` + + **Pass in environment variables** + + ```ruby + git '/opt/my_sources/couch' do + repository 'git://git.apache.org/couchdb.git' + revision 'master' + environment 'VAR' => 'whatever' + action :sync + end + ``` diff --git a/data/infra/resources/group.yaml b/data/infra/resources/group.yaml new file mode 100644 index 0000000..bfbee47 --- /dev/null +++ b/data/infra/resources/group.yaml @@ -0,0 +1,126 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: group +resource_description_list: +- markdown: Use the **group** resource to manage a local group. +syntax_full_code_block: |- + group 'name' do + append true, false # default value: false + comment String + excluded_members String, Array # default value: [] + gid String, Integer + group_name String # default value: 'name' unless specified + members String, Array # default value: [] + non_unique true, false # default value: false + system true, false # default value: false + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`group` 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." +- "`append`, `comment`, `excluded_members`, `gid`, `group_name`, `members`, `non_unique`, + and `system` are the properties available to this resource." +actions_list: + :create: + markdown: (default) Create a group. If a group already exists (but does not match), + update that group to match. + :manage: + markdown: Manage an existing group. This action does nothing if the group does + not exist. + :modify: + markdown: Modify an existing group. This action raises an exception if the group + does not exist. + :nothing: + shortcode: resources_common_actions_nothing.md + :remove: + markdown: Remove a group. +properties_list: +- property: append + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: How members should be appended and/or removed from a group. When true, + `members` are appended and `excluded_members` are removed. When `false`, group + members are reset to the value of the `members` property. +- property: comment + ruby_type: String + required: false + new_in: '14.9' + description_list: + - markdown: Specifies a comment to associate with the local group. +- property: excluded_members + ruby_type: String, Array + required: false + default_value: "[]" + description_list: + - markdown: Remove users from a group. May only be used when `append` is set to + `true`. +- property: gid + ruby_type: String, Integer + required: false + description_list: + - markdown: The identifier for the group. +- property: group_name + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: The name of the group. +- property: members + ruby_type: String, Array + required: false + default_value: "[]" + description_list: + - markdown: 'Which users should be set or appended to a group. When more than one + group member is identified, the list of members should be an array: `members + [''user1'', ''user2'']`.' +- property: non_unique + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Allow gid duplication. May only be used with the `Groupadd` user resource + provider. +- property: system + ruby_type: true, false + required: false + 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: + + ```ruby + group 'www-data' do + action :modify + members 'maintenance' + append true + end + ``` + + Add a user to group on the Windows platform: + + ```ruby + group 'Administrators' do + members ['domain\foo'] + append true + action :modify + end + ``` diff --git a/data/infra/resources/habitat_config.yaml b/data/infra/resources/habitat_config.yaml new file mode 100644 index 0000000..4fca703 --- /dev/null +++ b/data/infra/resources/habitat_config.yaml @@ -0,0 +1,84 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: habitat_config +resource_description_list: +- markdown: Use the **habitat_config** resource to apply a configuration to a Chef + Habitat service. +resource_new_in: '17.3' +syntax_full_code_block: |- + habitat_config 'name' do + config Mash (Hash-like) + gateway_auth_token String + remote_sup String # default value: "127.0.0.1:9632" + remote_sup_http String # default value: "127.0.0.1:9631" + service_group String # default value: 'name' unless specified + user String + action Symbol # defaults to :apply if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`habitat_config` 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." +- "`config`, `gateway_auth_token`, `remote_sup`, `remote_sup_http`, `service_group`, + and `user` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :apply: + markdown: applies the given configuration (default) +properties_list: +- property: config + ruby_type: Mash (Hash-like) + required: true + description_list: + - markdown: 'The configuration to apply as a ruby hash, for example, `{ worker_count: + 2, http: { keepalive_timeout: 120 } }`.' +- property: gateway_auth_token + ruby_type: String + required: false + description_list: + - markdown: Auth token for accessing the remote supervisor's http port. +- property: remote_sup + ruby_type: String + required: false + default_value: 127.0.0.1:9632 + description_list: + - markdown: Address to a remote supervisor's control gateway. +- property: remote_sup_http + ruby_type: String + required: false + default_value: 127.0.0.1:9631 + description_list: + - markdown: Address for remote supervisor http port. Used to pull existing. +- property: service_group + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: The service group to apply the configuration to. For example, `nginx.default` +- property: user + ruby_type: String + required: false + 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** + + ```ruby + habitat_config 'nginx.default' do + config({ + worker_count: 2, + http: { + keepalive_timeout: 120 + } + }) + end + ``` diff --git a/data/infra/resources/habitat_install.yaml b/data/infra/resources/habitat_install.yaml new file mode 100644 index 0000000..ba6ca80 --- /dev/null +++ b/data/infra/resources/habitat_install.yaml @@ -0,0 +1,96 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: habitat_install +resource_description_list: +- markdown: Use the **habitat_install** resource to install Chef Habitat. +resource_new_in: '17.3' +syntax_full_code_block: |- + habitat_install 'name' do + bldr_url String + create_user true, false # default value: true + hab_version String + install_url String + license String + tmp_dir String + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`habitat_install` 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." +- "`bldr_url`, `create_user`, `hab_version`, `install_url`, `license`, and `tmp_dir` + are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :install: + markdown: Installs Habitat. Does nothing if the `hab` binary is found in the default + location for the system (`/bin/hab` on Linux, `/usr/local/bin/hab` on macOS, + `C:/habitat/hab.exe` on Windows) (default) +properties_list: +- property: bldr_url + ruby_type: String + required: false + description_list: + - markdown: Optional URL to an alternate Habitat Builder. +- property: create_user + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Creates the `hab` system user. +- property: hab_version + ruby_type: String + required: false + description_list: + - markdown: Specify the version of `Habitat` you would like to install. +- property: install_url + ruby_type: String + required: false + default_value: https://raw.githubusercontent.com/habitat-sh/habitat/main/components/hab/install.sh + description_list: + - markdown: URL to the install script, default is from the [habitat repo](https://raw.githubusercontent.com/habitat-sh/habitat/main/components/hab/install.sh) + . +- property: license + ruby_type: String + required: false + allowed_values: '"accept"' + description_list: + - markdown: Specifies acceptance of habitat license when set to `accept`. +- property: tmp_dir + ruby_type: String + required: false + description_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** + + ```ruby + habitat_install + ``` + + **Installation specifying a habitat builder URL** + + ```ruby + habitat_install 'install habitat' do + bldr_url 'http://localhost' + end + ``` + + **Installation specifying version and habitat builder URL** + + ```ruby + habitat_install 'install habitat' do + bldr_url 'http://localhost' + hab_version '1.5.50' + end + ``` diff --git a/data/infra/resources/habitat_package.yaml b/data/infra/resources/habitat_package.yaml new file mode 100644 index 0000000..1ac8baa --- /dev/null +++ b/data/infra/resources/habitat_package.yaml @@ -0,0 +1,204 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: habitat_package +resource_description_list: +- markdown: Use the **habitat_package** to install or remove Chef Habitat packages + from Habitat Builder. +resource_new_in: '17.3' +syntax_full_code_block: |- + habitat_package 'name' do + auth_token String + 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 + options String + package_name String, Array + source String + timeout String, Integer + version String, Array + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`habitat_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." +- "`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 + version of the package. (default) + :nothing: + shortcode: resources_common_actions_nothing.md + :reconfig: + markdown: Change the installed package + :remove: + markdown: Remove a package. + :purge: + markdown: Purge a package. This action typically removes the configuration files + as well as the package. + :upgrade: + markdown: Install a package and ensure that a package is the latest version. +properties_list: +- property: auth_token + ruby_type: String + required: false + description_list: + - markdown: Auth token for installing a package from a private organization on Habitat + builder. +- property: binlink + ruby_type: true, false, force + required: false + default_value: 'false' + description_list: + - markdown: 'If habitat should attempt to binlink the package. Acceptable values: + `true`, `false`, `:force`. Will fail on binlinking if set to `true` and binary + or binlink exists.' +- property: bldr_url + ruby_type: String + required: false + default_value: https://bldr.habitat.sh + description_list: + - markdown: The habitat builder url where packages will be downloaded from. **Defaults + to public Habitat Builder** +- property: channel + ruby_type: String + required: false + 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 + description_list: + - markdown: 'Identifier of one or more packages that should not be uninstalled. + (ex: core/redis, core/busybox-static/1.42.2/21120102031201)' +- property: keep_latest + ruby_type: String + required: false + description_list: + - markdown: Ability to uninstall while retaining a specified version **This feature + only works in Habitat 1.5.86+.** +- property: no_deps + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Remove package but retain dependencies. +- property: options + ruby_type: String + required: false + description_list: + - markdown: Pass any additional parameters to the habitat package command. +- property: package_name + ruby_type: String, Array + required: false + description_list: + - 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: The optional path to a package on the local file system. +- property: timeout + ruby_type: String, Integer + required: false + description_list: + - markdown: The amount of time (in seconds) to wait before timing out. +- property: version + ruby_type: String, Array + required: false + description_list: + - markdown: The version of a package to be installed or upgraded. +target_mode: + support: full +examples: | + **Install core/redis** + + ```ruby + habitat_package 'core/redis' + ``` + + **Install specific version of a package from the unstable channel** + + ```ruby + habitat_package 'core/redis' do + version '3.2.3' + channel 'unstable' + end + ``` + + **Install a package with specific version and revision** + + ```ruby + habitat_package 'core/redis' do + version '3.2.3/20160920131015' + end + ``` + + **Install a package and force linking it's binary files to the system path** + + ```ruby + habitat_package 'core/nginx' do + binlink :force + end + ``` + + **Install a package and link it's binary files to the system path** + + ```ruby + habitat_package 'core/nginx' do + options '--binlink' + end + ``` + + **Remove package and all of it's versions** + + ```ruby + habitat_package 'core/nginx' + action :remove + end + ``` + + **Remove specified version of a package** + + ```ruby + habitat_package 'core/nginx/3.2.3' + action :remove + end + ``` + + **Remove package but retain some versions Note: Only available as of Habitat 1.5.86** + + ```ruby + habitat_package 'core/nginx' + keep_latest '2' + action :remove + end + ``` + + ```ruby + **Remove package but keep dependencies** + habitat_package 'core/nginx' + no_deps false + action :remove + end + ``` diff --git a/data/infra/resources/habitat_service.yaml b/data/infra/resources/habitat_service.yaml new file mode 100644 index 0000000..0527d6b --- /dev/null +++ b/data/infra/resources/habitat_service.yaml @@ -0,0 +1,211 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: habitat_service +resource_description_list: +- markdown: Use the **habitat_service** resource to manage Chef Habitat services. + This requires that `core/hab-sup` be running as a service. See the `habitat_sup` + resource documentation for more information. +- note: + markdown: Applications may run as a specific user. Often with Habitat, the default + is `hab`, or `root`. If the application requires another user, then it should + be created with Chef's `user` resource. +resource_new_in: '17.3' +syntax_full_code_block: |- + habitat_service 'name' do + bind String, Array # default value: [] + binding_mode Symbol, String # default value: :strict + bldr_url String # default value: "https://bldr.habitat.sh/" + channel Symbol, String # default value: :stable + gateway_auth_token String + health_check_interval Integer # default value: 30 + remote_sup String # default value: "127.0.0.1:9632" + remote_sup_http String # default value: "127.0.0.1:9631" + service_group String # default value: "default" + service_name String # default value: 'name' unless specified + shutdown_timeout Integer # default value: 8 + strategy Symbol, String # default value: :none + topology Symbol, String # default value: :standalone + update_condition Symbol, String # default value: :latest + action Symbol # defaults to :load if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`habitat_service` 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." +- "`bind`, `binding_mode`, `bldr_url`, `channel`, `gateway_auth_token`, `health_check_interval`, + `remote_sup`, `remote_sup_http`, `service_group`, `service_name`, `shutdown_timeout`, + `strategy`, `topology`, and `update_condition` are the properties available to this + resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :load: + markdown: "(default action) runs `hab service load` to load and start the specified + application service (default)" + :unload: + markdown: runs `hab service unload` to unload and stop the specified application + service + :start: + markdown: runs `hab service start` to start the specified application service + :stop: + markdown: runs `hab service stop` to stop the specified application service + :restart: + markdown: runs the `:stop` and then `:start` actions + :reload: + markdown: runs the `:unload` and then `:load` actions +properties_list: +- property: bind + ruby_type: String, Array + required: false + default_value: "[]" + description_list: + - markdown: Passes `--bind` with the specified services to bind to the hab command. + If an array of multiple service binds are specified then a `--bind` flag is + added for each. +- property: binding_mode + ruby_type: Symbol, String + required: false + default_value: ":strict" + allowed_values: ':strict, "strict", :relaxed, "relaxed"' + description_list: + - markdown: Passes `--binding-mode` with the specified binding mode. Defaults to + `:strict`. Options are `:strict` or `:relaxed` +- property: bldr_url + ruby_type: String + required: false + default_value: https://bldr.habitat.sh/ + description_list: + - markdown: |- + Passes `--url` with the specified Habitat Builder URL to the hab command. Depending on the type of Habitat Builder you are connecting to, this URL will look different, here are the **3** current types: + - Public Habitat Builder (default) - `https://bldr.habitat.sh` + - On-Prem Habitat Builder installed using the [Source Install Method](https://github.com/habitat-sh/on-prem-builder) - `https://your.bldr.url` + - On-Prem Habitat Builder installed using the [Automate Installer](https://automate.chef.io/docs/on-prem-builder/) - `https://your.bldr.url/bldr/v1` +- property: channel + ruby_type: Symbol, String + required: false + default_value: ":stable" + description_list: + - markdown: Passes `--channel` with the specified channel to the hab command +- property: gateway_auth_token + ruby_type: String + required: false + description_list: + - markdown: Auth token for accessing the remote supervisor's http port. +- property: health_check_interval + ruby_type: Integer + required: false + default_value: '30' + description_list: + - markdown: The interval (seconds) on which to run health checks. +- property: remote_sup + ruby_type: String + required: false + default_value: 127.0.0.1:9632 + description_list: + - markdown: Address to a remote Supervisor's Control Gateway +- property: remote_sup_http + ruby_type: String + required: false + default_value: 127.0.0.1:9631 + description_list: + - markdown: IP address and port used to communicate with the remote supervisor. + If this value is invalid, the resource will update the supervisor configuration + each time Chef Infra Server runs. +- property: service_group + ruby_type: String + required: false + default_value: default + description_list: + - markdown: Passes `--group` with the specified service group to the hab command +- property: service_name + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: The name of the service, must be in the form of `origin/name` +- property: shutdown_timeout + ruby_type: Integer + required: false + default_value: '8' + description_list: + - markdown: The timeout in seconds allowed during shutdown. +- property: strategy + ruby_type: Symbol, String + required: false + default_value: ":none" + allowed_values: ':none, "none", :"at-once", "at-once", :rolling, "rolling"' + description_list: + - markdown: Passes `--strategy` with the specified update strategy to the hab command. + Defaults to `:none`. Other options are `:'at-once'` and `:rolling` +- property: topology + ruby_type: Symbol, String + required: false + default_value: ":standalone" + allowed_values: ':standalone, "standalone", :leader, "leader"' + description_list: + - markdown: Passes `--topology` with the specified service topology to the hab command +- property: update_condition + ruby_type: Symbol, String + required: false + default_value: ":latest" + allowed_values: ':latest, "latest", :"track-channel", "track-channel"' + description_list: + - markdown: Passes `--update-condition` dictating when this service should updated. + Defaults to `latest`. Options are `latest` or `track-channel` **_ + - note: + markdown: |- + 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** + + ```ruby + habitat_package 'core/nginx' + habitat_service 'core/nginx' + + habitat_service 'core/nginx unload' do + service_name 'core/nginx' + action :unload + end + ``` + + **Pass the `strategy` and `topology` options to hab service commands** + + ```ruby + habitat_service 'core/redis' do + strategy 'rolling' + topology 'standalone' + end + ``` + + **Using update_condition** + + ```ruby + habitat_service 'core/redis' do + strategy 'rolling' + update_condition 'track-channel' + topology 'standalone' + end + ``` + + **If the service has it's own user specified that is not the `hab` user, don't create the `hab` user on install, and instead create the application user with Chef's `user` resource** + + ```ruby + habitat_install 'install habitat' do + create_user false + end + + user 'acme-apps' do + system true + end + + habitat_service 'acme/apps' + ``` diff --git a/data/infra/resources/habitat_sup.yaml b/data/infra/resources/habitat_sup.yaml new file mode 100644 index 0000000..801b1a1 --- /dev/null +++ b/data/infra/resources/habitat_sup.yaml @@ -0,0 +1,312 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: habitat_sup +resource_description_list: +- markdown: Use the **habitat_sup** resource to runs a Chef Habitat supervisor for + one or more Chef Habitat services. The resource is commonly used in conjunction + with `habitat_service` which will manage the services loaded and started within + the supervisor. +resource_new_in: '17.3' +syntax_full_code_block: |- + habitat_sup 'name' do + auth_token String + auto_update true, false # default value: false + bldr_url String + event_stream_application String + event_stream_cert String + event_stream_environment String + event_stream_site String + event_stream_token String + event_stream_url String + gateway_auth_token String + hab_channel String + health_check_interval String, Integer + keep_latest String + launcher_version String + license String + limit_no_files String + listen_ctl String + listen_gossip String + listen_http String + org String # default value: "default" + peer String, Array + permanent_peer true, false # default value: false + ring String + service_version String + sup_version String + toml_config true, false # default value: false + update_condition String + action Symbol # defaults to :run if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`habitat_sup` 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." +- "`auth_token`, `auto_update`, `bldr_url`, `event_stream_application`, `event_stream_cert`, + `event_stream_environment`, `event_stream_site`, `event_stream_token`, `event_stream_url`, + `gateway_auth_token`, `hab_channel`, `health_check_interval`, `keep_latest`, `launcher_version`, + `license`, `limit_no_files`, `listen_ctl`, `listen_gossip`, `listen_http`, `org`, + `peer`, `permanent_peer`, `ring`, `service_version`, `sup_version`, `toml_config`, + and `update_condition` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :run: + markdown: The `run` action handles installing Habitat using the `habitat_install` + resource, ensures that the appropriate versions of the `core/hab-sup` and `core/hab-launcher` + packages are installed using `habitat_package`, and then drops off the appropriate + init system definitions and manages the service. (default) + :stop: + markdown: +properties_list: +- property: auth_token + ruby_type: String + required: false + description_list: + - markdown: Auth token for accessing a private organization on bldr. This value + is templated into the appropriate service file. +- property: auto_update + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Passes `--auto-update`. This will set the Habitat supervisor to automatically + update itself any time a stable version has been released. +- property: bldr_url + ruby_type: String + required: false + description_list: + - markdown: The Habitat Builder URL for the `habitat_package` resource, if needed. +- property: event_stream_application + ruby_type: String + required: false + description_list: + - markdown: The name of your application that will be displayed in the Chef Automate + Applications Dashboard. +- property: event_stream_cert + ruby_type: String + required: false + description_list: + - markdown: With `Intermediary Certificates` or, Automate 2 being set to use TLS + with a valid cert, you will need to provide `Habitat` with your certificate + for communication with Automate to work. [Follow these steps!](https://automate.chef.io/docs/applications-setup/#share-the-tls-certificate-with-chef-habitat). +- property: event_stream_environment + ruby_type: String + required: false + description_list: + - markdown: The application environment for the supervisor, this is for grouping + in the Applications Dashboard. +- property: event_stream_site + ruby_type: String + required: false + description_list: + - markdown: Application Dashboard label for the 'site' of the application - can + be filtered in the dashboard. +- property: event_stream_token + ruby_type: String + required: false + description_list: + - markdown: Chef Automate token for sending application event stream data. +- property: event_stream_url + ruby_type: String + required: false + description_list: + - markdown: "`AUTOMATE_HOSTNAME:4222` - the Chef Automate URL with port 4222 specified" + - note: + markdown: The port can be changed if needed. +- property: gateway_auth_token + ruby_type: String + required: false + description_list: + - markdown: Auth token for accessing the supervisor's HTTP gateway. This value is + templated into the appropriate service file. +- property: hab_channel + ruby_type: String + required: false + description_list: + - markdown: The channel to install Habitat from. Defaults to stable +- property: health_check_interval + ruby_type: String, Integer + required: false + description_list: + - markdown: The interval (seconds) on which to run health checks. +- property: keep_latest + ruby_type: String + required: false + description_list: + - markdown: Automatically cleans up old packages. If this flag is enabled, service + startup will initiate an uninstall of all previous versions of the associated + package. This also applies when a service is restarted due to an update. If + a number is passed to this argument, that number of latest versions will be + kept. The same logic applies to the Supervisor package `env:HAB_KEEP_LATEST_PACKAGES=1` + - note: + markdown: This requires Habitat version `1.5.86+` +- property: launcher_version + ruby_type: String + required: false + description_list: + - markdown: Allows you to choose which version of launcher to install. +- property: license + ruby_type: String + required: false + allowed_values: '"accept"' + description_list: + - markdown: Specifies acceptance of habitat license when set to `accept`. +- property: limit_no_files + ruby_type: String + required: false + description_list: + - markdown: allows you to set LimitNOFILE in the systemd service when used + - note: + markdown: Linux Only. +- property: listen_ctl + ruby_type: String + required: false + description_list: + - markdown: Only valid for `:run` action, passes `--listen-ctl` with the specified + address and port, e.g., `0.0.0.0:9632`, to the hab command. +- property: listen_gossip + ruby_type: String + required: false + description_list: + - markdown: Only valid for `:run` action, passes `--listen-gossip` with the specified + address and port, e.g., `0.0.0.0:9638`, to the hab command. +- property: listen_http + ruby_type: String + required: false + description_list: + - markdown: Only valid for `:run` action, passes `--listen-http` with the specified + address and port, e.g., `0.0.0.0:9631`, to the hab command. +- property: org + ruby_type: String + required: false + default_value: default + description_list: + - markdown: Only valid for `:run` action, passes `--org` with the specified org + name to the hab command. +- property: peer + ruby_type: String, Array + required: false + description_list: + - markdown: Only valid for `:run` action, passes `--peer` with the specified initial + peer to the hab command. +- property: permanent_peer + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Only valid for `:run` action, passes `--permanent-peer` to the hab command. +- property: ring + ruby_type: String + required: false + description_list: + - markdown: Only valid for `:run` action, passes `--ring` with the specified ring + key name to the hab command. +- property: service_version + ruby_type: String + required: false + description_list: + - markdown: Allows you to choose which version of the **_Windows Service_** to install. +- property: sup_version + ruby_type: String + required: false + description_list: + - markdown: Allows you to choose which version of supervisor you would like to install. + - note: + markdown: If a version is provided, it will also install that version of habitat + if not previously installed. +- property: toml_config + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Supports using the Supervisor toml configuration instead of passing + exec parameters to the service, [reference](https://www.habitat.sh/docs/reference/#supervisor-config). +- property: update_condition + ruby_type: String + required: false + description_list: + - markdown: Passes `--update-condition` dictating when this service should updated. + Defaults to `latest`. Options are `latest` or `track-channel` **_ + - note: + markdown: |- + 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** + + ```ruby + habitat_sup 'default' + ``` + + **Update listen ports and use Supervisor toml config** + + ```ruby + habitat_sup 'test-options' do + listen_http '0.0.0.0:9999' + listen_gossip '0.0.0.0:9998' + toml_config true + end + ``` + + **Use with an on-prem Habitat Builder. Note: Access to public builder may not be available due to your company policies** + + ```ruby + habitat_sup 'default' do + bldr_url 'https://bldr.example.com' + end + ``` + + **Using update_condition** + + ```ruby + habitat_sup 'default' do + bldr_url 'https://bldr.example.com' + habitat_channel 'dev' + update_condition 'track-channel' + end + ``` + + **Provide event stream information** + + ```ruby + habitat_sup 'default' do + license 'accept' + event_stream_application 'myapp' + event_stream_environment 'production' + event_stream_site 'MySite' + event_stream_url 'automate.example.com:4222' + event_stream_token 'myawesomea2clitoken=' + event_stream_cert '/hab/cache/ssl/mycert.crt' + end + ``` + + **Provide specific versions** + + ```ruby + habitat_sup 'default' do + bldr_url 'https://bldr.example.com' + sup_version '1.5.50' + launcher_version '13458' + service_version '0.6.0' # WINDOWS ONLY + end + ``` + + **Set latest version of packages to retain** + + habitat_sup 'default' do + bldr_url 'https://bldr.example.com' + sup_version '1.5.86' + launcher_version '13458' + service_version '0.6.0' # WINDOWS ONLY + keep_latest '2' + end + ``` diff --git a/data/infra/resources/habitat_user_toml.yaml b/data/infra/resources/habitat_user_toml.yaml new file mode 100644 index 0000000..18115fe --- /dev/null +++ b/data/infra/resources/habitat_user_toml.yaml @@ -0,0 +1,59 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: habitat_user_toml +resource_description_list: +- markdown: Use the **habitat_user_toml** to template a `user.toml` for Chef Habitat + services. Configurations set in the `user.toml` override the `default.toml` for + a given package, which makes it an alternative to applying service group level + configuration. +resource_new_in: '17.3' +syntax_full_code_block: |- + habitat_user_toml 'name' do + config Mash (Hash-like) + service_name String # default value: 'name' unless specified + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`habitat_user_toml` 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." +- "`config` and `service_name` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: "(default action) Create the user.toml from the specified config. (default)" + :delete: + markdown: Delete the user.toml +properties_list: +- property: config + ruby_type: Mash (Hash-like) + required: true + description_list: + - markdown: 'Only valid for `:create` action. The configuration to apply as a ruby + hash, for example, `{ worker_count: 2, http: { keepalive_timeout: 120 } }`.' +- property: service_name + ruby_type: String + required: false + 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** + + ```ruby + habitat_user_toml 'nginx' do + config({ + worker_count: 2, + http: { + keepalive_timeout: 120 + } + }) + end + ``` diff --git a/data/infra/resources/homebrew_cask.yaml b/data/infra/resources/homebrew_cask.yaml new file mode 100644 index 0000000..47f4580 --- /dev/null +++ b/data/infra/resources/homebrew_cask.yaml @@ -0,0 +1,59 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: homebrew_cask +resource_description_list: +- markdown: Use the **homebrew_cask** resource to install binaries distributed via + the Homebrew package manager. +resource_new_in: '14.0' +syntax_full_code_block: |- + homebrew_cask 'name' do + cask_name String # default value: 'name' unless specified + homebrew_path String + options String + owner String, Integer # default value: "Calculated default username" + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`homebrew_cask` 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." +- "`cask_name`, `homebrew_path`, `options`, and `owner` are the properties available + to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :install: + markdown: Install an application that is packaged as a Homebrew cask. (default) + :remove: + markdown: Remove an application that is packaged as a Homebrew cask. +properties_list: +- property: cask_name + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the cask name if it differs from the resource + block's name. +- property: homebrew_path + ruby_type: String + required: false + description_list: + - markdown: The path to the Homebrew binary. +- property: options + ruby_type: String + required: false + description_list: + - markdown: Options to pass to the brew command during installation. +- property: owner + ruby_type: String, Integer + required: false + default_value: Calculated default username + description_list: + - markdown: The owner of the Homebrew installation. +target_mode: +examples: diff --git a/data/infra/resources/homebrew_package.yaml b/data/infra/resources/homebrew_package.yaml new file mode 100644 index 0000000..3912eec --- /dev/null +++ b/data/infra/resources/homebrew_package.yaml @@ -0,0 +1,126 @@ +--- +resource_reference: true +multi_package_resource: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: homebrew_package +resource_description_list: +- markdown: Use the **homebrew_package** resource to manage packages for the macOS + platform. +- note: + markdown: Starting with Chef Infra Client 16 the homebrew resource now accepts + an array of packages for installing multiple packages at once. +- notes_resource_based_on_package: true +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 + source String + timeout String, Integer + version String, Array + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`homebrew_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`, `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. + :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. + + 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 cannot automatically detect the correct owner.' +- property: options + ruby_type: String, Array + required: false + description_list: + - 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: 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: The optional path to a package on the local file system. +- property: timeout + ruby_type: String, Integer + required: false + description_list: + - markdown: The amount of time (in seconds) to wait before timing out. +- property: version + 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**: + + ```ruby + homebrew_package 'git' + ``` + + **Install multiple packages at once**: + + ```ruby + homebrew_package %w(git fish ruby) + ``` + + **Specify the Homebrew user with a UUID** + + ```ruby + homebrew_package 'git' do + homebrew_user 1001 + end + ``` + + **Specify the Homebrew user with a string**: + + ```ruby + homebrew_package 'vim' do + homebrew_user 'user1' + end + ``` diff --git a/data/infra/resources/homebrew_tap.yaml b/data/infra/resources/homebrew_tap.yaml new file mode 100644 index 0000000..e3b7d8d --- /dev/null +++ b/data/infra/resources/homebrew_tap.yaml @@ -0,0 +1,64 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: homebrew_tap +resource_description_list: +- markdown: Use the **homebrew_tap** resource to add additional formula repositories + to the Homebrew package manager. +resource_new_in: '14.0' +syntax_full_code_block: |- + homebrew_tap 'name' do + homebrew_path String + owner String # default value: "Calculated default username" + tap_name String # default value: 'name' unless specified + url String + action Symbol # defaults to :tap if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`homebrew_tap` 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." +- "`homebrew_path`, `owner`, `tap_name`, and `url` are the properties available to + this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :tap: + markdown: Add a Homebrew tap. (default) + :untap: + markdown: Remove a Homebrew tap. +properties_list: +- property: homebrew_path + ruby_type: String + required: false + description_list: + - markdown: The path to the Homebrew binary. +- property: owner + ruby_type: String + required: false + default_value: Calculated default username + description_list: + - markdown: The owner of the Homebrew installation. +- property: tap_name + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the tap name if it differs from the resource + block's name. +- property: url + ruby_type: String + required: false + description_list: + - markdown: The URL of the tap. +target_mode: +examples: | + **Tap a repository**: + + ```ruby + homebrew_tap 'apple/homebrew-apple' + ``` diff --git a/data/infra/resources/homebrew_update.yaml b/data/infra/resources/homebrew_update.yaml new file mode 100644 index 0000000..3c2fb82 --- /dev/null +++ b/data/infra/resources/homebrew_update.yaml @@ -0,0 +1,50 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: homebrew_update +resource_description_list: +- markdown: Use the **homebrew_update** resource to manage Homebrew repository updates + on macOS. +resource_new_in: '16.2' +syntax_full_code_block: |- + homebrew_update 'name' do + frequency Integer # default value: 86400 + action Symbol # defaults to :periodic if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`homebrew_update` 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." +- "`frequency` is the property available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :periodic: + markdown: Run a periodic update based on the frequency property. (default) + :update: + markdown: Run an immediate update. +properties_list: +- property: frequency + ruby_type: Integer + required: false + default_value: '86400' + 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 + homebrew_update 'all platforms' do + frequency 86400 + action :periodic + end + ``` + **Update the Homebrew repository at the start of a Chef Infra Client run**: + ```ruby + homebrew_update 'update' + ``` diff --git a/data/infra/resources/hostname.yaml b/data/infra/resources/hostname.yaml new file mode 100644 index 0000000..59d7d0e --- /dev/null +++ b/data/infra/resources/hostname.yaml @@ -0,0 +1,129 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: hostname +resource_description_list: +- markdown: Use the **hostname** resource to set the system's hostname, configure + hostname and hosts config file, and re-run the Ohai hostname plugin so the hostname + will be available in subsequent cookbooks. +resource_new_in: '14.0' +syntax_full_code_block: |- + hostname 'name' do + aliases Array + compile_time true, false # default value: true + domain_password String + domain_user String + fqdn String + hostname String # default value: 'name' unless specified + ipaddress String # default value: The node's IP address as determined by Ohai. + windows_reboot true, false # default value: true + action Symbol # defaults to :set if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`hostname` 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." +- "`aliases`, `compile_time`, `domain_password`, `domain_user`, `fqdn`, `hostname`, + `ipaddress`, and `windows_reboot` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :set: + markdown: Sets the node's hostname. (default) +properties_list: +- property: aliases + ruby_type: Array + required: false + description_list: + - markdown: An array of hostname aliases to use when configuring the hosts file. +- property: compile_time + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Determines whether or not the resource should be run at compile time. +- property: domain_password + ruby_type: String + required: false + new_in: '17.2' + description_list: + - markdown: The password to accompany the domain_user parameter +- property: domain_user + ruby_type: String + required: false + new_in: '17.2' + description_list: + - markdown: A domain account specified in the form of DOMAIN\user used when renaming + a domain-joined device +- property: fqdn + ruby_type: String + required: false + new_in: '17.0' + description_list: + - markdown: An optional property to set the fqdn if it differs from the resource + block's hostname. +- property: hostname + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the hostname if it differs from the resource + block's name. +- property: ipaddress + ruby_type: String + required: false + default_value: The node's IP address as determined by Ohai. + description_list: + - markdown: The IP address to use when configuring the hosts file. +- property: windows_reboot + ruby_type: true, false + required: false + default_value: 'true' + 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**: + + ```ruby + hostname 'example' + ``` + + **Manually specify the hostname and IP address**: + + ```ruby + hostname 'statically_configured_host' do + hostname 'example' + ipaddress '198.51.100.2' + end + ``` + + **Change the hostname of a Windows, Non-Domain joined node**: + + ```ruby + hostname 'renaming a workgroup computer' do + hostname 'Foo' + end + ``` + + **Change the hostname of a Windows, Domain-joined node (new in 17.2)**: + + ```ruby + hostname 'renaming a domain-joined computer' do + hostname 'Foo' + domain_user "Domain\Someone" + domain_password 'SomePassword' + end + ``` diff --git a/data/infra/resources/http_request.yaml b/data/infra/resources/http_request.yaml new file mode 100644 index 0000000..b458842 --- /dev/null +++ b/data/infra/resources/http_request.yaml @@ -0,0 +1,81 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: http_request +resource_description_list: +- markdown: Use the **http_request** resource to send an HTTP request (`GET`, `PUT`, + `POST`, `DELETE`, `HEAD`, or `OPTIONS`) with an arbitrary message. This resource + is often useful when custom callbacks are necessary. +syntax_full_code_block: |- + http_request 'name' do + headers Hash # default value: {} + url String + action Symbol # defaults to :get if not specified + end +syntax_description: | + An **http_request** resource block sends HTTP requests with an arbitrary message. + For example, to send a `DELETE` request to `'http://www.example.com/some_page?message=please_delete_me'`: + + ```ruby + http_request 'please_delete_me' do + url 'http://www.example.com/some_page' + action :delete + end + ``` + +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` and `url` are the properties available to this resource." +actions_list: + :delete: + markdown: Send a `DELETE` request. + :get: + markdown: "(default) Send a `GET` request.\n Changed in Chef Client 12.0 to deprecate\ + \ the hard-coded query string from earlier versions. Cookbooks that rely on\ + \ this string need to be updated to manually add it to the URL as it is passed\ + \ to the resource." + :head: + markdown: Send a `HEAD` request. + :nothing: + shortcode: resources_common_actions_nothing.md + :options: + markdown: Send an `OPTIONS` request. + :post: + markdown: Send a `POST` request. + :put: + markdown: Send a `PUT` request. +properties_list: +- property: headers + ruby_type: Hash + required: false + default_value: "{}" + description_list: + - markdown: A Hash of custom headers. +- 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\ + \n To send a `POST` request as JSON data, convert the message to JSON and\n include\ + \ the correct content-type header. For example:\n\n ```ruby\n http_request 'posting\ + \ data' do\n action :post\n url 'http://example.com/check_in'\n message\ + \ ({:some => 'data'}.to_json)\n headers({'AUTHORIZATION' => \"Basic #{\n \ + \ Base64.encode64('username:password')}\",\n 'Content-Type' => 'application/data'\n\ + \ })\n end\n ```\n\n Transfer a file only when the remote source changes\n\ + \n ```ruby\n remote_file '/tmp/couch.png' do\n source 'http://couchdb.apache.org/img/sketch.png'\n\ + \ action :nothing\n end\n\n http_request 'HEAD http://couchdb.apache.org/img/sketch.png'\ + \ do\n message ''\n url 'http://couchdb.apache.org/img/sketch.png'\n action\ + \ :head\n if ::File.exist?('/tmp/couch.png')\n headers 'If-Modified-Since'\ + \ => File.mtime('/tmp/couch.png').httpdate\n end\n notifies :create, 'remote_file[/tmp/couch.png]',\ + \ :immediately\n end\n ```\n" + diff --git a/data/infra/resources/ifconfig.yaml b/data/infra/resources/ifconfig.yaml new file mode 100644 index 0000000..dcbb64c --- /dev/null +++ b/data/infra/resources/ifconfig.yaml @@ -0,0 +1,231 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: ifconfig +resource_description_list: +- markdown: Use the **ifconfig** resource to manage interfaces on Unix and Linux systems. +- note: + markdown: This resource requires the ifconfig binary to be present on the system + and may require additional packages to be installed first. On Ubuntu 18.04 or + later you will need to install the `ifupdown` package, which disables the built + in Netplan functionality. +- warning: + markdown: This resource will not work with Fedora release 33 or later. +syntax_full_code_block: |- + ifconfig 'name' do + bcast String + bonding_opts String + bootproto String + bridge String + device String + ethtool_opts String + family String # default value: "inet" + gateway String + hwaddr String + inet_addr String + mask String + master String + metric String + mtu String + network String + onboot String + onparent String + slave String + target String # default value: 'name' unless specified + vlan String + action Symbol # defaults to :add if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`ifconfig` 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." +- "`bcast`, `bonding_opts`, `bootproto`, `bridge`, `device`, `ethtool_opts`, `family`, + `gateway`, `hwaddr`, `inet_addr`, `mask`, `master`, `metric`, `mtu`, `network`, + `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. + :enable: + markdown: Run ifconfig to enable a network interface. + :disable: + markdown: Run ifconfig to disable a network interface. +properties_list: +- property: bcast + ruby_type: String + required: false + description_list: + - markdown: The broadcast address for a network interface. On some platforms this + property is not set using ifconfig, but instead is added to the startup configuration + file for the network interface. +- property: bonding_opts + ruby_type: String + required: false + new_in: '13.4' + description_list: + - markdown: 'Bonding options to pass via `BONDING_OPTS` on RHEL and CentOS. For + example: `mode=active-backup miimon=100`.' +- property: bootproto + ruby_type: String + required: false + description_list: + - markdown: The boot protocol used by a network interface. +- property: bridge + ruby_type: String + required: false + new_in: '16.7' + description_list: + - markdown: The bridge interface this interface is a member of on Red Hat based + systems. +- property: device + ruby_type: String + required: false + description_list: + - markdown: The network interface to be configured. +- property: ethtool_opts + ruby_type: String + required: false + new_in: '13.4' + description_list: + - markdown: 'Options to be passed to ethtool(8). For example: `-A eth0 autoneg off + rx off tx off`.' +- property: family + ruby_type: String + required: false + default_value: inet + new_in: '14.0' + description_list: + - markdown: 'Networking family option for Debian-based systems; for example: `inet` + or `inet6`.' +- property: gateway + ruby_type: String + required: false + new_in: '14.4' + description_list: + - markdown: The gateway to use for the interface. +- property: hwaddr + ruby_type: String + required: false + description_list: + - markdown: The hardware address for the network interface. +- property: inet_addr + ruby_type: String + required: false + description_list: + - markdown: The Internet host address for the network interface. +- property: mask + ruby_type: String + required: false + description_list: + - markdown: 'The decimal representation of the network mask. For example: `255.255.255.0`.' +- property: master + ruby_type: String + required: false + new_in: '13.4' + description_list: + - markdown: Specifies the channel bonding interface to which the Ethernet interface + is linked. +- property: metric + ruby_type: String + required: false + description_list: + - markdown: The routing metric for the interface. +- property: mtu + ruby_type: String + required: false + description_list: + - markdown: The maximum transmission unit (MTU) for the network interface. +- property: network + ruby_type: String + required: false + description_list: + - markdown: The address for the network interface. +- property: onboot + ruby_type: String + required: false + description_list: + - markdown: Bring up the network interface on boot. +- property: onparent + ruby_type: String + required: false + description_list: + - markdown: Bring up the network interface when its parent interface is brought + up. +- property: slave + ruby_type: String + required: false + new_in: '13.4' + description_list: + - markdown: When set to `yes`, this device is controlled by the channel bonding + interface that is specified via the `master` property. +- property: target + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: The IP address that is to be assigned to the network interface. If not + specified we'll use the resource's name. +- property: vlan + ruby_type: String + required: false + 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** + + ```ruby + ifconfig '33.33.33.80' do + device 'eth1' + end + ``` + + will create the following interface configuration: + + ``` + iface eth1 inet static + address 33.33.33.80 + ``` + + **Configure an interface to use DHCP** + + ```ruby + ifconfig 'Set eth1 to DHCP' do + device 'eth1' + bootproto 'dhcp' + end + ``` + + will create the following interface configuration: + + ``` + iface eth1 inet dhcp + ``` + + **Update a static IP address with a boot protocol** + + ```ruby + ifconfig "33.33.33.80" do + bootproto "dhcp" + device "eth1" + end + ``` + + will update the interface configuration from static to dhcp: + + ``` + iface eth1 inet dhcp + address 33.33.33.80 + ``` diff --git a/data/infra/resources/inspec_input.yaml b/data/infra/resources/inspec_input.yaml new file mode 100644 index 0000000..9d02c61 --- /dev/null +++ b/data/infra/resources/inspec_input.yaml @@ -0,0 +1,93 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: inspec_input +resource_description_list: +- markdown: Use the **inspec_input** resource to add an input to the Compliance Phase. +resource_new_in: '17.5' +syntax_full_code_block: |- + inspec_input 'name' do + input Hash, String # default value: 'name' unless specified + source Hash, String # default value: 'name' unless specified + action Symbol # defaults to :add if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`inspec_input` 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." +- "`input` and `source` are the properties available to this resource." +actions_list: + :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 + required: false + default_value: The resource block's name + description_list: + - markdown: +- property: source + ruby_type: Hash, String + required: false + 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**: + + ```ruby + inspec_input 'openssh' do + action :add + end + ``` + + **Activate all inputs in the openssh cookbook's compliance segment**: + + ```ruby + inspec_input 'openssh::.*' do + action :add + end + ``` + + **Add an InSpec input to the Compliance Phase from a hash**: + + ```ruby + inspec_input { ssh_custom_path: '/whatever2' } + ``` + + **Add an InSpec input to the Compliance Phase using the 'name' property to identify the input**: + + ```ruby + inspec_input "setting my input" do + source( { ssh_custom_path: '/whatever2' }) + end + ``` + + **Add an InSpec input to the Compliance Phase using a TOML, JSON, or YAML file**: + + ```ruby + inspec_input "/path/to/my/input.yml" + ``` + + **Add an InSpec input to the Compliance Phase using a TOML, JSON, or YAML file, using the 'name' property**: + + ```ruby + inspec_input "setting my input" do + source "/path/to/my/input.yml" + end + ``` + + Note that the **inspec_input** resource does not update and will not fire notifications (similar to the log resource). This is done to preserve the ability to use + the resource while not causing the updated resource count to be larger than zero. Since the resource does not update the state of the managed node, this behavior + is still consistent with the configuration management model. Instead, you should use events to observe configuration changes for the compliance phase. It is + possible to use the `notify_group` resource to chain notifications of the two resources, but notifications are the wrong model to use, and you should use pure ruby + conditionals instead. Compliance configuration should be independent of other resources and should only be conditional based on state/attributes, not other resources. diff --git a/data/infra/resources/inspec_waiver.yaml b/data/infra/resources/inspec_waiver.yaml new file mode 100644 index 0000000..53ae0d3 --- /dev/null +++ b/data/infra/resources/inspec_waiver.yaml @@ -0,0 +1,145 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: inspec_waiver +resource_description_list: +- markdown: Use the **inspec_waiver** resource to add a waiver to the Compliance Phase. +resource_new_in: '17.5' +syntax_full_code_block: |- + inspec_waiver 'name' do + control String # default value: 'name' unless specified + expiration String + justification String + run_test true, false + source Hash, String + action Symbol # defaults to :add if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`inspec_waiver` 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." +- "`control`, `expiration`, `justification`, `run_test`, and `source` are the properties + available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :add: + markdown: Add a waiver to the compliance phase (default) +properties_list: +- property: control + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: The name of the control being waived +- property: expiration + ruby_type: String + required: false + description_list: + - markdown: The expiration date of the waiver - provided in YYYY-MM-DD format +- property: justification + ruby_type: String + required: false + description_list: + - markdown: Can be any text you want and might include a reason for the waiver as + well as who signed off on the waiver. +- property: run_test + ruby_type: true, false + required: false + description_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. +- property: source + ruby_type: Hash, String + required: false + description_list: + - markdown: +target_mode: + support: full +examples: | + **Activate the default waiver in the openssh cookbook's compliance segment**: + + ```ruby + inspec_waiver 'openssh' do + action :add + end + ``` + + **Activate all waivers in the openssh cookbook's compliance segment**: + + ```ruby + inspec_waiver 'openssh::.*' do + action :add + end + ``` + + **Add an InSpec waiver to the Compliance Phase**: + + ```ruby + inspec_waiver 'Add waiver entry for control' do + control 'my_inspec_control_01' + run_test false + justification "The subject of this control is not managed by Chef Infra Client on the systems in policy group #{node['policy_group']}" + expiration '2022-01-01' + action :add + end + ``` + + **Add an InSpec waiver to the Compliance Phase using the 'name' property to identify the control**: + + ```ruby + inspec_waiver 'my_inspec_control_01' do + justification "The subject of this control is not managed by Chef Infra Client on the systems in policy group #{node['policy_group']}" + action :add + end + ``` + + **Add an InSpec waiver to the Compliance Phase using an arbitrary YAML, JSON, or TOML file**: + + ```ruby + # files ending in .yml or .yaml that exist are parsed as YAML + inspec_waiver "/path/to/my/waiver.yml" + + inspec_waiver "my-waiver-name" do + source "/path/to/my/waiver.yml" + end + + # files ending in .json that exist are parsed as JSON + inspec_waiver "/path/to/my/waiver.json" + + inspec_waiver "my-waiver-name" do + source "/path/to/my/waiver.json" + end + + # files ending in .toml that exist are parsed as TOML + inspec_waiver "/path/to/my/waiver.toml" + + inspec_waiver "my-waiver-name" do + source "/path/to/my/waiver.toml" + end + ``` + + **Add an InSpec waiver to the Compliance Phase using a hash**: + + ```ruby + my_hash = { "ssh-01" => { + "expiration_date" => "2033-07-31", + "run" => false, + "justification" => "because" + } } + + inspec_waiver "my-waiver-name" do + source my_hash + end + ``` + + Note that the **inspec_waiver** resource does not update and will not fire notifications (similar to the log resource). This is done to preserve the ability to use + the resource while not causing the updated resource count to be larger than zero. Since the resource does not update the state of the managed node, this behavior + is still consistent with the configuration management model. Instead, you should use events to observe configuration changes for the compliance phase. It is + possible to use the `notify_group` resource to chain notifications of the two resources, but notifications are the wrong model to use, and you should use pure ruby + conditionals instead. Compliance configuration should be independent of other resources and should only be conditional based on state/attributes, not other resources. diff --git a/data/infra/resources/inspec_waiver_file_entry.yaml b/data/infra/resources/inspec_waiver_file_entry.yaml new file mode 100644 index 0000000..931c6ff --- /dev/null +++ b/data/infra/resources/inspec_waiver_file_entry.yaml @@ -0,0 +1,108 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: inspec_waiver_file_entry +resource_description_list: +- markdown: Use the **inspec_waiver_file_entry** resource to add or remove entries + from an InSpec waiver file. This can be used in conjunction with the Compliance + Phase. +resource_new_in: '17.1' +syntax_full_code_block: |- + inspec_waiver_file_entry 'name' do + backup false, Integer # default value: false + control String # default value: 'name' unless specified + expiration String + file_path String + justification String + run_test true, false + action Symbol # defaults to :add if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`inspec_waiver_file_entry` 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." +- "`backup`, `control`, `expiration`, `file_path`, `justification`, and `run_test` + are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :add: + markdown: " (default)" + :remove: + markdown: +properties_list: +- property: backup + ruby_type: false, Integer + required: false + default_value: 'false' + 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: control + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: The name of the control being added or removed to the waiver file +- property: expiration + ruby_type: String + required: false + description_list: + - markdown: The expiration date of the given waiver - provided in YYYY-MM-DD format +- property: file_path + ruby_type: String + required: true + default_value: "`/etc/chef/inspec_waivers.yml` on Linux/Unix and `C:\\chef\\inspec_waivers.yml` + on Windows" + description_list: + - markdown: The path to the waiver file being modified +- property: justification + ruby_type: String + required: false + description_list: + - markdown: Can be any text you want and might include a reason for the waiver as + well as who signed off on the waiver. +- property: run_test + ruby_type: true, false + required: false + description_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**: + + ```ruby + inspec_waiver_file_entry 'Add waiver entry for control' do + file_path 'C:\chef\inspec_waiver_file.yml' + control 'my_inspec_control_01' + run_test false + justification "The subject of this control is not managed by Chef Infra Client on the systems in policy group #{node['policy_group']}" + expiration '2022-01-01' + action :add + end + ``` + + **Add an InSpec waiver entry to a given waiver file using the 'name' property to identify the control**: + + ```ruby + inspec_waiver_file_entry 'my_inspec_control_01' do + justification "The subject of this control is not managed by Chef Infra Client on the systems in policy group #{node['policy_group']}" + action :add + end + ``` + + **Remove an InSpec waiver entry to a given waiver file**: + + ```ruby + inspec_waiver_file_entry "my_inspec_control_01" do + action :remove + end + ``` diff --git a/data/infra/resources/ips_package.yaml b/data/infra/resources/ips_package.yaml new file mode 100644 index 0000000..08188db --- /dev/null +++ b/data/infra/resources/ips_package.yaml @@ -0,0 +1,104 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: ips_package +resource_description_list: +- markdown: Use the **ips_package** resource to manage packages (using Image Packaging + System (IPS)) on the Solaris 11 platform. +- notes_resource_based_on_package: true +syntax_description: | + A **ips_package** resource block manages a package on a node, + typically by installing it. The simplest use of the **ips_package** resource is: + + ```ruby + ips_package ''package_name'' + ``` + + which will install the named package using all of the default options + and the default action (`:install`). +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 + timeout String, Integer + 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`, `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: accept_license + ruby_type: true, false + required: false + 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 + description_list: + - markdown: One (or more) additional command options that are passed to the command. +- property: package_name + ruby_type: String + required: false + description_list: + - 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: The optional path to a package on the local file system. +- property: timeout + ruby_type: String, Integer + required: false + description_list: + - markdown: The amount of time (in seconds) to wait before timing out. +- property: version + ruby_type: String + 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 new file mode 100644 index 0000000..3b2c584 --- /dev/null +++ b/data/infra/resources/kernel_module.yaml @@ -0,0 +1,139 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: kernel_module +resource_description_list: +- markdown: Use the **kernel_module** resource to manage kernel modules on Linux systems. + This resource can load, unload, blacklist, disable, enable, install, and uninstall + modules. +resource_new_in: '14.3' +syntax_full_code_block: |- + kernel_module 'name' do + load_dir String # default value: "/etc/modules-load.d" + modname String # default value: 'name' unless specified + options Array + unload_dir String # default value: "/etc/modprobe.d" + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`kernel_module` 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." +- "`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 + :load: + markdown: Load a kernel module. + :unload: + markdown: Unload kernel module. +properties_list: +- property: load_dir + ruby_type: String + required: false + default_value: "/etc/modules-load.d" + description_list: + - markdown: The directory to load modules from. +- property: modname + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the kernel module name if it differs from + the resource block's name. +- property: options + ruby_type: Array + required: false + new_in: '15.4' + description_list: + - markdown: An optional property to set options for the kernel module. +- property: unload_dir + ruby_type: String + required: false + 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. + + ```ruby + kernel_module 'loop' + ``` + + Install and load a kernel with a specific set of options, and ensure it loads on reboot. Consult kernel module + documentation for specific options that are supported. + + ```ruby + kernel_module 'loop' do + options [ + 'max_loop=4', + 'max_part=8', + ] + end + ``` + + Load a kernel module. + + ```ruby + kernel_module 'loop' do + action :load + end + ``` + + Unload a kernel module and remove module config, so it doesn't load on reboot. + + ```ruby + kernel_module 'loop' do + action :uninstall + end + ``` + + Unload kernel module. + + ```ruby + kernel_module 'loop' do + action :unload + end + ``` + + Blacklist a module from loading. + + ```ruby + kernel_module 'loop' do + action :blacklist + end + ``` + + Disable a kernel module so that it is not installable. + + ```ruby + kernel_module 'loop' do + action :disable + end + ``` + + Enable a kernel module so that it is can be installed. Does not load or install. + + ```ruby + kernel_module 'loop' do + action :enable + end + ``` diff --git a/data/infra/resources/ksh.yaml b/data/infra/resources/ksh.yaml new file mode 100644 index 0000000..004161d --- /dev/null +++ b/data/infra/resources/ksh.yaml @@ -0,0 +1,209 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: ksh +resource_description_list: +- markdown: Use the **ksh** resource to execute scripts using the Korn shell (ksh) + interpreter. This resource may also use any of the actions and properties that + are available to the **execute** resource. Commands that are executed with this + resource are (by their nature) not idempotent, as they are typically unique to + the environment in which they are run. Use `not_if` and `only_if` to guard this + resource for idempotence. +syntax_description: | + A **ksh** resource block executes scripts using ksh: + + ```ruby + ksh 'hello world' do + code <<-EOH + echo "Hello world!" + echo "Current directory: " $cwd + EOH + end + ``` + + where: + + - `code` specifies the command to run. +resource_new_in: '12.6' +syntax_full_code_block: |- + ksh '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 + user String, Integer + action Symbol # defaults to :run if not specified + end +syntax_properties_list: +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." +- "`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 + description_list: + - markdown: Prevent a command from creating a file when that file already exists. +- property: cwd + ruby_type: String + 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 + description_list: + - 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: 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 + 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: 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: user + ruby_type: String, Integer + required: false + description_list: + - 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 new file mode 100644 index 0000000..2f7115c --- /dev/null +++ b/data/infra/resources/launchd.yaml @@ -0,0 +1,413 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: launchd +resource_description_list: +- markdown: Use the **launchd** resource to manage system-wide services (daemons) + and per-user services (agents) on the macOS platform. +resource_new_in: '12.8' +syntax_full_code_block: |- + launchd 'name' do + abandon_process_group true, false + associated_bundle_identifiers Array + backup Integer, false + cookbook String + debug true, false + disabled true, false # default value: false + enable_globbing true, false + enable_transactions true, false + environment_variables Hash + exit_timeout Integer + group String, Integer + hard_resource_limits Hash + inetd_compatibility Hash + init_groups true, false + keep_alive true, false, Hash + label String # default value: 'name' unless specified + launch_events Hash + launch_only_once true, false + ld_group String + limit_load_from_hosts Array + limit_load_to_hosts Array + limit_load_to_session_type Array, String + low_priority_io true, false + mach_services Hash + mode String, Integer + nice Integer + on_demand true, false + owner String, Integer + path String + plist_hash Hash + process_type String + program String + program_arguments Array + queue_directories Array + root_directory String + run_at_load true, false + session_type String + sockets Hash + soft_resource_limits Array + source String + standard_error_path String + standard_in_path String + standard_out_path String + start_calendar_interval Hash, Array + start_interval Integer + start_on_mount true, false + throttle_interval Integer + time_out Integer + type String # default value: "daemon" + username String + wait_for_debugger true, false + watch_paths Array + working_directory String + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`launchd` 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." +- "`abandon_process_group`, `associated_bundle_identifiers`, `backup`, `cookbook`, + `debug`, `disabled`, `enable_globbing`, `enable_transactions`, `environment_variables`, + `exit_timeout`, `group`, `hard_resource_limits`, `inetd_compatibility`, `init_groups`, + `keep_alive`, `label`, `launch_events`, `launch_only_once`, `ld_group`, `limit_load_from_hosts`, + `limit_load_to_hosts`, `limit_load_to_session_type`, `low_priority_io`, `mach_services`, + `mode`, `nice`, `on_demand`, `owner`, `path`, `plist_hash`, `process_type`, `program`, + `program_arguments`, `queue_directories`, `root_directory`, `run_at_load`, `session_type`, + `sockets`, `soft_resource_limits`, `source`, `standard_error_path`, `standard_in_path`, + `standard_out_path`, `start_calendar_interval`, `start_interval`, `start_on_mount`, + `throttle_interval`, `time_out`, `type`, `username`, `wait_for_debugger`, `watch_paths`, + and `working_directory` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Create a launchd property list. (default) + :create_if_missing: + markdown: Create a launchd property list, if it does not already exist. + :delete: + markdown: Delete a launchd property list. This will unload a daemon or agent, + if loaded. + :enable: + markdown: Create a launchd property list, and then ensure that it is enabled. + If a launchd property list already exists, but does not match, updates the property + list to match, and then restarts the daemon or agent. + :disable: + markdown: Disable a launchd property list. + :restart: + markdown: Restart a launchd managed daemon or agent. +properties_list: +- property: abandon_process_group + ruby_type: true, false + required: false + description_list: + - markdown: If a job dies, all remaining processes with the same process ID may + be kept running. Set to true to kill all remaining processes. +- property: associated_bundle_identifiers + ruby_type: Array + required: false + description_list: + - 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 + required: false + description_list: + - markdown: The number of backups to be kept in `/var/chef/backup`. Set to `false` + to prevent backups from being kept. +- property: cookbook + ruby_type: String + required: false + description_list: + - markdown: The name of the cookbook in which the source files are located. +- property: debug + ruby_type: true, false + required: false + description_list: + - markdown: Sets the log mask to `LOG_DEBUG` for this job. +- property: disabled + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Hints to `launchctl` to not submit this job to launchd. +- property: enable_globbing + ruby_type: true, false + required: false + description_list: + - markdown: Update program arguments before invocation. +- property: enable_transactions + ruby_type: true, false + required: false + description_list: + - markdown: Track in-progress transactions; if none, then send the `SIGKILL` signal. +- property: environment_variables + ruby_type: Hash + required: false + description_list: + - markdown: Additional environment variables to set before running a job. +- property: exit_timeout + ruby_type: Integer + required: false + description_list: + - markdown: The amount of time (in seconds) launchd waits before sending a `SIGKILL` + signal. +- property: group + ruby_type: String, Integer + required: false + description_list: + - 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 + required: false + description_list: + - markdown: A Hash of resource limits to be imposed on a job. +- property: inetd_compatibility + ruby_type: Hash + required: false + description_list: + - markdown: Specifies if a daemon expects to be run as if it were launched from + inetd. Set to `wait => true` to pass standard input, output, and error file + descriptors. Set to `wait => false` to call the accept system call on behalf + of the job, and then pass standard input, output, and error file descriptors. +- property: init_groups + ruby_type: true, false + required: false + description_list: + - markdown: Specify if `initgroups` is called before running a job. +- property: keep_alive + ruby_type: true, false, Hash + required: false + new_in: '12.14' + description_list: + - markdown: Keep a job running continuously (true) or allow demand and conditions + on the node to determine if the job keeps running (`false`). +- property: label + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: The unique identifier for the job. +- property: launch_events + ruby_type: Hash + required: false + new_in: '15.1' + description_list: + - markdown: Specify higher-level event types to be used as launch-on-demand event + sources. +- property: launch_only_once + ruby_type: true, false + required: false + description_list: + - markdown: Specify if a job can be run only one time. Set this value to true if + a job cannot be restarted without a full machine reboot. +- property: ld_group + ruby_type: String + required: false + description_list: + - markdown: The group name. +- property: limit_load_from_hosts + ruby_type: Array + required: false + description_list: + - markdown: An array of hosts to which this configuration file does not apply, i.e. + 'apply this configuration file to all hosts not specified in this array'. +- property: limit_load_to_hosts + ruby_type: Array + required: false + description_list: + - markdown: An array of hosts to which this configuration file applies. +- property: limit_load_to_session_type + ruby_type: Array, String + required: false + description_list: + - markdown: The session type(s) to which this configuration file applies. +- property: low_priority_io + ruby_type: true, false + required: false + description_list: + - markdown: Specify if the kernel on the node should consider this daemon to be + low priority during file system I/O. +- property: mach_services + ruby_type: Hash + required: false + description_list: + - markdown: Specify services to be registered with the bootstrap subsystem. +- property: mode + ruby_type: String, Integer + required: false + description_list: + - markdown: 'A quoted 3-5 character string that defines the octal mode. For example: + ''755'', ''0755'', or 00755.' +- property: nice + ruby_type: Integer + required: false + description_list: + - markdown: The program scheduling priority value in the range -20 to 19. +- property: on_demand + ruby_type: true, false + required: false + description_list: + - markdown: Keep a job alive. Only applies to macOS version 10.4 (and earlier); + use `keep_alive` instead for newer versions. +- property: owner + ruby_type: String, Integer + 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 + is not specified, existing owners remain unchanged and new owner assignments + use the current user (when necessary). +- property: path + ruby_type: String + required: false + description_list: + - markdown: The path to the directory. Using a fully qualified path is recommended, + but is not always required. +- property: plist_hash + ruby_type: Hash + required: false + new_in: '12.19' + description_list: + - markdown: A Hash of key value pairs used to create the launchd property list. +- property: process_type + ruby_type: String + required: false + description_list: + - markdown: 'The intended purpose of the job: `Adaptive`, `Background`, `Interactive`, + or `Standard`.' +- property: program + ruby_type: String + required: false + description_list: + - markdown: The first argument of `execvp`, typically the file name associated with + the file to be executed. This value must be specified if `program_arguments` + is not specified, and vice-versa. +- property: program_arguments + ruby_type: Array + required: false + description_list: + - markdown: The second argument of `execvp`. If program is not specified, this property + must be specified and will be handled as if it were the first argument. +- property: queue_directories + ruby_type: Array + required: false + description_list: + - markdown: An array of non-empty directories which, if any are modified, will cause + a job to be started. +- property: root_directory + ruby_type: String + required: false + description_list: + - markdown: "`chroot` to this directory, and then run the job." +- property: run_at_load + ruby_type: true, false + required: false + description_list: + - markdown: Launch a job once (at the time it is loaded). +- property: session_type + ruby_type: String + required: false + description_list: + - markdown: 'The type of launchd plist to be created. Possible values: system (default) + or user.' +- property: sockets + ruby_type: Hash + required: false + description_list: + - markdown: A Hash of on-demand sockets that notify launchd when a job should be + run. +- property: soft_resource_limits + ruby_type: Array + required: false + description_list: + - markdown: A Hash of resource limits to be imposed on a job. +- property: source + ruby_type: String + required: false + description_list: + - markdown: The path to the launchd property list. +- property: standard_error_path + ruby_type: String + required: false + description_list: + - markdown: The file to which standard error (`stderr`) is sent. +- property: standard_in_path + ruby_type: String + required: false + description_list: + - markdown: The file to which standard input (`stdin`) is sent. +- property: standard_out_path + ruby_type: String + required: false + description_list: + - markdown: The file to which standard output (`stdout`) is sent. +- property: start_calendar_interval + ruby_type: Hash, Array + required: false + description_list: + - 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 + description_list: + - markdown: The frequency (in seconds) at which a job is started. +- property: start_on_mount + ruby_type: true, false + required: false + description_list: + - markdown: Start a job every time a file system is mounted. +- property: throttle_interval + ruby_type: Integer + required: false + description_list: + - markdown: The frequency (in seconds) at which jobs are allowed to spawn. +- property: time_out + ruby_type: Integer + required: false + description_list: + - markdown: The amount of time (in seconds) a job may be idle before it times out. + If no value is specified, the default timeout value for launchd will be used. +- property: type + ruby_type: String + required: false + default_value: daemon + description_list: + - markdown: 'The type of resource. Possible values: daemon (default), agent.' +- property: username + ruby_type: String + required: false + description_list: + - markdown: When launchd is run as the root user, the user to run the job as. +- property: wait_for_debugger + ruby_type: true, false + required: false + description_list: + - markdown: Specify if launchd has a job wait for a debugger to attach before executing + code. +- property: watch_paths + ruby_type: Array + required: false + description_list: + - markdown: An array of paths which, if any are modified, will cause a job to be + started. +- property: working_directory + ruby_type: String + 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 \ + \ Create a Launch Daemon using keys\n\n ```ruby\n launchd 'call.mom.weekly' do\n\ + \ program '/Library/scripts/call_mom.sh'\n start_calendar_interval 'Weekday'\ + \ => 7, 'Hourly' => 10\n time_out 300\n end\n ```\n\n Remove a Launch Daemon\n\ + \n ```ruby\n launchd 'com.chef.every15' do\n action :delete\n end\n ```\n" diff --git a/data/infra/resources/link.yaml b/data/infra/resources/link.yaml new file mode 100644 index 0000000..13950a4 --- /dev/null +++ b/data/infra/resources/link.yaml @@ -0,0 +1,193 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: link +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, '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. +syntax_description: | + A **link** resource block creates symbolic or hard links. For + example, to create a hard link from `/tmp/file` to `/etc/file`: + + ```ruby + link '/tmp/file' do + to '/etc/file' + link_type :hard + end + ``` + + Because the default value for `link_type` is symbolic, and because + properties that are not specified in the resource block will be assigned + their default values, the following example creates a symbolic link: + + ```ruby + link '/tmp/file' do + to '/etc/file' + end + ``` +syntax_full_code_block: |- + link 'name' do + group String, Integer + link_type String, Symbol # default value: :symbolic + owner String, Integer + target_file String # default value: 'name' unless specified + to String + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`link` 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." +- "`group`, `link_type`, `owner`, `target_file`, and `to` are the properties available + to this resource." +actions_list: + :create: + markdown: (default) Create a link. If a link already exists (but does not match), + update that link to match. + :delete: + markdown: Delete a link. + :nothing: + shortcode: resources_common_actions_nothing.md +properties_list: +- property: group + ruby_type: String, Integer + required: false + description_list: + - markdown: A group name or ID number that identifies the group associated with + a symbolic link. +- property: link_type + ruby_type: String, Symbol + required: false + default_value: ":symbolic" + allowed_values: ":hard, :symbolic" + description_list: + - markdown: 'The type of link: :symbolic or :hard.' +- property: owner + ruby_type: String, Integer + required: false + description_list: + - markdown: The owner associated with a symbolic link. +- property: target_file + ruby_type: String + 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. +- 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** + + The following example will create a symbolic link from `/tmp/file` to `/etc/file`: + + ```ruby + link '/tmp/file' do + to '/etc/file' + end + ``` + + **Create hard links** + + The following example will create a hard link from `/tmp/file` to `/etc/file`: + + ```ruby + link '/tmp/file' do + to '/etc/file' + link_type :hard + end + ``` + + **Delete links** + + The following example will delete the `/tmp/file` symbolic link and uses + the `only_if` guard to run the `test -L` command, which verifies that + `/tmp/file` is a symbolic link, and then only deletes `/tmp/file` if the + test passes: + + ```ruby + link '/tmp/file' do + action :delete + only_if + 'test -L /tmp/file' + end + ``` + + **Create multiple symbolic links** + + The following example creates symbolic links from two files in the `/vol/webserver/cert/` + directory to files located in the `/etc/ssl/certs/` directory: + + ```ruby + link '/vol/webserver/cert/server.crt' do + to '/etc/ssl/certs/ssl-cert-name.pem' + end + + link '/vol/webserver/cert/server.key' do + to '/etc/ssl/certs/ssl-cert-name.key' + end + ``` + + **Create platform-specific symbolic links** + + The following example shows installing a filter module on Apache. The package name is different for + different platforms, and for the Red Hat Enterprise Linux family, a symbolic link is required: + + ```ruby + include_recipe 'apache2::default' + + case node['platform_family'] + when 'debian' + ... + when 'suse' + ... + when 'rhel', 'fedora' + ... + + link '/usr/lib64/httpd/modules/mod_apreq.so' do + to '/usr/lib64/httpd/modules/mod_apreq2.so' + only_if 'test -f /usr/lib64/httpd/modules/mod_apreq2.so' + end + + link '/usr/lib/httpd/modules/mod_apreq.so' do + to '/usr/lib/httpd/modules/mod_apreq2.so' + only_if 'test -f /usr/lib/httpd/modules/mod_apreq2.so' + end + end + ... + + ``` + + + For the complete recipe, see + . + + + **Create Windows junction/reparse points** + + This example demonstrates how to create a directory junction/reparse point. In this example, `C:\\destination` + will be a junction/reparse point to the `C:\\source` directory. + + ```ruby + directory 'C:/source' + + link 'C:/destination' do + link_type :symbolic + to 'C:/source' + end + ``` + diff --git a/data/infra/resources/locale.yaml b/data/infra/resources/locale.yaml new file mode 100644 index 0000000..391216a --- /dev/null +++ b/data/infra/resources/locale.yaml @@ -0,0 +1,51 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: locale +resource_description_list: +- markdown: Use the **locale** resource to set the system's locale on Debian and Windows + systems. Windows support was added in Chef Infra Client 16.0 +resource_new_in: '14.5' +syntax_full_code_block: |- + locale 'name' do + lang String + lc_env Hash # default value: {} + action Symbol # defaults to :update if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`locale` 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." +- "`lang` and `lc_env` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :update: + markdown: Update the system's locale. (default) +properties_list: +- property: lang + ruby_type: String + required: false + description_list: + - markdown: Sets the default system language. +- property: lc_env + ruby_type: Hash + required: false + default_value: "{}" + 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' + + ```ruby + locale 'set system locale' do + lang 'en_US.UTF-8' + end + ``` diff --git a/data/infra/resources/log.yaml b/data/infra/resources/log.yaml new file mode 100644 index 0000000..07bdb41 --- /dev/null +++ b/data/infra/resources/log.yaml @@ -0,0 +1,56 @@ +--- +resource_reference: true +properties_shortcode: resource_log_properties.md +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +ruby_style_basics_chef_log: true +syntax_shortcode: resource_log_syntax.md +resource: log +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.)' +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)" +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\ + \ log 'message' do\n message 'This is the message that will be added to the\ + \ log.'\n level :info\n end\n ```\n" diff --git a/data/infra/resources/macos_pkg.yaml b/data/infra/resources/macos_pkg.yaml new file mode 100644 index 0000000..19ca7cf --- /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 new file mode 100644 index 0000000..ea11838 --- /dev/null +++ b/data/infra/resources/macos_userdefaults.yaml @@ -0,0 +1,105 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: macos_userdefaults +resource_description_list: +- markdown: Use the **macos_userdefaults** resource to manage the macOS user defaults + system. The properties of this resource are passed to the defaults command, and + the parameters follow the convention of that command. See the defaults(1) man + page for details on how the tool works. +resource_new_in: '14.0' +syntax_full_code_block: |- + macos_userdefaults 'name' do + domain String # default value: NSGlobalDomain: the global domain. + host String, Symbol # default value: :all + key String + user String, Symbol # default value: :current + value Integer, Float, String, true, false, Hash, Array + action Symbol # defaults to :write if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`macos_userdefaults` 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." +- "`domain`, `host`, `key`, `user`, and `value` are the properties available to this + resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :write: + markdown: Write the value to the specified domain/key. (default) + :delete: + markdown: Delete a key from a domain. +properties_list: +- property: domain + ruby_type: String + required: false + default_value: 'NSGlobalDomain: the global domain.' + description_list: + - markdown: The domain that the user defaults belong to. +- property: host + ruby_type: String, Symbol + required: false + default_value: ":all" + new_in: '16.3' + description_list: + - markdown: Set either :current, :all or a hostname to set the user default at the + host level. +- property: key + ruby_type: String + required: true + description_list: + - markdown: The preference key. +- property: user + ruby_type: String, Symbol + required: false + default_value: ":current" + description_list: + - markdown: The system user that the default will be applied to. Set :current for + current user, :all for all users or pass a valid username +- property: value + ruby_type: Integer, Float, String, true, false, Hash, Array + required: true + description_list: + - markdown: The value of the key. + - note: + 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''.' +target_mode: +examples: |+ + **Specify a global domain value** + + ```ruby + macos_userdefaults 'Full keyboard access to all controls' do + key 'AppleKeyboardUIMode' + value 2 + end + ``` + + **Setting a value on a specific domain** + + ```ruby + macos_userdefaults 'Enable macOS firewall' do + domain '/Library/Preferences/com.apple.alf' + key 'globalstate' + value 1 + end + ``` + + **Setting a value for specific user and hosts** + + ```ruby + macos_userdefaults 'Enable macOS firewall' do + key 'globalstate' + value 1 + user 'jane' + host :current + end + ``` + +... diff --git a/data/infra/resources/macosx_service.yaml b/data/infra/resources/macosx_service.yaml new file mode 100644 index 0000000..0f7ad66 --- /dev/null +++ b/data/infra/resources/macosx_service.yaml @@ -0,0 +1,175 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: macosx_service +resource_description_list: +- markdown: Use the **macosx_service** resource to manage services on the macOS platform. +syntax_full_code_block: |- + macosx_service 'name' do + init_command String + options Array, String + parameters Hash + pattern String + plist String + priority Integer, String, Hash + reload_command String, false + restart_command String, false + run_levels Array + service_name String # default value: 'name' unless specified + session_type String + start_command String, false + status_command String, false + stop_command String, false + supports Hash # default value: {"restart"=>nil, "reload"=>nil, "status"=>nil} + timeout Integer # default value: 900 + user String + action Symbol # defaults to :nothing if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`macosx_service` 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." +- "`init_command`, `options`, `parameters`, `pattern`, `plist`, `priority`, `reload_command`, + `restart_command`, `run_levels`, `service_name`, `session_type`, `start_command`, + `status_command`, `stop_command`, `supports`, `timeout`, and `user` are the properties + available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :enable: + markdown: Enable a service at boot. + :disable: + markdown: Disable a service. + :start: + markdown: Start a service, and keep it running until stopped or disabled. + :stop: + markdown: Stop a service. It will stay stopped until restarted. + :restart: + 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 + 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: 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: plist + ruby_type: String + required: false + description_list: + - markdown: A plist to use in the case where the filename and label for the service + do not match. +- 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 + description_list: + - markdown: The command used to tell a service to reload its configuration. +- property: restart_command + ruby_type: String, false + required: false + description_list: + - markdown: The command used to restart a service. +- 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 + default_value: The resource block's name + description_list: + - markdown: An optional property to set the service name if it differs from the + resource block's name. +- property: session_type + ruby_type: String + required: false + description_list: + - markdown: +- property: start_command + ruby_type: String, false + required: false + description_list: + - markdown: The command used to start a service. +- property: status_command + ruby_type: String, false + required: false + description_list: + - markdown: The command used to check the run status for a service. +- property: stop_command + ruby_type: String, false + required: false + description_list: + - markdown: The command used to stop a service. +- property: supports + ruby_type: Hash + 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, + 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: '900' + 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: diff --git a/data/infra/resources/macports_package.yaml b/data/infra/resources/macports_package.yaml new file mode 100644 index 0000000..654dd87 --- /dev/null +++ b/data/infra/resources/macports_package.yaml @@ -0,0 +1,103 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: macports_package +resource_description_list: +- markdown: Use the **macports_package** resource to manage packages for the macOS + platform using the MacPorts package management system. +syntax_description: 'A **macports_package** resource block manages a package on a + node, + + typically by installing it. The simplest use of the + + **macports_package** resource is: + + + ```ruby + + macports_package ''package_name'' + + ``` + + + which will install the named package using all of the default options + + and the default action (`:install`).' +syntax_full_code_block: |- + macports_package 'name' do + environment Hash + options String, Array + package_name String + source String + timeout String, Integer + version String + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`macports_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: 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 + description_list: + - markdown: One (or more) additional command options that are passed to the command. +- property: package_name + ruby_type: String + required: false + description_list: + - 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: The optional path to a package on the local file system. +- property: timeout + ruby_type: String, Integer + required: false + description_list: + - markdown: The amount of time (in seconds) to wait before timing out. +- property: version + ruby_type: String + 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 new file mode 100644 index 0000000..250069b --- /dev/null +++ b/data/infra/resources/mdadm.yaml @@ -0,0 +1,132 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: mdadm +resource_description_list: +- markdown: Use the **mdadm** resource to manage RAID devices in a Linux environment + using the mdadm utility. The mdadm resource will create and assemble an array, + but it will not create the config file that is used to persist the array upon + reboot. If the config file is required, it must be done by specifying a template + with the correct array layout, and then by using the mount provider to create + a file systems table (fstab) entry. +syntax_full_code_block: |- + mdadm 'name' do + bitmap String + chunk Integer # default value: 16 + devices Array # default value: [] + layout String + level Integer # default value: 1 + metadata String # default value: "0.90" + raid_device String # default value: 'name' unless specified + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`mdadm` 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." +- "`bitmap`, `chunk`, `devices`, `layout`, `level`, `metadata`, and `raid_device` + are the properties available to this resource." +actions_list: + :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) + :assemble: + markdown: Assemble a previously created array into an active array. + :stop: + markdown: Stop an active array. +properties_list: +- property: bitmap + ruby_type: String + required: false + description_list: + - markdown: The path to a file in which a write-intent bitmap is stored. +- property: chunk + ruby_type: Integer + required: false + default_value: '16' + description_list: + - markdown: The chunk size. This property should not be used for a RAID 1 mirrored + pair (i.e. when the `level` property is set to `1`). +- property: devices + ruby_type: Array + required: false + default_value: "[]" + description_list: + - markdown: The devices to be part of a RAID array. +- property: layout + ruby_type: String + required: false + description_list: + - markdown: 'The RAID5 parity algorithm. Possible values: `left-asymmetric` (or + `la`), `left-symmetric` (or ls), `right-asymmetric` (or `ra`), or `right-symmetric` + (or `rs`).' +- property: level + ruby_type: Integer + required: false + default_value: '1' + description_list: + - markdown: The RAID level. +- property: metadata + ruby_type: String + required: false + default_value: '0.90' + description_list: + - markdown: The superblock type for RAID metadata. +- property: raid_device + ruby_type: String + required: false + default_value: The resource block's name + 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** + + The mdadm command can be used to create RAID arrays. For example, a RAID 0 array named /dev/md0 with 10 devices would have a command similar to the following: + + ``` + mdadm --create /dev/md0 --level=0 --raid-devices=10 /dev/s01.../dev/s10 + ``` + + where /dev/s01 .. /dev/s10 represents 10 devices (01, 02, 03, and so on). This same command, when expressed as a recipe using the mdadm resource, would be similar to: + + ```ruby + mdadm '/dev/md0' do + devices [ '/dev/s01', ... '/dev/s10' ] + level 0 + action :create + end + ``` + + (again, where /dev/s01 .. /dev/s10 represents devices /dev/s01, /dev/s02, /dev/s03, and so on). + + **Create and assemble a RAID 1 array** + + ```ruby + mdadm '/dev/md0' do + devices [ '/dev/sda', '/dev/sdb' ] + level 1 + action [ :create, :assemble ] + end + ``` + + **Create and assemble a RAID 5 array** + + The mdadm command can be used to create RAID arrays. For example, a RAID 5 array named /dev/sd0 with 4, and a superblock type of 0.90 would be similar to: + + ```ruby + mdadm '/dev/sd0' do + devices [ '/dev/s1', '/dev/s2', '/dev/s3', '/dev/s4' ] + level 5 + metadata '0.90' + chunk 32 + action :create + end + ``` diff --git a/data/infra/resources/mount.yaml b/data/infra/resources/mount.yaml new file mode 100644 index 0000000..325ecbb --- /dev/null +++ b/data/infra/resources/mount.yaml @@ -0,0 +1,174 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: mount +resource_description_list: +- markdown: Use the **mount** resource to manage a mounted file system. +syntax_full_code_block: |- + mount 'name' do + device String + device_type String, Symbol # default value: :device + domain String + dump Integer, false # default value: 0 + enabled true, false # default value: false + fsck_device String # default value: "-" + fstype String # default value: "auto" + mount_point String # default value: 'name' unless specified + options Array, String # default value: ["defaults"] + pass Integer, false # default value: 2 + password String + supports Array, Hash # default value: "{ remount: false }" + username String + action Symbol # defaults to :mount if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`mount` 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." +- "`device`, `device_type`, `domain`, `dump`, `enabled`, `fsck_device`, `fstype`, + `mount_point`, `options`, `pass`, `password`, `supports`, and `username` are the + properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :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 + required: false + description_list: + - markdown: Required for `:umount` and `:remount` actions (for the purpose of checking + the mount command output for presence). The special block device or remote node, + a label, or a uuid to be mounted. +- property: device_type + ruby_type: String, Symbol + required: false + default_value: ":device" + allowed_values: ":device, :label, :uuid" + description_list: + - markdown: 'The type of device: :device, :label, or :uuid' +- property: domain + ruby_type: String + required: false + description_list: + - markdown: 'Windows only: Use to specify the domain in which the `username` and + `password` are located.' +- property: dump + ruby_type: Integer, false + required: false + default_value: '0' + description_list: + - markdown: The dump frequency (in days) used while creating a file systems table + (fstab) entry. +- property: enabled + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Use to specify if a mounted file system is enabled. +- property: fsck_device + ruby_type: String + required: false + default_value: "-" + description_list: + - markdown: 'Solaris only: The fsck device.' +- property: fstype + ruby_type: String + required: false + default_value: auto + description_list: + - markdown: The file system type (fstype) of the device. +- property: mount_point + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: The directory (or path) in which the device is to be mounted. Defaults + to the name of the resource block if not provided. +- property: options + ruby_type: Array, String + required: false + default_value: '["defaults"]' + description_list: + - markdown: An array or comma separated list of options for the mount. +- property: pass + ruby_type: Integer, false + required: false + default_value: '2' + description_list: + - markdown: The pass number used by the file system check (fsck) command while creating + a file systems table (fstab) entry. +- property: password + ruby_type: String + required: false + description_list: + - markdown: Windows only:. Use to specify the password for username. +- property: supports + ruby_type: Array, Hash + required: false + default_value: "{ remount: false }" + description_list: + - markdown: Specify a Hash of supported mount features. +- property: username + ruby_type: String + required: false + description_list: + - 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\ + \ 'rw'\n end\n ```\n\n Mount a local block drive\n\n ```ruby\n mount '/mnt/local'\ + \ do\n device '/dev/sdb1'\n fstype 'ext3'\n end\n ```\n\n Mount a non-block\ + \ file system\n\n ```ruby\n mount '/mount/tmp' do\n pass 0\n fstype\ + \ 'tmpfs'\n device '/dev/null'\n options 'nr_inodes=999k,mode=755,size=500m'\n\ + \ action [:mount, :enable]\n end\n ```\n\n Mount and add to the file systems\ + \ table\n\n ```ruby\n mount '/export/www' do\n device 'nas1prod:/export/web_sites'\n\ + \ fstype 'nfs'\n options 'rw'\n action [:mount, :enable]\n end\n ```\n\ + \n Mount a remote file system\n\n ```ruby\n mount '/export/www' do\n device\ + \ 'nas1prod:/export/web_sites'\n fstype 'nfs'\n options 'rw'\n end\n ```\n\ + \n Mount a remote folder in Microsoft Windows\n\n ```ruby\n mount 'T:' do\n\ + \ action :mount\n device '\\\\\\\\hostname.example.com\\\\folder'\n end\n\ + \ ```\n\n Unmount a remote folder in Microsoft Windows\n\n ```ruby\n mount\ + \ 'T:' do\n action :umount\n device '\\\\\\\\hostname.example.com\\\\D$'\n\ + \ end\n ```\n\n Stop a service, do stuff, and then restart it\n\n The following\ + \ example shows how to use the **execute**, **service**, and\n **mount** resources\ + \ together to ensure that a node running on Amazon EC2\n is running MySQL. This\ + \ example does the following:\n\n - Checks to see if the Amazon EC2 node has\ + \ MySQL\n - If the node has MySQL, stops MySQL\n - Installs MySQL\n - Mounts\ + \ the node\n - Restarts MySQL\n\n \n\n ```ruby\n # the following\ + \ code sample comes from the ``server_ec2``\n # recipe in the following cookbook:\n\ + \ # https://github.com/chef-cookbooks/mysql\n\n if (node.attribute?('ec2') &&\ + \ ! FileTest.directory?(node['mysql']['ec2_path']))\n\n service 'mysql' do\n\ + \ action :stop\n end\n\n execute 'install-mysql' do\n command \"\ + mv #{node['mysql']['data_dir']} #{node['mysql']['ec2_path']}\"\n not_if do\ + \ FileTest.directory?(node['mysql']['ec2_path']) end\n end\n\n [node['mysql']['ec2_path'],\ + \ node['mysql']['data_dir']].each do |dir|\n directory dir do\n owner\ + \ 'mysql'\n group 'mysql'\n end\n end\n\n mount node['mysql']['data_dir']\ + \ do\n device node['mysql']['ec2_path']\n fstype 'none'\n options\ + \ 'bind,rw'\n action [:mount, :enable]\n end\n\n service 'mysql' do\n\ + \ action :start\n end\n\n end\n ```\n\n where\n\n - the two **service**\ + \ resources are used to stop, and then restart the\n MySQL service\n - the\ + \ **execute** resource is used to install MySQL\n - the **mount** resource is\ + \ used to mount the node and enable MySQL\n" + diff --git a/data/infra/resources/msu_package.yaml b/data/infra/resources/msu_package.yaml new file mode 100644 index 0000000..4d9cf55 --- /dev/null +++ b/data/infra/resources/msu_package.yaml @@ -0,0 +1,96 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: msu_package +resource_description_list: +- markdown: Use the **msu_package** resource to install Microsoft Update(MSU) packages + on Microsoft Windows machines. +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 + timeout String, Integer # default value: 3600 + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`msu_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." +- "`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 + description_list: + - markdown: One (or more) additional command options that are passed to the command. +- property: package_name + ruby_type: String + required: false + description_list: + - 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 + default_value: lazy default + description_list: + - markdown: The local file path or URL for the MSU package. +- property: timeout + ruby_type: String, Integer + required: false + 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\\\ + Temp\\Windows8.1-KB2959977-x64.msu'\n action :install\n end\n ```\n\n ```\ + \ ruby\n msu_package 'Remove Windows 2012R2 Update KB2959977' do\n source 'C:\\\ + Users\\xyz\\AppData\\Local\\Temp\\Windows8.1-KB2959977-x64.msu'\n action :remove\n\ + \ end\n ```\n\n Using URL in source\n\n ```ruby\n msu_package 'Install Windows\ + \ 2012R2 Update KB2959977' do\n source 'https://s3.amazonaws.com/my_bucket/Windows8.1-KB2959977-x64.msu'\n\ + \ action :install\n end\n ```\n\n ```ruby\n msu_package 'Remove Windows\ + \ 2012R2 Update KB2959977' do\n source 'https://s3.amazonaws.com/my_bucket/Windows8.1-KB2959977-x64.msu'\n\ + \ action :remove\n end\n ```\n" + diff --git a/data/infra/resources/notify_group.yaml b/data/infra/resources/notify_group.yaml new file mode 100644 index 0000000..2069204 --- /dev/null +++ b/data/infra/resources/notify_group.yaml @@ -0,0 +1,60 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: notify_group +resource_description_list: +- markdown: The notify_group resource does nothing, and always fires notifications + which are set on it. Use it to DRY blocks of notifications that are common to + multiple resources, and provide a single target for other resources to notify. Unlike + most resources, its default action is :nothing. +resource_new_in: '15.8' +syntax_full_code_block: |- + notify_group 'name' do + action Symbol # defaults to :nothing if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`notify_group` 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." +actions_list: + :nothing: + 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. + + ```ruby + service "crude" do + action [ :enable, :start ] + end + + chef_sleep "60" do + action :nothing + end + + # Example code for a hypothetical badly behaved service that requires + # 60 seconds between a stop and start in order to restart the service + # (due to race conditions, bleeding connections down, resources that only + # slowly unlock in the background, or other poor software behaviors that + # are sometimes encountered). + # + notify_group "crude_stop_and_start" do + notifies :stop, "service[crude]", :immediately + notifies :sleep, "chef_sleep[60]", :immediately + notifies :start, "service[crude]", :immediately + end + + template "/etc/crude/crude.conf" do + source "crude.conf.erb" + variables node["crude"] + notifies :run, "notify_group[crude_stop_and_start]", :immediately + end + ``` diff --git a/data/infra/resources/ohai.yaml b/data/infra/resources/ohai.yaml new file mode 100644 index 0000000..cfd4b3f --- /dev/null +++ b/data/infra/resources/ohai.yaml @@ -0,0 +1,81 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: ohai +resource_description_list: +- markdown: Use the **ohai** resource to reload the Ohai configuration on a node. + This allows recipes that change system attributes (like a recipe that adds a user) + to refer to those attributes later on during the Chef Infra Client run. +syntax_full_code_block: |- + ohai 'name' do + plugin String + action Symbol # defaults to :reload if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`ohai` 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." +- "`plugin` is the property available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :reload: + markdown: Reloads the Ohai data. (default) +properties_list: +- property: plugin + ruby_type: String + required: false + description_list: + - markdown: Specific Ohai attribute data to reload. This property behaves similar + to specifying attributes when running Ohai on the command line and takes the + attribute that you wish to reload instead of the actual plugin name. For instance, + 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 + + ```ruby + ohai 'reload' do + action :reload + end + ``` + + Reload A Single Ohai Plugin + + ```ruby + ohai 'reload' do + plugin 'ipaddress' + action :reload + end + ``` + + Reload Ohai after a new user is created + + ```ruby + ohai 'reload_passwd' do + action :nothing + plugin 'etc' + end + + user 'daemon_user' do + home '/dev/null' + shell '/sbin/nologin' + system true + notifies :reload, 'ohai[reload_passwd]', :immediately + end + + ruby_block 'just an example' do + block do + # These variables will now have the new values + puts node['etc']['passwd']['daemon_user']['uid'] + puts node['etc']['passwd']['daemon_user']['gid'] + end + end + ``` diff --git a/data/infra/resources/ohai_hint.yaml b/data/infra/resources/ohai_hint.yaml new file mode 100644 index 0000000..bb6cd45 --- /dev/null +++ b/data/infra/resources/ohai_hint.yaml @@ -0,0 +1,86 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: ohai_hint +resource_description_list: +- markdown: Use the **ohai_hint** resource to aid in configuration detection by passing + hint data to Ohai. +resource_new_in: '14.0' +syntax_full_code_block: |- + ohai_hint 'name' do + compile_time true, false # default value: true + content Hash + hint_name String # default value: 'name' unless specified + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`ohai_hint` 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." +- "`compile_time`, `content`, and `hint_name` are the properties available to this + resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Create an Ohai hint file. (default) + :delete: + markdown: Delete an Ohai hint file. +properties_list: +- property: compile_time + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Determines whether or not the resource is executed during the compile + time phase. +- property: content + ruby_type: Hash + required: false + description_list: + - markdown: Values to include in the hint file. +- property: hint_name + ruby_type: String + required: false + default_value: The resource block's name + 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** + + ```ruby + ohai_hint 'example' do + content a: 'test_content' + end + ``` + + **Create a hint file with a name that does not match the resource name** + + ```ruby + ohai_hint 'example' do + hint_name 'custom' + end + ``` + + **Create a hint file that is not loaded at compile time** + + ```ruby + ohai_hint 'example' do + compile_time false + end + ``` + + **Delete a hint file** + + ```ruby + ohai_hint 'example' do + action :delete + end + ``` diff --git a/data/infra/resources/openbsd_package.yaml b/data/infra/resources/openbsd_package.yaml new file mode 100644 index 0000000..857af4d --- /dev/null +++ b/data/infra/resources/openbsd_package.yaml @@ -0,0 +1,111 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: openbsd_package +resource_description_list: +- markdown: Use the **openbsd_package** resource to manage packages for the OpenBSD + platform. +- notes_resource_based_on_package: true +resource_new_in: '12.1' +syntax_description: | + An **openbsd_package** resource block manages a package on a node, + typically by installing it. The simplest use of the **openbsd_package** + resource is: + + ```ruby + openbsd_package 'package_name' + ``` + + which will install the named package using all of the default options + and the default action (`:install`). +syntax_full_code_block: |- + openbsd_package 'name' do + environment Hash + options String, Array + package_name String + source String + timeout String, Integer + version String + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`openbsd_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: 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 + description_list: + - markdown: One (or more) additional command options that are passed to the command. +- property: package_name + ruby_type: String + required: false + description_list: + - 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: The optional path to a package on the local file system. +- property: timeout + ruby_type: String, Integer + required: false + description_list: + - markdown: The amount of time (in seconds) to wait before timing out. +- property: version + ruby_type: String + required: false + description_list: + - markdown: The version of a package to be installed or upgraded. +target_mode: + support: full +examples: | + **Install a package** + + ```ruby + openbsd_package 'name of package' do + action :install + end + ``` + + **Remove a package** + + ```ruby + openbsd_package 'name of package' do + action :remove + end + ``` diff --git a/data/infra/resources/openssl_dhparam.yaml b/data/infra/resources/openssl_dhparam.yaml new file mode 100644 index 0000000..a2f0b60 --- /dev/null +++ b/data/infra/resources/openssl_dhparam.yaml @@ -0,0 +1,105 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: openssl_dhparam +resource_description_list: +- markdown: Use the **openssl_dhparam** resource to generate `dhparam.pem` files. + If a valid `dhparam.pem` file is found at the specified location, no new file + will be created. If a file is found at the specified location but it is not a + valid `dhparam.pem` file, it will be overwritten. +resource_new_in: '14.0' +syntax_full_code_block: |- + openssl_dhparam 'name' do + generator Integer # default value: 2 + group String, Integer + key_length Integer # default value: 2048 + mode Integer, String # default value: "0640" + owner String, Integer + path String # default value: 'name' unless specified + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`openssl_dhparam` 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." +- "`generator`, `group`, `key_length`, `mode`, `owner`, and `path` are the properties + available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Create the `dhparam.pem` file. (default) +properties_list: +- property: generator + ruby_type: Integer + required: false + default_value: '2' + allowed_values: 2, 5 + description_list: + - markdown: The desired Diffie-Hellmann generator. +- property: group + ruby_type: String, Integer + required: false + description_list: + - markdown: The group ownership applied to all files created by the resource. +- property: key_length + ruby_type: Integer + required: false + default_value: '2048' + allowed_values: 1024, 2048, 4096, 8192 + description_list: + - markdown: The desired bit length of the generated key. +- property: mode + ruby_type: Integer, String + required: false + default_value: '0640' + description_list: + - markdown: The permission mode applied to all files created by the resource. +- property: owner + ruby_type: String, Integer + required: false + description_list: + - markdown: The owner applied to all files created by the resource. +- property: path + ruby_type: String + required: false + default_value: The resource block's name + 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** + + ```ruby + openssl_dhparam '/etc/httpd/ssl/dhparam.pem' + ``` + + **Create a dhparam file with a specific key length** + + ```ruby + openssl_dhparam '/etc/httpd/ssl/dhparam.pem' do + key_length 4096 + end + ``` + + **Create a dhparam file with specific user/group ownership** + + ```ruby + openssl_dhparam '/etc/httpd/ssl/dhparam.pem' do + owner 'www-data' + group 'www-data' + end + ``` + + **Manually specify the dhparam file path** + + ```ruby + openssl_dhparam 'httpd_dhparam' do + path '/etc/httpd/ssl/dhparam.pem' + end + ``` diff --git a/data/infra/resources/openssl_ec_private_key.yaml b/data/infra/resources/openssl_ec_private_key.yaml new file mode 100644 index 0000000..7f22302 --- /dev/null +++ b/data/infra/resources/openssl_ec_private_key.yaml @@ -0,0 +1,111 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: openssl_ec_private_key +resource_description_list: +- markdown: Use the **openssl_ec_private_key** resource to generate an elliptic curve + (EC) private key file. If a valid EC key file can be opened at the specified location, + no new file will be created. If the EC key file cannot be opened, either because + it does not exist or because the password to the EC key file does not match the + password in the recipe, then it will be overwritten. +resource_new_in: '14.4' +syntax_full_code_block: |- + openssl_ec_private_key 'name' do + force true, false # default value: false + group String, Integer + key_cipher String # default value: "des3" + key_curve String # default value: "prime256v1" + key_pass String + mode Integer, String # default value: "0600" + owner String, Integer + path String # default value: 'name' unless specified + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`openssl_ec_private_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." +- "`force`, `group`, `key_cipher`, `key_curve`, `key_pass`, `mode`, `owner`, and `path` + are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Generate the EC private key file. (default) +properties_list: +- property: force + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Force creation of the key even if the same key already exists on the + node. +- property: group + ruby_type: String, Integer + required: false + description_list: + - markdown: The group ownership applied to all files created by the resource. +- property: key_cipher + ruby_type: String + required: false + default_value: des3 + description_list: + - markdown: The designed cipher to use when generating your key. Run `openssl list-cipher-algorithms` + to see available options. +- property: key_curve + ruby_type: String + required: false + default_value: prime256v1 + allowed_values: '"prime256v1", "secp224r1", "secp256k1", "secp384r1", "secp521r1"' + description_list: + - markdown: The desired curve of the generated key (if key_type is equal to 'ec'). + Run openssl ecparam -list_curves to see available options. +- property: key_pass + ruby_type: String + required: false + description_list: + - markdown: The desired passphrase for the key. +- property: mode + ruby_type: Integer, String + required: false + default_value: '0600' + description_list: + - markdown: The permission mode applied to all files created by the resource. +- property: owner + ruby_type: String, Integer + required: false + description_list: + - markdown: The owner applied to all files created by the resource. +- property: path + ruby_type: String + required: false + default_value: The resource block's name + 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** + + ```ruby + openssl_ec_private_key '/etc/ssl_files/eckey_prime256v1_des3.pem' do + key_curve 'prime256v1' + key_pass 'something' + action :create + end + ``` + + **Generate a new ec private key with prime256v1 key curve and aes-128-cbc cipher** + + ```ruby + openssl_ec_private_key '/etc/ssl_files/eckey_prime256v1_des3.pem' do + key_curve 'prime256v1' + key_cipher 'aes-128-cbc' + key_pass 'something' + action :create + end + ``` diff --git a/data/infra/resources/openssl_ec_public_key.yaml b/data/infra/resources/openssl_ec_public_key.yaml new file mode 100644 index 0000000..5a3c37a --- /dev/null +++ b/data/infra/resources/openssl_ec_public_key.yaml @@ -0,0 +1,100 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: openssl_ec_public_key +resource_description_list: +- markdown: Use the **openssl_ec_public_key** resource to generate elliptic curve + (EC) public key files from a given EC private key. +resource_new_in: '14.4' +syntax_full_code_block: |- + openssl_ec_public_key 'name' do + group String, Integer + mode Integer, String # default value: "0640" + owner String, Integer + path String # default value: 'name' unless specified + private_key_content String + private_key_pass String + private_key_path String + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`openssl_ec_public_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." +- "`group`, `mode`, `owner`, `path`, `private_key_content`, `private_key_pass`, and + `private_key_path` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Generate the EC public key file from a private key. (default) +properties_list: +- property: group + ruby_type: String, Integer + required: false + description_list: + - markdown: The group ownership applied to all files created by the resource. +- property: mode + ruby_type: Integer, String + required: false + default_value: '0640' + description_list: + - markdown: The permission mode applied to all files created by the resource. +- property: owner + ruby_type: String, Integer + required: false + description_list: + - markdown: The owner applied to all files created by the resource. +- property: path + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property for specifying the path to write the file to if + it differs from the resource block's name. +- property: private_key_content + ruby_type: String + required: false + description_list: + - markdown: The content of the private key including new lines. This property is + used in place of private_key_path in instances where you want to avoid having + to first write the private key to disk +- property: private_key_pass + ruby_type: String + required: false + description_list: + - markdown: The passphrase of the provided private key. +- property: private_key_path + ruby_type: String + 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** + + ```ruby + openssl_ec_public_key '/etc/ssl_files/eckey_prime256v1_des3.pub' do + private_key_path '/etc/ssl_files/eckey_prime256v1_des3.pem' + private_key_pass 'something' + action :create + end + ``` + + **Generate new EC public key by passing in a private key** + + ```ruby + openssl_ec_public_key '/etc/ssl_files/eckey_prime256v1_des3_2.pub' do + private_key_content "-----BEGIN EC PRIVATE KEY----- + MHcCAQEEII2VAU9re44mAUzYPWCg+qqwdmP8CplsEg0b/DYPXLg2oAoGCCqGSM49 + AwEHoUQDQgAEKkpMCbIQ2C6Qlp/B+Odp1a9Y06Sm8yqPvCVIkWYP7M8PX5+RmoIv + jGBVf/+mVBx77ji3NpTilMUt2KPZ87lZ3w== + -----END EC PRIVATE KEY----- + " + action :create + end + ``` diff --git a/data/infra/resources/openssl_rsa_private_key.yaml b/data/infra/resources/openssl_rsa_private_key.yaml new file mode 100644 index 0000000..23d1c4b --- /dev/null +++ b/data/infra/resources/openssl_rsa_private_key.yaml @@ -0,0 +1,108 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: openssl_rsa_private_key +resource_description_list: +- markdown: Use the **openssl_rsa_private_key** resource to generate RSA private key + files. If a valid RSA key file can be opened at the specified location, no new + file will be created. If the RSA key file cannot be opened, either because it + does not exist or because the password to the RSA key file does not match the + password in the recipe, it will be overwritten. +resource_new_in: '14.0' +syntax_full_code_block: |- + openssl_rsa_private_key 'name' do + force true, false # default value: false + group String, Integer + key_cipher String # default value: "des3" + key_length Integer # default value: 2048 + key_pass String + mode Integer, String # default value: "0600" + owner String, Integer + path String # default value: 'name' unless specified + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`openssl_rsa_private_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." +- "`force`, `group`, `key_cipher`, `key_length`, `key_pass`, `mode`, `owner`, and + `path` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Create the RSA private key file. (default) +properties_list: +- property: force + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Force creation of the key even if the same key already exists on the + node. +- property: group + ruby_type: String, Integer + required: false + description_list: + - markdown: The group ownership applied to all files created by the resource. +- property: key_cipher + ruby_type: String + required: false + default_value: des3 + description_list: + - markdown: The designed cipher to use when generating your key. Run `openssl list-cipher-algorithms` + to see available options. +- property: key_length + ruby_type: Integer + required: false + default_value: '2048' + allowed_values: 1024, 2048, 4096, 8192 + description_list: + - markdown: The desired bit length of the generated key. +- property: key_pass + ruby_type: String + required: false + description_list: + - markdown: The desired passphrase for the key. +- property: mode + ruby_type: Integer, String + required: false + default_value: '0600' + description_list: + - markdown: The permission mode applied to all files created by the resource. +- property: owner + ruby_type: String, Integer + required: false + description_list: + - markdown: The owner applied to all files created by the resource. +- property: path + ruby_type: String + required: false + default_value: The resource block's name + 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 + + ```ruby + openssl_rsa_private_key '/etc/ssl_files/rsakey_des3.pem' do + key_length 2048 + action :create + end + ``` + + Generate new 1024bit key with the aes-128-cbc cipher + + ```ruby + openssl_rsa_private_key '/etc/ssl_files/rsakey_aes128cbc.pem' do + key_length 1024 + key_cipher 'aes-128-cbc' + action :create + end + ``` diff --git a/data/infra/resources/openssl_rsa_public_key.yaml b/data/infra/resources/openssl_rsa_public_key.yaml new file mode 100644 index 0000000..08c9065 --- /dev/null +++ b/data/infra/resources/openssl_rsa_public_key.yaml @@ -0,0 +1,126 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: openssl_rsa_public_key +resource_description_list: +- markdown: Use the **openssl_rsa_public_key** resource to generate RSA public key + files for a given RSA private key. +resource_new_in: '14.0' +syntax_full_code_block: |- + openssl_rsa_public_key 'name' do + group String, Integer + mode Integer, String # default value: "0640" + owner String, Integer + path String # default value: 'name' unless specified + private_key_content String + private_key_pass String + private_key_path String + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`openssl_rsa_public_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." +- "`group`, `mode`, `owner`, `path`, `private_key_content`, `private_key_pass`, and + `private_key_path` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Create the RSA public key file. (default) +properties_list: +- property: group + ruby_type: String, Integer + required: false + description_list: + - markdown: The group ownership applied to all files created by the resource. +- property: mode + ruby_type: Integer, String + required: false + default_value: '0640' + description_list: + - markdown: The permission mode applied to all files created by the resource. +- property: owner + ruby_type: String, Integer + required: false + description_list: + - markdown: The owner applied to all files created by the resource. +- property: path + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property for specifying the path to the public key if it + differs from the resource block's name. +- property: private_key_content + ruby_type: String + required: false + description_list: + - markdown: The content of the private key, including new lines. This property is + used in place of private_key_path in instances where you want to avoid having + to first write the private key to disk. +- property: private_key_pass + ruby_type: String + required: false + description_list: + - markdown: The passphrase of the provided private key. +- property: private_key_path + ruby_type: String + 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 + + ```ruby + openssl_rsa_public_key '/etc/ssl_files/rsakey_des3.pub' do + private_key_path '/etc/ssl_files/rsakey_des3.pem' + private_key_pass 'something' + action :create + end + ``` + + Generate new public key by passing in a private key + + ```ruby + openssl_rsa_public_key '/etc/ssl_files/rsakey_2.pub' do + private_key_pass 'something' + private_key_content "-----BEGIN RSA PRIVATE KEY----- + Proc-Type: 4,ENCRYPTED + DEK-Info: DES-EDE3-CBC,5EE0AE9A5FE3342E + + yb930kj5/4/nd738dPx6XdbDrMCvqkldaz0rHNw8xsWvwARrl/QSPwROG3WY7ROl + EUttVlLaeVaqRPfQbmTUfzGI8kTMmDWKjw52gJUx2YJTYRgMHAB0dzYIRjeZAaeS + ypXnEfouVav+jKTmmehr1WuVKbzRhQDBSalzeUwsPi2+fb3Bfuo1dRW6xt8yFuc4 + Akv1hCglymPzPHE2L0nSGjcgA2DZu+/S8/wZ4E63442NHPzO4VlLvpNvJrYpEWq9 + B5mJzcdXPeOTjqd13olNTlOZMaKxu9QShu50GreCTVsl8VRkK8NtwbWuPGBZlIFa + jzlS/RaLuzNzfajaKMkcIYco9t7gN2DwnsACHKqEYT8248Ii3NQ+9/M5YcmpywQj + WGr0UFCSAdCky1lRjwT+zGQKohr+dVR1GaLem+rSZH94df4YBxDYw4rjsKoEhvXB + v2Vlx+G7Vl2NFiZzxUKh3MvQLr/NDElpG1pYWDiE0DIG13UqEG++cS870mcEyfFh + SF2SXYHLWyAhDK0viRDChJyFMduC4E7a2P9DJhL3ZvM0KZ1SLMwROc1XuZ704GwO + YUqtCX5OOIsTti1Z74jQm9uWFikhgWByhVtu6sYL1YTqtiPJDMFhA560zp/k/qLO + FKiM4eUWV8AI8AVwT6A4o45N2Ru8S48NQyvh/ADFNrgJbVSeDoYE23+DYKpzbaW9 + 00BD/EmUQqaQMc670vmI+CIdcdE7L1zqD6MZN7wtPaRIjx4FJBGsFoeDShr+LoTD + rwbadwrbc2Rf4DWlvFwLJ4pvNvdtY3wtBu79UCOol0+t8DVVSPVASsh+tp8XncDE + KRljj88WwBjX7/YlRWvQpe5y2UrsHI0pNy8TA1Xkf6GPr6aS2TvQD5gOrAVReSse + /kktCzZQotjmY1odvo90Zi6A9NCzkI4ZLgAuhiKDPhxZg61IeLppnfFw0v3H4331 + V9SMYgr1Ftov0++x7q9hFPIHwZp6NHHOhdHNI80XkHqtY/hEvsh7MhFMYCgSY1pa + K/gMcZ/5Wdg9LwOK6nYRmtPtg6fuqj+jB3Rue5/p9dt4kfom4etCSeJPdvP1Mx2I + eNmyQ/7JN9N87FsfZsIj5OK9OB0fPdj0N0m1mlHM/mFt5UM5x39u13QkCt7skEF+ + yOptXcL629/xwm8eg4EXnKFk330WcYSw+sYmAQ9ZTsBxpCMkz0K4PBTPWWXx63XS + c4J0r88kbCkMCNv41of8ceeGzFrC74dG7i3IUqZzMzRP8cFeps8auhweUHD2hULs + XwwtII0YQ6/Fw4hgGQ5//0ASdvAicvH0l1jOQScHzXC2QWNg3GttueB/kmhMeGGm + sHOJ1rXQ4oEckFvBHOvzjP3kuRHSWFYDx35RjWLAwLCG9odQUApHjLBgFNg9yOR0 + jW9a2SGxRvBAfdjTa9ZBBrbjlaF57hq7mXws90P88RpAL+xxCAZUElqeW2Rb2rQ6 + Cbz4/AtPekV1CYVodGkPutOsew2zjNqlNH+M8XzfonA60UAH20TEqAgLKwgfgr+a + c+rXp1AupBxat4EHYJiwXBB9XcVwyp5Z+/dXsYmLXzoMOnp8OFyQ9H8R7y9Y0PEu + -----END RSA PRIVATE KEY----- + " + action :create + end + ``` diff --git a/data/infra/resources/openssl_x509_certificate.yaml b/data/infra/resources/openssl_x509_certificate.yaml new file mode 100644 index 0000000..29feb5d --- /dev/null +++ b/data/infra/resources/openssl_x509_certificate.yaml @@ -0,0 +1,246 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: openssl_x509_certificate +resource_description_list: +- markdown: Use the **openssl_x509_certificate** resource to generate signed or self-signed, + PEM-formatted x509 certificates. If no existing key is specified, the resource + will automatically generate a passwordless key with the certificate. If a CA private + key and certificate are provided, the certificate will be signed with them. +- note: + markdown: This resource was renamed from openssl_x509 to openssl_x509_certificate. + The legacy name will continue to function, but cookbook code should be updated + for the new resource name. +resource_new_in: '14.4' +syntax_full_code_block: |- + openssl_x509_certificate 'name' do + ca_cert_file String + ca_key_file String + ca_key_pass String + city String + common_name String + country String + csr_file String + email String + expire Integer # default value: 365 + extensions Hash # default value: {} + group String, Integer + key_curve String # default value: "prime256v1" + key_file String + key_length Integer # default value: 2048 + key_pass String + key_type String # default value: "rsa" + mode Integer, String + org String + org_unit String + owner String, Integer + path String # default value: 'name' unless specified + renew_before_expiry Integer + state String + subject_alt_name Array # default value: [] + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`openssl_x509_certificate` 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." +- "`ca_cert_file`, `ca_key_file`, `ca_key_pass`, `city`, `common_name`, `country`, + `csr_file`, `email`, `expire`, `extensions`, `group`, `key_curve`, `key_file`, `key_length`, + `key_pass`, `key_type`, `mode`, `org`, `org_unit`, `owner`, `path`, `renew_before_expiry`, + `state`, and `subject_alt_name` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Generate a certificate file. (default) +properties_list: +- property: ca_cert_file + ruby_type: String + required: false + description_list: + - markdown: The path to the CA X509 Certificate on the filesystem. If the `ca_cert_file` + property is specified, the `ca_key_file` property must also be specified, the + certificate will be signed with them. +- property: ca_key_file + ruby_type: String + required: false + description_list: + - markdown: The path to the CA private key on the filesystem. If the `ca_key_file` + property is specified, the `ca_cert_file` property must also be specified, the + certificate will be signed with them. +- property: ca_key_pass + ruby_type: String + required: false + description_list: + - markdown: The passphrase for CA private key's passphrase. +- property: city + ruby_type: String + required: false + description_list: + - markdown: Value for the `L` certificate field. +- property: common_name + ruby_type: String + required: false + description_list: + - markdown: Value for the `CN` certificate field. +- property: country + ruby_type: String + required: false + description_list: + - markdown: Value for the `C` certificate field. +- property: csr_file + ruby_type: String + required: false + description_list: + - markdown: The path to a X509 Certificate Request (CSR) on the filesystem. If the + `csr_file` property is specified, the resource will attempt to source a CSR + from this location. If no CSR file is found, the resource will generate a Self-Signed + Certificate and the certificate fields must be specified (common_name at last). +- property: email + ruby_type: String + required: false + description_list: + - markdown: Value for the `email` certificate field. +- property: expire + ruby_type: Integer + required: false + default_value: '365' + description_list: + - markdown: Value representing the number of days from now through which the issued + certificate cert will remain valid. The certificate will expire after this period. +- property: extensions + ruby_type: Hash + required: false + default_value: "{}" + description_list: + - markdown: Hash of X509 Extensions entries, in format `{ 'keyUsage' => { 'values' + => %w( keyEncipherment digitalSignature), 'critical' => true } }`. +- property: group + ruby_type: String, Integer + required: false + description_list: + - markdown: The group ownership applied to all files created by the resource. +- property: key_curve + ruby_type: String + required: false + default_value: prime256v1 + allowed_values: '"prime256v1", "secp384r1", "secp521r1"' + description_list: + - markdown: The desired curve of the generated key (if key_type is equal to 'ec'). + Run `openssl ecparam -list_curves` to see available options. +- property: key_file + ruby_type: String + required: false + description_list: + - markdown: The path to a certificate key file on the filesystem. If the key_file + property is specified, the resource will attempt to source a key from this location. + If no key file is found, the resource will generate a new key file at this location. + If the key_file property is not specified, the resource will generate a key + file in the same directory as the generated certificate, with the same name + as the generated certificate. +- property: key_length + ruby_type: Integer + required: false + default_value: '2048' + allowed_values: 1024, 2048, 4096, 8192 + description_list: + - markdown: The desired bit length of the generated key (if key_type is equal to + 'rsa'). +- property: key_pass + ruby_type: String + required: false + description_list: + - markdown: The passphrase for an existing key's passphrase. +- property: key_type + ruby_type: String + required: false + default_value: rsa + allowed_values: '"ec", "rsa"' + description_list: + - markdown: The desired type of the generated key. +- property: mode + ruby_type: Integer, String + required: false + description_list: + - markdown: The permission mode applied to all files created by the resource. +- property: org + ruby_type: String + required: false + description_list: + - markdown: Value for the `O` certificate field. +- property: org_unit + ruby_type: String + required: false + description_list: + - markdown: Value for the `OU` certificate field. +- property: owner + ruby_type: String, Integer + required: false + description_list: + - markdown: The owner applied to all files created by the resource. +- property: path + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property for specifying the path to write the file to if + it differs from the resource block's name. +- property: renew_before_expiry + ruby_type: Integer + required: false + new_in: '15.7' + description_list: + - markdown: The number of days before the expiry. The certificate will be automatically + renewed when the value is reached. +- property: state + ruby_type: String + required: false + description_list: + - markdown: Value for the `ST` certificate field. +- property: subject_alt_name + ruby_type: Array + required: false + default_value: "[]" + 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 + + ```ruby + openssl_x509_certificate '/etc/httpd/ssl/mycert.pem' do + common_name 'www.f00bar.com' + org 'Foo Bar' + org_unit 'Lab' + country 'US' + end + ``` + + Create a certificate using additional options + + ```ruby + openssl_x509_certificate '/etc/ssl_files/my_signed_cert.crt' do + common_name 'www.f00bar.com' + ca_key_file '/etc/ssl_files/my_ca.key' + ca_cert_file '/etc/ssl_files/my_ca.crt' + expire 365 + extensions( + 'keyUsage' => { + 'values' => %w( + keyEncipherment + digitalSignature), + 'critical' => true, + }, + 'extendedKeyUsage' => { + 'values' => %w(serverAuth), + 'critical' => false, + } + ) + subject_alt_name ['IP:127.0.0.1', 'DNS:localhost.localdomain'] + end + ``` diff --git a/data/infra/resources/openssl_x509_crl.yaml b/data/infra/resources/openssl_x509_crl.yaml new file mode 100644 index 0000000..1c0ed4f --- /dev/null +++ b/data/infra/resources/openssl_x509_crl.yaml @@ -0,0 +1,126 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: openssl_x509_crl +resource_description_list: +- markdown: Use the **openssl_x509_crl** resource to generate PEM-formatted x509 certificate + revocation list (CRL) files. +resource_new_in: '14.4' +syntax_full_code_block: |- + openssl_x509_crl 'name' do + ca_cert_file String + ca_key_file String + ca_key_pass String + expire Integer # default value: 8 + group String, Integer + mode Integer, String + owner String, Integer + path String # default value: 'name' unless specified + renewal_threshold Integer # default value: 1 + revocation_reason Integer # default value: 0 + serial_to_revoke Integer, String + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`openssl_x509_crl` 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." +- "`ca_cert_file`, `ca_key_file`, `ca_key_pass`, `expire`, `group`, `mode`, `owner`, + `path`, `renewal_threshold`, `revocation_reason`, and `serial_to_revoke` are the + properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Create the certificate revocation list (CRL) file. (default) +properties_list: +- property: ca_cert_file + ruby_type: String + required: true + description_list: + - markdown: The path to the CA X509 Certificate on the filesystem. If the `ca_cert_file` + property is specified, the `ca_key_file` property must also be specified, the + CRL will be signed with them. +- property: ca_key_file + ruby_type: String + required: true + description_list: + - markdown: The path to the CA private key on the filesystem. If the `ca_key_file` + property is specified, the `ca_cert_file` property must also be specified, the + CRL will be signed with them. +- property: ca_key_pass + ruby_type: String + required: false + description_list: + - markdown: The passphrase for CA private key's passphrase. +- property: expire + ruby_type: Integer + required: false + default_value: '8' + description_list: + - markdown: Value representing the number of days from now through which the issued + CRL will remain valid. The CRL will expire after this period. +- property: group + ruby_type: String, Integer + required: false + description_list: + - markdown: The group permission for the CRL file. +- property: mode + ruby_type: Integer, String + required: false + description_list: + - markdown: The permission mode of the CRL file. +- property: owner + ruby_type: String, Integer + required: false + description_list: + - markdown: The owner permission for the CRL file. +- property: path + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property for specifying the path to write the file to if + it differs from the resource block's name. +- property: renewal_threshold + ruby_type: Integer + required: false + default_value: '1' + description_list: + - markdown: Number of days before the expiration. It this threshold is reached, + the CRL will be renewed. +- property: revocation_reason + ruby_type: Integer + required: false + default_value: '0' + description_list: + - markdown: Reason for the revocation. +- property: serial_to_revoke + ruby_type: Integer, String + required: false + description_list: + - markdown: Serial of the X509 Certificate to revoke. +target_mode: +examples: | + **Create a certificate revocation file** + + ```ruby + openssl_x509_crl '/etc/ssl_test/my_ca.crl' do + ca_cert_file '/etc/ssl_test/my_ca.crt' + ca_key_file '/etc/ssl_test/my_ca.key' + end + ``` + + **Create a certificate revocation file for a particular serial** + + ```ruby + openssl_x509_crl '/etc/ssl_test/my_ca.crl' do + ca_cert_file '/etc/ssl_test/my_ca.crt' + ca_key_file '/etc/ssl_test/my_ca.key' + serial_to_revoke C7BCB6602A2E4251EF4E2827A228CB52BC0CEA2F + end + ``` diff --git a/data/infra/resources/openssl_x509_request.yaml b/data/infra/resources/openssl_x509_request.yaml new file mode 100644 index 0000000..7a4fe27 --- /dev/null +++ b/data/infra/resources/openssl_x509_request.yaml @@ -0,0 +1,177 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: openssl_x509_request +resource_description_list: +- markdown: Use the **openssl_x509_request** resource to generate PEM-formatted x509 + certificates requests. If no existing key is specified, the resource will automatically + generate a passwordless key with the certificate. +resource_new_in: '14.4' +syntax_full_code_block: |- + openssl_x509_request 'name' do + city String + common_name String + country String + email String + group String, Integer + key_curve String # default value: "prime256v1" + key_file String + key_length Integer # default value: 2048 + key_pass String + key_type String # default value: "ec" + mode Integer, String + org String + org_unit String + owner String, Integer + path String # default value: 'name' unless specified + state String + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`openssl_x509_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." +- "`city`, `common_name`, `country`, `email`, `group`, `key_curve`, `key_file`, `key_length`, + `key_pass`, `key_type`, `mode`, `org`, `org_unit`, `owner`, `path`, and `state` + are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Generate a certificate request file. (default) +properties_list: +- property: city + ruby_type: String + required: false + description_list: + - markdown: Value for the `L` certificate field. +- property: common_name + ruby_type: String + required: true + description_list: + - markdown: Value for the `CN` certificate field. +- property: country + ruby_type: String + required: false + description_list: + - markdown: Value for the `C` certificate field. +- property: email + ruby_type: String + required: false + description_list: + - markdown: Value for the `email` certificate field. +- property: group + ruby_type: String, Integer + required: false + description_list: + - markdown: The group ownership applied to all files created by the resource. +- property: key_curve + ruby_type: String + required: false + default_value: prime256v1 + allowed_values: '"prime256v1", "secp384r1", "secp521r1"' + description_list: + - markdown: The desired curve of the generated key (if key_type is equal to `ec`). + Run `openssl ecparam -list_curves` to see available options. +- property: key_file + ruby_type: String + required: false + description_list: + - markdown: The path to a certificate key file on the filesystem. If the `key_file` + property is specified, the resource will attempt to source a key from this location. + If no key file is found, the resource will generate a new key file at this location. + If the `key_file` property is not specified, the resource will generate a key + file in the same directory as the generated certificate, with the same name + as the generated certificate. +- property: key_length + ruby_type: Integer + required: false + default_value: '2048' + allowed_values: 1024, 2048, 4096, 8192 + description_list: + - markdown: The desired bit length of the generated key (if key_type is equal to + `rsa`). +- property: key_pass + ruby_type: String + required: false + description_list: + - markdown: The passphrase for an existing key's passphrase. +- property: key_type + ruby_type: String + required: false + default_value: ec + allowed_values: '"ec", "rsa"' + description_list: + - markdown: The desired type of the generated key. +- property: mode + ruby_type: Integer, String + required: false + description_list: + - markdown: The permission mode applied to all files created by the resource. +- property: org + ruby_type: String + required: false + description_list: + - markdown: Value for the `O` certificate field. +- property: org_unit + ruby_type: String + required: false + description_list: + - markdown: Value for the `OU` certificate field. +- property: owner + ruby_type: String, Integer + required: false + description_list: + - markdown: The owner applied to all files created by the resource. +- property: path + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property for specifying the path to write the file to if + it differs from the resource block's name. +- property: state + ruby_type: String + required: false + description_list: + - markdown: Value for the `ST` certificate field. +target_mode: +examples: | + **Generate new EC key and CSR file** + + ```ruby + openssl_x509_request '/etc/ssl_files/my_ec_request.csr' do + common_name 'myecrequest.example.com' + org 'Test Kitchen Example' + org_unit 'Kitchens' + country 'UK' + end + ``` + + **Generate a new CSR file from an existing EC key** + + ```ruby + openssl_x509_request '/etc/ssl_files/my_ec_request2.csr' do + common_name 'myecrequest2.example.com' + org 'Test Kitchen Example' + org_unit 'Kitchens' + country 'UK' + key_file '/etc/ssl_files/my_ec_request.key' + end + ``` + + **Generate new RSA key and CSR file** + + ```ruby + openssl_x509_request '/etc/ssl_files/my_rsa_request.csr' do + common_name 'myrsarequest.example.com' + org 'Test Kitchen Example' + org_unit 'Kitchens' + country 'UK' + key_type 'rsa' + end + ``` diff --git a/data/infra/resources/package.yaml b/data/infra/resources/package.yaml new file mode 100644 index 0000000..16b1ae7 --- /dev/null +++ b/data/infra/resources/package.yaml @@ -0,0 +1,470 @@ +--- +resource_reference: true +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. + + 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: + - [apt_package](/resources/bundled/apt_package/) + - [bff_package](/resources/bundled/bff_package/) + - [cab_package](/resources/bundled/cab_package/) + - [chef_gem](/resources/bundled/chef_gem/) + - [chocolatey_package](/resources/bundled/chocolatey_package/) + - [dmg_package](/resources/bundled/dmg_package/) + - [dnf_package](/resources/bundled/dnf_package/) + - [dpkg_package](/resources/bundled/dpkg_package/) + - [freebsd_package](/resources/bundled/freebsd_package/) + - [gem_package](/resources/bundled/gem_package/) + - [homebrew_package](/resources/bundled/homebrew_package/) + - [ips_package](/resources/bundled/ips_package/) + - [macports_package](/resources/bundled/macports_package/) + - [msu_package](/resources/bundled/msu_package/) + - [openbsd_package](/resources/bundled/openbsd_package/) + - [pacman_package](/resources/bundled/pacman_package/) + - [paludis_package](/resources/bundled/paludis_package/) + - [portage_package](/resources/bundled/portage_package/) + - [rpm_package](/resources/bundled/rpm_package/) + - [smartos_package](/resources/bundled/smartos_package/) + - [snap_package](/resources/bundled/snap_package/) + - [solaris_package](/resources/bundled/solaris_package/) + - [windows_package](/resources/bundled/windows_package/) + - [yum_package](/resources/bundled/yum_package/) + - [zypper_package](/resources/bundled/zypper_package/) +syntax_description: | + A **package** resource block manages a package on a node, typically by + installing it. The simplest use of the **package** resource is: + + ```ruby + package 'httpd' + ``` + + which will install Apache using all of the default options and the + default action (`:install`). + + For a package that has different package names, depending on the + platform, use a `case` statement within the **package**: + + ```ruby + package 'Install Apache' do + case node[:platform] + when 'redhat', + 'centos' + package_name 'httpd' + when 'ubuntu', 'debian' + package_name + 'apache2' + end + end + ``` +syntax_properties_list: +- '`''redhat'', ''centos''` will install Apache using the `httpd` package + and `''ubuntu'', ''debian''` will install it using the `apache2` package' +syntax_full_code_block: |- + package 'name' do + environment Hash + options String, Array + package_name String, Array + source String + timeout String, Integer + version String, Array + action Symbol # defaults to :install if not specified + end +syntax_full_properties_list: +- "`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: 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: Reconfigure a package. This action requires a response file. + :lock: + markdown: + :unlock: + markdown: +properties_list: +- property: allow_downgrade + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: '**yum_package** resource only. Downgrade a package to satisfy + requested version requirements.' +- property: arch + ruby_type: String, Array + required: false + description_list: + - markdown: '**yum_package** resource only. The architecture of the package to + + be installed or upgraded. This value can also be passed as part of + + the package name.' +- property: default_release + ruby_type: String + required: false + description_list: + - markdown: '**apt_package** resource only. The default release. For example: + + `stable`.' +- property: environment + ruby_type: Hash + required: false + 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: options + ruby_type: String, Array + required: false + description_list: + - 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: 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: The optional path to a package on the local file system. +- property: timeout + ruby_type: String, Integer + required: false + description_list: + - markdown: The amount of time (in seconds) to wait before timing out. +- property: version + ruby_type: String, Array + required: false + description_list: + - markdown: The version of a package to be installed or upgraded. +multi_package_resource: true +target_mode: + support: full +examples: | + **Install a gems file for use in recipes** + + ```ruby + chef_gem 'right_aws' do + action :install + end + + require 'right_aws' + ``` + + + **Install a gems file from the local file system** + + ```ruby + gem_package 'right_aws' do + source '/tmp/right_aws-1.11.0.gem' + action :install + end + ``` + + **Install a package** + + ```ruby + package 'tar' do + action :install + end + ``` + + **Install a package version** + + ```ruby + package 'tar' do + + version '1.16.1-1' + action :install + end + ``` + + **Install a package with options** + + ```ruby + package 'debian-archive-keyring' do + action :install + options '--force-yes' + end + ``` + + **Install a package with a response_file** + + Use of a `response_file` is only supported on Debian and Ubuntu at this + time. Custom resources must be written to support the use of a + `response_file`, which contains debconf answers to questions normally + asked by the package manager on installation. Put the file in + `/files/default` of the cookbook where the package is specified and Chef + Infra Client will use the **cookbook_file** resource to retrieve it. + + To install a package with a `response_file`: + + ```ruby + package 'sun-java6-jdk' do + response_file 'java.seed' + end + ``` + + **Install a specified architecture using a named provider** + + ```ruby + yum_package 'glibc-devel' do + arch 'i386' + end + ``` + + **Purge a package** + + ```ruby + package 'tar' do + action :purge + end + ``` + + **Remove a package** + + ```ruby + package 'tar' do + action :remove + end + ``` + + **Upgrade a package** + + ```ruby + package 'tar' do + action :upgrade + end + ``` + + **Use the `ignore_failure` common attribute** + + ```ruby + gem_package 'syntax' do + action :install + ignore_failure true + end + ``` + + **Avoid unnecessary string interpolation** + + Do this: + + ```ruby + package 'mysql-server' do + version node['mysql']['version'] + action :install + end + ``` + + and not this: + + ```ruby + package 'mysql-server' do + version "#{node['mysql']['version']}" + action :install + end + + ``` + + **Install a package in a platform** + + The following example shows how + to use the **package** resource to + install an application named `app` and ensure + that the correct packages + are installed for the correct platform: + + ```ruby + package 'app_name' do + action :install + end + + case node[:platform] + + when 'ubuntu','debian' + package 'app_name-doc' do + action :install + end + when 'centos' + package 'app_name-html' do + action :install + end + end + ``` + + **Install sudo, then configure /etc/sudoers/ file** + + The following example shows how to install sudo and then configure the + `/etc/sudoers` file: + + ```ruby + # the following code sample comes from the ``default`` + # recipe in the ``sudo`` cookbook: https://github.com/chef-cookbooks/sudo + + package 'sudo' do + action :install + end + + if node['authorization']['sudo']['include_sudoers_d'] + directory '/etc/sudoers.d' do + mode '0755' + owner 'root' + group 'root' + action :create + end + + cookbook_file '/etc/sudoers.d/README' do + source 'README' + mode '0440' + owner 'root' + group 'root' + action :create + end + end + + template '/etc/sudoers' do + source 'sudoers.erb' + mode '0440' + owner 'root' + group platform?('freebsd') ? 'wheel' : 'root' + variables( + :sudoers_groups => node['authorization']['sudo']['groups'], + :sudoers_users => node['authorization']['sudo']['users'], + :passwordless => node['authorization']['sudo']['passwordless'] + ) + end + ``` + + where: + + - the **package** resource is used to install sudo + - the `if` statement is used to ensure availability of the `/etc/sudoers.d` directory + - the **template** resource tells Chef Infra Client where to find the `sudoers` template + - the `variables` property is a hash that passes values to template + files (that are located in the `templates/` directory for the cookbook + + **Use a case statement to specify the platform** + + The following example shows how to use a case statement to tell Chef + Infra Client which platforms and packages to install using cURL. + + ```ruby + package 'curl' + case node[:platform] + when 'redhat', 'centos' + package 'package_1' + package 'package_2' + package 'package_3' + when 'ubuntu', 'debian' + package 'package_a' + package 'package_b' + package 'package_c' + end + end + ``` + + where `node[:platform]` for each node is identified by Ohai during every Chef + Infra Client run. For example: + + ```ruby + package 'curl' + case node[:platform] + when 'redhat', 'centos' + package 'zlib-devel' + package 'openssl-devel' + package 'libc6-dev' + when 'ubuntu', 'debian' + package 'openssl' + package 'pkg-config' + package 'subversion' + end + end + ``` + + **Use symbols to reference attributes** + + Symbols may be used to reference attributes: + + ```ruby + package 'mysql-server' do + version node[:mysql][:version] + action :install + end + ``` + + instead of strings: + + ```ruby + package 'mysql-server' do + version node['mysql']['version'] + action :install + end + ``` + + **Use a whitespace array to simplify a recipe** + + The following examples show different ways of doing the same thing. The + first shows a series of packages that will be upgraded: + + ```ruby + package 'package-a' do + action :upgrade + end + + package 'package-b' do + action :upgrade + end + + package 'package-c' do + action :upgrade + end + + package 'package-d' do + action :upgrade + end + ``` + + and the next uses a single **package** resource and a whitespace array (`%w`): + + ```ruby + package %w{package-a package-b package-c package-d} do + action :upgrade + end + ``` + + **Specify the Homebrew user with a UUID** + + ```ruby + homebrew_package 'emacs' do + homebrew_user 1001 + end + ``` + + **Specify the Homebrew user with a string** + + ```ruby + homebrew_package 'vim' do + homebrew_user 'user1' + end + ``` diff --git a/data/infra/resources/pacman_package.yaml b/data/infra/resources/pacman_package.yaml new file mode 100644 index 0000000..538128b --- /dev/null +++ b/data/infra/resources/pacman_package.yaml @@ -0,0 +1,104 @@ +--- +resource_reference: true +multi_package_resource: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: pacman_package +resource_description_list: +- markdown: Use the **pacman_package** resource to manage packages (using pacman) + on the Arch Linux platform. +- notes_resource_based_on_package: true +syntax_description: | + A **pacman_package** resource block manages a package on a node, + typically by installing it. The simplest use of the **pacman_package** + resource is: + + ```ruby + pacman_package 'package_name' + ``` + + which will install the named package using all of the default options + and the default action (`:install`). +syntax_full_code_block: |- + pacman_package 'name' do + environment Hash + options String, Array + package_name String, Array + source String + timeout String, Integer + 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." +- "`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 + description_list: + - 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: 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: The optional path to a package on the local file system. +- property: timeout + ruby_type: String, Integer + required: false + description_list: + - markdown: The amount of time (in seconds) to wait before timing out. +- property: version + ruby_type: String, Array + required: false + description_list: + - markdown: The version of a package to be installed or upgraded. +target_mode: + support: full +examples: | + **Install a package** + + ```ruby + pacman_package 'name of package' do + action :install + end + ``` + diff --git a/data/infra/resources/paludis_package.yaml b/data/infra/resources/paludis_package.yaml new file mode 100644 index 0000000..45135e4 --- /dev/null +++ b/data/infra/resources/paludis_package.yaml @@ -0,0 +1,98 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: paludis_package +resource_description_list: +- markdown: Use the **paludis_package** resource to manage packages for the Paludis + platform. +syntax_description: 'A **paludis_package** resource block manages a package on a node, + typically by installing it. The simplest use of the **paludis_package** + resource is: + + ```ruby + paludis_package ''package_name'' + ``` + + which will install the named package using all of the default options + and the default action (`:install`).' +resource_new_in: '12.1' +syntax_full_code_block: |- + paludis_package 'name' do + environment Hash + options String, Array + package_name String + source String + timeout String, Integer # default value: 3600 + version String + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`paludis_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: 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 + description_list: + - markdown: One (or more) additional command options that are passed to the command. +- property: package_name + ruby_type: String + required: false + description_list: + - 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: The optional path to a package on the local file system. +- property: timeout + ruby_type: String, Integer + required: false + default_value: '3600' + description_list: + - markdown: The amount of time (in seconds) to wait before timing out. +- property: version + ruby_type: String + 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 new file mode 100644 index 0000000..731bf13 --- /dev/null +++ b/data/infra/resources/perl.yaml @@ -0,0 +1,203 @@ +--- +resource_reference: true +resources_common_guards: true +resource: perl +resource_description_list: +- markdown: Use the **perl** resource to execute scripts using the Perl interpreter. + This resource may also use any of the actions and properties that are available + to the **execute** resource. Commands that are executed with this resource are + (by their nature) not idempotent, as they are typically unique to the environment + in which they are run. Use `not_if` and `only_if` to guard this resource for idempotence. +syntax_description: | + A **perl** resource block executes scripts Perl: + + ```ruby + perl 'hello world' do + code <<-EOH + print "Hello world! From Chef and Perl."; + EOH + end + ``` + where: + + `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 + 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: +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." +- "`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 + description_list: + - markdown: Prevent a command from creating a file when that file already exists. +- property: cwd + ruby_type: String + 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 + description_list: + - 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: 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 + 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: 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: user + ruby_type: String, Integer + required: false + description_list: + - 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 new file mode 100644 index 0000000..0dd17d6 --- /dev/null +++ b/data/infra/resources/plist.yaml @@ -0,0 +1,85 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: plist +resource_description_list: +- markdown: Use the **plist** resource to set config values in plist files on macOS + systems. +resource_new_in: '16.0' +syntax_full_code_block: |- + plist 'name' do + encoding String # default value: "binary" + entry String + group String # default value: "wheel" + mode String, Integer + owner String # default value: "root" + path String # default value: 'name' unless specified + value true, false, String, Integer, Float, Hash + action Symbol # defaults to :set if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`plist` 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." +- "`encoding`, `entry`, `group`, `mode`, `owner`, `path`, and `value` are the properties + available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :set: + markdown: Set a value in a plist file. (default) +properties_list: +- property: encoding + ruby_type: String + required: false + default_value: binary + description_list: + - markdown: +- property: entry + ruby_type: String + required: false + description_list: + - markdown: +- property: group + ruby_type: String + required: false + default_value: wheel + description_list: + - markdown: The group of the plist file. +- property: mode + ruby_type: String, Integer + required: false + description_list: + - markdown: 'The file mode of the plist file. Ex: ''644''' +- property: owner + ruby_type: String + required: false + default_value: root + description_list: + - markdown: The owner of the plist file. +- property: path + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: The path on disk to the plist file. +- property: value + ruby_type: true, false, String, Integer, Float, Hash + required: false + description_list: + - markdown: +target_mode: +examples: | + **Show hidden files in finder**: + + ```ruby + plist 'show hidden files' do + path '/Users/vagrant/Library/Preferences/com.apple.finder.plist' + entry 'AppleShowAllFiles' + value true + end + ``` diff --git a/data/infra/resources/portage_package.yaml b/data/infra/resources/portage_package.yaml new file mode 100644 index 0000000..1da7733 --- /dev/null +++ b/data/infra/resources/portage_package.yaml @@ -0,0 +1,88 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: portage_package +resource_description_list: +- markdown: Use the **portage_package** resource to manage packages for the Gentoo + platform. +- notes_resource_based_on_package: true +syntax_full_code_block: |- + portage_package 'name' do + environment Hash + options String, Array + package_name String + source String + timeout String, Integer # default value: 3600 + version String + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`portage_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: 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 + description_list: + - markdown: One (or more) additional command options that are passed to the command. +- property: package_name + ruby_type: String + required: false + description_list: + - 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: The optional path to a package on the local file system. +- property: timeout + ruby_type: String, Integer + required: false + default_value: '3600' + description_list: + - markdown: The amount of time (in seconds) to wait before timing out. +- property: version + ruby_type: String + 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 new file mode 100644 index 0000000..75e253e --- /dev/null +++ b/data/infra/resources/powershell_package.yaml @@ -0,0 +1,173 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: powershell_package +resource_description_list: +- markdown: Use the **powershell_package** resource to install and manage packages + via the PowerShell Package Manager for the Microsoft Windows platform. The powershell_package + resource requires administrative access, and a source must be configured in the + PowerShell Package Manager via the powershell_package_source resource. +resource_new_in: '12.16' +syntax_description: | + A **powershell_package** resource block manages a package on a node, typically by installing it. The simplest use of the **powershell_package** resource is: + + ```ruby + powershell_package 'package_name' + ``` + + which will install the named package using all of the default options and the default action (`:install`). +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 + source String + timeout String, Integer + version String, Array + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`powershell_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." +- "`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 + required: false + default_value: 'false' + new_in: '18.5' + 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 + description_list: + - 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.' +- property: skip_publisher_check + ruby_type: true, false + required: false + default_value: 'false' + new_in: '14.3' + description_list: + - markdown: Skip validating module author. +- property: source + ruby_type: String + required: false + new_in: '14.0' + description_list: + - markdown: Specify the source of the package. +- property: timeout + ruby_type: String, Integer + required: false + description_list: + - markdown: The amount of time (in seconds) to wait before timing out. +- property: version + ruby_type: String, Array + 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**: + + ```ruby + powershell_package 'xCertificate' do + action :install + version '1.1.0.0' + end + ``` + + + **Install multiple packages**: + + ```ruby + powershell_package 'Install Multiple Packages' do + action :install + package_name %w(xCertificate xNetworking) + end + ``` + + **Install a package from a custom source**: + + ```ruby + powershell_package 'xCertificate' do + action :install + source 'MyGallery' + end + ``` + + + **Install multiple packages, and specify package versions**: + + ```ruby + powershell_package 'Install Multiple Packages' do + action :install + package_name %w(xCertificate xNetworking) + version ['2.0.0.0', '2.12.0.0'] + end + ``` + + **Install multiple packages, specifying the package version for one + package but not the other**: + + + ```ruby + powershell_package 'Install Multiple Packages' do + action :install + package_name %w(xCertificate xNetworking) + version [nil, '2.12.0.0'] + end + ``` + + In this example, the `nil` tells `powershell_package` to install the + most up to date version of `xCertificate` that is available, while + pinning `xNetworking` to version 2.12.0.0. + + **Remove a package**: + + ```ruby + powershell_package 'xCertificate' do + action :remove + end + ``` + diff --git a/data/infra/resources/powershell_package_source.yaml b/data/infra/resources/powershell_package_source.yaml new file mode 100644 index 0000000..1febc10 --- /dev/null +++ b/data/infra/resources/powershell_package_source.yaml @@ -0,0 +1,197 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: powershell_package_source +resource_description_list: +- markdown: Use the **powershell_package_source** resource to register a PowerShell + package source and a Powershell package provider. There are two distinct objects + we care about here. The first is a package source like a PowerShell repository + or a NuGet Source. The second object is a provider that PowerShell uses to get + to that source with, like PowerShellGet, NuGet, Chocolatey, etc. +resource_new_in: '14.3' +syntax_full_code_block: |- + powershell_package_source 'name' do + new_name String + password String + provider_name String # default value: "NuGet" + publish_location String + script_publish_location String + script_source_location String + source_location String + source_name String # default value: 'name' unless specified + trusted true, false # default value: false + 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." +- "`action` identifies which steps Chef Infra Client will take to bring the node into + the desired state." +- "`new_name`, `password`, `provider_name`, `publish_location`, `script_publish_location`, + `script_source_location`, `source_location`, `source_name`, `trusted`, and `user` + are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :register: + markdown: Registers a PowerShell package source. (default) + :set: + markdown: Updates an existing PowerShell repository or package source. + :unregister: + markdown: Unregisters the PowerShell package source. +properties_list: +- property: new_name + ruby_type: String + required: false + new_in: '17.6' + description_list: + - markdown: Used to change the name of a standard package source. +- property: password + ruby_type: String + required: false + new_in: '17.6' + description_list: + - markdown: A password that, as part of a credential object, is used to register + a repository or other package source with. +- property: provider_name + ruby_type: String + required: false + default_value: NuGet + allowed_values: '"NuGet", "PowerShellGet", "Programs", "chocolatey", "msi", "msu", + "psl", "winget"' + description_list: + - markdown: The package management provider for the package source. The default + is `PowerShellGet`. Only change this option in specific use cases. +- property: publish_location + ruby_type: String + required: false + description_list: + - markdown: The URL where modules will be published to. Only valid if the provider + is `PowerShellGet`. +- property: script_publish_location + ruby_type: String + required: false + description_list: + - markdown: The location where scripts will be published to for this source. Only + valid if the provider is `PowerShellGet`. +- property: script_source_location + ruby_type: String + required: false + description_list: + - markdown: The URL where scripts are located for this source. Only valid if the + provider is `PowerShellGet`. +- property: source_location + ruby_type: String + required: false + new_in: '17.6' + description_list: + - markdown: The URL to the location to retrieve modules from. +- property: source_name + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: A label that names your package source. +- property: trusted + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Whether or not to trust packages from this source. Used when creating + a non-PowerShell repository package source. +- property: user + ruby_type: String + required: false + new_in: '17.6' + 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**: + + ```ruby + powershell_package_source 'PowerShellModules' do + source_name "PowerShellModules" + source_location "https://pkgs.dev.azure.com/some-org/some-project/_packaging/some_feed/nuget/v2" + publish_location "https://pkgs.dev.azure.com/some-org/some-project/_packaging/some_feed/nuget/v2" + trusted false + user "someuser@somelocation.io" + password "my_password" + provider_name "PSRepository" + action :register + end + ``` + + **Add a new package source that uses Chocolatey as the package provider**: + + ```ruby + powershell_package_source 'PowerShellModules' do + source_name "PowerShellModules" + source_location "https://pkgs.dev.azure.com/some-org/some-project/_packaging/some_feed/nuget/v2" + publish_location "https://pkgs.dev.azure.com/some-org/some-project/_packaging/some_feed/nuget/v2" + trusted true + provider_name "chocolatey" + action :register + end + ``` + + **Add a new PowerShell script source that is trusted**: + + ```ruby + powershell_package_source 'MyDodgyScript' do + source_name "MyDodgyScript" + script_source_location "https://pkgs.dev.azure.com/some-org/some-project/_packaging/some_feed/nuget/v2" + script_publish_location "https://pkgs.dev.azure.com/some-org/some-project/_packaging/some_feed/nuget/v2" + trusted true + action :register + end + ``` + + **Update an existing PowerShell repository to make it trusted**: + + ```ruby + powershell_package_source 'MyPSModule' do + source_name "MyPSModule" + trusted true + action :set + end + ``` + + **Update a Nuget package source with a new name and make it trusted**: + + ```ruby + powershell_package_source 'PowerShellModules -> GoldFishBowl' do + source_name "PowerShellModules" + new_name "GoldFishBowl" + provider_name "Nuget" + trusted true + action :set + end + ``` + + **Update a Nuget package source with a new name when the source is secured with a username and password**: + + ```ruby + powershell_package_source 'PowerShellModules -> GoldFishBowl' do + source_name "PowerShellModules" + new_name "GoldFishBowl" + trusted true + user "user@domain.io" + password "some_secret_password" + action :set + end + ``` + + **Unregister a package source**: + + ```ruby + powershell_package_source 'PowerShellModules' do + source_name "PowerShellModules" + action :unregister + end + ``` diff --git a/data/infra/resources/powershell_script.yaml b/data/infra/resources/powershell_script.yaml new file mode 100644 index 0000000..cbcdc37 --- /dev/null +++ b/data/infra/resources/powershell_script.yaml @@ -0,0 +1,441 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: powershell_script +resource_description_list: +- markdown: |- + Use the **powershell_script** resource to execute a script using the Windows PowerShell interpreter, much like how the script and script-based resources **bash**, **csh**, **perl**, **python**, and **ruby** are used. The **powershell_script** resource is specific to the Microsoft Windows platform, but may use both the Windows PowerShell interpreter or the PowerShell Core (pwsh) interpreter as of Chef Infra Client 16.6 and later. + + The **powershell_script** resource creates and executes a temporary file rather than running the command inline. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use `not_if` and `only_if` conditionals to guard this resource for idempotence. +syntax_description: | + A **powershell_script** resource block executes a batch script using the Windows PowerShell interpreter. + For example, writing to an interpolated path: + + ```ruby + powershell_script 'write-to-interpolated-path' do + code <<-EOH + $stream = [System.IO.StreamWriter] "#{Chef::Config[:file_cache_path]}/powershell-test.txt" + $stream.WriteLine("In #{Chef::Config[:file_cache_path]}...word.") + $stream.close() + EOH + end + ``` +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 + flags String + group String, Integer + 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 + use_inline_powershell true, false # default value: false + user String, Integer + action Symbol # defaults to :run if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`powershell_script` 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." +- "`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: + 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: convert_boolean_return + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: |- + Return `0` if the last line of a command is evaluated to be true or to return `1` if the last line is evaluated to be false. + + When the `guard_interpreter` common attribute is set to `:powershell_script`, a string command will be evaluated as if this value were set to `true`. This is because the behavior of this attribute is similar to the value of the `"$?"` expression common in UNIX interpreters. For example, this: + + ```ruby + powershell_script 'make_safe_backup' do + guard_interpreter :powershell_script + code 'cp ~/data/nodes.json ~/data/nodes.bak' + not_if 'test-path ~/data/nodes.bak' + end + ``` + + is similar to: + ```ruby + bash 'make_safe_backup' do + code 'cp ~/data/nodes.json ~/data/nodes.bak' + not_if 'test -e ~/data/nodes.bak' + end + ``` +- property: creates + ruby_type: String + required: false + description_list: + - markdown: Prevent a command from creating a file when that file already exists. +- property: cwd + ruby_type: String + 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 + description_list: + - 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: 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 + default_value: powershell + allowed_values: '"powershell", "pwsh"' + description_list: + - markdown: The interpreter type, `powershell` or `pwsh` (PowerShell Core) +- 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 + 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: 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: use_inline_powershell + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - 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 + description_list: + - 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: +examples: | + **Write to an interpolated path**: + + ```ruby + powershell_script 'write-to-interpolated-path' do + code <<-EOH + $stream = [System.IO.StreamWriter] "#{Chef::Config[:file_cache_path]}/powershell-test.txt" + $stream.WriteLine("In #{Chef::Config[:file_cache_path]}...word.") + $stream.close() + EOH + end + ``` + + **Change the working directory**: + + ```ruby + powershell_script 'cwd-then-write' do + cwd Chef::Config[:file_cache_path] + code <<-EOH + $stream = [System.IO.StreamWriter] "C:/powershell-test2.txt" + $pwd = pwd + $stream.WriteLine("This is the contents of: $pwd") + $dirs = dir + foreach ($dir in $dirs) { + $stream.WriteLine($dir.fullname) + } + $stream.close() + EOH + end + ``` + + **Change the working directory in Microsoft Windows**: + + ```ruby + powershell_script 'cwd-to-win-env-var' do + cwd '%TEMP%' + code <<-EOH + $stream = [System.IO.StreamWriter] "./temp-write-from-chef.txt" + $stream.WriteLine("chef on windows rox yo!") + $stream.close() + EOH + end + ``` + + **Pass an environment variable to a script**: + + ```ruby + powershell_script 'read-env-var' do + cwd Chef::Config[:file_cache_path] + environment ({'foo' => 'BAZ'}) + code <<-EOH + $stream = [System.IO.StreamWriter] "./test-read-env-var.txt" + $stream.WriteLine("FOO is $env:foo") + $stream.close() + EOH + end + ``` + + **Evaluate for true and/or false**: + + Use the `convert_boolean_return` attribute to raise an exception when + certain conditions are met. For example, the following fragments will + run successfully without error: + + ```ruby + powershell_script 'false' do + code '$false' + end + ``` + + and: + + + ```ruby + powershell_script 'true' do + code '$true' + end + ``` + + whereas the following will raise an exception: + + ```ruby + powershell_script 'false' do + convert_boolean_return true + code '$false' + end + ``` + + **Use the flags attribute**: + + ```ruby + powershell_script 'Install IIS' do + code <<-EOH + Import-Module ServerManager + Add-WindowsFeature Web-Server + EOH + flags '-NoLogo, -NonInteractive, -NoProfile, -ExecutionPolicy Unrestricted, -InputFormat None, -File' + guard_interpreter :powershell_script + not_if '(Get-WindowsFeature -Name Web-Server).Installed' + end + ``` + + **Rename computer, join domain, reboot**: + + The following example shows how to rename a computer, + join a domain, and then reboot the computer: + + ```ruby + reboot 'Restart Computer' do + action :nothing + end + + powershell_script 'Rename and Join Domain' do + code <<-EOH + ...your rename and domain join logic here... + EOH + not_if <<-EOH + $ComputerSystem = gwmi win32_computersystem + ($ComputerSystem.Name -like '#{node['some_attribute_that_has_the_new_name']}') -and + $ComputerSystem.partofdomain) + EOH + notifies :reboot_now, 'reboot[Restart Computer]', :immediately + end + ``` + + where: + + - The **powershell_script** resource block renames a computer, and + then joins a domain. + - The **reboot** resource restarts the computer. + - The `not_if` guard prevents the Windows PowerShell script from + running when the settings in the `not_if` guard match the desired + state. + - The `notifies` statement tells the **reboot** resource block to run + if the **powershell_script** block was executed during a Chef Infra + Client run. + + **Run a command as an alternate user**: + + *Note*: When Chef is running as a service, this feature + requires that the user that Chef runs as has `SeAssignPrimaryTokenPrivilege` + (aka `SE_ASSIGNPRIMARYTOKEN_NAME`) user right. By default only LocalSystem + and 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: + + ```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') + ``` + + The following example shows how to run `mkdir test_dir` from a Chef Infra Client run as an alternate user. + + ```ruby + # Passing only username and password + powershell_script 'mkdir test_dir' do + code "mkdir test_dir" + cwd Chef::Config[:file_cache_path] + user "username" + password "password" + end + + # Passing username and domain + powershell_script 'mkdir test_dir' do + code "mkdir test_dir" + cwd Chef::Config[:file_cache_path] + domain "domain" + user "username" + password "password" + end + + # Passing username = 'domain-name\\username'. No domain is passed + powershell_script 'mkdir test_dir' do + code "mkdir test_dir" + cwd Chef::Config[:file_cache_path] + user "domain-name\\username" + password "password" + end + + # Passing username = 'username@domain-name'. No domain is passed + powershell_script 'mkdir test_dir' do + code "mkdir test_dir" + cwd Chef::Config[:file_cache_path] + user "username@domain-name" + password "password" + end + + # Work around User Access Control (UAC) + powershell_script 'mkdir test_dir' do + code "mkdir test_dir" + cwd Chef::Config[:file_cache_path] + user "username" + password "password" + elevated true + end + ``` + + diff --git a/data/infra/resources/python.yaml b/data/infra/resources/python.yaml new file mode 100644 index 0000000..5a97559 --- /dev/null +++ b/data/infra/resources/python.yaml @@ -0,0 +1,200 @@ +--- +resource_reference: true +resources_common_guards: true +resource: python +resource_description_list: +- markdown: Use the **python** resource to execute scripts using the Python interpreter. + This resource may also use any of the actions and properties that are available + to the **execute** resource. Commands that are executed with this resource are + (by their nature) not idempotent, as they are typically unique to the environment + in which they are run. Use `not_if` and `only_if` to guard this resource for idempotence. +syntax_description: | + The **python** resource has the following syntax: + + ```ruby + python 'hello world' do + code <<-EOH + print "Hello world! From Chef and Python." + EOH + end + ``` +syntax_full_code_block: |- + python '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 + user String, Integer + action Symbol # defaults to :run if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`python` 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." +- "`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 + description_list: + - markdown: Prevent a command from creating a file when that file already exists. +- property: cwd + ruby_type: String + 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 + description_list: + - 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: 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 + 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: 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: user + ruby_type: String, Integer + required: false + description_list: + - 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/reboot.yaml b/data/infra/resources/reboot.yaml new file mode 100644 index 0000000..35cb030 --- /dev/null +++ b/data/infra/resources/reboot.yaml @@ -0,0 +1,83 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: reboot +resource_description_list: +- markdown: |- + Use the **reboot** resource to reboot a node, a necessary step with some installations on certain platforms. This resource is supported for use on the Microsoft Windows, macOS, and Linux platforms. + In using this resource via notifications, it's important to *only* use immediate notifications. Delayed notifications produce unintuitive and probably undesired results. +resource_new_in: '12.0' +syntax_full_code_block: |- + reboot 'name' do + delay_mins Integer # default value: 0 + reason String # default value: "Reboot by Chef Infra Client" + action Symbol # defaults to :nothing if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`reboot` 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." +- "`delay_mins` and `reason` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :request_reboot: + markdown: Reboot a node at the end of a Chef Infra Client run. + :reboot_now: + markdown: Reboot a node so that the Chef Infra Client may continue the installation + process. + :cancel: + markdown: Cancel a pending reboot request. +properties_list: +- property: delay_mins + ruby_type: Integer + required: false + default_value: '0' + description_list: + - markdown: The amount of time (in minutes) to delay a reboot request. +- property: reason + ruby_type: String + required: false + 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** + + ```ruby + reboot 'now' do + action :nothing + reason 'Cannot continue Chef run without a reboot.' + delay_mins 2 + end + + execute 'foo' do + command '...' + notifies :reboot_now, 'reboot[now]', :immediately + end + ``` + + **Reboot a node at the end of a Chef Infra Client run** + + ```ruby + reboot 'app_requires_reboot' do + action :request_reboot + reason 'Need to reboot when the run completes successfully.' + delay_mins 5 + end + ``` + + **Cancel a reboot** + + ```ruby + reboot 'cancel_reboot_request' do + action :cancel + reason 'Cancel a previous end-of-run reboot request.' + end + ``` diff --git a/data/infra/resources/registry_key.yaml b/data/infra/resources/registry_key.yaml new file mode 100644 index 0000000..23f7d47 --- /dev/null +++ b/data/infra/resources/registry_key.yaml @@ -0,0 +1,237 @@ +--- +resource_reference: true +registry_key: true +resource: registry_key +resource_description_list: +- markdown: Use the **registry_key** resource to create and delete registry keys in + 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. + + 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). + +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\ + \ data: %w(foo bar baz),\n }]\n action :create\nend\n```\n\nUse multiple registry\ + \ key entries with key values that are based on node\nattributes:\n\n```ruby\n\ + registry_key 'HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\\ + name_of_registry_key' do\n values [{name: 'key_name', type: :string, data: 'C:\\\ + Windows\\System32\\file_name.bmp'},\n {name: 'key_name', type: :string,\ + \ data: node['node_name']['attribute']['value']},\n {name: 'key_name',\ + \ type: :string, data: node['node_name']['attribute']['value']}\n ]\n action\ + \ :create\nend\n```" +syntax_full_code_block: |- + registry_key 'name' do + 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 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. + :create_if_missing: + markdown: Create a registry key if it does not exist. Also, create a registry + key value if it does not exist. + :delete: + markdown: Delete the specified values for a registry key. + :delete_key: + markdown: Delete the specified registry key and all of its subkeys. The `:delete_key` + 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. +properties_list: +- property: architecture + ruby_type: Symbol + required: false + default_value: ":machine" + allowed_values: ":i386, :machine, :x86_64" + description_list: + - markdown: 'The architecture of the node for which keys are to be created or + + deleted. Possible values: `:i386` (for nodes with a 32-bit + + registry), `:x86_64` (for nodes with a 64-bit registry), and + + `:machine` (to have Chef Infra Client determine the architecture + + during a Chef Infra Client run). + + + In order to read or write 32-bit registry keys on 64-bit machines + + running Microsoft Windows, the `architecture` property must be set + + to `:i386`. The `:x86_64` value can be used to force writing to a + + 64-bit registry location, but this value is less useful than the + + default (`:machine`) because Chef Infra Client returns an exception + + if `:x86_64` is used and the machine turns out to be a 32-bit + + machine (whereas with `:machine`, Chef Infra Client is able to + + access the registry key on the 32-bit machine).' +- property: key + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: 'The path to the location in which a registry key is to be created or + + from which a registry key is to be deleted. Default value: the + + `name` of the resource block. See "Syntax" section above for more + + information. The path must include the registry hive, which can be + + specified either as its full name or as the 3- or 4-letter + + abbreviation. For example, both `HKLM\SECURITY` and + + `HKEY_LOCAL_MACHINE\SECURITY` are both valid and equivalent. The + + following hives are valid: `HKEY_LOCAL_MACHINE`, `HKLM`, + + `HKEY_CURRENT_CONFIG`, `HKCC`, `HKEY_CLASSES_ROOT`, `HKCR`, + + `HKEY_USERS`, `HKU`, `HKEY_CURRENT_USER`, and `HKCU`.' +- property: recursive + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: 'When creating a key, this value specifies that the required keys for + + the specified path are to be created. When using the `:delete_key` + + action in a recipe, and if the registry key has subkeys, then set + + the value for this property to `true`. The `:delete_key` 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.' +- property: values + ruby_type: Hash, Array + required: false + default_value: "[]" + description_list: + - markdown: 'An array of hashes, where each Hash contains the values that are to + be set under a registry key. Each Hash must contain `name:`, + `type:`, and `data:` (and must contain no other key values). + `type:` represents the values available for registry keys in + Microsoft Windows. Use `:binary` for REG_BINARY, `:string` for + 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.' +target_mode: +examples: | + **Create a registry key** + + ```ruby + registry_key 'HKEY_LOCAL_MACHINE\\path-to-key\\Policies\\System' do + values [{ + name: 'EnableLUA', + type: :dword, + data: 0 + }] + action :create + end + ``` + + **Create a registry key with binary data: "\x01\x02\x03"**: + + ```ruby + registry_key 'HKEY_CURRENT_USER\ChefTest' do + values [{ + :name => "test", + :type => :binary, + :data => [0, 1, 2].map(&:chr).join + }] + + action :create + end + ``` + + **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: + + ```ruby + registry_key 'HKEY_LOCAL_MACHINE\SOFTWARE\Example' do + architecture :i386 + recursive true + action :create + end + ``` + + **Set proxy settings to be the same as those used by #{ChefUtils::Dist::Infra::PRODUCT}** + + ```ruby + proxy = URI.parse(Chef::Config[:http_proxy]) + registry_key 'HKCU\Software\Microsoft\path\to\key\Internet Settings' do + values [{name: 'ProxyEnable', type: :reg_dword, data: 1}, + {name: 'ProxyServer', data: "#{proxy.host}:#{proxy.port}"}, + {name: 'ProxyOverride', type: :reg_string, data: }, + ] + action :create + end + ``` + + **Set the name of a registry key to "(Default)"** + + ```ruby + registry_key 'Set (Default) value' do + key 'HKLM\Software\Test\Key\Path' + values [ + {name: '', type: :string, data: 'test'}, + ] + action :create + end + ``` + + **Delete a registry key value** + + ```ruby + registry_key 'HKEY_LOCAL_MACHINE\SOFTWARE\path\to\key\AU' do + values [{ + name: 'NoAutoRebootWithLoggedOnUsers', + type: :dword, + data: '' + }] + action :delete + end + ``` + + 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** + + ```ruby + registry_key 'HKCU\SOFTWARE\Policies\path\to\key\Themes' do + recursive true + action :delete_key + 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}. diff --git a/data/infra/resources/remote_directory.yaml b/data/infra/resources/remote_directory.yaml new file mode 100644 index 0000000..1a8cd0e --- /dev/null +++ b/data/infra/resources/remote_directory.yaml @@ -0,0 +1,225 @@ +--- +resource_reference: true +common_resource_functionality_resources_common_windows_security: true +remote_directory_recursive_directories: true +resource_directory_recursive_directories: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: remote_directory +resource_description_list: +- markdown: Use the **remote_directory** resource to incrementally transfer a directory + from a cookbook to a node. The directory that is copied from the cookbook should + be located under `COOKBOOK_NAME/files/default/REMOTE_DIRECTORY`. The `remote_directory` + resource will obey file specificity. +syntax_description: "A **remote_directory** resource block transfers a directory from\ + \ a\ncookbook to a node, and then assigns the permissions needed on that\ndirectory.\ + \ For example:\n\n```ruby\nremote_directory '/etc/apache2' do\n source 'apache2'\n\ + \ owner 'root'\n group 'root'\n mode '0755'\n action :create\nend\n```" +syntax_full_code_block: "remote_directory 'name' do\n cookbook String\n + \ files_backup Integer, false # default value: 5\n files_group String, + Integer\n files_mode String, Integer # default value: \"0644 on *nix systems\"\n + \ files_owner String, Integer\n group \n mode \n + \ overwrite true, false # default value: true\n owner \n path + \ String # default value: 'name' unless specified\n purge true, + 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." +- "`action` identifies which steps Chef Infra Client will take to bring the node into + the desired state." +- "`cookbook`, `files_backup`, `files_group`, `files_mode`, `files_owner`, `group`, + `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. +properties_list: +- property: cookbook + ruby_type: String + required: false + description_list: + - markdown: The cookbook in which a file is located (if it is not located in the + current cookbook). The default value is the current cookbook. +- property: files_backup + ruby_type: Integer, false + required: false + default_value: '5' + description_list: + - markdown: The number of backup copies to keep for files in the directory. +- property: files_group + ruby_type: String, Integer + required: false + description_list: + - markdown: Configure group permissions for files. A string or ID that identifies + the group owner by group name, 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: files_mode + ruby_type: String, Integer + required: false + default_value: 0644 on *nix systems + 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. +- property: files_owner + ruby_type: String, Integer + required: false + description_list: + - markdown: Configure owner permissions for files. 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 is not specified, existing owners remain unchanged + and new owner assignments use the current user (when necessary). +- property: group + ruby_type: '' + required: false + description_list: + - markdown: 'Use to configure permissions for directories. 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: mode + ruby_type: '' + 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 directory already exists, the existing mode on the + + directory is used. If `mode` is not specified, the directory 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 directory 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: overwrite + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Overwrite a file when it is different. +- property: owner + ruby_type: '' + required: false + description_list: + - markdown: 'Use to configure permissions for directories. 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 path to the directory. Using a fully qualified path is recommended, + but is not always required. +- property: purge + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Purge extra files found in the target directory. +- property: recursive + ruby_type: true, false + required: false + default_value: 'true' + 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: 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). +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\ + \ from the directory\n remote_directory '/tmp/remote_something' do\n source\ + \ 'something'\n files_backup 10\n files_owner 'root'\n files_group 'root'\n\ + \ files_mode '0644'\n owner 'nobody'\n group 'nobody'\n mode '0755'\n\ + \ end\n ```\n\n Use with the chef_handler resource\n\n The following example\ + \ shows how to use the **remote_directory**\n resource and the **chef_handler**\ + \ resource to reboot a handler named\n `WindowsRebootHandler`:\n\n ```ruby\n\ + \ # the following code sample comes from the\n # ``reboot_handler`` recipe in\ + \ the ``windows`` cookbook:\n # https://github.com/chef-cookbooks/windows\n\n \ + \ remote_directory node['chef_handler']['handler_path'] do\n source 'handlers'\n\ + \ recursive true\n action :create\n end\n\n chef_handler 'WindowsRebootHandler'\ + \ do\n source \"#{node['chef_handler']['handler_path']}/windows_reboot_handler.rb\"\ + \n arguments node['windows']['allow_pending_reboots']\n supports :report =>\ + \ true, :exception => false\n action :enable\n end\n ```\n" + diff --git a/data/infra/resources/remote_file.yaml b/data/infra/resources/remote_file.yaml new file mode 100644 index 0000000..81bf82f --- /dev/null +++ b/data/infra/resources/remote_file.yaml @@ -0,0 +1,349 @@ +--- +resource_reference: true +properties_resources_common_windows_security: true +remote_file_prevent_re_downloads: true +remote_file_unc_path: true +resources_common_atomic_update: true +resource: remote_file +resource_description_list: +- markdown: Use the **remote_file** resource to transfer a file from a remote location + using file specificity. This resource is similar to the **file** resource. +- note: + markdown: Fetching files from the `files/` directory in a cookbook should be done + with the **cookbook_file** resource. +syntax_description: "A **remote_file** resource block manages files by using files\ + \ that\nexist remotely. For example, to write the home page for an Apache\nwebsite:\n\ + \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\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: +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`, `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. + :delete: + markdown: Delete a file. + :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. +- property: authentication + ruby_type: Symbol + required: false + default_value: ":remote" + allowed_values: ":local, :remote" + description_list: + - markdown: +- 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: Optional, see `use_conditional_get`. The SHA-256 checksum of the file. + Use to prevent a file from being re-downloaded. When the local file matches + the checksum, Chef Infra Client does not download it. +- 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: ftp_active_mode + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Whether Chef Infra Client uses active or passive FTP. Set to `true` + to use active FTP. +- property: group + 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: headers + ruby_type: Hash + required: false + default_value: "{}" + description_list: + - markdown: |- + A Hash of custom headers. For example: + + ```ruby + headers({ "Cookie" => "user=some_user; pass=p@ssw0rd!" }) + ``` + + or: + + ```ruby + headers({ "Referer" => "#{header}" }) + ``` + + or: + + ```ruby + headers( "Authorization"=>"Basic #{ Base64.encode64("#{username}:#{password}").gsub("\n", "") }" ) + ``` +- property: http_options + ruby_type: Hash + required: false + default_value: "{}" + new_in: '17.5' + description_list: + - markdown: 'A Hash of custom HTTP options. For example: `http_options({ http_retry_count: + 0, http_retry_delay: 2 })`' +- 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: '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: '' + 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: remote_domain + ruby_type: String + required: false + new_in: '13.4' + description_list: + - markdown: "**Windows only** The domain of the user specified by the `remote_user` + property. By default the resource will authenticate against the domain of the + remote system, or as a local account if the remote system is not joined to a + domain. If the remote system is not part of a domain, it is necessary to authenticate + as a local user on the remote system by setting the domain to `.`, for example: + remote_domain '.'. The domain may also be specified as part of the `remote_user` + property." +- property: remote_password + ruby_type: String + required: false + new_in: '13.4' + description_list: + - markdown: "**Windows only** The password of the user specified by the `remote_user` + property. This property is required if `remote_user` is specified and may only + be specified if `remote_user` is specified. The `sensitive` property for this + resource will automatically be set to `true` if `remote_password` is specified." +- property: remote_user + ruby_type: String + required: false + new_in: '13.4' + description_list: + - markdown: "**Windows only** The name of a user with access to the remote file + specified by the source property. The user name may optionally be specified + with a domain, such as: `domain\\user` or `user@my.dns.domain.com` via Universal + Principal Name (UPN) format. The domain may also be set using the `remote_domain` + property. Note that this property is ignored if source is not a UNC path. If + this property is specified, the `remote_password` property is required." +- property: show_progress + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Displays the progress of the file download. +- property: ssl_verify_mode + ruby_type: Symbol + required: false + new_in: '16.2' + allowed_values: ":verify_none, :verify_peer" + description_list: + - markdown: Optional property to override SSL policy. If not specified, uses the + SSL policy from `config.rb`. +- property: use_etag + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Enable ETag headers. Set to `false` to disable ETag headers. To use + this setting, `use_conditional_get` must also be set to true. +- property: use_last_modified + ruby_type: true, false + required: false + default_value: 'true' + 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`. +target_mode: + support: full +examples: | + **Download a file without checking the checksum**: + + ```ruby + remote_file '/tmp/remote.txt' do + source 'https://example.org/remote.txt' + end + ``` + + **Download a file with a checksum to validate**: + + ```ruby + remote_file '/tmp/test_file' do + source 'http://www.example.com/tempfiles/test_file' + mode '0755' + checksum '3a7dac00b1' # A SHA256 (or portion thereof) of the file. + end + ``` + + **Download a file only if it's not already present**: + + ```ruby + remote_file '/tmp/remote.txt' do + source 'https://example.org/remote.txt' + checksum '3a7dac00b1' # A SHA256 (or portion thereof) of the file. + action :create_if_missing + end + ``` + + **Using HTTP Basic Authentication in Headers**: + + ```ruby + remote_file '/tmp/remote.txt' do + source 'https://example.org/remote.txt' + headers('Authorization' => "Basic #{Base64.encode64("USERNAME_VALUE:PASSWORD_VALUE").delete("\n")}") + checksum '3a7dac00b1' # A SHA256 (or portion thereof) of the file. + action :create_if_missing + end + ``` + + **Downloading a file to the Chef file cache dir for execution**: + + ```ruby + remote_file '#{Chef::Config['file_cache_path']}/install.sh' do + source 'https://example.org/install.sh' + action :create_if_missing + end + + execute '#{Chef::Config['file_cache_path']}/install.sh' + ``` + + **Specify advanced HTTP connection options including Net::HTTP (nethttp) options:** + + ```ruby + remote_file '/tmp/remote.txt' do + source 'https://example.org/remote.txt' + http_options({ + http_retry_delay: 0, + http_retry_count: 0, + keepalives: false, + nethttp: { + continue_timeout: 5, + max_retries: 5, + read_timeout: 5, + write_timeout: 5, + ssl_timeout: 5, + }, + }) + end + ``` diff --git a/data/infra/resources/rhsm_errata.yaml b/data/infra/resources/rhsm_errata.yaml new file mode 100644 index 0000000..93e670e --- /dev/null +++ b/data/infra/resources/rhsm_errata.yaml @@ -0,0 +1,52 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: rhsm_errata +resource_description_list: +- markdown: Use the **rhsm_errata** resource to install packages associated with a + given Red Hat Subscription Manager Errata ID. This is helpful if packages to mitigate + a single vulnerability must be installed on your hosts. +resource_new_in: '14.0' +syntax_full_code_block: |- + rhsm_errata 'name' do + errata_id String # default value: 'name' unless specified + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`rhsm_errata` 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." +- "`errata_id` is the property available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :install: + markdown: Install a package for a specific errata ID. (default) +properties_list: +- property: errata_id + ruby_type: String + required: false + default_value: The resource block's name + 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** + + ```ruby + rhsm_errata 'RHSA:2018-1234' + ``` + + **Specify an Errata ID that differs from the resource name** + + ```ruby + rhsm_errata 'errata-install' + errata_id 'RHSA:2018-1234' + end + ``` diff --git a/data/infra/resources/rhsm_errata_level.yaml b/data/infra/resources/rhsm_errata_level.yaml new file mode 100644 index 0000000..1721b52 --- /dev/null +++ b/data/infra/resources/rhsm_errata_level.yaml @@ -0,0 +1,48 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: rhsm_errata_level +resource_description_list: +- markdown: Use the **rhsm_errata_level** resource to install all packages of a specified + errata level from the Red Hat Subscription Manager. For example, you can ensure + that all packages associated with errata marked at a 'Critical' security level + are installed. +resource_new_in: '14.0' +syntax_full_code_block: |- + rhsm_errata_level 'name' do + errata_level String # default value: 'name' unless specified + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`rhsm_errata_level` 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." +- "`errata_level` is the property available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :install: + markdown: Install all packages of the specified errata level. (default) +properties_list: +- property: errata_level + ruby_type: String + required: false + default_value: The resource block's name + allowed_values: '"critical", "important", "low", "moderate"' + 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** + + ```ruby + rhsm_errata_level 'example_install_moderate' do + errata_level 'moderate' + end + ``` diff --git a/data/infra/resources/rhsm_register.yaml b/data/infra/resources/rhsm_register.yaml new file mode 100644 index 0000000..a2625ef --- /dev/null +++ b/data/infra/resources/rhsm_register.yaml @@ -0,0 +1,175 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: rhsm_register +resource_description_list: +- markdown: Use the **rhsm_register** resource to register a node with the Red Hat + Subscription Manager or a local Red Hat Satellite server. +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 + 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_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`, `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 + :register: + markdown: Register the node with RHSM. (default) + :unregister: + markdown: Unregister the node from RHSM. +properties_list: +- property: activation_key + ruby_type: String, Array + required: false + description_list: + - markdown: A string or array of activation keys to use when registering; you must + also specify the 'organization' property when using this property. +- property: auto_attach + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: If true, RHSM will attempt to automatically attach the host to applicable + subscriptions. It is generally better to use an activation key with the subscriptions + pre-defined. +- property: base_url + ruby_type: String + required: false + new_in: '17.8' + description_list: + - markdown: The hostname of the content delivery server to use to receive updates. + Both Customer Portal Subscription Management and Subscription Asset Manager + use Red Hat's hosted content delivery services, with the URL https://cdn.redhat.com. + Since Satellite 6 hosts its own content, the URL must be used for systems registered + with Satellite 6. +- property: environment + ruby_type: String + required: false + description_list: + - markdown: The environment to use when registering; required when using the username + and password properties. +- property: force + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: If true, the system will be registered even if it is already registered. + Normally, any register operations will fail if the machine has already been + registered. +- property: https_for_ca_consumer + ruby_type: true, false + required: false + default_value: 'false' + new_in: '15.9' + description_list: + - markdown: If true, Chef Infra Client will fetch the katello-ca-consumer-latest.noarch.rpm + from the satellite_host using HTTPS. +- property: install_katello_agent + ruby_type: true, false + required: false + 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 + description_list: + - markdown: The organization to use when registering; required when using the 'activation_key' + property. +- property: password + ruby_type: String + required: false + description_list: + - markdown: The password to use when registering. This property is not applicable + if using an activation key. If specified, username and environment are also + required. +- property: release + ruby_type: Float, String + required: false + new_in: '17.8' + 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 + example, `release '6.4'` will append `--release=6.4` to the register command. +- property: satellite_host + ruby_type: String + required: false + description_list: + - markdown: The FQDN of the Satellite host to register with. If this property is + not specified, the host will register with Red Hat's public RHSM service. +- property: server_url + ruby_type: String + required: false + new_in: '17.8' + description_list: + - markdown: The hostname of the subscription service to use. The default is Customer + Portal Subscription Management, subscription.rhn.redhat.com. If you do not use + this option, the system registers with Customer Portal Subscription Management. +- property: service_level + ruby_type: String + required: false + new_in: '17.8' + description_list: + - markdown: Sets the service level to use for subscriptions on the registering machine. + This is only used with the `auto_attach` option. +- property: system_name + ruby_type: String + required: false + new_in: '16.5' + description_list: + - markdown: The name of the system to register, defaults to the hostname. +- property: username + ruby_type: String + required: false + description_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** + + ```ruby + rhsm_register 'my-host' do + activation_key 'ABCD1234' + organization 'my_org' + end + ``` diff --git a/data/infra/resources/rhsm_repo.yaml b/data/infra/resources/rhsm_repo.yaml new file mode 100644 index 0000000..ed6b90a --- /dev/null +++ b/data/infra/resources/rhsm_repo.yaml @@ -0,0 +1,53 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: rhsm_repo +resource_description_list: +- markdown: Use the **rhsm_repo** resource to enable or disable Red Hat Subscription + Manager repositories that are made available via attached subscriptions. +resource_new_in: '14.0' +syntax_full_code_block: |- + rhsm_repo 'name' do + repo_name String # default value: 'name' unless specified + action Symbol # defaults to :enable if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`rhsm_repo` 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." +- "`repo_name` is the property available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :enable: + markdown: Enable a RHSM repository. (default) + :disable: + markdown: Disable a RHSM repository. +properties_list: +- property: repo_name + ruby_type: String + required: false + default_value: The resource block's name + 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** + + ```ruby + rhsm_repo 'rhel-7-server-extras-rpms' + ``` + + **Disable an RHSM repository** + + ```ruby + rhsm_repo 'rhel-7-server-extras-rpms' do + action :disable + end + ``` diff --git a/data/infra/resources/rhsm_subscription.yaml b/data/infra/resources/rhsm_subscription.yaml new file mode 100644 index 0000000..cbb6e84 --- /dev/null +++ b/data/infra/resources/rhsm_subscription.yaml @@ -0,0 +1,41 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: rhsm_subscription +resource_description_list: +- markdown: Use the **rhsm_subscription** resource to add or remove Red Hat Subscription + Manager subscriptions from your host. This can be used when a host's activation_key + does not attach all necessary subscriptions to your host. +resource_new_in: '14.0' +syntax_full_code_block: |- + rhsm_subscription 'name' do + pool_id String # default value: 'name' unless specified + action Symbol # defaults to :attach if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`rhsm_subscription` 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." +- "`pool_id` is the property available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :attach: + markdown: Attach the node to a subscription pool. (default) + :remove: + markdown: Remove the node from a subscription pool. +properties_list: +- property: pool_id + ruby_type: String + required: false + default_value: The resource block's name + 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 new file mode 100644 index 0000000..591fcec --- /dev/null +++ b/data/infra/resources/route.yaml @@ -0,0 +1,80 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: route +resource_description_list: +- markdown: Use the **route** resource to manage the system routing table in a Linux + environment. +syntax_description: "A **route** resource block manages the system routing table in\ + \ a Linux\nenvironment:\n\n```ruby\nroute '10.0.1.10/32' do\n gateway '10.0.0.20'\n\ + \ device 'eth1'\nend\n```" +syntax_full_code_block: |- + route 'name' do + comment String + device String + gateway String + metric Integer + netmask String + route_type Symbol, String # default value: :host + target String # default value: 'name' unless specified + action Symbol # defaults to :add if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`route` 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." +- "`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. +properties_list: +- property: comment + ruby_type: String + required: false + new_in: '14.0' + description_list: + - markdown: Add a comment for the route. +- property: device + ruby_type: String + required: false + description_list: + - markdown: The network interface to which the route applies. +- property: gateway + ruby_type: String + required: false + description_list: + - markdown: The gateway for the route. +- property: metric + ruby_type: Integer + required: false + description_list: + - markdown: The route metric value. +- property: netmask + ruby_type: String + required: false + description_list: + - markdown: 'The decimal representation of the network mask. For example: `255.255.255.0`.' +- property: route_type + ruby_type: Symbol, String + required: false + default_value: ":host" + allowed_values: ":host, :net" + description_list: [] +- property: target + ruby_type: String + required: false + 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 new file mode 100644 index 0000000..3a00be6 --- /dev/null +++ b/data/infra/resources/rpm_package.yaml @@ -0,0 +1,94 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: rpm_package +resource_description_list: +- markdown: Use the **rpm_package** resource to manage packages using the RPM Package + Manager. +syntax_full_code_block: |- + rpm_package 'name' do + allow_downgrade true, false # default value: true + environment Hash # default value: {} + options String, Array + package_name String + source String + timeout String, Integer + version String + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`rpm_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." +- "`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) + :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 + 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: options + ruby_type: String, Array + required: false + description_list: + - markdown: One (or more) additional command options that are passed to the command. +- property: package_name + ruby_type: String + required: false + description_list: + - 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: The optional path to a package on the local file system. +- property: timeout + ruby_type: String, Integer + required: false + description_list: + - markdown: The amount of time (in seconds) to wait before timing out. +- property: version + ruby_type: String + 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 new file mode 100644 index 0000000..bc4eebb --- /dev/null +++ b/data/infra/resources/ruby.yaml @@ -0,0 +1,200 @@ +--- +resource_reference: true +resources_common_guards: true +resource: ruby +resource_description_list: +- markdown: Use the **ruby** resource to execute scripts using the Ruby interpreter. + This resource may also use any of the actions and properties that are available + to the **execute** resource. Commands that are executed with this resource are + (by their nature) not idempotent, as they are typically unique to the environment + in which they are run. Use `not_if` and `only_if` to guard this resource for idempotence. +syntax_description: | + A **ruby** resource block executes scripts using Ruby: + ```ruby + ruby 'hello world' do + code <<-EOH + puts "Hello world! From Chef and Ruby." + EOH + end + ``` +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 + 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: +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." +- "`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 + description_list: + - markdown: Prevent a command from creating a file when that file already exists. +- property: cwd + ruby_type: String + 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 + description_list: + - 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: 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 + 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: 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: user + ruby_type: String, Integer + required: false + description_list: + - 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 new file mode 100644 index 0000000..098d8e6 --- /dev/null +++ b/data/infra/resources/ruby_block.yaml @@ -0,0 +1,143 @@ +--- +resource_reference: true +resource: ruby_block +resource_description_list: +- markdown: Use the **ruby_block** resource to execute Ruby code during a Chef Infra + Client run. Ruby code in the `ruby_block` resource is evaluated with other resources + during convergence, whereas Ruby code outside of a `ruby_block` resource is evaluated + before other resources, as the recipe is compiled. +syntax_description: "A **ruby_block** resource block executes a block of arbitrary\ + \ Ruby\ncode. For example, to reload the client.rb file during a Chef Infra\nClient\ + \ run:\n\n```ruby\nruby_block 'reload_client_config' do\n block do\n Chef::Config.from_file(\"\ + /etc/chef/client.rb\")\n end\n action :run\nend\n```" +syntax_full_code_block: |- + ruby_block 'name' do + 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." +- "`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: + :nothing: + shortcode: resources_common_actions_nothing.md + :run: + markdown: "Run a Ruby block. (default)" + :create: + markdown: The same as `:run`. +properties_list: +- property: block_name + ruby_type: String + required: false + default_value: The resource block's name + description_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** + + ```ruby + ruby_block 'reload_client_config' do + block do + Chef::Config.from_file('/etc/chef/client.rb') + end + action :run + end + ``` + + **Run a block on a particular platform** + + The following example shows how an if statement can be used with the `windows?` method in the Chef Infra Language to run code specific to Microsoft Windows. The code is defined using the ruby_block resource: + + ```ruby + if windows? + ruby_block 'copy libmysql.dll into ruby path' do + block do + require 'fileutils' + FileUtils.cp "#{node['mysql']['client']['lib_dir']}\\libmysql.dll", + node['mysql']['client']['ruby_dir'] + end + not_if { ::File.exist?("#{node['mysql']['client']['ruby_dir']}\\libmysql.dll") } + end + end + ``` + + **Stash a file in a data bag** + + The following example shows how to use the ruby_block resource to stash a BitTorrent file in a data bag so that it can be distributed to nodes in the organization. + + ```ruby + ruby_block 'share the torrent file' do + block do + f = File.open(node['bittorrent']['torrent'],'rb') + #read the .torrent file and base64 encode it + enc = Base64.encode64(f.read) + data = { + 'id'=>bittorrent_item_id(node['bittorrent']['file']), + 'seed'=>node.ipaddress, + 'torrent'=>enc + } + item = Chef::DataBagItem.new + item.data_bag('bittorrent') + item.raw_data = data + item.save + end + action :nothing + subscribes :create, "bittorrent_torrent[#{node['bittorrent']['torrent']}]", :immediately + end + ``` + + **Update the /etc/hosts file** + + The following example shows how the ruby_block resource can be used to update the /etc/hosts file: + + ```ruby + ruby_block 'edit etc hosts' do + block do + rc = Chef::Util::FileEdit.new('/etc/hosts') + rc.search_file_replace_line(/^127\.0\.0\.1 localhost$/, + '127.0.0.1 #{new_fqdn} #{new_hostname} localhost') + rc.write_file + end + end + ``` + + **Set environment variables** + + The following example shows how to use variables within a Ruby block to set environment variables using rbenv. + + ```ruby + node.override[:rbenv][:root] = rbenv_root + node.override[:ruby_build][:bin_path] = rbenv_binary_path + + ruby_block 'initialize' do + block do + ENV['RBENV_ROOT'] = node[:rbenv][:root] + ENV['PATH'] = "#{node[:rbenv][:root]}/bin:#{node[:ruby_build][:bin_path]}:#{ENV['PATH']}" + end + end + ``` + + **Call methods in a gem** + + The following example shows how to call methods in gems not shipped in Chef Infra Client + + ```ruby + chef_gem 'mongodb' + + ruby_block 'config_replicaset' do + block do + MongoDB.configure_replicaset(node, replicaset_name, rs_nodes) + end + action :run + end + ``` diff --git a/data/infra/resources/script.yaml b/data/infra/resources/script.yaml new file mode 100644 index 0000000..11038e5 --- /dev/null +++ b/data/infra/resources/script.yaml @@ -0,0 +1,323 @@ +--- +resource_reference: true +resources_common_guard_interpreter: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: script +resource_description_list: +- markdown: Use the **script** resource to execute scripts using a specified interpreter, + such as Bash, csh, Perl, Python, or Ruby. This resource may also use any of the + actions and properties that are available to the **execute** resource. Commands + that are executed with this resource are (by their nature) not idempotent, as + they are typically unique to the environment in which they are run. Use `not_if` + and `only_if` to guard this resource for idempotence. +- markdown: 'This resource is the base resource for several other resources used for + scripting on specific platforms. For more information about specific + resources for specific platforms, see the following topics: + - [bash](/resources/bundled/bash/) + - [csh](/resources/bundled/csh/) + - [ksh](/resources/bundled/ksh/) + - [perl](/resources/bundled/perl/) + - [python](/resources/bundled/python/) + - [ruby](/resources/bundled/ruby/) + Changed in 12.19 to support windows alternate user identity in execute + resources' +syntax_description: "A **script** resource block typically executes scripts using\ + \ a specified\ninterpreter, such as Bash, csh, Perl, Python, or Ruby:\n\n```ruby\n\ + script 'extract_module' do\n interpreter \"bash\"\n cwd ::File.dirname(src_filepath)\n\ + \ code <<-EOH\n mkdir -p #{extract_path}\n tar xzf #{src_filename} -C #{extract_path}\n\ + \ mv #{extract_path}/*/* #{extract_path}/\n EOH\n not_if { ::File.exist?(extract_path)\ + \ }\nend\n```" +syntax_properties_list: +- '`interpreter` specifies the command shell to use' +- '`cwd` specifies the directory from which the command is run' +- | + `code` specifies the command to run + It is more common to use the **script**-based resource that is specific to the + command shell. Chef has shell-specific resources for Bash, csh, ksh, Perl, + Python, and Ruby. + The same command as above, but run using the **bash** resource: + ```ruby + bash 'extract_module' do + cwd ::File.dirname(src_filepath) + code <<-EOH + mkdir -p #{extract_path} + tar xzf #{src_filename} -C #{extract_path} + mv #{extract_path}/*/* #{extract_path}/ + EOH + not_if { ::File.exist?(extract_path) } + end + ``` +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 + user String, Integer + action Symbol # defaults to :run if not specified + end +syntax_full_properties_list: +- "`script` 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." +- "`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 + description_list: + - markdown: Prevent a command from creating a file when that file already exists. +- property: cwd + ruby_type: String + 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 + description_list: + - 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: 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 + 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 + 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: 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: user + ruby_type: String, Integer + required: false + description_list: + - 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 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\ + \ tar -zxf tarball.tar.gz\n cd tarball\n ./configure\n make\n make\ + \ install\n EOH\n end\n ```\n\n Run a script\n\n ```ruby\n script 'install_something'\ + \ do\n interpreter 'bash'\n user 'root'\n cwd '/tmp'\n code <<-EOH\n\ + \ wget http://www.example.com/tarball.tar.gz\n tar -zxf tarball.tar.gz\n \ + \ cd tarball\n ./configure\n make\n make install\n EOH\n end\n ```\n\ + \n or something like:\n\n ```ruby\n bash 'openvpn-server-key' do\n environment('KEY_CN'\ + \ => 'server')\n code <<-EOF\n openssl req -batch -days #{node['openvpn']['key']['expire']}\ + \ \\\n -nodes -new -newkey rsa:#{key_size} -keyout #{key_dir}/server.key\ + \ \\\n -out #{key_dir}/server.csr -extensions server \\\n -config\ + \ #{key_dir}/openssl.cnf\n EOF\n not_if { File.exist?('#{key_dir}/server.crt')\ + \ }\n end\n ```\n\n where `code` contains the OpenSSL command to be run. The\ + \ `not_if`\n property tells Chef Infra Client not to run the command if the file\n\ + \ already exists.\n\n Install a file from a remote location using bash\n\n The\ + \ following is an example of how to install the `foo123` module for\n Nginx. This\ + \ module adds shell-style functionality to an Nginx\n configuration file and does\ + \ the following:\n\n - Declares three variables\n - Gets the Nginx file from\ + \ a remote location\n - Installs the file using Bash to the path specified by\ + \ the\n `src_filepath` variable\n\n \n\n ```ruby\n # the following\ + \ code sample is similar to the ``upload_progress_module``\n # recipe in the ``nginx``\ + \ cookbook:\n # https://github.com/chef-cookbooks/nginx\n\n src_filename = \"\ + foo123-nginx-module-v#{\n node['nginx']['foo123']['version']\n }.tar.gz\"\n\ + \ src_filepath = \"#{Chef::Config['file_cache_path']}/#{src_filename}\"\n extract_path\ + \ = \"#{\n Chef::Config['file_cache_path']\n }/nginx_foo123_module/#{\n \ + \ node['nginx']['foo123']['checksum']\n }\"\n\n remote_file 'src_filepath' do\n\ + \ source node['nginx']['foo123']['url']\n checksum node['nginx']['foo123']['checksum']\n\ + \ owner 'root'\n group 'root'\n mode '0755'\n end\n\n bash 'extract_module'\ + \ do\n cwd ::File.dirname(src_filepath)\n code <<-EOH\n mkdir -p #{extract_path}\n\ + \ tar xzf #{src_filename} -C #{extract_path}\n mv #{extract_path}/*/*\ + \ #{extract_path}/\n EOH\n not_if { ::File.exist?(extract_path) }\n end\n\ + \ ```\n\n Install an application from git using bash\n\n The following example\ + \ shows how Bash can be used to install a plug-in\n for rbenv named `ruby-build`,\ + \ which is located in git version source\n control. First, the application is synchronized,\ + \ and then Bash changes\n its working directory to the location in which `ruby-build`\ + \ is located,\n and then runs a command.\n\n ```ruby\n git \"#{Chef::Config[:file_cache_path]}/ruby-build\"\ + \ do\n repository 'git://github.com/sstephenson/ruby-build.git'\n revision\ + \ 'master'\n action :sync\n end\n\n bash 'install_ruby_build' do\n cwd \"\ + #{Chef::Config[:file_cache_path]}/ruby-build\"\n user 'rbenv'\n group 'rbenv'\n\ + \ code <<-EOH\n ./install.sh\n EOH\n environment 'PREFIX' => '/usr/local'\n\ + \ end\n ```\n\n To read more about `ruby-build`, see here:\n .\n\ + \n Store certain settings\n\n The following recipe shows how an attributes file\ + \ can be used to store\n certain settings. An attributes file is located in the\ + \ `attributes/`\n directory in the same cookbook as the recipe which calls the\ + \ attributes\n file. In this example, the attributes file specifies certain settings\n\ + \ for Python that are then used across all nodes against which this recipe\n will\ + \ run.\n\n Python packages have versions, installation directories, URLs, and\n\ + \ checksum files. An attributes file that exists to support this type of\n recipe\ + \ would include settings like the following:\n\n ```ruby\n default['python']['version']\ + \ = '2.7.1'\n\n if python['install_method'] == 'package'\n default['python']['prefix_dir']\ + \ = '/usr'\n else\n default['python']['prefix_dir'] = '/usr/local'\n end\n\n\ + \ default['python']['url'] = 'http://www.python.org/ftp/python'\n default['python']['checksum']\ + \ = '80e387...85fd61'\n ```\n\n and then the methods in the recipe may refer to\ + \ these values. A recipe\n that is used to install Python will need to do the following:\n\ + \n - Identify each package to be installed (implied in this example, not\n \ + \ shown)\n - Define variables for the package `version` and the `install_path`\n\ + \ - Get the package from a remote location, but only if the package does\n \ + \ not already exist on the target system\n - Use the **bash** resource to\ + \ install the package on the node, but\n only when the package is not already\ + \ installed\n\n \n\n ```ruby\n # the following code sample comes from\ + \ the ``oc-nginx`` cookbook on |github|: https://github.com/cookbooks/oc-nginx\n\ + \n version = node['python']['version']\n install_path = \"#{node['python']['prefix_dir']}/lib/python#{version.split(/(^\\\ + d+\\.\\d+)/)[1]}\"\n\n remote_file \"#{Chef::Config[:file_cache_path]}/Python-#{version}.tar.bz2\"\ + \ do\n source \"#{node['python']['url']}/#{version}/Python-#{version}.tar.bz2\"\ + \n checksum node['python']['checksum']\n mode '0755'\n not_if { ::File.exist?(install_path)\ + \ }\n end\n\n bash 'build-and-install-python' do\n cwd Chef::Config[:file_cache_path]\n\ + \ code <<-EOF\n tar -jxvf Python-#{version}.tar.bz2\n (cd Python-#{version}\ + \ && ./configure #{configure_options})\n (cd Python-#{version} && make && make\ + \ install)\n EOF\n not_if { ::File.exist?(install_path) }\n end\n ```\n\n\ + \ Run a command as an alternate user\n\n *Note*: When Chef is running as a service,\ + \ this feature requires that\n the user that Chef runs as has 'SeAssignPrimaryTokenPrivilege'\ + \ (aka\n 'SE_ASSIGNPRIMARYTOKEN_NAME') user right. By default only LocalSystem\n\ + \ and NetworkService have this right when running as a service. This is\n necessary\ + \ even if the user is an Administrator.\n\n This right can be added and checked\ + \ in a recipe using this example:\n\n ```ruby\n # Add 'SeAssignPrimaryTokenPrivilege'\ + \ for the user\n Chef::ReservedNames::Win32::Security.add_account_right('',\ + \ 'SeAssignPrimaryTokenPrivilege')\n\n # Check if the user has 'SeAssignPrimaryTokenPrivilege'\ + \ rights\n Chef::ReservedNames::Win32::Security.get_account_right('').include?('SeAssignPrimaryTokenPrivilege')\n\ + \ ```\n\n The following example shows how to run `mkdir test_dir` from a Chef\n\ + \ Infra Client run as an alternate user.\n\n ```ruby\n # Passing only username\ + \ and password\n script 'mkdir test_dir' do\n interpreter \"bash\"\n code \ + \ \"mkdir test_dir\"\n cwd Chef::Config[:file_cache_path]\n user \"username\"\ + \n password \"password\"\n end\n\n # Passing username and domain\n script 'mkdir\ + \ test_dir' do\n interpreter \"bash\"\n code \"mkdir test_dir\"\n cwd Chef::Config[:file_cache_path]\n\ + \ domain \"domain-name\"\n user \"username\"\n password \"password\"\n end\n\ + \n # Passing username = 'domain-name\\\\username'. No domain is passed\n script\ + \ 'mkdir test_dir' do\n interpreter \"bash\"\n code \"mkdir test_dir\"\n \ + \ cwd Chef::Config[:file_cache_path]\n user \"domain-name\\\\username\"\n password\ + \ \"password\"\n end\n\n # Passing username = 'username@domain-name'. No domain\ + \ is passed\n script 'mkdir test_dir' do\n interpreter \"bash\"\n code \"\ + mkdir test_dir\"\n cwd Chef::Config[:file_cache_path]\n user \"username@domain-name\"\ + \n password \"password\"\n end\n ```\n" diff --git a/data/infra/resources/selinux_boolean.yaml b/data/infra/resources/selinux_boolean.yaml new file mode 100644 index 0000000..b837b07 --- /dev/null +++ b/data/infra/resources/selinux_boolean.yaml @@ -0,0 +1,65 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: selinux_boolean +resource_description_list: +- markdown: Use **selinux_boolean** resource to set SELinux boolean values. +resource_new_in: '18.0' +syntax_full_code_block: |- + selinux_boolean 'name' do + boolean String # default value: 'name' unless specified + persistent true, false # default value: true + value Integer, String, true, false + action Symbol # defaults to :set if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`selinux_boolean` 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." +- "`boolean`, `persistent`, and `value` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :set: + markdown: Set the state of the boolean. (default) +properties_list: +- property: boolean + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: SELinux boolean to set. +- property: persistent + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Set to true for value setting to survive reboot. +- property: value + ruby_type: Integer, String, true, false + required: true + allowed_values: '"off", "on"' + description_list: + - markdown: SELinux boolean value. +target_mode: + support: full +examples: | + **Set ssh_keysign to true**: + + ```ruby + selinux_boolean 'ssh_keysign' do + value true + end + ``` + + **Set ssh_sysadm_login to 'on'**: + + ```ruby + selinux_boolean 'ssh_sysadm_login' do + value 'on' + end + ``` diff --git a/data/infra/resources/selinux_fcontext.yaml b/data/infra/resources/selinux_fcontext.yaml new file mode 100644 index 0000000..d867174 --- /dev/null +++ b/data/infra/resources/selinux_fcontext.yaml @@ -0,0 +1,77 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: selinux_fcontext +resource_description_list: +- markdown: Use the **selinux_fcontext** resource to set the SELinux context of files + using the `semanage fcontext` command. +resource_new_in: '18.0' +syntax_full_code_block: |- + selinux_fcontext 'name' do + file_spec String # default value: 'name' unless specified + file_type String # default value: "a" + secontext String + action Symbol # defaults to :manage if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`selinux_fcontext` 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." +- "`file_spec`, `file_type`, and `secontext` are the properties available to this + resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :manage: + markdown: Assign the file to the right context regardless of previous state. (default) + :addormodify: + markdown: Assign the file context if not set. Update the file context if previously + set. + :add: + markdown: Assign the file context if not set. + :modify: + markdown: Update the file context if previously set. + :delete: + markdown: 'Removes the file context if set. ' +properties_list: +- property: file_spec + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: Path to or regex matching the files or directories to label. +- property: file_type + ruby_type: String + required: false + default_value: a + allowed_values: '"a", "b", "c", "d", "f", "l", "p", "s"' + description_list: + - markdown: The type of the file being labeled. +- property: secontext + ruby_type: String + 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**: + + ```ruby + selinux_fcontext '/var/www/moodle(/.*)?' do + secontext 'httpd_sys_rw_content_t' + end + ``` + + **Adapt a symbolic link**: + + ```ruby + selinux_fcontext '/var/www/symlink_to_webroot' do + secontext 'httpd_sys_rw_content_t' + file_type 'l' + end + ``` diff --git a/data/infra/resources/selinux_install.yaml b/data/infra/resources/selinux_install.yaml new file mode 100644 index 0000000..5f6c606 --- /dev/null +++ b/data/infra/resources/selinux_install.yaml @@ -0,0 +1,62 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: selinux_install +resource_description_list: +- 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: |- + selinux_install 'name' do + packages String, Array + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`selinux_install` 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." +- "`packages` is the property available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :install: + markdown: Install required packages. (default) + :upgrade: + markdown: Upgrade required packages. + :remove: + markdown: Remove any SELinux-related packages. +properties_list: +- property: packages + ruby_type: String, Array + required: false + default_value: lazy default + description_list: + - markdown: SELinux packages for system. +target_mode: + support: full +examples: | + **Default installation**: + + ```ruby + selinux_install 'example' + ``` + + **Install with custom packages**: + + ```ruby + selinux_install 'example' do + packages %w(policycoreutils selinux-policy selinux-policy-targeted) + end + ``` + + **Uninstall** + ```ruby + selinux_install 'example' do + action :remove + end + ``` diff --git a/data/infra/resources/selinux_login.yaml b/data/infra/resources/selinux_login.yaml new file mode 100644 index 0000000..fef00bb --- /dev/null +++ b/data/infra/resources/selinux_login.yaml @@ -0,0 +1,65 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: selinux_login +resource_description_list: +- markdown: Use the **selinux_login** resource to add, update, or remove SELinux user + to OS login mappings. +resource_new_in: '18.1' +syntax_full_code_block: |- + selinux_login 'name' do + login String # default value: 'name' unless specified + range String + user String + action Symbol # defaults to :manage if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`selinux_login` 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." +- "`login`, `range`, and `user` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :manage: + markdown: Sets the SELinux login mapping to the desired settings regardless of + previous state. (default) + :add: + markdown: Creates the SELinux login mapping if not previously created. + :modify: + markdown: Updates the SELinux login mapping if previously created. + :delete: + markdown: Removes the SELinux login mapping if previously created. +properties_list: +- property: login + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the OS user login value if it differs from + the resource block's name. +- property: range + ruby_type: String + required: false + description_list: + - 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**: + + ```ruby + selinux_login 'test' do + user 'test_u' + range 's0' + end + ``` diff --git a/data/infra/resources/selinux_module.yaml b/data/infra/resources/selinux_module.yaml new file mode 100644 index 0000000..8851850 --- /dev/null +++ b/data/infra/resources/selinux_module.yaml @@ -0,0 +1,78 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: selinux_module +resource_description_list: +- 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: |- + selinux_module 'name' do + base_dir String # default value: "/etc/selinux/local" + content String + cookbook String + module_name String # default value: 'name' unless specified + source String + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`selinux_module` 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." +- "`base_dir`, `content`, `cookbook`, `module_name`, and `source` are the properties + available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Compile a module and install it. (default) + :delete: + markdown: Remove module source files from `/etc/selinux/local`. + :install: + markdown: Install a compiled module into the system. + :remove: + markdown: Remove a module from the system. +properties_list: +- property: base_dir + ruby_type: String + required: false + default_value: "/etc/selinux/local" + description_list: + - markdown: Directory to create module source file in. +- property: content + ruby_type: String + required: false + description_list: + - markdown: Module source as String. +- property: cookbook + ruby_type: String + required: false + description_list: + - 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 + description_list: + - markdown: Override the module name. +- property: source + ruby_type: String + required: false + description_list: + - markdown: Module source file name. +target_mode: + support: full +examples: | + **Creating SElinux module from .te file located at `files` directory of your cookbook.**: + + ```ruby + selinux_module 'my_policy_module' do + source 'my_policy_module.te' + action :create + end + ``` diff --git a/data/infra/resources/selinux_permissive.yaml b/data/infra/resources/selinux_permissive.yaml new file mode 100644 index 0000000..a762b83 --- /dev/null +++ b/data/infra/resources/selinux_permissive.yaml @@ -0,0 +1,47 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: selinux_permissive +resource_description_list: +- markdown: Use the **selinux_permissive** resource to allow some domains to misbehave + without stopping them. This is not as good as setting specific policies, but better + than disabling SELinux entirely. +resource_new_in: '18.0' +syntax_full_code_block: |- + selinux_permissive 'name' do + context String # default value: 'name' unless specified + action Symbol # defaults to :add if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`selinux_permissive` 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." +- "`context` is the property available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :add: + markdown: Add a permissive, unless already set. (default) + :delete: + markdown: Remove a permissive, if set. +properties_list: +- property: context + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: The SELinux context to permit. +target_mode: + support: full +examples: | + **Disable enforcement on Apache**: + + ```ruby + selinux_permissive 'httpd_t' do + notifies :restart, 'service[httpd]' + end + ``` diff --git a/data/infra/resources/selinux_port.yaml b/data/infra/resources/selinux_port.yaml new file mode 100644 index 0000000..aea73d6 --- /dev/null +++ b/data/infra/resources/selinux_port.yaml @@ -0,0 +1,67 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: selinux_port +resource_description_list: +- markdown: Use the **selinux_port** resource to assign a network port to a specific + SELinux context. For example, running a web server on a non-standard port. +resource_new_in: '18.0' +syntax_full_code_block: |- + selinux_port 'name' do + port Integer, String # default value: 'name' unless specified + protocol String + secontext String + action Symbol # defaults to :manage if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`selinux_port` 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." +- "`port`, `protocol`, and `secontext` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :manage: + markdown: Assign the port to the right context regardless of previous state. (default) + :addormodify: + markdown: Assigns the port context if not set. Updates the port context if previously + set. + :add: + markdown: Assign the port context if not set. + :modify: + markdown: Update the port context if previously set. + :delete: + markdown: Removes the port context if set. +properties_list: +- property: port + ruby_type: Integer, String + required: false + default_value: The resource block's name + description_list: + - markdown: Port to modify. +- property: protocol + ruby_type: String + required: true + allowed_values: '"tcp", "udp"' + description_list: + - markdown: Protocol to modify. +- property: secontext + ruby_type: String + required: true + description_list: + - markdown: SELinux context to assign to the port. +target_mode: + support: full +examples: | + **Allow nginx/apache to bind to port 5678 by giving it the http_port_t context**: + + ```ruby + selinux_port '5678' do + protocol 'tcp' + secontext 'http_port_t' + end + ``` diff --git a/data/infra/resources/selinux_state.yaml b/data/infra/resources/selinux_state.yaml new file mode 100644 index 0000000..31e5f71 --- /dev/null +++ b/data/infra/resources/selinux_state.yaml @@ -0,0 +1,88 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: selinux_state +resource_description_list: +- 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' +syntax_full_code_block: |- + selinux_state 'name' do + automatic_reboot true, false, Symbol # default value: false + config_file String # default value: "/etc/selinux/config" + persistent true, false # default value: true + policy String + action Symbol # defaults to :enforcing if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`selinux_state` 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." +- "`automatic_reboot`, `config_file`, `persistent`, and `policy` are the properties + available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :enforcing: + markdown: Set the SELinux state to enforcing. (default) + :permissive: + markdown: Set the SELinux state to permissive. + :disabled: + markdown: 'Set the SELinux state to disabled. **NOTE**: Switching to or from disabled + requires a reboot!' +properties_list: +- property: automatic_reboot + ruby_type: true, false, Symbol + required: false + default_value: 'false' + description_list: + - markdown: Perform an automatic node reboot if required for state change. +- property: config_file + ruby_type: String + required: false + default_value: "/etc/selinux/config" + description_list: + - markdown: Path to SELinux config file on disk. +- property: persistent + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Set the status update in the SELinux configuration file. +- property: policy + ruby_type: String + required: false + default_value: lazy default + allowed_values: '"default", "minimum", "mls", "src", "strict", "targeted"' + description_list: + - markdown: SELinux policy type. +target_mode: + support: full +examples: | + **Set SELinux state to permissive**: + + ```ruby + selinux_state 'permissive' do + action :permissive + end + ``` + + **Set SELinux state to enforcing**: + + ```ruby + selinux_state 'enforcing' do + action :enforcing + end + ``` + + **Set SELinux state to disabled**: + ```ruby + selinux_state 'disabled' do + action :disabled + end + ``` diff --git a/data/infra/resources/selinux_user.yaml b/data/infra/resources/selinux_user.yaml new file mode 100644 index 0000000..3ea5ad4 --- /dev/null +++ b/data/infra/resources/selinux_user.yaml @@ -0,0 +1,71 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: selinux_user +resource_description_list: +- markdown: Use the **selinux_user** resource to add, update, or remove SELinux users. +resource_new_in: '18.1' +syntax_full_code_block: |- + selinux_user 'name' do + level String + range String + roles Array + user String # default value: 'name' unless specified + action Symbol # defaults to :manage if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`selinux_user` 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`, `range`, `roles`, and `user` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :manage: + markdown: Sets the SELinux user to the desired settings regardless of previous + state. (default) + :add: + markdown: Creates the SELinux user if not previously created. + :modify: + markdown: Updates the SELinux user if previously created. + :delete: + markdown: Removes the SELinux user if previously created. +properties_list: +- property: level + ruby_type: String + required: false + description_list: + - markdown: MLS/MCS security level for the SELinux user. +- property: range + ruby_type: String + required: false + description_list: + - markdown: MLS/MCS security range for the SELinux user. +- property: roles + ruby_type: Array + required: false + description_list: + - markdown: Associated SELinux roles for the user. +- property: user + ruby_type: String + required: false + default_value: The resource block's name + 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: | + **Manage test_u SELinux user with a level and range of s0 and roles sysadm_r and staff_r**: + + ```ruby + selinux_user 'test_u' do + level 's0' + range 's0' + roles %w(sysadm_r staff_r) + end + ``` diff --git a/data/infra/resources/service.yaml b/data/infra/resources/service.yaml new file mode 100644 index 0000000..1ba0591 --- /dev/null +++ b/data/infra/resources/service.yaml @@ -0,0 +1,292 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: service +resource_description_list: +- markdown: Use the **service** resource to manage a service. +syntax_full_code_block: |- + service 'name' do + init_command String + options Array, String + parameters Hash + pattern String + priority Integer, String, Hash + reload_command String, false + restart_command String, false + run_levels Array + service_name String # default value: 'name' unless specified + start_command String, false + status_command String, false + stop_command String, false + supports Hash # default value: {"restart"=>nil, "reload"=>nil, "status"=>nil} + timeout Integer # default value: 900 + user String + action Symbol # defaults to :nothing if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`service` 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." +- "`init_command`, `options`, `parameters`, `pattern`, `priority`, `reload_command`, + `restart_command`, `run_levels`, `service_name`, `start_command`, `status_command`, + `stop_command`, `supports`, `timeout`, and `user` are the properties available to + this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :enable: + markdown: Enable a service at boot. This action is equivalent to an `Automatic` + startup type on the Microsoft Windows platform. This action is not supported + when using System Resource Controller (SRC) on the AIX platform because System + Resource Controller (SRC) does not have a standard mechanism for enabling and + disabling services on system boot. + :disable: + markdown: Disable a service. This action is equivalent to a `Disabled` startup + type on the Microsoft Windows platform. This action is not supported when using + System Resource Controller (SRC) on the AIX platform because System Resource + Controller (SRC) does not have a standard mechanism for enabling and disabling + services on system boot. + :start: + 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 + 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: 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 + description_list: + - markdown: The command used to tell a service to reload its configuration. +- property: restart_command + ruby_type: String, false + required: false + description_list: + - markdown: The command used to restart a service. +- 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 + default_value: The resource block's name + description_list: + - markdown: An optional property to set the service name if it differs from the + resource block's name. +- property: start_command + ruby_type: String, false + required: false + description_list: + - markdown: The command used to start a service. +- property: status_command + ruby_type: String, false + required: false + description_list: + - markdown: The command used to check the run status for a service. +- property: stop_command + ruby_type: String, false + required: false + description_list: + - markdown: The command used to stop a service. +- property: supports + ruby_type: Hash + 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, + 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: '900' + 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: + 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\ + \ service 'example_service' do\n supports status: true, restart: true, reload:\ + \ true\n action [ :enable, :start ]\n end\n ```\n\n Use a pattern\n\n ```\ + \ ruby\n service 'samba' do\n pattern 'smbd'\n action [:enable, :start]\n\ + \ end\n ```\n\n Use the :nothing common action\n\n ```ruby\n service 'memcached'\ + \ do\n action :nothing\n end\n ```\n\n Use the retries common attribute\n\n\ + \ ```ruby\n service 'apache' do\n action [ :enable, :start ]\n retries\ + \ 3\n end\n ```\n\n Manage a service, depending on the node platform\n\n ```\ + \ ruby\n service 'example_service' do\n if redhat?\n service_name 'redhat_name'\n\ + \ else\n service_name 'other_name'\n end\n supports restart: true\n\ + \ action [ :enable, :start ]\n end\n ```\n\n Reload a service using a template\n\ + \n To reload a service that is based on a template, use the **template**\n and\ + \ **service** resources together in the same recipe, similar to the\n following:\n\ + \n ```ruby\n template '/tmp/somefile' do\n mode '0755'\n source 'somefile.erb'\n\ + \ end\n\n service 'apache' do\n action :enable\n subscribes :reload, 'template[/tmp/somefile]',\ + \ :immediately\n end\n ```\n\n where the `subscribes` notification is used to\ + \ reload the service\n whenever the template is modified.\n\n Enable a service\ + \ after a restart or reload\n\n ```ruby\n service 'apache' do\n supports restart:\ + \ true, reload: true\n action :enable\n end\n ```\n\n Set an IP address using\ + \ variables and a template\n\n The following example shows how the **template**\ + \ resource can be used in\n a recipe to combine settings stored in an attributes\ + \ file, variables\n within a recipe, and a template to set the IP addresses that\ + \ are used by\n the Nginx service. The attributes file contains the following:\n\ + \n ```ruby\n default['nginx']['dir'] = '/etc/nginx'\n ```\n\n The recipe then\ + \ does the following to:\n\n - Declare two variables at the beginning of the\ + \ recipe, one for the\n remote IP address and the other for the authorized\ + \ IP address\n - Use the **service** resource to restart and reload the Nginx\ + \ service\n - Load a template named `authorized_ip.erb` from the `/templates`\n\ + \ directory that is used to set the IP address values based on the\n variables\ + \ specified in the recipe\n\n \n\n ```ruby\n node.default['nginx']['remote_ip_var']\ + \ = 'remote_addr'\n node.default['nginx']['authorized_ips'] = ['127.0.0.1/32']\n\ + \n service 'nginx' do\n supports :status => true, :restart => true, :reload\ + \ => true\n end\n\n template 'authorized_ip' do\n path \"#{node['nginx']['dir']}/authorized_ip\"\ + \n source 'modules/authorized_ip.erb'\n owner 'root'\n group 'root'\n \ + \ mode '0755'\n variables(\n :remote_ip_var => node['nginx']['remote_ip_var'],\n\ + \ :authorized_ips => node['nginx']['authorized_ips']\n )\n\n notifies\ + \ :reload, 'service[nginx]', :immediately\n end\n ```\n\n where the `variables`\ + \ property tells the template to use the variables\n set at the beginning of the\ + \ recipe and the `source` property is used to\n call a template file located in\ + \ the cookbook's `/templates` directory.\n The template file looks similar to:\n\ + \n ```ruby\n geo $<%= @remote_ip_var %> $authorized_ip {\n default no;\n \ + \ <% @authorized_ips.each do |ip| %>\n <%= \"#{ip} yes;\" %>\n <% end %>\n\ + \ }\n ```\n\n Use a cron timer to manage a service\n\n The following example\ + \ shows how to install the crond application using\n two resources and a variable:\n\ + \n ```ruby\n # the following code sample comes from the ``cron`` cookbook:\n\ + \ # https://github.com/chef-cookbooks/cron\n\n cron_package = case node['platform']\n\ + \ when 'redhat', 'centos', 'scientific', 'fedora', 'amazon'\n node['platform_version'].to_f\ + \ >= 6.0 ? 'cronie' : 'vixie-cron'\n else\n 'cron'\n end\n\n package\ + \ cron_package do\n action :install\n end\n\n service 'crond' do\n case\ + \ node['platform']\n when 'redhat', 'centos', 'scientific', 'fedora', 'amazon'\n\ + \ service_name 'crond'\n when 'debian', 'ubuntu', 'suse'\n service_name\ + \ 'cron'\n end\n action [:start, :enable]\n end\n ```\n\n where\n\n -\ + \ `cron_package` is a variable that is used to identify which\n platforms\ + \ apply to which install packages\n - the **package** resource uses the `cron_package`\ + \ variable to\n determine how to install the crond application on various nodes\n\ + \ (with various platforms)\n - the **service** resource enables the crond\ + \ application on nodes that\n have Red Hat, CentOS, Red Hat Enterprise Linux,\ + \ Fedora, or Amazon\n Web Services (AWS), and the cron service on nodes that\ + \ run Debian,\n Ubuntu, or openSUSE\n\n Restart a service, and then notify\ + \ a different service\n\n The following example shows how start a service named\ + \ `example_service`\n and immediately notify the Nginx service to restart.\n\n\ + \ ```ruby\n service 'example_service' do\n action :start\n notifies :restart,\ + \ 'service[nginx]', :immediately\n end\n ```\n\n Restart one service before restarting\ + \ another\n\n This example uses the `:before` notification to restart the `php-fpm`\n\ + \ service before restarting `nginx`:\n\n ```ruby\n service 'nginx' do\n action\ + \ :restart\n notifies :restart, 'service[php-fpm]', :before\n end\n ```\n\n\ + \ With the `:before` notification, the action specified for the `nginx`\n resource\ + \ will not run until action has been taken on the notified\n resource (`php-fpm`).\n\ + \n Stop a service, do stuff, and then restart it\n\n The following example shows\ + \ how to use the **execute**, **service**, and\n **mount** resources together to\ + \ ensure that a node running on Amazon EC2\n is running MySQL. This example does\ + \ the following:\n\n - Checks to see if the Amazon EC2 node has MySQL\n - \ + \ If the node has MySQL, stops MySQL\n - Installs MySQL\n - Mounts the node\n\ + \ - Restarts MySQL\n\n \n\n ```ruby\n # the following code sample\ + \ comes from the ``server_ec2``\n # recipe in the following cookbook:\n # https://github.com/chef-cookbooks/mysql\n\ + \n if (node.attribute?('ec2') && ! FileTest.directory?(node['mysql']['ec2_path']))\n\ + \n service 'mysql' do\n action :stop\n end\n\n execute 'install-mysql'\ + \ do\n command \"mv #{node['mysql']['data_dir']} #{node['mysql']['ec2_path']}\"\ + \n not_if do FileTest.directory?(node['mysql']['ec2_path']) end\n end\n\n\ + \ [node['mysql']['ec2_path'], node['mysql']['data_dir']].each do |dir|\n \ + \ directory dir do\n owner 'mysql'\n group 'mysql'\n end\n \ + \ end\n\n mount node['mysql']['data_dir'] do\n device node['mysql']['ec2_path']\n\ + \ fstype 'none'\n options 'bind,rw'\n action [:mount, :enable]\n\ + \ end\n\n service 'mysql' do\n action :start\n end\n\n end\n ```\n\ + \n where\n\n - the two **service** resources are used to stop, and then restart\ + \ the\n MySQL service\n - the **execute** resource is used to install MySQL\n\ + \ - the **mount** resource is used to mount the node and enable MySQL\n\n Control\ + \ a service using the execute resource\n\n
Warning

\n\n This is an example of something that should NOT be done. Use the\n **service**\ + \ resource to control a service, not the **execute** resource.\n\n
\n\ + \n Do something like this:\n\n ```ruby\n service 'tomcat' do\n action :start\n\ + \ end\n ```\n\n and NOT something like this:\n\n ```ruby\n execute 'start-tomcat'\ + \ do\n command '/etc/init.d/tomcat6 start'\n action :run\n end\n ```\n\n\ + \ There is no reason to use the **execute** resource to control a service\n because\ + \ the **service** resource exposes the `start_command` property\n directly, which\ + \ gives a recipe full control over the command issued in a\n much cleaner, more\ + \ direct manner.\n\n Enable a service on AIX using the mkitab command\n\n The\ + \ **service** resource does not support using the `:enable` and\n `:disable` actions\ + \ with resources that are managed using System Resource\n Controller (SRC). This\ + \ is because System Resource Controller (SRC) does\n not have a standard mechanism\ + \ for enabling and disabling services on\n system boot.\n\n One approach for enabling\ + \ or disabling services that are managed by\n System Resource Controller (SRC)\ + \ is to use the **execute** resource to\n invoke `mkitab`, and then use that command\ + \ to enable or disable the\n service.\n\n The following example shows how to install\ + \ a service:\n\n ```ruby\n execute \"install #{node['chef_client']['svc_name']}\ + \ in SRC\" do\n command \"mkssys -s #{node['chef_client']['svc_name']}\n \ + \ -p #{node['chef_client']['bin']}\n -u root\n\ + \ -S\n -n 15\n -f 9\n \ + \ -o #{node['chef_client']['log_dir']}/client.log\n \ + \ -e #{node['chef_client']['log_dir']}/client.log -a '\n \ + \ -i #{node['chef_client']['interval']}\n -s #{node['chef_client']['splay']}'\"\ + \n not_if \"lssrc -s #{node['chef_client']['svc_name']}\"\n action :run\n\ + \ end\n ```\n\n and then enable it using the `mkitab` command:\n\n ```ruby\n\ + \ execute \"enable #{node['chef_client']['svc_name']}\" do\n command \"mkitab\ + \ '#{node['chef_client']['svc_name']}:2:once:/usr/bin/startsrc\n \ + \ -s #{node['chef_client']['svc_name']} > /dev/console 2>&1'\"\n not_if \"\ + lsitab #{node['chef_client']['svc_name']}\"\n end\n ```\n" diff --git a/data/infra/resources/smartos_package.yaml b/data/infra/resources/smartos_package.yaml new file mode 100644 index 0000000..a77a12f --- /dev/null +++ b/data/infra/resources/smartos_package.yaml @@ -0,0 +1,84 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: smartos_package +resource_description_list: +- markdown: Use the **smartos_package** resource to manage packages for the SmartOS + platform. +- notes_resource_based_on_package: true +syntax_full_code_block: |- + smartos_package 'name' do + environment Hash + options String, Array + package_name String + source String + timeout String, Integer + version String + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`smartos_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: 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 + description_list: + - markdown: One (or more) additional command options that are passed to the command. +- property: package_name + ruby_type: String + required: false + description_list: + - 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: The optional path to a package on the local file system. +- property: timeout + ruby_type: String, Integer + required: false + description_list: + - markdown: The amount of time (in seconds) to wait before timing out. +- property: version + ruby_type: String + 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 new file mode 100644 index 0000000..b30b61e --- /dev/null +++ b/data/infra/resources/snap_package.yaml @@ -0,0 +1,124 @@ +--- +resource_reference: true +multi_package_resource: true +resources_common_guards: true +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 supported + Linux distributions. +resource_new_in: '15.0' +syntax_full_code_block: |- + snap_package 'name' do + channel String # default value: "latest/stable" + environment Hash + options String, Array + package_name String, Array + source String + timeout String, Integer + version String, Array + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`snap_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." +- "`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. + :reconfig: + markdown: + :lock: + markdown: + :unlock: + markdown: +properties_list: +- property: channel + ruby_type: String + required: false + default_value: latest/stable + description_list: + - 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 + description_list: + - 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: 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: The optional path to a package on the local file system. +- property: timeout + ruby_type: String, Integer + required: false + description_list: + - markdown: The amount of time (in seconds) to wait before timing out. +- property: version + ruby_type: String, Array + required: false + description_list: + - markdown: The version of a package to be installed or upgraded. +target_mode: + support: full +examples: | + **Install a package** + + ```ruby + snap_package 'hello' + ``` + + **Upgrade a package** + + ```ruby + snap_package 'hello' do + action :upgrade + 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 + snap_package 'hello' do + options 'classic' + end + ``` diff --git a/data/infra/resources/solaris_package.yaml b/data/infra/resources/solaris_package.yaml new file mode 100644 index 0000000..d315ce4 --- /dev/null +++ b/data/infra/resources/solaris_package.yaml @@ -0,0 +1,86 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: solaris_package +resource_description_list: +- markdown: Use the **solaris_package** resource to manage packages on the Solaris + platform. +syntax_full_code_block: |- + solaris_package 'name' do + environment Hash + options String, Array + package_name String + source String + timeout String, Integer + version String + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`solaris_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: 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 + description_list: + - markdown: One (or more) additional command options that are passed to the command. +- property: package_name + ruby_type: String + required: false + description_list: + - 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: The optional path to a package on the local file system. +- property: timeout + ruby_type: String, Integer + required: false + description_list: + - markdown: The amount of time (in seconds) to wait before timing out. +- property: version + ruby_type: String + 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 new file mode 100644 index 0000000..3122c40 --- /dev/null +++ b/data/infra/resources/ssh_known_hosts_entry.yaml @@ -0,0 +1,120 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: ssh_known_hosts_entry +resource_description_list: +- markdown: Use the **ssh_known_hosts_entry** resource to add an entry for the specified + host in /etc/ssh/ssh_known_hosts or a user's known hosts file if specified. +resource_new_in: '14.3' +syntax_full_code_block: |- + ssh_known_hosts_entry 'name' do + file_location String # default value: "/etc/ssh/ssh_known_hosts" + group String, Integer # default value: The root user's group depending on platform. + hash_entries true, false # default value: false + host String # default value: 'name' unless specified + key String + key_type String # default value: "rsa" + mode String # default value: "0644" + owner String, Integer # default value: "root" + port Integer # default value: 22 + timeout Integer # default value: 30 + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`ssh_known_hosts_entry` 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." +- "`file_location`, `group`, `hash_entries`, `host`, `key`, `key_type`, `mode`, `owner`, + `port`, and `timeout` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Create an entry in the ssh_known_hosts file. (default) + :flush: + markdown: Immediately flush the entries to the config file. Without this the actual + writing of the file is delayed in the Chef Infra Client run so all entries can + be accumulated before writing the file out. +properties_list: +- property: file_location + ruby_type: String + required: false + default_value: "/etc/ssh/ssh_known_hosts" + description_list: + - markdown: The location of the ssh known hosts file. Change this to set a known + host file for a particular user. +- property: group + ruby_type: String, Integer + required: false + default_value: The root user's group depending on platform. + description_list: + - markdown: The file group for the ssh_known_hosts file. +- property: hash_entries + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Hash the hostname and addresses in the ssh_known_hosts file for privacy. +- property: host + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: The host to add to the known hosts file. +- property: key + ruby_type: String + required: false + description_list: + - markdown: An optional key for the host. If not provided this will be automatically + determined. +- property: key_type + ruby_type: String + required: false + default_value: rsa + description_list: + - markdown: The type of key to store. +- property: mode + ruby_type: String + required: false + default_value: '0644' + description_list: + - markdown: The file mode for the ssh_known_hosts file. +- property: owner + ruby_type: String, Integer + required: false + default_value: root + description_list: + - markdown: The file owner for the ssh_known_hosts file. +- property: port + ruby_type: Integer + required: false + default_value: '22' + description_list: + - markdown: The server port that the ssh-keyscan command will use to gather the + public key. +- property: timeout + ruby_type: Integer + required: false + 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** + + ```ruby + ssh_known_hosts_entry 'github.com' + ``` + + **Add a single entry with your own provided key** + + ```ruby + ssh_known_hosts_entry 'github.com' do + key 'node.example.com ssh-rsa ...' + end + ``` diff --git a/data/infra/resources/subversion.yaml b/data/infra/resources/subversion.yaml new file mode 100644 index 0000000..593119e --- /dev/null +++ b/data/infra/resources/subversion.yaml @@ -0,0 +1,140 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: subversion +resource_description_list: +- markdown: Use the **subversion** resource to manage source control resources that + exist in a Subversion repository. +- warning: + markdown: The subversion resource has known bugs and may not work as expected. + For more information see Chef GitHub issues, particularly [#4050](https://github.com/chef/chef/issues/4050) + and [#4257](https://github.com/chef/chef/issues/4257). +syntax_full_code_block: |- + subversion 'name' do + destination String # default value: 'name' unless specified + environment Hash + group String, Integer + repository String + revision String # default value: "HEAD" + svn_arguments String, false # default value: "--no-auth-cache" + svn_binary String + svn_info_args String, false # default value: "--no-auth-cache" + svn_password String + svn_username String + timeout Integer + user String, Integer + action Symbol # defaults to :sync if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`subversion` 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." +- "`destination`, `environment`, `group`, `repository`, `revision`, `svn_arguments`, + `svn_binary`, `svn_info_args`, `svn_password`, `svn_username`, `timeout`, and `user` + are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :sync: + markdown: Update the source to the specified version, or get a new clone or checkout. + This action causes a hard reset of the index and working tree, discarding any + uncommitted changes. (default) + :checkout: + markdown: Clone or check out the source. When a checkout is available, this provider + 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 + it exists). +properties_list: +- property: destination + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: 'The location path to which the source is to be cloned, checked out, + or exported. Default value: the name of the resource block.' +- property: environment + ruby_type: Hash + required: false + description_list: + - markdown: A Hash of environment variables in the form of ({'ENV_VARIABLE' => 'VALUE'}). +- property: group + ruby_type: String, Integer + required: false + description_list: + - markdown: The system group that will own the checked-out code. +- property: repository + ruby_type: String + required: false + description_list: + - markdown: The URI of the code repository. +- property: revision + ruby_type: String + required: false + default_value: HEAD + description_list: + - markdown: The revision to checkout. +- property: svn_arguments + ruby_type: String, false + required: false + default_value: "--no-auth-cache" + description_list: + - markdown: The extra arguments that are passed to the Subversion command. +- property: svn_binary + ruby_type: String + required: false + description_list: + - markdown: The location of the svn binary. +- property: svn_info_args + ruby_type: String, false + required: false + default_value: "--no-auth-cache" + description_list: + - markdown: Use when the `svn info` command is used by Chef Infra Client and arguments + need to be passed. The `svn_arguments` command does not work when the `svn info` + command is used. +- property: svn_password + ruby_type: String + required: false + description_list: + - markdown: The password for a user that has access to the Subversion repository. +- property: svn_username + ruby_type: String + required: false + description_list: + - markdown: The user name for a user that has access to the Subversion repository. +- property: timeout + ruby_type: Integer + required: false + description_list: + - 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: | + **Get the latest version of an application** + + ```ruby + subversion 'CouchDB Edge' do + repository 'http://svn.apache.org/repos/asf/couchdb/trunk' + revision 'HEAD' + destination '/opt/my_sources/couch' + action :sync + end + ``` diff --git a/data/infra/resources/sudo.yaml b/data/infra/resources/sudo.yaml new file mode 100644 index 0000000..0fb1543 --- /dev/null +++ b/data/infra/resources/sudo.yaml @@ -0,0 +1,220 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: sudo +resource_description_list: +- markdown: Use the **sudo** resource to add or remove individual sudo entries using + sudoers.d files. Sudo version 1.7.2 or newer is required to use the sudo resource, + as it relies on the `#includedir` directive introduced in version 1.7.2. This + resource does not enforce installation of the required sudo version. Chef-supported + releases of Ubuntu, SuSE, Debian, and RHEL (6+) all support this feature. +resource_new_in: '14.0' +syntax_full_code_block: |- + sudo 'name' do + command_aliases Array # default value: [] + commands Array # default value: ["ALL"] + config_prefix String # default value: "Prefix values based on the node's platform" + defaults Array # default value: [] + env_keep_add Array # default value: [] + env_keep_subtract Array # default value: [] + filename String # default value: 'name' unless specified + groups String, Array # default value: [] + host String # default value: "ALL" + noexec true, false # default value: false + nopasswd true, false # default value: false + runas String # default value: "ALL" + setenv true, false # default value: false + template String + users String, Array # default value: [] + variables Hash + visudo_binary String # default value: "/usr/sbin/visudo" + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`sudo` 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." +- "`command_aliases`, `commands`, `config_prefix`, `defaults`, `env_keep_add`, `env_keep_subtract`, + `filename`, `groups`, `host`, `noexec`, `nopasswd`, `runas`, `setenv`, `template`, + `users`, `variables`, and `visudo_binary` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :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: +- property: command_aliases + ruby_type: Array + required: false + default_value: "[]" + description_list: + - 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 and/or command aliases this sudoer + can execute. +- property: config_prefix + ruby_type: String + required: false + default_value: Prefix values based on the node's platform + description_list: + - markdown: The directory that contains the sudoers configuration file. +- property: defaults + ruby_type: Array + required: false + default_value: "[]" + description_list: + - markdown: An array of defaults for the user/group. +- property: env_keep_add + ruby_type: Array + required: false + default_value: "[]" + description_list: + - markdown: An array of strings to add to `env_keep`. +- property: env_keep_subtract + ruby_type: Array + required: false + default_value: "[]" + description_list: + - markdown: An array of strings to remove from `env_keep`. +- property: filename + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: The name of the sudoers.d file if it differs from the name of the resource + block +- property: groups + ruby_type: String, Array + required: false + default_value: "[]" + description_list: + - markdown: Group(s) to provide sudo privileges to. This property accepts either + an array or a comma separated list. Leading % on group names is optional. +- property: host + ruby_type: String + required: false + default_value: ALL + description_list: + - markdown: The host to set in the sudo configuration. +- property: noexec + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Prevent commands from shelling out. +- property: nopasswd + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Allow sudo to be run without specifying a password. +- property: runas + ruby_type: String + required: false + default_value: ALL + description_list: + - markdown: User that the command(s) can be run as. +- property: setenv + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Determines whether or not to permit preservation of the environment + with `sudo -E`. +- property: template + ruby_type: String + required: false + description_list: + - markdown: The name of the erb template in your cookbook, if you wish to supply + your own template. +- property: users + ruby_type: String, Array + required: false + default_value: "[]" + description_list: + - markdown: User(s) to provide sudo privileges to. This property accepts either + an array or a comma separated list. +- property: variables + ruby_type: Hash + required: false + description_list: + - markdown: The variables to pass to the custom template. This property is ignored + if not using a custom template. +- property: visudo_binary + ruby_type: String + required: false + 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** + + ```ruby + sudo 'admin' do + user 'admin' + end + ``` + + **Grant a user and groups sudo privileges for any command** + + ```ruby + sudo 'admins' do + users 'bob' + groups 'sysadmins, superusers' + end + ``` + + **Grant passwordless sudo privileges for specific commands** + + ```ruby + sudo 'passwordless-access' do + commands ['/bin/systemctl restart httpd', '/bin/systemctl restart mysql'] + nopasswd true + end + ``` + + **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 new file mode 100644 index 0000000..719a330 --- /dev/null +++ b/data/infra/resources/swap_file.yaml @@ -0,0 +1,82 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: swap_file +resource_description_list: +- markdown: Use the **swap_file** resource to create or delete swap files on Linux + systems, and optionally to manage the swappiness configuration for a host. +resource_new_in: '14.0' +syntax_full_code_block: |- + swap_file 'name' do + path String # default value: 'name' unless specified + persist true, false # default value: false + size Integer + swappiness Integer + timeout Integer # default value: 600 + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`swap_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." +- "`path`, `persist`, `size`, `swappiness`, and `timeout` are the properties available + to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Create a swapfile. (default) + :remove: + markdown: Remove a swapfile and disable swap. +properties_list: +- property: path + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: The path where the swap file will be created on the system if it differs + from the resource block's name. +- property: persist + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Persist the swapon. +- property: size + ruby_type: Integer + required: false + description_list: + - markdown: The size (in MBs) of the swap file. +- property: swappiness + ruby_type: Integer + required: false + description_list: + - markdown: The swappiness value to set on the system. +- property: timeout + ruby_type: Integer + required: false + default_value: '600' + description_list: + - markdown: Timeout for `dd` / `fallocate` commands. +target_mode: + support: full +examples: | + **Create a swap file** + + ```ruby + swap_file '/dev/sda1' do + size 1024 + end + ``` + + **Remove a swap file** + + ```ruby + swap_file '/dev/sda1' do + action :remove + end + ``` diff --git a/data/infra/resources/sysctl.yaml b/data/infra/resources/sysctl.yaml new file mode 100644 index 0000000..d87cf8a --- /dev/null +++ b/data/infra/resources/sysctl.yaml @@ -0,0 +1,128 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: sysctl +resource_description_list: +- markdown: Use the **sysctl** resource to set or remove kernel parameters using the + `sysctl` command line tool and configuration files in the system's `sysctl.d` + directory. Configuration files managed by this resource are named `99-chef-KEYNAME.conf`. +resource_new_in: '14.0' +syntax_full_code_block: |- + sysctl 'name' do + comment Array, String # default value: [] + conf_dir String # default value: "/etc/sysctl.d" + ignore_error true, false # default value: false + key String # default value: 'name' unless specified + value Array, String, Integer, Float + action Symbol # defaults to :apply if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`sysctl` 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." +- "`comment`, `conf_dir`, `ignore_error`, `key`, and `value` are the properties available + to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :apply: + markdown: Set the kernel parameter and update the `sysctl` settings. (default) + :remove: + markdown: Remove the kernel parameter and update the `sysctl` settings. +properties_list: +- property: comment + ruby_type: Array, String + required: false + default_value: "[]" + new_in: '15.8' + description_list: + - markdown: Comments, placed above the resource setting in the generated file. For + multi-line comments, use an array of strings, one per line. +- property: conf_dir + ruby_type: String + required: false + default_value: "/etc/sysctl.d" + description_list: + - markdown: The configuration directory to write the config to. +- property: ignore_error + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Ignore any errors when setting the value on the command line. +- property: key + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: The kernel parameter key in dotted format if it differs from the resource + block's name. +- property: value + ruby_type: Array, String, Integer, Float + required: true + description_list: + - markdown: The value to set. +target_mode: + support: full +examples: | + **Set vm.swappiness**: + + ```ruby + sysctl 'vm.swappiness' do + value 19 + end + ``` + + **Remove kernel.msgmax**: + + **Note**: This only removes the sysctl.d config for kernel.msgmax. The value will be set back to the kernel default value. + + ```ruby + sysctl 'kernel.msgmax' do + action :remove + end + ``` + + **Adding Comments to sysctl configuration files**: + + ```ruby + sysctl 'vm.swappiness' do + value 19 + comment "define how aggressively the kernel will swap memory pages." + end + ``` + + This produces /etc/sysctl.d/99-chef-vm.swappiness.conf as follows: + + ``` + # define how aggressively the kernel will swap memory pages. + vm.swappiness = 1 + ``` + + **Converting sysctl settings from shell scripts**: + + Example of existing settings: + + ```bash + fs.aio-max-nr = 1048576 net.ipv4.ip_local_port_range = 9000 65500 kernel.sem = 250 32000 100 128 + ``` + + Converted to sysctl resources: + + ```ruby + sysctl 'fs.aio-max-nr' do + value '1048576' + end + + sysctl 'net.ipv4.ip_local_port_range' do + value '9000 65500' + end + + sysctl 'kernel.sem' do + value '250 32000 100 128' + end + ``` diff --git a/data/infra/resources/systemd_unit.yaml b/data/infra/resources/systemd_unit.yaml new file mode 100644 index 0000000..f9e5ed0 --- /dev/null +++ b/data/infra/resources/systemd_unit.yaml @@ -0,0 +1,152 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +unit_file_verification: true +resource: systemd_unit +resource_description_list: +- markdown: Use the **systemd_unit** resource to create, manage, and run [systemd + units](https://www.freedesktop.org/software/systemd/man/systemd.html#Concepts). +resource_new_in: '12.11' +syntax_full_code_block: |- + systemd_unit 'name' do + content String, Hash + triggers_reload true, false # default value: true + unit_name String # default value: 'name' unless specified + user String + verify true, false # default value: true + action Symbol # defaults to :nothing if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`systemd_unit` 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." +- "`content`, `triggers_reload`, `unit_name`, `user`, and `verify` are the properties + available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Create a systemd unit file, if it does not already exist. + :delete: + markdown: Delete a systemd unit file, if it exists. + :preset: + markdown: Restore the preset '`enable`/`disable`' configuration for a systemd + unit. *New in Chef Infra Client 14.0.* + :revert: + markdown: Revert to a vendor's version of a systemd unit file. *New in Chef Infra + Client 14.0.* + :enable: + markdown: Ensure the unit will be started after the next system boot. + :disable: + markdown: Ensure the unit will not be started after the next system boot. + :reenable: + markdown: Reenable a unit file. *New in Chef Infra Client 14.0.* + :mask: + markdown: Ensure the unit will not start, even to satisfy dependencies. + :unmask: + markdown: Stop the unit from being masked and cause it to start as specified. + :start: + markdown: Start a systemd unit. + :stop: + markdown: Stop a running systemd unit. + :restart: + markdown: Restart a systemd unit. + :reload: + markdown: Reload the configuration file for a systemd unit. + :try_restart: + markdown: Try to restart a systemd unit if the unit is running. + :reload_or_restart: + markdown: For systemd units that are services, this action reloads the configuration + of the service without restarting, if possible; otherwise, it will restart the + service so the new configuration is applied. + :reload_or_try_restart: + markdown: For systemd units that are services, this action reloads the configuration + of the service without restarting, if possible; otherwise, it will try to restart + the service so the new configuration is applied. +properties_list: +- property: content + ruby_type: String, Hash + required: false + description_list: + - markdown: A string or hash that contains a systemd [unit file](https://www.freedesktop.org/software/systemd/man/systemd.unit.html) + definition that describes the properties of systemd-managed entities, such as + services, sockets, devices, and so on. In Chef Infra Client 14.4 or later, repeatable + options can be implemented with an array. +- property: triggers_reload + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Specifies whether to trigger a daemon reload when creating or deleting + a unit. +- property: unit_name + ruby_type: String + required: false + default_value: The resource block's name + new_in: '13.7' + description_list: + - markdown: The name of the unit file if it differs from the resource block's name. +- property: user + ruby_type: String + required: false + description_list: + - markdown: The user account that the systemd unit process is run under. The path + to the unit for that user would be something like '/etc/systemd/user/sshd.service'. + If no user account is specified, the systemd unit will run under a 'system' + account, with the path to the unit being something like '/etc/systemd/system/sshd.service'. +- property: verify + ruby_type: true, false + required: false + default_value: 'true' + description_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** + + ```ruby + systemd_unit 'etcd.service' do + content({ Unit: { + Description: 'Etcd', + Documentation: ['https://coreos.com/etcd', 'man:etcd(1)'], + After: 'network.target', + }, + Service: { + Type: 'notify', + ExecStart: '/usr/local/etcd', + Restart: 'always', + }, + Install: { + WantedBy: 'multi-user.target', + } }) + action [:create, :enable] + end + ``` + + **Create systemd service unit file from a String** + + ```ruby + systemd_unit 'sysstat-collect.timer' do + content <<~EOU + [Unit] + Description=Run system activity accounting tool every 10 minutes + + [Timer] + OnCalendar=*:00/10 + + [Install] + WantedBy=sysstat.service + EOU + + action [:create, :enable] + end + ``` diff --git a/data/infra/resources/template.yaml b/data/infra/resources/template.yaml new file mode 100644 index 0000000..b8af5c9 --- /dev/null +++ b/data/infra/resources/template.yaml @@ -0,0 +1,382 @@ +--- +resource_reference: true +properties_resources_common_windows_security: true +resources_common_atomic_update: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +template_requirements: true +resource: template +resource_description_list: +- shortcode: template.md +- markdown: 'Use the **template** resource to manage the contents of a file using + an Embedded Ruby (ERB) template by transferring files from a sub-directory + of `COOKBOOK_NAME/templates/` to a specified path located on a host that + is running Chef Infra Client. This resource includes actions and + properties from the **file** resource. Template files managed by the + **template** resource follow the same file specificity rules as the + **remote_file** and **file** resources.' +syntax_description: "A **template** resource block typically declares the location\ + \ in which a\nfile is to be created, the source template that will be used to create\n\ + the file, and the permissions needed on that file. For example:\n\n```ruby\ntemplate\ + \ '/etc/motd' do\n source 'motd.erb'\n owner 'root'\n group 'root'\n mode '0755'\n\ + end\n```" +syntax_properties_list: +- '`''/etc/motd''` specifies the location in which the file is created' +- '`''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 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 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. + :delete: + markdown: Delete a file. + :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. +- 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: cookbook + ruby_type: String + required: false + description_list: + - markdown: The cookbook in which a file is located (if it is not located in the + current cookbook). The default value is the current cookbook. +- 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: local + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - 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 + 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: '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: '' + 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: variables + ruby_type: Hash + required: false + default_value: "{}" + description_list: + - 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\ + \ template\n\n ```ruby\n template '/tmp/config.conf' do\n local true\n \ + \ source '/tmp/config.conf.erb'\n end\n ```\n\n Configure a file using a variable\ + \ map\n\n ```ruby\n template '/tmp/config.conf' do\n source 'config.conf.erb'\n\ + \ variables(\n :config_var => node['configs']['config_var']\n )\n end\n\ + \ ```\n\n Use the not_if condition\n\n The following example shows how to use\ + \ the `not_if` condition to create\n a file based on a template and using the presence\ + \ of an attribute value\n on the node to specify the condition:\n\n ```ruby\n\ + \ template '/tmp/somefile' do\n mode '0755'\n source 'somefile.erb'\n \ + \ not_if { node['some_value'] }\n end\n ```\n\n The following example shows how\ + \ to use the `not_if` condition to create\n a file based on a template and then\ + \ Ruby code to specify the condition:\n\n ```ruby\n template '/tmp/somefile'\ + \ do\n mode '0755'\n source 'somefile.erb'\n not_if do\n File.exist?('/etc/passwd')\n\ + \ end\n end\n ```\n\n The following example shows how to use the `not_if`\ + \ condition to create\n a file based on a template and using a Ruby block (with\ + \ curly braces) to\n specify the condition:\n\n ```ruby\n template '/tmp/somefile'\ + \ do\n mode '0755'\n source 'somefile.erb'\n not_if { File.exist?('/etc/passwd')\ + \ }\n end\n ```\n\n The following example shows how to use the `not_if` condition\ + \ to create\n a file based on a template and using a string to specify the condition:\n\ + \n ```ruby\n template '/tmp/somefile' do\n mode '0755'\n source 'somefile.erb'\n\ + \ not_if 'test -f /etc/passwd'\n end\n ```\n\n Use the only_if condition\n\ + \n The following example shows how to use the `only_if` condition to create\n \ + \ a file based on a template and using the presence of an attribute on the\n node\ + \ to specify the condition:\n\n ```ruby\n template '/tmp/somefile' do\n mode\ + \ '0755'\n source 'somefile.erb'\n only_if { node['some_value'] }\n end\n\ + \ ```\n\n The following example shows how to use the `only_if` condition to create\n\ + \ a file based on a template, and then use Ruby to specify a condition:\n\n ```\ + \ ruby\n template '/tmp/somefile' do\n mode '0755'\n source 'somefile.erb'\n\ + \ only_if { ! ::File.exist?('/etc/passwd') }\n end\n ```\n\n The following\ + \ example shows how to use the `only_if` condition to create\n a file based on\ + \ a template and using a string to specify the condition:\n\n ```ruby\n template\ + \ '/tmp/somefile' do\n mode '0755'\n source 'somefile.erb'\n only_if 'test\ + \ -f /etc/passwd'\n end\n ```\n\n Use a whitespace array (%w)\n\n The following\ + \ example shows how to use a Ruby whitespace array to define\n a list of configuration\ + \ tools, and then use that list of tools within\n the **template** resource to\ + \ ensure that all of these configuration\n tools are using the same RSA key:\n\n\ + \ ```ruby\n %w{openssl.cnf pkitool vars Rakefile}.each do |f|\n template \"\ + /etc/openvpn/easy-rsa/#{f}\" do\n source \"#{f}.erb\"\n owner 'root'\n\ + \ group 'root'\n mode '0755'\n end\n end\n ```\n\n Use a relative\ + \ path\n\n ```ruby\n template \"#{ENV['HOME']}/chef-getting-started.txt\" do\n\ + \ source 'chef-getting-started.txt.erb'\n mode '0755'\n end\n ```\n\n Delay\ + \ notifications\n\n ```ruby\n template '/etc/nagios3/configures-nagios.conf'\ + \ do\n # other parameters\n notifies :run, 'execute[test-nagios-config]',\ + \ :delayed\n end\n ```\n\n Notify immediately\n\n By default, notifications\ + \ are `:delayed`, that is they are queued up as\n they are triggered, and then\ + \ executed at the very end of a Chef Infra\n Client run. To run an action immediately,\ + \ use `:immediately`:\n\n ```ruby\n template '/etc/nagios3/configures-nagios.conf'\ + \ do\n # other parameters\n notifies :run, 'execute[test-nagios-config]',\ + \ :immediately\n end\n ```\n\n and then Chef Infra Client would immediately run\ + \ the following:\n\n ```ruby\n execute 'test-nagios-config' do\n command 'nagios3\ + \ --verify-config'\n action :nothing\n end\n ```\n\n Notify multiple resources\n\ + \n ```ruby\n template '/etc/chef/server.rb' do\n source 'server.rb.erb'\n\ + \ owner 'root'\n group 'root'\n mode '0755'\n notifies :restart, 'service[chef-solr]',\ + \ :delayed\n notifies :restart, 'service[chef-solr-indexer]', :delayed\n notifies\ + \ :restart, 'service[chef-server]', :delayed\n end\n ```\n\n Reload a service\n\ + \n ```ruby\n template '/tmp/somefile' do\n mode '0755'\n source 'somefile.erb'\n\ + \ notifies :reload, 'service[apache]', :immediately\n end\n ```\n\n Restart\ + \ a service when a template is modified\n\n ```ruby\n template '/etc/www/configures-apache.conf'\ + \ do\n notifies :restart, 'service[apache]', :immediately\n end\n ```\n\n \ + \ Send notifications to multiple resources\n\n To send notifications to multiple\ + \ resources, just use multiple\n attributes. Multiple attributes will get sent\ + \ to the notified resources\n in the order specified.\n\n ```ruby\n template\ + \ '/etc/netatalk/netatalk.conf' do\n notifies :restart, 'service[afpd]', :immediately\n\ + \ notifies :restart, 'service[cnid]', :immediately\n end\n\n service 'afpd'\n\ + \ service 'cnid'\n ```\n\n Execute a command using a template\n\n The following\ + \ example shows how to set up IPv4 packet forwarding using\n the **execute** resource\ + \ to run a command named `forward_ipv4` that uses\n a template defined by the **template**\ + \ resource:\n\n ```ruby\n execute 'forward_ipv4' do\n command 'echo > /proc/.../ipv4/ip_forward'\n\ + \ action :nothing\n end\n\n template '/etc/file_name.conf' do\n source 'routing/file_name.conf.erb'\n\ + \ notifies :run, 'execute[forward_ipv4]', :delayed\n end\n ```\n\n where the\ + \ `command` property for the **execute** resource contains the\n command that is\ + \ to be run and the `source` property for the **template**\n resource specifies\ + \ which template to use. The `notifies` property for\n the **template** specifies\ + \ that the `execute[forward_ipv4]` (which is\n defined by the **execute** resource)\ + \ should be queued up and run at the\n end of a Chef Infra Client run.\n\n Set\ + \ an IP address using variables and a template\n\n The following example shows\ + \ how the **template** resource can be used in\n a recipe to combine settings stored\ + \ in an attributes file, variables\n within a recipe, and a template to set the\ + \ IP addresses that are used by\n the Nginx service. The attributes file contains\ + \ the following:\n\n ```ruby\n default['nginx']['dir'] = '/etc/nginx'\n ```\n\ + \n The recipe then does the following to:\n\n - Declare two variables at the\ + \ beginning of the recipe, one for the\n remote IP address and the other for\ + \ the authorized IP address\n - Use the **service** resource to restart and reload\ + \ the Nginx service\n - Load a template named `authorized_ip.erb` from the `/templates`\n\ + \ directory that is used to set the IP address values based on the\n variables\ + \ specified in the recipe\n\n \n\n ```ruby\n node.default['nginx']['remote_ip_var']\ + \ = 'remote_addr'\n node.default['nginx']['authorized_ips'] = ['127.0.0.1/32']\n\ + \n service 'nginx' do\n supports :status => true, :restart => true, :reload\ + \ => true\n end\n\n template 'authorized_ip' do\n path \"#{node['nginx']['dir']}/authorized_ip\"\ + \n source 'modules/authorized_ip.erb'\n owner 'root'\n group 'root'\n \ + \ mode '0755'\n variables(\n :remote_ip_var => node['nginx']['remote_ip_var'],\n\ + \ :authorized_ips => node['nginx']['authorized_ips']\n )\n\n notifies\ + \ :reload, 'service[nginx]', :immediately\n end\n ```\n\n where the `variables`\ + \ property tells the template to use the variables\n set at the beginning of the\ + \ recipe and the `source` property is used to\n call a template file located in\ + \ the cookbook's `/templates` directory.\n The template file looks similar to:\n\ + \n ```ruby\n geo $<%= @remote_ip_var %> $authorized_ip {\n default no;\n \ + \ <% @authorized_ips.each do |ip| %>\n <%= \"#{ip} yes;\" %>\n <% end %>\n\ + \ }\n ```\n\n Add a rule to an IP table\n\n The following example shows how\ + \ to add a rule named `test_rule` to an IP\n table using the **execute** resource\ + \ to run a command using a template\n that is defined by the **template** resource:\n\ + \n ```ruby\n execute 'test_rule' do\n command 'command_to_run\n --option\ + \ value\n ...\n --option value\n --source #{node[:name_of_node][:ipsec][:local][:subnet]}\n\ + \ -j test_rule'\n action :nothing\n end\n\n template '/etc/file_name.local'\ + \ do\n source 'routing/file_name.local.erb'\n notifies :run, 'execute[test_rule]',\ + \ :delayed\n end\n ```\n\n where the `command` property for the **execute** resource\ + \ contains the\n command that is to be run and the `source` property for the **template**\n\ + \ resource specifies which template to use. The `notifies` property for\n the\ + \ **template** specifies that the `execute[test_rule]` (which is\n defined by the\ + \ **execute** resource) should be queued up and run at the\n end of a Chef Infra\ + \ Client run.\n\n Apply proxy settings consistently across a Chef organization\n\ + \n The following example shows how a template can be used to apply\n consistent\ + \ proxy settings for all nodes of the same type:\n\n ```ruby\n template \"#{node['matching_node']['dir']}/sites-available/site_proxy.conf\"\ + \ do\n source 'site_proxy.matching_node.conf.erb'\n owner 'root'\n group\ + \ 'root'\n mode '0755'\n variables(\n :ssl_certificate => \"#{node['matching_node']['dir']}/shared/certificates/site_proxy.crt\"\ + ,\n :ssl_key => \"#{node['matching_node']['dir']}/shared/certificates/site_proxy.key\"\ + ,\n :listen_port => node['site']['matching_node_proxy']['listen_port'],\n\ + \ :server_name => node['site']['matching_node_proxy']['server_name'],\n\ + \ :fqdn => node['fqdn'],\n :server_options => node[:site]['matching_node']['server']['options'],\n\ + \ :proxy_options => node[:site]['matching_node']['proxy']['options']\n\ + \ )\n end\n ```\n\n where `matching_node` represents a type of node (like\ + \ Nginx) and\n `site_proxy` represents the type of proxy being used for that type\ + \ of\n node (like Nexus).\n\n Get template settings from a local file\n\n The\ + \ **template** resource can be used to render a template based on\n settings contained\ + \ in a local file on disk or to get the settings from a\n template in a cookbook.\ + \ Most of the time, the settings are retrieved\n from a template in a cookbook.\ + \ The following example shows how the\n **template** resource can be used to retrieve\ + \ these settings from a\n local file.\n\n The following example is based on a\ + \ few assumptions:\n\n - The environment is a Ruby on Rails application that\ + \ needs render a\n file named `database.yml`\n - Information about the application---the\ + \ user, their password, the\n server---is stored in a data bag on the Chef\ + \ server\n - The application is already deployed to the system and that only\n\ + \ requirement in this example is to render the `database.yml` file\n\n The\ + \ application source tree looks something like:\n\n myapp/\n -> config/\n\ + \ -> database.yml.erb\n\n
\n

Note

\n
\n \ + \

There should not be a file named database.yml (without the\ + \ .erb), as the database.yml file is what will be rendered\ + \ using the template resource.

\n\n
\n
\n\ + \n The deployment of the app will end up in `/srv`, so the full path to\n this\ + \ template would be something like\n `/srv/myapp/current/config/database.yml.erb`.\n\ + \n The content of the template itself may look like this:\n\n ```ruby\n <%=\ + \ @rails_env %>:\n adapter: <%= @adapter %>\n host: <%= @host %>\n database:\ + \ <%= @database %>\n username: <%= @username %>\n password: <%= @password\ + \ %>\n encoding: 'utf8'\n reconnect: true\n ```\n\n The recipe will be\ + \ similar to the following:\n\n ```ruby\n results = search(:node, \"role:myapp_database_master\ + \ AND chef_environment:#{node.chef_environment}\")\n db_master = results[0]\n\n\ + \ template '/srv/myapp/shared/database.yml' do\n source '/srv/myapp/current/config/database.yml.erb'\n\ + \ local true\n variables(\n :rails_env => node.chef_environment,\n \ + \ :adapter => db_master['myapp']['db_adapter'],\n :host => db_master['fqdn'],\n\ + \ :database => \"myapp_#{node.chef_environment}\",\n :username => \"myapp\"\ + ,\n :password => \"SUPERSECRET\",\n )\n end\n ```\n\n where:\n\n - \ + \ the `search` method in the Chef Infra Language is used to find the first node\n that\ + \ is the database master (of which there should only be one)\n - the `:adapter`\ + \ variable property may also require an attribute to\n have been set on a role,\ + \ which then determines the correct adapter\n\n The template will render similar\ + \ to the following:\n\n ```ruby\n production:\n adapter: mysql\n host:\ + \ domU-12-31-39-14-F1-C3.compute-1.internal\n database: myapp_production\n \ + \ username: myapp\n password: SUPERSECRET\n encoding: utf8\n reconnect:\ + \ true\n ```\n\n This example showed how to use the **template** resource to render\ + \ a\n template based on settings contained in a local file. Some other issues\n\ + \ that should be considered when using this type of approach include:\n\n - \ + \ Should the `database.yml` file be in a `.gitignore` file?\n - How do developers\ + \ run the application locally?\n - Does this work with chef-solo?\n\n Pass values\ + \ from recipe to template\n\n The following example shows how pass a value to a\ + \ template using the\n `variables` property in the **template** resource. The template\ + \ file is\n similar to:\n\n ```ruby\n [tcpout]\n defaultGroup = splunk_indexers_<%=\ + \ node['splunk']['receiver_port'] %>\n disabled=false\n\n [tcpout:splunk_indexers_<%=\ + \ node['splunk']['receiver_port'] %>]\n server=<% @splunk_servers.map do |s| -%><%=\ + \ s['ipaddress'] %>:<%= s['splunk']['receiver_port'] %> <% end.join(', ') -%>\n\ + \ <% @outputs_conf.each_pair do |name, value| -%>\n <%= name %> = <%= value %>\n\ + \ <% end -%>\n ```\n\n The recipe then uses the `variables` attribute to find\ + \ the values for\n `splunk_servers` and `outputs_conf`, before passing them into\ + \ the\n template:\n\n ```ruby\n template \"#{splunk_dir}/etc/system/local/outputs.conf\"\ + \ do\n source 'outputs.conf.erb'\n mode '0755'\n variables :splunk_servers\ + \ => splunk_servers, :outputs_conf => node['splunk']['outputs_conf']\n notifies\ + \ :restart, 'service[splunk]'\n end\n ```\n\n This example can be found in the\ + \ `client.rb` recipe and the\n `outputs.conf.erb` template files that are located\ + \ in the [chef-splunk\n cookbook](https://github.com/chef-cookbooks/chef-splunk/)\ + \ that is\n maintained by Chef.\n" diff --git a/data/infra/resources/timezone.yaml b/data/infra/resources/timezone.yaml new file mode 100644 index 0000000..5adeeef --- /dev/null +++ b/data/infra/resources/timezone.yaml @@ -0,0 +1,61 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: timezone +resource_description_list: +- markdown: 'Use the **timezone** resource to change the system timezone on Windows, + Linux, and macOS hosts. Timezones are specified in tz database format, with a + complete list of available TZ values for Linux and macOS here: . + On Windows systems run `tzutil /l` for a complete list of valid timezones.' +resource_new_in: '14.6' +syntax_full_code_block: |- + timezone 'name' do + timezone String # default value: 'name' unless specified + action Symbol # defaults to :set if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`timezone` 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." +- "`timezone` is the property available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :set: + markdown: Set the system timezone. (default) +properties_list: +- property: timezone + ruby_type: String + required: false + default_value: The resource block's name + 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** + + ```ruby + timezone 'UTC' + ``` + + **Set the timezone to America/Los_Angeles with a friendly resource name on Linux/macOS** + + ```ruby + timezone "Set the host's timezone to America/Los_Angeles" do + timezone 'America/Los_Angeles' + end + ``` + + **Set the timezone to PST with a friendly resource name on Windows** + + ```ruby + timezone "Set the host's timezone to PST" do + timezone 'Pacific Standard time' + end + ``` diff --git a/data/infra/resources/user_ulimit.yaml b/data/infra/resources/user_ulimit.yaml new file mode 100644 index 0000000..7e0d5eb --- /dev/null +++ b/data/infra/resources/user_ulimit.yaml @@ -0,0 +1,295 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: user_ulimit +resource_description_list: +- markdown: Use the **user_ulimit** resource to create individual ulimit files that + are installed into the `/etc/security/limits.d/` directory. +resource_new_in: '16.0' +syntax_full_code_block: |- + user_ulimit 'name' do + as_hard_limit String, Integer + as_limit String, Integer + as_soft_limit String, Integer + core_hard_limit String, Integer + core_limit String, Integer + core_soft_limit String, Integer + cpu_hard_limit String, Integer + cpu_limit String, Integer + cpu_soft_limit String, Integer + filehandle_hard_limit String, Integer + filehandle_limit String, Integer + filehandle_soft_limit String, Integer + filename String + locks_limit String, Integer + maxlogins_hard_limit String, Integer + maxlogins_limit String, Integer + maxlogins_soft_limit String, Integer + memory_limit String, Integer + msgqueue_hard_limit String, Integer + msgqueue_limit String, Integer + msgqueue_soft_limit String, Integer + process_hard_limit String, Integer + process_limit String, Integer + process_soft_limit String, Integer + rss_hard_limit String, Integer + rss_limit String, Integer + rss_soft_limit String, Integer + rtprio_hard_limit String, Integer + rtprio_limit String, Integer + rtprio_soft_limit String, Integer + sigpending_hard_limit String, Integer + sigpending_limit String, Integer + sigpending_soft_limit String, Integer + stack_hard_limit String, Integer + stack_limit String, Integer + stack_soft_limit String, Integer + username String # default value: 'name' unless specified + virt_limit String, Integer + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`user_ulimit` 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." +- "`as_hard_limit`, `as_limit`, `as_soft_limit`, `core_hard_limit`, `core_limit`, + `core_soft_limit`, `cpu_hard_limit`, `cpu_limit`, `cpu_soft_limit`, `filehandle_hard_limit`, + `filehandle_limit`, `filehandle_soft_limit`, `filename`, `locks_limit`, `maxlogins_hard_limit`, + `maxlogins_limit`, `maxlogins_soft_limit`, `memory_limit`, `msgqueue_hard_limit`, + `msgqueue_limit`, `msgqueue_soft_limit`, `process_hard_limit`, `process_limit`, + `process_soft_limit`, `rss_hard_limit`, `rss_limit`, `rss_soft_limit`, `rtprio_hard_limit`, + `rtprio_limit`, `rtprio_soft_limit`, `sigpending_hard_limit`, `sigpending_limit`, + `sigpending_soft_limit`, `stack_hard_limit`, `stack_limit`, `stack_soft_limit`, + `username`, and `virt_limit` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Create a ulimit configuration file. (default) + :delete: + markdown: Delete an existing ulimit configuration file. +properties_list: +- property: as_hard_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: as_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: as_soft_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: core_hard_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: core_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: core_soft_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: cpu_hard_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: cpu_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: cpu_soft_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: filehandle_hard_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: filehandle_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: filehandle_soft_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: filename + ruby_type: String + required: false + default_value: lazy default + description_list: + - markdown: +- property: locks_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: maxlogins_hard_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: maxlogins_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: maxlogins_soft_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: memory_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: msgqueue_hard_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: msgqueue_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: msgqueue_soft_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: process_hard_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: process_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: process_soft_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: rss_hard_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: rss_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: rss_soft_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: rtprio_hard_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: rtprio_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: rtprio_soft_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: sigpending_hard_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: sigpending_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: sigpending_soft_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: stack_hard_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: stack_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: stack_soft_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +- property: username + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: +- property: virt_limit + ruby_type: String, Integer + required: false + description_list: + - markdown: +target_mode: + support: full +examples: | + **Set filehandle limit for the tomcat user**: + + ```ruby + user_ulimit 'tomcat' do + filehandle_limit 8192 + end + ``` + + **Specify a username that differs from the name given to the resource block**: + + ```ruby + user_ulimit 'Bump filehandle limits for tomcat user' do + username 'tomcat' + filehandle_limit 8192 + end + ``` + + **Set filehandle limit for the tomcat user with a non-default filename**: + + ```ruby + user_ulimit 'tomcat' do + filehandle_limit 8192 + filename 'tomcat_filehandle_limits.conf' + end + ``` diff --git a/data/infra/resources/windows_ad_join.yaml b/data/infra/resources/windows_ad_join.yaml new file mode 100644 index 0000000..dd3320a --- /dev/null +++ b/data/infra/resources/windows_ad_join.yaml @@ -0,0 +1,120 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_ad_join +resource_description_list: +- markdown: Use the **windows_ad_join** resource to join a Windows Active Directory + domain. +resource_new_in: '14.0' +syntax_full_code_block: |- + windows_ad_join 'name' do + domain_name String # default value: 'name' unless specified + domain_password String + domain_user String + new_hostname String + ou_path String + reboot Symbol # default value: :immediate + reboot_delay Integer # default value: 0 + workgroup_name String + action Symbol # defaults to :join if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_ad_join` 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." +- "`domain_name`, `domain_password`, `domain_user`, `new_hostname`, `ou_path`, `reboot`, + `reboot_delay`, and `workgroup_name` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :join: + markdown: Join the Active Directory domain. (default) + :leave: + markdown: Leave an Active Directory domain and re-join a workgroup. +properties_list: +- property: domain_name + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the FQDN of the Active Directory domain + to join if it differs from the resource block's name. +- property: domain_password + ruby_type: String + required: true + description_list: + - markdown: The password for the domain user. Note that this resource is set to + hide sensitive information by default. +- property: domain_user + ruby_type: String + required: true + description_list: + - markdown: The domain user that will be used to join the domain. +- property: new_hostname + ruby_type: String + required: false + new_in: '14.5' + description_list: + - markdown: Specifies a new hostname for the computer in the new domain. +- property: ou_path + ruby_type: String + required: false + description_list: + - markdown: The path to the Organizational Unit where the host will be placed. +- property: reboot + ruby_type: Symbol + required: false + default_value: ":immediate" + allowed_values: ":delayed, :immediate, :never, :reboot_now, :request_reboot" + description_list: + - markdown: Controls the system reboot behavior post domain joining. Reboot immediately, + after the Chef Infra Client run completes, or never. Note that a reboot is necessary + for changes to take effect. +- property: reboot_delay + ruby_type: Integer + required: false + default_value: '0' + new_in: '16.5' + description_list: + - markdown: The amount of time (in minutes) to delay a reboot request. +- property: workgroup_name + ruby_type: String + required: false + new_in: '15.4' + description_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** + + ```ruby + windows_ad_join 'ad.example.org' do + domain_user 'nick' + domain_password 'p@ssw0rd1' + end + ``` + + **Join a domain, as `win-workstation`** + + ```ruby + windows_ad_join 'ad.example.org' do + domain_user 'nick' + domain_password 'p@ssw0rd1' + new_hostname 'win-workstation' + end + ``` + + **Leave the current domain and re-join the `local` workgroup** + + ```ruby + windows_ad_join 'Leave domain' do + action :leave + workgroup 'local' + end + ``` diff --git a/data/infra/resources/windows_audit_policy.yaml b/data/infra/resources/windows_audit_policy.yaml new file mode 100644 index 0000000..782fd3e --- /dev/null +++ b/data/infra/resources/windows_audit_policy.yaml @@ -0,0 +1,131 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_audit_policy +resource_description_list: +- markdown: Use the **windows_audit_policy** resource to configure system level and + per-user Windows advanced audit policy settings. +resource_new_in: '16.2' +syntax_full_code_block: |- + windows_audit_policy 'name' do + audit_base_directories true, false + audit_base_objects true, false + crash_on_audit_fail true, false + exclude_user String + failure true, false + full_privilege_auditing true, false + include_user String + subcategory String, Array + success true, false + action Symbol # defaults to :set if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_audit_policy` 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." +- "`audit_base_directories`, `audit_base_objects`, `crash_on_audit_fail`, `exclude_user`, + `failure`, `full_privilege_auditing`, `include_user`, `subcategory`, and `success` + are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :set: + markdown: Configure an audit policy. (default) +properties_list: +- property: audit_base_directories + ruby_type: true, false + required: false + description_list: + - markdown: Setting this audit policy option to true will force the system to assign + a System Access Control List to named objects to enable auditing of container + objects such as directories. +- property: audit_base_objects + ruby_type: true, false + required: false + description_list: + - markdown: Setting this audit policy option to true will force the system to assign + a System Access Control List to named objects to enable auditing of base objects + such as mutexes. +- property: crash_on_audit_fail + ruby_type: true, false + required: false + description_list: + - markdown: Setting this audit policy option to true will cause the system to crash + if the auditing system is unable to log events. +- property: exclude_user + ruby_type: String + required: false + description_list: + - markdown: The audit policy specified by the category or subcategory is applied + per-user if specified. When a user is specified, exclude user. Include and exclude + cannot be used at the same time. +- property: failure + ruby_type: true, false + required: false + description_list: + - markdown: Specify failure auditing. By setting this property to true the resource + will enable failure for the category or sub category. Success is the default + and is applied if neither success nor failure are specified. +- property: full_privilege_auditing + ruby_type: true, false + required: false + description_list: + - markdown: Setting this audit policy option to true will force the audit of all + privilege changes except SeAuditPrivilege. Setting this property may cause the + logs to fill up more quickly. +- property: include_user + ruby_type: String + required: false + description_list: + - markdown: The audit policy specified by the category or subcategory is applied + per-user if specified. When a user is specified, include user. Include and exclude + cannot be used at the same time. +- property: subcategory + ruby_type: String, Array + required: false + description_list: + - markdown: The audit policy subcategory, specified by GUID or name. Applied system-wide + if no user is specified. +- property: success + ruby_type: true, false + required: false + description_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"**: + + ```ruby + windows_audit_policy "Set Audit Policy for 'Logon and Logoff' actions to 'Success and Failure'" do + subcategory %w(Logon Logoff) + success true + failure true + action :set + end + ``` + + **Set Credential Validation policy to "Success"**: + + ```ruby + windows_audit_policy "Set Audit Policy for 'Credential Validation' actions to 'Success'" do + subcategory 'Credential Validation' + success true + failure false + action :set + end + ``` + + **Enable CrashOnAuditFail option**: + + ```ruby + windows_audit_policy 'Enable CrashOnAuditFail option' do + crash_on_audit_fail true + action :set + end + ``` diff --git a/data/infra/resources/windows_auto_run.yaml b/data/infra/resources/windows_auto_run.yaml new file mode 100644 index 0000000..6b55166 --- /dev/null +++ b/data/infra/resources/windows_auto_run.yaml @@ -0,0 +1,68 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_auto_run +resource_description_list: +- markdown: Use the **windows_auto_run** resource to set applications to run at login. +resource_new_in: '14.0' +syntax_full_code_block: |- + windows_auto_run 'name' do + args String + path String + program_name String # default value: 'name' unless specified + root Symbol # default value: :machine + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_auto_run` 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." +- "`args`, `path`, `program_name`, and `root` are the properties available to this + resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Create an item to be run at login. (default) + :remove: + markdown: Remove an item that was previously configured to run at login. +properties_list: +- property: args + ruby_type: String + required: false + description_list: + - markdown: Any arguments to be used with the program. +- property: path + ruby_type: String + required: false + description_list: + - markdown: The path to the program that will run at login. +- property: program_name + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: The name of the program to run at login if it differs from the resource + block's name. +- property: root + ruby_type: Symbol + required: false + default_value: ":machine" + 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" + action :create + end + ``` diff --git a/data/infra/resources/windows_certificate.yaml b/data/infra/resources/windows_certificate.yaml new file mode 100644 index 0000000..42099f7 --- /dev/null +++ b/data/infra/resources/windows_certificate.yaml @@ -0,0 +1,123 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_certificate +resource_description_list: +- markdown: Use the **windows_certificate** resource to install a certificate into + the Windows certificate store from a file. The resource grants read-only access + to the private key for designated accounts. Due to current limitations in WinRM, + installing certificates remotely may not work if the operation requires a user + profile. Operations on the local machine store should still work. +resource_new_in: '14.7' +syntax_full_code_block: |- + windows_certificate 'name' do + exportable true, false # default value: false + output_path String + pfx_password String + private_key_acl Array + source String # default value: 'name' unless specified + store_name String # default value: "MY" + user_store true, false # default value: false + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_certificate` 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." +- "`exportable`, `output_path`, `pfx_password`, `private_key_acl`, `source`, `store_name`, + and `user_store` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Creates or updates a certificate. (default) + :acl_add: + markdown: Adds read-only entries to a certificate's private key ACL. + :delete: + markdown: Deletes a certificate. + :fetch: + markdown: Fetches a certificate. + :verify: + markdown: Verifies a certificate and logs the result. +properties_list: +- property: exportable + ruby_type: true, false + required: false + default_value: 'false' + new_in: '16.8' + description_list: + - markdown: Ensure that imported pfx certificate is exportable. Please provide 'true' + if you want the certificate to be exportable. +- property: output_path + ruby_type: String + required: false + new_in: '17.0' + description_list: + - markdown: A path on the node where a certificate object (PFX, PEM, CER, KEY, etc) + can be exported to. +- property: pfx_password + ruby_type: String + required: false + description_list: + - markdown: The password to access the object with if it is a PFX file. +- property: private_key_acl + ruby_type: Array + required: false + description_list: + - markdown: An array of 'domain\account' entries to be granted read-only access + to the certificate's private key. Not idempotent. +- property: source + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: The source file (for `create` and `acl_add`), thumbprint (for `delete`, + `export`, and `acl_add`), or subject (for `delete` or `export`) if it differs + from the resource block's name. +- property: store_name + ruby_type: String + required: false + default_value: MY + allowed_values: '"AUTHROOT", "CA", "CLIENTAUTHISSUER", "DISALLOWED", "MY", "REMOTE + DESKTOP", "ROOT", "SMARTCARDROOT", "TRUST", "TRUSTEDDEVICES", "TRUSTEDPEOPLE", + "TRUSTEDPUBLISHER", "TrustedPublisher", "WEBHOSTING"' + description_list: + - markdown: The certificate store to manipulate. +- property: user_store + ruby_type: true, false + required: false + default_value: 'false' + description_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** + + ```ruby + windows_certificate 'c:/test/mycert.pfx' do + pfx_password 'password' + private_key_acl ["acme\fred", "pc\jane"] + end + ``` + + **Add cert to trusted intermediate store** + + ```ruby + windows_certificate 'c:/test/mycert.cer' do + store_name 'CA' + end + ``` + + **Remove all certificates matching the subject** + + ```ruby + windows_certificate 'me.acme.com' do + action :delete + end + ``` diff --git a/data/infra/resources/windows_defender.yaml b/data/infra/resources/windows_defender.yaml new file mode 100644 index 0000000..aafd74e --- /dev/null +++ b/data/infra/resources/windows_defender.yaml @@ -0,0 +1,120 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_defender +resource_description_list: +- markdown: Use the **windows_defender** resource to enable or disable the Microsoft + Windows Defender service. +resource_new_in: '17.3' +syntax_full_code_block: |- + windows_defender 'name' do + intrusion_protection_system true, false # default value: true + lock_ui true, false # default value: false + realtime_protection true, false # default value: true + scan_archives true, false # default value: true + scan_email true, false # default value: false + scan_mapped_drives true, false # default value: true + scan_network_files true, false # default value: false + scan_removable_drives true, false # default value: false + scan_scripts true, false # default value: false + action Symbol # defaults to :enable if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_defender` 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." +- "`intrusion_protection_system`, `lock_ui`, `realtime_protection`, `scan_archives`, + `scan_email`, `scan_mapped_drives`, `scan_network_files`, `scan_removable_drives`, + and `scan_scripts` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :enable: + markdown: Enable and configure Windows Defender. (default) + :disable: + markdown: Disable Windows Defender. +properties_list: +- property: intrusion_protection_system + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Enable network protection against exploitation of known vulnerabilities. +- property: lock_ui + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Lock the UI to prevent users from changing Windows Defender settings. +- property: realtime_protection + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Enable realtime scanning of downloaded files and attachments. +- property: scan_archives + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Scan file archives such as .zip or .gz archives. +- property: scan_email + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Scan e-mails for malware. +- property: scan_mapped_drives + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Scan files on mapped network drives. +- property: scan_network_files + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Scan files on a network. +- property: scan_removable_drives + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Scan content of removable drives. +- property: scan_scripts + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Scan scripts in malware scans. +target_mode: +examples: | + **Configure Windows Defender AV settings**: + + ```ruby + windows_defender 'Configure Defender' do + realtime_protection true + intrusion_protection_system true + lock_ui true + scan_archives true + scan_scripts true + scan_email true + scan_removable_drives true + scan_network_files false + scan_mapped_drives false + action :enable + end + ``` + + **Disable Windows Defender AV**: + + ```ruby + windows_defender 'Disable Defender' do + action :disable + end + ``` diff --git a/data/infra/resources/windows_defender_exclusion.yaml b/data/infra/resources/windows_defender_exclusion.yaml new file mode 100644 index 0000000..d8b15a6 --- /dev/null +++ b/data/infra/resources/windows_defender_exclusion.yaml @@ -0,0 +1,72 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_defender_exclusion +resource_description_list: +- markdown: Use the **windows_defender_exclusion** resource to exclude paths, processes, + or file types from Windows Defender realtime protection scanning. +resource_new_in: '17.3' +syntax_full_code_block: |- + windows_defender_exclusion 'name' do + extensions String, Array # default value: [] + paths String, Array # default value: [] + process_paths String, Array # default value: [] + action Symbol # defaults to :add if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_defender_exclusion` 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." +- "`extensions`, `paths`, and `process_paths` are the properties available to this + resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :add: + markdown: Add an exclusion to Windows Defender. (default) + :remove: + markdown: Remove an exclusion to Windows Defender. +properties_list: +- property: extensions + ruby_type: String, Array + required: false + default_value: "[]" + description_list: + - markdown: File extensions to exclude from scanning. +- property: paths + ruby_type: String, Array + required: false + default_value: "[]" + description_list: + - markdown: File or directory paths to exclude from scanning. +- property: process_paths + ruby_type: String, Array + required: false + default_value: "[]" + description_list: + - markdown: Paths to executables to exclude from scanning. +target_mode: +examples: | + **Add excluded items to Windows Defender scans**: + + ```ruby + windows_defender_exclusion 'Add to things to be excluded from scanning' do + paths 'c:\foo\bar, d:\bar\baz' + extensions 'png, foo, ppt, doc' + process_paths 'c:\windows\system32' + action :add + end + ``` + + **Remove excluded items from Windows Defender scans**: + + ```ruby + windows_defender_exclusion 'Remove things from the list to be excluded' do + process_paths 'c:\windows\system32' + action :remove + end + ``` diff --git a/data/infra/resources/windows_dfs_folder.yaml b/data/infra/resources/windows_dfs_folder.yaml new file mode 100644 index 0000000..30ad942 --- /dev/null +++ b/data/infra/resources/windows_dfs_folder.yaml @@ -0,0 +1,58 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_dfs_folder +resource_description_list: +- markdown: Use the **windows_dfs_folder** resource to creates a folder within DFS + as many levels deep as required. +resource_new_in: '15.0' +syntax_full_code_block: |- + windows_dfs_folder 'name' do + description String + folder_path String # default value: 'name' unless specified + namespace_name String + target_path String + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_dfs_folder` 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." +- "`description`, `folder_path`, `namespace_name`, and `target_path` are the properties + available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Creates the folder in dfs namespace. (default) + :delete: + markdown: Deletes the folder in the dfs namespace. +properties_list: +- property: description + ruby_type: String + required: false + description_list: + - markdown: Description for the share. +- property: folder_path + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the path of the dfs folder if it differs + from the resource block's name. +- property: namespace_name + ruby_type: String + required: true + description_list: + - markdown: The namespace this should be created within. +- property: target_path + ruby_type: String + 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 new file mode 100644 index 0000000..e57df52 --- /dev/null +++ b/data/infra/resources/windows_dfs_namespace.yaml @@ -0,0 +1,74 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_dfs_namespace +resource_description_list: +- markdown: Use the **windows_dfs_namespace** resource to creates a share and DFS + namespace on a Windows server. +resource_new_in: '15.0' +syntax_full_code_block: |- + windows_dfs_namespace 'name' do + change_users Array # default value: [] + description String + full_users Array # default value: ["BUILTIN\\administrators"] + namespace_name String # default value: 'name' unless specified + read_users Array # default value: [] + root String # default value: "C:\\DFSRoots" + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_dfs_namespace` 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." +- "`change_users`, `description`, `full_users`, `namespace_name`, `read_users`, and + `root` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Creates the dfs namespace on the server. (default) + :delete: + markdown: Deletes a DFS Namespace including the directory on disk. +properties_list: +- property: change_users + ruby_type: Array + required: false + default_value: "[]" + description_list: + - markdown: Determines which users should have change access to the share. +- property: description + ruby_type: String + required: true + description_list: + - markdown: Description of the share. +- property: full_users + ruby_type: Array + required: false + default_value: '["BUILTIN\\administrators"]' + description_list: + - markdown: Determines which users should have full access to the share. +- property: namespace_name + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the dfs namespace if it differs from the + resource block's name. +- property: read_users + ruby_type: Array + required: false + default_value: "[]" + description_list: + - markdown: Determines which users should have read access to the share. +- property: root + ruby_type: String + required: false + 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 new file mode 100644 index 0000000..8f9b37d --- /dev/null +++ b/data/infra/resources/windows_dfs_server.yaml @@ -0,0 +1,62 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_dfs_server +resource_description_list: +- markdown: Use the **windows_dfs_server** resource to set system-wide DFS settings. +resource_new_in: '15.0' +syntax_full_code_block: |- + windows_dfs_server 'name' do + enable_site_costed_referrals true, false # default value: false + ldap_timeout_secs Integer # default value: 30 + prefer_login_dc true, false # default value: false + sync_interval_secs Integer # default value: 3600 + use_fqdn true, false # default value: false + action Symbol # defaults to :configure if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_dfs_server` 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." +- "`enable_site_costed_referrals`, `ldap_timeout_secs`, `prefer_login_dc`, `sync_interval_secs`, + and `use_fqdn` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :configure: + markdown: Configure DFS settings (default) +properties_list: +- property: enable_site_costed_referrals + ruby_type: true, false + required: false + default_value: 'false' + description_list: [] +- property: ldap_timeout_secs + ruby_type: Integer + required: false + default_value: '30' + description_list: [] +- property: prefer_login_dc + ruby_type: true, false + required: false + default_value: 'false' + description_list: [] +- property: sync_interval_secs + ruby_type: Integer + required: false + default_value: '3600' + description_list: [] +- property: use_fqdn + ruby_type: true, false + required: false + default_value: 'false' + description_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 new file mode 100644 index 0000000..e515ea8 --- /dev/null +++ b/data/infra/resources/windows_dns_record.yaml @@ -0,0 +1,67 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_dns_record +resource_description_list: +- markdown: The windows_dns_record resource creates a DNS record for the given domain. +resource_new_in: '15.0' +syntax_full_code_block: |- + windows_dns_record 'name' do + dns_server String # default value: "localhost" + record_name String # default value: 'name' unless specified + record_type String # default value: "ARecord" + target String + zone String + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_dns_record` 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." +- "`dns_server`, `record_name`, `record_type`, `target`, and `zone` are the properties + available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Creates and updates the DNS entry. (default) + :delete: + markdown: Deletes a DNS entry. +properties_list: +- property: dns_server + ruby_type: String + required: false + default_value: localhost + new_in: '16.3' + description_list: + - markdown: The name of the DNS server on which to create the record. +- property: record_name + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the dns record name if it differs from the + resource block's name. +- property: record_type + ruby_type: String + required: false + default_value: ARecord + allowed_values: '"ARecord", "CNAME", "PTR"' + description_list: + - markdown: The type of record to create, can be either ARecord, CNAME or PTR. +- property: target + ruby_type: String + required: true + description_list: + - markdown: The target for the record. +- property: zone + ruby_type: String + 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 new file mode 100644 index 0000000..e3aea2d --- /dev/null +++ b/data/infra/resources/windows_dns_zone.yaml @@ -0,0 +1,55 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_dns_zone +resource_description_list: +- markdown: The windows_dns_zone resource creates an Active Directory Integrated DNS + Zone on the local server. +resource_new_in: '15.0' +syntax_full_code_block: |- + windows_dns_zone 'name' do + replication_scope String # default value: "Domain" + server_type String # default value: "Domain" + zone_name String # default value: 'name' unless specified + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_dns_zone` 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." +- "`replication_scope`, `server_type`, and `zone_name` are the properties available + to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Creates and updates a DNS Zone. (default) + :delete: + markdown: Deletes a DNS Zone. +properties_list: +- property: replication_scope + ruby_type: String + required: false + default_value: Domain + description_list: + - markdown: The replication scope for the zone, required if server_type set to 'Domain'. +- property: server_type + ruby_type: String + required: false + default_value: Domain + allowed_values: '"Domain", "Standalone"' + description_list: + - markdown: The type of DNS server, Domain or Standalone. +- property: zone_name + ruby_type: String + required: false + default_value: The resource block's name + 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 new file mode 100644 index 0000000..72fd8c6 --- /dev/null +++ b/data/infra/resources/windows_env.yaml @@ -0,0 +1,75 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_env +resource_description_list: +- markdown: |- + Use the **windows_env** resource to manage environment keys in Microsoft Windows. After an environment key is set, Microsoft Windows must be restarted before the environment key will be available to the Task Scheduler. + + This resource was previously called the **env** resource; its name was updated in Chef Infra Client 14.0 to reflect the fact that only Windows is supported. Existing cookbooks using `env` will continue to function, but should be updated to use the new name. +- note: + markdown: On UNIX-based systems, the best way to manipulate environment keys is + with the `ENV` variable in Ruby; however, this approach does not have the same + permanent effect as using the windows_env resource. +syntax_full_code_block: |- + windows_env 'name' do + delim String, false + key_name String # default value: 'name' unless specified + user String # default value: "" + value String + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_env` 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." +- "`delim`, `key_name`, `user`, and `value` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Create an environment variable. If an environment variable already exists + (but does not match), update that environment variable to match. (default) + :delete: + markdown: Delete an environment variable. + :modify: + markdown: Modify an existing environment variable. This prepends the new value + to the existing value, using the delimiter specified by the `delim` property. +properties_list: +- property: delim + ruby_type: String, false + required: false + description_list: + - markdown: The delimiter that is used to separate multiple values for a single + key. +- property: key_name + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the name of the key that is to be created, + deleted, or modified if it differs from the resource block's name. +- property: user + ruby_type: String + required: false + default_value: "" + description_list: + - markdown: +- property: value + ruby_type: String + required: true + description_list: + - markdown: The value of the environmental variable to set. +target_mode: +examples: | + **Set an environment variable**: + + ```ruby + windows_env 'ComSpec' do + value 'C:\Windows\system32\cmd.exe' + end + ``` diff --git a/data/infra/resources/windows_feature.yaml b/data/infra/resources/windows_feature.yaml new file mode 100644 index 0000000..53521c7 --- /dev/null +++ b/data/infra/resources/windows_feature.yaml @@ -0,0 +1,138 @@ +--- +resource_reference: true +resources_common_guards: true +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' 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 + all true, false # default value: false + feature_name Array, String # default value: 'name' unless specified + install_method Symbol # default value: :windows_feature_dism + management_tools true, false # default value: false + source String + timeout Integer # default value: 600 + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_feature` 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." +- "`all`, `feature_name`, `install_method`, `management_tools`, `source`, and `timeout` + are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :install: + markdown: Install a Windows role or feature. (default) + :remove: + markdown: Remove a Windows role or feature. + :delete: + markdown: Remove a Windows role or feature from the image. +properties_list: +- property: all + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Install all sub-features. +- property: feature_name + ruby_type: Array, String + required: false + default_value: The resource block's name + description_list: + - markdown: The name of the feature(s) or role(s) to install if they differ from + the resource block's name. The same feature may have different names depending + on the underlying installation method being used (ie DHCPServer vs DHCP; DNS-Server-Full-Role + vs DNS). +- property: install_method + ruby_type: Symbol + required: false + default_value: ":windows_feature_dism" + allowed_values: ":windows_feature_dism, :windows_feature_powershell, :windows_feature_servermanagercmd" + description_list: + - markdown: The underlying installation method to use for feature installation. + Specify `:windows_feature_dism` for DISM or `:windows_feature_powershell` for + PowerShell. +- property: management_tools + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Install all applicable management tools for the roles, role services, + or features (PowerShell-only). +- property: source + ruby_type: String + required: false + description_list: + - markdown: Specify a local repository for the feature install. +- property: timeout + ruby_type: Integer + required: false + default_value: '600' + description_list: + - markdown: Specifies a timeout (in seconds) for the feature installation. +target_mode: +examples: | + **Install the DHCP Server feature**: + + ```ruby + windows_feature 'DHCPServer' do + action :install + end + ``` + + **Install the .Net 3.5.1 feature using repository files on DVD**: + + ```ruby + windows_feature "NetFx3" do + action :install + source 'd:\sources\sxs' + end + ``` + + **Remove Telnet Server and Client features**: + + ```ruby + windows_feature %w(TelnetServer TelnetClient) do + action :remove + end + ``` + + **Add the SMTP Server feature using the PowerShell provider**: + + ```ruby + windows_feature 'smtp-server' do + action :install + all true + install_method :windows_feature_powershell + end + ``` + + **Install multiple features using one resource with the PowerShell provider**: + + ```ruby + windows_feature %w(Web-Asp-Net45 Web-Net-Ext45) do + action :install + install_method :windows_feature_powershell + end + ``` + + **Install the Network Policy and Access Service feature, including the management tools**: + + ```ruby + windows_feature 'NPAS' do + action :install + management_tools true + install_method :windows_feature_powershell + end + ``` diff --git a/data/infra/resources/windows_feature_dism.yaml b/data/infra/resources/windows_feature_dism.yaml new file mode 100644 index 0000000..5ca1225 --- /dev/null +++ b/data/infra/resources/windows_feature_dism.yaml @@ -0,0 +1,74 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_feature_dism +resource_description_list: +- markdown: Use the **windows_feature_dism** resource to add, remove, or entirely + delete Windows features and roles using DISM. +resource_new_in: '14.0' +syntax_full_code_block: |- + windows_feature_dism 'name' do + all true, false # default value: false + feature_name Array, String # default value: 'name' unless specified + source String + timeout Integer # default value: 600 + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_feature_dism` 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." +- "`all`, `feature_name`, `source`, and `timeout` are the properties available to + this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :install: + markdown: Install a Windows role/feature using DISM. (default) + :remove: + markdown: Remove a Windows role or feature using DISM. + :delete: + markdown: Remove a Windows role or feature from the image using DISM. +properties_list: +- property: all + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Install all sub-features. When set to `true`, this is the equivalent + of specifying the `/All` switch to `dism.exe` +- property: feature_name + ruby_type: Array, String + required: false + default_value: The resource block's name + description_list: + - markdown: The name of the feature(s) or role(s) to install if they differ from + the resource name. +- property: source + ruby_type: String + required: false + description_list: + - markdown: Specify a local repository for the feature install. +- property: timeout + ruby_type: Integer + required: false + default_value: '600' + description_list: + - markdown: Specifies a timeout (in seconds) for the feature installation. +target_mode: +examples: | + **Installing the TelnetClient service**: + + ```ruby + windows_feature_dism "TelnetClient" + ``` + + **Installing two features by using an array**: + + ```ruby + windows_feature_dism %w(TelnetClient TFTP) + ``` diff --git a/data/infra/resources/windows_feature_powershell.yaml b/data/infra/resources/windows_feature_powershell.yaml new file mode 100644 index 0000000..b3cf422 --- /dev/null +++ b/data/infra/resources/windows_feature_powershell.yaml @@ -0,0 +1,98 @@ +--- +resource_reference: true +resources_common_guards: true +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 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 + all true, false # default value: false + feature_name Array, String # default value: 'name' unless specified + management_tools true, false # default value: false + source String + timeout Integer # default value: 600 + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_feature_powershell` 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." +- "`all`, `feature_name`, `management_tools`, `source`, and `timeout` are the properties + available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :install: + markdown: Install a Windows role or feature using PowerShell. (default) + :remove: + markdown: Remove a Windows role or feature using PowerShell. + :delete: + markdown: Delete a Windows role or feature from the image using PowerShell. +properties_list: +- property: all + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Install all subfeatures. When set to `true`, this is the equivalent + of specifying the `-InstallAllSubFeatures` switch with `Add-WindowsFeature`. +- property: feature_name + ruby_type: Array, String + required: false + default_value: The resource block's name + description_list: + - markdown: The name of the feature(s) or role(s) to install if they differ from + the resource block's name. +- property: management_tools + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Install all applicable management tools for the roles, role services, + or features. +- property: source + ruby_type: String + required: false + description_list: + - markdown: Specify a local repository for the feature install. +- property: timeout + ruby_type: Integer + required: false + default_value: '600' + description_list: + - markdown: Specifies a timeout (in seconds) for the feature installation. +target_mode: +examples: | + **Add the SMTP Server feature**: + + ```ruby + windows_feature_powershell "smtp-server" do + action :install + all true + end + ``` + + **Install multiple features using one resource**: + + ```ruby + windows_feature_powershell ['Web-Asp-Net45', 'Web-Net-Ext45'] do + action :install + end + ``` + + **Install the Network Policy and Access Service feature**: + + ```ruby + windows_feature_powershell 'NPAS' do + action :install + management_tools true + end + ``` diff --git a/data/infra/resources/windows_firewall_profile.yaml b/data/infra/resources/windows_firewall_profile.yaml new file mode 100644 index 0000000..7a39d5c --- /dev/null +++ b/data/infra/resources/windows_firewall_profile.yaml @@ -0,0 +1,137 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_firewall_profile +resource_description_list: +- markdown: Use the **windows_firewall_profile** resource to enable, disable, and + configure the Windows firewall. +resource_new_in: '16.3' +syntax_full_code_block: |- + windows_firewall_profile 'name' do + allow_inbound_rules true, false, String + allow_local_firewall_rules true, false, String + allow_local_ipsec_rules true, false, String + allow_unicast_response true, false, String + allow_user_apps true, false, String + allow_user_ports true, false, String + default_inbound_action String + default_outbound_action String + display_notification true, false, String + profile String # default value: 'name' unless specified + action Symbol # defaults to :enable if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_firewall_profile` 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." +- "`allow_inbound_rules`, `allow_local_firewall_rules`, `allow_local_ipsec_rules`, + `allow_unicast_response`, `allow_user_apps`, `allow_user_ports`, `default_inbound_action`, + `default_outbound_action`, `display_notification`, and `profile` are the properties + available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :enable: + markdown: Enable and optionally configure a Windows Firewall profile. (default) + :disable: + markdown: Disable a Windows Firewall profile. +properties_list: +- property: allow_inbound_rules + ruby_type: true, false, String + required: false + allowed_values: true, false, "NotConfigured" + description_list: + - markdown: Allow users to set inbound firewall rules +- property: allow_local_firewall_rules + ruby_type: true, false, String + required: false + allowed_values: true, false, "NotConfigured" + description_list: + - markdown: Merges inbound firewall rules into the policy +- property: allow_local_ipsec_rules + ruby_type: true, false, String + required: false + allowed_values: true, false, "NotConfigured" + description_list: + - markdown: Allow users to manage local connection security rules +- property: allow_unicast_response + ruby_type: true, false, String + required: false + allowed_values: true, false, "NotConfigured" + description_list: + - markdown: Allow unicast responses to multicast and broadcast messages +- property: allow_user_apps + ruby_type: true, false, String + required: false + allowed_values: true, false, "NotConfigured" + description_list: + - markdown: Allow user applications to manage firewall +- property: allow_user_ports + ruby_type: true, false, String + required: false + allowed_values: true, false, "NotConfigured" + description_list: + - markdown: Allow users to manage firewall port rules +- property: default_inbound_action + ruby_type: String + required: false + allowed_values: '"Allow", "Block", "NotConfigured"' + description_list: + - markdown: Set the default policy for inbound network traffic +- property: default_outbound_action + ruby_type: String + required: false + allowed_values: '"Allow", "Block", "NotConfigured"' + description_list: + - markdown: Set the default policy for outbound network traffic +- property: display_notification + ruby_type: true, false, String + required: false + allowed_values: true, false, "NotConfigured" + description_list: + - markdown: Display a notification when firewall blocks certain activity +- property: profile + ruby_type: String + required: false + default_value: The resource block's name + 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**: + + ```ruby + windows_firewall_profile 'Private' do + default_inbound_action 'Block' + default_outbound_action 'Allow' + allow_inbound_rules true + display_notification false + action :enable + end + ``` + + **Enable and Configure the Public Profile of the Windows Firewall**: + + ```ruby + windows_firewall_profile 'Public' do + default_inbound_action 'Block' + default_outbound_action 'Allow' + allow_inbound_rules false + display_notification false + action :enable + end + ``` + + **Disable the Domain Profile of the Windows Firewall**: + + ```ruby + windows_firewall_profile 'Disable the Domain Profile of the Windows Firewall' do + profile 'Domain' + action :disable + end + ``` diff --git a/data/infra/resources/windows_firewall_rule.yaml b/data/infra/resources/windows_firewall_rule.yaml new file mode 100644 index 0000000..befe2c2 --- /dev/null +++ b/data/infra/resources/windows_firewall_rule.yaml @@ -0,0 +1,209 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_firewall_rule +resource_description_list: +- markdown: Use the **windows_firewall_rule** resource to create, change or remove + Windows firewall rules. +resource_new_in: '14.7' +syntax_full_code_block: |- + windows_firewall_rule 'name' do + description String + direction Symbol, String # default value: :inbound + displayname String # default value: The rule_name property value. + enabled true, false # default value: true + firewall_action Symbol, String # default value: :allow + group String + icmp_type String, Integer # default value: "Any" + interface_type Symbol, String # default value: :any + local_address String + local_port String, Integer, Array + profile Symbol, String, Array # default value: :any + program String + protocol String # default value: "TCP" + remote_address String, Array + remote_port String, Integer, Array + rule_name String # default value: 'name' unless specified + service String + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_firewall_rule` 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." +- "`description`, `direction`, `displayname`, `enabled`, `firewall_action`, `group`, + `icmp_type`, `interface_type`, `local_address`, `local_port`, `profile`, `program`, + `protocol`, `remote_address`, `remote_port`, `rule_name`, and `service` are the + properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Create a Windows firewall entry. (default) + :delete: + markdown: Delete an existing Windows firewall entry. +properties_list: +- property: description + ruby_type: String + required: false + description_list: + - markdown: The description to assign to the firewall rule. +- property: direction + ruby_type: Symbol, String + required: false + default_value: ":inbound" + allowed_values: ":inbound, :outbound" + description_list: + - markdown: The direction of the firewall rule. Direction means either inbound or + outbound traffic. +- property: displayname + ruby_type: String + required: false + default_value: The rule_name property value. + new_in: '16.0' + description_list: + - markdown: The displayname to assign to the firewall rule. +- property: enabled + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Whether or not to enable the firewall rule. +- property: firewall_action + ruby_type: Symbol, String + required: false + default_value: ":allow" + allowed_values: ":allow, :block, :notconfigured" + description_list: + - markdown: The action of the firewall rule. +- property: group + ruby_type: String + required: false + new_in: '16.0' + description_list: + - markdown: Specifies that only matching firewall rules of the indicated group association + are copied. +- property: icmp_type + ruby_type: String, Integer + required: false + default_value: Any + new_in: '16.0' + description_list: + - markdown: Specifies the ICMP Type parameter for using a protocol starting with + ICMP +- property: interface_type + ruby_type: Symbol, String + required: false + default_value: ":any" + allowed_values: ":any, :remoteaccess, :wired, :wireless" + description_list: + - markdown: The interface type the firewall rule applies to. +- property: local_address + ruby_type: String + required: false + description_list: + - markdown: The local address the firewall rule applies to. +- property: local_port + ruby_type: String, Integer, Array + required: false + description_list: + - markdown: The local port the firewall rule applies to. +- property: profile + ruby_type: Symbol, String, Array + required: false + default_value: ":any" + description_list: + - markdown: The profile the firewall rule applies to. +- property: program + ruby_type: String + required: false + description_list: + - markdown: The program the firewall rule applies to. +- property: protocol + ruby_type: String + required: false + default_value: TCP + description_list: + - markdown: The protocol the firewall rule applies to. +- property: remote_address + ruby_type: String, Array + required: false + description_list: + - markdown: The remote address(es) the firewall rule applies to. +- property: remote_port + ruby_type: String, Integer, Array + required: false + description_list: + - markdown: The remote port the firewall rule applies to. +- property: rule_name + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the name of the firewall rule to assign + if it differs from the resource block's name. +- property: service + ruby_type: String + required: false + description_list: + - markdown: The service the firewall rule applies to. +target_mode: +examples: | + **Allowing port 80 access**: + + ```ruby + windows_firewall_rule 'IIS' do + local_port '80' + protocol 'TCP' + firewall_action :allow + end + ``` + + **Configuring multiple remote-address ports on a rule**: + + ```ruby + windows_firewall_rule 'MyRule' do + description 'Testing out remote address arrays' + enabled false + local_port 1434 + remote_address %w(10.17.3.101 172.7.7.53) + protocol 'TCP' + action :create + end + ``` + + **Allow protocol ICMPv6 with ICMP Type**: + + ```ruby + windows_firewall_rule 'CoreNet-Rule' do + rule_name 'CoreNet-ICMP6-LR2-In' + display_name 'Core Networking - Multicast Listener Report v2 (ICMPv6-In)' + local_port 'RPC' + protocol 'ICMPv6' + icmp_type '8' + end + ``` + + **Blocking WinRM over HTTP on a particular IP**: + + ```ruby + windows_firewall_rule 'Disable WinRM over HTTP' do + local_port '5985' + protocol 'TCP' + firewall_action :block + local_address '192.168.1.1' + end + ``` + + **Deleting an existing rule** + + ```ruby + windows_firewall_rule 'Remove the SSH rule' do + rule_name 'ssh' + action :delete + end + ``` diff --git a/data/infra/resources/windows_font.yaml b/data/infra/resources/windows_font.yaml new file mode 100644 index 0000000..d16f675 --- /dev/null +++ b/data/infra/resources/windows_font.yaml @@ -0,0 +1,51 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_font +resource_description_list: +- markdown: Use the **windows_font** resource to install font files on Windows. By + default, the font is sourced from the cookbook using the resource, but a URI source + can be specified as well. +resource_new_in: '14.0' +syntax_full_code_block: |- + windows_font 'name' do + font_name String # default value: 'name' unless specified + source String + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_font` 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." +- "`font_name` and `source` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :install: + markdown: Install a font to the system fonts directory. (default) +properties_list: +- property: font_name + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the name of the font to install if it differs + from the resource block's name. +- property: source + ruby_type: String + 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**: + + ```ruby + windows_font 'Custom.otf' do + source 'https://example.com/Custom.otf' + end + ``` diff --git a/data/infra/resources/windows_package.yaml b/data/infra/resources/windows_package.yaml new file mode 100644 index 0000000..0f65947 --- /dev/null +++ b/data/infra/resources/windows_package.yaml @@ -0,0 +1,211 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_package +resource_description_list: +- markdown: |- + Use the **windows_package** resource to manage packages on the Microsoft Windows platform. + The **windows_package** resource supports these installer formats: + * Microsoft Installer Package (MSI) + * Nullsoft Scriptable Install System (NSIS) + * Inno Setup (inno) + * Wise + * InstallShield + * Custom installers such as installing a non-.msi file that embeds an .msi-based installer + + To enable idempotence of the `:install` action or to enable the `:remove` action with no source property specified, + `package_name` MUST be an exact match of the name used by the package installer. The names of installed packages + Windows knows about can be found in **Add/Remove programs**, in the output of `ohai packages`, or in the + `DisplayName` property in one of the following in the Windows registry: + + * `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. +- notes_resource_based_on_package: true +syntax_description: | + A **windows_package** resource block manages a package on a node, + typically by installing it. The simplest use of the **windows_package** + resource is: + + ```ruby + windows_package ''package_name'' + ``` + + which will install the named package using all of the default options + and the default action (`:install`).' +syntax_full_code_block: |- + windows_package 'name' do + checksum String + environment Hash + installer_type Symbol + options String + package_name String + remote_file_attributes Hash + returns String, Integer, Array + source String # default value: "The resource block's name" + timeout String, Integer # default value: "600 (seconds)" + version String, Array + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_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." +- "`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) + :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: 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).' +- property: options + ruby_type: String + required: false + description_list: + - markdown: One (or more) additional options that are passed to the command. +- property: package_name + ruby_type: String + required: false + description_list: + - markdown: An optional property to set the package name if it differs from the + resource block's name. +- property: remote_file_attributes + ruby_type: Hash + required: false + description_list: + - markdown: If the source package to install is at a remote location, this property + 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 + required: false + default_value: 0 (success) and 3010 (success where a reboot is necessary) + description_list: + - markdown: A comma-delimited list of return codes that indicate the success or + failure of the package command that was run. +- property: source + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - 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 + default_value: 600 (seconds) + description_list: + - markdown: The amount of time (in seconds) to wait before timing out. +- property: version + 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**: + + ```ruby + windows_package '7zip' do + action :install + source 'C:\7z920.msi' + end + ``` + + **Specify a URL for the source attribute**: + + ```ruby + windows_package '7zip' do + source 'http://www.7-zip.org/a/7z938-x64.msi' + end + ``` + + **Specify path and checksum**: + + ```ruby + windows_package '7zip' do + source 'http://www.7-zip.org/a/7z938-x64.msi' + checksum '7c8e873991c82ad9cfcdbdf45254ea6101e9a645e12977dcd518979e50fdedf3' + end + ``` + + **Modify remote_file resource attributes**: + + The windows_package resource may specify a package at a remote location using the remote_file_attributes property. This uses the remote_file resource to download the contents at the specified URL and passes in a Hash that modifies the properties of the remote_file resource. + + ```ruby + windows_package '7zip' do + source 'http://www.7-zip.org/a/7z938-x64.msi' + remote_file_attributes ({ + :path => 'C:\7zip.msi', + :checksum => '7c8e873991c82ad9cfcdbdf45254ea6101e9a645e12977dcd518979e50fdedf3' + }) + end + ``` + + **Download a nsis (Nullsoft) package resource**: + + ```ruby + windows_package 'Mercurial 3.6.1 (64-bit)' do + source 'https://www.mercurial-scm.org/release/windows/Mercurial-3.6.1-x64.exe' + checksum 'febd29578cb6736163d232708b834a2ddd119aa40abc536b2c313fc5e1b5831d' + end + ``` + + **Download a custom package**: + + ```ruby + windows_package 'Microsoft Visual C++ 2005 Redistributable' do + source 'https://download.microsoft.com/download/6/B/B/6BB661D6-A8AE-4819-B79F-236472F6070C/vcredist_x86.exe' + installer_type :custom + options '/Q' + end + ``` diff --git a/data/infra/resources/windows_pagefile.yaml b/data/infra/resources/windows_pagefile.yaml new file mode 100644 index 0000000..7622ba2 --- /dev/null +++ b/data/infra/resources/windows_pagefile.yaml @@ -0,0 +1,101 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_pagefile +resource_description_list: +- markdown: Use the **windows_pagefile** resource to configure pagefile settings on + Windows. +resource_new_in: '14.0' +syntax_full_code_block: |- + windows_pagefile 'name' do + automatic_managed true, false + initial_size Integer + maximum_size Integer + path String # default value: 'name' unless specified + system_managed true, false + action Symbol # defaults to :set if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_pagefile` 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." +- "`automatic_managed`, `initial_size`, `maximum_size`, `path`, and `system_managed` + are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :set: + markdown: Configures the default pagefile, creating if it doesn't exist. (default) + :delete: + markdown: Deletes the specified pagefile. +properties_list: +- property: automatic_managed + ruby_type: true, false + required: false + description_list: + - markdown: Enable automatic management of pagefile initial and maximum size. Setting + this to true ignores `initial_size` and `maximum_size` properties. +- property: initial_size + ruby_type: Integer + required: false + description_list: + - markdown: Initial size of the pagefile in megabytes. +- property: maximum_size + ruby_type: Integer + required: false + description_list: + - markdown: Maximum size of the pagefile in megabytes. +- property: path + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the pagefile name if it differs from the + resource block's name. +- property: system_managed + ruby_type: true, false + required: false + description_list: + - markdown: Configures whether the system manages the pagefile size. +target_mode: +examples: | + **Set the system to manage pagefiles**: + + ```ruby + windows_pagefile 'Enable automatic management of pagefiles' do + automatic_managed true + end + ``` + + **Delete a pagefile**: + + ```ruby + windows_pagefile 'Delete the pagefile' do + path 'C' + action :delete + end + ``` + + **Switch to system managed pagefiles**: + + ```ruby + windows_pagefile 'Change the pagefile to System Managed' do + path 'E:\' + system_managed true + action :set + end + ``` + + **Create a pagefile with an initial and maximum size**: + + ```ruby + windows_pagefile 'create the pagefile with these sizes' do + path 'f:\' + initial_size 100 + maximum_size 200 + end + ``` diff --git a/data/infra/resources/windows_path.yaml b/data/infra/resources/windows_path.yaml new file mode 100644 index 0000000..17df3cf --- /dev/null +++ b/data/infra/resources/windows_path.yaml @@ -0,0 +1,54 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_path +resource_description_list: +- markdown: Use the **windows_path** resource to manage the path environment variable + on Microsoft Windows. +resource_new_in: '13.4' +syntax_full_code_block: |- + windows_path 'name' do + path String # default value: 'name' unless specified + action Symbol # defaults to :add if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_path` 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." +- "`path` is the property available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :add: + markdown: Add an item to the system path. (default) + :remove: + markdown: Remove an item from the system path. +properties_list: +- property: path + ruby_type: String + required: false + default_value: The resource block's name + 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**: + + ```ruby + windows_path 'C:\Sysinternals' do + action :add + end + ``` + + **Remove 7-Zip from the system path**: + + ```ruby + windows_path 'C:\7-Zip' do + action :remove + end + ``` diff --git a/data/infra/resources/windows_printer.yaml b/data/infra/resources/windows_printer.yaml new file mode 100644 index 0000000..97bfdc2 --- /dev/null +++ b/data/infra/resources/windows_printer.yaml @@ -0,0 +1,141 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_printer +resource_description_list: +- markdown: Use the **windows_printer** resource to setup Windows printers. This resource + will automatically install the driver specified in the `driver_name` property + and will automatically create a printer port using either the `ipv4_address` property + or the `port_name` property. +resource_new_in: '14.0' +syntax_full_code_block: |- + windows_printer 'name' do + comment String + create_port true, false # default value: true + default true, false # default value: false + device_id String # default value: 'name' unless specified + driver_name String + ipv4_address String + location String + port_name String + share_name String + shared true, false # default value: false + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_printer` 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." +- "`comment`, `create_port`, `default`, `device_id`, `driver_name`, `ipv4_address`, + `location`, `port_name`, `share_name`, and `shared` are the properties available + to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Create a new printer and printer port, if one doesn't already. (default) + :delete: + markdown: Delete an existing printer. Note that this resource does not delete + the associated printer port. +properties_list: +- property: comment + ruby_type: String + required: false + description_list: + - markdown: Optional descriptor for the printer queue. +- property: create_port + ruby_type: true, false + required: false + default_value: 'true' + new_in: '17.3' + description_list: + - markdown: Create a printer port for the printer. Set this to false and specify + the `port_name` property if using the `windows_printer_port` resource to create + the port instead. +- property: default + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Determines whether or not this should be the system's default printer. +- property: device_id + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: 'An optional property to set the printer queue name if it differs from + the resource block''s name. Example: `HP LJ 5200 in fifth floor copy room`.' +- property: driver_name + ruby_type: String + required: true + description_list: + - markdown: The exact name of printer driver installed on the system. +- property: ipv4_address + ruby_type: String + required: false + description_list: + - markdown: The IPv4 address of the printer, such as `10.4.64.23` +- property: location + ruby_type: String + required: false + description_list: + - markdown: Printer location, such as `Fifth floor copy room`. +- property: port_name + ruby_type: String + required: false + default_value: The resource block name or the ipv4_address prepended with IP_. + new_in: '17.3' + description_list: + - markdown: The port name. +- property: share_name + ruby_type: String + required: false + description_list: + - markdown: The name used to identify the shared printer. +- property: shared + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Determines whether or not the printer is shared. +target_mode: +examples: | + **Create a printer**: + + ```ruby + windows_printer 'HP LaserJet 5th Floor' do + driver_name 'HP LaserJet 4100 Series PCL6' + ipv4_address '10.4.64.38' + end + ``` + + **Delete a printer**: + + Note: this doesn't delete the associated printer port. See windows_printer_port above for how to delete the port. + + ```ruby + windows_printer 'HP LaserJet 5th Floor' do + action :delete + end + ``` + + **Create a printer port and a printer that uses that port (new in 17.3)** + + ```ruby + windows_printer_port '10.4.64.39' do + port_name 'My awesome printer port' + snmp_enabled true + port_protocol 2 + end + + windows_printer 'HP LaserJet 5th Floor' do + driver_name 'HP LaserJet 4100 Series PCL6' + port_name 'My awesome printer port' + ipv4_address '10.4.64.38' + create_port false + end + ``` diff --git a/data/infra/resources/windows_printer_port.yaml b/data/infra/resources/windows_printer_port.yaml new file mode 100644 index 0000000..84ff763 --- /dev/null +++ b/data/infra/resources/windows_printer_port.yaml @@ -0,0 +1,95 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_printer_port +resource_description_list: +- markdown: Use the **windows_printer_port** resource to create and delete TCP/IPv4 + printer ports on Windows. +resource_new_in: '14.0' +syntax_full_code_block: |- + windows_printer_port 'name' do + ipv4_address String # default value: 'name' unless specified + port_name String + port_number Integer # default value: 9100 + port_protocol Integer # default value: 1 + snmp_enabled true, false # default value: false + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_printer_port` 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." +- "`ipv4_address`, `port_name`, `port_number`, `port_protocol`, and `snmp_enabled` + are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Create or update the printer port. (default) + :delete: + markdown: Delete an existing printer port. +properties_list: +- property: ipv4_address + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property for the IPv4 address of the printer if it differs + from the resource block's name. +- property: port_name + ruby_type: String + required: false + default_value: The resource block name or the ipv4_address prepended with IP_. + description_list: + - markdown: The port name. +- property: port_number + ruby_type: Integer + required: false + default_value: '9100' + description_list: + - markdown: The TCP port number. +- property: port_protocol + ruby_type: Integer + required: false + default_value: '1' + allowed_values: 1, 2 + description_list: + - markdown: 'The printer port protocol: 1 (RAW) or 2 (LPR).' +- property: snmp_enabled + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Determines if SNMP is enabled on the port. +target_mode: +examples: | + **Delete a printer port** + + ```ruby + windows_printer_port '10.4.64.37' do + action :delete + end + ``` + + **Delete a port with a custom port_name** + + ```ruby + windows_printer_port '10.4.64.38' do + port_name 'My awesome port' + action :delete + end + ``` + + **Create a port with more options** + + ```ruby + windows_printer_port '10.4.64.39' do + port_name 'My awesome port' + snmp_enabled true + port_protocol 2 + end + ``` diff --git a/data/infra/resources/windows_security_policy.yaml b/data/infra/resources/windows_security_policy.yaml new file mode 100644 index 0000000..797967a --- /dev/null +++ b/data/infra/resources/windows_security_policy.yaml @@ -0,0 +1,74 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_security_policy +resource_description_list: +- markdown: Use the **windows_security_policy** resource to set a security policy + on the Microsoft Windows platform. +resource_new_in: '16.0' +syntax_full_code_block: |- + windows_security_policy 'name' do + secoption String # default value: 'name' unless specified + secvalue String + action Symbol # defaults to :set if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_security_policy` 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." +- "`secoption` and `secvalue` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :set: + markdown: Set the Windows security policy (default) +properties_list: +- property: secoption + ruby_type: String + required: true + default_value: The resource block's name + allowed_values: '"AuditPolicyChange", "ClearTextPassword", "EnableAdminAccount", + "EnableGuestAccount", "ForceLogoffWhenHourExpire", "LSAAnonymousNameLookup", "LockoutBadCount", + "LockoutDuration", "LockoutDuration", "MaximumPasswordAge", "MinimumPasswordAge", + "MinimumPasswordLength", "NewAdministratorName", "NewGuestName", "PasswordComplexity", + "PasswordHistorySize", "RequireLogonToChangePassword", "ResetLockoutCount"' + description_list: + - markdown: The name of the policy to be set on windows platform to maintain its + security. +- property: secvalue + ruby_type: String + required: true + description_list: + - markdown: Policy value to be set for policy name. +target_mode: +examples: | + **Set Administrator Account to Enabled**: + + ```ruby + windows_security_policy 'EnableAdminAccount' do + secvalue '1' + action :set + end + ``` + + **Rename Administrator Account**: + + ```ruby + windows_security_policy 'NewAdministratorName' do + secvalue 'AwesomeChefGuy' + action :set + end + ``` + + **Set Guest Account to Disabled**: + + ```ruby + windows_security_policy 'EnableGuestAccount' do + secvalue '0' + action :set + end + ``` diff --git a/data/infra/resources/windows_service.yaml b/data/infra/resources/windows_service.yaml new file mode 100644 index 0000000..50acf55 --- /dev/null +++ b/data/infra/resources/windows_service.yaml @@ -0,0 +1,379 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_service +resource_description_list: +- markdown: Use the **windows_service** resource to create, delete, or manage a service + on the Microsoft Windows platform. +syntax_description: "A **windows_service** resource block manages the state of a service\ + \ on\na machine that is running Microsoft Windows. For example:\n\n```ruby\nwindows_service\ + \ 'BITS' do\n action :configure_startup\n startup_type :manual\nend\n```" +resource_new_in: '12.0' +syntax_full_code_block: |- + windows_service 'name' do + binary_path_name String + delayed_start true, false # default value: false + dependencies String, Array + description String + 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 + startup_type Symbol # default value: :automatic + status_command String, false + 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: +syntax_full_properties_list: +- "`windows_service` 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." +- "`binary_path_name`, `delayed_start`, `dependencies`, `description`, `desired_access`, + `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: + markdown: "Configure a pre-existing service.\n *New in Chef Client 14.0.*" + :configure_startup: + markdown: Configure a service based on the value of the `startup_type` property. + :create: + markdown: "Create the service based on the value of the `binary_path_name`, `service_name`\ + \ and/or `display_name` property.\n *New in Chef Client 14.0.*" + :delete: + markdown: "Delete the service based on the value of the `service_name` property.\n\ + \ *New in Chef Client 14.0.*" + :disable: + markdown: Disable a service. This action is equivalent to a `Disabled` startup + type on the Microsoft Windows platform. + :enable: + markdown: Enable a service at boot. This action is equivalent to an `Automatic` + startup type on the Microsoft Windows platform. + :nothing: + shortcode: resources_common_actions_nothing.md + :reload: + markdown: Reload the configuration for this service. This action is not supported + on the Windows platform and will raise an error if used. + :restart: + markdown: Restart a service. + :start: + markdown: Start a service, and keep it running until stopped or disabled. + :stop: + markdown: Stop a service. +properties_list: +- property: binary_path_name + ruby_type: String + required: false + new_in: '14.0' + description_list: + - markdown: The fully qualified path to the service binary file. The path can also + include arguments for an auto-start service. This is required for `:create` + and `:configure` actions +- property: delayed_start + ruby_type: true, false + required: false + default_value: 'false' + new_in: '14.0' + description_list: + - markdown: Set the startup type to delayed start. This only applies if `startup_type` + is `:automatic` +- property: dependencies + ruby_type: String, Array + required: false + new_in: '14.0' + description_list: + - markdown: A pointer to a double null-terminated array of null-separated names + of services or load ordering groups that the system must start before this service. + Specify `nil` or an empty string if the service has no dependencies. Dependency + on a group means that this service can run if at least one member of the group + is running after an attempt to start all members of the group. +- property: description + ruby_type: String + required: false + new_in: '14.0' + description_list: + - markdown: Description of the service. +- property: desired_access + ruby_type: Integer + required: false + default_value: '983551' + new_in: '14.0' + description_list: + - markdown: +- property: display_name + ruby_type: String + required: false + new_in: '14.0' + description_list: + - markdown: The display name to be used by user interface programs to identify the + service. This string has a maximum length of 256 characters. +- property: error_control + ruby_type: Integer + required: false + default_value: '1' + 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 + description_list: + - markdown: The command used to tell a service to reload its configuration. +- property: restart_command + ruby_type: String, false + required: false + description_list: + - markdown: The command used to restart a service. +- property: run_as_password + ruby_type: String + required: false + description_list: + - markdown: The password for the user specified by `run_as_user`. +- property: run_as_user + ruby_type: String + required: false + 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 + default_value: The resource block's name + description_list: + - markdown: An optional property to set the service name if it differs from the + resource block's name. +- property: service_type + ruby_type: Integer + required: false + default_value: '16' + new_in: '14.0' + description_list: + - markdown: +- property: start_command + ruby_type: String, false + required: false + description_list: + - markdown: The command used to start a service. +- property: startup_type + ruby_type: Symbol + required: false + default_value: ":automatic" + allowed_values: ":automatic, :disabled, :manual" + description_list: + - markdown: Use to specify the startup type of the service. +- property: status_command + ruby_type: String, false + required: false + description_list: + - markdown: The command used to check the run status for a service. +- property: stop_command + ruby_type: String, false + required: false + description_list: + - markdown: The command used to stop a service. +- property: supports + ruby_type: Hash + 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, + 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** + + Start a service with a `manual` startup type: + + ```ruby + windows_service 'BITS' do + action :configure_startup + startup_type :manual + end + ``` + + **Creating Services** + + Create a service named chef-client: + + ```ruby + windows_service 'chef-client' do + action :create + binary_path_name "C:\opscode\chef\bin" + end + ``` + + Create a service with `service_name` and `display_name`: + + ```ruby + windows_service 'Setup chef-client as a service' do + action :create + display_name 'CHEF-CLIENT' + service_name 'chef-client' + binary_path_name "C:\opscode\chef\bin" + end + ``` + + Create a service with the `manual` startup type: + + ```ruby + windows_service 'chef-client' do + action :create + binary_path_name "C:\opscode\chef\bin" + startup_type :manual + end + ``` + + Create a service with the `disabled` startup type: + + ```ruby + windows_service 'chef-client' do + action :create + binary_path_name "C:\opscode\chef\bin" + startup_type :disabled + end + ``` + + Create a service with the `automatic` startup type and delayed start enabled: + + ```ruby + windows_service 'chef-client' do + action :create + binary_path_name "C:\opscode\chef\bin" + startup_type :automatic + delayed_start true + end + ``` + + Create a service with a description: + + ```ruby + windows_service 'chef-client' do + action :create + binary_path_name "C:\opscode\chef\bin" + startup_type :automatic + description "Chef client as service" + end + ``` + + **Deleting Services** + + Delete a service named chef-client: + + ```ruby + windows_service 'chef-client' do + action :delete + end + ``` + + Delete a service with the `service_name` property: + + ```ruby + windows_service 'Delete chef client' do + action :delete + service_name 'chef-client' + end + ``` + + **Configuring Services** + + Change an existing service from automatic to manual startup: + + ```ruby + windows_service 'chef-client' do + action :configure + binary_path_name "C:\opscode\chef\bin" + startup_type :manual + end + ``` diff --git a/data/infra/resources/windows_share.yaml b/data/infra/resources/windows_share.yaml new file mode 100644 index 0000000..dd6a61a --- /dev/null +++ b/data/infra/resources/windows_share.yaml @@ -0,0 +1,139 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_share +resource_description_list: +- markdown: Use the **windows_share** resource to create, modify and remove Windows + shares. +resource_new_in: '14.7' +syntax_full_code_block: |- + windows_share 'name' do + ca_timeout Integer # default value: 0 + change_users Array # default value: [] + concurrent_user_limit Integer # default value: 0 + continuously_available true, false # default value: false + description String + encrypt_data true, false # default value: false + full_users Array # default value: [] + path String + read_users Array # default value: [] + scope_name String # default value: "*" + share_name String # default value: 'name' unless specified + temporary true, false # default value: false + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_share` 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." +- "`ca_timeout`, `change_users`, `concurrent_user_limit`, `continuously_available`, + `description`, `encrypt_data`, `full_users`, `path`, `read_users`, `scope_name`, + `share_name`, and `temporary` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Create or modify a Windows share. (default) + :delete: + markdown: Delete an existing Windows share. +properties_list: +- property: ca_timeout + ruby_type: Integer + required: false + default_value: '0' + description_list: + - markdown: The continuous availability time-out for the share. +- property: change_users + ruby_type: Array + required: false + default_value: "[]" + description_list: + - markdown: The users that should have 'modify' permission on the share in domain\username + format. +- property: concurrent_user_limit + ruby_type: Integer + required: false + default_value: '0' + description_list: + - markdown: The maximum number of concurrently connected users the share can accommodate. +- property: continuously_available + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Indicates that the share is continuously available. +- property: description + ruby_type: String + required: false + description_list: + - markdown: The description to be applied to the share. +- property: encrypt_data + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Indicates that the share is encrypted. +- property: full_users + ruby_type: Array + required: false + default_value: "[]" + description_list: + - markdown: The users that should have 'Full control' permissions on the share in + domain\username format. +- property: path + ruby_type: String + required: false + description_list: + - markdown: The path of the folder to share. Required when creating. If the share + already exists on a different path then it is deleted and re-created. +- property: read_users + ruby_type: Array + required: false + default_value: "[]" + description_list: + - markdown: The users that should have 'read' permission on the share in domain\username + format. +- property: scope_name + ruby_type: String + required: false + default_value: "*" + description_list: + - markdown: The scope name of the share. +- property: share_name + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the share name if it differs from the resource + block's name. +- property: temporary + ruby_type: true, false + required: false + default_value: 'false' + 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**: + + ```ruby + windows_share 'foo' do + action :create + path 'C:\foo' + full_users ['DOMAIN_A\some_user', 'DOMAIN_B\some_other_user'] + read_users ['DOMAIN_C\Domain users'] + end + ``` + + **Delete a share**: + + ```ruby + windows_share 'foo' do + action :delete + end + ``` diff --git a/data/infra/resources/windows_shortcut.yaml b/data/infra/resources/windows_shortcut.yaml new file mode 100644 index 0000000..70fa5b2 --- /dev/null +++ b/data/infra/resources/windows_shortcut.yaml @@ -0,0 +1,77 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_shortcut +resource_description_list: +- markdown: Use the **windows_shortcut** resource to create shortcut files on Windows. +resource_new_in: '14.0' +syntax_full_code_block: |- + windows_shortcut 'name' do + arguments String + cwd String + description String + iconlocation String + shortcut_name String # default value: 'name' unless specified + target String + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_shortcut` 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." +- "`arguments`, `cwd`, `description`, `iconlocation`, `shortcut_name`, and `target` + are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Create or modify a Windows shortcut. (default) +properties_list: +- property: arguments + ruby_type: String + required: false + description_list: + - markdown: Arguments to pass to the target when the shortcut is executed. +- property: cwd + ruby_type: String + required: false + description_list: + - markdown: Working directory to use when the target is executed. +- property: description + ruby_type: String + required: false + description_list: + - markdown: The description of the shortcut +- property: iconlocation + ruby_type: String + required: false + description_list: + - markdown: Icon to use for the shortcut. Accepts the format of `path, index`, where + index is the icon file to use. See Microsoft's [documentation](https://msdn.microsoft.com/en-us/library/3s9bx7at.aspx) + for details +- property: shortcut_name + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the shortcut name if it differs from the + resource block's name. +- property: target + ruby_type: String + required: false + description_list: + - markdown: The destination that the shortcut links to. +target_mode: +examples: | + **Create a shortcut with a description**: + + ```ruby + windows_shortcut 'C:\shortcut_dir.lnk' do + target 'C:\original_dir' + description 'Make a shortcut to C:\original_dir' + end + ``` diff --git a/data/infra/resources/windows_task.yaml b/data/infra/resources/windows_task.yaml new file mode 100644 index 0000000..d9e3c7e --- /dev/null +++ b/data/infra/resources/windows_task.yaml @@ -0,0 +1,351 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_task +resource_description_list: +- markdown: Use the **windows_task** resource to create, delete or run a Windows scheduled + task. +resource_new_in: '13.0' +syntax_full_code_block: |- + windows_task 'name' do + backup Integer, false # default value: 5 + command String + cwd String + day String, Integer + description String + disallow_start_if_on_batteries true, false # default value: false + execution_time_limit String, Integer # default value: "PT72H (72 hours in ISO8601 duration format)" + force true, false # default value: false + frequency Symbol + frequency_modifier Integer, String # default value: 1 + idle_time Integer + interactive_enabled true, false # default value: false + minutes_duration String, Integer + minutes_interval String, Integer + months String + password String + priority Integer # default value: 7 + random_delay String, Integer + run_level Symbol # default value: :limited + start_day String # default value: The current date. + start_time String + start_when_available true, false # default value: false + stop_if_going_on_batteries true, false # default value: false + task_name String # default value: 'name' unless specified + user String # default value: The localized SYSTEM user for the node. + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_task` 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." +- "`backup`, `command`, `cwd`, `day`, `description`, `disallow_start_if_on_batteries`, + `execution_time_limit`, `force`, `frequency`, `frequency_modifier`, `idle_time`, + `interactive_enabled`, `minutes_duration`, `minutes_interval`, `months`, `password`, + `priority`, `random_delay`, `run_level`, `start_day`, `start_time`, `start_when_available`, + `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. + :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 + required: false + default_value: '5' + new_in: '17.0' + description_list: + - markdown: Number of backups to keep of the task when modified/deleted. Set to + false to disable backups. +- property: command + ruby_type: String + required: false + description_list: + - markdown: The command to be executed by the windows scheduled task. +- property: cwd + ruby_type: String + required: false + description_list: + - markdown: The directory the task will be run from. +- property: day + ruby_type: String, Integer + required: false + description_list: + - markdown: |- + The day(s) on which the task runs. + * Use this property when setting `frequency` to `:monthly` or `:weekly`. + * Valid values with frequency `:weekly` are `MON`-`SUN` or `*`. + * Valid values with frequency `:monthly` are `1-31`, `MON`-`SUN`, and `LASTDAY`. + * Use `MON`-`SUN` or `LASTDAY` if you are setting `frequency_modifier` as "FIRST, SECOND, THIRD etc." else use 1-31. + * Multiple days should be comma separated. e.g `1, 2, 3` or `MON, WED, FRI`. +- property: description + ruby_type: String + required: false + new_in: '14.7' + description_list: + - markdown: The task description. +- property: disallow_start_if_on_batteries + ruby_type: true, false + required: false + default_value: 'false' + new_in: '14.4' + description_list: + - markdown: Disallow start of the task if the system is running on battery power. +- property: execution_time_limit + ruby_type: String, Integer + required: false + default_value: PT72H (72 hours in ISO8601 duration format) + description_list: + - markdown: The maximum time the task will run. This field accepts either seconds + or an ISO8601 duration value. +- property: force + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: When used with create, will update the task. +- property: frequency + ruby_type: Symbol + required: false + allowed_values: ":daily, :hourly, :minute, :monthly, :none, :on_idle, :on_logon, + :once, :onstart, :weekly" + description_list: + - markdown: The frequency with which to run the task. + - note: + markdown: This property is required in Chef Infra Client 14.1 or later. + - note: + markdown: The `:once` value requires the `start_time` property to be set. +- property: frequency_modifier + ruby_type: Integer, String + required: false + default_value: '1' + description_list: + - markdown: |- + * For frequency `:minute` valid values are 1 to 1439 + * For frequency `:hourly` valid values are 1 to 23 + * For frequency `:daily` valid values are 1 to 365 + * For frequency `:weekly` valid values are 1 to 52 + * For frequency `:monthly` valid values are `('FIRST', 'SECOND', 'THIRD', 'FOURTH', 'LAST')` OR `1-12`. + * e.g. If user want to run the task on `second week of the month` use `frequency_modifier` value as `SECOND`. Multiple values for weeks of the month should be comma separated e.g. `"FIRST, THIRD, LAST"`. + * To run task every (n) months use values 1 to 12. +- property: idle_time + ruby_type: Integer + required: false + description_list: + - markdown: For `:on_idle` frequency, the time (in minutes) without user activity + that must pass to trigger the task, from `1` - `999`. +- property: interactive_enabled + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Allow task to run interactively or non-interactively. Requires user + and password to also be set. +- property: minutes_duration + ruby_type: String, Integer + required: false + description_list: [] +- property: minutes_interval + ruby_type: String, Integer + required: false + description_list: [] +- property: months + ruby_type: String + required: false + description_list: + - markdown: 'The Months of the year on which the task runs, such as: `JAN, FEB` + or `*`. Multiple months should be comma delimited. e.g. `Jan, Feb, Mar, Dec`.' +- property: password + ruby_type: String + required: false + description_list: + - markdown: The user's password. The user property must be set if using this property. +- property: priority + ruby_type: Integer + required: false + default_value: '7' + description_list: + - markdown: Use to set Priority Levels range from 0 to 10. +- property: random_delay + ruby_type: String, Integer + required: false + description_list: + - markdown: Delays the task up to a given time (in seconds). +- property: run_level + ruby_type: Symbol + required: false + default_value: ":limited" + allowed_values: ":highest, :limited" + description_list: + - markdown: Run with `:limited` or `:highest` privileges. +- property: start_day + ruby_type: String + required: false + default_value: The current date. + description_list: + - markdown: Specifies the first date on which the task runs in **MM/DD/YYYY** format. +- property: start_time + ruby_type: String + required: false + description_list: + - markdown: Specifies the start time to run the task, in **HH:mm** format. +- property: start_when_available + ruby_type: true, false + required: false + default_value: 'false' + new_in: '14.15' + description_list: + - markdown: To start the task at any time after its scheduled time has passed. +- property: stop_if_going_on_batteries + ruby_type: true, false + required: false + default_value: 'false' + new_in: '14.4' + description_list: + - markdown: Scheduled task option when system is switching on battery. +- property: task_name + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: 'An optional property to set the task name if it differs from the resource + block''s name. Example: `Task Name` or `/Task Name`' +- property: user + ruby_type: String + required: false + 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**: + + ```ruby + windows_task 'chef-client' do + user 'Administrator' + password 'password' + command 'chef-client' + run_level :highest + frequency :minute + frequency_modifier 15 + end + ``` + + **Create a scheduled task to run every 2 days**: + + ```ruby + windows_task 'chef-client' do + command 'chef-client' + run_level :highest + frequency :daily + frequency_modifier 2 + end + ``` + + **Create a scheduled task to run on specific days of the week**: + + ```ruby + windows_task 'chef-client' do + command 'chef-client' + run_level :highest + frequency :weekly + day 'Mon, Thu' + end + ``` + + **Create a scheduled task to run only once**: + + ```ruby + windows_task 'chef-client' do + command 'chef-client' + run_level :highest + frequency :once + start_time '16:10' + end + ``` + + **Create a scheduled task to run on current day every 3 weeks and delay upto 1 min**: + + ```ruby + windows_task 'chef-client' do + command 'chef-client' + run_level :highest + frequency :weekly + frequency_modifier 3 + random_delay '60' + end + ``` + + **Create a scheduled task to run weekly starting on Dec 28th 2018**: + + ```ruby + windows_task 'chef-client 8' do + command 'chef-client' + run_level :highest + frequency :weekly + start_day '12/28/2018' + end + ``` + + **Create a scheduled task to run every Monday, Friday every 2 weeks**: + + ```ruby + windows_task 'chef-client' do + command 'chef-client' + run_level :highest + frequency :weekly + frequency_modifier 2 + day 'Mon, Fri' + end + ``` + + **Create a scheduled task to run when computer is idle with idle duration 20 min**: + + ```ruby + windows_task 'chef-client' do + command 'chef-client' + run_level :highest + frequency :on_idle + idle_time 20 + end + ``` + + **Delete a task named "old task"**: + ```ruby + windows_task 'old task' do + action :delete + end + ``` + + **Enable a task named "chef-client"**: + ```ruby + windows_task 'chef-client' do + action :enable + end + ``` + + **Disable a task named "ProgramDataUpdater" with TaskPath "\Microsoft\Windows\Application Experience\ProgramDataUpdater"** + ```ruby + windows_task '\Microsoft\Windows\Application Experience\ProgramDataUpdater' do + action :disable + end + ``` diff --git a/data/infra/resources/windows_uac.yaml b/data/infra/resources/windows_uac.yaml new file mode 100644 index 0000000..013d7d1 --- /dev/null +++ b/data/infra/resources/windows_uac.yaml @@ -0,0 +1,95 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_uac +resource_description_list: +- markdown: The *windows_uac* resource configures UAC on Windows hosts by setting + registry keys at `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System` +resource_new_in: '15.0' +syntax_full_code_block: |- + windows_uac 'name' do + consent_behavior_admins Symbol # default value: :prompt_for_consent_non_windows_binaries + consent_behavior_users Symbol # default value: :prompt_for_creds + detect_installers true, false + enable_uac true, false # default value: true + prompt_on_secure_desktop true, false # default value: true + require_signed_binaries true, false # default value: false + action Symbol # defaults to :configure if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_uac` 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." +- "`consent_behavior_admins`, `consent_behavior_users`, `detect_installers`, `enable_uac`, + `prompt_on_secure_desktop`, and `require_signed_binaries` are the properties available + to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :configure: + markdown: Configures UAC by setting registry keys at `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System`. + (default) +properties_list: +- property: consent_behavior_admins + ruby_type: Symbol + required: false + default_value: ":prompt_for_consent_non_windows_binaries" + allowed_values: ":no_prompt, :prompt_for_consent, :prompt_for_consent_non_windows_binaries, + :prompt_for_creds, :secure_prompt_for_consent, :secure_prompt_for_creds" + description_list: + - markdown: Behavior of the elevation prompt for administrators in Admin Approval + Mode. Sets HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System\EnableLUA\ConsentPromptBehaviorAdmin. +- property: consent_behavior_users + ruby_type: Symbol + required: false + default_value: ":prompt_for_creds" + allowed_values: ":auto_deny, :prompt_for_creds, :secure_prompt_for_creds" + description_list: + - markdown: Behavior of the elevation prompt for standard users. Sets HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System\EnableLUA\ConsentPromptBehaviorUser. +- property: detect_installers + ruby_type: true, false + required: false + description_list: + - markdown: Detect application installations and prompt for elevation. Sets HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System\EnableLUA\EnableInstallerDetection. +- property: enable_uac + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Enable or disable UAC Admin Approval Mode. If this is changed a system + restart is required. Sets HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System\EnableLUA. +- property: prompt_on_secure_desktop + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Switch to the secure desktop when prompting for elevation. Sets HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System\EnableLUA\PromptOnSecureDesktop. +- property: require_signed_binaries + ruby_type: true, false + required: false + 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**: + + ```ruby + windows_uac 'Disable UAC prompts for the admin' do + enable_uac true + prompt_on_secure_desktop false + consent_behavior_admins :no_prompt + end + ``` + + **Disable UAC entirely**: + + ```ruby + windows_uac 'Disable UAC entirely' do + enable_uac false + end + ``` diff --git a/data/infra/resources/windows_update_settings.yaml b/data/infra/resources/windows_update_settings.yaml new file mode 100644 index 0000000..7b0cab1 --- /dev/null +++ b/data/infra/resources/windows_update_settings.yaml @@ -0,0 +1,152 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_update_settings +resource_description_list: +- markdown: Use the **windows_update_settings** resource to manage the various Windows + Update patching options. +resource_new_in: '17.3' +syntax_full_code_block: |- + windows_update_settings 'name' do + automatic_update_option Integer, Symbol # default value: :download_and_schedule + automatically_install_minor_updates true, false # default value: false + block_windows_update_website true, false # default value: false + custom_detection_frequency Integer # default value: 22 + disable_automatic_updates true, false # default value: false + disable_os_upgrades true, false # default value: false + elevate_non_admins true, false # default value: true + enable_detection_frequency true, false # default value: false + no_reboot_with_users_logged_on true, false # default value: true + scheduled_install_day String # default value: "Everyday" + scheduled_install_hour Integer + target_wsus_group_name String + update_other_ms_products true, false # default value: true + wsus_server_url String + action Symbol # defaults to :set if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_update_settings` 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." +- "`automatic_update_option`, `automatically_install_minor_updates`, `block_windows_update_website`, + `custom_detection_frequency`, `disable_automatic_updates`, `disable_os_upgrades`, + `elevate_non_admins`, `enable_detection_frequency`, `no_reboot_with_users_logged_on`, + `scheduled_install_day`, `scheduled_install_hour`, `target_wsus_group_name`, `update_other_ms_products`, + and `wsus_server_url` are the properties available to this resource." +actions_list: + :nothing: + 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 + required: false + default_value: ":download_and_schedule" + allowed_values: ":download_and_notify, :download_and_schedule, :local_admin_decides, + :notify" + description_list: + - markdown: Control what to do when updates are found. This allows you to notify, + automatically download and notify to install, automatically download and schedule + the install, or let the local admin decide what action to take. +- property: automatically_install_minor_updates + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Automatically install minor updates. +- property: block_windows_update_website + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Block accessing the Windows Update website. +- property: custom_detection_frequency + ruby_type: Integer + required: false + default_value: '22' + description_list: + - markdown: If you decided to override the OS default detection frequency, specify + your choice here. Valid choices are 0 - 22 +- property: disable_automatic_updates + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Disable Windows Update. +- property: disable_os_upgrades + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Disable OS upgrades. +- property: elevate_non_admins + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Allow normal user accounts to temporarily be elevated to install patches. +- property: enable_detection_frequency + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Used to override the OS default of how often to check for updates +- property: no_reboot_with_users_logged_on + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Prevents the OS from rebooting while someone is on the console. +- property: scheduled_install_day + ruby_type: String + required: false + default_value: Everyday + allowed_values: '"Everyday", "Friday", "Monday", "Saturday", "Sunday", "Thursday", + "Tuesday", "Wednesday"' + description_list: + - markdown: A day of the week to tell Windows when to install updates. +- property: scheduled_install_hour + ruby_type: Integer + required: false + description_list: + - markdown: If you chose a scheduled day to install, then choose an hour on that + day for you installation +- property: target_wsus_group_name + ruby_type: String + required: false + description_list: + - markdown: Add the node to a WSUS Target Group. +- property: update_other_ms_products + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Allows for other Microsoft products to get updates too +- property: wsus_server_url + ruby_type: String + required: false + description_list: + - markdown: The URL of your WSUS server if you use one. +target_mode: +examples: | + **Set Windows Update settings**: + + ```ruby + windows_update_settings 'Settings to Configure Windows Nodes to automatically receive updates' do + disable_os_upgrades true + elevate_non_admins true + block_windows_update_website true + automatically_install_minor_updates true + scheduled_install_day 'Friday' + scheduled_install_hour 18 + update_other_ms_products true + action :enable + end + ``` diff --git a/data/infra/resources/windows_user_privilege.yaml b/data/infra/resources/windows_user_privilege.yaml new file mode 100644 index 0000000..1a96626 --- /dev/null +++ b/data/infra/resources/windows_user_privilege.yaml @@ -0,0 +1,122 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +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. +resource_new_in: '16.0' +syntax_full_code_block: |- + windows_user_privilege 'name' do + principal String # default value: 'name' unless specified + privilege Array, String + users Array, String + action Symbol # defaults to :add if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_user_privilege` 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." +- "`principal`, `privilege`, and `users` are the properties available to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :add: + 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 + privilege will be have the privilege removed. + :clear: + markdown: Clear all user privileges + :remove: + 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 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 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 +target_mode: +examples: | + **Set the SeNetworkLogonRight privilege for the Builtin Administrators and Authenticated Users groups**: + + The `:set` action will add this privilege for these two groups and remove this privilege from all other groups or users. + + ```ruby + windows_user_privilege 'Network Logon Rights' do + privilege 'SeNetworkLogonRight' + users ['BUILTIN\Administrators', 'NT AUTHORITY\Authenticated Users'] + action :set + end + ``` + + **Set the SeCreatePagefilePrivilege privilege for the Builtin Guests and Administrator groups**: + + The `:set` action will add this privilege for these two groups and remove this privilege from all other groups or users. + + ```ruby + windows_user_privilege 'Create Pagefile' do + privilege 'SeCreatePagefilePrivilege' + users ['BUILTIN\Guests', 'BUILTIN\Administrators'] + action :set + end + ``` + + **Add the SeDenyRemoteInteractiveLogonRight privilege to the 'Remote interactive logon' principal**: + + ```ruby + windows_user_privilege 'Remote interactive logon' do + privilege 'SeDenyRemoteInteractiveLogonRight' + action :add + end + ``` + + **Add the SeCreatePageFilePrivilege privilege to the Builtin Guests group**: + + ```ruby + windows_user_privilege 'Guests add Create Pagefile' do + principal 'BUILTIN\Guests' + privilege 'SeCreatePagefilePrivilege' + action :add + end + ``` + + **Remove the SeCreatePageFilePrivilege privilege from the Builtin Guests group**: + + ```ruby + windows_user_privilege 'Create Pagefile' do + privilege 'SeCreatePagefilePrivilege' + principal 'BUILTIN\Guests' + action :remove + end + ``` + + **Clear the SeDenyNetworkLogonRight privilege from all users**: + + ```ruby + windows_user_privilege 'Allow any user the Network Logon right' do + privilege 'SeDenyNetworkLogonRight' + action :clear + end + ``` diff --git a/data/infra/resources/windows_workgroup.yaml b/data/infra/resources/windows_workgroup.yaml new file mode 100644 index 0000000..3d0ffe0 --- /dev/null +++ b/data/infra/resources/windows_workgroup.yaml @@ -0,0 +1,76 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: windows_workgroup +resource_description_list: +- markdown: Use the **windows_workgroup** resource to join or change the workgroup + of a Windows host. +resource_new_in: '14.5' +syntax_full_code_block: |- + windows_workgroup 'name' do + password String + reboot Symbol # default value: :immediate + user String + workgroup_name String # default value: 'name' unless specified + action Symbol # defaults to :join if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`windows_workgroup` 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." +- "`password`, `reboot`, `user`, and `workgroup_name` are the properties available + to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :join: + markdown: Update the workgroup. (default) +properties_list: +- property: password + ruby_type: String + required: false + description_list: + - markdown: The password for the local administrator user. Required if using the + `user` property. +- property: reboot + ruby_type: Symbol + required: false + default_value: ":immediate" + allowed_values: ":never, :reboot_now, :request_reboot" + description_list: + - markdown: Controls the system reboot behavior post workgroup joining. Reboot immediately, + after the Chef Infra Client run completes, or never. Note that a reboot is necessary + for changes to take effect. +- property: user + ruby_type: String + required: false + description_list: + - markdown: The local administrator user to use to change the workgroup. Required + if using the `password` property. +- property: workgroup_name + ruby_type: String + required: false + default_value: The resource block's name + 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**: + + ```ruby + windows_workgroup 'myworkgroup' + ``` + + **Join a workgroup using a specific user**: + + ```ruby + windows_workgroup 'myworkgroup' do + user 'Administrator' + password 'passw0rd' + end + ``` diff --git a/data/infra/resources/yum_package.yaml b/data/infra/resources/yum_package.yaml new file mode 100644 index 0000000..5f22c0c --- /dev/null +++ b/data/infra/resources/yum_package.yaml @@ -0,0 +1,205 @@ +--- +resource_reference: true +multi_package_resource: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: yum_package +resource_description_list: +- markdown: Use the **yum_package** resource to install, upgrade, and remove packages + with Yum for the Red Hat and CentOS platforms. The yum_package resource is able + to resolve `provides` data for packages much like Yum can do when it is run from + the command line. This allows a variety of options for installing packages, like + minimum versions, virtual provides, and library names. +- note: + markdown: Support for using file names to install packages (as in `yum_package + '/bin/sh'`) is not available because the volume of data required to parse for + this is excessive. +- notes_resource_based_on_package: true +syntax_full_code_block: |- + yum_package 'name' do + allow_downgrade true, false # default value: true + arch String, Array + environment Hash # default value: {} + flush_cache Hash # default value: {"before"=>false, "after"=>false} + options String, Array + package_name String, Array + source String + timeout String, Integer + version String, Array + yum_binary String + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`yum_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." +- "`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) + :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: Locks the yum package to a specific version. + :unlock: + markdown: Unlocks the yum package so that it can be upgraded to a newer version. + :flush_cache: + 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: arch + ruby_type: String, Array + required: false + description_list: + - markdown: The architecture of the package to be installed or upgraded. This value + can also be passed as part of the package name. +- 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: Hash + 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 ]. + 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 + description_list: + - 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: 'One of the following: the name of a package, the name of a package + and its architecture, the name of a dependency.' +- 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 + description_list: + - markdown: The amount of time (in seconds) to wait before timing out. +- property: version + ruby_type: String, Array + required: false + description_list: + - markdown: The version of a package to be installed or upgraded. This property + is ignored when using the `:upgrade` action. +- property: yum_binary + ruby_type: String + required: false + description_list: + - markdown: The path to the yum binary. +target_mode: + support: full +examples: | + **Install an exact version**: + + ```ruby + yum_package 'netpbm = 10.35.58-8.el8' + ``` + + **Install a minimum version**: + + ```ruby + yum_package 'netpbm >= 10.35.58-8.el8' + ``` + + **Install a minimum version using the default action**: + + ```ruby + yum_package 'netpbm' + ``` + + **Install a version without worrying about the exact release**: + + ```ruby + yum_package 'netpbm-10.35*' + ``` + + + **To install a package**: + + ```ruby + yum_package 'netpbm' do + action :install + end + ``` + + **To install a partial minimum version**: + + ```ruby + yum_package 'netpbm >= 10' + ``` + + **To install a specific architecture**: + + ```ruby + yum_package 'netpbm' do + arch 'i386' + end + ``` + + or: + + ```ruby + yum_package 'netpbm.x86_64' + ``` + + **To install a specific version-release** + + ```ruby + yum_package 'netpbm' do + version '10.35.58-8.el8' + end + ``` + + **Handle cookbook_file and yum_package resources in the same recipe**: + + When a **cookbook_file** resource and a **yum_package** resource are + both called from within the same recipe, use the `flush_cache` attribute + to dump the in-memory Yum cache, and then use the repository immediately + to ensure that the correct package is installed: + + ```ruby + cookbook_file '/etc/yum.repos.d/custom.repo' do + source 'custom' + mode '0755' + end + + yum_package 'pkg-that-is-only-in-custom-repo' do + action :install + flush_cache [ :before ] + end + ``` diff --git a/data/infra/resources/yum_repository.yaml b/data/infra/resources/yum_repository.yaml new file mode 100644 index 0000000..262a6f4 --- /dev/null +++ b/data/infra/resources/yum_repository.yaml @@ -0,0 +1,405 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: yum_repository +resource_description_list: +- markdown: Use the **yum_repository** resource to manage a Yum repository configuration + file located at `/etc/yum.repos.d/repositoryid.repo` on the local machine. This + configuration file specifies which repositories to reference, how to handle cached + data, etc. +resource_new_in: '12.14' +syntax_full_code_block: |- + yum_repository 'name' do + baseurl String, Array + clean_metadata true, false # default value: true + cost String + description String # default value: "Yum Repository" + enabled true, false # default value: true + enablegroups true, false + exclude String + failovermethod String + fastestmirror_enabled true, false + gpgcheck true, false # default value: true + gpgkey String, Array + http_caching String + include_config String + includepkgs String + keepalive true, false + make_cache true, false # default value: true + makecache_fast true, false # default value: false + max_retries String, Integer + metadata_expire String + metalink String + mirror_expire String + mirrorlist String + mirrorlist_expire String + mode String, Integer # default value: "0644" + options Hash + password String + priority String + proxy String + proxy_password String + proxy_username String + repo_gpgcheck true, false + report_instanceid true, false + reposdir String # default value: "/etc/yum.repos.d/" + repositoryid String # default value: 'name' unless specified + skip_if_unavailable true, false + source String + sslcacert String + sslclientcert String + sslclientkey String + sslverify true, false + throttle String, Integer + timeout String + username String + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`yum_repository` 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." +- "`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." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Create a repository based on the properties. (default) + :remove: + markdown: + :makecache: + markdown: Force the creation of the repository cache. This is also done automatically + when a repository is updated. + :add: + markdown: + :delete: + markdown: Remove a repository. +properties_list: +- property: baseurl + ruby_type: String, Array + required: false + description_list: + - markdown: URL to the directory where the Yum repository's `repodata` directory + lives. Can be an `http://`, `https://` or a `ftp://` URLs. You can specify multiple + URLs in one `baseurl` statement. +- property: clean_metadata + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Specifies whether you want to purge all of the packages downloaded from + a Yum repository and held in a cache directory. +- property: cost + ruby_type: String + required: false + description_list: + - markdown: Relative cost of accessing this repository. Useful for weighing one + repo's packages as greater/less than any other. +- property: description + ruby_type: String + required: false + default_value: Yum Repository + description_list: + - markdown: Descriptive name for the repository channel and maps to the 'name' parameter + in a repository .conf. +- property: enabled + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Specifies whether or not Yum should use this repository. +- property: enablegroups + ruby_type: true, false + required: false + description_list: + - markdown: Specifies whether Yum will allow the use of package groups for this + repository. +- property: exclude + ruby_type: String + required: false + description_list: + - markdown: List of packages to exclude from updates or installs. This should be + a space separated list. Shell globs using wildcards (eg. * and ?) are allowed. +- property: failovermethod + ruby_type: String + required: false + allowed_values: '"priority", "roundrobin"' + description_list: + - markdown: Method to determine how to switch to a new server if the current one + fails, which can either be `roundrobin` or `priority`. `roundrobin` randomly + selects a URL out of the list of URLs to start with and proceeds through each + of them as it encounters a failure contacting the host. `priority` starts from + the first `baseurl` listed and reads through them sequentially. +- property: fastestmirror_enabled + ruby_type: true, false + required: false + description_list: + - markdown: Specifies whether to use the fastest mirror from a repository configuration + when more than one mirror is listed in that configuration. +- property: gpgcheck + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Specifies whether or not Yum should perform a GPG signature check on + the packages received from a repository. +- property: gpgkey + ruby_type: String, Array + required: false + description_list: + - markdown: |- + URL pointing to the ASCII-armored GPG key file for the repository. This is used if Yum needs a public key to verify a package and the required key hasn't been imported into the RPM database. If this option is set, Yum will automatically import the key from the specified URL. Multiple URLs may be specified in the same manner as the baseurl option. If a GPG key is required to install a package from a repository, all keys specified for that repository will be installed. + Multiple URLs may be specified in the same manner as the baseurl option. If a GPG key is required to install a package from a repository, all keys specified for that repository will be installed. +- property: http_caching + ruby_type: String + required: false + allowed_values: '"all", "none", "packages"' + description_list: + - markdown: |- + Determines how upstream HTTP caches are instructed to handle any HTTP downloads that Yum does. This option can take the following values: + - `all` means all HTTP downloads should be cached + - `packages` means only RPM package downloads should be cached, but not repository metadata downloads + - `none` means no HTTP downloads should be cached. + + The default value of `all` is recommended unless you are experiencing caching related issues. +- property: include_config + ruby_type: String + required: false + description_list: + - markdown: An external configuration file using the format `url://to/some/location`. +- property: includepkgs + ruby_type: String + required: false + description_list: + - markdown: Inverse of exclude property. This is a list of packages you want to + use from a repository. If this option lists only one package then that is all + Yum will ever see from the repository. +- property: keepalive + ruby_type: true, false + required: false + description_list: + - markdown: Determines whether or not HTTP/1.1 `keep-alive` should be used with + this repository. +- property: make_cache + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Determines whether package files downloaded by Yum stay in cache directories. + By using cached data, you can carry out certain operations without a network + connection. +- property: makecache_fast + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - 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 + required: false + description_list: + - markdown: Number of times any attempt to retrieve a file should retry before returning + an error. Setting this to `0` makes Yum try forever. +- property: metadata_expire + ruby_type: String + required: false + description_list: + - markdown: Time (in seconds) after which the metadata will expire. If the current + metadata downloaded is less than the value specified, then Yum will not update + the metadata against the repository. If you find that Yum is not downloading + information on updates as often as you would like lower the value of this option. + You can also change from the default of using seconds to using days, hours or + minutes by appending a `d`, `h` or `m` respectively. The default is six hours + to compliment yum-updates running once per hour. It is also possible to use + the word `never`, meaning that the metadata will never expire. + - note: + markdown: When using a metalink file, the metalink must always be newer than + the metadata for the repository due to the validation, so this timeout also + applies to the metalink file. +- property: metalink + ruby_type: String + required: false + description_list: + - markdown: Specifies a URL to a metalink file for the repomd.xml, a list of mirrors + for the entire repository are generated by converting the mirrors for the repomd.xml + file to a baseurl. +- property: mirror_expire + ruby_type: String + required: false + description_list: + - markdown: Time (in seconds) after which the mirrorlist locally cached will expire. + If the current mirrorlist is less than this many seconds old then Yum will not + download another copy of the mirrorlist, it has the same extra format as metadata_expire. + If you find that Yum is not downloading the mirrorlists as often as you would + like lower the value of this option. You can also change from the default of + using seconds to using days, hours or minutes by appending a `d`, `h` or `m` + respectively. +- property: mirrorlist + ruby_type: String + required: false + description_list: + - markdown: URL to a file containing a list of baseurls. This can be used instead + of or with the baseurl option. Substitution variables, described below, can + be used with this option. +- property: mirrorlist_expire + ruby_type: String + required: false + description_list: + - markdown: Specifies the time (in seconds) after which the mirrorlist locally cached + will expire. If the current mirrorlist is less than the value specified, then + Yum will not download another copy of the mirrorlist. You can also change from + the default of using seconds to using days, hours or minutes by appending a + `d`, `h` or `m` respectively. +- property: mode + ruby_type: String, Integer + required: false + default_value: '0644' + description_list: + - markdown: Permissions mode of .repo file on disk. This is useful for scenarios + where secrets are in the repo file. If this value is set to `600`, normal users + will not be able to use Yum search, Yum info, etc. +- property: options + ruby_type: Hash + required: false + description_list: + - markdown: Specifies the repository options. +- property: password + ruby_type: String + required: false + description_list: + - markdown: Password to use with the username for basic authentication. +- property: priority + ruby_type: String + required: false + description_list: + - markdown: Assigns a priority to a repository where the priority value is between + `1` and `99` inclusive. Priorities are used to enforce ordered protection of + repositories. Packages from repositories with a lower priority (higher numerical + value) will never be used to upgrade packages that were installed from a repository + with a higher priority (lower numerical value). The repositories with the lowest + numerical priority number have the highest priority. +- property: proxy + ruby_type: String + required: false + description_list: + - markdown: URL to the proxy server that Yum should use. +- property: proxy_password + ruby_type: String + required: false + description_list: + - markdown: Password for this proxy. +- property: proxy_username + ruby_type: String + required: false + description_list: + - markdown: Username to use for proxy. +- property: repo_gpgcheck + ruby_type: true, false + required: false + description_list: + - markdown: Determines whether or not Yum should perform a GPG signature check on + the repodata from this repository. +- property: report_instanceid + ruby_type: true, false + required: false + description_list: + - markdown: Determines whether to report the instance ID when using Amazon Linux + AMIs and repositories. +- property: reposdir + ruby_type: String + required: false + default_value: "/etc/yum.repos.d/" + new_in: '16.9' + description_list: + - markdown: The directory where the Yum repository files should be stored +- property: repositoryid + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the repository name if it differs from the + resource block's name. +- property: skip_if_unavailable + ruby_type: true, false + required: false + description_list: + - markdown: Allow yum to continue if this repository cannot be contacted for any + reason. +- property: source + ruby_type: String + required: false + description_list: + - markdown: Use a custom template source instead of the default one. +- property: sslcacert + ruby_type: String + required: false + description_list: + - markdown: Path to the directory containing the databases of the certificate authorities + Yum should use to verify SSL certificates. +- property: sslclientcert + ruby_type: String + required: false + description_list: + - markdown: Path to the SSL client certificate Yum should use to connect to repos/remote + sites. +- property: sslclientkey + ruby_type: String + required: false + description_list: + - markdown: Path to the SSL client key Yum should use to connect to repos/remote + sites. +- property: sslverify + ruby_type: true, false + required: false + description_list: + - markdown: Determines whether Yum will verify SSL certificates/hosts. +- property: throttle + ruby_type: String, Integer + required: false + description_list: + - markdown: Enable bandwidth throttling for downloads. +- property: timeout + ruby_type: String + required: false + description_list: + - markdown: Number of seconds to wait for a connection before timing out. Defaults + to 30 seconds. This may be too short of a time for extremely overloaded sites. +- property: username + ruby_type: String + required: false + description_list: + - markdown: Username to use for basic authentication to a repository. +target_mode: + support: full +examples: | + **Add an internal company repository**: + + ```ruby + yum_repository 'OurCo' do + description 'OurCo yum repository' + mirrorlist 'http://artifacts.ourco.org/mirrorlist?repo=ourco-8&arch=$basearch' + gpgkey 'http://artifacts.ourco.org/pub/yum/RPM-GPG-KEY-OURCO-8' + action :create + end + ``` + + **Delete a repository**: + + ```ruby + yum_repository 'CentOS-Media' do + action :delete + end + ``` diff --git a/data/infra/resources/zypper_package.yaml b/data/infra/resources/zypper_package.yaml new file mode 100644 index 0000000..79911e7 --- /dev/null +++ b/data/infra/resources/zypper_package.yaml @@ -0,0 +1,134 @@ +--- +resource_reference: true +multi_package_resource: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: zypper_package +resource_description_list: +- markdown: Use the **zypper_package** resource to install, upgrade, and remove packages + with Zypper for the SUSE Enterprise and openSUSE platforms. +- notes_resource_based_on_package: true +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 + package_name String, Array + source String + timeout String, Integer + version String, Array + action Symbol # defaults to :install if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`zypper_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." +- "`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) + :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: Locks the zypper package to a specific version. + :unlock: + markdown: Unlocks the zypper package so that it can be upgraded to a newer version. +properties_list: +- property: allow_downgrade + ruby_type: true, false + required: false + default_value: 'true' + 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 + new_in: '14.6' + description_list: + - markdown: One (or more) additional command options that are passed to the command. + For example, common zypper directives, such as `--no-recommends`. See the [zypper + man page](https://en.opensuse.org/SDB:Zypper_manual_(plain)) for the full list. +- property: gpg_check + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Verify the package's GPG signature. Can also be controlled site-wide + using the `zypper_check_gpg` config option. +- property: options + ruby_type: String, Array + required: false + description_list: + - 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: 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: The optional path to a package on the local file system. +- property: timeout + ruby_type: String, Integer + required: false + description_list: + - markdown: The amount of time (in seconds) to wait before timing out. +- property: version + ruby_type: String, Array + 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:** + + ```ruby + zypper_package 'name of package' do + action :install + end + ``` + + **Install a package using local file:** + + ```ruby + zypper_package 'jwhois' do + action :install + source '/path/to/jwhois.rpm' + end + ``` + + **Install without using recommend packages as a dependency:** + + ```ruby + package 'apache2' do + options '--no-recommends' + end + ``` diff --git a/data/infra/resources/zypper_repository.yaml b/data/infra/resources/zypper_repository.yaml new file mode 100644 index 0000000..3bcdfcb --- /dev/null +++ b/data/infra/resources/zypper_repository.yaml @@ -0,0 +1,184 @@ +--- +resource_reference: true +resources_common_guards: true +resources_common_notification: true +resources_common_properties: true +resource: zypper_repository +resource_description_list: +- markdown: Use the **zypper_repository** resource to create Zypper package repositories + on SUSE Enterprise Linux and openSUSE systems. This resource maintains full compatibility + with the **zypper_repository** resource in the existing **zypper** cookbook. +resource_new_in: '13.3' +syntax_full_code_block: |- + zypper_repository 'name' do + autorefresh true, false # default value: true + baseurl String + cookbook String # default value: "The cookbook containing the resource" + description String + enabled true, false # default value: true + gpgautoimportkeys true, false # default value: true + gpgcheck true, false # default value: true + gpgkey String, Array # default value: [] + keeppackages true, false # default value: false + mirrorlist String + mode String, Integer # default value: "0644" + path String + priority Integer # default value: 99 + refresh_cache true, false # default value: true + repo_name String # default value: 'name' unless specified + source String + type String # default value: "NONE" + action Symbol # defaults to :create if not specified + end +syntax_properties_list: +syntax_full_properties_list: +- "`zypper_repository` 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." +- "`autorefresh`, `baseurl`, `cookbook`, `description`, `enabled`, `gpgautoimportkeys`, + `gpgcheck`, `gpgkey`, `keeppackages`, `mirrorlist`, `mode`, `path`, `priority`, + `refresh_cache`, `repo_name`, `source`, and `type` are the properties available + to this resource." +actions_list: + :nothing: + shortcode: resources_common_actions_nothing.md + :create: + markdown: Add a new Zypper repository. (default) + :remove: + markdown: Remove a Zypper repository. + :add: + markdown: + :refresh: + markdown: Refresh Zypper repository. +properties_list: +- property: autorefresh + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Determines whether or not the repository should be refreshed automatically. +- property: baseurl + ruby_type: String + required: false + description_list: + - markdown: The base URL for the Zypper repository, such as `http://download.opensuse.org`. +- property: cookbook + ruby_type: String + required: false + default_value: The cookbook containing the resource + description_list: + - markdown: The cookbook to source the repository template file from. Only necessary + if you're using a custom template for the repository file. +- property: description + ruby_type: String + required: false + description_list: + - markdown: The description of the repository that will be shown by the `zypper + repos` command. +- property: enabled + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Determines whether or not the repository should be enabled. +- property: gpgautoimportkeys + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Automatically import the specified key when setting up the repository. +- property: gpgcheck + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Determines whether or not to perform a GPG signature check on the repository. +- property: gpgkey + ruby_type: String, Array + required: false + default_value: "[]" + description_list: + - markdown: The location of the repository key(s) to be imported. +- property: keeppackages + ruby_type: true, false + required: false + default_value: 'false' + description_list: + - markdown: Determines whether or not packages should be saved. +- property: mirrorlist + ruby_type: String + required: false + description_list: + - markdown: The URL of the mirror list that will be used. +- property: mode + ruby_type: String, Integer + required: false + default_value: '0644' + description_list: + - markdown: The file mode of the repository file. +- property: path + ruby_type: String + required: false + description_list: + - markdown: The relative path from the repository's base URL. +- property: priority + ruby_type: Integer + required: false + default_value: '99' + description_list: + - markdown: Determines the priority of the Zypper repository. +- property: refresh_cache + ruby_type: true, false + required: false + default_value: 'true' + description_list: + - markdown: Determines whether or not the package cache should be refreshed. +- property: repo_name + ruby_type: String + required: false + default_value: The resource block's name + description_list: + - markdown: An optional property to set the repository name if it differs from the + resource block's name. +- property: source + ruby_type: String + required: false + description_list: + - markdown: The name of the template for the repository file. Only necessary if + you're using a custom template for the repository file. +- property: type + ruby_type: String + required: false + default_value: NONE + description_list: + - markdown: Specifies the repository type. +target_mode: + support: full +examples: | + **Add the Apache repo on openSUSE Leap 15**: + + ```ruby + zypper_repository 'apache' do + baseurl 'http://download.opensuse.org/repositories/Apache' + path '/openSUSE_Leap_15.2' + type 'rpm-md' + priority '100' + end + ``` + + **Remove the repo named 'apache'**: + + ```ruby + zypper_repository 'apache' do + action :delete + end + ``` + + **Refresh the repo named 'apache'**: + + ```ruby + zypper_repository 'apache' do + action :refresh + end + ``` diff --git a/layouts/_default/infra_resource.html b/layouts/_default/infra_resource.html new file mode 100644 index 0000000..9b06130 --- /dev/null +++ b/layouts/_default/infra_resource.html @@ -0,0 +1,27 @@ +{{ define "main" }} +{{ $product := index .Params.data_path 0 }} + +{{ if eq $product "infra" }} +

+ +

+

+ This page is generated from the Chef Infra Client source code.
+ To suggest a change, edit the {{ index .Params.data_path 2 }}.rb file and submit a pull request to the Chef Infra Client repository.
+

+
+

+{{ end }} +{{ if eq $product "infra" }} +

All Infra resources page

+{{ else }} +

All {{ $product | title }} resources page

+{{ end }} + +
+ +{{ $yaml_file := index $.Site.Data (.Params.data_path) }} +{{ $partial_data := dict "yaml_file" $yaml_file "product" $product "resource_ID" "" "heading_base_level" 2 "include_resource_id" false }} +{{ partial "infra_resource_data" $partial_data }} + +{{ end }} diff --git a/layouts/_default/infra_resources_all.html b/layouts/_default/infra_resources_all.html new file mode 100644 index 0000000..7ea955a --- /dev/null +++ b/layouts/_default/infra_resources_all.html @@ -0,0 +1,21 @@ + +{{ define "main" }} + {{ $product := index .Params.data_path 0 }} + + {{ .Content }} + + {{ range $yaml_file := index $.Site.Data ( .Params.data_path )}} + {{ $resource := index $yaml_file "resource" }} + {{ $resource_ID := replace $resource "_" "-" }} + {{ if index $yaml_file "resource_reference" }} + +

{{ $resource }} resource

+

{{ $resource }} resource page

+ + {{ end }} + + {{ $partial_data := dict "yaml_file" $yaml_file "product" $product "resource_ID" $resource_ID "heading_base_level" 3 "include_resource_id" true }} + {{ partial "infra_resource_data" $partial_data }} + + {{ end }} +{{ end }} \ No newline at end of file diff --git a/layouts/partials/infra_resource_data.html b/layouts/partials/infra_resource_data.html new file mode 100644 index 0000000..6eba35d --- /dev/null +++ b/layouts/partials/infra_resource_data.html @@ -0,0 +1,674 @@ +{{ $yaml_file := .yaml_file }} +{{ $product := .product }} +{{ $resource_ID := .resource_ID }} +{{ $heading_base_level := .heading_base_level }} +{{ $include_resource_id := .include_resource_id }} + +{{ if $include_resource_id }} + {{ $resource_ID = printf "%s%s" "-" $resource_ID }} +{{ end }} + +{{ with index $yaml_file "resource_description_list" }} + {{ range . }} + {{ range $key, $value := . }} + {{ if eq $key "markdown" }} +

{{- $value | markdownify -}}

+ {{ end }} + {{ if eq $key "note" }} +
+

Note

+
+ {{ range $subkey, $subvalue := $value }} + {{ if eq $subkey "markdown" }} +

+ {{- $subvalue | markdownify -}} +

+ {{ end }} + {{ if eq $subkey "shortcode" }} +

+ {{ readFile (delimit (slice `content/reusable/md/` $subvalue ) "") | markdownify }} +

+ {{ end }} + {{ end }} +
+
+ {{ end }} + {{ if eq $key "warning" }} +
+

Warning

+
+ {{ range $subkey, $subvalue := $value }} + {{ if eq $subkey "markdown" }} +

+ {{- $subvalue | markdownify -}} +

+ {{ end }} + {{ if eq $subkey "shortcode" }} +

+ {{ readFile (delimit (slice `content/reusable/md/` $subvalue ) "") | markdownify }} +

+ {{ end }} + {{ end }} +
+
+ {{ end }} + {{ if eq $key "shortcode" }} +

+ {{ readFile (delimit (slice `content/reusable/md/` $value ) "") | markdownify }} +

+ {{ end }} + {{ if and (eq $key "notes_resource_based_on_package") (eq $value true)}} +
+

Note

+
+ {{ readFile "content/reusable/md/notes_resource_based_on_package.md" | markdownify }} +
+
+ {{ end }} + {{ end }} + {{ end }} +{{ end }} + +{{ if and ( ne (index $yaml_file "resource_new_in") "" ) ( index $yaml_file "resource_new_in" )}} + {{ if eq $product "infra" }} +

New in Chef Infra Client {{ index $yaml_file "resource_new_in" }}.

+ {{ else if ( eq $product "desktop") }} +

New in Chef Desktop {{ index $yaml_file "resource_new_in" }}.

+ {{ end }} +{{ end }} + + + +{{ with index $yaml_file "handler_types" }} + Handler Types + {{ readFile "content/reusable/md/handler_types.md" | markdownify }} + + Exception / Report + {{ readFile "content/reusable/md/handler_type_exception_report.md" | markdownify }} + {{ readFile "content/reusable/md/handler_type_exception_report_run_from_recipe.md" | markdownify }} + + Start + {{ readFile "content/reusable/md/handler_type_start.md" | markdownify }} + {{ readFile "content/reusable/md/handler_type_start_run_from_recipe.md" | markdownify }} +{{ end }} + + + +Syntax + +

{{ index $yaml_file "syntax_description" | markdownify }}

+ +{{ with index $yaml_file "syntax_code_block" }} +

{{ highlight index $yaml_file . "ruby" "" }}

+{{ end }} + +{{ with index $yaml_file "syntax_properties_list" }} +

where:

+
    + {{ range . }} +
  • {{ . | markdownify }}
    • + {{ end }} +
+{{ end }} + +{{ with index $yaml_file "syntax_full_code_block" }} +

The full syntax for all of the properties that are available to the {{ index $yaml_file "resource" }} resource is:

+

{{- highlight ( trim . "\n") "ruby" "" -}}

+{{ end }} + +{{ with index $yaml_file "syntax_full_properties_list" }} +

where:

+
    + {{ range . }} +
  • {{ . | markdownify }}
    • + {{ end }} +
+{{ end }} + +{{ with index $yaml_file "syntax_shortcode" }} + {{ readFile (delimit (slice `content/reusable/md/` . ) "") | markdownify }} +{{ end }} + +{{ with index $yaml_file "registry_key" }} + Registry Key Path Separators + {{ readFile "content/reusable/md/windows_registry_key_backslashes.md" | markdownify }} + + Chef Infra Language Methods + {{ readFile "content/reusable/md/infra_lang_method_windows_methods.md" | markdownify }} + + registry_data_exists? + {{ readFile "content/reusable/md/infra_lang_method_registry_data_exists.md" | markdownify }} + +
+

Note

+
+ {{ readFile "content/reusable/md/notes_registry_key_not_if_only_if.md" | markdownify }} +
+
+ + {{ readFile "content/reusable/md/infra_lang_method_registry_data_exists_syntax.md" | markdownify }} + + registry_get_subkeys + {{ readFile "content/reusable/md/infra_lang_method_registry_get_subkeys.md" | markdownify }} + +
+

Note

+
+ {{ readFile "content/reusable/md/notes_registry_key_not_if_only_if.md" | markdownify }} +
+
+ + {{ readFile "content/reusable/md/infra_lang_method_registry_get_subkeys_syntax.md" | markdownify }} + + registry_get_values + {{ readFile "content/reusable/md/infra_lang_method_registry_get_values.md" | markdownify }} + +
+

Note

+
+ {{ readFile "content/reusable/md/notes_registry_key_not_if_only_if.md" | markdownify }} +
+
+ + {{ readFile "content/reusable/md/infra_lang_method_registry_get_values_syntax.md" | markdownify }} + + registry_has_subkeys? + {{ readFile "content/reusable/md/infra_lang_method_registry_has_subkeys.md" | markdownify }} + +
+

Note

+
+ {{ readFile "content/reusable/md/notes_registry_key_not_if_only_if.md" | markdownify }} +
+
+ + {{ readFile "content/reusable/md/infra_lang_method_registry_has_subkeys_syntax.md" | markdownify }} + + registry_key_exists? + {{ readFile "content/reusable/md/infra_lang_method_registry_key_exists.md" | markdownify }} + +
+

Note

+
+ {{ readFile "content/reusable/md/notes_registry_key_not_if_only_if.md" | markdownify }} +
+
+ + {{ readFile "content/reusable/md/infra_lang_method_registry_key_exists_syntax.md" | markdownify }} + + registry_value_exists? + {{ readFile "content/reusable/md/infra_lang_method_registry_value_exists.md" | markdownify }} + +
+

Note

+
+ {{ readFile "content/reusable/md/notes_registry_key_not_if_only_if.md" | markdownify }} +
+
+ + {{ readFile "content/reusable/md/infra_lang_method_registry_value_exists_syntax.md" | markdownify }} + +{{ end }} + + + +{{ with index $yaml_file "nameless_apt_update" }} + Nameless + {{ readFile "content/reusable/md/nameless_apt_update.md" | markdownify }} +{{ end }} + +{{ with index $yaml_file "nameless_build_essential" }} + Nameless + {{ readFile "content/reusable/md/nameless_build_essential.md" | markdownify }} +{{ end }} + + + +{{ with index $yaml_file "resource_package_options" }} + Gem Package Options + {{ readFile "content/reusable/md/resource_package_options.md" | markdownify }} + + Specify with Hash + {{ readFile "content/reusable/md/resource_package_options_hash.md" | markdownify }} + Example + {{ readFile "content/reusable/md/resource_package_install_gem_with_hash_options.md" | markdownify }} Specify with String + {{ readFile "content/reusable/md/resource_package_options_string.md" | markdownify }} + Example + {{ readFile "content/reusable/md/resource_package_install_gem_with_options_string.md" | markdownify }} + + Specify with .gemrc File + {{ readFile "content/reusable/md/resource_package_options_gemrc.md" | markdownify }} + {{ readFile "content/reusable/md/resource_package_install_gem_with_gemrc.md" | markdownify }} +{{ end }} + + + +{{ if and ( index $yaml_file "actions_list" ) ( ne (index $yaml_file "actions_list") "" )}} + {{ with index $yaml_file "actions_list" }} + + Actions + +

The {{ index $yaml_file "resource" }} resource has the following actions:

+
+ {{ range $key, $value := . }} +
{{ $key | markdownify }}
+ {{ range $subkey, $subvalue := $value }} + {{ if eq $subkey "shortcode" }} +
{{ readFile (delimit (slice `content/reusable/md/` $subvalue ) "") | markdownify }}
+ {{ end }} + {{ if eq $subkey "markdown" }} +
{{- $subvalue | markdownify -}}
+ {{ end }} + {{ end }} + {{ end }} +
+ {{ end }} +{{ end }} + + + +Properties + +{{ if or (index $yaml_file "properties_shortcode") (index $yaml_file "properties_list") }} + {{ with index $yaml_file "properties_list" }} +

The {{ index $yaml_file "resource" }} resource has the following properties:

+ {{ range . }} +
+ {{ if and (.property) (ne .property nil) }} +
+ {{ .property }} +
+ {{ end }} + +
+ {{ if ne .ruby_type nil }} + Ruby Type: {{ .ruby_type }} {{ if .default_value }}| Default Value: {{ .default_value }}{{ end }} {{ if .required }}| REQUIRED{{ end }} + {{ if .allowed_values }}
Allowed Values: {{ .allowed_values }}{{ end }} +

+ {{ end }} + + {{ range .description_list }} + {{ range $key, $value := . }} + {{ if eq $key "markdown" }} +

{{- $value | markdownify -}}

+ {{ end }} + + {{ if eq $key "note" }} +
+

Note

+
+ {{ range $subkey, $subvalue := $value }} + {{ if eq $subkey "markdown" }} +

+ {{- $subvalue | markdownify -}} +

+ {{ end }} + {{ if eq $subkey "shortcode" }} +

+ {{ readFile (delimit (slice `content/reusable/md/` $subvalue ) "") | markdownify }} +

+ {{ end }} + {{ end }} +
+
+ {{ end }} + {{ if eq $key "warning" }} +
+

Warning

+
+ {{ range $subkey, $subvalue := $value }} + {{ if eq $subkey "markdown" }} +

+ {{- $subvalue | markdownify -}} +

+ {{ end }} + {{ if eq $subkey "shortcode" }} +

+ {{ readFile (delimit (slice `content/reusable/md/` $subvalue ) "") | markdownify }} +

+ {{ end }} + {{ end }} +
+
+ {{ end }} + {{ if eq $key "shortcode" }} +

+ {{ readFile (delimit (slice `content/reusable/md/` $value ) "") | markdownify }} +

+ {{ end }} + {{ end }} + {{ end }} + + {{ if and (.new_in) (ne .new_in nil) }} +

+ {{ if ge .new_in 15 }} + New in Chef Infra Client {{ .new_in }} + {{ else }} + New in Chef Client {{ .new_in }} + {{ end }} +

+ {{ end }} + {{ if and (.note) (ne .note nil) }} +
+

Note

+
{{- .note | markdownify -}}
+
+ {{ end }} +
+
+ {{ end }} + {{ end }} + {{ with index $yaml_file "properties_shortcode" }} + {{ readFile (delimit (slice `content/reusable/md/` . ) "") | markdownify }} + {{ end }} +{{ else }} +

This resource does not have any properties.

+{{ end }} + +{{ with index $yaml_file "multi_package_resource" }} + Multiple Packages + {{ readFile "content/reusable/md/resources_common_multiple_packages.md" | markdownify }} +{{ end }} + +{{ with index $yaml_file "resource_directory_recursive_directories" }} + Recursive Directories + {{ readFile "content/reusable/md/remote_directory_recursive_directories.md" | markdownify }} +{{ end }} + +{{ with index $yaml_file "resources_common_atomic_update" }} + Atomic File Updates + {{ readFile "content/reusable/md/resources_common_atomic_update.md" | markdownify }} +{{ end }} + +{{ with index $yaml_file "properties_resources_common_windows_security" }} + Windows File Security + {{ readFile "content/reusable/md/resources_common_windows_security.md" | markdownify }} + Access Control Lists (ACLs) + {{ readFile "content/reusable/md/resources_common_windows_security_acl.md" | markdownify }} + Inheritance + {{ readFile "content/reusable/md/resources_common_windows_security_inherits.md" | markdownify }} +{{ end }} + +{{ with index $yaml_file "remote_file_prevent_re_downloads" }} + Prevent Re-downloads + {{ readFile "content/reusable/md/remote_file_prevent_re_downloads.md" | markdownify }} +{{ end }} + +{{ with index $yaml_file "remote_file_unc_path" }} + Access a remote UNC path on Windows + {{ readFile "content/reusable/md/remote_file_unc_path.md" | markdownify }} +{{ end }} + +{{ with index $yaml_file "ps_credential_helper" }} + ps_credential Helper + {{ readFile "content/reusable/md/ps_credential_helper.md" | markdownify }} +{{ end }} + + + +{{ with index $yaml_file "ruby_style_basics_chef_log" }} + Log Entries + {{ readFile "content/reusable/md/ruby_style_basics_chef_log.md" | markdownify }} + {{ readFile "content/reusable/md/ruby_class_chef_log_fatal.md" | markdownify }} + {{ readFile "content/reusable/md/ruby_class_chef_log_multiple.md" | markdownify }} +{{ end }} + + + +{{ with index $yaml_file "debug_recipes_chef_shell" }} + + Debug Recipes with chef-shell + {{ readFile "content/reusable/md/chef_shell_summary.md" | markdownify }} + + Modes + {{ readFile "content/reusable/md/chef_shell_modes.md" | markdownify }} + + Configure + {{ readFile "content/reusable/md/chef_shell_config.md" | markdownify }} + + chef-shell.rb + {{ readFile "content/reusable/md/chef_shell_config_rb.md" | markdownify }} + + Run as a Chef Infra Client + {{ readFile "content/reusable/md/chef_shell_run_as_chef_client.md" | markdownify }} + + Manage + {{ readFile "content/reusable/md/chef_shell_manage.md" | markdownify }} + + Use Breakpoints + {{ readFile "content/reusable/md/chef_shell_breakpoints.md" | markdownify }} + + Step Through Run-list + {{ readFile "content/reusable/md/chef_shell_step_through_run_list.md" | markdownify }} + + Debug Existing Recipe + {{ readFile "content/reusable/md/chef_shell_debug_existing_recipe.md" | markdownify }} + + Advanced Debugging + {{ readFile "content/reusable/md/chef_shell_advanced_debug.md" | markdownify }} + + Debug Examples + +

The following examples show how to use chef-shell.

+ "Hello World" + {{ readFile "content/reusable/md/chef_shell_example_hello_world.md" | markdownify }} + + Get Specific Nodes + {{ readFile "content/reusable/md/chef_shell_example_get_specific_nodes.md" | markdownify }} + +{{ end }} + + + +{{ with index $yaml_file "template_requirements" }} + Using Templates + {{ readFile "content/reusable/md/template_requirements.md" | markdownify}} + + File Specificity + {{ readFile "content/reusable/md/template_specificity.md" | markdownify}} + {{ readFile "content/reusable/md/template_specificity_pattern.md" | markdownify}} + {{ readFile "content/reusable/md/template_specificity_example.md" | markdownify}} + + Helpers + {{ readFile "content/reusable/md/template_helpers.md" | markdownify}} + + Inline Methods + {{ readFile "content/reusable/md/resource_template_inline_method.md" | markdownify}} + + Inline Modules + {{ readFile "content/reusable/md/resource_template_inline_module.md" | markdownify}} + + Library Modules + {{ readFile "content/reusable/md/resource_template_library_module.md" | markdownify}} + + Host Notation + {{ readFile "content/reusable/md/template_host_notation.md" | markdownify}} + + Partial Templates + {{ readFile "content/reusable/md/template_partials.md" | markdownify}} + + render Method + {{ readFile "content/reusable/md/template_partials_render_method.md" | markdownify}} + + Transfer Frequency + {{ readFile "content/reusable/md/template_transfer_frequency.md" | markdownify}} + + Variables + {{ readFile "content/reusable/md/template_variables.md" | markdownify}} + +{{ end }} + + + +{{ with index $yaml_file "target_mode" }} + + Agentless Mode + +

The {{ index $yaml_file "resource" }} resource has {{ .support }} support for Agentless Mode.

+ + {{ if .support }} +

Supported platforms:

+ + {{ if and (.platforms) (ne .platforms nil) }} +
    + {{ range $key := .platforms }} +
  • {{ $key }}
    • + {{ end }} +
+ + {{ else }} +
    +
  • aix
    • +
  • bsd
    • +
  • linux
    • +
  • solaris
    • +
+ {{ end }} + + {{ .description | markdownify }} + +

+ {{ if and (.updated) (ne .updated nil) }} + Support was initially added in Chef Infra Client {{ .introduced }} and updated later in {{ .updated }}. + {{ else }} + Support was initially added in Chef Infra Client {{ default .introduced "19.0" }}. + {{ end }} +

+ + {{ if and (.requirements) (ne .requirements nil) }} +

+ {{ .requirements | markdownify }} +

+ {{ end }} + {{ end }} +{{ end }} + + + +{{ with index $yaml_file "unit_file_verification" }} + Unit file verification + {{ readFile "content/reusable/md/unit_file_verification.md" | markdownify }} +{{ end }} + + + +{{ if or (index $yaml_file "resources_common_properties" ) ( index $yaml_file "resources_common_notification" ) ( index $yaml_file "resources_common_guards" ) ( index $yaml_file "multi_package_resource" ) ( index $yaml_file "resources_common_guard_interpreter" ) ( index $yaml_file "remote_directory_recursive_directories" ) ( index $yaml_file "common_resource_functionality_resources_common_windows_security" )}} + + Common Resource Functionality + +

Chef resources include common properties, notifications, and resource guards.

+ + {{ if index $yaml_file "resources_common_properties" }} + Common Properties + + {{ readFile "content/reusable/md/resources_common_properties.md" | markdownify }} + + {{ end }} + + {{ if index $yaml_file "resources_common_notification" }} + Notifications + +
+
+ notifies +
+
+

Ruby Type: Symbol, 'Chef::Resource[String]'

+ {{ readFile "content/reusable/md/resources_common_notification_notifies.md" | markdownify }} +
+
+ + {{ readFile "content/reusable/md/resources_common_notification_timers.md" | markdownify }} + {{ readFile "content/reusable/md/resources_common_notification_notifies_syntax.md" | markdownify }} + +
+
+ subscribes +
+
+

Ruby Type: Symbol, 'Chef::Resource[String]'

+
+
+ {{ readFile "content/reusable/md/resources_common_notification_subscribes.md" | markdownify }} + {{ readFile "content/reusable/md/resources_common_notification_timers.md" | markdownify }} + {{ readFile "content/reusable/md/resources_common_notification_subscribes_syntax.md" | markdownify }} + + {{ end }} + + {{ if index $yaml_file "resources_common_guards" }} + Guards + + {{ readFile "content/reusable/md/resources_common_guards.md" | markdownify }} + Properties + {{ readFile "content/reusable/md/resources_common_guards_properties.md" | markdownify }} + + {{ end }} + + {{ if index $yaml_file "multi_package_resource" }} + Multiple Packages + + {{ readFile "content/reusable/md/resources_common_multiple_packages.md" | markdownify }} + + {{ end }} + + {{ if index $yaml_file "resources_common_guard_interpreter" }} + Guard Interpreter + +

+ {{ readFile "content/reusable/md/resources_common_guard_interpreter.md" | markdownify }} +

+ Attributes +

+ {{ readFile "content/reusable/md/resources_common_guard_interpreter_attributes.md" | markdownify }} +

+ + Inheritance +

+ {{ readFile "content/reusable/md/resources_common_guard_interpreter_attributes_inherit.md" | markdownify }} +

+ + Example +

+ {{ readFile "content/reusable/md/resources_common_guard_interpreter_example_default.md" | markdownify }} +

+ + {{ end }} + + {{ if index $yaml_file "remote_directory_recursive_directories" }} + Recursive Directories + {{ readFile "content/reusable/md/remote_directory_recursive_directories.md" | markdownify }} + Example + {{ readFile "content/reusable/md/remote_directory_recursive_directories_example.md" | markdownify }} + + {{ end }} + + {{ if index $yaml_file "common_resource_functionality_resources_common_windows_security" }} + Windows File Security + + {{ readFile "content/reusable/md/resources_common_windows_security.md" | markdownify }} + Access Control Lists (ACLs) + {{ readFile "content/reusable/md/resources_common_windows_security_acl.md" | markdownify }} + Inheritance + {{ readFile "content/reusable/md/resources_common_windows_security_inherits.md" | markdownify }} + + {{ end }} + +{{ end }} + + + +{{ if index $yaml_file "cookbook_file_specificity" }} + File Specificity + {{ readFile "content/reusable/md/cookbook_file_specificity.md" | markdownify }} +{{ end }} + + + +Examples + +{{ with index $yaml_file "examples" }} +

The following examples demonstrate various approaches for using the {{ index $yaml_file "resource" }} resource in recipes:

+ {{ . | markdownify }} +{{ else }} +

This resource does not have any examples.

+{{ end }} diff --git a/layouts/partials/infra_resource_toc.html b/layouts/partials/infra_resource_toc.html new file mode 100644 index 0000000..daadf3c --- /dev/null +++ b/layouts/partials/infra_resource_toc.html @@ -0,0 +1,270 @@ + diff --git a/layouts/partials/infra_resources_all_toc.html b/layouts/partials/infra_resources_all_toc.html new file mode 100644 index 0000000..79b8974 --- /dev/null +++ b/layouts/partials/infra_resources_all_toc.html @@ -0,0 +1,30 @@ + diff --git a/static/images/automate-dashboard.png b/static/images/automate-dashboard.png new file mode 100644 index 0000000..70558bc Binary files /dev/null and b/static/images/automate-dashboard.png differ diff --git a/static/images/automate_architecture.svg b/static/images/automate_architecture.svg new file mode 100644 index 0000000..b0c74ca --- /dev/null +++ b/static/images/automate_architecture.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/static/images/chef_bootstrap.png b/static/images/chef_bootstrap.png new file mode 100644 index 0000000..f0eeff4 Binary files /dev/null and b/static/images/chef_bootstrap.png differ diff --git a/static/images/chef_overview_2020.svg b/static/images/chef_overview_2020.svg new file mode 100644 index 0000000..9e2a0cd --- /dev/null +++ b/static/images/chef_overview_2020.svg @@ -0,0 +1,2479 @@ + +image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/static/images/chef_run.svg b/static/images/chef_run.svg new file mode 100644 index 0000000..dff4eec --- /dev/null +++ b/static/images/chef_run.svg @@ -0,0 +1,2718 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/static/images/includes_windows_environment_variable_path.png b/static/images/includes_windows_environment_variable_path.png new file mode 100644 index 0000000..314144a Binary files /dev/null and b/static/images/includes_windows_environment_variable_path.png differ diff --git a/static/images/overview_chef_attributes_precedence.png b/static/images/overview_chef_attributes_precedence.png new file mode 100644 index 0000000..c4b1f01 Binary files /dev/null and b/static/images/overview_chef_attributes_precedence.png differ diff --git a/static/images/start_chef.svg b/static/images/start_chef.svg new file mode 100644 index 0000000..676e5d9 --- /dev/null +++ b/static/images/start_chef.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/static/images/step_manage_webui_admin_organization_reset_key.png b/static/images/step_manage_webui_admin_organization_reset_key.png new file mode 100644 index 0000000..45e5e9a Binary files /dev/null and b/static/images/step_manage_webui_admin_organization_reset_key.png differ diff --git a/static/images/step_manage_webui_policy_client_reset_key_copy.png b/static/images/step_manage_webui_policy_client_reset_key_copy.png new file mode 100644 index 0000000..c7a7ea5 Binary files /dev/null and b/static/images/step_manage_webui_policy_client_reset_key_copy.png differ diff --git a/static/images/step_manage_webui_policy_client_reset_key_download.png b/static/images/step_manage_webui_policy_client_reset_key_download.png new file mode 100644 index 0000000..b311616 Binary files /dev/null and b/static/images/step_manage_webui_policy_client_reset_key_download.png differ diff --git a/tools/vale/markdownlint-rules.yaml b/tools/markdownlint-rules.yaml similarity index 100% rename from tools/vale/markdownlint-rules.yaml rename to tools/markdownlint-rules.yaml diff --git a/tools/vale/.vale-config/3-Hugo.ini b/tools/vale/.vale-config/2-Hugo.ini similarity index 60% rename from tools/vale/.vale-config/3-Hugo.ini rename to tools/vale/.vale-config/2-Hugo.ini index 3b01408..4347ca9 100644 --- a/tools/vale/.vale-config/3-Hugo.ini +++ b/tools/vale/.vale-config/2-Hugo.ini @@ -1,8 +1,10 @@ [*.md] # Exclude `{{< ... >}}`, `{{% ... %}}`, [Who]({{< ... >}}) TokenIgnores = ({{[%<] .* [%>]}}.*?{{[%<] ?/.* [%>]}}), \ -(\[.+\]\({{< .+ >}}\)) +(\[.+\]\({{< .+ >}}\)), \ +[^\S\r\n]({{[%<] \w+ .+ [%>]}})\s, \ +[^\S\r\n]({{[%<](?:/\*) .* (?:\*/)[%>]}})\s # Exclude `{{< myshortcode `This is some HTML, ... >}}` -BlockIgnores = (?sm)^({{[%<] [^{]*? [%>]}})\n$, \ +BlockIgnores = (?sm)^({{[%<] \w+ [^{]*?\s[%>]}})\n$, \ (?s) *({{< highlight [^>]* ?>}}.*?{{< ?/ ?highlight >}}) diff --git a/tools/vale/.vale-github-action.ini b/tools/vale/.vale-github-action.ini deleted file mode 100644 index 9603e98..0000000 --- a/tools/vale/.vale-github-action.ini +++ /dev/null @@ -1,19 +0,0 @@ -# Vale configuration file. -# -# This config file is for Vale lints run by GitHub Actions. -# See the .github/workflows/lint.yml file. -# See the .vale.ini file in the project root for lints run on a local workstation. -# -# For more information, see https://vale.sh/docs/. - -StylesPath = ../vale/ -MinAlertLevel = error -SkippedScopes = code -Packages = Microsoft, write-good, Hugo -Vocab = Chef - -[*.{md}] -BasedOnStyles = chef, Microsoft, vale, write-good - -# Ignore SVG markup -TokenIgnores = (\*\*\{\w*\}\*\*), (Master License and Services Agreement) diff --git a/tools/vale/Microsoft/Accessibility.yml b/tools/vale/Microsoft/Accessibility.yml index 05bf927..f5f4829 100644 --- a/tools/vale/Microsoft/Accessibility.yml +++ b/tools/vale/Microsoft/Accessibility.yml @@ -6,20 +6,25 @@ ignorecase: true tokens: - a victim of - able-bodied - - affected by - an epileptic + - birth defect - crippled + - differently abled - disabled - dumb - handicapped - handicaps - - healthy + - healthy person + - hearing-impaired - lame - maimed + - mentally handicapped - missing a limb - mute - - normal + - non-verbal + - normal person - sight-impaired + - slow learner - stricken with - suffers from - vision-impaired diff --git a/tools/vale/Microsoft/Adverbs.yml b/tools/vale/Microsoft/Adverbs.yml index 07d98d8..5619f99 100644 --- a/tools/vale/Microsoft/Adverbs.yml +++ b/tools/vale/Microsoft/Adverbs.yml @@ -1,5 +1,5 @@ extends: existence -message: "Consider removing '%s'." +message: "Remove '%s' if it's not important to the meaning of the statement." link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences ignorecase: true level: warning @@ -54,6 +54,7 @@ tokens: - doubtfully - dreamily - easily + - effectively - elegantly - energetically - enormously @@ -164,6 +165,7 @@ tokens: - quickly - quietly - quirkily + - quite - quizzically - randomly - rapidly diff --git a/tools/vale/Microsoft/ComplexWords.yml b/tools/vale/Microsoft/ComplexWords.yml deleted file mode 100644 index 65b7a34..0000000 --- a/tools/vale/Microsoft/ComplexWords.yml +++ /dev/null @@ -1,120 +0,0 @@ -extends: substitution -message: "Consider using '%s' instead of '%s'." -link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences -ignorecase: true -level: suggestion -action: - name: replace -swap: - "approximate(?:ly)?": about - abundance: plenty - accelerate: speed up - accentuate: stress - accompany: go with - accomplish: carry out|do - accorded: given - accordingly: so - accrue: add - accurate: right|exact - acquiesce: agree - acquire: get|buy - additional: more|extra - address: discuss - addressees: you - adjacent to: next to - adjustment: change - admissible: allowed - advantageous: helpful - advise: tell - aggregate: total - aircraft: plane - alleviate: ease - allocate: assign|divide - alternatively: or - alternatives: choices|options - ameliorate: improve - amend: change - anticipate: expect - apparent: clear|plain - ascertain: discover|find out - assistance: help - attain: meet - attempt: try - authorize: allow - belated: late - bestow: give - cease: stop|end - collaborate: work together - commence: begin - compensate: pay - component: part - comprise: form|include - concept: idea - concerning: about - confer: give|award - consequently: so - consolidate: merge - constitutes: forms - contains: has - convene: meet - demonstrate: show|prove - depart: leave - designate: choose - desire: want|wish - determine: decide|find - detrimental: bad|harmful - disclose: share|tell - discontinue: stop - disseminate: send|give - eliminate: end - elucidate: explain - employ: use - enclosed: inside|included - encounter: meet - endeavor: try - enumerate: count - equitable: fair - equivalent: equal - exclusively: only - expedite: hurry - facilitate: ease - females: women - finalize: complete|finish - frequently: often - identical: same - incorrect: wrong - indication: sign - initiate: start|begin - itemized: listed - jeopardize: risk - liaise: work with|partner with - maintain: keep|support - methodology: method - modify: change - monitor: check|watch - multiple: many - necessitate: cause - notify: tell - numerous: many - objective: aim|goal - obligate: bind|compel - optimum: best|most - permit: let - portion: part - possess: own - previous: earlier - previously: before - prioritize: rank - procure: buy - provide: give|offer - purchase: buy - relocate: move - solicit: request - state-of-the-art: latest - subsequent: later|next - substantial: large - sufficient: enough - terminate: end - transmit: send - utilization: use - utilize: use diff --git a/tools/vale/Microsoft/Contractions.yml b/tools/vale/Microsoft/Contractions.yml index 9f68313..8c81dcb 100644 --- a/tools/vale/Microsoft/Contractions.yml +++ b/tools/vale/Microsoft/Contractions.yml @@ -48,7 +48,3 @@ swap: 'where''s(?=\.)': where is will not: won't - mightn't've: might not have - mustn't've: mustn't have - shouldn't've: shouldn't have - wouldn't've: wouldn't have diff --git a/tools/vale/Microsoft/Dashes.yml b/tools/vale/Microsoft/Dashes.yml index 2894cf7..72b05ba 100644 --- a/tools/vale/Microsoft/Dashes.yml +++ b/tools/vale/Microsoft/Dashes.yml @@ -7,7 +7,7 @@ level: error action: name: edit params: - - remove - - ' ' + - trim + - " " tokens: - - '[—–]\s|\s[—–]' + - '\s[—–]\s|\s[—–]|[—–]\s' diff --git a/tools/vale/Microsoft/FirstPerson.yml b/tools/vale/Microsoft/FirstPerson.yml index 77761af..f58dea3 100644 --- a/tools/vale/Microsoft/FirstPerson.yml +++ b/tools/vale/Microsoft/FirstPerson.yml @@ -5,8 +5,8 @@ ignorecase: true level: warning nonword: true tokens: - - (?:^|\s)I\s - - (?:^|\s)I,\s + - (?:^|\s)I(?=\s) + - (?:^|\s)I(?=,\s) - \bI'd\b - \bI'll\b - \bI'm\b diff --git a/tools/vale/Microsoft/GenderBias.yml b/tools/vale/Microsoft/GenderBias.yml index 3d873aa..fc987b9 100644 --- a/tools/vale/Microsoft/GenderBias.yml +++ b/tools/vale/Microsoft/GenderBias.yml @@ -2,43 +2,41 @@ extends: substitution message: "Consider using '%s' instead of '%s'." ignorecase: true level: error +action: + name: replace swap: - (?:alumna|alumnus): graduate - (?:alumnae|alumni): graduates - air(?:m[ae]n|wom[ae]n): pilot(s) - anchor(?:m[ae]n|wom[ae]n): anchor(s) - authoress: author - camera(?:m[ae]n|wom[ae]n): camera operator(s) - chair(?:m[ae]n|wom[ae]n): chair(s) - congress(?:m[ae]n|wom[ae]n): member(s) of congress - door(?:m[ae]|wom[ae]n): concierge(s) - draft(?:m[ae]n|wom[ae]n): drafter(s) - fire(?:m[ae]n|wom[ae]n): firefighter(s) - fisher(?:m[ae]n|wom[ae]n): fisher(s) - fresh(?:m[ae]n|wom[ae]n): first-year student(s) - garbage(?:m[ae]n|wom[ae]n): waste collector(s) - lady lawyer: lawyer - ladylike: courteous - landlord: building manager - mail(?:m[ae]n|wom[ae]n): mail carriers - man and wife: husband and wife - man enough: strong enough - mankind: human kind - manmade: manufactured - manpower: personnel - men and girls: men and women - middle(?:m[ae]n|wom[ae]n): intermediary - news(?:m[ae]n|wom[ae]n): journalist(s) - ombuds(?:man|woman): ombuds - oneupmanship: upstaging - poetess: poet - police(?:m[ae]n|wom[ae]n): police officer(s) - repair(?:m[ae]n|wom[ae]n): technician(s) - sales(?:m[ae]n|wom[ae]n): salesperson or sales people - service(?:m[ae]n|wom[ae]n): soldier(s) - steward(?:ess)?: flight attendant - tribes(?:m[ae]n|wom[ae]n): tribe member(s) - waitress: waiter - woman doctor: doctor - woman scientist[s]?: scientist(s) - work(?:m[ae]n|wom[ae]n): worker(s) + (?:alumna|alumnus): graduate + (?:alumnae|alumni): graduates + air(?:m[ae]n|wom[ae]n): pilot(s) + anchor(?:m[ae]n|wom[ae]n): anchor(s) + authoress: author + camera(?:m[ae]n|wom[ae]n): camera operator(s) + door(?:m[ae]|wom[ae]n): concierge(s) + draft(?:m[ae]n|wom[ae]n): drafter(s) + fire(?:m[ae]n|wom[ae]n): firefighter(s) + fisher(?:m[ae]n|wom[ae]n): fisher(s) + fresh(?:m[ae]n|wom[ae]n): first-year student(s) + garbage(?:m[ae]n|wom[ae]n): waste collector(s) + lady lawyer: lawyer + ladylike: courteous + mail(?:m[ae]n|wom[ae]n): mail carriers + man and wife: husband and wife + man enough: strong enough + mankind: human kind + manmade: manufactured + manpower: personnel + middle(?:m[ae]n|wom[ae]n): intermediary + news(?:m[ae]n|wom[ae]n): journalist(s) + ombuds(?:man|woman): ombuds + oneupmanship: upstaging + poetess: poet + police(?:m[ae]n|wom[ae]n): police officer(s) + repair(?:m[ae]n|wom[ae]n): technician(s) + sales(?:m[ae]n|wom[ae]n): salesperson or sales people + service(?:m[ae]n|wom[ae]n): soldier(s) + steward(?:ess)?: flight attendant + tribes(?:m[ae]n|wom[ae]n): tribe member(s) + waitress: waiter + woman doctor: doctor + woman scientist[s]?: scientist(s) + work(?:m[ae]n|wom[ae]n): worker(s) diff --git a/tools/vale/Microsoft/HeadingPunctuation.yml b/tools/vale/Microsoft/HeadingPunctuation.yml index af04b02..4954cb1 100644 --- a/tools/vale/Microsoft/HeadingPunctuation.yml +++ b/tools/vale/Microsoft/HeadingPunctuation.yml @@ -7,7 +7,7 @@ scope: heading action: name: edit params: - - remove - - '.?!' + - trim_right + - ".?!" tokens: - - '[a-z][.?!](?:\s|$)' + - "[a-z][.?!]$" diff --git a/tools/vale/Microsoft/Headings.yml b/tools/vale/Microsoft/Headings.yml index fa98783..63624ed 100644 --- a/tools/vale/Microsoft/Headings.yml +++ b/tools/vale/Microsoft/Headings.yml @@ -26,4 +26,3 @@ exceptions: - Visual - VS - Windows - - Courier diff --git a/tools/vale/Microsoft/Hyphens.yml b/tools/vale/Microsoft/Hyphens.yml index 90bbb5d..7e5731c 100644 --- a/tools/vale/Microsoft/Hyphens.yml +++ b/tools/vale/Microsoft/Hyphens.yml @@ -7,8 +7,8 @@ nonword: true action: name: edit params: - - replace - - '-' - - ' ' + - regex + - "-" + - " " tokens: - - '\s[^\s-]+ly-' + - '\b[^\s-]+ly-\w+\b' diff --git a/tools/vale/Microsoft/Negative.yml b/tools/vale/Microsoft/Negative.yml index d6ff2f2..d73221f 100644 --- a/tools/vale/Microsoft/Negative.yml +++ b/tools/vale/Microsoft/Negative.yml @@ -6,8 +6,8 @@ level: error action: name: edit params: - - replace - - '-' - - '–' + - regex + - "-" + - "–" tokens: - - '\s-\d+\s' + - '(?<=\s)-\d+(?:\.\d+)?\b' diff --git a/tools/vale/Microsoft/Plurals.yml b/tools/vale/Microsoft/Plurals.yml new file mode 100644 index 0000000..1bb6660 --- /dev/null +++ b/tools/vale/Microsoft/Plurals.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Don't add '%s' to a singular noun. Use plural instead." +ignorecase: true +level: error +link: https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/s/s-es +raw: + - '\(s\)|\(es\)' diff --git a/tools/vale/Microsoft/RangeFormat.yml b/tools/vale/Microsoft/RangeFormat.yml deleted file mode 100644 index 452f717..0000000 --- a/tools/vale/Microsoft/RangeFormat.yml +++ /dev/null @@ -1,13 +0,0 @@ -extends: existence -message: "Use an en dash in a range of numbers." -link: https://docs.microsoft.com/en-us/style-guide/numbers -nonword: true -level: error -action: - name: edit - params: - - replace - - '-' - - '–' -tokens: - - '(?|C: drive)': drive C - '(?:internet bot|web robot)s?': bot(s) - '(?:microsoft cloud|the cloud)': cloud - '(?:mobile|smart) ?phone': phone - '24/7': every day - 'audio(?:-| )book': audiobook - 'back(?:-| )light': backlight - 'chat ?bots?': chatbot(s) + "(?:agent|virtual assistant|intelligent personal assistant)": personal digital assistant + "(?:assembler|machine language)": assembly language + "(?:drive C:|drive C>|C: drive)": drive C + "(?:internet bot|web robot)s?": bot(s) + "(?:microsoft cloud|the cloud)": cloud + "(?:mobile|smart) ?phone": phone + "24/7": every day + "audio(?:-| )book": audiobook + "back(?:-| )light": backlight + "chat ?bots?": chatbot(s) adaptor: adapter administrate: administer afterwards: afterward alphabetic: alphabetical alphanumerical: alphanumeric + an URL: a URL anti-aliasing: antialiasing anti-malware: antimalware anti-spyware: antispyware anti-virus: antivirus appendixes: appendices artificial intelligence: AI - '(?:assembler|machine language)': assembly language caap: CaaP conversation-as-a-platform: conversation as a platform eb: EB diff --git a/tools/vale/Microsoft/URLFormat.yml b/tools/vale/Microsoft/URLFormat.yml index 82e702f..4e24aa5 100644 --- a/tools/vale/Microsoft/URLFormat.yml +++ b/tools/vale/Microsoft/URLFormat.yml @@ -1,10 +1,9 @@ extends: substitution -message: "Use '%s' instead of '%s'." +message: Use 'of' (not 'for') to describe the relationship of the word URL to a resource. ignorecase: true -level: error +link: https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/u/url +level: suggestion action: name: replace swap: URL for: URL of - an URL: a URL - diff --git a/tools/vale/Microsoft/Wordiness.yml b/tools/vale/Microsoft/Wordiness.yml index 22a4c93..8a4fea7 100644 --- a/tools/vale/Microsoft/Wordiness.yml +++ b/tools/vale/Microsoft/Wordiness.yml @@ -2,12 +2,16 @@ extends: substitution message: "Consider using '%s' instead of '%s'." link: https://docs.microsoft.com/en-us/style-guide/word-choice/use-simple-words-concise-sentences ignorecase: true -level: warning +level: suggestion action: name: replace swap: - (?:give|gave) rise to: lead to + "sufficient number(?: of)?": enough + (?:extract|take away|eliminate): remove + (?:in order to|as a means to): to + (?:inform|let me know): tell (?:previous|prior) to: before + (?:utilize|make use of): use a (?:large)? majority of: most a (?:large)? number of: many a myriad of: myriad @@ -15,7 +19,7 @@ swap: all across: across all of a sudden: suddenly all of these: these - all of: all + all of(?! a sudden| these): all all-time record: record almost all: most almost never: seldom @@ -52,13 +56,14 @@ swap: continue on: continue despite the fact that: although disappear from sight: disappear + doomed to fail: doomed drag and drop: drag drag-and-drop: drag - doomed to fail: doomed due to the fact that: because during the period of: during during the time that: while emergency situation: emergency + establish connectivity: connect except when: unless excessive number: too many extend an invitation: invite @@ -74,6 +79,7 @@ swap: in a careful manner: carefully in a thoughtful manner: thoughtfully in a timely manner: timely + in addition: also in an effort to: to in between: between in lieu of: instead of @@ -106,7 +112,6 @@ swap: span across: span subsequent to: after successfully complete: complete - sufficient number (?:of)?: enough take action: act take into account: consider the question as to whether: whether diff --git a/tools/vale/write-good/E-Prime.yml b/tools/vale/write-good/E-Prime.yml index 1e4a920..074a102 100644 --- a/tools/vale/write-good/E-Prime.yml +++ b/tools/vale/write-good/E-Prime.yml @@ -5,16 +5,28 @@ level: suggestion tokens: - am - are + - aren't - be - been - being - he's - here's + - here's + - how's - i'm - is + - isn't + - it's - she's + - that's - there's - they're - was + - wasn't + - we're - were + - weren't + - what's + - where's - who's + - you're diff --git a/tools/vale/write-good/ThereIs.yml b/tools/vale/write-good/ThereIs.yml index 6666106..8b82e8f 100644 --- a/tools/vale/write-good/ThereIs.yml +++ b/tools/vale/write-good/ThereIs.yml @@ -1,6 +1,6 @@ extends: existence message: "Don't start a sentence with '%s'." ignorecase: false -level: warning +level: error raw: - '(?:[;-]\s)There\s(is|are)|\bThere\s(is|are)\b' diff --git a/tools/vale/write-good/Weasel.yml b/tools/vale/write-good/Weasel.yml index e293914..d1d90a7 100644 --- a/tools/vale/write-good/Weasel.yml +++ b/tools/vale/write-good/Weasel.yml @@ -3,205 +3,27 @@ message: "'%s' is a weasel word!" ignorecase: true level: warning tokens: - - absolutely - - accidentally - - additionally - - allegedly - - alternatively - - angrily - - anxiously - - approximately - - awkwardly - - badly - - barely - - beautifully - - blindly - - boldly - - bravely - - brightly - - briskly - - bristly - - bubbly - - busily - - calmly - - carefully - - carelessly - - cautiously - - cheerfully - clearly - - closely - - coldly - completely - - consequently - - correctly - - courageously - - crinkly - - cruelly - - crumbly - - cuddly - - currently - - daily - - daringly - - deadly - - definitely - - deliberately - - doubtfully - - dumbly - - eagerly - - early - - easily - - elegantly - - enormously - - enthusiastically - - equally - - especially - - eventually - - exactly - exceedingly - - exclusively + - excellent - extremely - fairly - - faithfully - - fatally - - fiercely - - finally - - fondly - - few - - foolishly - - fortunately - - frankly - - frantically - - generously - - gently - - giggly - - gladly - - gracefully - - greedily - - happily - - hardly - - hastily - - healthily - - heartily - - helpfully - - honestly - - hourly - - hungrily - - hurriedly - - immediately - - impatiently - - inadequately - - ingeniously - - innocently - - inquisitively + - huge - interestingly - - irritably - - jiggly - - joyously - - justly - - kindly + - is a number - largely - - lately - - lazily - - likely - - literally - - lonely - - loosely - - loudly - - loudly - - luckily - - madly - - many - - mentally - - mildly - - monthly - - mortally - mostly - - mysteriously - - neatly - - nervously - - nightly - - noisily - - normally - - obediently - - occasionally - - only - - openly - - painfully - - particularly - - patiently - - perfectly - - politely - - poorly - - powerfully - - presumably - - previously - - promptly - - punctually - - quarterly - - quickly - - quietly - - rapidly - - rarely - - really - - recently - - recklessly - - regularly - - remarkably + - obviously + - quite - relatively - - reluctantly - - repeatedly - - rightfully - - roughly - - rudely - - sadly - - safely - - selfishly - - sensibly - - seriously - - sharply - - shortly - - shyly + - remarkably + - several - significantly - - silently - - simply - - sleepily - - slowly - - smartly - - smelly - - smoothly - - softly - - solemnly - - sparkly - - speedily - - stealthily - - sternly - - stupidly - substantially - - successfully - - suddenly - surprisingly - - suspiciously - - swiftly - - tenderly - - tensely - - thoughtfully - - tightly - - timely - - truthfully - - unexpectedly - - unfortunately + - tiny - usually + - various + - vast - very - - victoriously - - violently - - vivaciously - - warmly - - waverly - - weakly - - wearily - - weekly - - wildly - - wisely - - worldly - - wrinkly - - yearly