winrm

package module
v0.0.0-...-4e03a8f Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 6, 2023 License: Apache-2.0 Imports: 31 Imported by: 0

README

Go Reference

Introduction

This package enables clients written in Go to quickly upload files to a Windows server, based on the Windows Remote Management (WinRM) protocol.

The approach to copying files is the same as Ansible's, and directories can be recursively copied in parallel. These two features make this package hundreds of times faster than github.com/packer-community/winrmcp.

To realize the above, this package exposes WinRM functionality useful for passing data to PowerShell pipelines via stdin, that is not available in github.com/masterzen/winrm:

  1. The command options WINRS_CONSOLEMODE_STDIN and WINRS_SKIP_CMD_SHELL are exposed. These options are defined here.
  2. The stdin stream of a command can be closed.

It should be noted that github.com/masterzen/winrm has better documentation than this package, and will probably be better maintained. But we have a simpler way of supporting different authentication methods, by allowing users to set a *http.Client rather than inventing another abstraction.

How do I use this package?

See test/main.go for example code.

Documentation

Index

Constants

View Source
const LogFieldCommandID = "cmd_id"

LogFieldCommandID is the name of the field containing the WinRM Command identifier.

View Source
const LogFieldShellID = "shell_id"

LogFieldShellID is the name of the field containing the WinRM Shell identifier.

View Source
const MaxCommandLineSize = 8157

MaxCommandLineSize is the maximum size of a command with zero additional arguments, in bytes. The value is 8157, even though Microsoft documents a maximum command line size of 8191. The difference is the result of emperical testing (i.e. (*Client).StartCommand failing commands larger than 8157).

Variables

This section is empty.

Functions

func FormatPowerShellScriptCommandLine

func FormatPowerShellScriptCommandLine(script string) []string

FormatPowerShellScriptCommandLine returns the command and arguments to run the specified PowerShell script. The returned slice contains the following elements: PowerShell -NoProfile -NonInteractive -ExecutionPolicy Unrestricted -EncodedCommand <base64>

func FormatURL

func FormatURL(useTLS bool, host string, port int) string

FormatURL formats the HTTP URL of a WinRM endpoint.

func MustRunCommand

func MustRunCommand(shell *Shell, command string, args []string, winrsConsoleModeStdin, winrsSkipCmdShell bool)

MustRunCommand wraps a call to RunCommand. If RunCommand returns an error then MustRunCommand panics.

func PowerShellSingleQuotedStringLiteral

func PowerShellSingleQuotedStringLiteral(v string) string

PowerShellSingleQuotedStringLiteral returns a string that is a valid single quoted string literal in PowerShell, that evaluates to the value of v.

func RunCommand

func RunCommand(shell *Shell, command string, args []string, winrsConsoleModeStdin, winrsSkipCmdShell bool) error

RunCommand is a safe utility that runs a command on the supplied shell. It copies the remote command's stderr and stdout to os.Stderr and os.Stdout, respectively. It also waits for the command to complete and then signals the command in case it does not terminate by itself, to avoid leaking resources. Use (*Shell).StartCommand for a lower level alternative. winrsConsoleModeStdin and winrsSkipCmdShell correspond to the SOAP options WINRS_CONSOLEMODE_STDIN and WINRS_SKIP_CMD_SHELL, respectively, and are defined here: https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-wsmv/c793e333-c409-43c6-a2eb-6ae2489c7ef4

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client contains: 1. a HTTP client and context for HTTP requests made with that client. 2. default parameters for SOAP headers. 3. Credentials used to authenticate with WinRM.

func NewClient

func NewClient(

	ctx context.Context,
	useTLS bool,
	host string,
	port int,
	user, password string,
	httpClient *http.Client,
	maxEnvelopeSize *int) (*Client, error)

NewClient returns a *Client and guards against some erroneous inputs. To use basic authentication, set password to a non-empty string. If password is the empty string, then client will not pass a basic authentiction header to HTTP requests, but other authentication mechanisms can still be implemented in the supplied HTTP client.

func (*Client) CreateShell

func (c *Client) CreateShell() (*Shell, error)

CreateShell creates a cmd.exe Shell that can be used to run commands.

func (*Client) SendInputMax

func (c *Client) SendInputMax() int

SendInputMax returns the maximum value number of bytes that can be sent in one request, given the current settings of c.

func (*Client) URL

func (c *Client) URL() string

URL returns the WinRM URL associated with this client.

func (*Client) ZenParametersConst

func (c *Client) ZenParametersConst() *zenwinrm.Parameters

ZenParametersConst returns the *"github.com/masterzen/winrm".Parameters associated with this client. The value pointed to should not be modified. This function is usefull when creating requests manually to compute size bounds (e.g. "github.com/masterzen/winrm".NewExecuteCommandRequest).

type Command

type Command struct {

	// Stdout is an io.Reader representing the remote command's stdout.
	Stdout io.Reader
	// Stderr is an io.Reader representing the remote command's stderr.
	Stderr io.Reader
	// contains filtered or unexported fields
}

Command represents a command running in a remote cmd.exe terminal, and should not be used directly. See (*Shell).StartCommand.

func (*Command) ExitCode

func (c *Command) ExitCode() int

ExitCode returns the exit code of the remote command, or -1 if it has not yet terminated. Use Wait to wait for the remote command to terminate.

func (*Command) ID

func (c *Command) ID() string

ID returns the WinRM identifier of this command.

func (*Command) SendInput

func (c *Command) SendInput(p []byte, end bool) error

SendInput copies bytes to the remote command's stdin. Set end to true to close the command process' stdin. len(p) must be at most c.Shell().Client().SendInputMax(). It is up to caller to ensure len(p) is not too large.

func (*Command) Shell

func (c *Command) Shell() *Shell

Shell returns the Shell from which this command was started.

func (*Command) Signal

func (c *Command) Signal()

Signal sends a termination signal to the remote command.

func (*Command) Wait

func (c *Command) Wait() error

Wait slurps output from the remote command's stdout and stderr buffers, and waits for the remote command to terminate.

type FileTreeCopier

type FileTreeCopier struct {
	// contains filtered or unexported fields
}

FileTreeCopier stores the state needed to efficiently copy file trees over the Windows Remote Management (WinRM) protocol.

func NewFileTreeCopier

func NewFileTreeCopier(shells []*Shell, remoteRoot, localRoot string) (*FileTreeCopier, error)

NewFileTreeCopier creates a new file copier and guards against errorneous input. remoteRoot must be a cleaned absolute Windows file path that starts with a drive letter. Limitations:

  1. if localRoot is a regular file then the remote directory to which it would be copied must not contain an entry with a case-insensitive equal name.
  2. after cleaning localRoot (using filepath.Clean), it should not contain any characters outside the regular expression class [a-zA-Z0-9-_\. ^&], because escaping such file names is not supported.

func (*FileTreeCopier) Run

func (f *FileTreeCopier) Run() error

Run copies the file tree.

type Shell

type Shell struct {
	// contains filtered or unexported fields
}

Shell represents a WinRM remote shell. See (*Client).CreateShell.

func (*Shell) Client

func (s *Shell) Client() *Client

Client returns the *Client associated with this shell. All commands created from this Shell perform HTTP requests using this client.

func (*Shell) Close

func (s *Shell) Close() error

Close deletes the remote shell.

func (*Shell) ID

func (s *Shell) ID() string

ID returns the ID of this Shell

func (*Shell) StartCommand

func (s *Shell) StartCommand(command string, args []string, winrsConsoleModeStdin, winrsSkipCmdShell bool) (*Command, error)

StartCommand starts a command on the remote shell. winrsConsoleModeStdin and winrsSkipCmdShell correspond to the SOAP options WINRS_CONSOLEMODE_STDIN and WINRS_SKIP_CMD_SHELL, respectively, and are defined here: https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-wsmv/c793e333-c409-43c6-a2eb-6ae2489c7ef4

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL