knife windows

[edit on GitHub]

The knife windows subcommand is used to interact with Windows systems managed by Chef Infra. Nodes are configured using WinRM, which allows external applications to call native objects like batch scripts, Windows PowerShell scripts, or scripting library variables. The knife windows subcommand supports NTLM and Kerberos methods of authentication.

cert generate

Use the cert generate argument to generate certificates for use with WinRM SSL listeners. This argument also generates a related public key file (in .pem format) to validate communication between listeners that are configured to use the generated certificate.

Syntax

This argument has the following syntax:

knife windows cert generate FILE_PATH (options)

Options

This argument has the following options:

-cp PASSWORD, --cert-passphrase PASSWORD

The password for the SSL certificate.

-cv MONTHS, --cert-validity MONTHS

The number of months for which a certificate is valid. Default value: 24.

-h HOSTNAME, --hostname HOSTNAME

The hostname for the listener. For example, --hostname something.mydomain.com or *.mydomain.com. Default value: *.

-k LENGTH, --key-length LENGTH

The length of the key. Default value: 2048.

-o PATH, --output-file PATH

The location in which the winrmcert.b64, winrmcert.pem, and winrmcert.pfx files are generated. For example: --output-file /home/.winrm/server_cert will create server_cert.b64, server_cert.pem, and server_cert.pfx in the server_cert directory. Default location: current_directory/winrmcert.

cert install

Use the cert install argument to install a certificate (such as one generated by the cert generate argument) into the Windows certificate store so that it may be used as the SSL certificate by a WinRM listener.

Syntax

This argument has the following syntax:

knife windows cert install CERT [CERT] (options)

Options

This argument has the following options:

-cp PASSWORD, --cert-passphrase PASSWORD

The password for the SSL certificate.

listener create

Use the listener create argument to create a WinRM listener on the Windows platform.

Syntax

This argument has the following syntax:

knife windows listener create (options)

Options

This argument has the following options:

-c CERT_PATH, --cert-install CERT_PATH

Add the specified certificate to the store before creating the listener.

-cp PASSWORD, --cert-passphrase PASSWORD

The password for the SSL certificate.

-h HOST_NAME, --hostname HOST_NAME

The hostname for the listener. For example, --hostname something.mydomain.com or *.mydomain.com. Default value: *.

-p PORT, --port PORT

The WinRM port. Default value: 5986.

-t THUMBPRINT, --cert-thumbprint THUMBPRINT

The thumbprint of the SSL certificate. Required when the --cert-install option is not part of a command.

Examples

Generate an SSL certificate, and then create a listener

Use the listener create, cert generate, and cert install arguments to create a new listener and assign it a newly-generated SSL certificate. First, make sure that WinRM is enabled on the machine. Do so by running the following command on the Windows node:

C:\> winrm quickconfig

Create the SSL certificate

knife windows cert generate --domain myorg.org --output-file $env:userprofile/winrmcerts/winrm-ssl

This command may be run on any machine and will output three file types: .b64, .pem, and .pfx.

Next, create the SSL listener:

knife windows listener create --hostname *.myorg.org --cert-install $env:userprofile/winrmcerts/winrm-ssl.pfx

This will use the same .pfx file that was output by the cert generate argument. If the command is run on a different machine from that which generated the certificates, the required certificate files must first be transferred securely to the system on which the listener will be created. (Use the cert install argument to install a certificate on a machine.)

The SSL listener is created and should be listening on TCP port 5986, which is the default WinRM SSL port.