sandbox

Documentation

Index

• Constants
• func InitNetwork(ctx context.Context)
• type Option
  • func Copy(src, dest string) Option
  • func EchoStdErr() Option
  • func EchoStdOut() Option
  • func EnablePacketLogging() Option
  • func EnableRawSockets() Option
  • func EnableStrace() Option
  • func Image(image string) Option
  • func LogStdErr() Option
  • func LogStdOut() Option
  • func Logger(logger *slog.Logger) Option
  • func NoPull() Option
  • func Offline() Option
  • func SetEnv(key, value string) Option
  • func Tag(tag string) Option
  • func Volume(src, dest string) Option
• type RunResult
  • func (r *RunResult) Log() (io.ReadCloser, error)
  • func (r *RunResult) Status() RunStatus
  • func (r *RunResult) Stderr() []byte
  • func (r *RunResult) Stdout() []byte
• type RunStatus
• type Sandbox
  • func New(options ...Option) Sandbox

Constants

const (
	// RunStatusUnknown is used when some other issue occurred that prevented
	// an attempt to run the command.
	RunStatusUnknown = iota

	// RunStatusSuccess is used to indicate that the command being executed
	// successfully.
	RunStatusSuccess

	// RunStatusFailure is used to indicate that the command exited with some
	// failure.
	RunStatusFailure

	// RunStatusTimeout is used to indicate that the command failed to complete
	// within the allowed timeout.
	RunStatusTimeout
)

const (
	// NetworkInterface is the name of a network interface that has access to
	// the sandbox network traffic.
	NetworkInterface = bridgeInterface
)

Functions

func InitNetwork

func InitNetwork(ctx context.Context)

InitNetwork initializes the host for sandbox network connections

It will ensure that the network interface exists, and any firewall rules are configured.

This function is idempotent and is safe to be called more than once.

This function must be called after logging is complete, and may exit if any of the commands fail.

Types

type Option

type Option interface {
	// contains filtered or unexported methods
}

func Copy

func Copy(src, dest string) Option

Copy copies a file from the host into the sandbox during initialisation

func EchoStdErr

func EchoStdErr() Option

EchoStdErr enables simple echoing of the sandboxed process stderr.

func EchoStdOut

func EchoStdOut() Option

EchoStdOut enables simple echoing of the sandboxed process stdout.

func EnablePacketLogging

func EnablePacketLogging() Option

EnablePacketLogging enables packet logging for the sandbox.

func EnableRawSockets

func EnableRawSockets() Option

EnableRawSockets allows use of raw sockets in the sandbox.

func EnableStrace

func EnableStrace() Option

EnableStrace enables strace functionality for the sandbox.

func Image

func Image(image string) Option

Image sets the image to be used by the sandbox. It is a required option.

func LogStdErr

func LogStdErr() Option

LogStdErr enables wrapping each line of stderr from the sandboxed process as log.Warn line in the main container.

func LogStdOut

func LogStdOut() Option

LogStdOut enables wrapping each line of stdout from sandboxed process as a log.Info line in the main container.

func Logger

func Logger(logger *slog.Logger) Option

func NoPull

func NoPull() Option

NoPull will disable the image for the sandbox from being pulled during Init.

func Offline

func Offline() Option

Offline disables network functionality for the sandbox.

func SetEnv

func SetEnv(key, value string) Option

func Tag

func Tag(tag string) Option

func Volume

func Volume(src, dest string) Option

Volume can be used to specify an additional volume map into the container. src is the path in the host that will be mapped to the dest path.

type RunResult

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

func (*RunResult) Log

func (r *RunResult) Log() (io.ReadCloser, error)

Log returns the log file recorded during a run.

This log will contain strace data.

func (*RunResult) Status

func (r *RunResult) Status() RunStatus

func (*RunResult) Stderr

func (r *RunResult) Stderr() []byte

func (*RunResult) Stdout

func (r *RunResult) Stdout() []byte

type RunStatus

type RunStatus uint8

type Sandbox

type Sandbox interface {
	// Init prepares the sandbox for run and copy commands. The sandbox is
	// only properly initialised if this function returns nil.
	Init(ctx context.Context) error

	// Run executes the supplied command and args in the sandbox.
	// Multiple calls to Run will reuse the same container state,
	// until Clean() is called.
	// The returned RunResult stores information about the execution.
	// If any error occurs, it is returned with a partial RunResult.
	Run(ctx context.Context, command string, args ...string) (*RunResult, error)

	// Clean cleans up the Sandbox. Once called, the Sandbox cannot be used again.
	Clean(ctx context.Context) error

	// CopyIntoSandbox copies a path in the host to one in the sandbox. The paths
	// may be files or directories. The copy fails if the host path does not exist.
	// See https://docs.podman.io/en/latest/markdown/podman-cp.1.html for details
	// on specifying paths.
	// The sandbox must be initialised using Init() before calling this function.
	CopyIntoSandbox(ctx context.Context, hostPath, sandboxPath string) error

	// CopyBackToHost copies a path in the sandbox to one in the host. The paths
	// may be files or directories. The copy fails if the sandbox path does not exist.
	// See https://docs.podman.io/en/latest/markdown/podman-cp.1.html for details
	// on specifying paths.
	// Caution: files coming out of the sandbox are untrusted and proper validation
	// should be performed on the file before use.
	// The sandbox must be initialised using Init() before calling this function.
	CopyBackToHost(ctx context.Context, hostPath, sandboxPath string) error
}

func New

func New(options ...Option) Sandbox