New in 10.0 This feature is new for Chef 0.10.

Description

This Knife Plugin adds additional functionality to the Chef Knife CLI tool for configuring/interacting with nodes running Microsoft Windows.

The subcommands should function on any system running Ruby 1.9.1+ but nodes being configured via these subcommands require Windows Remote Management (WinRM) 1.0+. WinRM allows you to call native objects in Windows, which includes, but is not limited to:

• running batch scripts,
• powershell scripts and
• fetching WMI variables.

For more information on WinRM, please visit Microsoft's WinRM site.

You will want to familiarize yourself with (certain key aspects) of WinRM because you will be writing scripts/running commands with this tool to get you from (specific point A) to (specific point B). WinRM is built into Windows 7 and Windows Server 2008+. It can also be easily installed in older version of Windows, including:

• Windows Server 2003
• Windows Vista

More information can be found on Microsoft Support article 968930.

Requirements/Version

• Chef is supported on Windows Server 2008 R2, 2003 R2 and Windows 7. Additionally, it is known to run on Windows Vista.

• Knife Plugins require Chef 0.10 or greater.

• knife-windows requires Ruby 1.9.1 or greater.

• The following modifications should be made to hosts that you would like to communicate with using WinRM:

  The following should be run within cmd.exe, not Powershell, in order to avoid issues with escaping the command line.

  • A server running WinRM must be configured properly to allow outside connections and the entire network path from the knife workstation to the server. The easiest way to accomplish this is to use WinRM's quick configuration option:
  • The Chef and Ohai gem installations (that occur during bootstrap) take more memory than the default 150MB WinRM allocates per shell. Bump it up to 300MB with the following setting:
  • Bootstrap commands can take longer than the WinRM default 60 seconds to complete, bump to 30 minutes:

    WinRM supports both the HTTP and HTTPS transports and the following authentication schemes: Kerberos, Digest, Certificate and Basic. The details of these authentication transports are outside of the scope of this README but details can be found on the WinRM configuration guide. Currently, this plugin support Kerberos and Basic authentication schemes.//

  • For development and testing purposes, unencrypted traffic with Basic authentication can make things easier:

WinRM installation must be configured correctly Before any WinRM related knife subcommands will function correctly a node’s WinRM installation must be configured correctly. The above settings should be added to your base server image (AMI) or passed in using some sort of user-data mechanism provided by your cloud provider.

On 2008R1 and earlier, windows defaults to using port 80 for winrm HTTP and 443 for winrm HTTPS. To change winrm to used HTTP on port

Installation

Knife Plugins ship as Ruby gems so knife-windows is easily installable.

Since knife-windows is written in pure Ruby (just like Chef) you should be able to install it on any platform that Chef supports. This means you can manage your Windows nodes from the comfort of bash on your favorite Linux distro or better yet zsh on OS X if you'd like!

Subcommands

This plugin provides the following Knife subcommands. Specific command options can be found by invoking the subcommand with a ---help flag.

knife winrm

The winrm subcommand allows you to invoke commands in parallel on a subset of the nodes in your infrastructure. The winrm subcommand uses the same syntax as the search subcommand; you could could find the uptime of all your web servers using the command:

You could also invoke everyone's favorite Windows command ipconfig against a single server (vs a search query in the prior example) using the following command:

Or force a chef run:

This subcommand operates in a very similar manner as knife ssh leveraging the WinRM protocol for communication. It also include’s knife ssh’s "interactive session mode"

knife bootstrap windows winrm

Performs a Chef Bootstrap (via the WinRM protocol) on the target node. The goal of the bootstrap is to get Chef installed on the target system so it can run Chef Client with a Chef Server. The main assumption is a baseline OS installation exists. It is primarily intended for Chef Client systems that talk to a Chef server.

In the future this subcommand will be used internally by some cloud computing server create commands like the current knife bootstrap subcommand is. This subcommand operates in a very similar manner as knife bootstrap leveraging the WinRM protocol for communication. An initial run_list for the node can also be passed to the subcommand. Example usage:

knife bootstrap windows ssh

Performs a Chef Bootstrap (via the SSH protocol) on the target node. The goal of the bootstrap is to get Chef installed on the target system so it can run Chef Client with a Chef Server. The main assumption is a baseline OS installation exists. It is primarily intended for Chef Client systems that talk to a Chef server.

This subcommand assumes the SSH session will use Windows native cmd.exe command shell vs a bash shell through an emulated cygwin layer. Most popular Windows based SSHd daemons like freeSSHd and WinSSHD behave this way.

An initial run_list for the node can also be passed to the subcommand. Example usage:

Bootstrap Templates

This gem provides the following bootstrap templates:

windows-chef-client-msi

This bootstrap template does the following:

1. Installs the latest version of Chef (and all dependencies) using the `chef-client` msi.
2. Writes the validation.pem per the local knife configuration.
3. Writes a default config file for Chef (C:\chef\client.rb) using values from the knife.rb.
4. Creates a JSON attributes file containing the specified run list and run Chef.

This is the default bootstrap template used by both the windows bootstrap subcommands.

windows-shell

This bootstrap template does the following:

1. Installs Ruby 1.8.7 via the Ruby Installer for Windows which also includes the latest version of RubyGems
2. Installs the RubyInstaller Development Kit (DevKit). The RubyInstaller Development Kit (DevKit) is a MSYS/MinGW based toolkit than enables you to build many of the native C/C++ extensions available for Ruby.
3. Installs required Windows-related gems from RubyGems.org
4. Installs latest Chef version from RubyGems.org including Ohai and Chef.
5. Writes the validation.pem per the local knife configuration.
6. Writes a default config file for Chef (C:\chef\client.rb) using values from the knife.rb.
7. Creates a JSON attributes file containing the specified run list and run Chef.

This should be considered a legacy bootstrap template and will most likely be removed in a future version.

Custom Knife Bootstrap Script

Knife Exec