singularity

Documentation

Index

• 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)
  • 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) PrepareConfig(starterConfig *starter.Config) error
  • func (e *EngineOperations) StartProcess(masterConnFd int) error

Types

type EngineOperations

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

EngineOperations is a Singularity runtime engine that implements engine.Operations. Basically, this is the core of `singularity run/exec/shell/instance` 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.

For better understanding of runtime flow in general refer to https://github.com/opencontainers/runtime-spec/blob/master/runtime.md#lifecycle. CleanupContainer is performing step 8/9 here.

func (*EngineOperations) Config

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

Config returns a pointer to a singularityConfig.EngineConfig literal as a config.EngineConfig interface. This pointer gets stored in the engine.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, 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.

Specifically in singularity engine, additional privileges are gained during network setup (see container.prepareNetworkSetup) in fakeroot flow. The rest of the 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).

func (*EngineOperations) InitConfig

func (e *EngineOperations) InitConfig(cfg *config.Common)

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.

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 write instance state/config files (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, singularity engine does not escalate privileges.

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 singularity configuration file parsing, handling user input, reading capabilities, and checking what namespaces are required.

No additional privileges can be gained as any of them are already dropped by the time PrepareConfig is called.

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).