mounts

Documentation

Overview

Package mounts enhances the Linux kernel's mountinfo data model ("/proc/[PID]/mountinfo") with mount point visibility ("overmounts") and a hierarchical mount path tree.

Lack of visibility for a specific mount point indicates that it has been rendered hidden by either another mount higher up the mount path hierarchy, such as when "/a" hides "/a/b". Or a mount point is hidden by an "in-place" (bind) mount point, such as when mounting "/a" on itself (for instance, to remove child mounts or to change mount options).

For understanding this package it is important to understand the difference between "mount paths" as opposed to "mount points".

Mount Paths

A "mount path" is the path of a mount point in the Virtual File System (VFS) of Linux, such as "/a/b/c". The important take-away here is that a mount path is not the same as mount point. A mount point has a mount path, but a mount path isn't a mount point. In particular, there can be multiple mount points with the same mount path and our our mount path data model thus dul(l)y reflects this.

Mount Points

In our context, a "mount point" describes the properties of a particular mount, such as where the "files & directories" come from, mount options, and at which path the mount point appears in the Virtual File System.

Mount points have uniques (integer) identifiers; however, while these are unambiguous at a given time, they can be reused by the Linux kernel, so they're not necessarily unambiguous over time.

Hidden Mounts and Overmounts

The terms "hidden mounts" and "overmounts" are used (more or less synonymously) to describe mount points that have become inacessible from the perspective of the VFS mount paths. For instance, because due to a new mount point higher up the mount path hierarchy or by overmounting a mount point at the same mount path with itself.

References

procfs(7) and there details about /proc/[PID]/mountinfo in particular: https://man7.org/linux/man-pages/man5/procfs.5.html

Index

• type MountPath
  • func (p MountPath) Path() string
  • func (p MountPath) VisibleMount() *MountPoint
• type MountPathMap
  • func NewMountPathMap(mounts []mntinfo.Mountinfo) (mountpathmap MountPathMap)
• type MountPoint

Types

type MountPath

type MountPath struct {
	Mounts   []*MountPoint `json:"mounts"` // one or several mount points at this same (VFS) path.
	Parent   *MountPath    `json:"-"`      // Parent mount path, except for root mount path.
	Children []*MountPath  `json:"-"`      // Children mount paths.
}

MountPath represents a path name (in the VFS) where there are one or even multiple mount points. MountPaths form a ("sparse") hierarchy of mount paths with references to their nearest parent mount path (that is, longest path prefix) as well as child mount paths.

For instance, given the mount paths "/a" and "/a/b/c" the model only stored "/a" and "/a/b/c", but there is no mount path "/a/b".

Use MountPath.Path() to get the mount path of a MountPath object.

func (MountPath) Path

func (p MountPath) Path() string

Path returns the path name of a MountPath object.

func (MountPath) VisibleMount

func (p MountPath) VisibleMount() *MountPoint

VisibleMount returns the (only) visible mount point at this mount path, or nil if all the mount points at this mount path are hidden by overmounts.

type MountPathMap

type MountPathMap map[string]*MountPath

MountPathMap maps mount paths to (potentially multiple) mount points. If there are multiple mount points with the same mount path, then only at most one of them will be visible, unless this mount path is completely hidden by an overmount with a shorter VFS prefix and no child mounts with the this prefix path.

func NewMountPathMap

func NewMountPathMap(mounts []mntinfo.Mountinfo) (mountpathmap MountPathMap)

NewMountPathMap takes a list of mounts (mount information) and builds a map based on the mount paths, taking into account that due to overmounting the same mount path may map onto multiple mount points (but with only one being not hidden).

Additionally, the mount information accessible by the map is arranged into two separate trees: one tree for the hierarchy of mount paths and a separate tree for the mount point hierarchy.

type MountPoint

type MountPoint struct {
	mntinfo.Mountinfo               // mount (point) information.
	Hidden            bool          `json:"hidden"` // mount point hidden or "overmounted".
	Parent            *MountPoint   `json:"-"`      // parent mount point, if its ID could be resolved.
	Children          []*MountPoint `json:"-"`      // child mount points, derived from mount and parent IDs.
}

MountPoint contains information about a single mount point with additional object references to parent and child mount points.

MountInfo objects form a hierarchical tree that is separate from the mount path tree. The parent/child references base on the mount and parent IDs (from /proc/$PID/mountinfo), instead of mount paths.