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
checksums.yaml CHANGED
@@ -1,15 +1,7 @@
1
1
  ---
2
- !binary "U0hBMQ==":
3
- metadata.gz: !binary |-
4
- M2QyMmEwMTg1NGM2ZWEyNzdhYjFhMzE3YWI0NDY1NjcxNzU3NzgxNQ==
5
- data.tar.gz: !binary |-
6
- MmU3YWEzNjFhMWJjYTY2NzlkY2Q3NWMzMDYyZTMwMDNkYWZkZDNmOQ==
2
+ SHA1:
3
+ metadata.gz: b8379925d2d838d0a7aa4eb8272d76b552b79959
4
+ data.tar.gz: 5a49c146219b795d55dffeda41fa81b79942bcb6
7
5
  SHA512:
8
- metadata.gz: !binary |-
9
- YTI3MTczYWRmNzBjZDg5MTMyMjA4NjdlMWNiMTdhNDEyYjhhZmE0NTI5NjA2
10
- YTU0Mjk3OWY2NmMyZjM5MTcyNDI4NzFiZWUwMmRmMTUyNDI2MGJiOTFhMDJi
11
- NGJhYmQ1NzMxMzIyN2IyMzU1ODZkZTczMzE2YTA0MWExM2RiNTA=
12
- data.tar.gz: !binary |-
13
- ZmVmMTEwZTU4NjdmOWI2NmE4MTczYTM1YmRhNjAxMjY3NWIzZDUwYmIwYmE5
14
- ODk5NmMzYzZjNzBkZDMxY2I3ZGEwODU2YTk0ZDJhNWRjMWYwZTk3YTQ3MmRi
15
- NWFkZTVlYTUxNTRkNjgxNTVmNTU5Nzg5ZTliNjNlNmExZTgwNjM=
6
+ metadata.gz: 78319d369c8c9cdb1c5f87e3010d6468ff17c898b71e1c2a6d75930ce539fce5f44541293113f26a34b0cf8dd960372f5cbe22db1157aefc191e0ba012c3ef73
7
+ data.tar.gz: aeda179f22c1036fc9f90a8e9cfdbdfebeb72e466b9c5713de574bdc0b48394b8c92306e875b16026d1d689b45a8b16cac91910ff34f7be7534fbcba91106c9a
data/.gitignore CHANGED
@@ -1,4 +1,5 @@
1
1
  *.gem
2
2
  .bundle
3
3
  Gemfile.lock
4
+ ci.gemfile.lock
4
5
  pkg/*
data/.travis.yml CHANGED
@@ -1,6 +1,20 @@
1
+ language: ruby
2
+
1
3
  rvm:
2
- - 1.9.2
3
4
  - 1.9.3
4
5
  - 2.0.0
5
6
 
6
- script: bundle exec rake spec
7
+ gemfile: ci.gemfile
8
+
9
+ env:
10
+ - CHEF_VERSION="master"
11
+ - CHEF_VERSION="~> 12.0"
12
+ - CHEF_VERSION="< 12"
13
+
14
+ matrix:
15
+ exclude:
16
+ - rvm: 1.9.3
17
+ env: CHEF_VERSION="master"
18
+ - rvm: 1.9.3
19
+ env: CHEF_VERSION="~> 12.0"
20
+
data/CHANGELOG.md CHANGED
@@ -1,12 +1,46 @@
1
1
  # knife-windows Change Log
2
2
 
3
- ## Unreleased changes
4
- None.
3
+ ## Release 1.0.0
5
4
 
6
- ## Latest release: 0.8.2
5
+ * [knife-windows #281](https://github.com/chef/knife-windows/pull/281) Prevent unencrypted negotiate auth, automatically prefix local usernames with '.' for negotiate
6
+ * [knife-windows #275](https://github.com/chef/knife-windows/pull/275) Added bootstrap\_install\_command option in parity with knife bootstrap
7
+ * [knife-windows #240](https://github.com/chef/knife-windows/pull/240) Change kerberos keytab short option to -T to resolve conflict
8
+ * [knife-windows #232](https://github.com/chef/knife-windows/pull/232) Adding --hint option to bootstrap
9
+ * [knife-windows #227](https://github.com/chef/knife-windows/issues/227) Exception: NoMethodError: undefined method 'gsub' for false:FalseClass
10
+ * [knife-windows #222](https://github.com/chef/knife-windows/issues/222) Validatorless bootstrap support
11
+ * [knife-windows #202](https://github.com/chef/knife-windows/issues/202) knife windows bootstrap should support enabling the service
12
+ * [knife-windows #213](https://github.com/chef/knife-windows/pull/213) Search possibilities of HOME for bootstrap templates
13
+ * [knife-windows #206](https://github.com/chef/knife-windows/pull/206) Add a flag msi_url that allows one to fetch the Chef client msi from a non-chef.io path
14
+ * [knife-windows #192](https://github.com/chef/knife-windows/issues/192) deprecate knife bootstrap --distro
15
+ * [knife-windows #159](https://github.com/opscode/knife-windows/issues/159) `winrm_port` option should default to 5986 if `winrm_transport` option is `ssl`
16
+ * [knife-windows #149](https://github.com/chef/knife-windows/pull/149) Adding knife wsman test to validate WSMAN/WinRM availability
17
+ * [knife-windows #139](https://github.com/opscode/knife-windows/issues/139) Force dev dependency on Chef 11 for test scenarios to avoid Ohai 8 conflict on Ruby 1.9.x
18
+ * [knife-windows #126](https://github.com/opscode/knife-windows/pull/126) Allow disabling of SSL peer verification in knife-windows for testing
19
+ * [knife-windows #154](https://github.com/opscode/knife-windows/issues/154) Unreleased regression in master: NameError: undefined local variable or method `path_separator
20
+ * [knife-windows #143](https://github.com/opscode/knife-windows/issues/143) Unreleased regression in master: WinRM::WinRMHTTPTransportError: Bad HTTP response returned from server (503) in the middle of bootstrap
21
+ * [knife-windows #133](https://github.com/opscode/knife-windows/issues/133) Bootstrap failure -- unable to validate SSL chef server endpoints
22
+ * [knife-windows #132](https://github.com/opscode/knife-windows/issues/132) New subcommands for WinRM: windows listener create, cert generate, and cert install
23
+ * [knife-windows #129](https://github.com/opscode/knife-windows/issues/129) New --winrm-authentication-protocol option for explicit control of authentication
24
+ * [knife-windows #125](https://github.com/opscode/knife-windows/issues/125) knife-windows should use PowerShell first before cscript to download the Chef Client msi
25
+ * [knife-windows #92](https://github.com/opscode/knife-windows/issues/92) EventMachine issue: knife bootstrap windows winrm error
26
+ * [knife-windows #94](https://github.com/opscode/knife-windows/issues/94) Remove Eventmachine dependency
27
+ * [knife-windows #252](https://github.com/chef/knife-windows/pull/252) Fail early on ECONNREFUSED, Closes #244.
28
+ * [knife-windows #260](https://github.com/chef/knife-windows/pull/260) Fail quickly on invalid option combinations, Closes #259
29
+
30
+ ## Release: 0.8.5
31
+ * [knife-windows #228](https://github.com/chef/knife-windows/pull/228) make winrm-s dep more strict on knife-windows 0.8.x
32
+
33
+ ## Release: 0.8.4
34
+ * [knife-windows #133](https://github.com/opscode/knife-windows/issues/133) Bootstrap failure -- unable to validate SSL chef server endpoints
35
+
36
+ ## Release: 0.8.3
37
+ * [knife-windows #131](https://github.com/opscode/knife-windows/issues/108) Issue #131: Windows should be bootstrapped using latest Chef Client version compatible with knife's version just like non-Windows systems
38
+ * [knife-windows #139](https://github.com/opscode/knife-windows/issues/139) Force dev dependency on Chef 11 for test scenarios to avoid Ohai 8 conflict on Ruby 1.9.x
39
+
40
+ ## Release: 0.8.2
7
41
  * [knife-windows #108](https://github.com/opscode/knife-windows/issues/108) Error: Unencrypted communication not supported if remote server does not require encryption
8
42
 
9
- ## Latest release: 0.8.0
43
+ ## Release: 0.8.0
10
44
  * [knife-windows #98](https://github.com/opscode/knife-windows/issues/98) Get winrm command exit code if it is not expected
11
45
  * [knife-windows #96](https://github.com/opscode/knife-windows/issues/96) Fix break from OS patch KB2918614
12
46
  * Remove the 'instance data' method of creating EC2 servers
data/DOC_CHANGES.md CHANGED
@@ -5,19 +5,335 @@ Example Doc Change:
5
5
  ### Headline for the required change
6
6
  Description of the required change.
7
7
  -->
8
+ # knife-windows 1.0.0 doc changes
8
9
 
9
- # knife-windows 0.8.2 doc changes
10
-
11
- ### Negotiate / NTLM authentication support
12
- If you are running `knife-windows` subcommands from a Windows workstation, you
13
- should not specify a username argument that includes a domain name (i.e. a
14
- name formatted like `domain\user`) unless the remote host has WinRM's
15
- `AllowUnencrypted` setting set to `$false` (the default setting on Windows if
16
- the `winrm quickconfig` command was used to enable WinRM). If you've modified
17
- the host to set this to `$true` instead of its default value and you run
18
- subcommands from a Windows workstation where the username specified to
19
- `knife-windows` contains a domain, the command will fail with an
20
- authentication error. To avoid this, omit the domain name (this will only work
21
- if the system is not joined to a domain, i.e. you were specifying the local
22
- workstation as the domain), or set `AllowUnencrypted` to `$false` which is a
23
- more secure setting.
10
+ ### New bootstrap download and installation options
11
+ The following commands enable alternate ways to download and install
12
+ Chef Client during bootstrap:
13
+
14
+ * `--msi-url URL`: Optional. Used to override the location from which Chef
15
+ Client is downloaded. If not specified, Chef Client is downloaded
16
+ from the Internet -- this option allows downloading from a private network
17
+ location for instance.
18
+ * `--install-as-service`: Optional. Install chef-client as a Windows service
19
+ * `--bootstrap-install-command`: Optional. Instead of downloading Chef
20
+ Client and installing it using a default installation command,
21
+ bootstrap will invoke this command. If an image already has
22
+ Chef Client installed, this command can be specified as empty
23
+ (`''`), in which case no installation will be done and the rest of
24
+ bootstrap will proceed as if it's already installed.
25
+
26
+ ### WinRM default port default change
27
+ The `winrm_port` option specifies the TCP port on the remote system to which
28
+ to connect for WinRM communication for `knife-windows` commands that use
29
+ WinRM. The default value of this option is **5986** if the WinRM transport
30
+ (configured by the `winrm_transport` option) is SSL, otherwise it is **5985**.
31
+ These defaults correspond to the port assignment conventions for the WinRM
32
+ protocol, which is also honored by WinRM tools built-in to Windows such as the
33
+ `winrs` tool.
34
+
35
+ In previous releases, the default port was always 5985, regardless of the
36
+ transport being used. To override the default, specify the `winrm_port`
37
+ (`-p`) option and specify the desired port as the option's value.
38
+
39
+ ### WinRM authentication protocol defaults to `negotiate` regardless of name formats
40
+ Unless explicitly overridden using the new `winrm_authentication_protocol`
41
+ option, `knife-windows` subcommands that use WinRM will authenticate using the
42
+ negotiate protocol, just as the tools built-in to the Windows operating
43
+ system would do.
44
+
45
+ Previously, `knife-windows` would use basic authentication, unless the
46
+ username specified to the `winrm_user` option had the format `domain\user`,
47
+ and in that case `knife-windows` would use negotiate authentication.
48
+
49
+ To override the new behavior, specify the `winrm_authentication_protocol`
50
+ option with a value of either the `basic` or `kerberos` to choose a different
51
+ authentication protocol.
52
+
53
+ ### New `:winrm_authentication_protocol` option
54
+
55
+ This option allows the authentication protocol used for WinRM communication to
56
+ be explicitly specified. The supported protocol values are `kerberos`, `negotiate`,
57
+ and `basic`, each of which directs `knife-windows` to use the respective authentication protocols.
58
+
59
+ If the option is not specified, `knife-windows` treats this as a default value
60
+ of `negotiate` and the tool uses negotiate authentication for WinRM.
61
+
62
+ ### New `:winrm_ssl_verify_mode` option
63
+ When running the `winrm` and `bootstrap windows` subcommands with the
64
+ `winrm_transport` option set to `ssl` to communicate with a remote Windows system using
65
+ the WinRM protocol via the SSL transport, you may disable `knife`'s verification of
66
+ the remote system's SSL certificate. This is useful for testing or
67
+ troubleshooting SSL connectivity before you've verified the certificate of the remote system's SSL WinRM listener.
68
+
69
+ The option that controls whether the server is validated is the
70
+ `knife[:winrm_verify_ssl_mode]` option, which has the same values as Chef's
71
+ [`:ssl_verify_mode`](https://docs.getchef.com/config_rb_client.html#settings) option. By default, the option is set to `:verify_peer`,
72
+ which means that SSL communication must be verified using a certificate file
73
+ specified by the `:ca_trust_file` option. To avoid the need to have this file available
74
+ during testing, you can specify the `knife[:winrm_ssl_verify_mode]` option in
75
+ `knife.rb` OR specify it directly on the `knife` command line as
76
+ `--winrm-ssl-verify-mode` and set its value to `:verify_none`, which will
77
+ override the default behavior and skip the verification of the remote system
78
+ -- there is no need to specify the `:ca_trust_file` option in this case.
79
+
80
+ Here's an example that disables peer verification:
81
+
82
+ knife winrm -m 192.168.0.6 -x 'mydomain\myuser' -P "$PASSWORDVAR" -t ssl --winrm-ssl-verify-mode verify_none ipconfig
83
+
84
+ This option should be used carefully since disabling the verification of the
85
+ remote system's certificate can subject knife commands to spoofing attacks.
86
+
87
+ ### New subcommands to automate WinRM SSL listener configuration
88
+ The WinRM protocol may be encapsulated by SSL, but the configuration of such
89
+ connections can be difficult, particularly when the WinRM client is a
90
+ non-Windows system. Three new knife subcommands have been implemented in
91
+ knife-windows 1.0.0.rc.0 to simplify and automate this configuration:
92
+
93
+ * `knife windows cert generate` subcommand:
94
+ Generates certificates in formats useful for creating WinRM SSL listeners.
95
+ It also generates a related public key file in .pem format to validating
96
+ communication involving listeners configured with the generated certificate.
97
+ * `knife windows cert install` subcommand:
98
+ Installs a certificate such as one generated by the `cert generate`
99
+ subcommand into the Windows certificate store so that it can be used as the
100
+ SSL certificate for a WinRM listener. This command will only function on the
101
+ Windows operating system. Certificates are always installed in the
102
+ computer's personal store, i.e. the store that can be viewed via the
103
+ PowerShell command `ls Cert:\LocalMachine\My`.
104
+ * `knife windows listener create` subcommand:
105
+ Creates a WinRM listener on a Windows system. This command functions only on
106
+ the Windows operating system.
107
+
108
+ #### Example WinRM listener configuration workflows
109
+
110
+ The subcommands are used in the following scenarios
111
+
112
+ ##### Creation of a new listener with a new SSL certificate
113
+
114
+ This workflow assumes that WinRM is enabled on the system, which can be
115
+ accomplished with the command
116
+
117
+ winrm quickconfig
118
+
119
+ If you're creating a listener and don't already have an SSL certificate with
120
+ which to configure it, you can quickly create an enabled listener with a short
121
+ sequence of commands. The example below assumes that the `knife-windows`
122
+ plugin is being executed on a Windows system via the PowerShell command shell,
123
+ and that the system is registered with the relevant DNS with the name
124
+ `mysystem.myorg.org` and that this is the name with which the user would like
125
+ to remotely access this system.
126
+
127
+ This sequence of commands creates a listener -- it assumes the existence of the directory `winrmcerts`
128
+ under the user's profile directory:
129
+
130
+ knife windows cert generate --domain myorg.org --output-file $env:userprofile/winrmcerts/winrm-ssl
131
+ knife windows listener create --hostname *.myorg.org --cert-install $env:userprofile/winrmcerts/winrm-ssl.pfx
132
+
133
+ The first command, `cert generate`, may be executed on any computer (even one not running the
134
+ Windows operating system) and produces three files. The first two are certificates containing
135
+ private keys that should be stored securely. The 3rd is a `.pem` file
136
+ containing the public key required to validate the server. This file may be
137
+ shared. The command also outputs the thumbprint of the generated certificate,
138
+ which is useful for finding the certificate in a certificate store or using
139
+ with other commands that require the thumbprint.
140
+
141
+ The next command, `listener create`, creates the SSL listener -- if it is executed on a different
142
+ system than that which generated the certificates, the required certificate
143
+ file **must** be transferred securely to the system on which the listener will
144
+ be created. It requires a PKCS12 `.pfx` file for the `--cert-install` argument
145
+ which is one of the files generated by the previous `cert generate` command.
146
+
147
+ After these commands are executed, an SSL listener will be created listening
148
+ on TCP port 5986, the default WinRM SSL port. Using PowerShell, the following
149
+ command will show this and other listeners on the system:
150
+
151
+ ls wsman:\localhost\listener
152
+
153
+ As an alternative to the command sequence above, the `cert install` command could be used to install the
154
+ certificate in a separate step, i which case the `--cert-install` option must
155
+ be replaced with the `--cert-thumbprint` option to use the generated
156
+ certificate's thumbprint to identify the certificate with which the listener
157
+ should be configured:
158
+
159
+ knife windows cert generate --domain myorg.org --output-file $env:userprofile/winrmcerts/winrm-ssl
160
+ knife windows cert install $env:userprofile/winrmcerts/winrm-ssl
161
+ knife windows listener create --hostname *.myorg.org --cert-thumbprint 1F3A70E2601FA1576BC4850ED2D7EF6587076423
162
+
163
+ The system would then be in the same state as that after the original shorter
164
+ command sequence.
165
+
166
+ Note that the `cert install` command could be skipped if the certificate
167
+ already exists in the personal certificate store of the computer. To view that store and
168
+ see the thumbprints of certificates that could be used with the `listener
169
+ create` command to create an SSL listener, the following PowerShell command
170
+ may be executed:
171
+
172
+ ls Cert:\LocalMachine\My
173
+
174
+ ##### Connecting to a configured SSL listeners
175
+
176
+ In order to connect securely to the configured SSL listener via the `knife
177
+ winrm` or `knife bootstrap windows winrm` subcommands, the workstation running
178
+ `knife` must have a `.pem` file that contains the listener's public key, such
179
+ as the one generated by `knife windows cert generate`. If the file was
180
+ generated from a different system than the one initiating the connection with
181
+ the listener, it must be transferred securely to the initiating system.
182
+
183
+ For example, assume the file `./winrmcerts/myserver.pem` was securely
184
+ copied from another system on which the `cert generate` command originally
185
+ produced the file. Now it can be used against a system with the appropriately
186
+ configured listener as follows:
187
+
188
+ knife winrm -f ./winrmcerts/myserver.pem -m myserver.myorg.com -t ssl ipconfig -x 'my_ad_domain\myuser' -P "$PASSWORDVAR"
189
+
190
+ This will send the output of the Windows command `ipconfig` on the remote
191
+ system. The argument to the `-f` option is the public key for the listener so
192
+ that the listener's authenticity can be validated. The specified key
193
+ can simply be a copy of the `.pem` file generated by the `cert generate` subcommand if
194
+ that was used to create the certificates for the listener. The user
195
+ `my_ad_domain\myuser` in the example is a user in the Windows Active Directory
196
+ domain `my_ad_domain`.
197
+
198
+ Alternatively, the [`knife ssl fetch`](https://docs.chef.io/knife_ssl_fetch.html) command can be used to retrieve the
199
+ public key for the listener by simply reading it from the listener, though this command *must* be executed under
200
+ conditions where the connection to the server is considered secure:
201
+
202
+ knife ssl fetch https://myserver.myorg.org:5986/wsman
203
+ knife winrm -f ./.chef/trusted_certs/wildcard_myorg_org.crt -m myserver.myorg.com -t ssl ipconfig -x 'my_ad_domain\myuser' -P "$PASSWORDVAR"
204
+
205
+ In the `fetch` subcommand, the URL specified for testing WinRM connectivity to
206
+ a given server SERVER on port PORT takes the form `https://SERVER:PORT/wsman`,
207
+ hence the url specified above to retrieve the key for `myserver.myorg.org`.
208
+ The command also outputs the location to which the key was retrieved, which
209
+ can then be used as input to a subsequent `knife winrm` command.
210
+
211
+ For that `knife winrm` command in the example, the argument to the `-f` option is again the public key -- this time its value
212
+ of `./.chef/trusted_certs/wildcard_myorg_org.crt` is the file system location to which
213
+ `knife ssl fetch` retrieved the public key.
214
+
215
+ #### Testing WinRM SSL configuration
216
+
217
+ The techniques below are useful for validating a WinRM listener's configuration -- all
218
+ examples below assume there is a WinRM SSL listener configured on a remote Windows
219
+ system `winserver.myoffice.com` on the default WinRM port of 5986 and this is
220
+ the server being tested.
221
+
222
+ ##### PowerShell's `test-wsman` cmdlet
223
+ If you have access to a workstation running
224
+ the Windows 8 or Windows Server 2012 or later versions of the Windows
225
+ operating systems, you can use the `test-wsman` command to validate the
226
+ configuration of a listener on a remote system `winserver.myoffice.com`:
227
+
228
+ 1. On the Windows workstation client (not the system with the listener),
229
+ install the .pfx public key certificate for the listener using
230
+ certmgr.msc. This should be installed in the personal store under *"Trusted
231
+ Root Certification Authorities"*.
232
+ 2. Start PowerShell, and use it to run this command:
233
+ `test-wsman -ComputerName winserver.myoffice.com -UseSSL`
234
+
235
+ If the command executes without error, the ssl configuration is correct.
236
+
237
+ ##### End to end SSL testing with `knife winrm`
238
+
239
+ To validate that SSL is enabled for the listener without validating the
240
+ server's certificate, the `--winrm-ssl-verify-mode` option of the `winrm`
241
+ subcommand can be used:
242
+
243
+ knife winrm -m winserver.myoffice.com -t ssl --winrm-ssl-verify-mode verify_none ipconfig -x 'my_ad_domain\myuser' -P "$PASSWORDVAR"
244
+
245
+ If this succeeds, then any failures to execute the command when correctly
246
+ validating the server, i.e. when specifying the `-f` parameter, are due to
247
+ certificate configuration issues, not other connectivity or authentication
248
+ problems.
249
+
250
+ ##### The winrs tool
251
+
252
+ The `winrs` tool is built into Windows, so if a Windows system is available,
253
+ `winrs` may be used to troubleshoot. It takes parameters analogous to those of
254
+ `knife winrm` and differences in success and failure between the two tools may
255
+ indicate areas to investigate.
256
+
257
+ Visit Microsoft's documentation for [`winrs`](https://technet.microsoft.com/en-us/library/hh875630.aspx) to learn more about the tool.
258
+
259
+ ### Troubleshooting WinRM authentication issues
260
+
261
+ Authentication issues can be debugged by loosening the authentication
262
+ requirements on the server and explicitly using
263
+ `--winrm-authentication-protocol` option for `knife winrm` to attempt to
264
+ connect. As an example, the following PowerShell commands on the server will allow basic authentication
265
+ and unencrypted communication:
266
+
267
+ si wsman:\localhost\service\allowunencrypted $true
268
+ # Don't set the following if attempting domain authentication
269
+ si wsman:\localhost\service\auth\basic $true
270
+
271
+ From the client, `knife winrm` can be instructed to explicitly allow basic
272
+ authentication when validating authentication using a non-domain (i.e. local)
273
+ account:
274
+
275
+ # For testing a local account
276
+ knife winrm -m winserver.myoffice.com --winrm-authentication-protocol basic ipconfig -x 'localuser' -P "$PASSWORDVAR" -VV
277
+
278
+ # For testing a domain account
279
+ knife winrm -m winserver.myoffice.com --winrm-authentication-protocol negotiate ipconfig -x 'localuser' -P "$PASSWORDVAR" -VV
280
+
281
+ If the listener is an SSL listener, the additional arguments `-t ssl
282
+ --winrm-ssl-verify-mode verify_none` should be supplied to enable SSL
283
+ communication and disable peer verification for testing. The specification of
284
+ `-VV` enables additional detailed debug output that can provide clues to the
285
+ root cause of any failures.
286
+
287
+ If the command fails, there is either a connectivity issue or a problem with
288
+ an incorrect or expired password or disabled account.
289
+
290
+ If the command succeeds, try the following
291
+
292
+ si wsman:\localhost\service\allowunencrypted $false
293
+
294
+ Then retry the earlier `knife winrm` command. If it fails, this may indicate
295
+ an issue with your operating system's ability to encrypt traffic, particularly
296
+ when using the `plaintext` transport, i.e. when not using the `SSL` transport.
297
+ In that case, the Windows platform supports encryption of plaintext traffic
298
+ through native Windows authentication protocols, but such support is often incomplete on other platforms.
299
+
300
+ If the command succeeds, then there may be a more subtle issue with negotiate
301
+ authentication. It may be necessary to explicitly specify a domain in the user
302
+ name parameter (e.g. `mydomain\myuser` rather than just `user`) for instance,
303
+ or a specified domain may actually be incorrect and something that should be omitted.
304
+
305
+ ### Platform WinRM authentication support
306
+
307
+ `knife-windows` supports `Kerberos`, `Negotiate`, and `Basic` authentication
308
+ for WinRM communication. However, some of these protocols
309
+ may not work with `knife-windows` on non-Windows systems because
310
+ `knife-windows` relies on operating system libraries such as GSSAPI to implement
311
+ Windows authentication, and some versions of these libraries do not
312
+ fully implement the protocols.
313
+
314
+ The following table shows the authentication protocols that can be used with
315
+ `knife-windows` depending on whether the knife workstation is a Windows
316
+ system, the transport, and whether or not the target user is a domain user or
317
+ local to the target Windows system.
318
+
319
+ | Workstation OS / Account Scope | SSL | Plaintext |
320
+ |--------------------------------|------------------------------|----------------------------|
321
+ | Windows / Local | Kerberos, Negotiate* , Basic | Kerberos, Negotiate, Basic |
322
+ | Windows / Domain | Kerberos, Negotiate | Kerberos, Negotiate |
323
+ | Non-Windows / Local | Kerberos, [Negotiate*](https://github.com/chef/knife-windows/issues/176) Basic | Kerberos, Basic |
324
+ | Non-Windows / Domain | Kerberos, Negotiate | Kerberos |
325
+
326
+ > \* There is a known defect in the `knife winrm` and `knife bootstrap windows
327
+ > winrm` subcommands invoked on any OS platform when authenticating with the Negotiate protocol over
328
+ > the SSL transport. The defect is tracked by
329
+ > [knife-windows issue #176](https://github.com/chef/knife-windows/issues/176): If the remote system is
330
+ > domain-joined, local accounts may not be used to authenticate via Negotiate
331
+ > over SSL -- only domain accounts will work. Local accounts will only
332
+ > successfully authenticate if the system is not joined to a domain.
333
+ >
334
+ > This is generally not an issue for bootstrap scenarios, where the
335
+ > system has yet to be joined to any domain, but can be a problem for remote
336
+ > management cases after the system is domain joined. Workarounds include using
337
+ > a domain account instead, or enabling Basic authentication on the remote
338
+ > system (unencrypted communication **does not** need to be enabled to make
339
+ > Basic authentication function over SSL).
data/Gemfile CHANGED
@@ -4,8 +4,9 @@ source "https://rubygems.org"
4
4
  gemspec
5
5
 
6
6
  group :test do
7
+ gem "chef"
7
8
  gem "rspec", '~> 3.0'
8
9
  gem "ruby-wmi"
9
- gem "chef"
10
+ gem "httpclient"
10
11
  gem 'rake'
11
12
  end