hermit-run 0.4.0

Hermit: a deterministic Linux execution engine for reproducible runs, record and replay, and concurrency-race search.
Documentation
/*
 * Copyright (c) Meta Platforms, Inc. and affiliates.
 * All rights reserved.
 *
 * This source code is licensed under the BSD-style license found in the
 * LICENSE file in the root directory of this source tree.
 */

//! Report the proc mount's capabilities after container setup.

use nix::sys::statvfs::FsFlags;
use nix::sys::statvfs::statvfs;
use reverie::Errno;
use reverie::Pid;

/// One diagnostic per container launch, outside the captured guest output.
pub const READONLY_WARNING: &str =
    "hermit: warning: /proc is mounted read-only; guest writes to procfs may fail with EROFS.\n";

fn write_warning(warning: &str) {
    // This also runs in the namespace-only pre_exec callback. Avoid allocation,
    // stdio locks, and formatting after fork. Diagnostics are best effort if
    // stderr is closed; a warning must not turn a successful setup into an error.
    // Reverie restores SIGPIPE's default disposition before invoking us. Block
    // it for this write and consume only a signal newly generated by our EPIPE,
    // preserving both the caller's mask and any previously pending signal.
    // SAFETY: the signal sets are initialized before use. These Linux signal
    // operations use no allocation or userspace locks.
    let (blocked, original, pending) = unsafe {
        let mut blocked = std::mem::zeroed::<libc::sigset_t>();
        let mut original = std::mem::zeroed::<libc::sigset_t>();
        let mut pending = std::mem::zeroed::<libc::sigset_t>();
        libc::sigemptyset(&mut blocked);
        libc::sigaddset(&mut blocked, libc::SIGPIPE);
        if libc::sigprocmask(libc::SIG_BLOCK, &blocked, &mut original) == -1 {
            return;
        }
        if libc::sigpending(&mut pending) == -1 {
            libc::sigprocmask(libc::SIG_SETMASK, &original, std::ptr::null_mut());
            return;
        }
        (blocked, original, pending)
    };
    let mut broken_pipe = false;
    let mut remaining = warning.as_bytes();
    while !remaining.is_empty() {
        // SAFETY: the message bytes remain valid for the complete write.
        let written = unsafe {
            libc::write(
                libc::STDERR_FILENO,
                remaining.as_ptr().cast(),
                remaining.len(),
            )
        };
        if written > 0 {
            remaining = &remaining[written as usize..];
        } else if written == -1 && Errno::last() == Errno::EINTR {
            continue;
        } else {
            broken_pipe = written == -1 && Errno::last() == Errno::EPIPE;
            break;
        }
    }
    // SAFETY: consume only our new SIGPIPE without waiting, then restore the
    // exact mask inherited by this thread before continuing guest startup.
    unsafe {
        if broken_pipe && libc::sigismember(&pending, libc::SIGPIPE) == 0 {
            let timeout = libc::timespec {
                tv_sec: 0,
                tv_nsec: 0,
            };
            while libc::sigtimedwait(&blocked, std::ptr::null_mut(), &timeout) == -1
                && Errno::last() == Errno::EINTR
            {}
        }
        libc::sigprocmask(libc::SIG_SETMASK, &original, std::ptr::null_mut());
    }
}

/// Inspect the completed container; safe to call in a pre_exec callback.
pub fn warn_if_readonly_proc() {
    let mut stats = std::mem::MaybeUninit::<libc::statfs64>::uninit();
    // SAFETY: the pathname is NUL-terminated and statfs64 initializes the buffer
    // on success. Linux statfs64 is a syscall wrapper, unlike libc statvfs
    // compatibility paths that may allocate or lock between fork and exec.
    if unsafe { libc::statfs64(c"/proc".as_ptr(), stats.as_mut_ptr()) } == -1 {
        write_warning("hermit: warning: could not determine the /proc mount mode.\n");
    } else if unsafe { stats.assume_init().f_flags } & libc::ST_RDONLY as libc::c_long != 0 {
        write_warning(READONLY_WARNING);
    }
}

/// The tracer is stopped after setup, so inspect its actual root rather than
/// the controller's proc mount, which can have different capabilities.
pub(crate) fn guest_proc_readonly(pid: Pid) -> Option<bool> {
    match statvfs(format!("/proc/{pid}/root/proc").as_str()) {
        Ok(stats) => Some(stats.flags().contains(FsFlags::ST_RDONLY)),
        Err(error) => {
            write_warning(&format!(
                "hermit: warning: could not determine the guest /proc mount mode: {error}\n"
            ));
            None
        }
    }
}

pub(crate) fn report_proc_mode(recorded: Option<bool>, actual: Option<bool>) {
    if let (Some(recorded), Some(actual)) = (recorded, actual)
        && recorded != actual
    {
        let mode = |readonly| if readonly { "read-only" } else { "read-write" };
        write_warning(&format!(
            "hermit: warning: /proc mount mode differs: recording was {}, replay is {}; \
             guest procfs writes may behave differently.\n",
            mode(recorded),
            mode(actual)
        ));
    } else if actual == Some(true) {
        write_warning(READONLY_WARNING);
    }
}

#[cfg(test)]
mod tests {
    use std::os::fd::AsRawFd;
    use std::os::fd::FromRawFd;
    use std::os::fd::OwnedFd;

    use reverie::process::Container;

    #[test]
    fn readonly_proc_warning_survives_closed_stderr() {
        let mut descriptors = [-1; 2];
        // SAFETY: pipe2 initializes two distinct owned descriptors on success.
        assert_eq!(
            unsafe { libc::pipe2(descriptors.as_mut_ptr(), libc::O_CLOEXEC) },
            0,
            "create stderr pipe: {}",
            std::io::Error::last_os_error()
        );
        // SAFETY: ownership of each fresh descriptor is transferred once.
        let (reader, writer) = unsafe {
            (
                OwnedFd::from_raw_fd(descriptors[0]),
                OwnedFd::from_raw_fd(descriptors[1]),
            )
        };
        drop(reader);

        // Do not create a PID namespace: its init process is protected from an
        // unhandled SIGPIPE and would let an unsafe warning writer pass.
        let observation = Container::new()
            .run(|| {
                // SAFETY: all descriptor and signal changes affect only this
                // child. The signal sets are initialized before use.
                unsafe {
                    let mut action = std::mem::zeroed::<libc::sigaction>();
                    action.sa_sigaction = libc::SIG_DFL;
                    libc::sigemptyset(&mut action.sa_mask);
                    let mut signals = std::mem::zeroed::<libc::sigset_t>();
                    libc::sigemptyset(&mut signals);
                    libc::sigaddset(&mut signals, libc::SIGPIPE);
                    if libc::dup2(writer.as_raw_fd(), libc::STDERR_FILENO) == -1
                        || libc::sigaction(libc::SIGPIPE, &action, std::ptr::null_mut()) == -1
                        || libc::sigprocmask(libc::SIG_UNBLOCK, &signals, std::ptr::null_mut())
                            == -1
                    {
                        return Err(*libc::__errno_location());
                    }

                    super::report_proc_mode(None, Some(true));

                    let mut mask = std::mem::zeroed::<libc::sigset_t>();
                    let mut pending = std::mem::zeroed::<libc::sigset_t>();
                    if libc::sigprocmask(libc::SIG_BLOCK, std::ptr::null(), &mut mask) == -1
                        || libc::sigpending(&mut pending) == -1
                        || libc::sigaction(libc::SIGPIPE, std::ptr::null(), &mut action) == -1
                    {
                        return Err(*libc::__errno_location());
                    }
                    Ok((
                        libc::getpid(),
                        action.sa_sigaction == libc::SIG_DFL,
                        libc::sigismember(&mask, libc::SIGPIPE) == 0,
                        libc::sigismember(&pending, libc::SIGPIPE) == 0,
                    ))
                }
            })
            .expect("the warning must not terminate the child with SIGPIPE")
            .expect("configure and inspect child stderr and signal state");
        assert!(
            observation.0 > 1,
            "the child must not be PID namespace init"
        );
        assert_eq!(
            (observation.1, observation.2, observation.3),
            (true, true, true),
            "the warning must preserve default/unblocked SIGPIPE and consume its own pending signal"
        );
    }
}