1use std::fmt;
14use std::io;
15use std::sync::{Mutex, PoisonError};
16
17use crate::handoff::ListenerHandle;
18#[cfg(unix)]
19use crate::sys::KindError;
20
21#[non_exhaustive]
27#[derive(Debug)]
28pub enum InheritError {
29 BadCount,
31 TooMany {
33 max: u32,
35 },
36 NotASocket {
38 fd: i32,
40 },
41 NotListening {
43 fd: i32,
45 },
46 WrongKind {
48 fd: i32,
50 },
51 NamesMismatch,
53 PidFdMismatch,
55 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#[derive(Debug)]
91pub struct InheritedListener {
92 pub name: Option<String>,
94 pub handle: ListenerHandle,
96}
97
98#[cfg(unix)]
100const MAX_FDS: u32 = 64;
101#[cfg(unix)]
103const FIRST_FD: i32 = 3;
104
105struct 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
116pub 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
151pub 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 let plan = plan_systemd(&env, std::process::id(), FIRST_FD)?;
176 taken.read = true;
178 taken.left = take_systemd(plan)?;
179 }
180 taken.read = true;
181 Ok(())
182}
183
184#[cfg(unix)]
186type Plan = Vec<(i32, Option<String>)>;
187
188#[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#[cfg(unix)]
200fn plan_systemd(
201 env: &dyn Fn(&str) -> Option<String>,
202 pid: u32,
203 first: i32,
204) -> Result<Plan, InheritError> {
205 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 if fds.iter().any(|&fd| crate::sys::close_on_exec(fd)) {
237 return Ok(Vec::new());
238 }
239 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#[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 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#[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#[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 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 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 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 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 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 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 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 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 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 #[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 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 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 #[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}