knife-windows 0.8.2 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. checksums.yaml +5 -13
  2. data/.gitignore +1 -0
  3. data/.travis.yml +16 -2
  4. data/CHANGELOG.md +38 -4
  5. data/DOC_CHANGES.md +331 -15
  6. data/Gemfile +2 -1
  7. data/README.md +306 -71
  8. data/RELEASE_NOTES.md +63 -43
  9. data/Rakefile +9 -4
  10. data/appveyor.yml +42 -0
  11. data/ci.gemfile +15 -0
  12. data/knife-windows.gemspec +6 -4
  13. data/lib/chef/knife/bootstrap/windows-chef-client-msi.erb +96 -71
  14. data/lib/chef/knife/bootstrap_windows_base.rb +219 -37
  15. data/lib/chef/knife/bootstrap_windows_ssh.rb +22 -5
  16. data/lib/chef/knife/bootstrap_windows_winrm.rb +24 -24
  17. data/lib/chef/knife/core/windows_bootstrap_context.rb +146 -12
  18. data/lib/chef/knife/knife_windows_base.rb +33 -0
  19. data/lib/chef/knife/windows_cert_generate.rb +155 -0
  20. data/lib/chef/knife/windows_cert_install.rb +68 -0
  21. data/lib/chef/knife/windows_helper.rb +3 -1
  22. data/lib/chef/knife/windows_listener_create.rb +107 -0
  23. data/lib/chef/knife/winrm.rb +103 -206
  24. data/lib/chef/knife/winrm_base.rb +30 -11
  25. data/lib/chef/knife/winrm_knife_base.rb +218 -0
  26. data/lib/chef/knife/winrm_session.rb +81 -0
  27. data/lib/chef/knife/winrm_shared_options.rb +47 -0
  28. data/lib/chef/knife/wsman_endpoint.rb +44 -0
  29. data/lib/chef/knife/wsman_test.rb +96 -0
  30. data/lib/knife-windows/path_helper.rb +234 -0
  31. data/lib/knife-windows/version.rb +1 -1
  32. data/spec/assets/win_template_rendered_with_bootstrap_install_command.txt +217 -0
  33. data/spec/assets/win_template_rendered_without_bootstrap_install_command.txt +329 -0
  34. data/spec/assets/win_template_unrendered.txt +246 -0
  35. data/spec/functional/bootstrap_download_spec.rb +129 -35
  36. data/spec/spec_helper.rb +28 -1
  37. data/spec/unit/knife/bootstrap_options_spec.rb +150 -0
  38. data/spec/unit/knife/bootstrap_template_spec.rb +27 -26
  39. data/spec/unit/knife/bootstrap_windows_winrm_spec.rb +166 -32
  40. data/spec/unit/knife/core/windows_bootstrap_context_spec.rb +151 -0
  41. data/spec/unit/knife/windows_cert_generate_spec.rb +90 -0
  42. data/spec/unit/knife/windows_cert_install_spec.rb +51 -0
  43. data/spec/unit/knife/windows_listener_create_spec.rb +76 -0
  44. data/spec/unit/knife/winrm_session_spec.rb +56 -0
  45. data/spec/unit/knife/winrm_spec.rb +403 -118
  46. data/spec/unit/knife/wsman_test_spec.rb +176 -0
  47. metadata +67 -21
data/README.md CHANGED
@@ -1,24 +1,14 @@
1
1
  Knife Windows Plugin
2
2
  ====================
3
+ [![Build Status Master](https://travis-ci.org/chef/knife-windows.svg?branch=master)](https://travis-ci.org/chef/knife-windows)
4
+ [![Build Status Master](https://ci.appveyor.com/api/projects/status/github/chef/knife-windows?branch=master&svg=true&passingText=master%20-%20Ok&pendingText=master%20-%20Pending&failingText=master%20-%20Failing)](https://ci.appveyor.com/project/Chef/knife-windows/branch/master)
3
5
 
4
6
  This plugin adds additional functionality to the Chef Knife CLI tool for
5
- configuring/interacting with nodes running Microsoft Windows. The subcommands
6
- should function on any system running Ruby 1.9.1+ but nodes being configured
7
- via these subcommands require Windows Remote Management (WinRM) 1.0+.WinRM
8
- allows you to call native objects in Windows. This includes, but is not
9
- limited to, running batch scripts, powershell scripts and fetching WMI
10
- variables. For more information on WinRM, please visit
11
- [Microsoft's WinRM site](http://msdn.microsoft.com/en-us/library/aa384426(v=VS.85).aspx).
12
- You will want to familiarize yourself with (certain key aspects) of WinRM
13
- because you will be writing scripts / running commands with this tool to get
14
- you from specific point A to specific point B.
15
-
16
- WinRM is built into Windows 7 and Windows Server 2008+. It can also be easily installed on older version of Windows, including:
17
-
18
- * Windows Server 2003
19
- * Windows Vista
7
+ configuring / interacting with nodes running Microsoft Windows:
20
8
 
21
- More information can be found on [Microsoft Support article 968930](http://support.microsoft.com/?kbid=968930).
9
+ * Bootstrap of nodes via the [Windows Remote Management (WinRM)](http://msdn.microsoft.com/en-us/library/aa384426\(v=VS.85\).aspx) or SSH protocols
10
+ * Remote command execution using the WinRM protocol
11
+ * Utilities to configure WinRM SSL endpoints on managed nodes
22
12
 
23
13
  ## Subcommands
24
14
 
@@ -26,29 +16,60 @@ This plugin provides the following Knife subcommands. Specific command options c
26
16
 
27
17
  ### knife winrm
28
18
 
29
- The `winrm` subcommand allows you to invoke commands in parallel on a subset of the nodes in your infrastructure. The `winrm` subcommand uses the same syntax as the [search subcommand](http://wiki.opscode.com/display/chef/Search); you could could find the uptime of all your web servers using the command:
19
+ The `winrm` subcommand allows you to invoke commands in parallel on a subset of the nodes in your infrastructure. The `winrm` subcommand uses the same syntax as the [search subcommand](https://docs.chef.io/knife_search.html); you could could find the uptime of all your web servers using the command:
30
20
 
31
21
  knife winrm "role:web" "net stats srv" -x Administrator -P 'super_secret_password'
32
22
 
33
23
  Or force a chef run:
34
24
 
35
- knife winrm 'ec2-50-xx-xx-124.compute-1.amazonaws.com' 'chef-client -c c:/chef/client.rb' -m -x Administrator -P 'super_secret_password'
36
- ec2-50-xx-xx-124.compute-1.amazonaws.com [Fri, 04 Mar 2011 22:00:49 +0000] INFO: Starting Chef Run (Version 0.9.12)
37
- ec2-50-xx-xx-124.compute-1.amazonaws.com [Fri, 04 Mar 2011 22:00:50 +0000] WARN: Node ip-0A502FFB has an empty run list.
38
- ec2-50-xx-xx-124.compute-1.amazonaws.com [Fri, 04 Mar 2011 22:00:53 +0000] INFO: Chef Run complete in 4.383966 seconds
39
- ec2-50-xx-xx-124.compute-1.amazonaws.com [Fri, 04 Mar 2011 22:00:53 +0000] INFO: cleaning the checksum cache
40
- ec2-50-xx-xx-124.compute-1.amazonaws.com [Fri, 04 Mar 2011 22:00:53 +0000] INFO: Running report handlers
41
- ec2-50-xx-xx-124.compute-1.amazonaws.com [Fri, 04 Mar 2011 22:00:53 +0000] INFO: Report handlers complete
25
+ knife winrm "myserver.myorganization.net" "chef-client -c c:/chef/client.rb" -m -x Administrator -P "super_secret_password"
26
+ myserver.myorganization.net [Fri, 04 Mar 2011 22:00:49 +0000] INFO: Starting Chef Run (Version 0.9.12)
27
+ myserver.myorganization.net [Fri, 04 Mar 2011 22:00:50 +0000] WARN: Node ip-0A502FFB has an empty run list.
28
+ myserver.myorganization.net [Fri, 04 Mar 2011 22:00:53 +0000] INFO: Chef Run complete in 4.383966 seconds
29
+ myserver.myorganization.net [Fri, 04 Mar 2011 22:00:53 +0000] INFO: cleaning the checksum cache
30
+ myserver.myorganization.net [Fri, 04 Mar 2011 22:00:53 +0000] INFO: Running report handlers
31
+ myserver.myorganization.net [Fri, 04 Mar 2011 22:00:53 +0000] INFO: Report handlers complete
42
32
 
43
- This subcommand operates in a manner similar to [knife ssh](http://wiki.opscode.com/display/chef/Knife#Knife-SSHSubcommand)...just leveraging the WinRM protocol for communication. It also include's `knife ssh`'s "[interactive session mode](http://wiki.opscode.com/display/chef/Knife#Knife-InteractiveMode)"
33
+ This subcommand operates in a manner similar to [knife ssh](https://docs.chef.io/knife_ssh.html)...just leveraging the WinRM protocol for communication. It also includes `knife ssh`'s "[interactive session mode](https://docs.chef.io/knife_ssh.html#options)"
44
34
 
45
35
  ### knife bootstrap windows winrm
46
36
 
47
37
  Performs a Chef Bootstrap (via the WinRM protocol) on the target node. The goal of the bootstrap is to get Chef installed on the target system so it can run Chef Client with a Chef Server. The main assumption is a baseline OS installation exists. It is primarily intended for Chef Client systems that talk to a Chef server.
48
38
 
49
- This subcommand operates in a manner similar to [knife bootstrap](http://wiki.opscode.com/display/chef/Knife+Bootstrap)...just leveraging the WinRM protocol for communication. An initial run_list for the node can also be passed to the subcommand. Example usage:
39
+ This subcommand operates in a manner similar to [knife bootstrap](https://docs.chef.io/knife_bootstrap.html)...just leveraging the WinRM protocol for communication. An initial run_list for the node can also be passed to the subcommand. Example usage:
40
+
41
+ knife bootstrap windows winrm myserver.myorganization.net -r 'role[webserver],role[production]' -x Administrator -P 'super_secret_password'
42
+
43
+ #### Tip: Use SSL for WinRM communication
44
+
45
+ By default, the `knife winrm` and `knife bootstrap windows winrm` subcommands use a plaintext transport,
46
+ but they support an option `--winrm-transport` (or `-t`) with the argument
47
+ `ssl` that allows the SSL to secure the WinRM payload. Here's an example:
48
+
49
+ knife winrm -t ssl "role:web" "net stats srv" -x Administrator -P "super_secret_password" -f ~/server_public_cert.crt
50
+
51
+ Use of SSL is strongly recommended, particularly when invoking `knife-windows` on non-Windows platforms, since
52
+ without SSL there are limited options for ensuring the privacy of the
53
+ plaintext transport. See the section on [Platform authentication
54
+ support](#platform-winrm-authentication-support).
55
+
56
+ SSL will become the default transport in future revisions of
57
+ `knife-windows`.
58
+
59
+ ### knife wsman test
60
+
61
+ Connects to the remote WSMan/WinRM endpoint and verifies the remote node is listening. This is the equivalent of running Test-Wsman from PowerShell. Endpoints to test can be specified manually, or be driven by search and use many of the same connection options as knife winrm.
62
+ To test a single node using the default WinRM port (5985)
63
+
64
+ knife wsman test 192.168.1.10 -m
65
+
66
+ or to test a single node with SSL enabled on the default port (5986)
67
+
68
+ knife wsman test 192.168.1.10 -m --winrm-transport ssl
69
+
70
+ or to test all windows nodes registered with your Chef Server organization
50
71
 
51
- knife bootstrap windows winrm ec2-50-xx-xx-124.compute-1.amazonaws.com -r 'role[webserver],role[production]' -x Administrator -P 'super_secret_password'
72
+ knife wsman test platform:windows
52
73
 
53
74
  ### knife bootstrap windows ssh
54
75
 
@@ -58,94 +79,308 @@ This subcommand assumes the SSH session will use the Windows native cmd.exe comm
58
79
 
59
80
  An initial run_list for the node can also be passed to the subcommand. Example usage:
60
81
 
61
- knife bootstrap windows ssh ec2-50-xx-xx-124.compute-1.amazonaws.com -r 'role[webserver],role[production]' -x Administrator -i ~/.ssh/id_rsa
82
+ knife bootstrap windows ssh myserver.myorganization.net -r "role[webserver],role[production]" -x Administrator -i ~/.ssh/id_rsa
62
83
 
63
- ## BOOTSTRAP TEMPLATES:
84
+ ### knife windows cert generate
64
85
 
65
- This gem provides the bootstrap template `windows-chef-client-msi`.
86
+ Generates a certificate(x509) containing a public / private key pair for WinRM 'SSL' communication.
87
+ The certificate will be generated in three different formats *.pfx, *.b64 and *.pem.
88
+ The PKCS12(i.e *.pfx) contains both the public and private keys, usually used on the server. This will be added to WinRM Server's Certificate Store.
89
+ The *.b64 is Base64 PKCS12 key pair. Contains both the public and private keys, for upload to the Cloud REST API. e.g. Azure.
90
+ The *.pem is Base64 encoded public certificate only. Required by the client to connect to the server.
91
+ This command also displays the thumbprint of the generated certificate.
66
92
 
67
- ### windows-chef-client-msi
93
+ knife windows cert generate --cert-passphrase "strong_passphrase" --hostname "myserver.myorganization.net" --output-file "~/server_cert.pfx"
94
+ # This command will generate certificates in the user's home directory with names server_cert.b64, server_cert.pfx and server_cert.pem.
68
95
 
69
- This bootstrap template does the following:
96
+ ### knife windows cert install
70
97
 
71
- * Installs the latest version of Chef (and all dependencies) using the `chef-client` msi.
98
+ This command only functions on Windows. It adds the specified certificate to its certificate store. This command must include a valid PKCS12(i.e *.pfx) certificate file path.
99
+
100
+ knife windows cert install "~/server_cert.pfx" --cert-passphrase "strong_passphrase"
101
+
102
+ ### knife windows listener create
103
+ This command only functions on Windows. It creates the winrm listener for SSL communication(i.e HTTPS).
104
+ This command can also install certificate which is specified using --cert-install option and use the installed certificate thumbprint to create winrm listener.
105
+ --hostname option is optional. Default value for hostname is *.
106
+
107
+ knife windows listener create --cert-passphrase "strong_passphrase" --hostname "myserver.mydomain.net" --cert-install "~/server_cert.pfx"
108
+
109
+ The command also allows you to use existing certificates from local store to create winrm listener. Use --cert-thumbprint option to specify the certificate thumbprint.
110
+
111
+ knife windows listener create --cert-passphrase "strong_passphrase" --hostname "myserver.mydomain.net" --cert-thumbprint "bf0fef0bb41be40ceb66a3b38813ca489fe99746"
112
+
113
+ You can get the thumbprint for existing certificates in the local store using the following PowerShell command:
114
+
115
+ ls cert:\LocalMachine\My
116
+
117
+ ## Bootstrap template
118
+
119
+ This gem provides the bootstrap template `windows-chef-client-msi`,
120
+ which does the following:
121
+
122
+ * Installs the latest version of Chef Client (and all dependencies) using the `chef-client` msi.
72
123
  * Writes the validation.pem per the local knife configuration.
73
124
  * Writes a default config file for Chef (`C:\chef\client.rb`) using values from the `knife.rb`.
74
125
  * Creates a JSON attributes file containing the specified run list and run Chef.
75
126
 
76
- This is the default bootstrap template used by both the `windows bootstrap` subcommands.
127
+ This template is used by both `knife windows bootstrap winrm` and `knife windows bootstrap ssh` subcommands.
77
128
 
78
- ## REQUIREMENTS/SETUP:
129
+ ## Requirements / setup
79
130
 
80
131
  ### Ruby
81
132
 
82
- Ruby 1.9.1+ is needed.
133
+ Ruby 1.9.3+ is required.
83
134
 
84
- ### Chef Version
135
+ ### Chef version
85
136
 
86
- Knife plugins require >= Chef 0.10. More details about Knife plugins can be [found on the Chef wiki](http://wiki.opscode.com/display/chef/Knife+Plugins).
137
+ This knife plugins requires >= Chef 11.0.0. More details about Knife plugins can be
138
+ [found in the Chef documentation](https://docs.chef.io/plugin_knife.html).
87
139
 
88
140
  ## Nodes
89
141
 
90
- **NOTE**: Before any WinRM related knife subcommands will function correctly a node's WinRM installation must be configured correctly. The below settings should be added to your base server image (AMI) or passed in using some sort of user-data mechanism provided by your cloud provider.
142
+ ### WinRM versions
143
+
144
+ The node must be running Windows Remote Management (WinRM) 2.0+. WinRM
145
+ allows you to call native objects in Windows. This includes, but is not
146
+ limited to, running PowerShell scripts, batch scripts, and fetching WMI
147
+ data. For more information on WinRM, please visit
148
+ [Microsoft's WinRM site](http://msdn.microsoft.com/en-us/library/aa384426\(v=VS.85\).aspx).
149
+
150
+ WinRM is built into Windows 7 and Windows Server 2008+. It can also [be installed](https://support.microsoft.com/en-us/kb/968929) on older version of Windows, including:
151
+
152
+ * Windows Server 2003
153
+ * Windows Vista
91
154
 
92
- A server running WinRM must also be configured properly to allow outside connections and the entire network path from the knife workstation to the server. The easiest way to accomplish this is to use [WinRM's quick configuration option](http://msdn.microsoft.com/en-us/library/aa384372(v=vs.85).aspx#quick_default_configuration):
155
+ ### WinRM configuration
156
+
157
+ **NOTE**: Before any WinRM related knife subcommands will function
158
+ a node's WinRM installation must be configured correctly.
159
+ The settings below must be added to your base server image or passed
160
+ in using some sort of user-data mechanism provided by your cloud
161
+ provider. Some cloud providers will set up the required WinRM
162
+ configuration through the cloud API for creating instances -- see
163
+ the documentation for the provider.
164
+
165
+ A server running WinRM must also be configured properly to allow
166
+ outside connections for the entire network path from the knife workstation to the server. The easiest way to accomplish this is to use [WinRM's quick configuration option](http://msdn.microsoft.com/en-us/library/aa384372\(v=vs.85\).aspx#quick_default_configuration):
93
167
 
94
168
  winrm quickconfig -q
95
169
 
96
- The Chef and Ohai gem installations (that occur during bootstrap) take more
97
- memory than the default 150MB WinRM allocates per shell -- this can slow down
98
- bootstrap. Optionally increase the memory limit to 300MB with the following command:
170
+ This will set up an WinRM listener using the HTTP (plaintext)
171
+ transport -- WinRM also supports the SSL transport for improved
172
+ robustness against information disclosure and other threats.
99
173
 
100
- winrm set winrm/config/winrs @{MaxMemoryPerShellMB="300"}
174
+ The chef-client installation and bootstrap may take more
175
+ memory than the default 150MB WinRM allocates per shell on older versions of
176
+ Windows (prior to Windows Server 2012) -- this can slow down
177
+ bootstrap or cause it to fail. The memory limit was increased to 1GB with Windows Management Framework 3
178
+ (and Server 2012). However, there is a bug in Windows Management Framework 3
179
+ (and Server 2012) which requires a [hotfix from Microsoft](https://support.microsoft.com/en-us/kb/2842230/en-us).
180
+ You can increase the memory limit to 1GB with the following PowerShell
181
+ command:
182
+
183
+ ```powershell
184
+ set-item wsman:\localhost\shell\maxmemorypershellmb 1024
185
+ ```
101
186
 
102
187
  Bootstrap commands can take longer than the WinRM default 60 seconds to
103
188
  complete, optionally increase to 30 minutes if bootstrap terminates a command prematurely:
104
189
 
105
- winrm set winrm/config @{MaxTimeoutms="1800000"}
190
+ ```powershell
191
+ set-item wsman:\localhost\MaxTimeoutms 300000
192
+ ```
193
+
194
+ Note that the `winrm` command itself supports the same configuration
195
+ capabilities as the PowerShell commands given above -- if you need to
196
+ configure WinRM without using PowerShell, use `winrm -?` to get help.
197
+
198
+ WinRM supports both the HTTP and HTTPS (SSL) transports and the following
199
+ authentication schemes: Kerberos, Digest, Certificate and Basic. The details
200
+ of these authentication transports are outside of the scope of this
201
+ README but details can be found on the
202
+ [WinRM configuration guide](http://msdn.microsoft.com/en-us/library/aa384372\(v=vs.85\).aspx).
203
+
204
+ #### Configure SSL on a Windows node
205
+
206
+ WinRM supports use of SSL to provide privacy and integrity of
207
+ communication using the protocol and to prevent spoofing attacks.
208
+
209
+ ##### Configure SSL using `knife`
210
+
211
+ `knife-windows` includes three commands to assist with SSL
212
+ configuration -- these commands support all versions of Windows and do
213
+ not rely on PowerShell:
214
+
215
+ * `knife windows cert generate`: creates a certificate that may be used
216
+ to configure an SSL WinRM listener
217
+
218
+ * `knife windows cert install`: Installs a certificate into the
219
+ Windows certificate store so it can be used to configure an SSL
220
+ WinRM listener.
221
+
222
+ * `knife windows listener create`: Creates a WinRM listener on a
223
+ Windows node -- it can use either a certificate already installed in
224
+ the Windows certificate store, or one created by other tools
225
+ including the `knife windows cert generate` command.
226
+
227
+ Here is an example that configures a listener on the node on which the
228
+ commands are executed:
229
+
230
+ knife windows cert generate --domain myorg.org --output-file $env:userprofile/winrmcerts/winrm-ssl
231
+ knife windows listener create --hostname *.myorg.org --cert-install $env:userprofile/winrmcerts/winrm-ssl.pfx
232
+
233
+ Note that the first command which generates the certificate for the
234
+ listener could be executed from any system that can run `knife` as
235
+ long as the certificate it generates is made available at a path at
236
+ which the second command can access it.
237
+
238
+ See previous sections for additional details of the `windows cert generate`, `windows cert install` and `windows listener create` subcommands.
106
239
 
107
- WinRM supports both the HTTP and HTTPS transports and the following
108
- authentication schemes: Kerberos, Digest, Certificate and Basic. The details
109
- of these authentication transports are outside of the scope of this README but
110
- details can be found on the
111
- [WinRM configuration guide](http://msdn.microsoft.com/en-us/library/aa384372(v=vs.85).aspx).
112
- Currently, this plugin support Kerberos and Basic authentication schemes on
113
- all platform versions. The negotiate protocol which allows NTLM is fully
114
- supported when `knife windows bootstrap` is executed on a Windows system; if
115
- it is executed on a non-Windows system, certificate authentication or Kerberos
116
- should be used instead via the `:kerberos_service` and related options of the subcommands.
240
+ ##### Configure SSL using *Windows Server 2012 or later*
241
+ The following PowerShell commands may be used to create an SSL WinRM
242
+ listener with a self-signed certificate on Windows 2012R2 or later systems:
117
243
 
118
- **NOTE**: In order to use NTLM / Negotiate to authenticate as the user
119
- specified by the `--winrm-user` (`-x`) option, you must include the user's
120
- Windows domain when specifying the user name using the format `domain\user`
121
- where the backslash ('`\`') character separates the user from the domain. If
122
- an account local to the node is being used to access, `.` may be used as the domain:
244
+ ```powershell
245
+ $cert = New-SelfSignedCertificate -DnsName 'myserver.mydomain.org' -CertStoreLocation Cert:\LocalMachine\My
246
+ new-item -address * -force -path wsman:\localhost\listener -port 5986 -hostname ($cert.subject -split '=')[1] -transport https -certificatethumbprint $cert.Thumbprint
247
+ # Open the firewall for 5986, the default WinRM SSL port
248
+ netsh advfirewall firewall set rule name="Windows Remote Management (HTTPS-In)" profile=public protocol=tcp localport=5986 remoteip=localsubnet new remoteip=any
123
249
 
124
- knife bootstrap windows winrm web1.cloudapp.net -r 'server::web' -x 'proddomain\webuser' -P 'super_secret_password'
125
- knife bootstrap windows winrm db1.cloudapp.net -r 'server::db' -x '.\localadmin' -P 'super_secret_password'
250
+ ```
126
251
 
127
- For development and testing purposes, unencrypted traffic with Basic authentication can make it easier to test connectivity:
252
+ Note that the first command which uses the `New-SelfSignedCertificate`
253
+ cmdlet is available only in PowerShell version 4.0 and later.
128
254
 
129
- winrm set winrm/config/service @{AllowUnencrypted="true"}
130
- winrm set winrm/config/service/auth @{Basic="true"}
255
+ ##### Configure SSL using `winrm quickconfig`
256
+
257
+ The following command can configure an SSL WinRM listener if the
258
+ Windows certificate store's Local Machine store contains a certificate
259
+ that meets certain criteria that are most likely to be met if the
260
+ system is joined to a Windows Active Directory domain:
131
261
 
132
- ## Troubleshooting
262
+ winrm quickconfig -transport:https -q
263
+
264
+ If the criteria are not met, an error message will follow with
265
+ guidance on the certificate requirements; you may need to obtain a
266
+ certificate from the appropriate source or use the PowerShell or
267
+ `knife` techniques given above to create the listener instead.
268
+
269
+ ##### Disabling peer verification
270
+ In the SSL examples above, the `-f` parameter was used to supply a
271
+ certificate that could validate the identity of the remote server.
272
+ For debugging purposes, this validation may be skipped if you have not
273
+ obtained a public certificate that can validate the server. Here is an
274
+ example:
275
+
276
+ knife winrm -m 192.168.0.6 -x "mydomain\myuser" -P $PASSWD -t ssl --winrm-ssl-verify-mode verify_none ipconfig
277
+
278
+ This option should be used carefully since disabling the verification of the
279
+ remote system's certificate can subject knife commands to spoofing attacks.
280
+
281
+ ## WinRM authentication
282
+
283
+ The default authentication protocol for `knife-windows` subcommands that use
284
+ WinRM is the Negotiate protocol. The following commands when executed on a
285
+ Windows system show authentication for domain and local accounts respectively:
286
+
287
+ knife bootstrap windows winrm web1.cloudapp.net -r "server::web" -x "proddomain\webuser" -P "super_secret_password"
288
+ knife bootstrap windows winrm db1.cloudapp.net -r "server::db" -x "localadmin" -P "super_secret_password"
289
+
290
+ The commands above are using the default plaintext transport for WinRM --
291
+ the default of Negotiate authentication may not be fully supported on
292
+ non-Windows systems using the plaintext transport. To work around this, the
293
+ remote system can be configured with an SSL WinRM listener instead of a
294
+ plaintext listener. Then the above commands should be modified to use the SSL
295
+ transport as follows using the `-t` (or `--winrm-transport`) option with the
296
+ `ssl` argument:
297
+
298
+ knife bootstrap windows winrm -t ssl web1.cloudapp.net -r "server::web" -x "proddomain\webuser" -P "super_secret_password" -f ~/mycert.crt
299
+ knife bootstrap windows winrm -t ssl db1.cloudapp.net -r "server::db" -x "localadmin" -P "super_secret_password" ~/mycert.crt
300
+
301
+ The commands using SSL above will work from any operating system, not
302
+ just Windows.
303
+
304
+ ### Troubleshooting authentication
305
+
306
+ For development and testing purposes, unencrypted traffic with Basic
307
+ authentication can make it easier to test connectivity. The configuration for
308
+ the remote system may be accomplished with the following PowerShell commands:
309
+
310
+ ```powershell
311
+ set-item wsman:\localhost\service\allowunencrypted $true
312
+ set-item wsman:\localhost\service\auth\basic $true
313
+ ```
314
+ To test connectivity via `knife-windows` from another system, the default
315
+ authentication protocol of Negotiate must be overridden using the
316
+ `--winrm-authentication-protocol` option with the desired protocol, in this
317
+ case Basic:
318
+
319
+ knife winrm -m web1.cloudapp.net --winrm-authentication-protocol basic ipconfig -x localadmin -P "super_secret_password"
320
+
321
+ Note that when using Basic authentication, domain accounts may not be used for
322
+ authentication; an account local to the remote system must be used.
323
+
324
+ ### Platform WinRM authentication support
325
+
326
+ `knife-windows` supports `Kerberos`, `Negotiate`, and `Basic` authentication
327
+ for WinRM communication. However, some of these protocols
328
+ may not work with `knife-windows` on non-Windows systems because
329
+ `knife-windows` relies on operating system libraries such as GSSAPI to implement
330
+ Windows authentication, and some versions of these libraries do not
331
+ fully implement the protocols.
332
+
333
+ The following table shows the authentication protocols that can be used with
334
+ `knife-windows` depending on whether the knife workstation is a Windows
335
+ system, the transport, and whether or not the target user is a domain user or
336
+ local to the target Windows system.
337
+
338
+ | Workstation OS / Account Scope | SSL | Plaintext |
339
+ |--------------------------------|------------------------------|----------------------------|
340
+ | Windows / Local | Kerberos, Negotiate* , Basic | Kerberos, Negotiate, Basic |
341
+ | Windows / Domain | Kerberos, Negotiate | Kerberos, Negotiate |
342
+ | Non-Windows / Local | Kerberos, [Negotiate*](https://github.com/chef/knife-windows/issues/176) Basic | Kerberos, Basic |
343
+ | Non-Windows / Domain | Kerberos, Negotiate | Kerberos |
344
+
345
+ > \* There is a known defect in the `knife winrm` and `knife bootstrap windows
346
+ > winrm` subcommands invoked on any OS platform when authenticating with the Negotiate protocol over
347
+ > the SSL transport. The defect is tracked by
348
+ > [knife-windows issue #176](https://github.com/chef/knife-windows/issues/176): If the remote system is
349
+ > domain-joined, local accounts may not be used to authenticate via Negotiate
350
+ > over SSL -- only domain accounts will work. Local accounts will only
351
+ > successfully authenticate if the system is not joined to a domain.
352
+ >
353
+ > This is generally not an issue for bootstrap scenarios, where the
354
+ > system has yet to be joined to any domain, but can be a problem for remote
355
+ > management cases after the system is domain joined. Workarounds include using
356
+ > a domain account instead, or enabling Basic authentication on the remote
357
+ > system (unencrypted communication **does not** need to be enabled to make
358
+ > Basic authentication function over SSL).
359
+
360
+ ## General troubleshooting
361
+
362
+ * Windows 2008R2 and earlier versions require an extra configuration
363
+ for MaxTimeoutms to avoid WinRM::WinRMHTTPTransportError: Bad HTTP
364
+ response error while bootstrapping. It should be at least 300000.
365
+
366
+ `set-item wsman:\\localhost\\MaxTimeoutms 300000`
133
367
 
134
368
  * When I run the winrm command I get: "Error: Invalid use of command line. Type "winrm -?" for help."
135
369
  You're running the winrm command from PowerShell and you need to put the key/value pair in single quotes. For example:
136
370
 
137
- winrm set winrm/config/winrs '@{MaxMemoryPerShellMB="512"}'
371
+ `winrm set winrm/config/winrs '@{MaxMemoryPerShellMB="1024"}'`
372
+
138
373
 
139
374
  ## CONTRIBUTING:
140
375
 
141
- Please file bugs against the KNIFE_WINDOWS project at https://github.com/opscode/knife-windows/issues.
376
+ Please file bugs against the KNIFE_WINDOWS project at https://github.com/chef/knife-windows/issues.
142
377
 
143
- More information on the contribution process for Opscode projects can be found in the [Chef Contributions document](http://docs.opscode.com/community_contributions.html).
378
+ More information on the contribution process for Chef projects can be found in the [Chef Contributions document](http://docs.chef.io/community_contributions.html).
144
379
 
145
380
  # LICENSE:
146
381
 
147
- Author:: Seth Chisamore (<schisamo@opscode.com>)
148
- Copyright:: Copyright (c) 2014 Opscode, Inc.
382
+ Author:: Seth Chisamore (<schisamo@chef.io>)
383
+ Copyright:: Copyright (c) 2015 Chef Software, Inc.
149
384
  License:: Apache License, Version 2.0
150
385
 
151
386
  Licensed under the Apache License, Version 2.0 (the "License");
data/RELEASE_NOTES.md CHANGED
@@ -6,57 +6,77 @@ Example Note:
6
6
  ## Example Heading
7
7
  Details about the thing that changed that needs to get included in the Release Notes in markdown.
8
8
  -->
9
- # knife-windows 0.8.2 release notes:
10
- This release of knife-windows addresses a regression in knife-windows 0.8.0
11
- from previous releases where `knife winrm` and `knife bootstrap windows`
12
- commands fail due to inability to authenticate:
13
- [knife-windows #108](https://github.com/opscode/knife-windows/issues/108).
9
+ # knife-windows 1.0.0 release notes:
10
+ This release of knife-windows includes new features to improve authentication,
11
+ simplify use of the WinRM SSL transport, install and download Chef
12
+ Client during bootstrap, and addresses compatibility issues with Chef Client 12.0.
14
13
 
15
- You can install the fix for this issue by upgrading to this new version using
16
- the `gem` command:
14
+ You can install the new features using the `gem` command:
17
15
 
18
- gem install knife-windows --pre
16
+ gem install knife-windows
19
17
 
20
- A thank you goes to **Richard Lavey** for reporting [knife-windows #108](https://github.com/opscode/knife-windows/issues/108).
18
+ Due to dependency conflicts, to use knife-windows 1.0.0+ with ChefDK
19
+ 0.6.2, you must also upgrade chef-provisioning to 1.2.0+ and update
20
+ the line referencing chef-provisioning in
21
+ `c:\opscode\chefdk\bin\chef`. To avoid this, use ChefDk 0.7.0 or later
22
+ with this version of `knife-windows`.
21
23
 
22
- ## Impact of [knife-windows #108](https://github.com/opscode/knife-windows/issues/108)
23
-
24
- [knife-windows #108](https://github.com/opscode/knife-windows/issues/108) will affect a given user if all of the following are true:
25
-
26
- * You are running `knife-windows` subcommands on a Windows workstation
27
- * The remote node you're interacting with via `knife-windows` has a WinRM
28
- configuration with the `WSMan:\localhost\Service\AllowUnencrypted` (in
29
- PowerShell's WinRM settings drive provider)
30
-
31
- In this situation, you will receive an authentication error message from
32
- the `knife winrm` or `knife bootstrap windows` command such as
33
- `Error: Unencrypted communication not supported`. To resolve this error,
34
- simply install this version of the gem as described earlier.
35
-
36
- If you are running the `knife` commands from a non-Windows operating system,
37
- [knife-windows #108](https://github.com/opscode/knife-windows/issues/108) does
38
- not affect you, so you don't need to upgrade just for this issue.
24
+ chef gem install knife-windows
25
+ chef gem install chef-provisioning
39
26
 
40
27
  ## Reporting issues and contributing
41
28
 
42
- `knife-windows` issues like the one addressed in this release should be
43
- reported in the ticketing system at https://github.com/opscode/knife-windows/issues. You can learn more about how to contribute features and bug fixes to `knife-windows` in the [Chef Contributions document](http://docs.opscode.com/community_contributions.html).
44
-
45
- ## Features added in knife-windows 0.8.2
46
- None.
47
-
48
- ## Issues fixed in knife-windows 0.8.2
49
- [knife-windows #108](https://github.com/opscode/knife-windows/issues/108) Error: Unencrypted communication not supported if remote server does not require encryption
50
-
51
- The fix in this release will cause a behavior change from the 0.8.0 release:
52
-
53
- * As described in the [documentation changes](https://github.com/opscode/knife-windows/blob/0.8.0/DOC_CHANGES.md) for the 0.8.0 release of the `knife-windows`, the negotiate authentication
54
- protocol will only be used in this 0.8.2 release if a domain is specified (you can specify '.' as
55
- the domain if you want to use the local workstation as the domain). Due to a
56
- defect in the 0.8.0 release, the negotiate protocol was being used even when
57
- the domain was not specified.
29
+ `knife-windows` issues like those addressed in this release should be reported in the ticketing system at https://github.com/chef/knife-windows/issues. You can learn more about how to contribute features and bug fixes to `knife-windows` in the [Chef Contributions document](http://docs.chef.io/community_contributions.html).
30
+
31
+ ## Breaking changes
32
+
33
+ ### Negotiate as the default authentication protocol
34
+ With this release, the default authentication protocol for WinRM
35
+ communication is negotiate, which is the same as that for tools built-in to
36
+ the Windows operating system. Prior to this release, the protocol depended
37
+ on the format of the `--winrm-user` option -- the basic authentication
38
+ protocol would be assumed unless that option had the format `domain\user`.
39
+
40
+ To revert to the behavior of previous releases or otherwise force `knife-windows` to use a specific authentication protocol such as
41
+ basic, use the `--winrm-authentication-protocol` option.
42
+
43
+ ### Default WinRM port depends on the transport
44
+ The default port for WinRM communication is now **5986** when the SSL transport is used (the transport is
45
+ configured by the `winrm_transport` option), otherwise it is **5985**. In
46
+ previous releases, if the port was not specified, it was always 5985.
47
+
48
+ To override this behavior, explicitly specify the desired port using the
49
+ `winrm_port` (`-p`) option.
50
+
51
+ ### Kerberos Keytab short option is now -T
52
+ The short option flag for --keytab-file is now -T to fix a conflict with the --identity-file option.
53
+
54
+ ## Features added in knife-windows 1.0.0
55
+ * New `--winrm-authentication-protocol` option for explicit control of WinRM authentication
56
+ * `knife windows cert generate` subcommand:
57
+ Generates a certificate and related public key file for use in configuring a WinRM listener and validating communication involving it.
58
+ * `knife windows cert install` subcommand:
59
+ Installs a certificate such as one generated by the `cert generate`
60
+ subcommand into the Windows certificate store's LocalMachine personal store
61
+ so that it can be used as part of the configuration for a WinRM SSL listener
62
+ * `knife windows listener create` subcommand:
63
+ Creates a WinRM SSL listener on a Windows system
64
+ * Added `--hint` option for creating Ohai hints on bootstrap
65
+ * Validatorless bootstrapping is now supported
66
+ * New `--bootstrap-install-command` option allows an alternate command
67
+ to be used to install Chef Client
68
+ * New `--install-as-service` option will have Chef Client be installed
69
+ as a Windows service on bootstrap
70
+ * Added `--msi_url` option for providing an alternate URL to the Chef Client installation package
71
+ * `knife wsman test` subcommand:
72
+ Verifies winrm functionality on a remote system, e.g. `knife wsman
73
+ test 192.168.1.10 -m --winrm-transport ssl`
74
+
75
+ ## Issues fixed in knife-windows 1.0.0
76
+ See the [knife-windows 1.0.0 CHANGELOG](https://github.com/chef/knife-windows/blob/1.0.0/CHANGELOG.md)
77
+ for the list of issues fixed in this release.
58
78
 
59
79
  ## knife-windows on RubyGems and Github
60
80
  https://rubygems.org/gems/knife-windows
61
- https://github.com/opscode/knife-windows
81
+ https://github.com/chef/knife-windows
62
82
 
data/Rakefile CHANGED
@@ -4,11 +4,16 @@ Bundler::GemHelper.install_tasks
4
4
  begin
5
5
  require 'rspec/core/rake_task'
6
6
 
7
- task :default => :spec
7
+ task :default => [:unit_spec, :functional_spec]
8
8
 
9
- desc "Run all specs in spec directory"
10
- RSpec::Core::RakeTask.new(:spec) do |t|
11
- t.pattern = 'spec/**/*_spec.rb'
9
+ desc "Run all functional specs in spec directory"
10
+ RSpec::Core::RakeTask.new(:functional_spec) do |t|
11
+ t.pattern = 'spec/functional/**/*_spec.rb'
12
+ end
13
+
14
+ desc "Run all unit specs in spec directory"
15
+ RSpec::Core::RakeTask.new(:unit_spec) do |t|
16
+ t.pattern = 'spec/unit/**/*_spec.rb'
12
17
  end
13
18
 
14
19
  rescue LoadError