Skip to main content

net_io/
inherit.rs

1//! Inherited listeners: systemd socket activation and FastCGI's descriptor 0.
2//!
3//! Inherited descriptors are verified before net-io takes them, taken once per
4//! process (a second call gets what is left, never a second owner of the same
5//! number), and set close-on-exec. The `LISTEN_*` variables are left in the
6//! environment (decision D-036): the pid check already keeps a child from
7//! using them. A program that re-executes itself in place (`execve` without
8//! `fork`, so the pid stays) keeps them too; there a descriptor with
9//! close-on-exec set marks the variables as stale, because a descriptor that
10//! crossed `execve` never has the flag. Such a program should still clear
11//! `LISTEN_PID` before `execve`, or place the listeners at 3 again.
12
13use std::fmt;
14use std::io;
15use std::sync::{Mutex, PoisonError};
16
17use crate::handoff::ListenerHandle;
18#[cfg(unix)]
19use crate::sys::KindError;
20
21/// Why inherited descriptors were refused.
22///
23/// ```
24/// assert_eq!(net_io::InheritError::BadCount.to_string(), "LISTEN_FDS is not a valid count");
25/// ```
26#[non_exhaustive]
27#[derive(Debug)]
28pub enum InheritError {
29    /// `LISTEN_FDS` is not a non-negative number.
30    BadCount,
31    /// More descriptors than allowed.
32    TooMany {
33        /// The maximum.
34        max: u32,
35    },
36    /// The descriptor is not a socket.
37    NotASocket {
38        /// The descriptor.
39        fd: i32,
40    },
41    /// The socket is not listening.
42    NotListening {
43        /// The descriptor.
44        fd: i32,
45    },
46    /// The socket's family or type is not one net-io serves.
47    WrongKind {
48        /// The descriptor.
49        fd: i32,
50    },
51    /// `LISTEN_FDNAMES` does not match `LISTEN_FDS`.
52    NamesMismatch,
53    /// `LISTEN_PIDFDID` does not match this process.
54    PidFdMismatch,
55    /// An OS call failed.
56    Os(io::Error),
57}
58
59impl fmt::Display for InheritError {
60    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
61        match self {
62            InheritError::BadCount => f.write_str("LISTEN_FDS is not a valid count"),
63            InheritError::TooMany { max } => write!(f, "more than {max} inherited descriptors"),
64            InheritError::NotASocket { fd } => write!(f, "descriptor {fd} is not a socket"),
65            InheritError::NotListening { fd } => {
66                write!(f, "descriptor {fd} is not a listening socket")
67            }
68            InheritError::WrongKind { fd } => {
69                write!(f, "descriptor {fd} is not a TCP or Unix stream socket")
70            }
71            InheritError::NamesMismatch => f.write_str("LISTEN_FDNAMES does not match LISTEN_FDS"),
72            InheritError::PidFdMismatch => {
73                f.write_str("LISTEN_PIDFDID does not match this process")
74            }
75            InheritError::Os(e) => write!(f, "{e}"),
76        }
77    }
78}
79
80impl std::error::Error for InheritError {
81    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
82        match self {
83            InheritError::Os(e) => Some(e),
84            _ => None,
85        }
86    }
87}
88
89/// A listener systemd passed to this process, with its `LISTEN_FDNAMES` name.
90#[derive(Debug)]
91pub struct InheritedListener {
92    /// Its name from `LISTEN_FDNAMES`, when systemd gave names.
93    pub name: Option<String>,
94    /// The socket.
95    pub handle: ListenerHandle,
96}
97
98/// The most descriptors systemd may pass (FR-42).
99#[cfg(unix)]
100const MAX_FDS: u32 = 64;
101/// systemd's first passed descriptor (`SD_LISTEN_FDS_START`).
102#[cfg(unix)]
103const FIRST_FD: i32 = 3;
104
105/// What systemd passed, taken once per process.
106struct Taken {
107    read: bool,
108    left: Vec<InheritedListener>,
109}
110
111static SYSTEMD: Mutex<Taken> = Mutex::new(Taken {
112    read: false,
113    left: Vec::new(),
114});
115
116/// The listeners systemd passed to this process (socket activation). Reads
117/// `LISTEN_PID` (it must name this process, otherwise the variables were meant
118/// for another and the list is empty), `LISTEN_PIDFDID` where present (Linux:
119/// must match this process's pidfd), `LISTEN_FDS` (at most 64), and
120/// `LISTEN_FDNAMES`. Every descriptor from 3 is verified (a socket, listening,
121/// TCP or Unix stream, close-on-exec clear) before any is taken. Not started by
122/// systemd, or a descriptor in the range has close-on-exec set (the variables
123/// outlived a re-exec in place): an empty list. A second call returns what
124/// earlier calls (including [`systemd_named`]) left.
125///
126/// # Errors
127///
128/// `BadCount`, `TooMany`, `NamesMismatch`, `PidFdMismatch`, `NotASocket`,
129/// `NotListening`, `WrongKind`, `Os`. Nothing is taken on an error, with one
130/// exception: an OS call that fails while the verified descriptors are being
131/// taken closes all of them, and later calls return an empty list, so no number
132/// is ever taken twice or left open with no owner.
133///
134/// ```no_run
135/// use net_io::{AllowAll, ListenerSpec, ServerBuilder};
136/// let mut builder = ServerBuilder::new();
137/// for inherited in net_io::systemd()? {
138///     builder = builder.listener(ListenerSpec::adopt(inherited.handle));
139/// }
140/// let server = builder.handler(|conn| { conn.send_all(b"hi\n")?; Ok(()) }).gate(AllowAll).build()?;
141/// server.open_door()?;
142/// server.wait_for_stop();
143/// # Ok::<(), Box<dyn std::error::Error>>(())
144/// ```
145pub fn systemd() -> Result<Vec<InheritedListener>, InheritError> {
146    let mut taken = SYSTEMD.lock().unwrap_or_else(PoisonError::into_inner);
147    read_once(&mut taken)?;
148    Ok(std::mem::take(&mut taken.left))
149}
150
151/// The one listener systemd passed under `name` (`LISTEN_FDNAMES`), or `None`.
152/// The others stay for later calls.
153///
154/// # Errors
155///
156/// As [`systemd`].
157pub fn systemd_named(name: &str) -> Result<Option<InheritedListener>, InheritError> {
158    let mut taken = SYSTEMD.lock().unwrap_or_else(PoisonError::into_inner);
159    read_once(&mut taken)?;
160    Ok(taken
161        .left
162        .iter()
163        .position(|l| l.name.as_deref() == Some(name))
164        .map(|i| taken.left.remove(i)))
165}
166
167fn read_once(taken: &mut Taken) -> Result<(), InheritError> {
168    if taken.read {
169        return Ok(());
170    }
171    #[cfg(unix)]
172    {
173        let env = |k: &str| std::env::var(k).ok();
174        // Verification takes nothing, so a failure there may be retried.
175        let plan = plan_systemd(&env, std::process::id(), FIRST_FD)?;
176        // Taking can fail half way and close what it took: never read again.
177        taken.read = true;
178        taken.left = take_systemd(plan)?;
179    }
180    taken.read = true;
181    Ok(())
182}
183
184/// Descriptors verified and ready to take, with their names.
185#[cfg(unix)]
186type Plan = Vec<(i32, Option<String>)>;
187
188/// The systemd protocol over `env`, with descriptors from `first` (3 outside tests).
189#[cfg(all(unix, any(test, fuzzing)))]
190fn from_systemd(
191    env: &dyn Fn(&str) -> Option<String>,
192    pid: u32,
193    first: i32,
194) -> Result<Vec<InheritedListener>, InheritError> {
195    take_systemd(plan_systemd(env, pid, first)?)
196}
197
198/// Reads the variables and verifies every descriptor; takes nothing.
199#[cfg(unix)]
200fn plan_systemd(
201    env: &dyn Fn(&str) -> Option<String>,
202    pid: u32,
203    first: i32,
204) -> Result<Plan, InheritError> {
205    // Not for this process (or not systemd at all): nothing inherited.
206    match env("LISTEN_PID").and_then(|p| p.trim().parse::<u32>().ok()) {
207        Some(p) if p == pid => {}
208        _ => return Ok(Vec::new()),
209    }
210    #[cfg(target_os = "linux")]
211    if let Some(want) = env("LISTEN_PIDFDID") {
212        let want: u64 = want
213            .trim()
214            .parse()
215            .map_err(|_| InheritError::PidFdMismatch)?;
216        if crate::sys::pidfd_inode().map_err(InheritError::Os)? != want {
217            return Err(InheritError::PidFdMismatch);
218        }
219    }
220    let Some(count) = env("LISTEN_FDS") else {
221        return Ok(Vec::new());
222    };
223    let count: u32 = count.trim().parse().map_err(|_| InheritError::BadCount)?;
224    if count > MAX_FDS {
225        return Err(InheritError::TooMany { max: MAX_FDS });
226    }
227    let names: Option<Vec<String>> =
228        env("LISTEN_FDNAMES").map(|n| n.split(':').map(str::to_owned).collect());
229    if names.as_ref().is_some_and(|n| n.len() != count as usize) {
230        return Err(InheritError::NamesMismatch);
231    }
232    let fds: Vec<i32> = (0..count as i32).map(|i| first + i).collect();
233    // A descriptor passed across `execve` has close-on-exec clear. One with it set
234    // belongs to this image: after a re-exec in place (same pid, variables kept)
235    // the numbers were reused, so the variables are stale and nothing is ours.
236    if fds.iter().any(|&fd| crate::sys::close_on_exec(fd)) {
237        return Ok(Vec::new());
238    }
239    // Verify every descriptor before taking any.
240    for &fd in &fds {
241        crate::sys::inherited_kind(fd).map_err(|e| kind_error(e, fd))?;
242    }
243    Ok(fds
244        .into_iter()
245        .enumerate()
246        .map(|(i, fd)| {
247            let name = names
248                .as_ref()
249                .and_then(|n| n.get(i))
250                .filter(|n| !n.is_empty())
251                .cloned();
252            (fd, name)
253        })
254        .collect())
255}
256
257/// Takes the verified descriptors. A failure here (an OS call that fails on a
258/// descriptor just verified) closes every descriptor of the plan: those already
259/// taken, the one that failed, and those not reached yet, which would otherwise stay
260/// open with no owner, since the variables are never read again.
261#[cfg(unix)]
262fn take_systemd(plan: Plan) -> Result<Vec<InheritedListener>, InheritError> {
263    let mut out = Vec::with_capacity(plan.len());
264    let mut plan = plan.into_iter();
265    while let Some((fd, name)) = plan.next() {
266        let taken = crate::sys::claim_inherited(fd)
267            .map_err(InheritError::Os)
268            .and_then(|owned| {
269                ListenerHandle::verified(owned, name.clone()).map_err(|e| kind_error(e, fd))
270            });
271        match taken {
272            Ok(handle) => out.push(InheritedListener { name, handle }),
273            Err(e) => {
274                // Claiming takes ownership before anything can fail, so dropping
275                // the result closes the descriptor either way.
276                for (rest, _) in plan {
277                    drop(crate::sys::claim_inherited(rest));
278                }
279                return Err(e);
280            }
281        }
282    }
283    Ok(out)
284}
285
286/// The fuzz target's entry: `LISTEN_FDS`, `LISTEN_FDNAMES`, and
287/// `LISTEN_PIDFDID` from `data` (split at NUL), descriptors looked for from
288/// 1,000,000 (never open), so nothing real is touched.
289#[cfg(all(fuzzing, unix))]
290pub(crate) fn fuzz_systemd_env(data: &[u8]) {
291    let text = String::from_utf8_lossy(data);
292    let mut parts = text.split('\0');
293    let pid = std::process::id();
294    let (fds, names, pidfd) = (parts.next(), parts.next(), parts.next());
295    let env = |k: &str| match k {
296        "LISTEN_PID" => Some(pid.to_string()),
297        "LISTEN_FDS" => fds.map(str::to_owned),
298        "LISTEN_FDNAMES" => names.map(str::to_owned),
299        "LISTEN_PIDFDID" => pidfd.map(str::to_owned),
300        _ => None,
301    };
302    if let Ok(list) = from_systemd(&env, pid, 1_000_000) {
303        assert!(list.is_empty(), "no descriptor is open up there");
304    }
305}
306
307#[cfg(all(fuzzing, not(unix)))]
308pub(crate) fn fuzz_systemd_env(_data: &[u8]) {}
309
310#[cfg(unix)]
311fn kind_error(e: KindError, fd: i32) -> InheritError {
312    match e {
313        KindError::NotASocket => InheritError::NotASocket { fd },
314        KindError::NotListening => InheritError::NotListening { fd },
315        KindError::WrongKind => InheritError::WrongKind { fd },
316        KindError::Os(e) => InheritError::Os(e),
317    }
318}
319
320#[cfg(unix)]
321static FASTCGI: Mutex<bool> = Mutex::new(false);
322
323/// FastCGI's listening socket (`FCGI_LISTENSOCK_FILENO`, as `mod_fcgid` starts a
324/// FastCGI server): descriptor 0 is taken only if it is a socket, listening,
325/// has no peer, and has close-on-exec clear (it crossed an `execve`); otherwise
326/// `None` (a terminal, a file, a pipe, a connected socket, a socket this image
327/// opened itself). Taken once per process: later calls return `None`.
328///
329/// # Errors
330///
331/// `Os` when an OS call fails unexpectedly.
332///
333/// ```no_run
334/// if let Some(handle) = net_io::fastcgi_listener()? {
335///     println!("started by a FastCGI manager on {}", handle.local());
336/// }
337/// # Ok::<(), net_io::InheritError>(())
338/// ```
339#[cfg(unix)]
340pub fn fastcgi_listener() -> Result<Option<ListenerHandle>, InheritError> {
341    let mut taken = FASTCGI.lock().unwrap_or_else(PoisonError::into_inner);
342    if *taken {
343        return Ok(None);
344    }
345    let got = fastcgi_from(0)?;
346    if got.is_some() {
347        *taken = true;
348    }
349    Ok(got)
350}
351
352#[cfg(unix)]
353fn fastcgi_from(fd: i32) -> Result<Option<ListenerHandle>, InheritError> {
354    // Close-on-exec set: this image's own descriptor, not one a manager passed.
355    if crate::sys::close_on_exec(fd) {
356        return Ok(None);
357    }
358    match crate::sys::inherited_kind(fd) {
359        Ok(_) => {}
360        Err(KindError::Os(e)) => return Err(InheritError::Os(e)),
361        Err(_) => return Ok(None),
362    }
363    // A listener has no peer: `inherited_kind` refused a connected socket (on
364    // macOS by `getpeername`), so descriptor 0 is taken only when it is ours.
365    let owned = crate::sys::claim_inherited(fd).map_err(InheritError::Os)?;
366    ListenerHandle::verified(owned, None)
367        .map(Some)
368        .map_err(|e| kind_error(e, fd))
369}
370
371#[cfg(all(test, unix))]
372mod tests {
373    use super::*;
374    use std::collections::HashMap;
375    use std::os::fd::AsFd;
376
377    fn env(vars: &[(&str, &str)]) -> impl Fn(&str) -> Option<String> {
378        let map: HashMap<String, String> = vars
379            .iter()
380            .map(|(k, v)| ((*k).to_owned(), (*v).to_owned()))
381            .collect();
382        move |k| map.get(k).cloned()
383    }
384
385    /// Places listeners at `base`, `base + 1`, ... like systemd at 3.
386    fn place(base: i32, n: usize) -> Vec<std::net::TcpListener> {
387        (0..n)
388            .map(|i| {
389                let l = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
390                crate::sys::dup_to(l.as_fd(), base + i as i32).unwrap();
391                l
392            })
393            .collect()
394    }
395
396    #[test]
397    fn test_systemd_protocol() {
398        let me = std::process::id();
399        let pid = me.to_string();
400        // Edge cases 95 and 97: nothing for us.
401        assert!(from_systemd(&env(&[]), me, 900).unwrap().is_empty());
402        assert!(
403            from_systemd(&env(&[("LISTEN_PID", "1"), ("LISTEN_FDS", "1")]), me, 900)
404                .unwrap()
405                .is_empty()
406        );
407        assert!(
408            from_systemd(&env(&[("LISTEN_PID", &pid), ("LISTEN_FDS", "0")]), me, 900)
409                .unwrap()
410                .is_empty()
411        );
412        // Edge case 96.
413        for bad in ["x", "-1", ""] {
414            assert!(matches!(
415                from_systemd(&env(&[("LISTEN_PID", &pid), ("LISTEN_FDS", bad)]), me, 900),
416                Err(InheritError::BadCount)
417            ));
418        }
419        assert!(matches!(
420            from_systemd(&env(&[("LISTEN_PID", &pid), ("LISTEN_FDS", "65")]), me, 900),
421            Err(InheritError::TooMany { max: 64 })
422        ));
423        // Edge case 98.
424        assert!(matches!(
425            from_systemd(
426                &env(&[
427                    ("LISTEN_PID", &pid),
428                    ("LISTEN_FDS", "2"),
429                    ("LISTEN_FDNAMES", "a")
430                ]),
431                me,
432                900
433            ),
434            Err(InheritError::NamesMismatch)
435        ));
436        // Edge case 99: a closed number and a regular file.
437        assert!(matches!(
438            from_systemd(&env(&[("LISTEN_PID", &pid), ("LISTEN_FDS", "1")]), me, 990),
439            Err(InheritError::NotASocket { fd: 990 })
440        ));
441        let file = std::fs::File::open("/dev/null").unwrap();
442        crate::sys::dup_to(file.as_fd(), 991).unwrap();
443        assert!(matches!(
444            from_systemd(&env(&[("LISTEN_PID", &pid), ("LISTEN_FDS", "1")]), me, 991),
445            Err(InheritError::NotASocket { fd: 991 })
446        ));
447        crate::sys::close_number(991);
448    }
449
450    #[test]
451    fn test_systemd_takes_verified_listeners_with_names() {
452        let me = std::process::id();
453        let pid = me.to_string();
454        let ls = place(910, 2);
455        let got = from_systemd(
456            &env(&[
457                ("LISTEN_PID", &pid),
458                ("LISTEN_FDS", "2"),
459                ("LISTEN_FDNAMES", "web:"),
460            ]),
461            me,
462            910,
463        )
464        .unwrap();
465        assert_eq!(got.len(), 2);
466        assert_eq!(got[0].name.as_deref(), Some("web"));
467        assert_eq!(got[1].name, None, "an empty name is no name");
468        assert_eq!(
469            got[0].handle.local().socket_addr(),
470            Some(ls[0].local_addr().unwrap())
471        );
472        // Edge case 100: a connected socket is refused, and nothing is taken.
473        let l = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
474        let c = std::net::TcpStream::connect(l.local_addr().unwrap()).unwrap();
475        crate::sys::dup_to(c.as_fd(), 920).unwrap();
476        assert!(matches!(
477            from_systemd(&env(&[("LISTEN_PID", &pid), ("LISTEN_FDS", "1")]), me, 920),
478            Err(InheritError::NotListening { fd: 920 })
479        ));
480        crate::sys::close_number(920);
481    }
482
483    #[test]
484    fn test_fastcgi_descriptor_checks() {
485        // Edge case 101: a file, a connected socket: None; a listener: taken.
486        let file = std::fs::File::open("/dev/null").unwrap();
487        crate::sys::dup_to(file.as_fd(), 930).unwrap();
488        assert!(fastcgi_from(930).unwrap().is_none());
489        crate::sys::close_number(930);
490        let l = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
491        let c = std::net::TcpStream::connect(l.local_addr().unwrap()).unwrap();
492        crate::sys::dup_to(c.as_fd(), 931).unwrap();
493        assert!(fastcgi_from(931).unwrap().is_none());
494        crate::sys::close_number(931);
495        crate::sys::dup_to(l.as_fd(), 932).unwrap();
496        let h = fastcgi_from(932).unwrap().unwrap();
497        assert_eq!(h.local().socket_addr(), Some(l.local_addr().unwrap()));
498        assert!(fastcgi_from(-1).unwrap().is_none());
499    }
500
501    /// A descriptor with close-on-exec set did not cross an `execve`, so it is
502    /// not inherited: after an in-place re-exec that kept `LISTEN_*`, the
503    /// numbers belong to the new image.
504    #[test]
505    fn test_close_on_exec_descriptors_are_not_inherited() {
506        use std::os::fd::IntoRawFd;
507        let me = std::process::id();
508        let pid = me.to_string();
509        let _ls = place(940, 2);
510        // Descriptor 941 is the new image's own: close-on-exec, as std sets it.
511        let own = crate::sys::claim_inherited(941).unwrap().into_raw_fd();
512        assert_eq!(own, 941);
513        let got =
514            from_systemd(&env(&[("LISTEN_PID", &pid), ("LISTEN_FDS", "2")]), me, 940).unwrap();
515        assert!(got.is_empty(), "stale variables: nothing inherited");
516        // Neither number was taken: both are still open.
517        assert!(crate::sys::inherited_kind(940).is_ok());
518        assert!(crate::sys::inherited_kind(941).is_ok());
519        assert!(fastcgi_from(941).unwrap().is_none());
520        assert!(crate::sys::inherited_kind(941).is_ok());
521        crate::sys::close_number(940);
522        crate::sys::close_number(941);
523    }
524
525    /// A take that fails part way closes every descriptor it was given, those
526    /// after the failure too: none is left open with no owner.
527    #[test]
528    fn test_failed_take_leaves_no_descriptor_open() {
529        let first = place(960, 1);
530        let file = std::fs::File::open("/dev/null").unwrap();
531        crate::sys::dup_to(file.as_fd(), 961).unwrap();
532        let _after = place(962, 1);
533        let plan = vec![(960, None), (961, None), (962, None)];
534        assert!(take_systemd(plan).is_err(), "961 is not a socket");
535        for fd in 960..=962 {
536            assert!(!crate::sys::is_open(fd), "descriptor {fd} is still open");
537        }
538        drop(first);
539    }
540}