README
¶
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:
- The command options
WINRS_CONSOLEMODE_STDINandWINRS_SKIP_CMD_SHELLare exposed. These options are defined here. - 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
- func FormatPowerShellScriptCommandLine(script string) []string
- func FormatURL(useTLS bool, host string, port int) string
- func MustRunCommand(shell *Shell, command string, args []string, ...)
- func PowerShellSingleQuotedStringLiteral(v string) string
- func RunCommand(shell *Shell, command string, args []string, ...) error
- type Client
- type Command
- type FileTreeCopier
- type Shell
Constants ¶
const LogFieldCommandID = "cmd_id"
LogFieldCommandID is the name of the field containing the WinRM Command identifier.
const LogFieldShellID = "shell_id"
LogFieldShellID is the name of the field containing the WinRM Shell identifier.
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 ¶
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 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 ¶
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 ¶
CreateShell creates a cmd.exe Shell that can be used to run commands.
func (*Client) SendInputMax ¶
SendInputMax returns the maximum value number of bytes that can be sent in one request, given the current settings of c.
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 ¶
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) SendInput ¶
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.
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:
- 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.
- 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.
type Shell ¶
type Shell struct {
// contains filtered or unexported fields
}
Shell represents a WinRM remote shell. See (*Client).CreateShell.
func (*Shell) Client ¶
Client returns the *Client associated with this shell. All commands created from this Shell perform HTTP requests using this client.
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
Source Files
Directories