The following items are new for Chef Infra Client 12.6 and/or are changes from previous versions. The short version:

- **New timer for resource notifications** Use the `: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.
- **New ksh resource** The **ksh** resource is added and is based on
    the **script** resource.
- **New metadata.rb settings** The metadata.rb file has settings for
    `chef_version` and `ohai_version` that allow ranges to be specified
    that declare the supported versions of Chef Infra Client and Ohai.
- **dsc_resource supports reboots** The **dsc_resource** resource
    supports immediate and queued reboots. This uses the **reboot**
    resource and its `:reboot_now` or `:request_reboot` actions.
- **New and changed knife bootstrap options** The `--identify-file`
    option for the `knife bootstrap` subcommand is renamed to
    `--ssh-identity-file`; the `--sudo-preserve-home` is new.
- **New installer types for the windows_package resource** The
    **windows_package** resource now supports the following installer
    types: `:custom`, Inno Setup (`:inno`), InstallShield
    (`:installshield`), Microsoft Installer Package (MSI) (`:msi`),
    Nullsoft Scriptable Install System (NSIS) (`:nsis`), Wise (`:wise`).
    Prior versions of Chef supported only `:msi`.
- **dsc_resource resource may be run in non-disabled refresh mode**
    The latest version of Windows Management Framework (WMF) 5 has
    relaxed the limitation that prevented Chef Infra Client from running in
    non-disabled refresh mode. Requires Windows PowerShell 5.0.10586.0
    or higher.
- **dsc_script and dsc_resource resources may be in the same
    run-list** The latest version of Windows Management Framework (WMF)
    5 has relaxed the limitation that prevented Chef Infra Client from running
    in non-disabled refresh mode, which allows the Local Configuration
    Manager to be set to `Push`. Requires Windows PowerShell 5.0.10586.0
    or higher.
- **New --profile-ruby option** Use the `--profile-ruby` option to
    dump a (large) profiling graph into
    `/var/chef/cache/graph_profile.out`.
- **New live_stream property for the execute resource** Set the
    `live_stream` property to `true` to send the output of a command run
    by the **execute** resource to Chef Infra Client event stream.

## Notification Timers

A timer specifies the point during the 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 the Chef Infra Client run.

`:immediate`, `:immediately`

:   Specifies that a notification should be run immediately, per
    resource notified.

## ksh

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.

<div class="admonition-note">
<p class="admonition-note-title">Note</p>
<div class="admonition-note-text">

The **ksh** script resource (which is based on the **script** resource)
is different from the **ruby_block** resource because Ruby code that is
run with this resource is created as a temporary file and executed like
other script resources, rather than run inline.

</div>
</div>

### Syntax

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

The full syntax for all of the properties that are available to the
**ksh** resource is:

```ruby
ksh 'name' do
  code                       String
  creates                    String
  cwd                        String
  environment                Hash
  flags                      String
  group                      String, Integer
  notifies                   # see description
  path                       Array
  returns                    Integer, Array
  subscribes                 # see description
  timeout                    Integer, Float
  user                       String, Integer
  umask                      String, Integer
  action                     Symbol # defaults to :run if not specified
end
```

where

- `ksh` is the resource
- `name` is the name of the resource block
- `action` identifies the steps Chef Infra Client will take to bring the
    node into the desired state
- `code`, `creates`, `cwd`, `environment`, `flags`, `group`, `path`,
    `returns`, `timeout`, `user`, and `umask` are properties of this
    resource, with the Ruby type shown. See "Properties" section below
    for more information about all of the properties that may be used
    with this resource.

### Actions

The ksh resource has the following actions:

`:nothing`

:   Prevent a command from running. This action is used to specify that
    a command is run only when another resource notifies it.

`:run`

:   Default. Run a script.

### Properties

The ksh resource has the following properties:

`code`

:   **Ruby Type:** String

    A quoted (" ") string of code to be executed.

`creates`

:   **Ruby Type:** String

    Prevent a command from creating a file when that file already
    exists.

`cwd`

:   **Ruby Type:** String

    The current working directory from which the command will be run.

`environment`

:   **Ruby Type:** Hash

    A Hash of environment variables in the form of
    `({"ENV_VARIABLE" => "VALUE"})`. (These variables must exist for a
    command to be run successfully.)

`flags`

:   **Ruby Type:** String

    One or more command line flags that are passed to the interpreter
    when a command is invoked.

`group`

:   **Ruby Type:** String, Integer

    The group name or group ID that must be changed before running a
    command.

`path`

:   <div class="admonition-warning">
    <p class="admonition-warning-title">Warning</p>
    <div class="admonition-warning-text">

    The `path` property has been deprecated and will throw an exception
    in Chef Infra Client 12 or later. We recommend you use the `environment`
    property instead.

    </div>
    </div>

    **Ruby Type:** Array

    An array of paths to use when searching for a command. These paths
    are not added to the command's environment \$PATH. The default value
    uses the system path.

    For example:

    ```ruby
    ksh 'mycommand' do
      environment 'PATH' => "/my/path/to/bin:#{ENV['PATH']}"
    end
    ```

`returns`

:   **Ruby Type:** Integer, Array | **Default Value:** `0`

    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.

`timeout`

:   **Ruby Type:** Integer, Float | **Default Value:** `3600`

    The amount of time (in seconds) a command is to wait before timing
    out.

`user`

:   **Ruby Type:** String, Integer

    The user name or user ID that should be changed before running a
    command.

`umask`

:   **Ruby Type:** String, Integer

    The file mode creation mask, or umask.

## Changes for PowerShell 5.0.10586.0

Using the **dsc_resource** has the following requirements:

- Windows Management Framework (WMF) 5.0 February Preview (or higher),
    which includes Windows PowerShell 5.0.10018.0 (or higher).

- The `RefreshMode` configuration setting in the Local Configuration
    Manager must be set to `Disabled`.

    <div class="admonition-note">
    <p class="admonition-note-title">Note</p>
    <div class="admonition-note-text">

    Starting with Chef Infra Client 12.6 release, this requirement applies
    only for versions of Windows PowerShell earlier than 5.0.10586.0.
    The latest version of Windows Management Framework (WMF) 5 has
    relaxed the limitation that prevented Chef Infra Client from running in
    non-disabled refresh mode.

    </div>
    </div>

- 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`.

    <div class="admonition-note">
    <p class="admonition-note-title">Note</p>
    <div class="admonition-note-text">

    Starting with Chef Infra Client 12.6 release, this requirement applies
    only for versions of Windows PowerShell earlier than 5.0.10586.0.
    The latest version of Windows Management Framework (WMF) 5 has
    relaxed the limitation that prevented Chef Infra Client from running in
    non-disabled refresh mode, which allows the Local Configuration
    Manager to be set to `Push`.

    </div>
    </div>

- The **dsc_resource** resource can only use binary- or script-based
    resources. Composite DSC resources may not be used.

    This is because composite resources aren't "real" resources from the
    perspective of the Local Configuration Manager (LCM). Composite
    resources are used by the "configuration" keyword from the
    `PSDesiredStateConfiguration` module, and then evaluated in that
    context. When using DSC to create the configuration document (the
    Managed Object Framework (MOF) file) from the configuration command,
    the composite resource is evaluated. Any individual resources from
    that composite resource are written into the Managed Object
    Framework (MOF) document. As far as the Local Configuration Manager
    (LCM) is concerned, there is no such thing as a composite resource.
    Unless that changes, the **dsc_resource** resource and/or
    `Invoke-DscResource` command cannot directly use them.

## New metadata.rb Settings

The following settings are new for metadata.rb:

<table>
<colgroup>
<col style="width: 40%" />
<col style="width: 60%" />
</colgroup>
<thead>
<tr class="header">
<th>Setting</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><p><code>chef_version</code></p></td>
<td><p>A range of chef-client versions that are supported by this cookbook.</p>
<p>For example, to match any 12.x version of the chef-client, but not 11.x or 13.x:</p>
<div class="sourceCode" id="cb1"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb1-1"><a href="#cb1-1"></a>chef_version <span class="st">&#39;~&gt; 12&#39;</span></span></code></pre></div>
<p>A more complex example where you set both a lower and upper bound of Chef Infra Client version:</p>
<div class="sourceCode" id="cb2"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb2-1"><a href="#cb2-1"></a>chef_version <span class="st">&quot;&gt;= 14.2.1&quot;</span>, <span class="st">&quot;&lt; 14.5.1&quot;</span></span></code></pre></div></td>
</tr>
<tr>
<td><p><code>ohai_version</code></p></td>
<td><p>A range of chef-client versions that are supported by this cookbook.</p>
<p>For example, to match any 8.x version of Ohai, but not 7.x or 9.x:</p>
<div class="sourceCode" id="cb3"><pre class="sourceCode ruby"><code class="sourceCode ruby"><span id="cb3-1"><a href="#cb3-1"></a>ohai_version <span class="st">&quot;~&gt; 8&quot;</span></span></code></pre></div></td>
</tr>
</tbody>
</table>

<div class="admonition-note">
<p class="admonition-note-title">Note</p>
<div class="admonition-note-text">

These settings are not visible in Chef Supermarket.

</div>
</div>

## knife bootstrap Options

The following option is new for `knife bootstrap`:

`--sudo-preserve-home`

:   Use to preserve the non-root user's `HOME` environment.

The `--identify-file` option is now `--ssh-identify-file`.

## --profile-ruby Option

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-client run.
This option:

- Generates a large amount of data about the chef-client run.
- Has a dependency on the `ruby-prof` gem, which is packaged as part
    of Chef and the ChefDK.
- Increases the amount of time required to complete the chef-client
    run.
- Should not be used in a production environment.