launcher

Documentation

Overview

Package launcher is responsible for implementing launchers, which can start a container, with configuration passed from the CLI layer.

Index

• func HidepidProc() bool
• func WithPrivilege(cond bool, desc string, fn func() error) error
• type ExecParams
  • func (ep ExecParams) ActionScriptArgs() (args []string, err error)
• type Launcher
• type MountSpecs
• type Namespaces
• type Option
  • func OptAllowSUID(b bool) Option
  • func OptAppName(a string) Option
  • func OptBoot(b bool) Option
  • func OptCacheDisabled(b bool) Option
  • func OptCaps(add, drop string) Option
  • func OptCdiDirs(op []string) Option
  • func OptCgroupsJSON(cj string) Option
  • func OptConfigFile(c string) Option
  • func OptContain(b bool) Option
  • func OptContainAll(b bool) Option
  • func OptContainLibs(cl []string) Option
  • func OptCwdPath(p string) Option
  • func OptDNS(d string) Option
  • func OptDevice(op []string) Option
  • func OptEnv(env map[string]string, envFiles []string, clean bool) Option
  • func OptFakeroot(b bool) Option
  • func OptHome(homeDir string, custom bool, disable bool) Option
  • func OptHostname(h string) Option
  • func OptKeepPrivs(b bool) Option
  • func OptKeyInfo(ki *cryptkey.KeyInfo) Option
  • func OptMounts(ms MountSpecs) Option
  • func OptNamespaces(n Namespaces) Option
  • func OptNetnsPath(n string) Option
  • func OptNetwork(network string, args []string) Option
  • func OptNoCompat(b bool) Option
  • func OptNoEval(b bool) Option
  • func OptNoInit(b bool) Option
  • func OptNoMount(nm []string) Option
  • func OptNoNvidia(b bool) Option
  • func OptNoPrivs(b bool) Option
  • func OptNoRocm(b bool) Option
  • func OptNoSetgroups(b bool) Option
  • func OptNoTmpSandbox(b bool) Option
  • func OptNoUmask(b bool) Option
  • func OptNvidia(nv bool, nvccli bool) Option
  • func OptOverlayPaths(op []string) Option
  • func OptProot(p string) Option
  • func OptRocm(b bool) Option
  • func OptSIFFuse(b bool) Option
  • func OptScratchDirs(sd []string) Option
  • func OptSecurity(s []string) Option
  • func OptShellPath(s string) Option
  • func OptTmpSandbox(b bool) Option
  • func OptTransportOptions(tOpts *ociimage.TransportOptions) Option
  • func OptWorkDir(wd string) Option
  • func OptWritable(b bool) Option
  • func OptWritableTmpfs(b bool) Option
• type Options

Functions

func HidepidProc

func HidepidProc() bool

HidepidProc checks if hidepid is set on the /proc mount point.

If this is set then an instance started in the with setuid workflow cannot be joined later or stopped correctly.

func WithPrivilege

func WithPrivilege(cond bool, desc string, fn func() error) error

WithPrivilege calls fn if cond is satisfied, and we are uid 0.

Types

type ExecParams

type ExecParams struct {
	// Image is the container image to execute, as a bare path, or <transport>:<path>.
	Image string
	// Action is one of exec/run/shell/start/test as specified on the CLI.
	Action string
	// Process is the command to execute as the container process, where applicable.
	Process string
	// Args are the arguments passed to the container process.
	Args []string
	// Instance is the name of an instance (optional).
	Instance string
}

ExecParams specifies the image and process for a launcher to Exec.

func (ExecParams) ActionScriptArgs

func (ep ExecParams) ActionScriptArgs() (args []string, err error)

ActionScriptArgs returns the args that will appropriately exec the action script in a singularity (non-oci) container, for a given ExecParams.

type Launcher

type Launcher interface {
	// Exec will execute the container image 'image', starting 'process', and
	// passing arguments 'args'. If instanceName is specified, the container
	// must be launched as a background instance, otherwise it must run
	// interactively, attached to the console.
	Exec(ctx context.Context, ep ExecParams) error
}

Launcher is responsible for configuring and launching a container image. It will execute a runtime, such as Singularity's native runtime (via the starter binary), or an external OCI runtime (e.g. runc).

type MountSpecs

type MountSpecs struct {
	// Binds holds <src>[:<dst>[:<opts>]] bind mount specifications from the CLI
	// --bind flag
	Binds []string
	// DataBinds holds <src sif>:<dst> data container bind specifications from
	// the CLI --data flag.
	DataBinds []string
	// Mounts holds Docker csv style mount specifications from the CLI --mount
	// flag.
	Mounts []string
	// FuseMounts holds <type>:<fuse command> <mountpoint> FUSE mount
	// specifications from the CLI --fusemount flag.
	FuseMounts []string
}

MountSpecs holds the various kinds of mount specifications that can be a applied to a container.

type Namespaces

type Namespaces struct {
	User bool
	UTS  bool
	PID  bool
	IPC  bool
	Net  bool
	// NoPID will force the PID namespace not to be used, even if set by default / other flags.
	NoPID bool
}

Namespaces holds flags for the optional (non-mount) namespaces that can be requested for a container launch.

type Option

type Option func(co *Options) error

func OptAllowSUID

func OptAllowSUID(b bool) Option

OptAllowSUID permits setuid executables inside a container started by the root user.

func OptAppName

func OptAppName(a string) Option

OptAppName sets a SCIF application name to run.

func OptBoot

func OptBoot(b bool) Option

OptBoot enables execution of /sbin/init on startup of an instance container.

func OptCacheDisabled

func OptCacheDisabled(b bool) Option

OptCacheDisabled indicates caching of images was disabled in the CLI.

func OptCaps

func OptCaps(add, drop string) Option

OptCaps sets capabilities to add and drop.

func OptCdiDirs

func OptCdiDirs(op []string) Option

OptCdiDirs sets CDI spec search-directories to apply.

func OptCgroupsJSON

func OptCgroupsJSON(cj string) Option

OptCgroupsJSON sets a Cgroups resource limit configuration to apply to the container.

func OptConfigFile

func OptConfigFile(c string) Option

OptConfigFile specifies an alternate singularity.conf that will be used by unprivileged installations only.

func OptContain

func OptContain(b bool) Option

OptContain starts the container with minimal /dev and empty home/tmp mounts.

func OptContainAll

func OptContainAll(b bool) Option

OptContainAll infers Contain, and adds PID, IPC namespaces, and CleanEnv.

func OptContainLibs

func OptContainLibs(cl []string) Option

OptContainLibs mounts specified libraries into the container .singularity.d/libs dir.

func OptCwdPath

func OptCwdPath(p string) Option

OptCwdPath specifies the initial working directory in the container.

func OptDNS

func OptDNS(d string) Option

OptDNS sets a DNS entry for the container resolv.conf.

func OptDevice

func OptDevice(op []string) Option

OptDevice sets CDI device mappings to apply.

func OptEnv

func OptEnv(env map[string]string, envFiles []string, clean bool) Option

OptEnv sets container environment

envFiles is a slice of paths to files container environment variables to set. env is a map of name=value env vars to set. clean removes host variables from the container environment.

func OptFakeroot

func OptFakeroot(b bool) Option

OptFakeroot enables the fake root mode, using user namespaces and subuid / subgid mapping.

func OptHome

func OptHome(homeDir string, custom bool, disable bool) Option

OptHome sets the home directory configuration for the container.

homeDir is the path or src:dst to bind mount. custom is a marker that this is user supplied, and must not be overridden. disable will disable the home mount entirely, ignoring other options.

func OptHostname

func OptHostname(h string) Option

OptHostname sets a hostname for the container (infers/requires UTS namespace).

func OptKeepPrivs

func OptKeepPrivs(b bool) Option

OptKeepPrivs keeps all privileges inside a container started by the root user.

func OptKeyInfo

func OptKeyInfo(ki *cryptkey.KeyInfo) Option

OptKeyInfo sets encryption key material to use when accessing an encrypted container image.

func OptMounts

func OptMounts(ms MountSpecs) Option

OptMounts sets user-requested mounts to propagate into the container.

func OptNamespaces

func OptNamespaces(n Namespaces) Option

OptNamespaces enable the individual kernel-support namespaces for the container.

func OptNetnsPath

func OptNetnsPath(n string) Option

OptJoinNetNamespace sets the network namespace to join, if permitted.

func OptNetwork

func OptNetwork(network string, args []string) Option

OptNetwork enables CNI networking.

network is the name of the CNI configuration to enable. args are arguments to pass to the CNI plugin.

func OptNoCompat

func OptNoCompat(b bool) Option

OptNoCompat disable OCI compatible mode, for singularity native mode default behaviors.

func OptNoEval

func OptNoEval(b bool) Option

OptNoEval disables shell evaluation of args and env vars.

func OptNoInit

func OptNoInit(b bool) Option

OptNoInit disables shim process when PID namespace is used.

func OptNoMount

func OptNoMount(nm []string) Option

OptNoMount disables the specified bind mounts.

func OptNoNvidia

func OptNoNvidia(b bool) Option

OptNoNvidia disables NVIDIA GPU support, even if enabled via singularity.conf.

func OptNoPrivs

func OptNoPrivs(b bool) Option

OptNoPrivs drops all privileges inside a container.

func OptNoRocm

func OptNoRocm(b bool) Option

OptNoRocm disables Rocm GPU support, even if enabled via singularity.conf.

func OptNoSetgroups

func OptNoSetgroups(b bool) Option

OptNoSetgroups disables calling setgroups for the fakeroot user namespace.

func OptNoTmpSandbox

func OptNoTmpSandbox(b bool) Option

OptNoTmpSandbox prohibits unpacking of images into temporary sandbox dirs.

func OptNoUmask

func OptNoUmask(b bool) Option

OptNoUmask disables propagation of the host umask into the container, using a default 0022.

func OptNvidia

func OptNvidia(nv bool, nvccli bool) Option

OptNvidia enables NVIDIA GPU support.

nvccli sets whether to use the nvidia-container-runtime (true), or legacy bind mounts (false).

func OptOverlayPaths

func OptOverlayPaths(op []string) Option

OptOverlayPaths sets overlay images and directories to apply to the container. Relative paths are resolved to absolute paths at this point.

func OptProot

func OptProot(p string) Option

OptProot mounts specified proot executable into the container .singularity.d/libs dir.

func OptRocm

func OptRocm(b bool) Option

OptRocm enable Rocm GPU support.

func OptSIFFuse

func OptSIFFuse(b bool) Option

OptSIFFuse enables FUSE mounting of a SIF image, if possible.

func OptScratchDirs

func OptScratchDirs(sd []string) Option

OptScratchDirs sets temporary host directories to create and bind into the container.

func OptSecurity

func OptSecurity(s []string) Option

OptSecurity supplies a list of security options (selinux, apparmor, seccomp) to apply.

func OptShellPath

func OptShellPath(s string) Option

OptShellPath specifies a custom shell executable to be launched in the container.

func OptTmpSandbox

func OptTmpSandbox(b bool) Option

TmpSandbox forces unpacking of images into temporary sandbox dirs when a kernel or FUSE mount would otherwise be used.

func OptTransportOptions

func OptTransportOptions(tOpts *ociimage.TransportOptions) Option

OptTransportOptions sets Docker/OCI image transport options (auth etc.)

func OptWorkDir

func OptWorkDir(wd string) Option

OptWorkDir sets the parent path for scratch directories, and contained home/tmp on the host.

func OptWritable

func OptWritable(b bool) Option

OptWritable sets the container image to be writable.

func OptWritableTmpfs

func OptWritableTmpfs(b bool) Option

OptWritableTmpFs applies an ephemeral writable overlay to the container.

type Options

type Options struct {
	// Writable marks the container image itself as writable.
	Writable bool
	// WritableTmpfs applies an ephemeral writable overlay to the container.
	WritableTmpfs bool
	// OverlayPaths holds paths to image or directory overlays to be applied.
	OverlayPaths []string
	// Scratchdir lists paths into the container to be mounted from a temporary location on the host.
	ScratchDirs []string
	// WorkDir is the parent path for scratch directories, and contained home/tmp on the host.
	WorkDir string

	// HomeDir is the home directory to mount into the container, or a src:dst pair.
	HomeDir string
	// CustomHome is a marker that HomeDir is user-supplied, and should not be
	// modified by the logic used for fakeroot execution.
	CustomHome bool
	// NoHome disables automatic mounting of the home directory into the container.
	NoHome bool

	// BindPaths lists paths to bind from host to container, which may be <src>:<dest> pairs.
	BindPaths []string
	// DataBinds lists data container binds, as <src sif>:<dest> pairs.
	DataBinds []string
	// FuseMount lists paths to be mounted into the container using a FUSE binary, and their options.
	FuseMount []string
	// Mounts lists paths to bind from host to container, from the docker compatible `--mount` flag (CSV format).
	Mounts []string
	// NoMount is a list of automatic / configured mounts to disable.
	NoMount []string

	// Nvidia enables NVIDIA GPU support.
	Nvidia bool
	// NcCCLI sets NVIDIA GPU support to use the nvidia-container-cli.
	NvCCLI bool
	// NoNvidia disables NVIDIA GPU support when set default in singularity.conf.
	NoNvidia bool
	// Rocm enables Rocm GPU support.
	Rocm bool
	// NoRocm disable Rocm GPU support when set default in singularity.conf.
	NoRocm bool

	// ContainLibs lists paths of libraries to bind mount into the container .singularity.d/libs dir.
	ContainLibs []string
	// Proot is the path to a proot binary to bind mount into the container .singularity.d/libs dir.
	Proot string

	// Env is a map of name=value env vars to set in the container.
	Env map[string]string
	// EnvFiles contains filenames to read container env vars from.
	EnvFiles []string
	// CleanEnv starts the container with a clean environment, excluding host env vars.
	CleanEnv bool
	// NoEval instructs Singularity not to shell evaluate args and env vars.
	NoEval bool

	// Namespaces is the list of optional Namespaces requested for the container.
	Namespaces Namespaces

	// NetnsPath is the path to a network namespace to join, rather than
	// creating one / applying a CNI config.
	NetnsPath string

	// Network is the name of an optional CNI networking configuration to apply.
	Network string
	// NetworkArgs are argument to pass to the CNI plugin that will configure networking when Network is set.
	NetworkArgs []string
	// Hostname is the hostname to set in the container (infers/requires UTS namespace).
	Hostname string
	// DNS is the comma separated list of DNS servers to be set in the container's resolv.conf.
	DNS string

	// AddCaps is the list of capabilities to Add to the container process.
	AddCaps string
	// DropCaps is the list of capabilities to drop from the container process.
	DropCaps string
	// AllowSUID permits setuid executables inside a container started by the root user.
	AllowSUID bool
	// KeepPrivs keeps all privileges inside a container started by the root user.
	KeepPrivs bool
	// NoPrivs drops all privileges inside a container.
	NoPrivs bool
	// SecurityOpts is the list of security options (selinux, apparmor, seccomp) to apply.
	SecurityOpts []string
	// NoUmask disables propagation of the host umask into the container, using a default 0022.
	NoUmask bool

	// CGroupsJSON is a JSON format cgroups resource limit specification to apply.
	CGroupsJSON string

	// ConfigFile is an alternate singularity.conf that will be used by unprivileged installations only.
	ConfigFile string

	// ShellPath is a custom shell executable to be launched in the container.
	ShellPath string
	// CwdPath is the initial working directory in the container.
	CwdPath string

	// Fakeroot enables the fake root mode, using user namespaces and subuid / subgid mapping.
	Fakeroot bool
	// NoSetgroups disables calling setgroups for the fakeroot user namespace.
	NoSetgroups bool
	// Boot enables execution of /sbin/init on startup of an instance container.
	Boot bool
	// NoInit disables shim process when PID namespace is used.
	NoInit bool
	// Contain starts the container with minimal /dev and empty home/tmp mounts.
	Contain bool
	// ContainAll infers Contain, and adds PID, IPC namespaces, and CleanEnv.
	ContainAll bool

	// AppName sets a SCIF application name to run.
	AppName string

	// KeyInfo holds encryption key information for accessing encrypted containers.
	KeyInfo *cryptkey.KeyInfo

	// SIFFUSE enables mounting SIF container images using FUSE.
	SIFFUSE bool
	// CacheDisabled indicates caching of images was disabled in the CLI, as in
	// userns flows we will need to delete the redundant temporary pulled image after
	// conversion to sandbox.
	CacheDisabled bool

	// TransportOptions holds Docker/OCI image transport configuration (auth etc.)
	// This will be used by a launcher handling OCI images directly.
	TransportOptions *ociimage.TransportOptions

	// TmpSandbox forces unpacking of images into temporary sandbox dirs when a
	// kernel or FUSE mount would otherwise be used.
	TmpSandbox bool

	// NoTmpSandbox prohibits unpacking of images into temporary sandbox dirs.
	NoTmpSandbox bool

	// Devices contains the list of device mappings (if any), e.g. CDI mappings.
	Devices []string

	// CdiDirs contains the list of directories in which CDI should look for device definition JSON files
	CdiDirs []string

	// NoCompat indicates the container should be run in non-OCI compatible
	// mode, i.e. with default mounts etc. as native mode. Effective for the OCI
	// launcher only.
	NoCompat bool
}

Options accumulates launch configuration from passed functional options. Note that the Options is modified heavily by logic during the Exec function call.