engine

Documentation

Index

• func RegisterOperations(name string, operations Operations)
• func RegisterRPCMethods(name string, methods interface{})
• func ServeRPCRequests(e *Engine, conn net.Conn)
• type Engine
  • func Get(b []byte) (*Engine, error)
• type Operations

Functions

func RegisterOperations

func RegisterOperations(name string, operations Operations)

RegisterOperations registers engine operations for a runtime engine.

func RegisterRPCMethods

func RegisterRPCMethods(name string, methods interface{})

RegisterRPCMethods registers engine RPC methods served by RPC server.

func ServeRPCRequests

func ServeRPCRequests(e *Engine, conn net.Conn)

ServeRPCRequests serves runtime engine RPC requests with corresponding registered engine methods.

Types

type Engine

type Engine struct {
	Operations
	*config.Common
}

Engine is the combination of an Operations and a config.Common. The singularity startup routines (internal/app/starter/*) can spawn a container process from this type.

func Get

func Get(b []byte) (*Engine, error)

Get returns the engine described by the JSON []byte configuration.

type Operations

type Operations interface {
	// Config returns a zero value of the current EngineConfig, which
	// depends on the implementation, used to populate the Common struct.
	//
	// Since this method simply returns a zero value of the concrete
	// EngineConfig, it does not matter whether or not there are any elevated
	// privileges during this call.
	Config() config.EngineConfig
	// InitConfig stores the parsed config.Common inside the Operations
	// implementation.
	//
	// Since this method simply stores config.Common, it does not matter
	// whether or not there are any elevated privileges during this call.
	InitConfig(*config.Common)
	// PrepareConfig is called during stage1 to validate and prepare
	// container configuration.
	//
	// No additional privileges can be gained as any of them are already
	// dropped by the time PrepareConfig is called.
	PrepareConfig(*starter.Config) error
	// CreateContainer is called from master process to prepare container
	// environment, e.g. perform mount operations, setup network, etc.
	//
	// Additional privileges required for setup may be gained when running
	// in suid flow. However, when a user namespace is requested and it is not
	// a hybrid workflow (e.g. fakeroot), then there is no privileged saved uid
	// and thus no additional privileges can be gained.
	CreateContainer(context.Context, int, net.Conn) error
	// StartProcess is called during stage2 after RPC server finished
	// environment preparation. This is the container process itself.
	//
	// No additional privileges can be gained during this call (unless container
	// is executed as root intentionally) as starter will set uid/euid/suid
	// to the targetUID (PrepareConfig will set it by calling starter.Config.SetTargetUID).
	StartProcess(net.Conn) error
	// PostStartProcess is called from master after successful
	// execution of the container process.
	//
	// Additional privileges may be gained when running
	// in suid flow. However, when a user namespace is requested and it is not
	// a hybrid workflow (e.g. fakeroot), then there is no privileged saved uid
	// and thus no additional privileges can be gained.
	PostStartProcess(context.Context, int) error
	// MonitorContainer is called from master once the container has
	// been spawned. It will typically block until the container exists.
	//
	// Additional privileges may be gained when running
	// in suid flow. However, when a user namespace is requested and it is not
	// a hybrid workflow (e.g. fakeroot), then there is no privileged saved uid
	// and thus no additional privileges can be gained.
	MonitorContainer(int, chan os.Signal) (syscall.WaitStatus, error)
	// CleanupContainer is called from master after the MonitorContainer returns.
	// It is responsible for ensuring that the container has been properly torn down.
	//
	// Additional privileges may be gained when running
	// in suid flow. However, when a user namespace is requested and it is not
	// a hybrid workflow (e.g. fakeroot), then there is no privileged saved uid
	// and thus no additional privileges can be gained.
	CleanupContainer(context.Context, error, syscall.WaitStatus) error
	// PostStartHost is called after the container process has been executed. It
	// is run in the POST_START_HOST process forked from starter before
	// namespace setup etc. and will perform any cleanup in the host mount
	// namespace at time of CLI execution.
	//
	// No additional privileges can be gained during this call in the setuid
	// flow as privileges are dropped permanently after forking in starter.
	PostStartHost(context.Context) error
	// CleanupHost is called on container exit or startup failure to perform any
	// required cleanup in the host mount namespace at time of CLI execution.
	//
	// If container creation fails early, in STAGE 1, it will be called directly
	// from STAGE 1. Otherwise it is run in the CLEANUP_HOST PROCESS, triggered
	// by master, or the SIGKILL parent death signal.
	//
	// No additional privileges can be gained during this call in the setuid
	// flow, as privileges are dropped permanently in both STAGE1 and
	// CLEANUP_HOST after forking in starter.
	CleanupHost(context.Context) error
}

Operations is an interface describing necessary operations to launch a container process. Some of them may be called with elevated privilege or the potential to escalate privileges. Refer to an individual method documentation for a detailed description of the context in which it is called.