Table Of Contents

knife windows

The knife windows subcommand is used to configure and interact with nodes that exist on server and/or desktop machines that are running Microsoft Windows. Nodes are configured using Windows Remote Management, which allows native objects—batch scripts, Windows PowerShell scripts, or scripting library variables—to be called by external applications.


Review the list of common options available to this (and all) Knife subcommands and plugins.

Install this plugin

To install the knife windows plugin using RubyGems, run the following command:

$ /opt/chef/embedded/bin/gem install knife-windows

where /opt/chef/embedded/bin/ is the path to the location where the chef-client expects Knife plugins to be located. If the chef-client was installed using RubyGems, omit the path in the previous example.


This subcommand requires Windows Remote Management to be installed, and then configured correctly. For more information, see: and/or Use the quick configuration option in Windows Remote Management to allow outside connections and the entire network path from Knife (and the workstation):

$ winrm quickconfig -q

The following Windows Remote Management configuration settings should be updated:

Setting Description
MaxMemoryPerShellMB The chef-client and Ohai typically require more memory than the default setting allows. Increase this value to 300MB. (Only required on Windows Server 2008 R2 Standard and older. The default in Windows Server 2012 was increased to 1024MB.)
MaxTimeoutms A bootstrap command can take longer than allowed by the default setting. Increase this value to 1800000 (30 minutes).
AllowUnencrypted Set this value to true for development and testing purposes.
Basic Set this value to true for development and testing purposes. The knife windows subcommand supports Kerberos and Basic authentication schemes.

To update these settings, run the following commands:

$ winrm set winrm/config/winrs @{MaxMemoryPerShellMB="300"}


$ winrm set winrm/config @{MaxTimeoutms="1800000"}


$ winrm set winrm/config/service @{AllowUnencrypted="true"}

and then:

$ winrm set winrm/config/service/auth @{Basic="true"}

Ensure that the Windows Firewall is configured to allow Windows Remote Management connections from the workstation. For example:

$ netsh advfirewall firewall set rule name="Windows Remote Management (HTTP-In)" profile=public protocol=tcp localport=5985 remoteip=localsubnet new remoteip=any

Domain Authentication

The knife windows plugin supports Microsoft Windows domain authentication. This requires:

To create the listener over HTTPS, run the following command:

$ winrm create winrm/config/Listener?Address=IP:<ip_address>+Transport=HTTPS @{Hostname="<fqdn>";CertificateThumbprint="<hexidecimal_thumbprint_value>"}

where the CertificateThumbprint is the thumbprint hex value copied from the certificate details. (The hex value may require that spaces be removed before passing them to the node using the knife windows plugin.) Windows Remote Management 2.0 uses port 5985 for HTTP and port 5986 for HTTPS traffic, by default.

To bootstrap the target node using the knife bootstrap subcommand, run a command similar to the following:

$ knife bootstrap windows winrm '' -r 'role[webserver]' -x domain\\administrator -P 'password' -p 5986

and then use the winrm argument in the knife windows plugin to verify the communication with the new node:

$ knife winrm '' 'dir' -m -x domain\\administrator -P 'super_secret_password' –p 5986

bootstrap windows ssh

The bootstrap windows ssh argument is used to bootstrap chef-client installations in a Microsoft Windows environment, using a command shell that is native to Microsoft Windows.


This argument has the following syntax:

$ knife bootstrap windows ssh (options)


This argument has the following options:

--bootstrap-proxy PROXY_URL
The proxy server for the node that is the target of a bootstrap operation.
--bootstrap-version VERSION
The version of the chef-client to install.
-d DISTRO, --distro DISTRO
The template file to be used during a bootstrap operation. The following distributions are supported: chef-full (the default bootstrap), centos5-gems, fedora13-gems, ubuntu10.04-gems, ubuntu10.04-apt, ubuntu12.04-gems, and the name of a custom bootstrap template file. When this option is used, Knife will search for the template file in the following order: the bootstrap/ folder in the current working directory, the bootstrap/ folder in the chef-repo, the bootstrap/ folder in the ~/.chef/ directory, or a default bootstrap file. Do not use the --template-file option when --distro is specified.
The SSH identity file used for authentication. Key-based authentication is recommended.
-N NAME, --node-name NAME
The name of the node.
Use --no-host-key-verify to disable host key verification. Default setting: --host-key-verify.
-p PORT, --ssh-port PORT
The SSH port.
-P PASSWORD, --ssh-password PASSWORD
The SSH password. This can be used to pass the password directly on the command line. If this option is not specified (and a password is required) Knife will prompt for the password.
Use to install pre-release gems.
-r RUN_LIST, --run-list RUN_LIST
A comma-separated list of roles and/or recipes to be applied.
-s SECRET, --secret SECRET
The encryption key that is used for values contained within a data bag item.
--secret-file FILE
The path to the file that contains the encryption key.
--template-file TEMPLATE
The path to a template file that will be used during a bootstrap operation. Do not use the --distro option when --template-file is specified.
-x USER_NAME, --ssh-user USER_NAME
The SSH user name.


The winrm argument is used to create a connection to one or more remote machines. As each connection is created, a password must be provided. This argument uses the same syntax as the search subcommand.

Windows Remote Management requires that a target node be accessible via the ports configured to support access via HTTP or HTTPS.


This argument has the following syntax:

$ knife winrm SEARCH_QUERY SSH_COMMAND (options)


This argument has the following options:

-a ATTR, --attribute ATTR
The attribute that is used when opening the SSH connection. The default attribute is the FQDN of the host. Other possible values include a public IP address, a private IP address, or a hostname.
-f CA_TRUST_FILE, --ca-trust-file CA_TRUST_FILE
The certificate authority (CA) trust file used for SSL transport.
The SSH identity file used for authentication. Key-based authentication is recommended.
-i KEYTAB_FILE, --keytab-file KEYTAB_FILE
The keytab file that contains the encryption key required by Kerberos-based authentication.
-m, --manual-list
Use to define a search query as a space-separated list of servers.
-p PORT, --winrm-port PORT
The Windows Remote Management port. Default: 5985.
-P PASSWORD, --winrm-password PASSWORD
The Windows Remote Management password.
The administrative domain to which a user belongs.
--returns CODES
A comma-delimited list of return codes, which indicate the success or failure for the command that was run remotely.
The service principal used during Kerberos-based authentication.
The search query used to return a list of servers to be accessed using SSH and the specified SSH_COMMAND. This option uses the same syntax as the search sub-command.
The command that will be run against the results of a search query.
-t TRANSPORT, --winrm-transport TRANSPORT
The Windows Remote Management transport type: ssl or plaintext.
-x USERNAME, --winrm-user USERNAME
The Windows Remote Management user name.


Find Uptime for Web Servers

To find the uptime of all web servers, enter:

$ knife winrm "role:web" "net stats srv" -x Administrator -P password

Force a chef-client run

To force a chef-client run:

knife winrm '' 'chef-client -c c:/chef/client.rb' -m -x admin -P 'password' [date] INFO: Starting Chef Run (Version 0.9.12) [date] WARN: Node ip-0A502FFB has an empty run list. [date] INFO: Chef Run complete in 4.383966 seconds [date] INFO: cleaning the checksum cache [date] INFO: Running report handlers [date] INFO: Report handlers complete

Where in the examples above, [date] represents the date and time the long entry was created. For example: [Fri, 04 Mar 2011 22:00:53 +0000].

Bootstrap a Windows machine using SSH

To bootstrap a Microsoft Windows machine using SSH:

$ knife bootstrap windows ssh -r 'role[webserver],role[production]' -x Administrator -i ~/.ssh/id_rsa

Bootstrap a Windows machine using Windows Remote Management

To bootstrap a Microsoft Windows machine using Windows Remote Management:

$ knife bootstrap windows winrm -r 'role[webserver],role[production]' -x Administrator -P 'super_secret_password'