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 ¶
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 ¶
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 (*Registry) Add ¶
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) Do ¶
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.