Add YAML configuration model and loader

Config is layered: built-in defaults, then the YAML file, then BFD_* environment variables, then CLI flags. Global defaults live under a 'defaults' mapping; per-peer settings are file-only. Includes config.yaml.dist and ScriptHookSink::with_script_dir so the hooks directory is configurable.
This commit is contained in:
ktims committed 2026-10-22 17:48:59 -07:00
1 parent 0284ee17b1
commit ea56afd2f2
6 files changed
+754 -2

No files matched your search

+620
View File
@@ -0,0 +1,620 @@
//! Daemon configuration: YAML model, layered loading and validation.
//!
//! Layers, lowest to highest precedence: built-in defaults, the YAML file, `BFD_*` environment variables (global
//! settings only), command line (`--bind` replaces, `--peer` adds). Per-peer settings can only come from the file; peers
//! given on the command line use the global defaults.
//!
//! [`Config`] is the editable, serialisable model. [`Config::resolve`] validates it and produces a [`ResolvedConfig`]
//! with all per-peer inheritance applied, which is what the daemon runs from.
use std::{
collections::HashSet,
error::Error,
fmt, fs, io,
net::IpAddr,
path::{Path, PathBuf},
time::Duration,
};
use serde::{de, Deserialize, Deserializer, Serialize};
use crate::bfd::BfdInterval;
pub const DEFAULT_CONFIG_PATH: &str = "/etc/rust-bfd/config.yaml";
pub const DEFAULT_HOOKS_DIR: &str = "/etc/rust-bfd/hooks.d";
pub const ENV_BIND: &str = "BFD_BIND";
pub const ENV_HOOKS_DIR: &str = "BFD_HOOKS_DIR";
pub const ENV_DEFAULTS_DESIRED_MIN_TX: &str = "BFD_DEFAULTS_DESIRED_MIN_TX";
pub const ENV_DEFAULTS_REQUIRED_MIN_RX: &str = "BFD_DEFAULTS_REQUIRED_MIN_RX";
pub const ENV_DEFAULTS_DETECT_MULT: &str = "BFD_DEFAULTS_DETECT_MULT";
#[derive(Debug)]
pub enum ConfigError {
Io {
path: PathBuf,
source: io::Error,
},
Parse {
path: PathBuf,
source: serde_yaml_ng::Error,
},
Env {
var: &'static str,
message: String,
},
Invalid(String),
}
impl fmt::Display for ConfigError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Io { path, source } => {
write!(f, "cannot read config file `{}`: {source}", path.display())
}
Self::Parse { path, source } => {
write!(f, "invalid config file `{}`: {source}", path.display())
}
Self::Env { var, message } => {
write!(f, "invalid environment variable {var}: {message}")
}
Self::Invalid(message) => write!(f, "invalid configuration: {message}"),
}
}
}
impl Error for ConfigError {
fn source(&self) -> Option<&(dyn Error + 'static)> {
match self {
Self::Io { source, .. } => Some(source),
Self::Parse { source, .. } => Some(source),
Self::Env { .. } | Self::Invalid(_) => None,
}
}
}
/// Timer and multiplier settings inherited by every peer that does not override them.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct Defaults {
#[serde(with = "humantime_serde")]
pub desired_min_tx: Duration,
#[serde(with = "humantime_serde")]
pub required_min_rx: Duration,
pub detect_mult: u8,
}
impl Default for Defaults {
fn default() -> Self {
Self {
desired_min_tx: Duration::from_millis(300),
required_min_rx: Duration::from_millis(300),
detect_mult: 3,
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct PeerConfig {
pub address: IpAddr,
#[serde(
default,
skip_serializing_if = "Option::is_none",
with = "humantime_serde"
)]
pub desired_min_tx: Option<Duration>,
#[serde(
default,
skip_serializing_if = "Option::is_none",
with = "humantime_serde"
)]
pub required_min_rx: Option<Duration>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub detect_mult: Option<u8>,
}
impl PeerConfig {
pub fn new(address: IpAddr) -> Self {
Self {
address,
desired_min_tx: None,
required_min_rx: None,
detect_mult: None,
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct Config {
/// Local addresses to bind. Accepts a single address, a list, or a comma-separated string. The daemon currently
/// supports exactly one.
#[serde(deserialize_with = "deserialize_bind")]
pub bind: Vec<IpAddr>,
/// Directory of executable state-change hook scripts.
pub hooks_dir: PathBuf,
pub defaults: Defaults,
pub peers: Vec<PeerConfig>,
}
impl Default for Config {
fn default() -> Self {
Self {
bind: Vec::new(),
hooks_dir: PathBuf::from(DEFAULT_HOOKS_DIR),
defaults: Defaults::default(),
peers: Vec::new(),
}
}
}
fn parse_bind_list(s: &str) -> Result<Vec<IpAddr>, String> {
s.split(|c: char| c == ',' || c.is_whitespace())
.map(str::trim)
.filter(|item| !item.is_empty())
.map(|item| {
item.parse()
.map_err(|e| format!("invalid bind address `{item}`: {e}"))
})
.collect()
}
fn deserialize_bind<'de, D: Deserializer<'de>>(deserializer: D) -> Result<Vec<IpAddr>, D::Error> {
#[derive(Deserialize)]
#[serde(untagged)]
enum OneOrMany {
One(String),
Many(Vec<String>),
}
match OneOrMany::deserialize(deserializer)? {
OneOrMany::One(s) => parse_bind_list(&s).map_err(de::Error::custom),
OneOrMany::Many(items) => items
.iter()
.map(|s| parse_bind_list(s).map_err(de::Error::custom))
.try_fold(Vec::new(), |mut acc, addrs| {
acc.extend(addrs?);
Ok(acc)
}),
}
}
impl Config {
pub fn from_yaml(yaml: &str) -> Result<Self, serde_yaml_ng::Error> {
// An empty (or comment-only) document is a null value, which means "all defaults".
Ok(serde_yaml_ng::from_str::<Option<Self>>(yaml)?.unwrap_or_default())
}
fn from_file(path: &Path) -> Result<Self, ConfigError> {
let yaml = fs::read_to_string(path).map_err(|source| ConfigError::Io {
path: path.to_owned(),
source,
})?;
Self::from_yaml(&yaml).map_err(|source| ConfigError::Parse {
path: path.to_owned(),
source,
})
}
/// Load the config file. An explicit `path` must exist; with `None`, [`DEFAULT_CONFIG_PATH`] is used if present and
/// built-in defaults otherwise.
pub fn load(path: Option<&Path>) -> Result<Self, ConfigError> {
match path {
Some(path) => Self::from_file(path),
None => match Self::from_file(Path::new(DEFAULT_CONFIG_PATH)) {
Err(ConfigError::Io { source, .. }) if source.kind() == io::ErrorKind::NotFound => {
Ok(Self::default())
}
other => other,
},
}
}
/// Override global settings from `BFD_*` variables supplied by `var`. Unset and empty variables are ignored.
pub fn apply_env(&mut self, var: impl Fn(&str) -> Option<String>) -> Result<(), ConfigError> {
let get = |name: &str| var(name).filter(|v| !v.trim().is_empty());
let env_err = |var: &'static str, message: String| ConfigError::Env { var, message };
let parse_duration = |name: &'static str, value: String| {
humantime::parse_duration(value.trim()).map_err(|e| env_err(name, e.to_string()))
};
if let Some(v) = get(ENV_BIND) {
self.bind = parse_bind_list(&v).map_err(|m| env_err(ENV_BIND, m))?;
}
if let Some(v) = get(ENV_HOOKS_DIR) {
self.hooks_dir = PathBuf::from(v);
}
if let Some(v) = get(ENV_DEFAULTS_DESIRED_MIN_TX) {
self.defaults.desired_min_tx = parse_duration(ENV_DEFAULTS_DESIRED_MIN_TX, v)?;
}
if let Some(v) = get(ENV_DEFAULTS_REQUIRED_MIN_RX) {
self.defaults.required_min_rx = parse_duration(ENV_DEFAULTS_REQUIRED_MIN_RX, v)?;
}
if let Some(v) = get(ENV_DEFAULTS_DETECT_MULT) {
self.defaults.detect_mult = v
.trim()
.parse()
.map_err(|e| env_err(ENV_DEFAULTS_DETECT_MULT, format!("{e}")))?;
}
Ok(())
}
/// Apply command line settings: a non-empty `bind` replaces the configured addresses, `peers` are added (with
/// default settings) unless a peer with that address is already configured.
pub fn apply_cli(&mut self, bind: Vec<IpAddr>, peers: impl IntoIterator<Item = IpAddr>) {
if !bind.is_empty() {
self.bind = bind;
}
for address in peers {
if !self.peers.iter().any(|p| p.address == address) {
self.peers.push(PeerConfig::new(address));
}
}
}
/// Validate and apply defaults to each peer.
pub fn resolve(&self) -> Result<ResolvedConfig, ConfigError> {
let invalid = |message: String| ConfigError::Invalid(message);
if self.bind.is_empty() {
return Err(invalid(
"no bind address configured (`bind`, BFD_BIND or --bind)".into(),
));
}
let mut seen = HashSet::new();
if let Some(dup) = self.bind.iter().find(|addr| !seen.insert(**addr)) {
return Err(invalid(format!("duplicate bind address {dup}")));
}
let mut seen = HashSet::new();
let peers = self
.peers
.iter()
.map(|peer| {
if !seen.insert(peer.address) {
return Err(invalid(format!("duplicate peer {}", peer.address)));
}
if !self
.bind
.iter()
.any(|b| b.is_ipv4() == peer.address.is_ipv4())
{
return Err(invalid(format!(
"peer {} has no bind address of the same address family",
peer.address
)));
}
let what = |field: &str| format!("peer {} {field}", peer.address);
let detect_mult = peer.detect_mult.unwrap_or(self.defaults.detect_mult);
if detect_mult == 0 {
return Err(invalid(format!(
"{} must be at least 1",
what("detect_mult")
)));
}
Ok(ResolvedPeer {
address: peer.address,
desired_min_tx: to_interval(
peer.desired_min_tx.unwrap_or(self.defaults.desired_min_tx),
&what("desired_min_tx"),
)?,
required_min_rx: to_interval(
peer.required_min_rx
.unwrap_or(self.defaults.required_min_rx),
&what("required_min_rx"),
)?,
detect_mult,
})
})
.collect::<Result<Vec<_>, _>>()?;
// Validate the defaults even when no peer uses them, so that a bad value is not latent.
let d = &self.defaults;
to_interval(d.desired_min_tx, "defaults.desired_min_tx")?;
to_interval(d.required_min_rx, "defaults.required_min_rx")?;
if d.detect_mult == 0 {
return Err(invalid("defaults.detect_mult must be at least 1".into()));
}
Ok(ResolvedConfig {
bind: self.bind.clone(),
hooks_dir: self.hooks_dir.clone(),
peers,
})
}
}
/// Zero is rejected for both intervals: a zero Required Min RX Interval is legal in RFC 5880 (it asks the peer to
/// stop sending periodic packets) but is not supported here.
fn to_interval(value: Duration, what: &str) -> Result<BfdInterval, ConfigError> {
let micros = value.as_micros();
if micros == 0 {
return Err(ConfigError::Invalid(format!(
"{what} must be greater than zero"
)));
}
u32::try_from(micros)
.map(BfdInterval::from_micros)
.map_err(|_| {
ConfigError::Invalid(format!(
"{what} of {} is too large (maximum is {} microseconds)",
humantime::format_duration(value),
u32::MAX
))
})
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ResolvedConfig {
pub bind: Vec<IpAddr>,
pub hooks_dir: PathBuf,
pub peers: Vec<ResolvedPeer>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ResolvedPeer {
pub address: IpAddr,
pub desired_min_tx: BfdInterval,
pub required_min_rx: BfdInterval,
pub detect_mult: u8,
}
#[cfg(test)]
mod tests {
use std::collections::HashMap;
use super::*;
fn ip(s: &str) -> IpAddr {
s.parse().unwrap()
}
fn env(pairs: &[(&str, &str)]) -> impl Fn(&str) -> Option<String> {
let map: HashMap<String, String> = pairs
.iter()
.map(|(k, v)| (k.to_string(), v.to_string()))
.collect();
move |k| map.get(k).cloned()
}
const FULL: &str = "
bind: 192.0.2.1
hooks_dir: /tmp/hooks
defaults:
desired_min_tx: 500ms
required_min_rx: 250ms
detect_mult: 5
peers:
- address: 192.0.2.2
- address: 192.0.2.3
desired_min_tx: 1s
detect_mult: 4
";
#[test]
fn parses_full_config() {
let config = Config::from_yaml(FULL).unwrap();
assert_eq!(config.bind, vec![ip("192.0.2.1")]);
assert_eq!(config.hooks_dir, PathBuf::from("/tmp/hooks"));
assert_eq!(config.defaults.desired_min_tx, Duration::from_millis(500));
assert_eq!(config.peers.len(), 2);
assert_eq!(config.peers[1].desired_min_tx, Some(Duration::from_secs(1)));
assert_eq!(config.peers[0].detect_mult, None);
}
#[test]
fn empty_and_comment_only_documents_are_defaults() {
assert_eq!(Config::from_yaml("").unwrap(), Config::default());
assert_eq!(Config::from_yaml("# nothing\n").unwrap(), Config::default());
}
#[test]
fn partial_defaults_keep_remaining_builtin_values() {
let config = Config::from_yaml("defaults:\n detect_mult: 7\n").unwrap();
assert_eq!(config.defaults.detect_mult, 7);
assert_eq!(config.defaults.desired_min_tx, Duration::from_millis(300));
}
#[test]
fn peers_inherit_defaults_and_override() {
let resolved = Config::from_yaml(FULL).unwrap().resolve().unwrap();
let (a, b) = (resolved.peers[0], resolved.peers[1]);
assert_eq!(a.desired_min_tx, BfdInterval::from_millis(500));
assert_eq!(a.required_min_rx, BfdInterval::from_millis(250));
assert_eq!(a.detect_mult, 5);
assert_eq!(b.desired_min_tx, BfdInterval::from_secs(1));
assert_eq!(b.required_min_rx, BfdInterval::from_millis(250));
assert_eq!(b.detect_mult, 4);
}
#[test]
fn bind_accepts_scalar_list_and_comma_string() {
for yaml in [
"bind: 192.0.2.1",
"bind: [192.0.2.1]",
"bind: \"192.0.2.1\"",
] {
assert_eq!(Config::from_yaml(yaml).unwrap().bind, vec![ip("192.0.2.1")]);
}
let multi = Config::from_yaml("bind: \"192.0.2.1, 2001:db8::1\"").unwrap();
assert_eq!(multi.bind, vec![ip("192.0.2.1"), ip("2001:db8::1")]);
let list = Config::from_yaml("bind: [192.0.2.1, \"2001:db8::1\"]").unwrap();
assert_eq!(list.bind, multi.bind);
}
#[test]
fn rejects_unknown_fields_and_bad_values() {
assert!(Config::from_yaml("bnid: 192.0.2.1").is_err());
assert!(Config::from_yaml("defaults:\n desired_min_txx: 1s").is_err());
assert!(Config::from_yaml("peers:\n - address: 192.0.2.2\n color: red").is_err());
assert!(Config::from_yaml("bind: not-an-ip").is_err());
assert!(Config::from_yaml("defaults:\n desired_min_tx: soon").is_err());
assert!(Config::from_yaml("peers:\n - detect_mult: 3").is_err());
}
#[test]
fn yaml_roundtrip() {
let config = Config::from_yaml(FULL).unwrap();
let again = Config::from_yaml(&serde_yaml_ng::to_string(&config).unwrap()).unwrap();
assert_eq!(config, again);
}
#[test]
fn env_overrides_globals() {
let mut config = Config::from_yaml(FULL).unwrap();
config
.apply_env(env(&[
(ENV_BIND, "192.0.2.9"),
(ENV_HOOKS_DIR, "/other"),
(ENV_DEFAULTS_DESIRED_MIN_TX, "2s"),
(ENV_DEFAULTS_REQUIRED_MIN_RX, "100ms"),
(ENV_DEFAULTS_DETECT_MULT, "9"),
]))
.unwrap();
assert_eq!(config.bind, vec![ip("192.0.2.9")]);
assert_eq!(config.hooks_dir, PathBuf::from("/other"));
assert_eq!(config.defaults.desired_min_tx, Duration::from_secs(2));
assert_eq!(config.defaults.required_min_rx, Duration::from_millis(100));
assert_eq!(config.defaults.detect_mult, 9);
// Peers are untouched, and an explicit per-peer value still beats an overridden default.
assert_eq!(config.peers, Config::from_yaml(FULL).unwrap().peers);
}
#[test]
fn env_bind_accepts_multiple_addresses() {
for value in [
"192.0.2.1,2001:db8::1",
"192.0.2.1, 2001:db8::1",
"192.0.2.1 2001:db8::1",
] {
let mut config = Config::default();
config.apply_env(env(&[(ENV_BIND, value)])).unwrap();
assert_eq!(
config.bind,
vec![ip("192.0.2.1"), ip("2001:db8::1")],
"{value}"
);
}
}
#[test]
fn dist_config_is_valid() {
let config = Config::from_yaml(include_str!("../config.yaml.dist")).unwrap();
let resolved = config.resolve().unwrap();
assert_eq!(resolved.peers.len(), 1);
assert_eq!(config.defaults, Defaults::default());
assert_eq!(config.hooks_dir, PathBuf::from(DEFAULT_HOOKS_DIR));
}
#[test]
fn env_ignores_empty_and_unrelated_variables() {
let mut config = Config::from_yaml(FULL).unwrap();
config
.apply_env(env(&[
(ENV_BIND, ""),
(ENV_DEFAULTS_DETECT_MULT, " "),
("BFD_PEERS", "192.0.2.99"),
("BFD_PEER", "192.0.2.98"),
("BFD_ADDR", "192.0.2.97"),
]))
.unwrap();
assert_eq!(config, Config::from_yaml(FULL).unwrap());
}
#[test]
fn env_errors_name_the_variable() {
for (var, value) in [
(ENV_BIND, "nope"),
(ENV_DEFAULTS_DESIRED_MIN_TX, "fast"),
(ENV_DEFAULTS_DETECT_MULT, "-1"),
(ENV_DEFAULTS_DETECT_MULT, "300"),
] {
let err = Config::default()
.apply_env(env(&[(var, value)]))
.unwrap_err();
assert!(err.to_string().contains(var), "{err}");
}
}
#[test]
fn cli_bind_replaces_and_peers_merge() {
let mut config = Config::from_yaml(FULL).unwrap();
config.apply_cli(
vec![ip("192.0.2.7"), ip("2001:db8::7")],
[ip("192.0.2.3"), ip("192.0.2.4"), ip("192.0.2.4")],
);
assert_eq!(config.bind, vec![ip("192.0.2.7"), ip("2001:db8::7")]);
let addrs: Vec<_> = config.peers.iter().map(|p| p.address).collect();
assert_eq!(
addrs,
vec![ip("192.0.2.2"), ip("192.0.2.3"), ip("192.0.2.4")]
);
// The file's settings for an existing peer win over the bare CLI entry.
assert_eq!(config.peers[1].detect_mult, Some(4));
let mut config = Config::from_yaml(FULL).unwrap();
config.apply_cli(Vec::new(), []);
assert_eq!(config.bind, vec![ip("192.0.2.1")]);
}
#[test]
fn resolve_validation() {
let base =
|| Config::from_yaml("bind: 192.0.2.1\npeers:\n - address: 192.0.2.2\n").unwrap();
assert!(base().resolve().is_ok());
let mut c = base();
c.bind.clear();
assert!(c.resolve().is_err());
let mut c = base();
c.bind.push(ip("192.0.2.1"));
assert!(c.resolve().is_err());
let mut c = base();
c.peers.push(PeerConfig::new(ip("192.0.2.2")));
assert!(c
.resolve()
.unwrap_err()
.to_string()
.contains("duplicate peer"));
let mut c = base();
c.peers.push(PeerConfig::new(ip("2001:db8::2")));
assert!(c
.resolve()
.unwrap_err()
.to_string()
.contains("address family"));
c.bind.push(ip("2001:db8::1"));
assert!(c.resolve().is_ok());
let mut c = base();
c.peers[0].detect_mult = Some(0);
assert!(c.resolve().is_err());
let mut c = base();
c.peers[0].desired_min_tx = Some(Duration::ZERO);
assert!(c.resolve().is_err());
let mut c = base();
c.peers[0].required_min_rx = Some(Duration::from_secs(5000));
assert!(c.resolve().unwrap_err().to_string().contains("too large"));
let mut c = base();
c.defaults.detect_mult = 0;
assert!(c.resolve().is_err());
}
#[test]
fn zero_peers_is_valid() {
let config = Config::from_yaml("bind: 192.0.2.1").unwrap();
assert!(config.resolve().unwrap().peers.is_empty());
}
#[test]
fn load_requires_explicit_path_to_exist() {
let err = Config::load(Some(Path::new("/nonexistent/rust-bfd.yaml"))).unwrap_err();
assert!(matches!(err, ConfigError::Io { .. }));
}
}