cli

Documentation

Index

• Constants
• Variables
• func ExecuteSingularity()
• func TraverseParentsUses(cmd *cobra.Command) string

Constants

const (
	// LibraryProtocol holds the sylabs cloud library base URI
	// for more info refer to https://cloud.sylabs.io/library
	LibraryProtocol = "library"
	// ShubProtocol holds singularity hub base URI
	// for more info refer to https://singularity-hub.org/
	ShubProtocol = "shub"
	// HTTPProtocol holds the remote http base URI
	HTTPProtocol = "http"
	// HTTPSProtocol holds the remote https base URI
	HTTPSProtocol = "https"
)

Variables

var (
	AppName         string
	BindPaths       []string
	HomePath        string
	OverlayPath     []string
	ScratchPath     []string
	WorkdirPath     string
	PwdPath         string
	ShellPath       string
	Hostname        string
	Network         string
	NetworkArgs     []string
	DNS             string
	Security        []string
	CgroupsPath     string
	ContainLibsPath []string

	IsBoot          bool
	IsFakeroot      bool
	IsCleanEnv      bool
	IsContained     bool
	IsContainAll    bool
	IsWritable      bool
	IsWritableTmpfs bool
	Nvidia          bool
	NoHome          bool
	NoInit          bool
	NoNvidia        bool

	NetNamespace  bool
	UtsNamespace  bool
	UserNamespace bool
	PidNamespace  bool
	IpcNamespace  bool

	AllowSUID bool
	KeepPrivs bool
	NoPrivs   bool
	AddCaps   string
	DropCaps  string
)

actionflags.go contains flag variables for action-like commands to draw from

var (
	CapUser    string
	CapGroup   string
	CapDesc    bool
	CapListAll bool
)

contains flag variables for capability commands

var (
	// PullLibraryURI holds the base URI to a Sylabs library API instance
	PullLibraryURI string
	// PullImageName holds the name to be given to the pulled image
	PullImageName string
)

var BuildCmd = &cobra.Command{
	DisableFlagsInUseLine: true,
	Args:                  cobra.ExactArgs(2),

	Use:              docs.BuildUse,
	Short:            docs.BuildShort,
	Long:             docs.BuildLong,
	Example:          docs.BuildExample,
	PreRun:           preRun,
	Run:              run,
	TraverseChildren: true,
}

BuildCmd represents the build command

var CapabilityAddCmd = &cobra.Command{
	Args:                  cobra.MinimumNArgs(1),
	DisableFlagsInUseLine: true,
	Run: func(cmd *cobra.Command, args []string) {
		manageCap(args[0], capAdd)
	},

	Use:     docs.CapabilityAddUse,
	Short:   docs.CapabilityAddShort,
	Long:    docs.CapabilityAddLong,
	Example: docs.CapabilityAddExample,
}

CapabilityAddCmd singularity capability add

var CapabilityCmd = &cobra.Command{
	RunE: func(cmd *cobra.Command, args []string) error {
		return errors.New("Invalid command")
	},
	DisableFlagsInUseLine: true,

	Use:           docs.CapabilityUse,
	Short:         docs.CapabilityShort,
	Long:          docs.CapabilityLong,
	Example:       docs.CapabilityExample,
	SilenceErrors: true,
}

CapabilityCmd is the capability command

var CapabilityDropCmd = &cobra.Command{
	Args:                  cobra.MinimumNArgs(1),
	DisableFlagsInUseLine: true,
	Run: func(cmd *cobra.Command, args []string) {
		manageCap(args[0], capDrop)
	},

	Use:     docs.CapabilityDropUse,
	Short:   docs.CapabilityDropShort,
	Long:    docs.CapabilityDropLong,
	Example: docs.CapabilityDropExample,
}

CapabilityDropCmd singularity capability drop

var CapabilityListCmd = &cobra.Command{
	Args:                  cobra.MinimumNArgs(0),
	DisableFlagsInUseLine: true,
	Run: func(cmd *cobra.Command, args []string) {
		manageCap("", capList)
	},

	Use:     docs.CapabilityListUse,
	Short:   docs.CapabilityListShort,
	Long:    docs.CapabilityListLong,
	Example: docs.CapabilityListExample,
}

CapabilityListCmd singularity capability list

var ExecCmd = &cobra.Command{
	DisableFlagsInUseLine: true,
	TraverseChildren:      true,
	Args:                  cobra.MinimumNArgs(2),
	PreRun:                replaceURIWithImage,
	Run: func(cmd *cobra.Command, args []string) {
		a := append([]string{"/.singularity.d/actions/exec"}, args[1:]...)
		execStarter(cmd, args[0], a, "")
	},

	Use:     docs.ExecUse,
	Short:   docs.ExecShort,
	Long:    docs.ExecLong,
	Example: docs.ExecExamples,
}

ExecCmd represents the exec command

var InspectCmd = &cobra.Command{
	DisableFlagsInUseLine: true,
	Args:                  cobra.ExactArgs(1),

	Use:     docs.InspectUse,
	Short:   docs.InspectShort,
	Long:    docs.InspectLong,
	Example: docs.InspectExample,

	Run: func(cmd *cobra.Command, args []string) {

		if _, err := os.Stat(args[0]); err != nil {
			sylog.Fatalf("container not found: %s", err)
		}

		abspath, err := filepath.Abs(args[0])
		if err != nil {
			sylog.Fatalf("While determining absolute file path: %v", err)
		}
		name := filepath.Base(abspath)

		attributes := make(map[string]string)

		a := []string{"/bin/sh", "-c", ""}
		prefix := "@@@start"
		delimiter := "@@@end"

		if helpfile {
			sylog.Debugf("Inspection of helpfile selected.")

			a[2] += fmt.Sprintf(" echo '%v\nhelpfile';", prefix)
			a[2] += " cat .singularity.d/runscript.help;"
			a[2] += fmt.Sprintf(" echo '%v';", delimiter)
		}

		if deffile {
			sylog.Debugf("Inspection of deffile selected.")

			a[2] += fmt.Sprintf(" echo '%v\ndeffile';", prefix)
			a[2] += " cat .singularity.d/Singularity;"
			a[2] += fmt.Sprintf(" echo '%v';", delimiter)
		}

		if runscript {
			sylog.Debugf("Inspection of runscript selected.")

			a[2] += fmt.Sprintf(" echo '%v\nrunscript';", prefix)
			a[2] += " cat .singularity.d/runscript;"
			a[2] += fmt.Sprintf(" echo '%v';", delimiter)
		}

		if testfile {
			sylog.Debugf("Inspection of test selected.")

			a[2] += fmt.Sprintf(" echo '%v\ntest';", prefix)
			a[2] += " cat .singularity.d/test;"
			a[2] += fmt.Sprintf(" echo '%v';", delimiter)
		}

		if environment {
			sylog.Debugf("Inspection of environment selected.")

			a[2] += fmt.Sprintf(" echo '%v\nenvironment';", prefix)
			a[2] += " find .singularity.d/env -name 9*-environment.sh -exec echo -n == \\; -exec basename -z {} \\; -exec echo == \\; -exec cat {} \\; -exec echo \\;;"
			a[2] += fmt.Sprintf(" echo '%v';", delimiter)
		}

		if labels || len(a[2]) == 0 {
			sylog.Debugf("Inspection of labels as default.")

			a[2] += fmt.Sprintf(" echo '%v\nlabels';", prefix)
			a[2] += " cat .singularity.d/labels.json;"
			a[2] += fmt.Sprintf(" echo '%v';", delimiter)
		}

		fileContents, err := getFileContent(abspath, name, a)
		if err != nil {
			sylog.Fatalf("While getting helpfile: %v", err)
		}

		contentSlice := strings.Split(fileContents, delimiter)
		for _, s := range contentSlice {
			s = strings.TrimSpace(s)
			if strings.HasPrefix(s, prefix) {
				split := strings.SplitN(s, "\n", 3)
				if len(split) == 3 {
					attributes[split[1]] = split[2]
				} else if len(split) == 2 {
					sylog.Warningf("%v metadata was not found.", split[1])
				}
			}
		}

		if jsonfmt {
			// store this in a struct, then marshal the struct to json
			type result struct {
				Data map[string]string `json:"attributes"`
				T    string            `json:"type"`
			}

			d := result{
				Data: attributes,
				T:    "container",
			}

			b, err := json.MarshalIndent(d, "", "\t")
			if err != nil {
				log.Fatal(err)
			}

			fmt.Println(string(b))
		} else {

			for _, value := range attributes {
				fmt.Println("\n" + value + "\n")
			}
		}

	},
	TraverseChildren: true,
}

InspectCmd represents the build command

var InstanceCmd = &cobra.Command{
	RunE: func(cmd *cobra.Command, args []string) error {
		return errors.New("Invalid command")
	},
	DisableFlagsInUseLine: true,

	Use:           docs.InstanceUse,
	Short:         docs.InstanceShort,
	Long:          docs.InstanceLong,
	Example:       docs.InstanceExample,
	SilenceErrors: true,
}

InstanceCmd singularity instance

var InstanceListCmd = &cobra.Command{
	Args: cobra.RangeArgs(0, 1),
	Run: func(cmd *cobra.Command, args []string) {
		listInstance()
	},
	DisableFlagsInUseLine: true,

	Use:     docs.InstanceListUse,
	Short:   docs.InstanceListShort,
	Long:    docs.InstanceListLong,
	Example: docs.InstanceListExample,
}

InstanceListCmd singularity instance list

var InstanceStartCmd = &cobra.Command{
	Args:                  cobra.MinimumNArgs(2),
	PreRun:                replaceURIWithImage,
	DisableFlagsInUseLine: true,
	Run: func(cmd *cobra.Command, args []string) {
		a := []string{"/.singularity.d/actions/start"}
		execStarter(cmd, args[0], a, args[1])
	},

	Use:     docs.InstanceStartUse,
	Short:   docs.InstanceStartShort,
	Long:    docs.InstanceStartLong,
	Example: docs.InstanceStartExample,
}

InstanceStartCmd singularity instance start

var InstanceStopCmd = &cobra.Command{
	DisableFlagsInUseLine: true,
	RunE: func(cmd *cobra.Command, args []string) error {
		if len(args) > 0 && !stopAll {
			stopInstance(args[0])
			return nil
		} else if stopAll {
			stopInstance("*")
			return nil
		} else {
			return errors.New("Invalid command")
		}
	},

	Use:     docs.InstanceStopUse,
	Short:   docs.InstanceStopShort,
	Long:    docs.InstanceStopLong,
	Example: docs.InstanceStopExample,
}

InstanceStopCmd singularity instance stop

var KeysCmd = &cobra.Command{
	RunE: func(cmd *cobra.Command, args []string) error {
		return errors.New("Invalid command")
	},
	DisableFlagsInUseLine: true,

	Use:           docs.KeysUse,
	Short:         docs.KeysShort,
	Long:          docs.KeysLong,
	Example:       docs.KeysExample,
	SilenceErrors: true,
}

KeysCmd is the 'keys' command that allows management of key stores

var KeysListCmd = &cobra.Command{
	Args:                  cobra.ExactArgs(0),
	DisableFlagsInUseLine: true,
	Run: func(cmd *cobra.Command, args []string) {
		if err := doKeysListCmd(secret); err != nil {
			os.Exit(2)
		}
	},

	Use:     docs.KeysListUse,
	Short:   docs.KeysListShort,
	Long:    docs.KeysListLong,
	Example: docs.KeysListExample,
}

KeysListCmd is `singularity keys list' and lists local store OpenPGP keys

var KeysNewPairCmd = &cobra.Command{
	Args:                  cobra.ExactArgs(0),
	DisableFlagsInUseLine: true,
	Run: func(cmd *cobra.Command, args []string) {
		if _, err := sypgp.GenKeyPair(); err != nil {
			sylog.Fatalf("creating newpair failed: %v", err)
		}
	},

	Use:     docs.KeysNewPairUse,
	Short:   docs.KeysNewPairShort,
	Long:    docs.KeysNewPairLong,
	Example: docs.KeysNewPairExample,
}

KeysNewPairCmd is `singularity keys newpair' and generate a new OpenPGP key pair

var KeysPullCmd = &cobra.Command{
	Args:                  cobra.ExactArgs(1),
	DisableFlagsInUseLine: true,
	PreRun:                sylabsToken,
	Run: func(cmd *cobra.Command, args []string) {
		if err := doKeysPullCmd(args[0], keyServerURL); err != nil {
			sylog.Errorf("pull failed: %s", err)
			os.Exit(2)
		}
	},

	Use:     docs.KeysPullUse,
	Short:   docs.KeysPullShort,
	Long:    docs.KeysPullLong,
	Example: docs.KeysPullExample,
}

KeysPullCmd is `singularity keys pull' and fetches public keys from a key server

var KeysPushCmd = &cobra.Command{
	Args:                  cobra.ExactArgs(1),
	DisableFlagsInUseLine: true,
	PreRun:                sylabsToken,
	Run: func(cmd *cobra.Command, args []string) {
		if err := doKeysPushCmd(args[0], keyServerURL); err != nil {
			sylog.Errorf("push failed: %s", err)
			os.Exit(2)
		}
	},

	Use:     docs.KeysPushUse,
	Short:   docs.KeysPushShort,
	Long:    docs.KeysPushLong,
	Example: docs.KeysPushExample,
}

KeysPushCmd is `singularity keys list' and lists local store OpenPGP keys

var KeysSearchCmd = &cobra.Command{
	Args:                  cobra.ExactArgs(1),
	DisableFlagsInUseLine: true,
	PreRun:                sylabsToken,
	Run: func(cmd *cobra.Command, args []string) {
		if err := doKeysSearchCmd(args[0], keyServerURL); err != nil {
			sylog.Errorf("search failed: %s", err)
			os.Exit(2)
		}
	},

	Use:     docs.KeysSearchUse,
	Short:   docs.KeysSearchShort,
	Long:    docs.KeysSearchLong,
	Example: docs.KeysSearchExample,
}

KeysSearchCmd is `singularity keys search' and look for public keys from a key server

var PullCmd = &cobra.Command{
	DisableFlagsInUseLine: true,
	Args:                  cobra.RangeArgs(1, 2),
	PreRun:                sylabsToken,
	Run:                   pullRun,
	Use:                   docs.PullUse,
	Short:                 docs.PullShort,
	Long:                  docs.PullLong,
	Example:               docs.PullExample,
}

PullCmd singularity pull

var PushCmd = &cobra.Command{
	DisableFlagsInUseLine: true,
	Args:                  cobra.ExactArgs(2),
	PreRun:                sylabsToken,
	Run: func(cmd *cobra.Command, args []string) {

		if authToken != "" {
			err := client.UploadImage(args[0], args[1], PushLibraryURI, authToken, "No Description")
			if err != nil {
				sylog.Fatalf("%v\n", err)
			}
		} else {
			sylog.Fatalf("Couldn't push image to library: %v", authWarning)
		}
	},

	Use:     docs.PushUse,
	Short:   docs.PushShort,
	Long:    docs.PushLong,
	Example: docs.PushExample,
}

PushCmd singularity push

var (
	// PushLibraryURI holds the base URI to a Sylabs library API instance
	PushLibraryURI string
)

var RunCmd = &cobra.Command{
	DisableFlagsInUseLine: true,
	TraverseChildren:      true,
	Args:                  cobra.MinimumNArgs(1),
	PreRun:                replaceURIWithImage,
	Run: func(cmd *cobra.Command, args []string) {
		a := append([]string{"/.singularity.d/actions/run"}, args[1:]...)
		execStarter(cmd, args[0], a, "")
	},

	Use:     docs.RunUse,
	Short:   docs.RunShort,
	Long:    docs.RunLong,
	Example: docs.RunExamples,
}

RunCmd represents the run command

var RunHelpCmd = &cobra.Command{
	DisableFlagsInUseLine: true,
	PreRun:                sylabsToken,
	Args:                  cobra.ExactArgs(1),
	Run: func(cmd *cobra.Command, args []string) {

		if _, err := os.Stat(args[0]); err != nil {
			sylog.Fatalf("container not found: %s", err)
		}

		abspath, err := filepath.Abs(args[0])
		name := filepath.Base(abspath)
		a := []string{"/bin/cat", "/.singularity.d/runscript.help"}
		starter := buildcfg.LIBEXECDIR + "/singularity/bin/starter-suid"
		procname := "Singularity help"
		Env := []string{sylog.GetEnvVar(), "SRUNTIME=singularity"}

		engineConfig := singularity.NewConfig()
		ociConfig := &oci.Config{}
		generator := generate.Generator{Config: &ociConfig.Spec}
		engineConfig.OciConfig = ociConfig

		generator.SetProcessArgs(a)
		engineConfig.SetImage(abspath)

		cfg := &config.Common{
			EngineName:   singularity.Name,
			ContainerID:  name,
			EngineConfig: engineConfig,
		}

		configData, err := json.Marshal(cfg)
		if err != nil {
			sylog.Fatalf("CLI Failed to marshal CommonEngineConfig: %s\n", err)
		}

		if err := exec.Pipe(starter, []string{procname}, Env, configData); err != nil {
			sylog.Fatalf("%s", err)
		}
	},

	Use:     docs.RunHelpUse,
	Short:   docs.RunHelpShort,
	Long:    docs.RunHelpLong,
	Example: docs.RunHelpExample,
}

RunHelpCmd singularity run-help <image>

var SearchCmd = &cobra.Command{
	DisableFlagsInUseLine: true,
	Args:                  cobra.ExactArgs(1),
	PreRun:                sylabsToken,
	Run: func(cmd *cobra.Command, args []string) {
		if err := client.SearchLibrary(args[0], SearchLibraryURI, authToken); err != nil {
			sylog.Fatalf("Couldn't search library: %v", err)
		}

	},

	Use:     docs.SearchUse,
	Short:   docs.SearchShort,
	Long:    docs.SearchLong,
	Example: docs.SearchExample,
}

SearchCmd singularity search

var (
	// SearchLibraryURI holds the base URI to a Sylabs library API instance
	SearchLibraryURI string
)

var ShellCmd = &cobra.Command{
	DisableFlagsInUseLine: true,
	TraverseChildren:      true,
	Args:                  cobra.MinimumNArgs(1),
	PreRun:                replaceURIWithImage,
	Run: func(cmd *cobra.Command, args []string) {
		a := []string{"/.singularity.d/actions/shell"}
		execStarter(cmd, args[0], a, "")
	},

	Use:     docs.ShellUse,
	Short:   docs.ShellShort,
	Long:    docs.ShellLong,
	Example: docs.ShellExamples,
}

ShellCmd represents the shell command

var SignCmd = &cobra.Command{
	DisableFlagsInUseLine: true,
	Args:                  cobra.ExactArgs(1),
	PreRun:                sylabsToken,

	Run: func(cmd *cobra.Command, args []string) {

		fmt.Printf("Signing image: %s\n", args[0])
		if err := doSignCmd(args[0], keyServerURL); err != nil {
			sylog.Errorf("signing container failed: %s", err)
			os.Exit(2)
		}
		fmt.Printf("Signature created and applied to %v\n", args[0])
	},

	Use:     docs.SignUse,
	Short:   docs.SignShort,
	Long:    docs.SignLong,
	Example: docs.SignExample,
}

SignCmd singularity sign

var SingularityCmd = &cobra.Command{
	TraverseChildren:      true,
	DisableFlagsInUseLine: true,
	PersistentPreRun:      persistentPreRun,
	RunE: func(cmd *cobra.Command, args []string) error {
		return errors.New("Invalid command")
	},

	Use:           docs.SingularityUse,
	Version:       buildcfg.PACKAGE_VERSION,
	Short:         docs.SingularityShort,
	Long:          docs.SingularityLong,
	Example:       docs.SingularityExample,
	SilenceErrors: true,
}

SingularityCmd is the base command when called without any subcommands

var TestCmd = &cobra.Command{
	DisableFlagsInUseLine: true,
	TraverseChildren:      true,
	Args:                  cobra.MinimumNArgs(1),
	PreRun:                replaceURIWithImage,
	Run: func(cmd *cobra.Command, args []string) {
		a := append([]string{"/.singularity.d/test"}, args[1:]...)
		execStarter(cmd, args[0], a, "")
	},

	Use:     docs.RunTestUse,
	Short:   docs.RunTestShort,
	Long:    docs.RunTestLong,
	Example: docs.RunTestExample,
}

TestCmd represents the test command

var VerifyCmd = &cobra.Command{
	DisableFlagsInUseLine: true,
	Args:                  cobra.ExactArgs(1),
	PreRun:                sylabsToken,

	Run: func(cmd *cobra.Command, args []string) {

		fmt.Printf("Verifying image: %s\n", args[0])
		if err := doVerifyCmd(args[0], keyServerURL); err != nil {
			sylog.Errorf("verification failed: %s", err)
			os.Exit(2)
		}
	},

	Use:     docs.VerifyUse,
	Short:   docs.VerifyShort,
	Long:    docs.VerifyLong,
	Example: docs.VerifyExample,
}

VerifyCmd singularity verify

var VersionCmd = &cobra.Command{
	DisableFlagsInUseLine: true,
	Run: func(cmd *cobra.Command, args []string) {
		fmt.Println(buildcfg.PACKAGE_VERSION)
	},

	Use:   "version",
	Short: "Show application version",
}

VersionCmd displays installed singularity version

Functions

func ExecuteSingularity

func ExecuteSingularity()

ExecuteSingularity 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 root command (singularity).

func TraverseParentsUses

func TraverseParentsUses(cmd *cobra.Command) string

TraverseParentsUses walks the parent commands and outputs a properly formatted use string