cmdext: Add pass_systemd_fds() for socket activation fd passing

It's a bit too complicated to use the systemd socket protocol,
let's make it simpler.

Assisted-by: OpenCode (Claude claude-opus-4-6)
Signed-off-by: Colin Walters <walters@verbum.org>

Author: cgwalters

src/cmdext.rs

@@ -4,17 +4,23 @@
 //!
 //! - File descriptor passing
 //! - Changing to a file-descriptor relative directory
+//! - Systemd socket activation fd passing
 
 use cap_std::fs::Dir;
 use cap_std::io_lifetimes;
 use cap_tempfile::cap_std;
 use io_lifetimes::OwnedFd;
 use rustix::fd::{AsFd, FromRawFd, IntoRawFd};
 use rustix::io::FdFlags;
+use std::ffi::CString;
 use std::os::fd::AsRawFd;
 use std::os::unix::process::CommandExt;
 use std::sync::Arc;
 
+/// The file descriptor number at which systemd passes the first socket.
+/// See `sd_listen_fds(3)`.
+const SD_LISTEN_FDS_START: i32 = 3;
+
 /// Extension trait for [`std::process::Command`].
 ///
 /// [`cap_std::fs::Dir`]: https://docs.rs/cap-std/latest/cap_std/fs/struct.Dir.html
@@ -25,6 +31,24 @@ pub trait CapStdExtCommandExt {
     /// Use the given directory as the current working directory for the process.
     fn cwd_dir(&mut self, dir: Dir) -> &mut Self;
 
+    /// Set up the [systemd socket activation][sd_listen_fds] environment for
+    /// the child process.
+    ///
+    /// Each `(fd, name)` pair is placed at consecutive file descriptor numbers
+    /// starting from `SD_LISTEN_FDS_START` (3), and the environment variables
+    /// `LISTEN_PID`, `LISTEN_FDS`, and `LISTEN_FDNAMES` are set accordingly
+    /// inside the child (via `pre_exec`).
+    ///
+    /// Note that `LISTEN_PID` must reflect the child's actual PID, so it
+    /// cannot be set with [`Command::env`] — it is written directly with
+    /// `setenv(3)` in the forked child before exec.
+    ///
+    /// [sd_listen_fds]: https://www.freedesktop.org/software/systemd/man/latest/sd_listen_fds.html
+    fn pass_systemd_fds<'a>(
+        &mut self,
+        fds: impl IntoIterator<Item = (Arc<OwnedFd>, &'a str)>,
+    ) -> &mut Self;
+
     /// On Linux, arrange for [`SIGTERM`] to be delivered to the child if the
     /// parent *thread* exits. This helps avoid leaking child processes if
     /// the parent crashes for example.
@@ -39,6 +63,22 @@ pub trait CapStdExtCommandExt {
     fn lifecycle_bind_to_parent_thread(&mut self) -> &mut Self;
 }
 
+/// Wrapper around `libc::setenv` that checks the return value.
+///
+/// # Safety
+///
+/// Must only be called in a single-threaded context (e.g. after `fork()`
+/// and before `exec()`).
+#[allow(unsafe_code)]
+unsafe fn check_setenv(key: *const i8, val: *const i8) -> std::io::Result<()> {
+    // SAFETY: Caller guarantees we are in a single-threaded context
+    // with valid nul-terminated C strings.
+    if unsafe { libc::setenv(key, val, 1) } != 0 {
+        return Err(std::io::Error::last_os_error());
+    }
+    Ok(())
+}
+
 #[allow(unsafe_code)]
 impl CapStdExtCommandExt for std::process::Command {
     fn take_fd_n(&mut self, fd: Arc<OwnedFd>, target: i32) -> &mut Self {
@@ -62,6 +102,49 @@ impl CapStdExtCommandExt for std::process::Command {
         self
     }
 
+    fn pass_systemd_fds<'a>(
+        &mut self,
+        fds: impl IntoIterator<Item = (Arc<OwnedFd>, &'a str)>,
+    ) -> &mut Self {
+        let mut n_fds: i32 = 0;
+        let mut names = Vec::new();
+        for (fd, name) in fds {
+            assert!(
+                !name.contains('\0') && !name.contains(':'),
+                "systemd fd name must not contain NUL or ':'"
+            );
+            let target = SD_LISTEN_FDS_START
+                .checked_add(n_fds)
+                .expect("too many fds");
+            self.take_fd_n(fd, target);
+            names.push(name.to_owned());
+            n_fds = n_fds.checked_add(1).expect("too many fds");
+        }
+
+        // Build the env values now (owned), then move them into the pre_exec
+        // closure. We cannot use Command::env() because it causes Rust's
+        // Command to build an envp array that replaces environ, which would
+        // clobber the setenv calls we make in pre_exec for LISTEN_PID.
+        let fd_count = CString::new(n_fds.to_string()).unwrap();
+        // SAFETY: We validated that no name contains NUL above.
+        let fd_names = CString::new(names.join(":")).unwrap();
+
+        unsafe {
+            self.pre_exec(move || {
+                let pid = rustix::process::getpid();
+                let pid_dec = rustix::path::DecInt::new(pid.as_raw_nonzero().get());
+                // SAFETY: After fork() and before exec(), the child is
+                // single-threaded, so setenv (which is not thread-safe) is
+                // safe to call here.
+                check_setenv(c"LISTEN_PID".as_ptr(), pid_dec.as_c_str().as_ptr())?;
+                check_setenv(c"LISTEN_FDS".as_ptr(), fd_count.as_ptr())?;
+                check_setenv(c"LISTEN_FDNAMES".as_ptr(), fd_names.as_ptr())?;
+                Ok(())
+            });
+        }
+        self
+    }
+
     fn cwd_dir(&mut self, dir: Dir) -> &mut Self {
         unsafe {
             self.pre_exec(move || {

tests/it/main.rs

@@ -860,3 +860,78 @@ fn test_lifecycle_bind_to_parent_thread() -> Result<()> {
 
     Ok(())
 }
+
+#[test]
+#[cfg(not(windows))]
+fn test_pass_systemd_fds() -> Result<()> {
+    // Verify the child sees the correct LISTEN_* env vars and can read from the fd.
+    let (r, w) = rustix::pipe::pipe()?;
+    let r = Arc::new(r);
+    let mut w: cap_std::fs::File = w.into();
+    write!(w, "sd-activate-test")?;
+    drop(w);
+
+    // The child: verify LISTEN_PID matches $$, print the other vars, read fd 3.
+    let script = r#"
+test "$LISTEN_PID" = "$$" || { echo "LISTEN_PID=$LISTEN_PID but $$=$$" >&2; exit 1; }
+printf '%s\n' "$LISTEN_FDS" "$LISTEN_FDNAMES"
+cat <&3
+"#;
+    let mut c = Command::new("/bin/bash");
+    c.arg("-c").arg(script);
+    c.stdout(std::process::Stdio::piped());
+    c.pass_systemd_fds([(r, "myproto")]);
+    let out = c.output()?;
+    assert!(
+        out.status.success(),
+        "child failed: {}",
+        String::from_utf8_lossy(&out.stderr)
+    );
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    let lines: Vec<&str> = stdout.lines().collect();
+    assert_eq!(lines.len(), 3, "unexpected output: {stdout}");
+    assert_eq!(lines[0], "1");
+    assert_eq!(lines[1], "myproto");
+    assert_eq!(lines[2], "sd-activate-test");
+
+    Ok(())
+}
+
+#[test]
+#[cfg(not(windows))]
+fn test_pass_systemd_fds_multi() -> Result<()> {
+    // Test passing multiple fds with distinct names.
+    let (r1, w1) = rustix::pipe::pipe()?;
+    let (r2, w2) = rustix::pipe::pipe()?;
+    let r1 = Arc::new(r1);
+    let r2 = Arc::new(r2);
+    let mut w1: cap_std::fs::File = w1.into();
+    let mut w2: cap_std::fs::File = w2.into();
+    write!(w1, "first")?;
+    write!(w2, "second")?;
+    drop(w1);
+    drop(w2);
+
+    // fd 3 = first pipe, fd 4 = second pipe
+    let script = r#"
+printf '%s\n' "$LISTEN_FDS" "$LISTEN_FDNAMES"
+cat <&3
+printf '\n'
+cat <&4
+"#;
+    let mut c = Command::new("/bin/bash");
+    c.arg("-c").arg(script);
+    c.stdout(std::process::Stdio::piped());
+    c.pass_systemd_fds([(r1, "alpha"), (r2, "beta")]);
+    let out = c.output()?;
+    assert!(out.status.success(), "child failed: {:?}", out);
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    let lines: Vec<&str> = stdout.lines().collect();
+    assert_eq!(lines.len(), 4, "unexpected output: {stdout}");
+    assert_eq!(lines[0], "2");
+    assert_eq!(lines[1], "alpha:beta");
+    assert_eq!(lines[2], "first");
+    assert_eq!(lines[3], "second");
+
+    Ok(())
+}