launcher

package
v4.1.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 8, 2024 License: BSD-3-Clause Imports: 10 Imported by: 0

Documentation

Overview

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

Index

Constants

This section is empty.

Variables

This section is empty.

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 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, envFile string, clean bool) Option

OptEnv sets container environment

envFile is a path to a file 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(binds []string, mounts []string, fuseMounts []string) Option

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

binds lists bind mount specifications in Singularity's <src>:<dst>[:<opts>] format. mounts lists bind mount specifications in Docker CSV processed format. fuseMounts list FUSE mounts in <type>:<fuse command> <mountpoint> format.

func OptNamespaces 

func OptNamespaces(n Namespaces) Option

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

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 added in v4.1.0 

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 added in v4.1.0 

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
	// 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
	// EnvFile is a file to read container env vars from.
	EnvFile 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

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

Source Files

View all Source files

Directories

Path Synopsis
Package native implements a Launcher that will configure and launch a container with Singularity's own (native) runtime.
 Package native implements a Launcher that will configure and launch a container with Singularity's own (native) runtime.
Package oci implements a Launcher that will configure and launch a container with an OCI runtime.
 Package oci implements a Launcher that will configure and launch a container with an OCI runtime.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.