runtimeprofile

package
v1.0.40 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 17, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Index

Constants

View Source
const (
	ItzgDefaultUID = 1000
	ItzgDefaultGID = 1000
)

ItzgDefaultUID and ItzgDefaultGID are the accounts shipped in itzg/minecraft-server. A different uid/gid during root-then-drop tries to rewrite /etc/passwd and /etc/group, which fails on a read-only root.

View Source
const SkipChown = "SKIP_CHOWN"

SkipChown tells the itzg image not to recursively chown /data.

View Source
const SkipNsswitchConf = "SKIP_NSSWITCH_CONF"

SkipNsswitchConf tells the itzg image not to rewrite /etc/nsswitch.conf.

Variables

View Source
var ErrRuntimeIncompatible = errors.New("container configuration is incompatible with this image or runtime")

ErrRuntimeIncompatible reports a container configuration that cannot boot the configured image. It is raised from the fully-resolved Docker configuration, before any daemon mutation, so an unsupported combination never replaces a running container or leaves a half-created one behind.

Functions

func HasNoNewPrivileges

func HasNoNewPrivileges(opts []string) bool

HasNoNewPrivileges reports whether security options keep the no-new-privileges bit.

func IsMinecraftImage

func IsMinecraftImage(image string) bool

IsMinecraftImage reports whether an image reference is the itzg Minecraft server image, which is the image that follows the root-start-then-drop bootstrap contract the profile checks.

func MinecraftBootstrapCapabilities

func MinecraftBootstrapCapabilities() []string

MinecraftBootstrapCapabilities are the capabilities the itzg entrypoint needs to prepare /data and drop to the game user.

func PreflightProfile

func PreflightProfile(profile RuntimeProfile) error

PreflightProfile is PreflightRuntime for an already-described profile.

func PreflightRuntime

func PreflightRuntime(spec RuntimeSpec) error

PreflightRuntime inspects the resolved configuration and returns an error when it cannot boot the configured image. The returned error wraps ErrRuntimeIncompatible and every fatal issue.

func RunContract

func RunContract(t *testing.T, describe func(RuntimeSpec) RuntimeProfile)

RunContract executes the shared runtime and storage fixture suite through describe. Panel's container create path and Cloud's node agent both pass their own describe function so the same cases cover both callers.

Types

type ContainerLimits

type ContainerLimits struct {
	// RequestedMemoryMB is the server's configured memory.
	RequestedMemoryMB int64
	// RequestedMemoryBytes and RequestedMemorySwapBytes are HostConfig values
	// sent to Docker. MemoryBytes and MemorySwapBytes are effective: zero when
	// /info says the daemon cannot apply them.
	RequestedMemoryBytes     int64
	RequestedMemorySwapBytes int64
	MemoryBytes              int64
	MemorySwapBytes          int64
	// SwapDisabled is true when the request sets MemorySwap equal to Memory or
	// leaves both unset. It describes the request, not daemon capability.
	SwapDisabled bool
	// RequestedPidsLimit is the process cap on the request. PidsLimit is
	// effective, or 0 when the daemon default applies or /info says pids
	// limits are unsupported.
	RequestedPidsLimit int64
	PidsLimit          int64
	// CPULimit is the configured CPU cap, or 0 for unlimited.
	CPULimit float64
	// RequestedWritableLayerMB is storage-opt size on the request.
	// WritableLayerMB is effective, or 0 when the layer is unbounded, the
	// root is read-only, or /info says storage-opt size is unsupported.
	RequestedWritableLayerMB int64
	WritableLayerMB          int64
	// WorldDiskEnforced is true only when the daemon quotas the world bind.
	// Panel admission (storage.world_quota_mb) can refuse create without
	// setting this. storage-opt size never sets it, including overlay2+xfs.
	WorldDiskEnforced bool
}

ContainerLimits is the enforcement that is actually requested from the daemon, next to the limit the caller asked for. A zero effective value means no limit: it is never reported as if the requested limit applied.

type DaemonEnforcement

type DaemonEnforcement struct {
	Rootless                    bool
	CgroupDriver                string
	CgroupVersion               string
	StorageDriver               string
	MemoryLimitSupported        bool
	SwapLimitSupported          bool
	PidsLimitSupported          bool
	WritableLayerQuotaSupported bool
}

DaemonEnforcement records which cgroup and storage limits the Docker daemon reports as supported. Callers compare this against the resolved container request so an ignored limit is never presented as enforced.

func (DaemonEnforcement) CgroupLimitsQualified

func (d DaemonEnforcement) CgroupLimitsQualified() bool

CgroupLimitsQualified reports whether memory/swap/pids caps are expected to apply on this daemon. Rootless mode needs cgroup v2 delegation; a v1 rootless daemon may ignore resource flags even when MemoryLimit is true.

type RuntimeIssue

type RuntimeIssue struct {
	Code     RuntimeIssueCode
	Severity RuntimeIssueSeverity
	// Detail says what the effective configuration is.
	Detail string
	// Remedy says what to change. It never suggests weakening confinement
	// beyond what the image actually needs.
	Remedy string
}

RuntimeIssue is one compatibility finding with an actionable remedy.

func (RuntimeIssue) Error

func (i RuntimeIssue) Error() string

Error renders the issue as a single diagnostic sentence.

type RuntimeIssueCode

type RuntimeIssueCode string

RuntimeIssueCode is a stable machine-readable identifier for a compatibility finding. It is part of the operator-facing diagnostic, so keep it stable.

const (
	// RuntimeIssueDataMountMissing is raised when no /data mount is present.
	RuntimeIssueDataMountMissing RuntimeIssueCode = "data_mount_missing"
	// RuntimeIssueDataMountReadOnly is raised when /data is mounted read-only.
	RuntimeIssueDataMountReadOnly RuntimeIssueCode = "data_mount_read_only"
	// RuntimeIssueRootfsReadOnlyNsswitch is raised when the root filesystem is
	// read-only but the image was not told to skip its /etc/nsswitch.conf
	// rewrite. The entrypoint fails and the container restart-loops.
	RuntimeIssueRootfsReadOnlyNsswitch RuntimeIssueCode = "read_only_root_blocks_nsswitch"
	// RuntimeIssueBootstrapCapabilitiesMissing is raised when the container
	// starts as root and drops privileges but no longer holds the capabilities
	// that the drop needs.
	RuntimeIssueBootstrapCapabilitiesMissing RuntimeIssueCode = "bootstrap_capabilities_missing"
	// RuntimeIssueNoNewPrivilegesDisabled is raised when no-new-privileges was
	// replaced instead of extended by an override.
	RuntimeIssueNoNewPrivilegesDisabled RuntimeIssueCode = "no_new_privileges_disabled"
	// RuntimeIssuePrivilegedMode is raised for full privilege mode.
	RuntimeIssuePrivilegedMode RuntimeIssueCode = "privileged_mode"
	// RuntimeIssueWritableRootfs is raised when the read-only root default was
	// turned off.
	RuntimeIssueWritableRootfs RuntimeIssueCode = "writable_rootfs"
	// RuntimeIssueNonNumericUser is raised when config.User names a user that
	// Docker can only resolve through the image's /etc/passwd.
	RuntimeIssueNonNumericUser RuntimeIssueCode = "non_numeric_user"
	// RuntimeIssueCustomEntrypoint is raised when an override replaces the
	// image entrypoint that performs first-boot preparation.
	RuntimeIssueCustomEntrypoint RuntimeIssueCode = "custom_entrypoint"
	// RuntimeIssueTmpfsMissing is raised when /tmp is not a tmpfs on a
	// read-only root.
	RuntimeIssueTmpfsMissing RuntimeIssueCode = "tmpfs_missing"
	// RuntimeIssueTmpfsTooSmall is raised when /tmp is too small for unpacking
	// a server jar or mod archive.
	RuntimeIssueTmpfsTooSmall RuntimeIssueCode = "tmpfs_too_small"
	// RuntimeIssueTmpfsExec is raised when /tmp stays executable.
	RuntimeIssueTmpfsExec RuntimeIssueCode = "tmpfs_exec"
	// RuntimeIssueHostNetwork is raised for host networking.
	RuntimeIssueHostNetwork RuntimeIssueCode = "host_network"
	// RuntimeIssueHostDevice is raised for a host device mapping.
	RuntimeIssueHostDevice RuntimeIssueCode = "host_device"
	// RuntimeIssueDataOwnerMismatch is raised when the container runs as a
	// numeric user that cannot own the world directory the panel created.
	RuntimeIssueDataOwnerMismatch RuntimeIssueCode = "data_owner_mismatch"
	// RuntimeIssueMemoryLimitUnset is raised when the container has no memory
	// limit, so one server can consume the node.
	RuntimeIssueMemoryLimitUnset RuntimeIssueCode = "memory_limit_unset"
	// RuntimeIssueSwapEnabled is raised when the 0-swap policy was overridden.
	RuntimeIssueSwapEnabled RuntimeIssueCode = "swap_enabled"
	// RuntimeIssuePidsLimitUnset is raised when the fork-bomb guard is absent.
	RuntimeIssuePidsLimitUnset RuntimeIssueCode = "pids_limit_unset"
	// RuntimeIssueWritableLayerUnbounded is raised for a writable root with no
	// writable-layer cap.
	RuntimeIssueWritableLayerUnbounded RuntimeIssueCode = "writable_layer_unbounded"
	// RuntimeIssueStorageQuotaIsNotAWorldQuota is raised when a storage-opt
	// size is presented as if it bounded the world.
	RuntimeIssueStorageQuotaIsNotAWorldQuota RuntimeIssueCode = "storage_quota_is_not_a_world_quota"
	// RuntimeIssueWorldQuotaExceeded is raised when storage.world_quota_mb is
	// set and measured world bytes meet or exceed it. Creation is refused.
	RuntimeIssueWorldQuotaExceeded RuntimeIssueCode = "world_quota_exceeded"
	// RuntimeIssueWorldQuotaUnmeasured is raised when a world quota is set but
	// world bytes could not be measured, so admission fails closed.
	RuntimeIssueWorldQuotaUnmeasured RuntimeIssueCode = "world_quota_unmeasured"
	// RuntimeIssueWritableLayerCapIgnored is raised when a writable-layer cap
	// is configured but the root is read-only, so nothing is capped.
	RuntimeIssueWritableLayerCapIgnored RuntimeIssueCode = "writable_layer_cap_ignored"
	// RuntimeIssueMemoryLimitUnsupported is raised when the container requests a
	// memory cap but the daemon reports it cannot enforce one.
	RuntimeIssueMemoryLimitUnsupported RuntimeIssueCode = "memory_limit_unsupported"
	// RuntimeIssueSwapLimitUnsupported is raised when swap is enabled on the
	// request but the daemon reports swap limits are unavailable.
	RuntimeIssueSwapLimitUnsupported RuntimeIssueCode = "swap_limit_unsupported"
	// RuntimeIssuePidsLimitUnsupported is raised when a process cap is set but
	// the daemon reports pids limits are unavailable.
	RuntimeIssuePidsLimitUnsupported RuntimeIssueCode = "pids_limit_unsupported"
	// RuntimeIssueRootlessCgroupUnqualified is raised when a rootless daemon is
	// not on cgroup v2, so cgroup resource flags may be ignored.
	RuntimeIssueRootlessCgroupUnqualified RuntimeIssueCode = "rootless_cgroup_unqualified"
	// RuntimeIssueWritableLayerCapUnsupported is raised when a writable-layer
	// cap is requested on a storage stack that does not support storage-opt size.
	RuntimeIssueWritableLayerCapUnsupported RuntimeIssueCode = "writable_layer_cap_unsupported"
	// RuntimeIssueImageUnpinned is raised when a Minecraft image is a moving
	// tag. It is a warning: the container can still boot, but a rebuilt tag
	// can change what the next recreate runs.
	RuntimeIssueImageUnpinned RuntimeIssueCode = "image_unpinned"
	// RuntimeIssueRootlessHostRootData is raised when a rootless daemon must run
	// the root-then-drop bootstrap but the world directory is still owned by
	// host uid 0. The entrypoint cannot chown it into the user namespace.
	RuntimeIssueRootlessHostRootData RuntimeIssueCode = "rootless_host_root_data"
	// RuntimeIssueReadOnlyRootUserMod is raised when root-then-drop would
	// usermod/groupmod an account that is not already in the image, which
	// needs a writable /etc.
	RuntimeIssueReadOnlyRootUserMod RuntimeIssueCode = "read_only_root_blocks_usermod"
	// RuntimeIssueSensitiveMount is raised when an override bind shadows a
	// sensitive container path (for example /etc or the Docker socket).
	RuntimeIssueSensitiveMount RuntimeIssueCode = "sensitive_mount_target"
	// RuntimeIssueTmpfsReplaced is raised when a bind or volume covers /tmp
	// and therefore replaces the default noexec tmpfs.
	RuntimeIssueTmpfsReplaced RuntimeIssueCode = "tmpfs_replaced"
)

type RuntimeIssueSeverity

type RuntimeIssueSeverity string

RuntimeIssueSeverity orders issues by whether they block a boot.

const (
	// RuntimeFatal issues mean the container cannot reach a playable state as
	// configured. They stop creation.
	RuntimeFatal RuntimeIssueSeverity = "fatal"
	// RuntimeWarning issues mean the configuration is weaker or more fragile
	// than the default, but the image can still boot. They are reported and
	// never stop creation.
	RuntimeWarning RuntimeIssueSeverity = "warning"
)

type RuntimeProfile

type RuntimeProfile struct {
	Image string
	// ImageDigest is the sha256 digest when the image reference is pinned.
	// Empty means the reference is a tag.
	ImageDigest       string
	ImagePinned       bool
	MinecraftImage    bool
	User              string
	RootStartDropUser bool
	ReadOnlyRootfs    bool
	DataMount         string
	DataWritable      bool
	Tmpfs             map[string]string
	CapAdd            []string
	CapDrop           []string
	Privileged        bool
	NoNewPrivileges   bool
	NetworkMode       string
	Devices           []string
	Entrypoint        []string
	Limits            ContainerLimits
	// SkipDataChown is true when SKIP_CHOWN is set so the image will not
	// recursively chown /data on this start.
	SkipDataChown bool
	Issues        []RuntimeIssue
}

RuntimeProfile is the effective, inspectable runtime description of one container: what it runs as, what it can write, how confined it is, and which limits are actually enforced.

func DescribeRuntime

func DescribeRuntime(spec RuntimeSpec) RuntimeProfile

DescribeRuntime returns the effective profile of a resolved runtime spec together with its compatibility issues.

func (RuntimeProfile) Description

func (p RuntimeProfile) Description() string

Description renders a one-line summary of the effective profile for logs and diagnostics.

func (RuntimeProfile) Fatal

func (p RuntimeProfile) Fatal() bool

Fatal reports whether any issue blocks a boot.

type RuntimeSpec

type RuntimeSpec struct {
	// Image is the resolved image reference.
	Image string
	// DataPath is the host directory bound to /data.
	DataPath string
	// MinecraftImage marks an image that follows the itzg first-boot
	// contract: start as root, prepare /data, rewrite /etc/nsswitch.conf, then
	// drop to the unprivileged game user through gosu.
	MinecraftImage bool
	// RequestedMemoryMB is the memory the server record asked for, which the
	// effective container limit is derived from.
	RequestedMemoryMB int64
	// WritableLayerMB is the operator's writable-layer cap. It is applied only
	// when the root filesystem is writable.
	WritableLayerMB int64
	// WorldQuotaMB is panel admission against measured world bytes. 0 disables.
	// It is not a daemon, xfs, or volume quota and does not set WorldDiskEnforced.
	WorldQuotaMB int64
	// WorldBytes is the metrics collector's world-directory total when known.
	WorldBytes int64
	// WorldBytesKnown is false when a set quota could not be measured.
	WorldBytesKnown bool
	// DataOwnerUID is the owner of DataPath when the platform can report it.
	// It lets the profile tell a supported non-root path (the directory was
	// prepared for that uid) from one that would fail at boot.
	DataOwnerUID *int
	// Daemon is the Docker daemon's reported limit capabilities when known.
	// Missing means qualification was not performed; no daemon issue is raised.
	Daemon *DaemonEnforcement
	// Config and HostConfig are the resolved daemon request.
	Config     *container.Config
	HostConfig *container.HostConfig
}

RuntimeSpec is the fully-resolved configuration that is about to be sent to the Docker daemon. Because it is taken after the defaults and every operator override have been applied, a check here sees exactly what the daemon will run rather than what the helpers meant. It does not carry a panel server row, an RPC handler, or a transport protobuf.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL