Chef

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 WinRM, which allows native objects—batch scripts, Windows PowerShell scripts, or scripting library variables—to be called by external applications. The knife windows subcommand supports NTLM, Kerberos, and certificate authority (CA) methods of authentication.

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:

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

Requirements

This subcommand requires WinRM to be installed, and then configured correctly, including ensuring the correct ports are open. For more information, see: http://msdn.microsoft.com/en-us/library/aa384372(v=vs.85).aspx and/or http://support.microsoft.com/kb/968930. Use the quick configuration option in WinRM to allow outside connections and the entire network path from knife (and the workstation):

$ winrm quickconfig -q

The following WinRM 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"}

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"}

Ensure that the Windows Firewall is configured to allow WinRM connections between the workstation and the Chef server. 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.) WinRM 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, first use the winrm argument in the knife windows plugin to verify communication with the node:

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

and then run a command similar to the following:

$ knife bootstrap windows winrm 'node1.domain.com' -r 'role[webserver]' -x domain\\administrator -P '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.

Syntax

This argument has the following syntax:

$ knife bootstrap windows ssh (options)

Options

This argument has the following options:

--auth-timeout MINUTES,
The amount of time (in minutes) to wait for authentication to succeed. Default: 2.
--bootstrap-no-proxy NO_PROXY_URL_or_IP
A URL or IP address that specifies a location that should not be proxied.
--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.
-G GATEWAY, --ssh-gateway GATEWAY
The SSH tunnel or gateway that is used to run a bootstrap action on a machine that is not accessible from the workstation.
-i IDENTITY_FILE, --identity-file IDENTITY_FILE
The SSH identity file used for authentication. Key-based authentication is recommended.
-j JSON_ATTRIBS, --json-attributes JSON_ATTRIBS
A JSON string that is added to the first run of a chef-client.
-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
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
The encryption key that is used for values contained within a data bag item.
--secret-file SECRET_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.

bootstrap windows winrm

The bootstrap windows winrm argument is used to bootstrap chef-client installations in a Microsoft Windows environment, using WinRM and the WS-Management protocol for communication. This argument requires the FQDN of the host machine to be specified. The Microsoft Installer Package (MSI) run silently during the bootstrap operation (using the /qn option).

Syntax

This argument has the following syntax:

$ knife bootstrap windows winrm FQDN

Options

This argument has the following options:

--auth-timeout MINUTES,
The amount of time (in minutes) to wait for authentication to succeed. Default: 2.
--bootstrap-no-proxy NO_PROXY_URL_or_IP
A URL or IP address that specifies a location that should not be proxied.
--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.
-j JSON_ATTRIBS, --json-attributes JSON_ATTRIBS
A JSON string that is added to the first run of a chef-client.
-N NAME, --node-name NAME
The name of the node.
--prerelease
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
The encryption key that is used for values contained within a data bag item.
--secret-file SECRET_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.

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.

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

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 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
Optional. The certificate authority (CA) trust file used for SSL transport.
-i IDENTITY_FILE, --identity-file IDENTITY_FILE
The keytab file that contains the encryption key required by Kerberos-based authentication.
--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 WinRM port. Default: 5985.
-P PASSWORD, --winrm-password PASSWORD
The WinRM password.
-R KERBEROS_REALM, --kerberos-realm KERBEROS_REALM
Optional. 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
Optional. 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 WinRM transport type: ssl or plaintext.
-x USERNAME, --winrm-user USERNAME
The WinRM user name.

Examples

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

Bootstrap a Windows machine using SSH

To bootstrap a Microsoft Windows machine using SSH:

$ 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 a Windows machine using Windows Remote Management

To bootstrap a Microsoft Windows machine using WinRM:

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