Documentation
¶
Overview ¶
Package overlay assembles OverlayFS environments from squashfs layers.
The assembly sequence is:
- Mount each layer as a read-only squashfs loopback device.
- Mount a tmpfs for the ephemeral upper and work directories.
- Assemble the OverlayFS at /strata/env.
- Write environment config files so processes see the merged view.
Mount and Cleanup are Linux-only (syscall.Mount). On other platforms they return ErrNotSupported. ConfigureEnvironment is platform-neutral.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNotSupported = errors.New("overlay: OverlayFS assembly requires Linux")
ErrNotSupported is returned on non-Linux platforms where OverlayFS assembly is not available.
Functions ¶
func ConfigureEnvironment ¶
ConfigureEnvironment writes the three environment files after a successful mount. rootDir is the filesystem root prefix; use "/" in production and t.TempDir() in tests.
Files written:
- <rootDir>/etc/profile.d/strata.sh — shell env (PATH, LD_LIBRARY_PATH, STRATA_*)
- <rootDir>/etc/strata/environment — systemd EnvironmentFile (KEY=VALUE)
- <rootDir>/etc/strata/active.lock.yaml — the active lockfile
func VerifyLayerLayout ¶
VerifyLayerLayout checks that a mounted layer's on-disk structure matches the Name/Version/InstallLayout its manifest claims.
Those three fields are read on the assembly path to build PATH and LD_LIBRARY_PATH, but are covered by no signature — the cosign bundle attests the layer bytes, not the manifest document (#146). Under an A1 registry write an attacker edits them in a served manifest, breaks no signature, and redirects which binaries a login shell resolves. Deriving the layout from the mounted bytes turns those unsigned assertions into checkable ones, so a tampered manifest is refused rather than silently degrading the environment to host binaries.
layerRoot is the layer's own mount point — a single layer, not the merged overlay, so the check is attributed to the layer whose manifest is under test:
- A versioned layer (InstallLayout != "flat") must contain <name>/<version>/bin, the exact directory ConfigureEnvironment puts on PATH. Its absence means the manifest names a version the bytes do not provide (e.g. a served manifest with version bumped 3.11.9 → 3.11.10).
- A "flat" layer must NOT contain <name>/<version>/bin. Its presence means a versioned layer was relabeled "flat" to drop it from PATH while it still mounts — a silent downgrade to host binaries.
Types ¶
type Config ¶
type Config struct {
LayersDir string // default: /strata/layers
RWDir string // default: /strata/rw
MergedDir string // default: /strata/env
Strategy MountStrategy // nil → selectMountStrategy() (Linux only)
// VerifyLayerLayout, when true, makes MountWithConfig refuse any layer whose
// on-disk structure contradicts the Name/Version/InstallLayout its manifest
// claims (#146). The runtime boot paths (Mount, strata run) set it; the build
// environment (MountBuildEnv) does not — build_requires layers are inputs to a
// build, not a runtime environment a user trusts, and are not the A1 target.
VerifyLayerLayout bool
}
Config controls how MountWithConfig assembles the OverlayFS. Zero values use production defaults (/strata/* paths, auto-detected strategy).
type LayerPath ¶
type LayerPath struct {
ID string // layer ID, used for mount point naming
SHA256 string // hex SHA256, used as cache key
Path string // local .sqfs file path
MountOrder int // from lockfile; 1 = bottom of stack
// Name, Version and InstallLayout are the manifest triple that decides how
// this layer contributes to PATH/LD_LIBRARY_PATH. They are unsigned (#146),
// so when Config.VerifyLayerLayout is set the mount checks them against the
// layer's actual contents. Empty on paths that do not verify layout.
Name string
Version string
InstallLayout string
}
LayerPath is a pulled squashfs layer ready to be mounted.
type MountStrategy ¶
type MountStrategy interface {
MountSquashfs(sqfsPath, mountPoint string) error
MountTmpfs(mountPoint string) error
MountOverlay(lowerDirs []string, upper, work, merged string) error
Unmount(mountPoint string, lazy bool) error
}
MountStrategy performs the individual filesystem mount operations. SyscallMountStrategy uses kernel mounts (requires CAP_SYS_ADMIN). FUSEMountStrategy uses squashfuse + fuse-overlayfs (unprivileged).
type Overlay ¶
type Overlay struct {
MergedPath string // /strata/env — what processes see
UpperDir string // tmpfs subdir for ephemeral writes
WorkDir string // tmpfs subdir for OverlayFS internal use
// contains filtered or unexported fields
}
Overlay is a mounted OverlayFS assembly. Call Cleanup when done. The overlay stays mounted until Cleanup is called (i.e., until the strata-agent process exits).
func Mount ¶
Mount mounts each layer as a read-only squashfs loopback device, creates a tmpfs for the upper and work directories, then assembles the OverlayFS at /strata/env. It is a thin wrapper around MountWithConfig with production defaults.
func MountBuildEnv ¶
MountBuildEnv mounts the given squashfs layers as a read-only OverlayFS build environment at a configurable base directory. It is a thin wrapper around MountWithConfig with paths under baseDir.
Layout under baseDir:
layers/<id> — squashfs mount point for each layer (read-only) rw/upper — tmpfs subdir for ephemeral writes during build rw/work — OverlayFS internal work directory (tmpfs) merged — merged view presented to the build script
func MountWithConfig ¶
MountWithConfig assembles the OverlayFS using the provided Config. Zero-value Config fields use production defaults (/strata/* paths, auto-detected mount strategy).
Layers are mounted in ascending MountOrder (MountOrder=1 is at the bottom of the OverlayFS lower stack). The highest-MountOrder layer wins in the OverlayFS lookup order.
If any mount step fails, all previously mounted filesystems are unmounted before returning the error. No dangling mounts are left behind.
Source Files