Bootstrap Windows - knife-windows - Chef

The knife-windows plugin extends Chef’s knife CLI with subcommands to bootstrap and manage Microsoft Windows nodes over Windows Remote Management (WinRM) or SSH. It enables:

Bootstrapping Windows Server nodes via WinRM (http port 5985 or https port 5986).
Executing ad-hoc remote commands via knife winrm.
Testing and configuring WinRM listeners (knife wsman).

This guide walks through installing knife-windows, preparing WinRM on a target Windows host, verifying WS-Management connectivity, troubleshooting common WinRMAuthorizationError pitfalls (such as UAC local token filtering vs. built-in Administrator), and running a complete Windows bootstrap that registers chef-client as a Windows service.

Step 1: Install Required Chef Gems on the Workstation

On your Chef Workstation, verify or install the winrm and knife-windows gems inside ChefDK’s embedded Ruby environment:

chef gem install winrm
chef gem install knife-windows

(Note: In newer versions of Chef Workstation, WinRM bootstrapping is built directly into knife bootstrap via --connection-protocol winrm, while knife bootstrap windows winrm remains supported for backward compatibility.)

Step 2: Configure WinRM on the Target Windows Node

On the target Windows Server, open PowerShell as Administrator and enable PowerShell Remoting / WinRM:

Enable-PSRemoting -Force

Open TCP port 5985 (WinRM HTTP) in Windows Firewall:

netsh advfirewall firewall add rule name="WinRM-HTTP" dir=in localport=5985 protocol=TCP action=allow

Lab / Test WinRM Configuration

In a non-domain lab environment where Kerberos is unavailable and you are testing over HTTP (5985), configure the WinRM client and service listeners to accept Basic authentication and unencrypted WinRM payloads:

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

Security Warning (Lab Only): Enabling Basic="true" and AllowUnencrypted="true" over HTTP (5985) is strictly for isolated test environments. In production, always use Negotiate / NTLM / Kerberos authentication (which encrypts the WinRM payload even over port 5985) or configure a WinRM HTTPS listener on TCP port 5986 with a valid TLS certificate.

Step 3: Verify WinRM Connectivity from the Chef Workstation

Test TCP reachability on port 5985:

nc -zv 172.22.2.222 5985
# Or with telnet:
telnet 172.22.2.222 5985

Test the WS-Management endpoint using knife wsman test:

knife wsman test 172.22.2.222 -m

Connected successfully to 172.22.2.222 at http://172.22.2.222:5985/wsman.

Step 4: Troubleshooting Common `knife bootstrap windows winrm` Errors

When bootstrapping a non-domain Windows machine, several common authentication errors can occur. Here is a summary of each failure mode and why it happens:

Attempt 1 & 4: `WinRM::WinRMAuthorizationError` (Wrong Password or Untrusted SSL Cert)

└─▪ knife bootstrap windows winrm 172.16.2.35 --winrm-user Administrator --winrm-password 'REPLACE_WITH_PASSWORD' --node-name nagios_test_windows_client --run-list 'recipe[chef-client]'
Waiting for remote response before bootstrap.ERROR: Failed to authenticate to 172.16.2.35 as Administrator
Response: WinRM::WinRMAuthorizationError
Hint: Make sure to prefix domain usernames with the correct domain name.
Hint: Local user names should be prefixed with computer name or IP address.

Why it happens: Either the password/account name is mismatched, or knife cannot verify the SSL certificate when negotiating the session.

Attempt 2: Non-Built-In Local Admin Account (`CHEF-WINDOWS-01\chef`) Denied by Windows UAC

└─▪ knife bootstrap windows winrm 172.22.2.222 --winrm-user 'CHEF-WINDOWS-01\chef' --winrm-password 'REPLACE_WITH_PASSWORD' --node-name nagiosxi_test_windows_client --winrm-ssl-verify-mode verify_none -y --run-list 'recipe[chef-client]'
Waiting for remote response before bootstrap.ERROR: Failed to authenticate to 172.22.2.222 as CHEF-WINDOWS-01\chef
Response: WinRM::WinRMAuthorizationError

Why it happens: By default, Windows User Account Control (UAC) Remote Restrictions (LocalAccountTokenFilterPolicy = 0) strip administrative privileges from non-built-in local accounts (such as chef) logging in remotely over WinRM, whereas the built-in local Administrator account (RID -500) is exempt. To use a custom local administrator account over WinRM, either use the built-in Administrator account or set LocalAccountTokenFilterPolicy = 1 under HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System.

Attempt 3: Validatorless Bootstrap Blocked Over Unencrypted Basic Auth

└─▪ knife bootstrap windows winrm 172.22.2.222 --winrm-user 'CHEF-WINDOWS-01\chef' --winrm-password 'REPLACE_WITH_PASSWORD' --node-name nagiosxi_test_windows_client --winrm-authentication-protocol basic -VV -y --run-list 'recipe[chef-client]'
DEBUG: Looking for key winrm_authentication_protocol and found value basic
DEBUG: Looking for key winrm_transport and found value plaintext
ERROR: Validatorless bootstrap over unsecure winrm channels could expose your key to network sniffing

Why it happens: Chef refuses to perform a validatorless bootstrap over plaintext HTTP with --winrm-authentication-protocol basic because the newly generated client private key would be transmitted in cleartext over the network. Leaving --winrm-authentication-protocol at its default (negotiate, which uses NTLM/Kerberos message-level encryption) resolves this error.

Step 5: Successful Windows Bootstrap (`Try 5`)

Using the built-in Administrator account, default negotiate WinRM authentication, and --winrm-ssl-verify-mode verify_none:

knife bootstrap windows winrm 172.22.2.222 \
  --winrm-user 'Administrator' \
  --winrm-password 'REPLACE_WITH_ADMIN_PASSWORD' \
  --node-name nagiosxi_test_windows_client \
  --winrm-ssl-verify-mode verify_none \
  -V -y \
  --run-list 'recipe[chef-client]'

What Happens Under the Hood During Bootstrap

As shown in the verbose (-V) bootstrap output below, knife bootstrap windows winrm:

Creates the client and node objects (nagiosxi_test_windows_client) on the Chef Server.
Connects to 172.22.2.222 over WinRM and renders a temporary bootstrap batch script (C:\Users\ADMINI~1\AppData\Local\Temp\bootstrap-*.bat).
Creates C:\chef, generates helper download scripts (C:\chef\wget.vbs and C:\chef\wget.ps1), and downloads the latest Chef Client MSI installer for Windows Server (chef-client-latest.msi).
Installs the Chef Client MSI silently (msiexec /qn /i ...).
Writes the trusted Chef Server certificate into C:\chef\trusted_certs\, writes C:\chef\client.rb and C:\chef\first-boot.json, and invokes chef-client.
Converges recipe[chef-client], which creates C:\chef\run, C:\chef\cache, C:\chef\backup, C:\chef\log, and C:\chef\client.service.rb, then registers and starts the chef-client Windows service.

Creating new client for nagiosxi_test_windows_client
Creating new node for nagiosxi_test_windows_client

Waiting for remote response before bootstrap.172.22.2.222 .
22.2.222 Response received.
Remote node responded after 0.01 minutes.
22.2.222 AMD64
Bootstrapping Chef on 172.22.2.222
22.2.222 Rendering "C:\Users\ADMINI~1\AppData\Local\Temp\bootstrap-18039-1472729874.bat" chunk 1..8
22.2.222 Checking for existing directory "C:\chef"...
22.2.222 Existing directory not found, creating.
...
22.2.222 Detected Windows Version 6.3 Build 9600
22.2.222 Installing downloaded client package...
22.2.222 C:\Users\Administrator>msiexec /qn /log "C:\Users\ADMINI~1\AppData\Local\Temp\chef-client-msi22296.log" /i "C:\Users\ADMINI~1\AppData\Local\Temp\chef-client-latest.msi"
22.2.222 Successfully installed Chef Client package.
22.2.222 Writing validation key...
22.2.222 C:\Users\Administrator>mkdir C:\chef\trusted_certs
...
22.2.222 C:\Users\Administrator>chef-client -c c:/chef/client.rb -j c:/chef/first-boot.json
22.2.222 [2016-09-01T14:40:22+03:00] INFO: *** Chef 12.13.37 ***
22.2.222 [2016-09-01T14:40:22+03:00] INFO: Platform: x64-mingw32
22.2.222 [2016-09-01T14:40:54+03:00] INFO: Run List is [recipe[chef-client]]
22.2.222 [2016-09-01T14:40:55+03:00] INFO: Loading cookbooks [chef-client@5.0.0, cron@1.7.6, logrotate@2.1.0, compat_resource@12.13.37, windows@1.44.3, chef_handler@1.4.0]
...
22.2.222 [2016-09-01T14:41:09+03:00] INFO: directory[C:/chef/run] created directory C:/chef/run
22.2.222 [2016-09-01T14:41:09+03:00] INFO: directory[C:/chef/backup] created directory C:/chef/backup
22.2.222 [2016-09-01T14:41:09+03:00] INFO: directory[C:/chef/log] created directory C:/chef/log
22.2.222 [2016-09-01T14:41:09+03:00] INFO: template[C:/chef/client.service.rb] created file C:/chef/client.service.rb
22.2.222 [2016-09-01T14:41:14+03:00] INFO: execute[register-chef-service] ran successfully
22.2.222 [2016-09-01T14:41:14+03:00] INFO: Processing windows_service[chef-client] action enable (chef-client::windows_service line 50)
22.2.222 [2016-09-01T14:41:22+03:00] INFO: windows_service[chef-client] started
22.2.222 [2016-09-01T14:41:22+03:00] INFO: Chef Run complete in 27.546223 seconds

The Windows node is now bootstrapped, registered with the Chef Server, and running chef-client as a background Windows service.

References

Share on

Twitter Facebook Google+ LinkedIn

Bootstrap Windows - knife-windows - Chef

AHMED ZBYR

Step 1: Install Required Chef Gems on the Workstation

Step 2: Configure WinRM on the Target Windows Node

Lab / Test WinRM Configuration

Step 3: Verify WinRM Connectivity from the Chef Workstation

Step 4: Troubleshooting Common `knife bootstrap windows winrm` Errors

Attempt 1 & 4: `WinRM::WinRMAuthorizationError` (Wrong Password or Untrusted SSL Cert)

Attempt 2: Non-Built-In Local Admin Account (`CHEF-WINDOWS-01\chef`) Denied by Windows UAC

Attempt 3: Validatorless Bootstrap Blocked Over Unencrypted Basic Auth

Step 5: Successful Windows Bootstrap (`Try 5`)

What Happens Under the Hood During Bootstrap

References

Share on

You May Also Enjoy

PostgreSQL Deep Dive (Part 1): Process & Memory Architecture

How a 200-Year-Old Math Trick Powers Your Wi-Fi: Fourier Transforms in Computer Networks (Explained Simply)

PHP2Shell (CVE-2026-109618) Explained Simply: How an “Out of Memory” Error Lets Attackers Take Over Your Server—And How to Fix It

Patient Zero in Canberra: When a Rogue AI Agent Hacked the Australian Healthcare System Over a Dermatology Spreadsheet

Bootstrap Windows - knife-windows - Chef

AHMED ZBYR

Step 1: Install Required Chef Gems on the Workstation

Step 2: Configure WinRM on the Target Windows Node

Lab / Test WinRM Configuration

Step 3: Verify WinRM Connectivity from the Chef Workstation

Step 4: Troubleshooting Common knife bootstrap windows winrm Errors

Attempt 1 & 4: WinRM::WinRMAuthorizationError (Wrong Password or Untrusted SSL Cert)

Attempt 2: Non-Built-In Local Admin Account (CHEF-WINDOWS-01\chef) Denied by Windows UAC

Attempt 3: Validatorless Bootstrap Blocked Over Unencrypted Basic Auth

Step 5: Successful Windows Bootstrap (Try 5)

What Happens Under the Hood During Bootstrap

References

Share on

You May Also Enjoy

PostgreSQL Deep Dive (Part 1): Process & Memory Architecture

How a 200-Year-Old Math Trick Powers Your Wi-Fi: Fourier Transforms in Computer Networks (Explained Simply)

PHP2Shell (CVE-2026-109618) Explained Simply: How an “Out of Memory” Error Lets Attackers Take Over Your Server—And How to Fix It

Patient Zero in Canberra: When a Rogue AI Agent Hacked the Australian Healthcare System Over a Dermatology Spreadsheet

Step 4: Troubleshooting Common `knife bootstrap windows winrm` Errors

Attempt 1 & 4: `WinRM::WinRMAuthorizationError` (Wrong Password or Untrusted SSL Cert)

Attempt 2: Non-Built-In Local Admin Account (`CHEF-WINDOWS-01\chef`) Denied by Windows UAC

Step 5: Successful Windows Bootstrap (`Try 5`)