knife-windows 0.8.6 → 1.0.0.rc.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b1ec9c8dd7c8a66f06b72b2e46bc3e172477bd7a
-  data.tar.gz: 2a07331546fc140023af2b6e4ef8bb3abb174f24
+  metadata.gz: e51a14571a819d9ff57f8ff5c1f9be04e45645a0
+  data.tar.gz: fd8710840fd171781b95ed291b2c2926aa503fdf
 SHA512:
-  metadata.gz: 9f287cd625f4b21850b54293cb2c7b8cf104c35f06d966ad3e319d4da258fad285870b3b07d668e554b3d2761c877e2092f2db279dcadb98db8d454dd02f1ea6
-  data.tar.gz: b5a6ef473ba830356a6aafa6295a6732f837ea618542750cf077d6d3d3dbc99167d755ce1aa940b3f84ba4fac8b7b72edb2a53bfdfa855438661ca944835d337
+  metadata.gz: f7e087bfadbb0825a9a3a27388df0e4262642b39aaa839eb9d7396dd1a83d8bf92d4f454881a979c938fbff7c12c9f7104b6f5ae38aabbab3759487fc5ec5888
+  data.tar.gz: 7cdddbaa21aff487fc7a2c4db10e26b52d8929a4c06d4b74db252ac1fbe2e6b38fdf94359ea3d10c490718d0c11917c08fbf96b488043771d276865ce82557e4

data/.gitignore

@@ -1,4 +1,5 @@
 *.gem
 .bundle
 Gemfile.lock
+ci.gemfile.lock
 pkg/*

data/.travis.yml

@@ -1,6 +1,20 @@
+language: ruby
+
 rvm:
+  - 1.9.3
   - 2.0.0
-  - 2.1.5
-  - 2.2.0
 
-script: bundle exec rake spec
+gemfile: ci.gemfile
+
+env:
+  - CHEF_VERSION="master"
+  - CHEF_VERSION="~> 12.0"
+  - CHEF_VERSION="< 12"
+
+matrix:
+  exclude:
+  - rvm: 1.9.3
+    env: CHEF_VERSION="master"
+  - rvm: 1.9.3
+    env: CHEF_VERSION="~> 12.0"
+

data/CHANGELOG.md

@@ -1,23 +1,42 @@
 # knife-windows Change Log
 
-## Latest release: 0.8.6
-* [knife-windows #268](https://github.com/chef/knife-windows/issues/268) Use winrm 1.3.x in 0.8-stable
+## Unreleased changes
+
+* [knife-windows #240](https://github.com/chef/knife-windows/pull/240) Change kerberos keytab short option to -T to resolve conflict
+* [knife-windows #232](https://github.com/chef/knife-windows/pull/232) Adding --hint option to bootstrap
+* [knife-windows #227](https://github.com/chef/knife-windows/issues/227) Exception: NoMethodError: undefined method 'gsub' for false:FalseClass
+* [knife-windows #222](https://github.com/chef/knife-windows/issues/222) Validatorless bootstrap support
+* [knife-windows #202](https://github.com/chef/knife-windows/issues/202) knife windows bootstrap should support enabling the service
+* [knife-windows #213](https://github.com/chef/knife-windows/pull/213) Search possibilities of HOME for bootstrap templates
+* [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
+* [knife-windows #192](https://github.com/chef/knife-windows/issues/192) deprecate knife bootstrap --distro
+* [knife-windows #159](https://github.com/opscode/knife-windows/issues/159) `winrm_port` option should default to 5986 if `winrm_transport` option is `ssl`
+* [knife-windows #149](https://github.com/chef/knife-windows/pull/149) Adding knife wsman test to validate WSMAN/WinRM availability
+* [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
+* [knife-windows #126](https://github.com/opscode/knife-windows/pull/126) Allow disabling of SSL peer verification in knife-windows for testing
+* [knife-windows #154](https://github.com/opscode/knife-windows/issues/154) Unreleased regression in master: NameError: undefined local variable or method `path_separator
+* [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
+* [knife-windows #133](https://github.com/opscode/knife-windows/issues/133) Bootstrap failure -- unable to validate SSL chef server endpoints
+* [knife-windows #132](https://github.com/opscode/knife-windows/issues/132) New subcommands for WinRM: windows listener create, cert generate, and cert install
+* [knife-windows #129](https://github.com/opscode/knife-windows/issues/129) New --winrm-authentication-protocol option for explicit control of authentication
+* [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
+* [knife-windows #92](https://github.com/opscode/knife-windows/issues/92) EventMachine issue: knife bootstrap windows winrm error
+* [knife-windows #94](https://github.com/opscode/knife-windows/issues/94) Remove Eventmachine dependency
 
 ## Release: 0.8.5
-* [knife-windows #228](https://github.com/chef/knife-windows/issues/228) make winrm-s dep more strict on knife-windows 0.8.x
+* [knife-windows #228](https://github.com/chef/knife-windows/pull/228) make winrm-s dep more strict on knife-windows 0.8.x
 
 ## Release: 0.8.4
 * [knife-windows #133](https://github.com/opscode/knife-windows/issues/133) Bootstrap failure -- unable to validate SSL chef server endpoints
 
 ## Release: 0.8.3
-* [knife-windows #131](https://github.com/opscode/knife-windows/issues/108): Windows should be bootstrapped using latest Chef Client version compatible with knife's version just like non-Windows systems
-* [knife-windows #162](https://github.com/chef/knife-windows/issues/162): fixes "uninitialized constant Chef::Knife::Bootstrap (NameError)"
+* [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
+* [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
 
 ## Release: 0.8.2
 * [knife-windows #108](https://github.com/opscode/knife-windows/issues/108) Error: Unencrypted communication not supported if remote server does not require encryption
 
 ## Release: 0.8.0
-
 * [knife-windows #98](https://github.com/opscode/knife-windows/issues/98) Get winrm command exit code if it is not expected
 * [knife-windows #96](https://github.com/opscode/knife-windows/issues/96) Fix break from OS patch KB2918614
 * Remove the 'instance data' method of creating EC2 servers

data/DOC_CHANGES.md

@@ -0,0 +1,323 @@
+<!---
+This file is reset every time a new release is done. This file describes changes that have not yet been released.
+
+Example Doc Change:
+### Headline for the required change
+Description of the required change.
+-->
+# knife-windows 1.0.0 doc changes
+
+### WinRM default port default change
+The `winrm_port` option specifies the TCP port on the remote system to which
+to connect for WinRM communication for `knife-windows` commands that use
+WinRM. The default value of this option is **5986** if the WinRM transport
+(configured by the `winrm_transport` option) is SSL, otherwise it is **5985**.
+These defaults correspond to the port assignment conventions for the WinRM
+protocol, which is also honored by WinRM tools built-in to Windows such as the
+`winrs` tool.
+
+In previous releases, the default port was always 5985, regardless of the
+transport being used. To override the default, specify the `winrm_port`
+(`-p`) option and specify the desired port as the option's value.
+
+### WinRM authentication protocol defaults to `negotiate` regardless of name formats
+Unless explicitly overridden using the new `winrm_authentication_protocol`
+option, `knife-windows` subcommands that use WinRM will authenticate using the
+negotiate protocol, just as the tools built-in to the Windows operating
+system would do.
+
+Previously, `knife-windows` would use basic authentication, unless the
+username specified to the `winrm_user` option had the format `domain\user`,
+and in that case `knife-windows` would use negotiate authentication.
+
+To override the new behavior, specify the `winrm_authentication_protocol`
+option with a value of either the `basic` or `kerberos` to choose a different
+authentication protocol.
+
+### New `:winrm_authentication_protocol` option
+
+This option allows the authentication protocol used for WinRM communication to
+be explicitly specified. The supported protocol values are `kerberos`, `negotiate`,
+and `basic`, each of which directs `knife-windows` to use the respective authentication protocols.
+
+If the option is not specified, `knife-windows` treats this as a default value
+of `negotiate` and the tool uses negotiate authentication for WinRM.
+
+### New `:winrm_ssl_verify_mode` option
+When running the `winrm` and `bootstrap windows` subcommands with the
+`winrm_transport` option set to `ssl` to communicate with a remote Windows system using
+the WinRM protocol via the SSL transport, you may disable `knife`'s verification of
+the remote system's SSL certificate. This is useful for testing or
+troubleshooting SSL connectivity before you've verified the certificate of the remote system's SSL WinRM listener.
+
+The option that controls whether the server is validated is the
+`knife[:winrm_verify_ssl_mode]` option, which has the same values as Chef's
+[`:ssl_verify_mode`](https://docs.getchef.com/config_rb_client.html#settings) option. By default, the option is set to `:verify_peer`,
+which means that SSL communication must be verified using a certificate file
+specified by the `:ca_trust_file` option. To avoid the need to have this file available
+during testing, you can specify the `knife[:winrm_ssl_verify_mode]` option in
+`knife.rb` OR specify it directly on the `knife` command line as
+`--winrm-ssl-verify-mode` and set its value to `:verify_none`, which will
+override the default behavior and skip the verification of the remote system
+-- there is no need to specify the `:ca_trust_file` option in this case.
+
+Here's an example that disables peer verification:
+
+    knife winrm -m 192.168.0.6 -x 'mydomain\myuser' -P "$PASSWORDVAR" -t ssl --winrm-ssl-verify-mode verify_none ipconfig 
+
+This option should be used carefully since disabling the verification of the
+remote system's certificate can subject knife commands to spoofing attacks.
+
+### New subcommands to automate WinRM SSL listener configuration
+The WinRM protocol may be encapsulated by SSL, but the configuration of such
+connections can be difficult, particularly when the WinRM client is a
+non-Windows system. Three new knife subcommands have been implemented in
+knife-windows 1.0.0.rc.0 to simplify and automate this configuration:
+
+* `knife windows cert generate` subcommand:
+  Generates certificates in formats useful for creating WinRM SSL listeners.
+  It also generates a related public key file in .pem format to validating
+  communication involving listeners configured with the generated certificate.
+* `knife windows cert install` subcommand:
+  Installs a certificate such as one generated by the `cert generate`
+  subcommand into the Windows certificate store so that it can be used as the
+  SSL certificate for a WinRM listener. This command will only function on the
+  Windows operating system. Certificates are always installed in the
+  computer's personal store, i.e. the store that can be viewed via the
+  PowerShell command `ls Cert:\LocalMachine\My`.
+* `knife windows listener create` subcommand:
+  Creates a WinRM listener on a Windows system. This command functions only on
+  the Windows operating system.
+
+#### Example WinRM listener configuration workflows
+
+The subcommands are used in the following scenarios
+
+##### Creation of a new listener with a new SSL certificate
+
+This workflow assumes that WinRM is enabled on the system, which can be
+accomplished with the command
+
+    winrm quickconfig
+
+If you're creating a listener and don't already have an SSL certificate with
+which to configure it, you can quickly create an enabled listener with a short
+sequence of commands. The example below assumes that the `knife-windows`
+plugin is being executed on a Windows system via the PowerShell command shell,
+and that the system is registered with the relevant DNS with the name
+`mysystem.myorg.org` and that this is the name with which the user would like
+to remotely access this system.
+
+This sequence of commands creates a listener -- it assumes the existence of the directory `winrmcerts`
+under the user's profile directory:
+
+    knife windows cert generate --domain myorg.org --output-file $env:userprofile/winrmcerts/winrm-ssl 
+    knife windows listener create --hostname *.myorg.org --cert-install $env:userprofile/winrmcerts/winrm-ssl.pfx 
+
+The first command, `cert generate`, may be executed on any computer (even one not running the
+Windows operating system) and produces three files. The first two are certificates containing
+private keys that should be stored securely. The 3rd is a `.pem` file
+containing the public key required to validate the server. This file may be
+shared. The command also outputs the thumbprint of the generated certificate,
+which is useful for finding the certificate in a certificate store or using
+with other commands that require the thumbprint.
+
+The next command, `listener create`,  creates the SSL listener -- if it is executed on a different
+system than that which generated the certificates, the required certificate
+file **must** be transferred securely to the system on which the listener will
+be created. It requires a PKCS12 `.pfx` file for the `--cert-install` argument
+which is one of the files generated by the previous `cert generate` command.
+
+After these commands are executed, an SSL listener will be created listening
+on TCP port 5986, the default WinRM SSL port. Using PowerShell, the following
+command will show this and other listeners on the system:
+
+    ls wsman:\localhost\listener
+
+As an alternative to the command sequence above, the `cert install` command could be used to install the
+certificate in a separate step, i which case the `--cert-install` option must
+be replaced with the `--cert-thumbprint` option to use the generated
+certificate's thumbprint to identify the certificate with which the listener
+should be configured:
+
+    knife windows cert generate --domain myorg.org --output-file $env:userprofile/winrmcerts/winrm-ssl 
+    knife windows cert install $env:userprofile/winrmcerts/winrm-ssl
+    knife windows listener create --hostname *.myorg.org --cert-thumbprint 1F3A70E2601FA1576BC4850ED2D7EF6587076423
+
+The system would then be in the same state as that after the original shorter
+command sequence.
+
+Note that the `cert install` command could be skipped if the certificate
+already exists in the personal certificate store of the computer. To view that store and
+see the thumbprints of certificates that could be used with the `listener
+create` command to create an SSL listener, the following PowerShell command
+may be executed:
+
+    ls Cert:\LocalMachine\My
+
+##### Connecting to a configured SSL listener
+
+In order to connect securely to the configured SSL listener via the `knife
+winrm` or `knife bootstrap windows winrm` subcommands, the workstation running
+`knife` must have a `.pem` file that contains the listener's public key, such
+as the one generated by `knife windows cert generate`. If the file was
+generated from a different system than the one initiating the connection with
+the listener, it must be transferred securely to the initiating system.
+
+For example, assume the file `./winrmcerts/myserver.pem` was securely
+copied from another system on which the `cert generate` command originally
+produced the file. Now it can be used against a system with the appropriately
+configured listener as follows:
+
+    knife winrm -f ./winrmcerts/myserver.pem -m myserver.myorg.com -t ssl ipconfig -x 'my_ad_domain\myuser' -P "$PASSWORDVAR"
+
+This will send the output of the Windows command `ipconfig` on the remote
+system. The argument to the `-f` option is the public key for the listener so
+that the listener's authenticity can be validated. The specified key
+can simply be a copy of the `.pem` file generated by the `cert generate` subcommand if
+that was used to create the certificates for the listener. The user
+`my_ad_domain\myuser` in the example is a user in the Windows Active Directory
+domain `my_ad_domain`.
+
+Alternatively, the [`knife ssl fetch`](https://docs.chef.io/knife_ssl_fetch.html) command can be used to retrieve the
+public key for the listener by simply reading it from the listener, though this command *must* be executed under
+conditions where the connection to the server is considered secure:
+
+     knife ssl fetch https://myserver.myorg.org:5986/wsman
+     knife winrm -f ./.chef/trusted_certs/wildcard_myorg_org.crt -m myserver.myorg.com -t ssl ipconfig -x 'my_ad_domain\myuser' -P "$PASSWORDVAR"
+
+In the `fetch` subcommand, the URL specified for testing WinRM connectivity to
+a given server SERVER on port PORT takes the form `https://SERVER:PORT/wsman`,
+hence the url specified above to retrieve the key for `myserver.myorg.org`.
+The command also outputs the location to which the key was retrieved, which
+can then be used as input to a subsequent `knife winrm` command.
+
+For that `knife winrm` command in the example, the argument to the `-f` option is again the public key -- this time its value
+of `./.chef/trusted_certs/wildcard_myorg_org.crt` is the file system location to which
+`knife ssl fetch` retrieved the public key.
+
+#### Testing WinRM SSL configuration
+
+The techniques below are useful for validating a WinRM listener's configuration -- all
+examples below assume there is a WinRM SSL listener configured on a remote Windows
+system `winserver.myoffice.com` on the default WinRM port of 5986 and this is
+the server being tested.
+
+##### PowerShell's `test-wsman` cmdlet
+If you have access to a workstation running
+the Windows 8 or Windows Server 2012 or later versions of the Windows
+operating systems, you can use the `test-wsman` command to validate the
+configuration of a listener on a remote system `winserver.myoffice.com`:
+
+1. On the Windows workstation client (not the system with the listener),
+    install the .pfx public key certificate for the listener using
+    certmgr.msc. This should be installed in the personal store under *"Trusted
+    Root Certification Authorities"*.
+2. Start PowerShell, and use it to run this command:
+    `test-wsman -ComputerName winserver.myoffice.com -UseSSL`
+
+If the command executes without error, the ssl configuration is correct.
+
+##### End to end SSL testing with `knife winrm`
+
+To validate that SSL is enabled for the listener without validating the
+server's certificate, the `--winrm-ssl-verify-mode` option of the `winrm`
+subcommand can be used:
+
+     knife winrm -m winserver.myoffice.com -t ssl --winrm-ssl-verify-mode verify_none ipconfig -x 'my_ad_domain\myuser' -P "$PASSWORDVAR"
+
+If this succeeds, then any failures to execute the command when correctly
+validating the server, i.e. when specifying the `-f` parameter, are due to
+certificate configuration issues, not other connectivity or authentication
+problems.
+
+##### The winrs tool
+
+The `winrs` tool is built into Windows, so if a Windows system is available,
+`winrs` may be used to troubleshoot. It takes parameters analogous to those of
+`knife winrm` and differences in success and failure between the two tools may
+indicate areas to investigate.
+
+Visit Microsoft's documentation for [`winrs`](https://technet.microsoft.com/en-us/library/hh875630.aspx) to learn more about the tool.
+
+### Troubleshooting WinRM authentication issues
+
+Authentication issues can be debugged by loosening the authentication
+requirements on the server and explicitly using
+`--winrm-authentication-protocol` option for `knife winrm` to attempt to
+connect. As an example, the following PowerShell commands on the server will allow basic authentication
+and unencrypted communication:
+
+    si wsman:\localhost\service\allowunencrypted $true
+    # Don't set the following if attempting domain authentication
+    si wsman:\localhost\service\auth\basic $true 
+
+From the client, `knife winrm` can be instructed to explicitly allow basic
+authentication when validating authentication using a non-domain (i.e. local)
+account:
+
+    # For testing a local account
+    knife winrm -m winserver.myoffice.com --winrm-authentication-protocol basic ipconfig -x 'localuser' -P "$PASSWORDVAR" -VV
+
+    # For testing a domain account
+    knife winrm -m winserver.myoffice.com --winrm-authentication-protocol negotiate ipconfig -x 'localuser' -P "$PASSWORDVAR" -VV
+
+If the listener is an SSL listener, the additional arguments `-t ssl
+--winrm-ssl-verify-mode verify_none` should be supplied to enable SSL
+communication and disable peer verification for testing. The specification of
+`-VV` enables additional detailed debug output that can provide clues to the
+root cause of any failures.
+
+If the command fails, there is either a connectivity issue or a problem with
+an incorrect or expired password or disabled account.
+
+If the command succeeds, try the following
+
+    si wsman:\localhost\service\allowunencrypted $false
+    
+Then retry the earlier `knife winrm` command. If it fails, this may indicate
+an issue with your operating system's ability to encrypt traffic, particularly
+when using the `plaintext` transport, i.e. when not using the `SSL` transport.
+In that case, the Windows platform supports encryption of plaintext traffic
+through native Windows authentication protocols, but such support is often incomplete on other platforms.    
+
+If the command succeeds, then there may be a more subtle issue with negotiate
+authentication. It may be necessary to explicitly specify a domain in the user
+name parameter (e.g. `mydomain\myuser` rather than just `user`) for instance,
+or a specified domain may actually be incorrect and something that should be omitted.
+
+### Platform WinRM authentication support
+
+`knife-windows` supports `Kerberos`, `Negotiate`, and `Basic` authentication
+for WinRM communication. However, some of these protocols
+may not work with `knife-windows` on non-Windows systems because
+`knife-windows` relies on operating system libraries such as GSSAPI to implement
+Windows authentication, and some versions of these libraries do not
+fully implement the protocols.
+
+The following table shows the authentication protocols that can be used with
+`knife-windows` depending on whether the knife workstation is a Windows
+system, the transport, and whether or not the target user is a domain user or
+local to the target Windows system.
+
+| Workstation OS / Account Scope | SSL                          | Plaintext                  |
+|--------------------------------|------------------------------|----------------------------|
+| Windows / Local                | Kerberos, Negotiate* , Basic | Kerberos, Negotiate, Basic |
+| Windows / Domain               | Kerberos, Negotiate          | Kerberos, Negotiate        |
+| Non-Windows / Local            | Kerberos, [Negotiate*](https://github.com/chef/knife-windows/issues/176) Basic | Kerberos, Basic |
+| Non-Windows / Domain           | Kerberos, Negotiate          | Kerberos                   |
+
+> \* There is a known defect in the `knife winrm` and `knife bootstrap windows
+> winrm` subcommands invoked on any OS  platform when authenticating with the Negotiate protocol over
+> the SSL transport. The defect is tracked by
+> [knife-windows issue #176](https://github.com/chef/knife-windows/issues/176): If the remote system is
+> domain-joined, local accounts may not be used to authenticate via Negotiate
+> over SSL -- only domain accounts will work. Local accounts will only
+> successfully authenticate if the system is not joined to a domain.
+>
+> This is generally not an issue for bootstrap scenarios, where the
+> system has yet to be joined to any domain, but can be a problem for remote
+> management cases after the system is domain joined. Workarounds include using
+> a domain account instead, or enabling Basic authentication on the remote
+> system (unencrypted communication **does not** need to be enabled to make
+> Basic authentication function over SSL).

data/Gemfile

@@ -4,8 +4,9 @@ source "https://rubygems.org"
 gemspec
 
 group :test do
+  gem "chef"
   gem "rspec", '~> 3.0'
   gem "ruby-wmi"
-  gem "chef"
+  gem "httpclient"
   gem 'rake'
 end

data/README.md

@@ -1,12 +1,14 @@
 Knife Windows Plugin
 ====================
+[![Build Status Master](https://travis-ci.org/chef/knife-windows.svg?branch=master)](https://travis-ci.org/chef/knife-windows)
+[![Build Status Master](https://ci.appveyor.com/api/projects/status/github/chef/knife-windows?branch=master&svg=true&passingText=master%20-%20Ok&pendingText=master%20-%20Pending&failingText=master%20-%20Failing)](https://ci.appveyor.com/project/Chef/knife-windows/branch/master)
 
 This plugin adds additional functionality to the Chef Knife CLI tool for
 configuring/interacting with nodes running Microsoft Windows. The subcommands
-should function on any system running Ruby 1.9.1+ but nodes being configured
+should function on any system running Ruby 1.9.3+ but nodes being configured
 via these subcommands require Windows Remote Management (WinRM) 1.0+.WinRM
 allows you to call native objects in Windows. This includes, but is not
-limited to, running batch scripts, powershell scripts and fetching WMI
+limited to, running PowerShell scripts, batch scripts, and fetching WMI
 variables. For more information on WinRM, please visit
 [Microsoft's WinRM site](http://msdn.microsoft.com/en-us/library/aa384426(v=VS.85).aspx).
 You will want to familiarize yourself with (certain key aspects) of WinRM
@@ -26,7 +28,7 @@ This plugin provides the following Knife subcommands. Specific command options c
 
 ### knife winrm
 
-The `winrm` subcommand allows you to invoke commands in parallel on a subset of the nodes in your infrastructure. The `winrm` subcommand uses the same syntax as the [search subcommand](http://wiki.opscode.com/display/chef/Search); you could could find the uptime of all your web servers using the command:
+The `winrm` subcommand allows you to invoke commands in parallel on a subset of the nodes in your infrastructure. The `winrm` subcommand uses the same syntax as the [search subcommand](https://docs.chef.io/knife_search.html); you could could find the uptime of all your web servers using the command:
 
     knife winrm "role:web" "net stats srv" -x Administrator -P 'super_secret_password'
 
@@ -40,16 +42,48 @@ Or force a chef run:
     ec2-50-xx-xx-124.compute-1.amazonaws.com [Fri, 04 Mar 2011 22:00:53 +0000] INFO: Running report handlers
     ec2-50-xx-xx-124.compute-1.amazonaws.com [Fri, 04 Mar 2011 22:00:53 +0000] INFO: Report handlers complete
 
-This subcommand operates in a manner similar to [knife ssh](http://wiki.opscode.com/display/chef/Knife#Knife-SSHSubcommand)...just leveraging the WinRM protocol for communication. It also include's `knife ssh`'s "[interactive session mode](http://wiki.opscode.com/display/chef/Knife#Knife-InteractiveMode)"
+This subcommand operates in a manner similar to [knife ssh](https://docs.chef.io/knife_ssh.html)...just leveraging the WinRM protocol for communication. It also include's `knife ssh`'s "[interactive session mode](https://docs.chef.io/knife_ssh.html#options)"
+
+### knife wsman test
+
+Connects to the remote WSMan/WinRM endpoint and verifies the remote node is listening.  This is the equivalent of running Test-Wsman from PowerShell.  Endpoints to test can be specified manually, or be driven by search and use many of the same connection options as knife winrm.
+To test a single node using the default WinRM port (5985)
+
+    knife wsman test 192.168.1.10 -m
+
+or to test a single node with SSL enabled on the default port (5986)
+
+    knife wsman test 192.168.1.10 -m --winrm-transport ssl
+
+or to test all windows nodes registered with your Chef Server organization
+
+    knife wsman test platform:windows
+
 
 ### knife bootstrap windows winrm
 
 Performs a Chef Bootstrap (via the WinRM protocol) on the target node. The goal of the bootstrap is to get Chef installed on the target system so it can run Chef Client with a Chef Server. The main assumption is a baseline OS installation exists. It is primarily intended for Chef Client systems that talk to a Chef server.
 
-This subcommand operates in a manner similar to [knife bootstrap](http://wiki.opscode.com/display/chef/Knife+Bootstrap)...just leveraging the WinRM protocol for communication. An initial run_list for the node can also be passed to the subcommand. Example usage:
+This subcommand operates in a manner similar to [knife bootstrap](https://docs.chef.io/knife_bootstrap.html)...just leveraging the WinRM protocol for communication. An initial run_list for the node can also be passed to the subcommand. Example usage:
 
     knife bootstrap windows winrm ec2-50-xx-xx-124.compute-1.amazonaws.com -r 'role[webserver],role[production]' -x Administrator -P 'super_secret_password'
 
+### Use SSL for WinRM communication
+
+By default, the `knife winrm` and `knife bootstrap windows winrm` subcommands use a plaintext transport,
+but they support an option `--winrm-transport` (or `-t`) with the argument
+`ssl` that allows the SSL to secure the WinRM payload. Here's an example:
+
+    knife winrm -t ssl "role:web" "net stats srv" -x Administrator -P 'super_secret_password'
+
+Use of SSL is strongly recommended, particularly when invoking `knife-windows` on non-Windows platforms, since
+without SSL there are limited options for ensuring the privacy of the
+plaintext transport. See the section on [Platform authentication
+support](#platform-winrm-authentication-support).
+
+SSL will become the default transport in future revisions of
+`knife-windows`.
+
 ### knife bootstrap windows ssh
 
 Performs a Chef Bootstrap (via the SSH protocol) on the target node. The goal of the bootstrap is to get Chef installed on the target system so it can run Chef Client with a Chef Server. The main assumption is a baseline OS installation exists. It is primarily intended for Chef Client systems that talk to a Chef server.
@@ -60,6 +94,39 @@ An initial run_list for the node can also be passed to the subcommand. Example u
 
     knife bootstrap windows ssh ec2-50-xx-xx-124.compute-1.amazonaws.com -r 'role[webserver],role[production]' -x Administrator -i ~/.ssh/id_rsa
 
+### knife windows cert generate
+
+Generates a certificate(x509) containing a public / private key pair for WinRM 'SSL' communication.
+The certificate will be generated in three different formats *.pfx, *.b64 and *.pem.
+The PKCS12(i.e *.pfx) contains both the public and private keys, usually used on the server. This will be added to WinRM Server's Certificate Store.
+The *.b64 is Base64 PKCS12 key pair. Contains both the public and private keys, for upload to the Cloud REST API. e.g. Azure.
+The *.pem is Base64 encoded public certificate only. Required by the client to connect to the server.
+This command also displays the thumbprint of the generated certificate.
+
+    knife windows cert generate --cert-passphrase "strong_passphrase" --domain "cloudapp.net" --output-file "~/server_cert.pfx"
+    # This command will generate certificates at user's home directory with names server_cert.b64, server_cert.pfx and server_cert.pem.
+
+### knife windows cert install
+
+This command only functions on Windows. It adds the specified certificate to its certificate store. This command must include a valid PKCS12(i.e *.pfx) certificate file path.
+
+    knife windows cert install "~/server_cert.pfx" --cert-passphrase "strong_passphrase"
+
+### knife windows listener create
+This command only functions on Windows. It creates the winrm listener for SSL communication(i.e HTTPS).
+This command can also install certificate which is specified using --cert-install option and use the installed certificate thumbprint to create winrm listener.
+--hostname option is optional. Default value for hostname is *.
+
+    knife windows listener create --cert-passphrase "strong_passphrase" --hostname "*.cloudapp.net" --cert-install "~/server_cert.pfx"
+
+The command also allows you to use existing certificates from local store to create winrm listener. Use --cert-thumbprint option to specify the certificate thumbprint.
+
+    knife windows listener create --cert-passphrase "strong_passphrase" --hostname "*.cloudapp.net" --cert-thumbprint "bf0fef0bb41be40ceb66a3b38813ca489fe99746"
+
+You can get the thumbprint for existing certificates in local store using the following PowerShell command:
+
+    Get-ChildItem -path cert:\LocalMachine\My
+
 ## BOOTSTRAP TEMPLATES:
 
 This gem provides the bootstrap template `windows-chef-client-msi`.
@@ -73,17 +140,18 @@ This bootstrap template does the following:
 * Writes a default config file for Chef (`C:\chef\client.rb`) using values from the `knife.rb`.
 * Creates a JSON attributes file containing the specified run list and run Chef.
 
-This is the default bootstrap template used by both the `windows bootstrap` subcommands.
+This is the default bootstrap template used by both of the `windows bootstrap` subcommands.
 
 ## REQUIREMENTS/SETUP:
 
 ### Ruby
 
-Ruby 1.9.1+ is needed.
+Ruby 1.9.3+ is needed.
 
 ### Chef Version
 
-Knife plugins require >= Chef 0.10. More details about Knife plugins can be [found on the Chef wiki](http://wiki.opscode.com/display/chef/Knife+Plugins).
+This knife plugins requires >= Chef 11.0.0. More details about Knife plugins can be
+[found in the Chef documentation](https://docs.chef.io/plugin_knife.html).
 
 ## Nodes
 
@@ -94,7 +162,8 @@ A server running WinRM must also be configured properly to allow outside connect
     winrm quickconfig -q
 
 The Chef and Ohai gem installations (that occur during bootstrap) take more
-memory than the default 150MB WinRM allocates per shell -- this can slow down
+memory than the default 150MB WinRM allocates per shell on older versions of
+Windows (prior to Windows Server 2012) -- this can slow down
 bootstrap. Optionally increase the memory limit to 300MB with the following command:
 
     winrm set winrm/config/winrs @{MaxMemoryPerShellMB="300"}
@@ -105,47 +174,109 @@ complete, optionally increase to 30 minutes if bootstrap terminates a command pr
     winrm set winrm/config @{MaxTimeoutms="1800000"}
 
 WinRM supports both the HTTP and HTTPS transports and the following
-authentication schemes: Kerberos, Digest, Certificate and Basic.  The details
+authentication schemes: Kerberos, Digest, Certificate and Basic. The details
 of these authentication transports are outside of the scope of this README but
 details can be found on the
 [WinRM configuration guide](http://msdn.microsoft.com/en-us/library/aa384372(v=vs.85).aspx).
-Currently, this plugin support Kerberos and Basic authentication schemes on
-all platform versions. The negotiate protocol which allows NTLM is fully
-supported when `knife windows bootstrap` is executed on a Windows system; if
-it is executed on a non-Windows system, certificate authentication or Kerberos
-should be used instead via the `:kerberos_service` and related options of the subcommands. 
-
-**NOTE**: In order to use NTLM / Negotiate to authenticate as the user
-  specified by the `--winrm-user` (`-x`) option, you must include the user's
-  Windows domain when specifying the user name using the format `domain\user`
-  where the backslash ('`\`') character separates the user from the domain. If
-  an account local to the node is being used to access, `.` may be used as the domain:
+
+## WinRM authentication
+
+The default authentication protocol for `knife-windows` subcommands that use
+WinRM is the Negotiate protocol. The following commands when executed on a
+Windows system show authentication for domain and local accounts respectively:
 
     knife bootstrap windows winrm web1.cloudapp.net -r 'server::web' -x 'proddomain\webuser' -P 'super_secret_password'
-    knife bootstrap windows winrm db1.cloudapp.net -r 'server::db' -x '.\localadmin' -P 'super_secret_password'
+    knife bootstrap windows winrm db1.cloudapp.net -r 'server::db' -x 'localadmin' -P 'super_secret_password'
+
+The commands above are using the default plaintext transport for WinRM --
+the default of Negotiate authentication may not be fully supported on
+non-Windows systems using the plaintext transport. To work around this, the
+remote system can be configured with an SSL WinRM listener instead of a
+plaintext listener. Then the above commands should be modified to use the SSL
+transport as follows using the `-t` (or `--winrm-transport`) option with the
+`ssl` argument:
+
+    knife bootstrap windows winrm -t ssl web1.cloudapp.net -r 'server::web' -x 'proddomain\webuser' -P 'super_secret_password'
+    knife bootstrap windows winrm -t ssl db1.cloudapp.net -r 'server::db' -x 'localadmin' -P 'super_secret_password'
 
-For development and testing purposes, unencrypted traffic with Basic authentication can make it easier to test connectivity:
+The commands using SSL above will work from any operating system, not just Windows.
+
+### Troubleshooting authentication
+
+For development and testing purposes, unencrypted traffic with Basic
+authentication can make it easier to test connectivity. The configuration for
+the remote system may be accomplished with the following commands:
 
     winrm set winrm/config/service @{AllowUnencrypted="true"}
     winrm set winrm/config/service/auth @{Basic="true"}
 
-## Troubleshooting
+To test connectivity via `knife-windows` from another system, the default
+authentication protocol of Negotiate must be overridden using the
+`--winrm-authentication-protocol` option with the desired protocol, in this
+case Basic:
+
+    knife winrm -m web1.cloudapp.net --winrm-authentication-protocol basic ipconfig -x 'localadmin' -P 'super_secret_password'
+
+Note that when using Basic authentication, domain accounts may not be used for
+authentication; an account local to the remote system must be used.
+
+### Platform WinRM authentication support
+
+`knife-windows` supports `Kerberos`, `Negotiate`, and `Basic` authentication
+for WinRM communication. However, some of these protocols
+may not work with `knife-windows` on non-Windows systems because
+`knife-windows` relies on operating system libraries such as GSSAPI to implement
+Windows authentication, and some versions of these libraries do not
+fully implement the protocols.
+
+The following table shows the authentication protocols that can be used with
+`knife-windows` depending on whether the knife workstation is a Windows
+system, the transport, and whether or not the target user is a domain user or
+local to the target Windows system.
+
+| Workstation OS / Account Scope | SSL                          | Plaintext                  |
+|--------------------------------|------------------------------|----------------------------|
+| Windows / Local                | Kerberos, Negotiate* , Basic | Kerberos, Negotiate, Basic |
+| Windows / Domain               | Kerberos, Negotiate          | Kerberos, Negotiate        |
+| Non-Windows / Local            | Kerberos, [Negotiate*](https://github.com/chef/knife-windows/issues/176) Basic | Kerberos, Basic |
+| Non-Windows / Domain           | Kerberos, Negotiate          | Kerberos                   |
+
+> \* There is a known defect in the `knife winrm` and `knife bootstrap windows
+> winrm` subcommands invoked on any OS  platform when authenticating with the Negotiate protocol over
+> the SSL transport. The defect is tracked by
+> [knife-windows issue #176](https://github.com/chef/knife-windows/issues/176): If the remote system is
+> domain-joined, local accounts may not be used to authenticate via Negotiate
+> over SSL -- only domain accounts will work. Local accounts will only
+> successfully authenticate if the system is not joined to a domain.
+>
+> This is generally not an issue for bootstrap scenarios, where the
+> system has yet to be joined to any domain, but can be a problem for remote
+> management cases after the system is domain joined. Workarounds include using
+> a domain account instead, or enabling Basic authentication on the remote
+> system (unencrypted communication **does not** need to be enabled to make
+> Basic authentication function over SSL).
+
+## General troubleshooting
 
 * When I run the winrm command I get: "Error: Invalid use of command line. Type "winrm -?" for help."
   You're running the winrm command from PowerShell and you need to put the key/value pair in single quotes. For example:
 
-    winrm set winrm/config/winrs '@{MaxMemoryPerShellMB="512"}'
+   `winrm set winrm/config/winrs '@{MaxMemoryPerShellMB="512"}'`
+
+* Windows 2008R2 and earlier versions require an extra configuration for MaxTimeoutms to avoid WinRM::WinRMHTTPTransportError: Bad HTTP response error while bootstrapping. It should be atleast 300000.
+
+    `winrm set winrm/config @{MaxTimeoutms="300000"}`
 
 ## CONTRIBUTING:
 
-Please file bugs against the KNIFE_WINDOWS project at https://github.com/opscode/knife-windows/issues.
+Please file bugs against the KNIFE_WINDOWS project at https://github.com/chef/knife-windows/issues.
 
-More information on the contribution process for Opscode projects can be found in the [Chef Contributions document](http://docs.opscode.com/community_contributions.html).
+More information on the contribution process for Chef projects can be found in the [Chef Contributions document](http://docs.chef.io/community_contributions.html).
 
 # LICENSE:
 
-Author:: Seth Chisamore (<schisamo@opscode.com>)
-Copyright:: Copyright (c) 2014 Opscode, Inc.
+Author:: Seth Chisamore (<schisamo@chef.io>)
+Copyright:: Copyright (c) 2015 Chef Software, Inc.
 License:: Apache License, Version 2.0
 
 Licensed under the Apache License, Version 2.0 (the "License");