Documentation
¶
Overview ¶
Package criu wraps the criu command line for the two things fiberd needs: dump one fiber's process tree into an image directory, and restore it later into a cgroup leaf of the runtime's choosing.
Index ¶
- Constants
- Variables
- func DumpMounts(pid int, dir string) ([]string, error)
- func FindPagemaps(dir string) ([]string, error)
- func HasDelta(dir string) bool
- func ImageBytes(dir string) (uint64, error)
- func MergeDelta(dir string, parent *Parent) error
- func MountPoints(mountinfo string) []string
- func OwnMountNS(pid int) bool
- func RestoreMounts(dir, root string) ([]string, error)
- func SocketInode(pid, fd int) (string, error)
- type After
- type Commander
- type DeltaInfo
- type Options
- type Pagemap
- type PagemapEntry
- type Parent
- type Process
- type Restored
Constants ¶
const ( // Page flags in pagemap entries. PEParent = 1 << 0 PELazy = 1 << 1 PEPresent = 1 << 2 )
const MountsFile = "fiberd-mounts.json"
MountsFile, beside a dump's images, names the single-file mounts of a tree that has a mount namespace of its own. CRIU's automatic external mount detection (--external mnt[]) dumps them but cannot restore them, so each is dumped and restored by name.
Variables ¶
var ErrParentMismatch = errors.New("criu: delta was taken over a checkpoint this home does not hold")
var MinVersion = [2]int{4, 2}
MinVersion is the oldest criu fiberd parks with. Older ones dump glibc's getrandom state page (2.41 and later) and restore it as plain memory, so every copy resumed from one park continues one keystream, and on recent kernels the dump of that page fails outright.
var PageSize = uint64(os.Getpagesize())
PageSize is the page granularity of the images (host page size).
Functions ¶
func DumpMounts ¶
DumpMounts records, in dir, the single-file mounts of pid's mount namespace and returns the criu dump arguments for that namespace. It returns nil when pid shares the caller's.
func FindPagemaps ¶
FindPagemaps lists the pagemap images in a dump directory.
func HasDelta ¶
HasDelta reports whether dir holds a delta (pages stripped) rather than a full checkpoint.
func ImageBytes ¶
ImageBytes sums the memory image files (pages-*.img) in dir: the size of the checkpointed working set until incremental dumps (phase 6) make it the delta over the zygote.
func MergeDelta ¶
MergeDelta turns a delta directory back into a full checkpoint using the parent, which must hash to the delta's recorded parent. Streams. It rewrites the only copy of a parked session, so it is all or nothing the same way: a failure leaves the delta as it was, still restorable.
func MountPoints ¶
MountPoints lists the mount points of a mountinfo table, unescaped, in table order.
func OwnMountNS ¶
OwnMountNS reports whether pid lives in a mount namespace other than the caller's.
func RestoreMounts ¶
RestoreMounts returns the criu restore arguments for a dump DumpMounts recorded, with root as the new namespace's root (a mount point of the host's /), or nil when the dump has no mount namespace.
func SocketInode ¶
SocketInode returns the inode of the unix socket a process holds on fd, formatted for --external unix[...].
Types ¶
type After ¶
type After int
After says what becomes of the dumped tree once the images are written.
const ( // Kill ends the tree as the dump completes. Kill After = iota // LeaveRunning lets the tree run on, and the caller ends it once the // images are durable. LeaveRunning // LeaveStopped leaves every task of the tree stopped, so nothing it // could write between the dump and what the caller records next is // missed. The caller continues or kills it. A tree with a pid // namespace of its own is continued task by task, since SIGCONT to // its root reaches that process alone. LeaveStopped )
type Commander ¶
type Commander interface {
Output(ctx context.Context, args []string) ([]byte, error)
Start(args []string, files []*os.File, cgroupFD int) (Process, error)
}
Commander is how the package runs criu. Output runs a check or a dump to its end and returns what it printed. Start begins a restore with files as criu's descriptors 3 and up, inside the cgroup cgroupFD names when it is not negative, and returns the running process.
type DeltaInfo ¶
type DeltaInfo struct {
PageSize uint64 `json:"page_size"`
ParentSHA256 string `json:"parent_sha256"`
TotalPages uint64 `json:"total_pages"`
KeptPages uint64 `json:"kept_pages"`
Files []string `json:"files"` // pagemap images the delta covers
}
DeltaInfo is written beside a delta as delta.json.
func ComputeDelta ¶
ComputeDelta rewrites the checkpoint in dir as a delta over the parent: every page whose bytes equal the parent's page at the same address is dropped from the pages file and marked PE_PARENT in the pagemap. Runs are split and re-merged so the pagemap stays compact. Streams. All or nothing: every result is written to a temporary file first, and only when all of them succeeded are they renamed over the images, delta.json last. A failure leaves the full checkpoint as it was.
func ReadDeltaInfo ¶
ReadDeltaInfo loads delta.json.
func (DeltaInfo) DeltaBytes ¶
DeltaBytes is the size of the retained pages.
type Options ¶
type Options struct {
Bin string // default "criu", found as helper.Resolve finds it
// Wrap is a command a restore runs through, given criu and its
// arguments after its own: for a restore that needs mounts of its
// own (the runc backend's /sys bind). It must exec criu in place,
// so the pid stays criu's.
Wrap []string
// Commander runs criu. Nil runs the binary Bin names, so a test can
// stand in for criu without a process.
Commander Commander
}
Options select the binary and the flags common to every call.
func (Options) Available ¶
Available reports whether criu is installed, at least MinVersion, and `criu check` passes.
func (Options) DumpWith ¶
func (o Options) DumpWith(ctx context.Context, pid int, dir string, after After, extra []string) error
DumpWith checkpoints the tree rooted at pid into dir, and after says what becomes of the tree once the images are written. extra holds more criu arguments, for example "--external", "unix[<inode>]" to allow a socket whose peer lives outside the dumped tree (the zygote's control channel at build time).
func (Options) RestoreWith ¶
func (o Options) RestoreWith(ctx context.Context, dir string, cgroupFD int, extra []string, files []*os.File) (*Restored, error)
RestoreWith starts `criu restore` for the images in dir, inside the cgroup whose directory descriptor is cgroupFD (so the restored tree lands in that leaf), and returns once the tree is running or ctx ends. extra holds more criu arguments (external mounts, a new root filesystem for trees dumped inside a container). files[i] becomes criu's descriptor 3+i, which an "--inherit-fd fd[3+i]:<key>" in extra hands to the restored tree.
type Pagemap ¶
type Pagemap struct {
Path string
Header []byte // the 8 magic bytes, preserved verbatim
PagesID uint32
Entries []PagemapEntry
}
Pagemap is one task's memory map.
func ReadPagemap ¶
ReadPagemap parses pagemap-<pid>.img.
type PagemapEntry ¶
PagemapEntry is one run of pages.
type Parent ¶
type Parent struct {
Dir string
// contains filtered or unexported fields
}
Parent is a loaded zygote checkpoint: its pages files memory-mapped and every present page indexed by address, plus a hash of the pages files that identifies it. Load once per checkpoint and reuse; Close unmaps.
func LoadParent ¶
LoadParent maps a checkpoint directory. Memory cost is the index (a few tens of bytes per page); the pages stay in the page cache.
Source Files