knife-windows 1.0.0.rc.1 → 1.0.0.rc.2
Sign up to get free protection for your applications and to get access to all the features.
- 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).
|