WinRM for Go

This is a Go library (and command-line executable) to execute remote commands on Windows machines through the use of WinRM/WinRS.

Note: this library doesn't support domain users (it doesn't support GSSAPI nor Kerberos). It's primary target is to execute remote commands on EC2 windows machines.

Contact

• Bugs: https://github.com/masterzen/winrm/issues

Getting Started

Preparing the remote windows machine

WinRM is available on Windows Server 2008 and up. This project supports only basic authentication for local accounts (domain users are not supported). The remote windows system must be prepared for winrm:

For a PowerShell script to do what is described below in one go, check Richard Downer's blog

On the remote host, open a Command Prompt (not a PowerShell prompt!) using the Run as Administrator option and paste in the following lines:

	winrm quickconfig
	y
	winrm set winrm/config/service/Auth @{Basic="true"}
	winrm set winrm/config/service @{AllowUnencrypted="true"}
	winrm set winrm/config/winrs @{MaxMemoryPerShellMB="1024"}

N.B.: The Windows Firewall needs to be running to run this command. See Microsoft Knowledge Base article #2004640.

N.B.: Do not disable Negotiate authentication as the winrm command itself uses this for internal authentication, and you risk getting a system where winrm doesn't work anymore.

N.B.: The MaxMemoryPerShellMB option has no effects on some Windows 2008R2 systems because of a WinRM bug. Make sure to install the hotfix described Microsoft Knowledge Base article #2842230 if you need to run commands that uses more than 150MB of memory.

For more information on WinRM, please refer to the online documentation at Microsoft's DevCenter.

Building the winrm go and executable

You can build winrm from source:

git clone https://github.com/masterzen/winrm
cd winrm
make

This will generate a binary in the base directory called ./winrm.

Note: this winrm code doesn't depend anymore on Gokogiri which means it is now in pure Go.

Note: you need go 1.1+. Please check your installation with

go version

Command-line usage

Once built, you can run remote commands like this:

./winrm -hostname remote.domain.com -username "Administrator" -password "secret" "ipconfig /all" 

Library Usage

Warning the API might be subject to change.

For the fast version (this doesn't allow to send input to the command):

import "github.com/masterzen/winrm/winrm"

client := winrm.NewClient("localhost", "Administrator", "secret")
client.Run("ipconfig /all", os.Stdout, os.Stderr)

or

import "github.com/masterzen/winrm/winrm"

client := winrm.NewClient("localhost", "Administrator", "secret")
stdout, stderr, _ := client.RunWithString("ipconfig /all", "")
println(stdout)
println(stderr)

For a more complex example, it is possible to call the various functions directly:

import (
  "github.com/masterzen/winrm/winrm"
  "fmt"
  "bytes"
  "os"
)

stdin := bytes.NewBufferString("ipconfig /all")

client := winrm.NewClient("localhost", "Administrator", "secret")
shell, err := client.CreateShell()
if err != nil {
  fmt.Printf("Impossible to create shell %s\n", err)
  os.Exit(1)
}
var cmd *Command
cmd, err = shell.Execute("cmd.exe")
if err != nil {
  fmt.Printf("Impossible to create Command %s\n", err)
  os.Exit(1)
}

go io.Copy(cmd.Stdin, &stdin)
go io.Copy(os.Stdout, cmd.Stdout)
go io.Copy(os.Stderr, cmd.Stderr)

cmd.Wait()
shell.Close()

Developing on WinRM

If you wish to work on winrm itself, you'll first need Go installed (version 1.1+ is required). Make sure you have Go properly installed, including setting up your GOPATH.

For some additional dependencies, Go needs Mercurial and Bazaar to be installed. Winrm itself doesn't require these, but a dependency of a dependency does.

Next, clone this repository into $GOPATH/src/github.com/masterzen/winrm and then just type make. In a few moments, you'll have a working winrm executable:

$ make
...
$ bin/winrm
...

You can run tests by typing make test.

If you make any changes to the code, run make format in order to automatically format the code according to Go standards.

When new dependencies are added to winrm you can use make updatedeps to get the latest and subsequently use make to compile and generate the winrm binary.