samctr

Documentation

Overview

SPDX-License-Identifier: GPL-2.0

(c) 2025 Adam McCartney <adam@mur.at>

SPDX-License-Identifier: GPL-2.0

(c) 2025 Adam McCartney <adam@mur.at>

SPDX-License-Identifier: GPL-2.0

(c) 2025 Adam McCartney <adam@mur.at>

SPDX-License-Identifier: GPL-2.0

(c) 2025 Adam McCartney <adam@mur.at>

SPDX-License-Identifier: GPL-2.0

(c) 2025 Adam McCartney <adam@mur.at>

SPDX-License-Identifier: GPL-2.0

(c) 2025 Adam McCartney <adam@mur.at>

SPDX-License-Identifier: GPL-2.0

(c) 2025 Adam McCartney <adam@mur.at>

SPDX-License-Identifier: GPL-2.0

(c) 2025 Adam McCartney <adam@mur.at>

SPDX-License-Identifier: GPL-2.0

(c) 2025 Adam McCartney <adam@mur.at>

SPDX-License-Identifier: GPL-2.0

(c) 2025 Adam McCartney <adam@mur.at>

SPDX-License-Identifier: GPL-2.0

(c) 2025 Adam McCartney <adam@mur.at>

Copyright © 2025 Adam McCartney <adam@mur.at>

Index

• Constants
• Variables
• func ApptainerExecArg(rs *RuntimeState) string
• func ApptainerPullArgs(rs *RuntimeState) []string
• func ApptainerShellArg(rs *RuntimeState) string
• func CtrConvertSif(url, tmpDir string) (string, error)
• func Execute()
• func IoRunner(prg, arg string) (string, error)
• func LoadConfig(confPath string, root *cobra.Command) error
• func PrepareContainerPreRun(cmd *cobra.Command, args []string) error
• func PrepareFuseMounts(config *Config) ([]isamctr.FuseMount, error)
• func PullRunner(runtime *RuntimeState) error
• func RunSystemShell(runtime *RuntimeState, argFmt func(rs *RuntimeState) string) error
• func Runner(prg string, argFmt func(rs *RuntimeState) []string, runtime *RuntimeState) error
• type Config
• type RuntimeState
  • func CtrSetup(rs *RuntimeState, runner func(runtime *RuntimeState) error) (*RuntimeState, error)
  • func (rs *RuntimeState) SetApptainerBindPaths()

Constants

const DefaultHostInjections = "/opt/eessi"

Variables

var (
	FuseCmdRW             string
	HostInjections        string
	Image                 string
	ExtraBindPaths        string
	Nvidia                string
	ResumePath            string
	RootTmpDirPrefix      string
	ToStdout              bool
	WriteableRepositories []string
)

var AppConfig = &Config{}

var RootCmd = &cobra.Command{
	Use:   "samctr",
	Short: "A containerized build environment for CVMFS software repositories.",
	Long: `A containerized build environment for CVMFS software repositories.

This program wraps the Apptainer container runtime, exposing two
commands that facilitate running a container with a set of default
options. The core functionality of the commands is preserved - "shell"
launches an interactive shell session in the container, "exec" executes
a command in the container. The main focus of this program is to make it
easier to run these commands with the required confiration parameters
needed to mount a CVMFS repository in a writeable way using fusemounts.

Examples:
	samctr shell 
	samctr exec ls /etc`,
}

RootCmd represents the base command when called without any subcommands

Functions

func ApptainerExecArg

func ApptainerExecArg(rs *RuntimeState) string

func ApptainerPullArgs

func ApptainerPullArgs(rs *RuntimeState) []string

func ApptainerShellArg

func ApptainerShellArg(rs *RuntimeState) string

func CtrConvertSif

func CtrConvertSif(url, tmpDir string) (string, error)

func Execute

func Execute()

Execute adds all child commands to the root command and sets flags appropriately. This is called by main.main(). It only needs to happen once to the rootCmd.

func IoRunner

func IoRunner(prg, arg string) (string, error)

Run a system command and get the output

func LoadConfig

func LoadConfig(confPath string, root *cobra.Command) error

func PrepareContainerPreRun

func PrepareContainerPreRun(cmd *cobra.Command, args []string) error

Intended to be used as a cobra PreRunE for subcommands that require the container SIF to be available

func PrepareFuseMounts

func PrepareFuseMounts(config *Config) ([]isamctr.FuseMount, error)

basically, we need to create a list of fusemounts that appeared in the config file (these are the ro fusemounts)

  then we process the writeable-repository flag
  on finding writeable repository, we should:

a) copy the "ro" fusemount (it must exist, else err)
b) create a new FuseMount "fmNew" from the existing "fm":
        fmNew.Type = fm.Type
        fmNew.Cmd  = fuse-overlayfs | unionfs   (which ?)
        fmNew.Args = args formatted from the helper
        fmNew.CtrMountpoint = fm.CtrMountpoint
c) update the CtrMountpoint of fm
        fm.CtrMountpoint = "/cvmfs_ro"

func PullRunner

func PullRunner(runtime *RuntimeState) error

func RunSystemShell

func RunSystemShell(runtime *RuntimeState, argFmt func(rs *RuntimeState) string) error

Set up a call to "/bin/sh" note that any job will be automatically terminated after the values set by WithTimeout

func Runner

func Runner(prg string, argFmt func(rs *RuntimeState) []string, runtime *RuntimeState) error

Simple runner for non-interactive tasks Note the timeout -> (processes running under this context will be killed when the timeout completes)

Types

type Config

type Config struct {
	ApptainerVarHome     string `mapstructure:"apptainer_var_home"`
	ApptainerVarCachedir string `mapstructure:"apptainer_var_cachedir"`
	//ApptainerMode        string                   `mapstructure:"apptainer_mode"`
	//ApptainerPrg         string                   `mapstructure:"apptainer_prg"`
	//ApptainerPrgArgs     []string                 `mapstructure:"apptainer_prg_args"`
	RootTmpDirPrefix string   `mapstructure:"root_tmp_dir_prefix"`
	BindPaths        []string `mapstructure:"bind_paths"`
	Nvidia           string   `mapstructure:"nvidia"`
	//CtrAdditionalOptions []string                 `mapstructure:"ctr_additional_options"`
	HostInjections string              `mapstructure:"host_injections"`
	Image          string              `mapstructure:"image"`
	FuseMounts     []isamctr.FuseMount `mapstructure:"fusemounts"`
	FuseCmdRW      string              `mapstructure:"fuse_cmd_rw"`
	WriteableRepos []string            `mapstructure:"writeable_repos"`
}

type RuntimeState

type RuntimeState struct {
	// host-side storage details created by setup storage
	Storage *samctr.StorageState

	// container image
	Image string

	// path to converted sif file
	ContainerSif string

	// merged list of bind mounts (config + generated)
	AllBindMounts      []samctr.BindMount
	ApptainerBindPaths []string

	// Any additional options to pass to apptainer
	ApptainerCmdOpts []string

	Environ []string

	ArgsAfterDash []string
}

holds ephemeral state computed during Prepare and consumed by Run

var Runtime *RuntimeState

func CtrSetup

func CtrSetup(rs *RuntimeState, runner func(runtime *RuntimeState) error) (*RuntimeState, error)

func (*RuntimeState) SetApptainerBindPaths

func (rs *RuntimeState) SetApptainerBindPaths()

This should be called _once_ after all the setup is complete, before invoking the final "runner" call