package cmd

import "github.com/Microsoft/hcsshim/internal/cmd"

Package cmd provides functionality used to execute commands inside of containers or UVMs, and to connect an upstream client to those commands for handling in/out/err IO.

Index

Variables 

var ErrUnsafePath = errors.New("path is unsafe")

Functions

func CreateNamedPipeListener 

func CreateNamedPipeListener() (string, net.Listener, error)

CreateNamedPipeListener is a helper function to create and return a pipe listener and it's created path.

func CreatePipeAndListen 

func CreatePipeAndListen(f interface{}, in bool) (string, error)

CreatePipeAndListen is a helper function to create a pipe listener and accept connections. Returns the created pipe path on success.

If `in` is true, `f` should implement io.Reader If `in` is false, `f` should implement io.Writer

func ExecInShimHost 

func ExecInShimHost(ctx context.Context, req *CmdProcessRequest) (int, error)

ExecInShimHost is a helper function used to execute commands specified in `req` in the shim's hosting system.

func ExecInUvm 

func ExecInUvm(ctx context.Context, vm *uvm.UtilityVM, req *CmdProcessRequest) (int, error)

ExecInUvm is a helper function used to execute commands specified in `req` inside the given UVM.

Types

type Cmd 

type Cmd struct {
	// Host is the process host in which to launch the process.
	Host cow.ProcessHost

	// The OCI spec for the process.
	Spec *specs.Process

	// Standard IO streams to relay to/from the process.
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer

	// Log provides a logrus entry to use in logging IO copying status.
	Log *logrus.Entry

	// Context provides a context that terminates the process when it is done.
	Context context.Context

	// CopyAfterExitTimeout is the amount of time after process exit we allow the
	// stdout, stderr relays to continue before forcibly closing them if not
	// already completed. This is primarily a safety step against the HCS when
	// it fails to send a close on the stdout, stderr pipes when the process
	// exits and blocks the relay wait groups forever.
	CopyAfterExitTimeout time.Duration

	// Process is filled out after Start() returns.
	Process cow.Process

	// ExitState is filled out after Wait() (or Run() or Output()) completes.
	ExitState *ExitState
	// contains filtered or unexported fields
}

Cmd represents a command being prepared or run in a process host.

func Command 

func Command(host cow.ProcessHost, name string, arg ...string) *Cmd

Command makes a Cmd for a given command and arguments.

func CommandContext 

func CommandContext(ctx context.Context, host cow.ProcessHost, name string, arg ...string) *Cmd

CommandContext makes a Cmd for a given command and arguments. After it is launched, the process is killed when the context becomes done.

func (*Cmd) Output 

func (c *Cmd) Output() ([]byte, error)

Output runs a command via Run and collects its stdout into a buffer, which it returns.

func (*Cmd) Run 

func (c *Cmd) Run() error

Run is equivalent to Start followed by Wait.

func (*Cmd) Start 

func (c *Cmd) Start() error

Start starts a command. The caller must ensure that if Start succeeds, Wait is eventually called to clean up resources.

func (*Cmd) Wait 

func (c *Cmd) Wait() error

Wait waits for a command and its IO to complete and closes the underlying process. It can only be called once. It returns an ExitError if the command runs and returns a non-zero exit code.

type CmdProcessRequest 

type CmdProcessRequest struct {
	Args     []string
	Workdir  string
	Terminal bool
	Stdin    string
	Stdout   string
	Stderr   string
}

CmdProcessRequest stores information on command requests made through this package.

type ExitError 

type ExitError struct {
	*ExitState
}

ExitError is used when a process exits with a non-zero exit code.

func (*ExitError) Error 

func (err *ExitError) Error() string

type ExitState 

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

ExitState contains whether a process has exited and with which exit code.

func (*ExitState) ExitCode 

func (s *ExitState) ExitCode() int

ExitCode returns the exit code of the process, or -1 if the exit code is not known.

type UpstreamIO 

type UpstreamIO interface {
	// Close closes all open io.
	//
	// This call is idempotent and safe to call multiple times.
	Close(ctx context.Context)
	// CloseStdin closes just `Stdin()` if open.
	//
	// This call is idempotent and safe to call multiple times.
	CloseStdin(ctx context.Context)
	// Stdin returns the open `stdin` reader. If `stdin` was never opened this
	// will return `nil`.
	Stdin() io.Reader
	// StdinPath returns the original path used to open the `Stdin()` reader.
	StdinPath() string
	// Stdout returns the open `stdout` writer. If `stdout` was never opened
	// this will return `nil`.
	Stdout() io.Writer
	// StdoutPath returns the original path used to open the `Stdout()` writer.
	StdoutPath() string
	// Stderr returns the open `stderr` writer. If `stderr` was never opened
	// this will return `nil`.
	Stderr() io.Writer
	// StderrPath returns the original path used to open the `Stderr()` writer.
	StderrPath() string
	// Terminal returns `true` if the connection is emulating a terminal. If
	// `true` `Stderr()` will always return `nil` and `StderrPath()` will always
	// return `""`.
	Terminal() bool
}

UpstreamIO is an interface describing the IO to connect to above the shim. Depending on the callers settings there may be no opened IO.

func NewBinaryIO 

func NewBinaryIO(ctx context.Context, id string, uri *url.URL) (_ UpstreamIO, err error)

NewBinaryIO runs a custom binary process for pluggable shim logging driver.

Container's IO will be redirected to the logging driver via named pipes, which are passed as "CONTAINER_STDOUT", "CONTAINER_STDERR" environment variables. The logging driver MUST dial a wait pipe passed via "CONTAINER_WAIT" environment variable AND CLOSE it to indicate that it's ready to consume the IO. For customer's convenience container ID and namespace are also passed via "CONTAINER_ID" and "CONTAINER_NAMESPACE".

The path to the logging driver can be provided via a URL's host/path. Additional arguments can be passed to the logger via URL query params

func NewNpipeIO 

func NewNpipeIO(ctx context.Context, stdin, stdout, stderr string, terminal bool, retryTimeout time.Duration) (_ UpstreamIO, err error)

NewNpipeIO creates connected upstream io. It is the callers responsibility to validate that `if terminal == true`, `stderr == ""`. retryTimeout refers to the timeout used to try and reconnect to the server end of the named pipe if the connection is severed. A value of 0 for retryTimeout is treated as an infinite timeout.

func NewUpstreamIO 

func NewUpstreamIO(ctx context.Context, id, stdout, stderr, stdin string, terminal bool, ioRetryTimeout time.Duration) (UpstreamIO, error)

NewUpstreamIO returns an UpstreamIO instance. Currently we only support named pipes and binary logging driver for container IO. When using binary logger `stdout` and `stderr` are assumed to be the same and the value of `stderr` is completely ignored.

Source Files

cmd.go diag.go doc.go io.go io_binary.go io_npipe.go

Version
v0.12.3
Published
Apr 19, 2024
Platform
windows/amd64
Imports
28 packages
Last checked
7 hours ago –

Tools for package owners.