knife windows

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

This subcommand should be installed as a Knife plugin, using RubyGems.

This subcommand has the following syntax when connecting to one (or more) machines that run Microsoft Windows:

knife winrm [ARGUMENT] (options)

And the following syntax when performing a bootstrap:

knife bootstrap windows [ARGUMENT] (options)

Note

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:

$ gem install knife-windows

Requirements

This subcommand requires Windows Remote Management to be installed, and then configured correctly. For more information, see: http://msdn.microsoft.com/en-us/library/aa384426(v=vs.85).aspx and/or http://support.microsoft.com/kb/968930. 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 for Chef:

Setting	Description
MaxMemoryPerShellMB	Chef and Ohai require more memory than the default setting allows. Increase this value to 300MB.
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"}

and:

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

and:

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

and then:

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

bootstrap windows ssh

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

Syntax

This argument has the following syntax:

$ knife bootstrap windows ssh (options)

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 Chef to install.

-d DISTRO, --distro DISTRO

The template file to be used during a bootstrap operation. Use this option if the specific location of the template file is unknown. The following distributions are supported: chef-full (the default bootstrap), centos5-gems, fedora13-gems, ubuntu10.04-gems, ubuntu10.04-apt, and ubuntu12.04-gems. If this option is used, Knife will search for the template file in the following order: a bootstrap/ folder in the current working directory, a bootstrap/ folder in the Chef repository, a bootstrap/ folder in ~/.chef/, or a bootstrap file shipped with Chef. Do not use the --template-file option when --distro is specified.

-i IDENTITY_FILE, --identity-file IDENTITY_FILE

The SSH identity file used for authentication. Key-based authentication is recommended.

-N NAME, --node-name NAME

The name of the node.

--[no-]host-key-verify

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.

--prerelease

Indicates that pre-release Chef gems should be installed.

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

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

Examples

For example:

$ knife bootstrap windows ssh ec2-50-xx-xx-124.compute-1.amazonaws.com -r 'role[webserver],role[production]' -x Administrator -i ~/.ssh/id_rsa

bootstrap windows winrm

The bootstrap windows winrm argument is used to bootstrap Chef installations in a Microsoft Windows environment, using Windows Remote Management and the WS-Management protocol for communication. This argument requires the FQDN of the host machine to be specified.

Syntax

This argument has the following syntax:

$ knife bootstrap windows winrm FQDN

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 Chef to install.

-d DISTRO, --distro DISTRO

The template file to be used during a bootstrap operation. Use this option if the specific location of the template file is unknown. The following distributions are supported: chef-full (the default bootstrap), centos5-gems, fedora13-gems, ubuntu10.04-gems, ubuntu10.04-apt, and ubuntu12.04-gems. If this option is used, Knife will search for the template file in the following order: a bootstrap/ folder in the current working directory, a bootstrap/ folder in the Chef repository, a bootstrap/ folder in ~/.chef/, or a bootstrap file shipped with Chef. Do not use the --template-file option when --distro is specified.

-N NAME, --node-name NAME

The name of the node.

--prerelease

Indicates that pre-release Chef gems should be installed.

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

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

Examples

For example:

$ knife bootstrap windows winrm ec2-50-xx-xx-124.compute-1.amazonaws.com -r 'role[webserver],role[production]' -x Administrator -P 'super_secret_password'

winrm

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.

Syntax

This argument has the following syntax:

$ knife winrm SEARCH_QUERY SSH_COMMAND (options)

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 fully-qualified domain name 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.

-i IDENTITY_FILE, --identity-file IDENTITY_FILE

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

Indicates that a search query is 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.

-R KERBEROS_REALM, --kerberos-realm KERBEROS_REALM

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.

-S KERBEROS_SERVICE, --kerberos-service KERBEROS_SERVICE

The service principal used during Kerberos-based authentication.

SEARCH_QUERY

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.

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

Examples

For example, to find the uptime of all web servers, enter:

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

Or, to force a Chef run:

knife winrm 'ec2-50-xx-xx-124.amazonaws.com' 'chef-client -c c:/chef/client.rb' -m -x admin -P 'password'
ec2-50-xx-xx-124.amazonaws.com [date] INFO: Starting Chef Run (Version 0.9.12)
ec2-50-xx-xx-124.amazonaws.com [date] WARN: Node ip-0A502FFB has an empty run list.
ec2-50-xx-xx-124.amazonaws.com [date] INFO: Chef Run complete in 4.383966 seconds
ec2-50-xx-xx-124.amazonaws.com [date] INFO: cleaning the checksum cache
ec2-50-xx-xx-124.amazonaws.com [date] INFO: Running report handlers
ec2-50-xx-xx-124.amazonaws.com [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].