image

Documentation

Overview

Package image provides underlying data types for Apptainer image formats. Additionally, all image types will satisfy the ImageFormat{} interface. This interface will expose all things necessary to use an Apptainer image, whether through OCI or directly.

type ImageFormat interface {
    Root() *spec.Root - Root() returns the OCI compliant root of the
                        Image. This function may perform some action,
                        such as extracting the filesystem to a dir.
}

Index

• Constants
• Variables
• func CheckExt3Header(b []byte) (uint64, error)
• func CheckSquashfsHeader(b []byte) (uint64, error)
• func GetSquashfsComp(b []byte) (string, error)
• func IsReadOnlyFilesytem(err error) bool
• func NewPartitionReader(image *Image, name string, index int) (io.Reader, error)
• func NewSectionReader(image *Image, name string, index int) (io.Reader, error)
• func RegisterDriver(name string, driver Driver) error
• func ResolvePath(path string) (string, error)
• type Driver
  • func GetDriver(name string) Driver
• type DriverFeature
• type DriverParams
• type Image
  • func Init(path string, writable bool) (*Image, error)
  • func (i *Image) AuthorizedGroup(groups []string) (bool, error)
  • func (i *Image) AuthorizedOwner(owners []string) (bool, error)
  • func (i *Image) AuthorizedPath(paths []string) (bool, error)
  • func (i *Image) GetAllPartitions() ([]Section, error)
  • func (i *Image) GetDataPartitions() ([]Section, error)
  • func (i *Image) GetOverlayPartitions() ([]Section, error)
  • func (i *Image) GetRootFsPartition() (*Section, error)
  • func (i *Image) GetRootFsPartitions() ([]Section, error)
  • func (i *Image) HasEncryptedRootFs() (encrypted bool, err error)
  • func (i *Image) ReInit()
• type MountFunc
• type MountParams
• type Section
• type Usage

Constants

const (
	// SQUASHFS constant for squashfs format
	SQUASHFS = iota + 0x1000
	// EXT3 constant for ext3 format
	EXT3
	// SANDBOX constant for directory format
	SANDBOX
	// SIF constant for sif format
	SIF
	// ENCRYPTSQUASHFS constant for encrypted squashfs format
	ENCRYPTSQUASHFS
	// RAW constant for raw format
	RAW
	// GOCRYPTFS constant for encrypted gocryptfs format
	GOCRYPTFSSQUASHFS
)

const (
	// RootFsUsage defines flag for image/partition
	// usable as root filesystem.
	RootFsUsage = Usage(1 << iota)
	// OverlayUsage defines flag for image/partition
	// usable as overlay.
	OverlayUsage
	// DataUsage defines flag for image/partition
	// usable as data.
	DataUsage
)

const (
	// ErrNoSection corresponds to an image section not found.
	ErrNoSection = readerError("no section found")
	// ErrNoPartition corresponds to an image partition not found.
	ErrNoPartition = readerError("no partition found")
)

const (
	// SIFDescOCIConfigJSON is the name of the SIF descriptor holding the OCI configuration.
	SIFDescOCIConfigJSON = "oci-config.json"
	// SIFDescInspectMetadataJSON is the name of the SIF descriptor holding the container metadata.
	SIFDescInspectMetadataJSON = "inspect-metadata.json"
)

const (
	// RootFs partition name
	RootFs = "!__rootfs__!"
)

Variables

var ErrUnknownFormat = errors.New("image format not recognized")

ErrUnknownFormat represents an unknown image format error.

Functions

func CheckExt3Header

func CheckExt3Header(b []byte) (uint64, error)

CheckExt3Header checks if byte content contains a valid ext3 header and returns offset where ext3 partition begin

func CheckSquashfsHeader

func CheckSquashfsHeader(b []byte) (uint64, error)

CheckSquashfsHeader checks if byte content contains a valid squashfs header and returns offset where squashfs partition starts

func GetSquashfsComp

func GetSquashfsComp(b []byte) (string, error)

GetSquashfsComp checks if byte content contains a valid squashfs header and returns type of compression used

func IsReadOnlyFilesytem

func IsReadOnlyFilesytem(err error) bool

IsReadOnlyFilesytem returns if the corresponding error is a read-only filesystem error or not.

func NewPartitionReader

func NewPartitionReader(image *Image, name string, index int) (io.Reader, error)

NewPartitionReader searches and returns a reader for an image partition identified by name or by index, if index is less than 0 only partition with provided name will be returned if a matching entry is found

func NewSectionReader

func NewSectionReader(image *Image, name string, index int) (io.Reader, error)

NewSectionReader searches and returns a reader for an image section identified by name or by index, if index is less than 0 only section with provided name will be returned if a matching entry is found.

func RegisterDriver

func RegisterDriver(name string, driver Driver) error

RegisterDriver registers an image driver by name.

func ResolvePath

func ResolvePath(path string) (string, error)

ResolvePath returns a resolved absolute path.

Types

type Driver

type Driver interface {
	// Mount is called each time an engine mount an image
	Mount(*MountParams, MountFunc) error
	// Start the driver for initialization.
	Start(*DriverParams, int) error
	// Stop the driver related to given mount target for cleanup.
	Stop(string) error
	// Features Feature returns supported features.
	Features() DriverFeature
}

Driver defines the image driver interface to register.

func GetDriver

func GetDriver(name string) Driver

GetDriver returns the named image driver interface.

type DriverFeature

type DriverFeature uint16

DriverFeature defines a feature type that a driver is supporting.

const (
	// ImageFeature means the driver handle image mount setup.
	ImageFeature DriverFeature = 1 << iota
	// OverlayFeature means the driver handle overlay mount.
	OverlayFeature
	// FuseFeature means the driver use FUSE.
	FuseFeature
)

type DriverParams

type DriverParams struct {
	SessionPath string         // session driver image path
	UsernsFd    int            // user namespace file descriptor
	FuseFd      int            // fuse file descriptor
	Config      *config.Common // common engine configuration
}

DriverParams defines parameters passed to driver interface while starting it.

type Image

type Image struct {
	Partitions []Section `json:"partitions"`
	Sections   []Section `json:"sections"`
	Path       string    `json:"path"`
	Name       string    `json:"name"`
	Source     string    `json:"source"`
	Type       int       `json:"type"`
	File       *os.File  `json:"-"`
	Fd         uintptr   `json:"fd"`
	Writable   bool      `json:"writable"`
	Usage      Usage     `json:"usage"`
}

Image describes an image object, an image is composed of one or more partitions (eg: container root filesystem, overlay), image format like SIF contains descriptors pointing to chunk of data, chunks position and size are stored as image sections.

func Init

func Init(path string, writable bool) (*Image, error)

Init initializes an image object based on given path.

func (*Image) AuthorizedGroup

func (i *Image) AuthorizedGroup(groups []string) (bool, error)

AuthorizedGroup checks whether the image is owned by any group from the supplied groups list.

func (*Image) AuthorizedOwner

func (i *Image) AuthorizedOwner(owners []string) (bool, error)

AuthorizedOwner checks whether the image is owned by any user from the supplied users list.

func (*Image) AuthorizedPath

func (i *Image) AuthorizedPath(paths []string) (bool, error)

AuthorizedPath checks if image is in a path supplied in paths

func (*Image) GetAllPartitions

func (i *Image) GetAllPartitions() ([]Section, error)

GetAllPartitions returns all partitions found in the image.

func (*Image) GetDataPartitions

func (i *Image) GetDataPartitions() ([]Section, error)

GetDataPartitions returns data partitions found in the image.

func (*Image) GetOverlayPartitions

func (i *Image) GetOverlayPartitions() ([]Section, error)

GetOverlayPartitions returns overlay partitions found in the image.

func (*Image) GetRootFsPartition

func (i *Image) GetRootFsPartition() (*Section, error)

GetRootFsPartition returns the first root filesystem partition found in the image.

func (*Image) GetRootFsPartitions

func (i *Image) GetRootFsPartitions() ([]Section, error)

GetRootFsPartitions returns root filesystem partitions found in the image.

func (*Image) HasEncryptedRootFs

func (i *Image) HasEncryptedRootFs() (encrypted bool, err error)

HasEncryptedRootFs returns true if the image contains an encrypted rootfs partition.

func (*Image) ReInit

func (i *Image) ReInit()

ReInit fills in the File object if needed. This function should be called after passing an image object between processes using JSON

type MountFunc

type MountFunc func(source string, target string, filesystem string, flags uintptr, data string) error

MountFunc defines mount function prototype

type MountParams

type MountParams struct {
	Source           string   // image source
	Target           string   // image target mount point
	Filesystem       string   // image filesystem type
	Flags            uintptr  // mount flags
	Offset           uint64   // offset where start filesystem
	Size             uint64   // size of image filesystem
	Key              []byte   // filesystem decryption key
	FSOptions        []string // filesystem mount options
	DontElevatePrivs bool     // omit cmd.SysProcAttr, currently only used by gocryptfs
}

MountParams defines parameters passed to driver interface while mounting images.

type Section

type Section struct {
	Name         string `json:"name"`
	Size         uint64 `json:"size"`
	Offset       uint64 `json:"offset"`
	ID           uint32 `json:"id"`
	Type         uint32 `json:"type"`
	AllowedUsage Usage  `json:"allowed_usage"`
}

Section identifies and locates a data section in image object.

type Usage

type Usage uint8