Module host_input 

The host identity of a file a guest opened.

Hermit maps each host inode it sees to a deterministic one in the order it first sees them, so a host file that is REPLACED while a run is going (a package manager rewriting /etc/ld.so.cache between the opens of two guest processes, for example) gives that run one more inode than the other run, and every later inode number differs. hermit run --verify then reports a divergence that the guest did not cause. Each verification run therefore records one HostInputRecord per host file the guest opens. Detcore reports each open to its global state (crate::config::Config::record_host_inputs), which writes the run’s records to a side file (crate::config::Config::host_input_log) when the run ends, never part of the compared log. On a divergence the two runs’ records are compared to name such a change.

A run that writes a record meant to be reproduced later (a --record-preemptions-to schedule, or a --summary-json summary) also keeps a HostInputSet: each host file the guest opened, with the identity its first open found, and a digest of the set. A run that replays such a schedule compares the files it opens against the set and reports each one that changed (HostInputChange): Hermit does not make a changing filesystem deterministic, so a replay that reads different host files can diverge, and it then says why.

Structs

HostFileIdentity

The host’s identity for a file at the moment it was opened or captured.

HostInput

One host file in a HostInputSet: its path and the identity the run’s first open of that path found.

HostInputChange

A host file that differs between a recorded run and the run that reproduces it (host_input_changed): other bytes, or, where either run could not hash them, another identity (replaced, or modified in size or time). The reproduction may read other bytes than the recorded run did, and diverge where it does.

HostInputLogEnd

The last line of a complete host-input log: how many records, of both kinds, precede it. A log without it, or with another count, is incomplete.

HostInputRecord

One host file a guest opened: the path it named, made absolute against its working directory or directory descriptor, the host identity of the file the open reached (or the captured origin of an authenticated launcher-owned snapshot), and the open itself, as the thread (dtid) and that thread’s syscall number (syscall, the finish syscall #N of the run’s log) that made it. A path that is not UTF-8 is recorded lossily.

HostInputSet

The host files one run’s guest opened, for a later run that reproduces it to compare against: one HostInput per path, sorted by path, and a digest of the set, so that two runs can be compared by one string. The digest is the SHA-256 (lowercase hex) of one line per file: its path and the SHA-256 of its bytes where they were hashed, otherwise its identity. So it agrees with host_input_changed: two runs that read the same bytes at the same paths get the same digest whatever the files’ inodes and times. A path is left out when it is not absolute, names a kernel object (is_kernel_object, also by the descriptor’s own path, HostInputRecord::kernel_object), or was rebound by the guest itself (guest_rebound): those can change between runs without the host’s files changing.

HostInputSnapshot

A private copy of a captured host input. The launcher supplies this only for a copy it owns: physical authenticates the object the guest opened, while origin names the object whose bytes were captured. Aliases of the copy have the same provenance; an unrelated object at its usual guest path does not. This is host-only state, never a guest or record-format payload.

HostMutationRecord

A path the guest itself rebound in its file namespace during the run: renamed to or from, linked, unlinked, made as a symlink, node or directory, removed as a directory, or opened to create (see crate::config::Config::record_host_inputs). Made absolute as an open’s path is. A host file whose path, or a directory above it, the guest rebound may have been replaced by the guest, so such a change is never named as a host input change.

Constants

HOST_INPUT_CHANGED_SINCE_RECORDING_MARKER

The marker that begins the stderr line a reproducing run prints for each HostInputChange. A harness greps for it, as for HERMIT_SKID_OVERSHOOT; keep it stable.

HOST_INPUT_CONTENT_LIMIT

The largest file whose bytes Detcore hashes for a HostInput: a larger one is compared by its identity alone, so that a guest that opens big data files does not pay to read them twice.

Functions

guest_rebound

Whether the guest may have rebound path, or a directory above it, in its file namespace: one of mutated (HostMutationRecord paths) is path or an ancestor of it. Detcore reports /, the ancestor of every absolute path, for a change whose path it could not establish. A path that is not absolute cannot be matched against those changes at all, so it counts as rebound too.

host_input_changed

Whether now shows a different file than recorded, for the same path: other bytes, where both runs hashed them, and otherwise another identity. A file rewritten with the same bytes (as a package manager’s ldconfig does) is therefore not a change where its content was hashed.

is_kernel_object

Whether path names a kernel object under /proc, /sys or /dev rather than a host input file: its metadata is not file content, and Hermit virtualizes those trees separately.