Documentation
¶
Overview ¶
Package hostmount answers one question for a panel that may be running in a container: where does the Docker daemon see this process's data directory?
A bind source is interpreted by the daemon in the host's filesystem, not in the panel's. When the panel runs in a container, a server directory it sees at /app/data/servers/x must be requested as /srv/carbon-panel/data/servers/x. Requiring the operator to restate that mapping in an environment variable is redundant: the panel can read it from its own container's mount table, which is also the only way to notice that the mount is missing or read-only.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNotMounted = errors.New("data directory is not a mounted volume")
ErrNotMounted reports that the container has no volume covering the data directory at all, so worlds would be written into the container layer.
Functions ¶
func CheckMounted ¶
CheckMounted refuses a data directory that is not on a persistent mount. It runs before the database is created, so a compose file with a missing or misspelt volume fails without writing anything into the container layer.
Only the data directory is fatal. Backups and scratch space may legitimately live somewhere this check cannot see (an S3-only deployment keeps a local scratch directory), so those are reported by UnmountedWarnings instead.
A panel running directly on a host has nothing to check and returns nil. So does a platform where mountinfo is not available; the daemon-backed check in Resolve still applies there.
func CheckOverride ¶
func CheckOverride() error
CheckOverride validates the deprecated host-path override without needing a Docker client, so a relative value is rejected before the database is created. It is a no-op when the variable is unset.
func Configure ¶
func Configure(m Mapping)
Configure publishes the resolved mapping. It is called once during startup. An empty mapping clears it, which is what a caller that wants the legacy fallback (a test, a maintenance command) does.
func Translate ¶
Translate maps a path onto the daemon's filesystem using the configured mapping. A process that never resolved one (a unit test, a maintenance command) falls back to the legacy environment override, so behaviour does not change under it.
func UnmountedWarnings ¶
UnmountedWarnings names the non-critical directories that are not on a persistent mount. They are usable, but their contents do not survive a container recreate.
func ValidateDirs ¶
ValidateDirs checks that the directories the panel depends on are usable before anything writes to them. It is the check that turns a bad volume mapping into one clear error at startup instead of worlds silently landing in a container's writable layer.
Types ¶
type Dirs ¶
Dirs are the directories the panel writes: server worlds, backups and scratch space. They are the ones that must survive a container recreate.
type Inspector ¶
Inspector reports the mounts of the container this process runs in. A nil slice with a nil error means the process is not running in a container the daemon knows about.
type Mapping ¶
type Mapping struct {
// ContainerDir is the path this process writes to.
ContainerDir string
// HostDir is the path the daemon understands. It equals ContainerDir when
// no translation is needed.
HostDir string
// Translated reports whether the two differ.
Translated bool
// Origin names where the mapping came from, for the startup log.
Origin string
// Mismatch reports that a deprecated override disagreed with the mapping
// the daemon reported. The detected mapping still wins.
Mismatch bool
// OverrideDir is the override value that disagreed.
OverrideDir string
}
Mapping is the resolved relationship between a directory as this process sees it and the same directory as the Docker daemon sees it.
func Current ¶
func Current() Mapping
Current returns the resolved mapping, or the zero mapping when startup has not resolved one.
func Resolve ¶
Resolve determines the host-side path of the data directory.
Detection is best effort and never fails a running deployment by itself:
- when the process is not in a container, no translation is needed;
- when the container's mount table names a mount that covers the data directory, that mount is authoritative, and a read-only, tmpfs or relative mount is a hard error because the panel would otherwise write worlds into a layer that is discarded with the container;
- when the mount table cannot be read (a restricted Docker socket proxy, for example) the legacy override is used if it is present, and otherwise the panel runs without translation and says so.
type Mount ¶
type Mount struct {
Kind Kind
Source string // the host path for a bind mount, the volume name for a volume
Destination string // the path inside the container
RW bool
}
Mount is one entry of a container's mount table.
type NotMountedError ¶
NotMountedError names the directory and the setting that produced it.
func (*NotMountedError) Error ¶
func (e *NotMountedError) Error() string
Error names the directory and explains the consequence.
func (*NotMountedError) Is ¶
func (e *NotMountedError) Is(target error) bool
Is lets callers test for ErrNotMounted whichever check produced the error.