ctrfs

package
v0.2.6 Latest Latest
Warning

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

Go to latest
Published: Oct 14, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

Documentation

Overview

Package ctrfs provides access to a container's filesystem as the container itself sees it.

A container's mounts are applied by the OCI runtime inside the container's own mount namespace. The bundle's rootfs directory, which is what vminitd sees in its own mount namespace, therefore only backs the paths that no mount covers: every bind, volume, tmpfs and overlay destination is shadowed by an empty directory. Reading or writing through the bundle rootfs silently targets those shadowed entries rather than the mounted content.

This package resolves paths through the container's mount namespace instead, so the kernel performs the same mount resolution the container's own processes get, for every mount type, in the correct stacking order.

Only the mount namespace is joined, which makes this close to but not the same as running inside the container. Operations keep vminitd's remaining namespaces and its credentials: root, every capability, no seccomp filter and no cgroup limits. They can therefore read and write what the container's own processes cannot, and anything the kernel derives from a namespace reflects vminitd's rather than the container's, so /proc/sys/net reports the VM's network settings and /proc/self does not resolve at all. Resolution cannot ascend above the container's root, but procfs magic links such as /proc/<pid>/root are not resolution, and where those lead depends on whether the container was given its own PID namespace.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Handle

type Handle struct {
	// contains filtered or unexported fields
}

Handle is a pinned reference to a container's mount namespace.

Holding a Handle keeps the namespace and its entire mount tree alive independently of whether any process in it is still running.

func (*Handle) Close

func (h *Handle) Close() error

Close drops the registry's reference to the namespace. Once no reference remains the kernel tears down the namespace's mount tree and releases the filesystems underneath it. Close is idempotent.

Close does not wait for operations already running against the handle. It refuses any that have not started yet and leaves the last one still running to close the descriptor, so releasing a container never blocks for as long as a transfer takes.

func (*Handle) Do

func (h *Handle) Do(fn func() error) error

Do runs fn on a thread that has joined the container's mount namespace, so paths inside fn resolve as they do for the container's own processes: through its mounts, in its stacking order, and anchored at its root. fn must do all of its filesystem work on the calling goroutine, because only that thread has the container's view and anything handed to another goroutine resolves against vminitd's filesystem instead, silently rather than failing. fn should also be brief, since it occupies a thread that cannot be reused.

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry tracks a pinned mount namespace per container, so a container's filesystem stays reachable for as long as the container exists.

A mount namespace lives while it has at least one reference: a member process, an open file descriptor on /proc/<pid>/ns/mnt, or a bind mount of that path. Relying on a member process would restrict access to running containers, because the namespace and its whole mount tree are torn down as soon as the last process in it exits, which happens on its own for any container whose main process returns. Holding a file descriptor keeps the namespace and its mounts intact after that, so a container that has exited but not yet been deleted remains readable.

A Registry is safe for concurrent use.

func NewRegistry

func NewRegistry() *Registry

NewRegistry returns an empty Registry.

func (*Registry) Add

func (r *Registry) Add(id string, pid int) error

Add pins the mount namespace of pid and records it under the given container ID. The namespace stays pinned until Release or Close.

Add must be called while pid is still alive, which for a container means any time after the OCI runtime has created it. The container's mounts are already in place at that point, before its init process has been started.

Adding an ID that is already present replaces and releases the previous pin, so a recreated container does not inherit a stale namespace.

func (*Registry) Close

func (r *Registry) Close() error

Close releases every reference held by the registry.

func (*Registry) Do

func (r *Registry) Do(id string, fn func() error) error

Do runs fn with the given container's filesystem as the root directory, so paths inside fn resolve as the container resolves them: to mounted content rather than to the entries the container's mounts shadow in the bundle rootfs.

See Handle.Do for the constraints on fn. In particular fn must do all of its filesystem work on the calling goroutine.

func (*Registry) Release

func (r *Registry) Release(id string) error

Release drops the pin recorded for the given container ID, allowing the kernel to tear the namespace down once nothing else references it. Releasing an ID that is not present is not an error, so Release is safe to call on cleanup paths that may run more than once.

Jump to

Keyboard shortcuts

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