atomfs

README

atomfs

atomfs is a tool that can mount OCI images built in the squashfs format as a read-only overlayfs filesystem that can be used by a container runtime.

For OCI-squashfs images that were created with dm-verity data appended, which stacker does by default, then atomfs will mount each individual squashfs layer using dm-verity before constructing the final overlayfs stack. This ensures the integrity of the contents of the image when mounted, and the use of squashfs removes the window of time between tar extraction and image mounting when an image could be tampered with.

atomfs library

Please find the atomfs library documentation at godoc.

atomfs binary

This can be used to mount an OCI+squashfs image. If you are host root, then squashfs will be mounted by the kernel. If you are container root but not host root, then squashfuse will be used.

Example:

atomfs mount containers/oci:minbase:latest mnt
atomfs umount mnt

Longer example:

$ lxc-usernsexec -s
$ atomfs mount zothub:busybox-squashfs dest
$ ls dest
bin  dev  etc  home  lib  lib64  root  tmp  usr  var
$ atomfs umount dest
$ mkdir upper
$ atomfs mount --upper=./upper zothub:busybox-squashfs dest
$ ls dest
bin  dev  etc  home  lib  lib64  root  tmp  usr  var
$ touch dest/ab
$ atomfs umount dest
$ ls upper/
ab

Implementation details

The atomfs binary uses the atomfs package's Molecule API to mount oci images.

Each squashfs layer is mounted separately at a subdir under /run/atomfs/meta/$mountnsid/$mountpoint/, and then an overlay mount is constructed for the specified mountpath. If specified in the config, a writeable upperdir is added to the overlay mount.

Note that if you simply call umount on the mountpoint, then you will be left with all the individual squashfs mounts under /run/atomfs/meta/$mountnsid/$mountpoint/. Use atomfs umount instead.

Note that you do need to be root in your namespace in order to do the final overlay mount. (We could get around this by using fuse-overlay, but creating a namespace seems overall tidy).

Documentation

Index

• Variables
• func EnsureDir(dir string) error
• func GetMountNSName() (string, error)
• func PathExists(d string) bool
• func ReplacePathSeparators(p string) string
• func RuntimeDir(metadir string) string
• func Umount(dest string) error
• func UmountWithMetadir(dest, metadirArg string) error
• type Molecule
  • func BuildMoleculeFromOCI(opts MountOCIOpts) (Molecule, error)
  • func (m Molecule) MetadataPath() (string, error)
  • func (m Molecule) Mount(dest string) error
  • func (m Molecule) MountedAtomsPath(parts ...string) (string, error)
• type MountOCIOpts
  • func (c MountOCIOpts) AtomsPath(parts ...string) string
  • func (c MountOCIOpts) WriteToFile(filename string) error

Variables

var OverlayMountOptions = "index=off,xino=on,userxattr"

var TestOverrideRuntimeDirKey = "ATOMFS_TEST_RUN_DIR"

Functions

func EnsureDir

func EnsureDir(dir string) error

func GetMountNSName

func GetMountNSName() (string, error)

func PathExists

func PathExists(d string) bool

func ReplacePathSeparators

func ReplacePathSeparators(p string) string

remove dir separators to make one dir name. It is OK that this can't be cleanly backed out, we don't need it to

func RuntimeDir

func RuntimeDir(metadir string) string

Allow overriding runtime dir for tests so we can assert empty dirs, etc.

func Umount

func Umount(dest string) error

Default Umount passes "" and uses /run/atomfs metadir, see RuntimeDir().

func UmountWithMetadir

func UmountWithMetadir(dest, metadirArg string) error

Types

type Molecule

type Molecule struct {
	// Atoms is the list of atoms in this Molecule. The first element in
	// this list is the top most layer in the overlayfs.
	Atoms []ispec.Descriptor
	// contains filtered or unexported fields
}

func BuildMoleculeFromOCI

func BuildMoleculeFromOCI(opts MountOCIOpts) (Molecule, error)

func (Molecule) MetadataPath

func (m Molecule) MetadataPath() (string, error)

func (Molecule) Mount

func (m Molecule) Mount(dest string) error

Mount mounts an overlay at dest, with writeable overlay as per m.config

func (Molecule) MountedAtomsPath

func (m Molecule) MountedAtomsPath(parts ...string) (string, error)

type MountOCIOpts

type MountOCIOpts struct {
	OCIDir                 string
	Tag                    string
	Target                 string
	AddWriteableOverlay    bool
	WriteableOverlayPath   string
	AllowMissingVerityData bool
	MetadataDir            string
}

func (MountOCIOpts) AtomsPath

func (c MountOCIOpts) AtomsPath(parts ...string) string

func (MountOCIOpts) WriteToFile

func (c MountOCIOpts) WriteToFile(filename string) error