Setting up WinRM for Chef

What is Windows Remote Management (WinRM)?

Windows Remote Management (known as WinRM) is a handy new remote management service for Windows Server 2003 R2, Windows Vista, and Windows Server 2008. WinRM is the “server” component of this remote management application and WinRS (Windows Remote Shell) is the “client” for WinRM, which runs on the remote computer attempting to remotely manage the WinRM server. However, I should note that BOTH computers must have WinRM installed and enabled on them for WinRS to work and retrieve information from the remote system.

WinRM is based on the Web Services for Management (WS-Management) standards. What that means is that WinRM uses the HTTP protocol (port 80) and SOAP requests to do its job. The good thing about that is that HTTP request are easy to send and receive through a firewall. And, consequently, the good and bad of that is that it will make it easier to remotely manage someone else’s Windows PC over the Internet OR it makes it easier for a malicious attacker to remotely attack Windows PCs over the Internet. The other benefit to WinRM using HTTP is that no additional ports would have to be opened up on server & client firewalls if HTTP inbound was already permitted.

Per Microsoft, WinRM is “Microsoft's new tool for opening up a standards-based API for systems management.” So, if you weren’t tool interested in learning about it prior to this, in my mind, the fact that it is “Microsoft’s new remote management standard” makes it well worth learning about.

You may already be familiar with the Windows Management Instrumentation (WMI) database. If not, that database contains all sorts of information about the hardware and software on that computer. Just about every Windows systems management application out there leverages the WMI database to perform whatever administrative tasks that needs to be performed on that PC. 

WinRM will use the WMI database to perform similar tasks that you or your systems management package may have already been performing using another programming interface like VBScript. The benefit to WinRM is that it uses port 80 (HTTP), as I mentioned above, and there is special code that even allows WinRM to share port 80 inbound with IIS, which may already be running on port 80.

WinRM supports multiple types of authentication to prevent just anyone from performing administrative tasks on your PC clients and servers. Of course, you should keep in mind that, just by enabling WinRM, you are opening up yet another avenue of attack on that system. However, like any other port that is opened, if authentication and encryption are put in place, you have taken all reasonable precautions.

Your systems management software vendor may already be planning on leveraging WinRM in the next release of their product so you may, unknowingly, use WinRM through another application. However, you can also use it yourself with a command line tool – winrm.cmd. With this CLI utility, you can quite easily, pull information out of the WMI database for whatever systems management function you want to perform.

As you can see below, WinRM has a command line interface with a lot of options. This help information for WinRM will show up even if WinRM isn’t “enabled” or “listening” on your system.

Figure 1: WinRM command line options

How do I enable and use WinRM?

If you are using Windows 2008 Server, WinRM is installed but not enabled by default. This is a good security precaution. The easiest way to determine if WinRM is already enabled and started on your machine is to go to a CMD prompt and run:

winrm enumerate winrm/config/listener

If you get no response them WinRM is not running. To configure WinRM to start automatically and allow for remote access, use the winrm quickconfig command like this:

C:\Users\Administrator> winrm quickconfig
WinRM is not set up to allow remote access to this machine for management.
The following changes must be made:
Create a WinRM listener on HTTP://* to accept WS-Man requests to any IP on this machine.
Make these changes [y/n]? y
WinRM has been updated for remote management.
Created a WinRM listener on HTTP://* to accept WS-Man requests to any IP on this machine.
C:\Users\Administrator>
Once I configured the quickconfig, I reran the enumeration command with these results:
C:\Users\Administrator> winrm e winrm/config/listener
Listener
Address = *
Transport = HTTP
Port = 80
Hostname
Enabled = true
URLPrefix = wsman
CertificateThumbprint
ListeningOn = 10.253.15.98, 127.0.0.1, ::1, fe80::5efe:10.253.15.98%11, fe80::9583:2148:e1ef:6444%10
C:\Users\Administrator>

From this, I know that WinRMis enabled.

By the way, if you want to disable WinRM at any point, you would use this command:

winrm delete winrm/config/listener?IPAdress=*+Transport=HTTP

To use WinRM, the hosts communicating with it will need to be members of the same domain as the WinRM host. If this is not the case, I recommend you consult the different WinRM security scenarios in the article “Remotely managing your Server Core using WinRM and WinRS”.

What is WinRS and how do I use it?

WinRS is the Windows Remote Shell. With WinRS, you can query remote Windows machines that are running WinRM. However, keep in mind that your machine also needs to be running WinRM to use WinRS.

As you can see from the diagram below, winrs is a full featured command line tool with a great deal of help information available for it.

Figure 2: WinRS command line options

One of the most common uses for WinRS is to execute commands on a remote system. Of course this is communicated using the HTTP protocol / port 80 (by default).

Below is an example where I executed WinRS on the localhost running WinRM. I ran two commands – “ver” and “dir C:”. Each command was returned with the appropriate information.

Figure 3: WinRS command demonstration

Further setup instructions can be found here. 

If you are running Knife from Windows and the remote Windows server is on the same domain, you should be able to connect.  Otherwise, you will need to configure the WinRM server to recognise the client machine as a trusted host.