oci

Documentation

Index

• Constants
• type EngineConfig
  • func NewConfig() *EngineConfig
  • func (e *EngineConfig) GetBundlePath() string
  • func (e *EngineConfig) GetLogFormat() string
  • func (e *EngineConfig) GetLogPath() string
  • func (e *EngineConfig) GetPidFile() string
  • func (e *EngineConfig) GetState() *ociruntime.State
  • func (e *EngineConfig) GetSystemdCgroups() bool
  • func (e *EngineConfig) SetBundlePath(path string)
  • func (e *EngineConfig) SetLogFormat(format string)
  • func (e *EngineConfig) SetLogPath(path string)
  • func (e *EngineConfig) SetPidFile(path string)
  • func (e *EngineConfig) SetState(state *ociruntime.State)
  • func (e *EngineConfig) SetSystemdCgroups(systemd bool)
• type EngineOperations
  • func (e *EngineOperations) CleanupContainer(ctx context.Context, fatal error, status syscall.WaitStatus) error
  • func (e *EngineOperations) Config() config.EngineConfig
  • func (e *EngineOperations) CreateContainer(ctx context.Context, pid int, rpcConn net.Conn) error
  • func (e *EngineOperations) InitConfig(cfg *config.Common, privStageOne bool)
  • func (e *EngineOperations) MonitorContainer(pid int, signals chan os.Signal) (syscall.WaitStatus, error)
  • func (e *EngineOperations) PostStartProcess(ctx context.Context, pid int) error
  • func (e *EngineOperations) PreStartProcess(ctx context.Context, pid int, masterConn net.Conn, fatalChan chan error) error
  • func (e *EngineOperations) PrepareConfig(starterConfig *starter.Config) error
  • func (e *EngineOperations) StartProcess(masterConnFd int) error

Constants

const Name = "oci"

Name of the engine.

Types

type EngineConfig

type EngineConfig struct {
	BundlePath     string           `json:"bundlePath"`
	LogPath        string           `json:"logPath"`
	LogFormat      string           `json:"logFormat"`
	PidFile        string           `json:"pidFile"`
	OciConfig      *oci.Config      `json:"ociConfig"`
	MasterPts      int              `json:"masterPts"`
	SlavePts       int              `json:"slavePts"`
	OutputStreams  [2]int           `json:"outputStreams"`
	ErrorStreams   [2]int           `json:"errorStreams"`
	InputStreams   [2]int           `json:"inputStreams"`
	SyncSocket     string           `json:"syncSocket"`
	EmptyProcess   bool             `json:"emptyProcess"`
	Exec           bool             `json:"exec"`
	SystemdCgroups bool             `json:"systemdCgroups"`
	Cgroups        *cgroups.Manager `json:"-"`

	sync.Mutex `json:"-"`
	State      ociruntime.State `json:"state"`
}

EngineConfig is the config for the OCI engine.

func NewConfig

func NewConfig() *EngineConfig

NewConfig returns an oci.EngineConfig.

func (*EngineConfig) GetBundlePath

func (e *EngineConfig) GetBundlePath() string

GetBundlePath returns the container bundle path.

func (*EngineConfig) GetLogFormat

func (e *EngineConfig) GetLogFormat() string

GetLogFormat returns the container log format.

func (*EngineConfig) GetLogPath

func (e *EngineConfig) GetLogPath() string

GetLogPath returns the container log path.

func (*EngineConfig) GetPidFile

func (e *EngineConfig) GetPidFile() string

GetPidFile gets the pid file path.

func (*EngineConfig) GetState

func (e *EngineConfig) GetState() *ociruntime.State

GetState returns the container state as defined by OCI state specification.

func (*EngineConfig) GetSystemdCgroups

func (e *EngineConfig) GetSystemdCgroups() bool

SetSystemdCgroups gets whether to manage cgroups with systemd.

func (*EngineConfig) SetBundlePath

func (e *EngineConfig) SetBundlePath(path string)

SetBundlePath sets the container bundle path.

func (*EngineConfig) SetLogFormat

func (e *EngineConfig) SetLogFormat(format string)

SetLogFormat sets the container log format.

func (*EngineConfig) SetLogPath

func (e *EngineConfig) SetLogPath(path string)

SetLogPath sets the container log path.

func (*EngineConfig) SetPidFile

func (e *EngineConfig) SetPidFile(path string)

SetPidFile sets the pid file path.

func (*EngineConfig) SetState

func (e *EngineConfig) SetState(state *ociruntime.State)

SetState sets the container state as defined by OCI state specification.

func (*EngineConfig) SetSystemdCgroups

func (e *EngineConfig) SetSystemdCgroups(systemd bool)

SetSystemdCgroups sets whether to manage cgroups with systemd.

type EngineOperations

type EngineOperations struct {
	CommonConfig *config.Common `json:"-"`
	EngineConfig *EngineConfig  `json:"engineConfig"`
}

EngineOperations is an Apptainer OCI runtime engine that implements engine.Operations. Basically, this is the core of `apptainer oci` commands.

func (*EngineOperations) CleanupContainer

func (e *EngineOperations) CleanupContainer(ctx context.Context, fatal error, status 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.

Specifically in oci engine, no additional privileges are gained here. However, most likely this still will be executed as root since `apptainer oci` command set requires privileged execution.

func (*EngineOperations) Config

func (e *EngineOperations) Config() config.EngineConfig

Config returns a pointer to EngineConfig literal as a config.EngineConfig interface. This pointer gets stored in the Engine.Common field.

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.

func (*EngineOperations) CreateContainer

func (e *EngineOperations) CreateContainer(ctx context.Context, pid int, rpcConn net.Conn) error

CreateContainer is called from master process to prepare container environment, e.g. perform mount operations, 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.

Specifically in oci engine, no additional privileges are gained. Container setup (e.g. mount operations) where privileges may be required is performed by calling RPC server methods (see internal/app/starter/rpc_linux.go for details).

However, most likely this still will be executed as root since `apptainer oci` command set requires privileged execution.

func (*EngineOperations) InitConfig

func (e *EngineOperations) InitConfig(cfg *config.Common, privStageOne bool)

InitConfig stores the parsed config.Common inside the engine.

Since this method simply stores config.Common, it does not matter whether or not there are any elevated privileges during this call.

func (*EngineOperations) MonitorContainer

func (e *EngineOperations) MonitorContainer(pid int, signals chan os.Signal) (syscall.WaitStatus, error)

MonitorContainer is called from master once the container has been spawned. It will 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.

Particularly here no additional privileges are gained as monitor does not need them for wait4 and kill syscalls. However, most likely this still will be executed as root since `apptainer oci` command set requires privileged execution.

func (*EngineOperations) PostStartProcess

func (e *EngineOperations) PostStartProcess(ctx context.Context, pid int) error

PostStartProcess is called from master after successful execution of the container process. It will execute OCI post start hooks (if any).

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.

Here, however, oci engine does not escalate privileges, which means OCI hooks will be executed on behalf of a user who spawned a container (but not the one who runs it as targetUID may be arbitrary).

Most likely this still will be executed as root since `apptainer oci` command set requires privileged execution.

func (*EngineOperations) PreStartProcess

func (e *EngineOperations) PreStartProcess(ctx context.Context, pid int, masterConn net.Conn, fatalChan chan error) error

PreStartProcess is called from master after before container startup.

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.

func (*EngineOperations) PrepareConfig

func (e *EngineOperations) PrepareConfig(starterConfig *starter.Config) error

PrepareConfig is called during stage1 to validate and prepare container configuration. It is responsible for reading capabilities, checking what namespaces are required, opening streams for attach and exec, etc.

No additional privileges can be gained as any of them are already dropped by the time PrepareConfig is called. However, most likely this still will be executed as root since `apptainer oci` command set requires privileged execution.

func (*EngineOperations) StartProcess

func (e *EngineOperations) StartProcess(masterConnFd int) 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).