Command-line tool and library for Windows remote command execution in Go
Clone or download
masterzen Merge pull request #85 from maxbog/master
Add support for custom dialers.
Latest commit 58761a4 Jul 2, 2018
Permalink
Failed to load latest commit information.
development Set default codepage to UTF-8 Nov 20, 2015
scripts Update travis-ci test and coverage Jul 12, 2015
soap Remove LGPL dependencies Aug 12, 2017
.gitignore Remove LGPL dependencies Aug 12, 2017
.travis.yml Fix #77 - fix RunWithString race condition Feb 24, 2018
LICENSE WinRM: Windows remote command execution for Go Dec 30, 2013
Makefile Fix #49 split the library and the command-line tool May 23, 2016
README.md Add support for custom dialers. Jun 29, 2018
auth.go Add support for custom dialers. Jun 29, 2018
client.go Add support for custom dialers. Jun 29, 2018
client_test.go Add support for custom dialers. Jun 29, 2018
command.go Unnecessary var declarations, no need to certs and keys to be pointers, May 31, 2016
command_test.go Remove LGPL dependencies Aug 12, 2017
endpoint.go Fix formatting May 24, 2017
endpoint_test.go Unnecessary var declarations, no need to certs and keys to be pointers, May 31, 2016
error.go Unnecessary var declarations, no need to certs and keys to be pointers, May 31, 2016
error_test.go Unnecessary var declarations, no need to certs and keys to be pointers, May 31, 2016
fixture_test.go Remove LGPL dependencies Aug 12, 2017
http.go Add support for custom dialers. Jun 29, 2018
http_test.go Add support for custom dialers. Jun 29, 2018
ntlm.go Add support for custom dialers. Jun 29, 2018
ntlm_test.go Add support for custom dialers. Jun 29, 2018
parameters.go Add support for custom dialers. Jun 29, 2018
parameters_test.go Fix #49 split the library and the command-line tool May 23, 2016
powershell.go Fix #49 split the library and the command-line tool May 23, 2016
powershell_test.go Fix #49 split the library and the command-line tool May 23, 2016
request.go Remove LGPL dependencies Aug 12, 2017
request_test.go Remove LGPL dependencies Aug 12, 2017
response.go Remove LGPL dependencies Aug 12, 2017
response_test.go Remove LGPL dependencies Aug 12, 2017
shell.go Remove LGPL dependencies Aug 12, 2017
shell_test.go Fix formatting May 24, 2017

README.md

WinRM for Go

Note: if you're looking for the winrm command-line tool, this has been splitted from this project and is available at winrm-cli

This is a Go library 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.

Build Status Coverage Status

Contact

Getting Started

WinRM is available on Windows Server 2008 and up. This project natively supports basic authentication for local accounts, see the steps in the next section on how to prepare the remote Windows machine for this scenario. The authentication model is pluggable, see below for an example on using Negotiate/NTLM authentication (e.g. for connecting to vanilla Azure VMs).

Preparing the remote Windows machine for Basic authentication

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, 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

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

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

go version

Command-line usage

For command-line usage check the winrm-cli project

Library Usage

Warning the API might be subject to change.

For the fast version (this doesn't allow to send input to the command) and it's using HTTP as the transport:

package main

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

endpoint := winrm.NewEndpoint(host, 5986, false, false, nil, nil, nil, 0)
client, err := winrm.NewClient(endpoint, "Administrator", "secret")
if err != nil {
	panic(err)
}
client.Run("ipconfig /all", os.Stdout, os.Stderr)

or

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

endpoint := winrm.NewEndpoint("localhost", 5985, false, false, nil, nil, nil, 0)
client, err := winrm.NewClient(endpoint,"Administrator", "secret")
if err != nil {
	panic(err)
}

_, err := client.RunWithInput("ipconfig", os.Stdout, os.Stderr, os.Stdin)
if err != nil {
	panic(err)
}

By passing a TransportDecorator in the Parameters struct it is possible to use different Transports (e.g. NTLM)

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

endpoint := winrm.NewEndpoint("localhost", 5985, false, false, nil, nil, nil, 0)

params := DefaultParameters
params.TransportDecorator = func() Transporter { return &ClientNTLM{} }

client, err := NewClientWithParameters(endpoint, "test", "test", params)
if err != nil {
	panic(err)
}

_, err := client.RunWithInput("ipconfig", os.Stdout, os.Stderr, os.Stdin)
if err != nil {
	panic(err)
}

By passing a Dial in the Parameters struct it is possible to use different dialer (e.g. tunnel through SSH)

package main
     
 import (
    "github.com/masterzen/winrm"
    "golang.org/x/crypto/ssh"
    "os"
 )
 
 func main() {
 
    sshClient, err := ssh.Dial("tcp","localhost:22", &ssh.ClientConfig{
        User:"ubuntu",
        Auth: []ssh.AuthMethod{ssh.Password("ubuntu")},
        HostKeyCallback: ssh.InsecureIgnoreHostKey(),
    })
 
    endpoint := winrm.NewEndpoint("other-host", 5985, false, false, nil, nil, nil, 0)
 
    params := winrm.DefaultParameters
    params.Dial = sshClient.Dial
 
    client, err := winrm.NewClientWithParameters(endpoint, "test", "test", params)
    if err != nil {
        panic(err)
    }
 
    _, err = client.RunWithInput("ipconfig", os.Stdout, os.Stderr, os.Stdin)
    if err != nil {
        panic(err)
    }
 }

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

package main

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

stdin := bytes.NewBufferString("ipconfig /all")
endpoint := winrm.NewEndpoint("localhost", 5985, false, false,nil, nil, nil, 0)
client , err := winrm.NewClient(endpoint, "Administrator", "secret")
if err != nil {
	panic(err)
}
shell, err := client.CreateShell()
if err != nil {
  panic(err)
}
var cmd *winrm.Command
cmd, err = shell.Execute("cmd.exe")
if err != nil {
  panic(err)
}

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

cmd.Wait()
shell.Close()

For using HTTPS authentication with x 509 cert without checking the CA

	package main

	import (
		"github.com/masterzen/winrm"
		"os"
		"io/ioutil"
	)

	clientCert, err := ioutil.ReadFile("path/to/cert")
	if err != nil {
		panic(err)
	}

	clientKey, err := ioutil.ReadFile("path/to/key")
	if err != nil {
		panic(err)
	}

	winrm.DefaultParameters.TransportDecorator = func() winrm.Transporter {
		// winrm https module
		return &winrm.ClientAuthRequest{}
	}

	endpoint := winrm.NewEndpoint(host, 5986, false, false, clientCert, clientKey, nil, 0)
	client, err := winrm.NewClient(endpoint, "Administrator", ""
	if err != nil {
		panic(err)
	}
	client.Run("ipconfig /all", os.Stdout, os.Stderr)

Developing on WinRM

If you wish to work on winrm itself, you'll first need Go installed (version 1.5+ 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.

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.