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