shadow_rs/core/
configuration.rs

1//! Shadow's configuration and cli parsing code using [serde] and [clap]. This contains all of
2//! Shadow's configuration options, some of which are also exposed as CLI options.
3//!
4//! Shadow uses [schemars] to get the option description (its doc comment) and default value so that
5//! it can be shown in the CLI help text.
6//!
7//! This code should be careful about validating or interpreting values. It should be focused on
8//! parsing and checking that the format is correct, and not validating the values. For example for
9//! options that take paths, this code should not verify that the path actually exists or perform
10//! any path canonicalization. That should be left to other code outside of this module. This is so
11//! that the configuration parsing does not become environment-dependent. If a configuration file
12//! parses on one system, it should parse successfully on other systems as well.
13
14use std::borrow::Cow;
15use std::collections::{BTreeMap, HashSet};
16use std::ffi::{CStr, CString, OsStr, OsString};
17use std::os::unix::ffi::OsStrExt;
18use std::str::FromStr;
19
20use clap::Parser;
21use logger as c_log;
22use merge::Merge;
23use once_cell::sync::Lazy;
24use schemars::{JsonSchema, schema_for};
25use serde::{Deserialize, Serialize};
26use shadow_shim_helper_rs::simulation_time::SimulationTime;
27
28use crate::cshadow as c;
29use crate::host::syscall::formatter::FmtOptions;
30use crate::utility::units::{self, Unit};
31
32const START_HELP_TEXT: &str = "\
33    Run real applications over simulated networks.\n\n\
34    For documentation, visit https://shadow.github.io/docs/guide";
35
36const END_HELP_TEXT: &str = "\
37    If units are not specified, all values are assumed to be given in their base \
38    unit (seconds, bytes, bits, etc). Units can optionally be specified (for \
39    example: '1024 B', '1024 bytes', '1 KiB', '1 kibibyte', etc) and are \
40    case-sensitive.";
41
42// clap requires a 'static str for the version
43static VERSION: Lazy<String> = Lazy::new(crate::shadow::version);
44
45#[derive(Debug, Clone, Parser)]
46#[clap(name = "Shadow", about = START_HELP_TEXT, after_help = END_HELP_TEXT)]
47#[clap(version = VERSION.as_str())]
48#[clap(next_display_order = None)]
49// clap only shows the possible values for bool options (unless we add support for the other
50// non-bool options in the future), which isn't very helpful
51#[clap(hide_possible_values = true)]
52pub struct CliOptions {
53    /// Path to the Shadow configuration file. Use '-' to read from stdin
54    #[clap(required_unless_present_any(&["show_build_info", "shm_cleanup"]))]
55    pub config: Option<String>,
56
57    /// Pause to allow gdb to attach
58    #[clap(long, short = 'g')]
59    pub gdb: bool,
60
61    /// Pause after starting any processes on the comma-delimited list of hostnames
62    #[clap(value_parser = parse_set_str)]
63    #[clap(long, value_name = "hostnames")]
64    pub debug_hosts: Option<HashSet<String>>,
65
66    /// Exit after running shared memory cleanup routine
67    #[clap(long, exclusive(true))]
68    pub shm_cleanup: bool,
69
70    /// Exit after printing build information
71    #[clap(long, exclusive(true))]
72    pub show_build_info: bool,
73
74    /// Exit after printing the final configuration
75    #[clap(long)]
76    pub show_config: bool,
77
78    #[clap(flatten)]
79    pub general: GeneralOptions,
80
81    #[clap(flatten)]
82    pub network: NetworkOptions,
83
84    #[clap(flatten)]
85    pub host_option_defaults: HostDefaultOptions,
86
87    #[clap(flatten)]
88    pub experimental: ExperimentalOptions,
89}
90
91/// Options contained in a configuration file.
92#[derive(Debug, Clone, Serialize, Deserialize)]
93#[serde(deny_unknown_fields)]
94pub struct ConfigFileOptions {
95    pub general: GeneralOptions,
96
97    pub network: NetworkOptions,
98
99    #[serde(default)]
100    pub host_option_defaults: HostDefaultOptions,
101
102    #[serde(default)]
103    pub experimental: ExperimentalOptions,
104
105    // we use a BTreeMap so that the hosts are sorted by their hostname (useful for determinism)
106    // since shadow parses to a serde_yaml::Value initially, we don't need to worry about duplicate
107    // hostnames here
108    pub hosts: BTreeMap<HostName, HostOptions>,
109}
110
111/// Shadow configuration options after processing command-line and configuration file options.
112#[derive(Debug, Clone, Serialize)]
113pub struct ConfigOptions {
114    pub general: GeneralOptions,
115
116    pub network: NetworkOptions,
117
118    pub experimental: ExperimentalOptions,
119
120    // we use a BTreeMap so that the hosts are sorted by their hostname (useful for determinism)
121    pub hosts: BTreeMap<HostName, HostOptions>,
122}
123
124impl ConfigOptions {
125    pub fn new(mut config_file: ConfigFileOptions, options: CliOptions) -> Self {
126        // the `HostDefaultOptions::default` contains only `None` values, so we must first merge the
127        // config file with the real defaults from `HostDefaultOptions::new_with_defaults`
128        config_file.host_option_defaults = config_file
129            .host_option_defaults
130            .with_defaults(HostDefaultOptions::new_with_defaults());
131
132        // override config options with command line options
133        config_file.general = options.general.with_defaults(config_file.general);
134        config_file.network = options.network.with_defaults(config_file.network);
135        config_file.host_option_defaults = options
136            .host_option_defaults
137            .with_defaults(config_file.host_option_defaults);
138        config_file.experimental = options.experimental.with_defaults(config_file.experimental);
139
140        // copy the host defaults to all of the hosts
141        for host in config_file.hosts.values_mut() {
142            host.host_options = host
143                .host_options
144                .clone()
145                .with_defaults(config_file.host_option_defaults.clone());
146        }
147
148        Self {
149            general: config_file.general,
150            network: config_file.network,
151            experimental: config_file.experimental,
152            hosts: config_file.hosts,
153        }
154    }
155
156    pub fn model_unblocked_syscall_latency(&self) -> bool {
157        self.general.model_unblocked_syscall_latency.unwrap()
158    }
159
160    pub fn max_unapplied_cpu_latency(&self) -> SimulationTime {
161        let nanos = self.experimental.max_unapplied_cpu_latency.unwrap();
162        let nanos = nanos.convert(units::TimePrefix::Nano).unwrap().value();
163        SimulationTime::from_nanos(nanos)
164    }
165
166    pub fn unblocked_syscall_latency(&self) -> SimulationTime {
167        let nanos = self.experimental.unblocked_syscall_latency.unwrap();
168        let nanos = nanos.convert(units::TimePrefix::Nano).unwrap().value();
169        SimulationTime::from_nanos(nanos)
170    }
171
172    pub fn unblocked_vdso_latency(&self) -> SimulationTime {
173        let nanos = self.experimental.unblocked_vdso_latency.unwrap();
174        let nanos = nanos.convert(units::TimePrefix::Nano).unwrap().value();
175        SimulationTime::from_nanos(nanos)
176    }
177
178    pub fn native_preemption_enabled(&self) -> bool {
179        self.experimental.native_preemption_enabled.unwrap()
180    }
181
182    pub fn native_preemption_native_interval(
183        &self,
184    ) -> anyhow::Result<linux_api::time::kernel_old_timeval> {
185        let t = self.experimental.native_preemption_native_interval.unwrap();
186        let t = core::time::Duration::from(t);
187        // TODO: Would be a little nicer to surface this error when we parse the
188        // config. I think ideally we'd update the type such that some bounds
189        // can be enforced at parse time.
190        if t < core::time::Duration::from_micros(1) {
191            return Err(anyhow::anyhow!(
192                "native_preemption_native_interval must be >= 1 microsecond. Got {t:?}."
193            ));
194        }
195        let rv = linux_api::time::kernel_old_timeval {
196            tv_sec: t.as_secs().try_into().unwrap(),
197            tv_usec: t.subsec_micros().into(),
198        };
199        assert!(!(rv.tv_sec == 0 && rv.tv_usec == 0));
200        Ok(rv)
201    }
202
203    pub fn native_preemption_sim_interval(&self) -> SimulationTime {
204        let t = self.experimental.native_preemption_sim_interval.unwrap();
205        let nanos = t.convert(units::TimePrefix::Nano).unwrap().value();
206        SimulationTime::from_nanos(nanos)
207    }
208
209    pub fn strace_logging_mode(&self) -> Option<FmtOptions> {
210        match self.experimental.strace_logging_mode.as_ref().unwrap() {
211            StraceLoggingMode::Standard => Some(FmtOptions::Standard),
212            StraceLoggingMode::Deterministic => Some(FmtOptions::Deterministic),
213            StraceLoggingMode::Long => Some(FmtOptions::Long),
214            StraceLoggingMode::Off => None,
215        }
216    }
217}
218
219/// Help messages used by Clap for command line arguments, combining the doc string with
220/// the Serde default.
221static GENERAL_HELP: Lazy<std::collections::HashMap<String, String>> =
222    Lazy::new(|| generate_help_strs(schema_for!(GeneralOptions)));
223
224// these must all be Option types since they aren't required by the CLI, even if they're
225// required in the configuration file
226#[derive(Debug, Clone, Parser, Serialize, Deserialize, Merge, JsonSchema)]
227#[clap(next_help_heading = "General (Override configuration file options)")]
228#[clap(next_display_order = None)]
229#[serde(deny_unknown_fields)]
230#[merge(strategy = merge::option::overwrite_none)]
231pub struct GeneralOptions {
232    /// The simulated time at which simulated processes are sent a SIGKILL signal
233    #[clap(long, value_name = "seconds")]
234    #[clap(help = GENERAL_HELP.get("stop_time").unwrap().as_str())]
235    pub stop_time: Option<units::Time<units::TimePrefix>>,
236
237    /// Initialize randomness using seed N
238    #[clap(long, value_name = "N")]
239    #[clap(help = GENERAL_HELP.get("seed").unwrap().as_str())]
240    #[serde(default = "default_some_1")]
241    pub seed: Option<u32>,
242
243    /// How many parallel threads to use to run the simulation. A value of 0 will allow Shadow to
244    /// choose the number of threads.
245    #[clap(long, short = 'p', value_name = "cores")]
246    #[clap(help = GENERAL_HELP.get("parallelism").unwrap().as_str())]
247    #[serde(default = "default_some_0")]
248    pub parallelism: Option<u32>,
249
250    /// The simulated time that ends Shadow's high network bandwidth/reliability bootstrap period
251    #[clap(long, value_name = "seconds")]
252    #[clap(help = GENERAL_HELP.get("bootstrap_end_time").unwrap().as_str())]
253    #[serde(default = "default_some_time_0")]
254    pub bootstrap_end_time: Option<units::Time<units::TimePrefix>>,
255
256    /// Log level of output written on stdout. If Shadow was built in release mode, then log
257    /// messages at level 'trace' will always be dropped
258    #[clap(long, short = 'l', value_name = "level")]
259    #[clap(help = GENERAL_HELP.get("log_level").unwrap().as_str())]
260    #[serde(default = "default_some_info")]
261    pub log_level: Option<LogLevel>,
262
263    /// Interval at which to print heartbeat messages
264    #[clap(long, value_name = "seconds")]
265    #[clap(help = GENERAL_HELP.get("heartbeat_interval").unwrap().as_str())]
266    #[serde(default = "default_some_nullable_time_1")]
267    pub heartbeat_interval: Option<NullableOption<units::Time<units::TimePrefix>>>,
268
269    /// Path to store simulation output
270    #[clap(long, short = 'd', value_name = "path")]
271    #[clap(help = GENERAL_HELP.get("data_directory").unwrap().as_str())]
272    #[serde(default = "default_data_directory")]
273    pub data_directory: Option<String>,
274
275    /// Path to recursively copy during startup and use as the data-directory
276    #[clap(long, short = 'e', value_name = "path")]
277    #[clap(help = GENERAL_HELP.get("template_directory").unwrap().as_str())]
278    #[serde(default)]
279    pub template_directory: Option<NullableOption<String>>,
280
281    /// Show the simulation progress on stderr
282    #[clap(long, value_name = "bool")]
283    #[clap(help = GENERAL_HELP.get("progress").unwrap().as_str())]
284    #[serde(default = "default_some_false")]
285    pub progress: Option<bool>,
286
287    /// Model syscalls and VDSO functions that don't block as having some
288    /// latency. This should have minimal effect on typical simulations, but
289    /// can be helpful for programs with "busy loops" that otherwise deadlock
290    /// under Shadow.
291    #[clap(long, value_name = "bool")]
292    #[clap(help = GENERAL_HELP.get("model_unblocked_syscall_latency").unwrap().as_str())]
293    #[serde(default = "default_some_false")]
294    pub model_unblocked_syscall_latency: Option<bool>,
295}
296
297impl GeneralOptions {
298    /// Replace unset (`None`) values of `base` with values from `default`.
299    pub fn with_defaults(mut self, default: Self) -> Self {
300        self.merge(default);
301        self
302    }
303}
304
305/// Help messages used by Clap for command line arguments, combining the doc string with
306/// the Serde default.
307static NETWORK_HELP: Lazy<std::collections::HashMap<String, String>> =
308    Lazy::new(|| generate_help_strs(schema_for!(NetworkOptions)));
309
310// these must all be Option types since they aren't required by the CLI, even if they're
311// required in the configuration file
312#[derive(Debug, Clone, Parser, Serialize, Deserialize, Merge, JsonSchema)]
313#[clap(next_help_heading = "Network (Override network options)")]
314#[clap(next_display_order = None)]
315#[serde(deny_unknown_fields)]
316#[merge(strategy = merge::option::overwrite_none)]
317pub struct NetworkOptions {
318    /// The network topology graph
319    #[clap(skip)]
320    pub graph: Option<GraphOptions>,
321
322    /// When routing packets, follow the shortest path rather than following a direct
323    /// edge between nodes. If false, the network graph is required to be complete.
324    #[serde(default = "default_some_true")]
325    #[clap(long, value_name = "bool")]
326    #[clap(help = NETWORK_HELP.get("use_shortest_path").unwrap().as_str())]
327    pub use_shortest_path: Option<bool>,
328}
329
330impl NetworkOptions {
331    /// Replace unset (`None`) values of `base` with values from `default`.
332    pub fn with_defaults(mut self, default: Self) -> Self {
333        self.merge(default);
334        self
335    }
336}
337
338/// Help messages used by Clap for command line arguments, combining the doc string with
339/// the Serde default.
340static EXP_HELP: Lazy<std::collections::HashMap<String, String>> =
341    Lazy::new(|| generate_help_strs(schema_for!(ExperimentalOptions)));
342
343#[derive(Debug, Clone, Parser, Serialize, Deserialize, Merge, JsonSchema)]
344#[clap(
345    next_help_heading = "Experimental (Unstable and may change or be removed at any time, regardless of Shadow version)"
346)]
347#[clap(next_display_order = None)]
348#[serde(default, deny_unknown_fields)]
349#[merge(strategy = merge::option::overwrite_none)]
350pub struct ExperimentalOptions {
351    /// Use the SCHED_FIFO scheduler. Requires CAP_SYS_NICE. See sched(7), capabilities(7)
352    #[clap(hide_short_help = true)]
353    #[clap(long, value_name = "bool")]
354    #[clap(help = EXP_HELP.get("use_sched_fifo").unwrap().as_str())]
355    pub use_sched_fifo: Option<bool>,
356
357    /// Count the number of occurrences for individual syscalls
358    #[clap(hide_short_help = true)]
359    #[clap(long, value_name = "bool")]
360    #[clap(help = EXP_HELP.get("use_syscall_counters").unwrap().as_str())]
361    pub use_syscall_counters: Option<bool>,
362
363    /// Count object allocations and deallocations. If disabled, we will not be able to detect object memory leaks
364    #[clap(hide_short_help = true)]
365    #[clap(long, value_name = "bool")]
366    #[clap(help = EXP_HELP.get("use_object_counters").unwrap().as_str())]
367    pub use_object_counters: Option<bool>,
368
369    /// Preload our libc library for all managed processes for fast syscall interposition when possible.
370    #[clap(hide_short_help = true)]
371    #[clap(long, value_name = "bool")]
372    #[clap(help = EXP_HELP.get("use_preload_libc").unwrap().as_str())]
373    pub use_preload_libc: Option<bool>,
374
375    /// Preload our OpenSSL RNG library for all managed processes to mitigate non-deterministic use of OpenSSL.
376    #[clap(hide_short_help = true)]
377    #[clap(long, value_name = "bool")]
378    #[clap(help = EXP_HELP.get("use_preload_openssl_rng").unwrap().as_str())]
379    pub use_preload_openssl_rng: Option<bool>,
380
381    /// Preload our OpenSSL crypto library for all managed processes to skip some crypto operations
382    /// (may speed up simulation if your CPU lacks AES-NI support, but can cause bugs so do not use
383    /// unless you know what you're doing).
384    #[clap(hide_short_help = true)]
385    #[clap(long, value_name = "bool")]
386    #[clap(help = EXP_HELP.get("use_preload_openssl_crypto").unwrap().as_str())]
387    pub use_preload_openssl_crypto: Option<bool>,
388
389    /// Pin each thread and any processes it executes to the same logical CPU Core to improve cache affinity
390    #[clap(hide_short_help = true)]
391    #[clap(long, value_name = "bool")]
392    #[clap(help = EXP_HELP.get("use_cpu_pinning").unwrap().as_str())]
393    pub use_cpu_pinning: Option<bool>,
394
395    /// Each worker thread will spin in a `sched_yield` loop while waiting for a new task. This is
396    /// ignored if not using the thread-per-core scheduler.
397    #[clap(hide_short_help = true)]
398    #[clap(long, value_name = "bool")]
399    #[clap(help = EXP_HELP.get("use_worker_spinning").unwrap().as_str())]
400    pub use_worker_spinning: Option<bool>,
401
402    /// If set, overrides the automatically calculated minimum time workers may run ahead when sending events between nodes
403    #[clap(hide_short_help = true)]
404    #[clap(long, value_name = "seconds")]
405    #[clap(help = EXP_HELP.get("runahead").unwrap().as_str())]
406    pub runahead: Option<NullableOption<units::Time<units::TimePrefix>>>,
407
408    /// Update the minimum runahead dynamically throughout the simulation.
409    #[clap(hide_short_help = true)]
410    #[clap(long, value_name = "bool")]
411    #[clap(help = EXP_HELP.get("use_dynamic_runahead").unwrap().as_str())]
412    pub use_dynamic_runahead: Option<bool>,
413
414    /// Initial size of the socket's send buffer
415    #[clap(hide_short_help = true)]
416    #[clap(long, value_name = "bytes")]
417    #[clap(help = EXP_HELP.get("socket_send_buffer").unwrap().as_str())]
418    pub socket_send_buffer: Option<units::Bytes<units::SiPrefixUpper>>,
419
420    /// Enable send window autotuning
421    #[clap(hide_short_help = true)]
422    #[clap(long, value_name = "bool")]
423    #[clap(help = EXP_HELP.get("socket_send_autotune").unwrap().as_str())]
424    pub socket_send_autotune: Option<bool>,
425
426    /// Initial size of the socket's receive buffer
427    #[clap(hide_short_help = true)]
428    #[clap(long, value_name = "bytes")]
429    #[clap(help = EXP_HELP.get("socket_recv_buffer").unwrap().as_str())]
430    pub socket_recv_buffer: Option<units::Bytes<units::SiPrefixUpper>>,
431
432    /// Enable receive window autotuning
433    #[clap(hide_short_help = true)]
434    #[clap(long, value_name = "bool")]
435    #[clap(help = EXP_HELP.get("socket_recv_autotune").unwrap().as_str())]
436    pub socket_recv_autotune: Option<bool>,
437
438    /// The queueing discipline to use at the network interface
439    #[clap(hide_short_help = true)]
440    #[clap(long, value_name = "mode")]
441    #[clap(help = EXP_HELP.get("interface_qdisc").unwrap().as_str())]
442    pub interface_qdisc: Option<QDiscMode>,
443
444    /// Log the syscalls for each process to individual "strace" files
445    #[clap(hide_short_help = true)]
446    #[clap(long, value_name = "mode")]
447    #[clap(help = EXP_HELP.get("strace_logging_mode").unwrap().as_str())]
448    pub strace_logging_mode: Option<StraceLoggingMode>,
449
450    /// Max amount of execution-time latency allowed to accumulate before the
451    /// clock is moved forward. Moving the clock forward is a potentially
452    /// expensive operation, so larger values reduce simulation overhead, at the
453    /// cost of coarser time jumps. Note also that accumulated-but-unapplied
454    /// latency is discarded when a thread is blocked on a syscall.
455    #[clap(hide_short_help = true)]
456    #[clap(long, value_name = "seconds")]
457    #[clap(help = EXP_HELP.get("max_unapplied_cpu_latency").unwrap().as_str())]
458    pub max_unapplied_cpu_latency: Option<units::Time<units::TimePrefix>>,
459
460    /// Simulated latency of an unblocked syscall. For efficiency Shadow only
461    /// actually adds this latency if and when `max_unapplied_cpu_latency` is
462    /// reached.
463    #[clap(hide_short_help = true)]
464    #[clap(long, value_name = "seconds")]
465    #[clap(help = EXP_HELP.get("unblocked_syscall_latency").unwrap().as_str())]
466    pub unblocked_syscall_latency: Option<units::Time<units::TimePrefix>>,
467
468    /// Simulated latency of a vdso "syscall". For efficiency Shadow only
469    /// actually adds this latency if and when `max_unapplied_cpu_latency` is
470    /// reached.
471    #[clap(hide_short_help = true)]
472    #[clap(long, value_name = "seconds")]
473    #[clap(help = EXP_HELP.get("unblocked_vdso_latency").unwrap().as_str())]
474    pub unblocked_vdso_latency: Option<units::Time<units::TimePrefix>>,
475
476    /// The host scheduler implementation, which decides how to assign hosts to threads and threads
477    /// to CPU cores
478    #[clap(hide_short_help = true)]
479    #[clap(long, value_name = "name")]
480    #[clap(help = EXP_HELP.get("scheduler").unwrap().as_str())]
481    pub scheduler: Option<Scheduler>,
482
483    /// When true, report error-level messages to stderr in addition to logging to stdout.
484    #[clap(hide_short_help = true)]
485    #[clap(long, value_name = "bool")]
486    #[clap(help = EXP_HELP.get("report_errors_to_stderr").unwrap().as_str())]
487    pub report_errors_to_stderr: Option<bool>,
488
489    /// Use the rust TCP implementation
490    #[clap(hide_short_help = true)]
491    #[clap(long, value_name = "bool")]
492    #[clap(help = EXP_HELP.get("use_new_tcp").unwrap().as_str())]
493    pub use_new_tcp: Option<bool>,
494
495    /// When true, and when managed code runs for an extended time without
496    /// returning control to shadow (e.g. by making a syscall), shadow preempts
497    /// the managed code and moves simulated time forward. This can be used to
498    /// escape "pure-CPU busy-loops", but isn't usually needed, breaks
499    /// simulation determinism, and significantly affects simulation
500    /// performance.
501    #[clap(hide_short_help = true)]
502    #[clap(long, value_name = "bool")]
503    #[clap(help = EXP_HELP.get("native_preemption_enabled").unwrap().as_str())]
504    pub native_preemption_enabled: Option<bool>,
505
506    /// When `native_preemption_enabled` is true, amount of native CPU-time to
507    /// wait before preempting managed code that hasn't returned control to
508    /// shadow. Only supports microsecond granularity, and values below 1 microsecond
509    /// are rejected.
510    #[clap(hide_short_help = true)]
511    #[clap(long, value_name = "seconds")]
512    #[clap(help = EXP_HELP.get("native_preemption_native_interval").unwrap().as_str())]
513    pub native_preemption_native_interval: Option<units::Time<units::TimePrefix>>,
514
515    /// When `native_preemption_enabled` is true, amount of simulated time to
516    /// consume after `native_preemption_native_interval` has elapsed without
517    /// returning control to shadow.
518    #[clap(hide_short_help = true)]
519    #[clap(long, value_name = "seconds")]
520    #[clap(help = EXP_HELP.get("native_preemption_sim_interval").unwrap().as_str())]
521    pub native_preemption_sim_interval: Option<units::Time<units::TimePrefix>>,
522}
523
524impl ExperimentalOptions {
525    /// Replace unset (`None`) values of `base` with values from `default`.
526    pub fn with_defaults(mut self, default: Self) -> Self {
527        self.merge(default);
528        self
529    }
530}
531
532impl Default for ExperimentalOptions {
533    fn default() -> Self {
534        Self {
535            use_sched_fifo: Some(false),
536            use_syscall_counters: Some(true),
537            use_object_counters: Some(true),
538            use_preload_libc: Some(true),
539            use_preload_openssl_rng: Some(true),
540            use_preload_openssl_crypto: Some(false),
541            max_unapplied_cpu_latency: Some(units::Time::new(1, units::TimePrefix::Micro)),
542            // 1-2 microseconds is a ballpark estimate of the minimal latency for
543            // context switching to the kernel and back on modern machines.
544            // Default to the lower end to minimize effect in simualations without busy loops.
545            unblocked_syscall_latency: Some(units::Time::new(1, units::TimePrefix::Micro)),
546            // Actual latencies vary from ~40 to ~400 CPU cycles. https://stackoverflow.com/a/13096917
547            // Default to the lower end to minimize effect in simualations without busy loops.
548            unblocked_vdso_latency: Some(units::Time::new(10, units::TimePrefix::Nano)),
549            use_cpu_pinning: Some(true),
550            use_worker_spinning: Some(true),
551            runahead: Some(NullableOption::Value(units::Time::new(
552                1,
553                units::TimePrefix::Milli,
554            ))),
555            use_dynamic_runahead: Some(false),
556            socket_send_buffer: Some(units::Bytes::new(131_072, units::SiPrefixUpper::Base)),
557            socket_send_autotune: Some(true),
558            socket_recv_buffer: Some(units::Bytes::new(174_760, units::SiPrefixUpper::Base)),
559            socket_recv_autotune: Some(true),
560            interface_qdisc: Some(QDiscMode::Fifo),
561            strace_logging_mode: Some(StraceLoggingMode::Off),
562            scheduler: Some(Scheduler::ThreadPerCore),
563            report_errors_to_stderr: Some(true),
564            use_new_tcp: Some(false),
565            native_preemption_enabled: Some(false),
566            native_preemption_native_interval: Some(units::Time::new(
567                100,
568                units::TimePrefix::Milli,
569            )),
570            native_preemption_sim_interval: Some(units::Time::new(10, units::TimePrefix::Milli)),
571        }
572    }
573}
574
575/// Help messages used by Clap for command line arguments, combining the doc string with
576/// the Serde default.
577static HOST_HELP: Lazy<std::collections::HashMap<String, String>> =
578    Lazy::new(|| generate_help_strs(schema_for!(HostDefaultOptions)));
579
580#[derive(Debug, Clone, Parser, Serialize, Deserialize, Merge, JsonSchema)]
581#[clap(next_help_heading = "Host Defaults (Default options for hosts)")]
582#[clap(next_display_order = None)]
583#[serde(default, deny_unknown_fields)]
584// serde will default all fields to `None`, but in the cli help we want the actual defaults
585#[schemars(default = "HostDefaultOptions::new_with_defaults")]
586#[merge(strategy = merge::option::overwrite_none)]
587pub struct HostDefaultOptions {
588    /// Log level at which to print node messages
589    #[clap(long = "host-log-level", name = "host-log-level")]
590    #[clap(value_name = "level")]
591    #[clap(help = HOST_HELP.get("log_level").unwrap().as_str())]
592    pub log_level: Option<NullableOption<LogLevel>>,
593
594    /// Should shadow generate pcap files?
595    #[clap(long, value_name = "bool")]
596    #[clap(help = HOST_HELP.get("pcap_enabled").unwrap().as_str())]
597    pub pcap_enabled: Option<bool>,
598
599    /// How much data to capture per packet (header and payload) if pcap logging is enabled
600    #[clap(long, value_name = "bytes")]
601    #[clap(help = HOST_HELP.get("pcap_capture_size").unwrap().as_str())]
602    pub pcap_capture_size: Option<units::Bytes<units::SiPrefixUpper>>,
603}
604
605impl HostDefaultOptions {
606    pub fn new_with_defaults() -> Self {
607        Self {
608            log_level: None,
609            pcap_enabled: Some(false),
610            // From pcap(3): "A value of 65535 should be sufficient, on most if not all networks, to
611            // capture all the data available from the packet". The maximum length of an IP packet
612            // (including the header) is 65535 bytes.
613            pcap_capture_size: Some(units::Bytes::new(65535, units::SiPrefixUpper::Base)),
614        }
615    }
616
617    /// Replace unset (`None`) values of `base` with values from `default`.
618    pub fn with_defaults(mut self, default: Self) -> Self {
619        self.merge(default);
620        self
621    }
622}
623
624#[allow(clippy::derivable_impls)]
625impl Default for HostDefaultOptions {
626    fn default() -> Self {
627        // Our config fields would typically be initialized with their real defaults here in the
628        // `Default::default` implementation, but we need to handle the host options differently
629        // because the global `host_option_defaults` can be overridden by host-specific
630        // `host_options`. So instead we use defaults of `None` here and set the real defaults with
631        // `Self::new_with_defaults` in `ConfigOptions::new`.
632        Self {
633            log_level: None,
634            pcap_enabled: None,
635            pcap_capture_size: None,
636        }
637    }
638}
639
640#[derive(Serialize, Deserialize, Eq, PartialEq, Debug, Copy, Clone, JsonSchema)]
641#[serde(rename_all = "kebab-case")]
642pub enum RunningVal {
643    Running,
644}
645
646/// The enum variants here have an extra level of indirection to get the
647/// serde serialization that we want.
648#[derive(Debug, Copy, Clone, Eq, PartialEq, Serialize, Deserialize, JsonSchema)]
649#[serde(untagged)]
650pub enum ProcessFinalState {
651    Exited { exited: i32 },
652    Signaled { signaled: Signal },
653    Running(RunningVal),
654}
655
656impl Default for ProcessFinalState {
657    fn default() -> Self {
658        Self::Exited { exited: 0 }
659    }
660}
661
662impl std::fmt::Display for ProcessFinalState {
663    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
664        // We use the yaml serialization here so that when reporting that an
665        // expected state didn't match the actual state, it's clear how to set
666        // the expected state in the config file to match the actual state if
667        // desired.
668        //
669        // The current enum works OK for this since there are no internal
670        // newlines in the serialization; if there are some later we might wand
671        // to serialize to json instead, which can always be put on a single
672        // line and should also be valid yaml.
673        let s = serde_yaml::to_string(self).or(Err(std::fmt::Error))?;
674        write!(f, "{}", s.trim())
675    }
676}
677
678#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
679#[serde(deny_unknown_fields)]
680pub struct ProcessOptions {
681    pub path: std::path::PathBuf,
682
683    /// Process arguments
684    #[serde(default = "default_args_empty")]
685    pub args: ProcessArgs,
686
687    /// Environment variables passed when executing this process
688    #[serde(default)]
689    pub environment: BTreeMap<EnvName, String>,
690
691    /// The simulated time at which to execute the process
692    #[serde(default)]
693    pub start_time: units::Time<units::TimePrefix>,
694
695    /// The simulated time at which to send a `shutdown_signal` signal to the process
696    #[serde(default)]
697    pub shutdown_time: Option<units::Time<units::TimePrefix>>,
698
699    /// The signal that will be sent to the process at `shutdown_time`
700    #[serde(default = "default_sigterm")]
701    pub shutdown_signal: Signal,
702
703    /// The expected final state of the process. Shadow will report an error
704    /// if the actual state doesn't match.
705    #[serde(default)]
706    pub expected_final_state: ProcessFinalState,
707}
708
709#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
710#[serde(deny_unknown_fields)]
711pub struct HostOptions {
712    /// Network graph node ID to assign the host to
713    pub network_node_id: u32,
714
715    pub processes: Vec<ProcessOptions>,
716
717    /// IP address to assign to the host
718    #[serde(default)]
719    pub ip_addr: Option<std::net::Ipv4Addr>,
720
721    /// Downstream bandwidth capacity of the host
722    #[serde(default)]
723    pub bandwidth_down: Option<units::BitsPerSec<units::SiPrefixUpper>>,
724
725    /// Upstream bandwidth capacity of the host
726    #[serde(default)]
727    pub bandwidth_up: Option<units::BitsPerSec<units::SiPrefixUpper>>,
728
729    #[serde(default)]
730    pub host_options: HostDefaultOptions,
731}
732
733#[derive(Debug, Copy, Clone, Serialize, Deserialize, JsonSchema)]
734#[serde(rename_all = "kebab-case")]
735pub enum LogLevel {
736    Error,
737    Warning,
738    Info,
739    Debug,
740    Trace,
741}
742
743impl FromStr for LogLevel {
744    type Err = serde_yaml::Error;
745
746    fn from_str(s: &str) -> Result<Self, Self::Err> {
747        serde_yaml::from_str(s)
748    }
749}
750
751impl LogLevel {
752    pub fn to_c_loglevel(&self) -> c_log::LogLevel {
753        match self {
754            Self::Error => c_log::_LogLevel_LOGLEVEL_ERROR,
755            Self::Warning => c_log::_LogLevel_LOGLEVEL_WARNING,
756            Self::Info => c_log::_LogLevel_LOGLEVEL_INFO,
757            Self::Debug => c_log::_LogLevel_LOGLEVEL_DEBUG,
758            Self::Trace => c_log::_LogLevel_LOGLEVEL_TRACE,
759        }
760    }
761}
762
763impl From<LogLevel> for log::Level {
764    fn from(level: LogLevel) -> Self {
765        match level {
766            LogLevel::Error => log::Level::Error,
767            LogLevel::Warning => log::Level::Warn,
768            LogLevel::Info => log::Level::Info,
769            LogLevel::Debug => log::Level::Debug,
770            LogLevel::Trace => log::Level::Trace,
771        }
772    }
773}
774
775#[derive(Debug, Clone, PartialOrd, Ord, PartialEq, Eq, Serialize, JsonSchema)]
776pub struct HostName(String);
777
778impl<'de> serde::Deserialize<'de> for HostName {
779    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
780        struct HostNameVisitor;
781
782        impl serde::de::Visitor<'_> for HostNameVisitor {
783            type Value = HostName;
784
785            fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
786                formatter.write_str("a string")
787            }
788
789            fn visit_string<E>(self, v: String) -> Result<Self::Value, E>
790            where
791                E: serde::de::Error,
792            {
793                // hostname(7): "Valid characters for hostnames are ASCII(7) letters from a to z,
794                // the digits from 0 to 9, and the hyphen (-)."
795                fn is_allowed(c: char) -> bool {
796                    c.is_ascii_lowercase() || c.is_ascii_digit() || c == '-' || c == '.'
797                }
798                if let Some(invalid_char) = v.chars().find(|x| !is_allowed(*x)) {
799                    return Err(E::custom(format!(
800                        "invalid hostname character: '{invalid_char}'"
801                    )));
802                }
803
804                if v.is_empty() {
805                    return Err(E::custom("empty hostname"));
806                }
807
808                // hostname(7): "A hostname may not start with a hyphen."
809                if v.starts_with('-') {
810                    return Err(E::custom("hostname begins with a '-' character"));
811                }
812
813                // hostname(7): "Each element of the hostname must be from 1 to 63 characters long
814                // and the entire hostname, including the dots, can be at most 253 characters long."
815                if v.len() > 253 {
816                    return Err(E::custom("hostname exceeds 253 characters"));
817                }
818
819                Ok(HostName(v))
820            }
821
822            fn visit_str<E>(self, v: &str) -> Result<Self::Value, E>
823            where
824                E: serde::de::Error,
825            {
826                // serde::de::Visitor: "It is never correct to implement `visit_string` without
827                // implementing `visit_str`. Implement neither, both, or just `visit_str`.'
828                self.visit_string(v.to_string())
829            }
830        }
831
832        deserializer.deserialize_string(HostNameVisitor)
833    }
834}
835
836impl std::ops::Deref for HostName {
837    type Target = String;
838
839    fn deref(&self) -> &Self::Target {
840        &self.0
841    }
842}
843
844impl From<HostName> for String {
845    fn from(name: HostName) -> Self {
846        name.0
847    }
848}
849
850impl std::fmt::Display for HostName {
851    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
852        self.0.fmt(f)
853    }
854}
855
856#[derive(Debug, Clone, PartialOrd, Ord, PartialEq, Eq, Serialize, JsonSchema)]
857pub struct EnvName(String);
858
859impl EnvName {
860    pub fn new(name: impl Into<String>) -> Option<Self> {
861        let name = name.into();
862
863        // an environment variable name cannot contain a '=' character
864        if name.contains('=') {
865            return None;
866        }
867
868        Some(Self(name))
869    }
870}
871
872impl<'de> serde::Deserialize<'de> for EnvName {
873    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
874        struct EnvNameVisitor;
875
876        impl serde::de::Visitor<'_> for EnvNameVisitor {
877            type Value = EnvName;
878
879            fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
880                formatter.write_str("a string")
881            }
882
883            fn visit_string<E>(self, v: String) -> Result<Self::Value, E>
884            where
885                E: serde::de::Error,
886            {
887                let Some(name) = EnvName::new(v) else {
888                    let e = "environment variable name contains a '=' character";
889                    return Err(E::custom(e));
890                };
891
892                Ok(name)
893            }
894
895            fn visit_str<E>(self, v: &str) -> Result<Self::Value, E>
896            where
897                E: serde::de::Error,
898            {
899                // serde::de::Visitor: "It is never correct to implement `visit_string` without
900                // implementing `visit_str`. Implement neither, both, or just `visit_str`.'
901                self.visit_string(v.to_string())
902            }
903        }
904
905        deserializer.deserialize_string(EnvNameVisitor)
906    }
907}
908
909impl std::ops::Deref for EnvName {
910    type Target = String;
911
912    fn deref(&self) -> &Self::Target {
913        &self.0
914    }
915}
916
917impl From<EnvName> for String {
918    fn from(name: EnvName) -> Self {
919        name.0
920    }
921}
922
923impl std::fmt::Display for EnvName {
924    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
925        self.0.fmt(f)
926    }
927}
928
929#[derive(Debug, Copy, Clone, Serialize, Deserialize, JsonSchema)]
930#[serde(rename_all = "kebab-case")]
931pub enum Scheduler {
932    ThreadPerHost,
933    ThreadPerCore,
934}
935
936impl FromStr for Scheduler {
937    type Err = serde_yaml::Error;
938
939    fn from_str(s: &str) -> Result<Self, Self::Err> {
940        serde_yaml::from_str(s)
941    }
942}
943
944fn default_data_directory() -> Option<String> {
945    Some("shadow.data".into())
946}
947
948/// Parse a string as a comma-delimited set of `T` values.
949fn parse_set<T>(s: &str) -> Result<HashSet<T>, <T as FromStr>::Err>
950where
951    T: std::cmp::Eq + std::hash::Hash + FromStr,
952{
953    s.split(',').map(|x| x.trim().parse()).collect()
954}
955
956/// Parse a string as a comma-delimited set of `String` values.
957fn parse_set_str(s: &str) -> Result<HashSet<String>, <String as FromStr>::Err> {
958    parse_set(s)
959}
960
961#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
962#[serde(rename_all = "kebab-case")]
963#[repr(C)]
964pub enum QDiscMode {
965    Fifo,
966    RoundRobin,
967}
968
969impl FromStr for QDiscMode {
970    type Err = serde_yaml::Error;
971
972    fn from_str(s: &str) -> Result<Self, Self::Err> {
973        serde_yaml::from_str(s)
974    }
975}
976
977#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
978#[serde(rename_all = "kebab-case")]
979pub enum Compression {
980    Xz,
981}
982
983#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
984#[serde(deny_unknown_fields)]
985pub struct FileSource {
986    /// The path to the file
987    pub path: String,
988    /// The file's compression format
989    pub compression: Option<Compression>,
990}
991
992#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
993#[serde(rename_all = "kebab-case")]
994pub enum GraphSource {
995    File(FileSource),
996    Inline(String),
997}
998
999#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
1000// we use "kebab-case" for other shadow options, but are leaving this as "snake_case" for backwards
1001// compatibility
1002#[serde(tag = "type", rename_all = "snake_case")]
1003pub enum GraphOptions {
1004    Gml(GraphSource),
1005    #[serde(rename = "1_gbit_switch")]
1006    OneGbitSwitch,
1007}
1008
1009#[derive(Debug, Clone, Serialize, JsonSchema)]
1010#[serde(untagged)]
1011pub enum ProcessArgs {
1012    List(Vec<String>),
1013    Str(String),
1014}
1015
1016/// Serde doesn't provide good deserialization error messages for untagged enums, so we implement
1017/// our own. For example, if serde finds a yaml value such as 4 for the process arguments, it won't
1018/// deserialize it to the string "4" and the yaml parsing will fail. The serde-generated error
1019/// message will say something like "data did not match any variant of untagged enum ProcessArgs at
1020/// line X column Y" which isn't very helpful to the user, so here we try to give a better error
1021/// message.
1022impl<'de> serde::Deserialize<'de> for ProcessArgs {
1023    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
1024        struct ProcessArgsVisitor;
1025
1026        impl<'de> serde::de::Visitor<'de> for ProcessArgsVisitor {
1027            type Value = ProcessArgs;
1028
1029            fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
1030                formatter.write_str("a string or a sequence of strings")
1031            }
1032
1033            fn visit_str<E>(self, v: &str) -> Result<Self::Value, E>
1034            where
1035                E: serde::de::Error,
1036            {
1037                Ok(Self::Value::Str(v.to_owned()))
1038            }
1039
1040            fn visit_seq<A>(self, mut seq: A) -> Result<Self::Value, A::Error>
1041            where
1042                A: serde::de::SeqAccess<'de>,
1043            {
1044                let mut v = vec![];
1045
1046                while let Some(val) = seq.next_element()? {
1047                    v.push(val);
1048                }
1049
1050                Ok(Self::Value::List(v))
1051            }
1052        }
1053
1054        deserializer.deserialize_any(ProcessArgsVisitor)
1055    }
1056}
1057
1058// TODO: use linux_api's Signal internally, which we control and which supports
1059// realtime signals. We need to implement conversion to and from strings to do
1060// so, while being careful that the conversion is compatible with nix's so as
1061// not to be a breaking change to our configuration format.
1062#[derive(Debug, Copy, Clone, Eq, PartialEq)]
1063pub struct Signal(nix::sys::signal::Signal);
1064
1065impl From<nix::sys::signal::Signal> for Signal {
1066    fn from(value: nix::sys::signal::Signal) -> Self {
1067        Self(value)
1068    }
1069}
1070
1071impl TryFrom<linux_api::signal::Signal> for Signal {
1072    type Error = <nix::sys::signal::Signal as TryFrom<i32>>::Error;
1073    fn try_from(value: linux_api::signal::Signal) -> Result<Self, Self::Error> {
1074        let signal = nix::sys::signal::Signal::try_from(value.as_i32())?;
1075        Ok(Self(signal))
1076    }
1077}
1078
1079impl serde::Serialize for Signal {
1080    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
1081    where
1082        S: serde::Serializer,
1083    {
1084        serializer.serialize_str(self.0.as_str())
1085    }
1086}
1087
1088impl<'de> serde::Deserialize<'de> for Signal {
1089    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
1090        struct SignalVisitor;
1091
1092        impl serde::de::Visitor<'_> for SignalVisitor {
1093            type Value = Signal;
1094
1095            fn expecting(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
1096                formatter.write_str("a signal string (e.g. \"SIGINT\") or integer")
1097            }
1098
1099            fn visit_str<E>(self, v: &str) -> Result<Self::Value, E>
1100            where
1101                E: serde::de::Error,
1102            {
1103                nix::sys::signal::Signal::from_str(v)
1104                    .map(Signal)
1105                    .map_err(|_e| E::custom(format!("Invalid signal string: {v}")))
1106            }
1107
1108            fn visit_i64<E>(self, v: i64) -> Result<Self::Value, E>
1109            where
1110                E: serde::de::Error,
1111            {
1112                let v = i32::try_from(v)
1113                    .map_err(|_e| E::custom(format!("Invalid signal number: {v}")))?;
1114                nix::sys::signal::Signal::try_from(v)
1115                    .map(Signal)
1116                    .map_err(|_e| E::custom(format!("Invalid signal number: {v}")))
1117            }
1118
1119            fn visit_u64<E>(self, v: u64) -> Result<Self::Value, E>
1120            where
1121                E: serde::de::Error,
1122            {
1123                let v = i64::try_from(v)
1124                    .map_err(|_e| E::custom(format!("Invalid signal number: {v}")))?;
1125                self.visit_i64(v)
1126            }
1127        }
1128
1129        deserializer.deserialize_any(SignalVisitor)
1130    }
1131}
1132
1133impl std::fmt::Display for Signal {
1134    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1135        write!(f, "{}", self.0)
1136    }
1137}
1138
1139impl JsonSchema for Signal {
1140    fn schema_name() -> Cow<'static, str> {
1141        "Signal".into()
1142    }
1143
1144    fn json_schema(_gen: &mut schemars::SchemaGenerator) -> schemars::Schema {
1145        // Use the "anything" schema. The Deserialize implementation does the
1146        // actual parsing and error handling.
1147        // TODO: Ideally we'd only accept strings or integers here. The
1148        // documentation isn't very clear about how to construct such a schema
1149        // though, and we currently only use the schemas for command-line-option
1150        // help strings. Since we don't currently take Signals in
1151        // command-line-options, it doesn't matter.
1152        schemars::json_schema!(true)
1153    }
1154}
1155
1156impl std::ops::Deref for Signal {
1157    type Target = nix::sys::signal::Signal;
1158
1159    fn deref(&self) -> &Self::Target {
1160        &self.0
1161    }
1162}
1163
1164#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
1165#[serde(rename_all = "kebab-case")]
1166pub enum StraceLoggingMode {
1167    Off,
1168    Standard,
1169    Deterministic,
1170    Long,
1171}
1172
1173impl FromStr for StraceLoggingMode {
1174    type Err = serde_yaml::Error;
1175
1176    fn from_str(s: &str) -> Result<Self, Self::Err> {
1177        serde_yaml::from_str(s)
1178    }
1179}
1180
1181/// This wrapper type allows cli options to specify "null" to overwrite a config file option with
1182/// `None`, and is intended to be used for options where "null" is a valid option value.
1183///
1184/// **Warning**: This may result in unexpected behaviour when wrapping string types. For example, if
1185/// this is used for a file path option, the value "null" will conflict with the valid filename
1186/// "null". So if the user specifies "null" for this option, Shadow will assume it means "no value"
1187/// rather than the filename "null".
1188///
1189/// ### Motivation
1190///
1191/// For configuration options, there are generally three states:
1192/// - set
1193/// - not set
1194/// - null
1195///
1196/// For serde, all three states are configurable:
1197/// - set: `runahead: 5ms`
1198/// - not set: (no `runahead` option used in yaml)
1199/// - null: `runahead: null`
1200///
1201/// For clap, there are only two states:
1202/// - set: `--runahead 5ms`
1203/// - not set: (no `--runahead` option used in command)
1204///
1205/// There is no way to set a "null" state for cli options with clap.
1206///
1207/// ### Configuration in Shadow
1208///
1209/// Shadow first parses the config file and cli options separately before merging them.
1210///
1211/// Parsing for serde:
1212/// - set: `runahead: 5ms` => runahead is set to `Some(5ms)`
1213/// - not set: (no `runahead` option used in yaml) => runahead is set to its default (either
1214///   `Some(..)` or `None`)
1215/// - null: `runahead: null` => runahead is set to `None`
1216///
1217/// Parsing for clap:
1218/// - set: `--runahead 5ms` => runahead is set to `Some(5ms)`
1219/// - not set: (no `--runahead` option used in command) => runahead is set to `None`
1220///
1221/// Then the options are merged such that any `Some(..)` options from the cli options will overwrite
1222/// any `Some` or `None` options from the config file.
1223///
1224/// The issue is that no clap option can overwrite a config file option of `Some` with a value of
1225/// `None`. For example if the config file specifies `runahead: 5ms`, then with clap you can only
1226/// use `--runahead 2ms` to change the runahead to a `Some(2ms)` value, or you can not set
1227/// `--runahead` at all to leave it as a `Some(5ms)` value. But there is no cli option to change the
1228/// runahead to a `None` value.
1229///
1230/// This `NullableOption` type is a wrapper to allow you to specify "null" on the command line to
1231/// overwrite the config file value with `None`. From the example above, you could now specify
1232/// "--runahead null" to overwrite the config file value (for example `Some(5ms)`) with a `None`
1233/// value.
1234#[derive(Debug, Copy, Clone, JsonSchema, Eq, PartialEq)]
1235pub enum NullableOption<T> {
1236    Value(T),
1237    Null,
1238}
1239
1240impl<T> NullableOption<T> {
1241    pub fn as_ref(&self) -> NullableOption<&T> {
1242        match self {
1243            NullableOption::Value(x) => NullableOption::Value(x),
1244            NullableOption::Null => NullableOption::Null,
1245        }
1246    }
1247
1248    pub fn as_mut(&mut self) -> NullableOption<&mut T> {
1249        match self {
1250            NullableOption::Value(x) => NullableOption::Value(x),
1251            NullableOption::Null => NullableOption::Null,
1252        }
1253    }
1254
1255    /// Easier to use than `Into<Option<T>>` since `Option` has a lot of blanket `From`
1256    /// implementations, requiring a lot of type annotations.
1257    pub fn to_option(self) -> Option<T> {
1258        match self {
1259            NullableOption::Value(x) => Some(x),
1260            NullableOption::Null => None,
1261        }
1262    }
1263}
1264
1265impl<T: serde::Serialize> serde::Serialize for NullableOption<T> {
1266    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
1267        match self {
1268            // use the inner type's serialize function
1269            Self::Value(x) => Ok(T::serialize(x, serializer)?),
1270            Self::Null => serializer.serialize_none(),
1271        }
1272    }
1273}
1274
1275impl<'de, T: serde::Deserialize<'de>> serde::Deserialize<'de> for NullableOption<T> {
1276    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
1277        // always use the inner type's deserialize function
1278        Ok(Self::Value(T::deserialize(deserializer)?))
1279    }
1280}
1281
1282impl<T> FromStr for NullableOption<T>
1283where
1284    T: FromStr<Err: std::fmt::Debug + std::fmt::Display>,
1285{
1286    type Err = T::Err;
1287
1288    fn from_str(s: &str) -> Result<Self, Self::Err> {
1289        match s {
1290            // since we use serde-yaml, use "null" to match yaml's "null"
1291            "null" => Ok(Self::Null),
1292            x => Ok(Self::Value(FromStr::from_str(x)?)),
1293        }
1294    }
1295}
1296
1297/// A trait for `Option`-like types that can be flattened into a single `Option`.
1298pub trait Flatten<T> {
1299    fn flatten(self) -> Option<T>;
1300    fn flatten_ref(&self) -> Option<&T>;
1301}
1302
1303impl<T> Flatten<T> for Option<NullableOption<T>> {
1304    fn flatten(self) -> Option<T> {
1305        self.and_then(|x| x.to_option())
1306    }
1307
1308    fn flatten_ref(&self) -> Option<&T> {
1309        self.as_ref().and_then(|x| x.as_ref().to_option())
1310    }
1311}
1312
1313/// Helper function for serde default `ProcessArgs::Str("")` values.
1314fn default_args_empty() -> ProcessArgs {
1315    ProcessArgs::Str("".to_string())
1316}
1317
1318/// Helper function for serde default `Signal(Signal::SIGTERM)` values.
1319fn default_sigterm() -> Signal {
1320    Signal(nix::sys::signal::Signal::SIGTERM)
1321}
1322
1323/// Helper function for serde default `Some(0)` values.
1324fn default_some_time_0() -> Option<units::Time<units::TimePrefix>> {
1325    Some(units::Time::new(0, units::TimePrefix::Sec))
1326}
1327
1328/// Helper function for serde default `Some(true)` values.
1329fn default_some_true() -> Option<bool> {
1330    Some(true)
1331}
1332
1333/// Helper function for serde default `Some(false)` values.
1334fn default_some_false() -> Option<bool> {
1335    Some(false)
1336}
1337
1338/// Helper function for serde default `Some(0)` values.
1339fn default_some_0() -> Option<u32> {
1340    Some(0)
1341}
1342
1343/// Helper function for serde default `Some(1)` values.
1344fn default_some_1() -> Option<u32> {
1345    Some(1)
1346}
1347
1348/// Helper function for serde default `Some(NullableOption::Value(1 sec))` values.
1349fn default_some_nullable_time_1() -> Option<NullableOption<units::Time<units::TimePrefix>>> {
1350    let time = units::Time::new(1, units::TimePrefix::Sec);
1351    Some(NullableOption::Value(time))
1352}
1353
1354/// Helper function for serde default `Some(LogLevel::Info)` values.
1355fn default_some_info() -> Option<LogLevel> {
1356    Some(LogLevel::Info)
1357}
1358
1359// when updating this graph, make sure to also update the copy in docs/shadow_config_spec.md
1360pub const ONE_GBIT_SWITCH_GRAPH: &str = r#"graph [
1361  directed 0
1362  node [
1363    id 0
1364    host_bandwidth_up "1 Gbit"
1365    host_bandwidth_down "1 Gbit"
1366  ]
1367  edge [
1368    source 0
1369    target 0
1370    latency "1 ms"
1371    packet_loss 0.0
1372  ]
1373]"#;
1374
1375/// Generate help strings for objects in a JSON schema, including the Serde defaults if available.
1376fn generate_help_strs(schema: schemars::Schema) -> std::collections::HashMap<String, String> {
1377    // the default for each field
1378    let mut defaults = std::collections::HashMap::<String, String>::new();
1379
1380    // for each field with an entry in "properties"
1381    for (name, obj) in schema.get("properties").unwrap().as_object().unwrap() {
1382        let description = obj
1383            .get("description")
1384            .map(|x| x.as_str().unwrap())
1385            .unwrap_or("");
1386
1387        // schemars gives us the raw doc string, so there is no markdown formatting/rendering
1388        // applied. This means that line breaks aren't collapsed and our help text will have
1389        // unintended line breaks.
1390        //
1391        // We don't want to bring in an entire markdown parser here, so we crudely remove the line
1392        // breaks manually. This will cause issues where there are intended line breaks (lines
1393        // ending with two spaces), new paragraphs ('\n\n'), etc. But hopefully this is good enough
1394        // for now.
1395        //
1396        // See https://github.com/GREsau/schemars/issues/120
1397        let description = description.replace("\n", " ");
1398
1399        let name = name.clone();
1400
1401        match obj.get("default") {
1402            Some(default) => {
1403                let space = if !description.is_empty() { " " } else { "" };
1404                defaults.insert(name, format!("{description}{space}[default: {default}]"))
1405            }
1406            None => defaults.insert(name, description.to_string()),
1407        };
1408    }
1409
1410    defaults
1411}
1412
1413/// Parses a string as a list of arguments following the shell's parsing rules. This
1414/// uses `g_shell_parse_argv()` for parsing.
1415pub fn parse_string_as_args(args_str: &OsStr) -> Result<Vec<OsString>, String> {
1416    if args_str.is_empty() {
1417        return Ok(Vec::new());
1418    }
1419
1420    let args_str = CString::new(args_str.as_bytes()).unwrap();
1421
1422    // parse the argument string
1423    let mut argc: libc::c_int = 0;
1424    let mut argv: *mut *mut libc::c_char = std::ptr::null_mut();
1425    let mut error: *mut libc::c_char = std::ptr::null_mut();
1426    let rv = unsafe { c::process_parseArgStr(args_str.as_ptr(), &mut argc, &mut argv, &mut error) };
1427
1428    // if there was an error, return a copy of the error string
1429    if !rv {
1430        let error_message = match error.is_null() {
1431            false => unsafe { CStr::from_ptr(error) }.to_str().unwrap(),
1432            true => "Unknown parsing error",
1433        }
1434        .to_string();
1435
1436        unsafe { c::process_parseArgStrFree(argv, error) };
1437        return Err(error_message);
1438    }
1439
1440    assert!(!argv.is_null());
1441
1442    // copy the arg strings
1443    let args: Vec<_> = (0..argc)
1444        .map(|x| unsafe {
1445            let arg_ptr = *argv.add(x as usize);
1446            assert!(!arg_ptr.is_null());
1447            OsStr::from_bytes(CStr::from_ptr(arg_ptr).to_bytes()).to_os_string()
1448        })
1449        .collect();
1450
1451    unsafe { c::process_parseArgStrFree(argv, error) };
1452    Ok(args)
1453}
1454
1455#[cfg(test)]
1456mod tests {
1457    use super::*;
1458
1459    #[test]
1460    // can't call foreign function: process_parseArgStr
1461    #[cfg_attr(miri, ignore)]
1462    fn test_parse_args() {
1463        let arg_str = r#"the quick brown fox "jumped over" the "\"lazy\" dog""#;
1464        let expected_args = &[
1465            "the",
1466            "quick",
1467            "brown",
1468            "fox",
1469            "jumped over",
1470            "the",
1471            "\"lazy\" dog",
1472        ];
1473
1474        let arg_str: OsString = arg_str.into();
1475        let args = parse_string_as_args(&arg_str).unwrap();
1476
1477        assert_eq!(args, expected_args);
1478    }
1479
1480    #[test]
1481    // can't call foreign function: process_parseArgStr
1482    #[cfg_attr(miri, ignore)]
1483    fn test_parse_args_empty() {
1484        let arg_str = "";
1485        let expected_args: &[&str] = &[];
1486
1487        let arg_str: OsString = arg_str.into();
1488        let args = parse_string_as_args(&arg_str).unwrap();
1489
1490        assert_eq!(args, expected_args);
1491    }
1492
1493    #[test]
1494    // can't call foreign function: process_parseArgStr
1495    #[cfg_attr(miri, ignore)]
1496    fn test_parse_args_error() {
1497        let arg_str = r#"hello "world"#;
1498
1499        let arg_str: OsString = arg_str.into();
1500        let err_str = parse_string_as_args(&arg_str).unwrap_err();
1501
1502        assert!(!err_str.is_empty());
1503    }
1504
1505    #[test]
1506    // can't call foreign function: process_parseArgStr
1507    #[cfg_attr(miri, ignore)]
1508    fn test_nullable_option() {
1509        // format the yaml with an optional general option
1510        let yaml_fmt_fn = |option| {
1511            format!(
1512                r#"
1513                general:
1514                  stop_time: 1 min
1515                  {option}
1516                network:
1517                  graph:
1518                    type: 1_gbit_switch
1519                hosts:
1520                  myhost:
1521                    network_node_id: 0
1522                    processes:
1523                    - path: /bin/true
1524                "#,
1525            )
1526        };
1527
1528        let time_1_sec = units::Time::new(1, units::TimePrefix::Sec);
1529        let time_5_sec = units::Time::new(5, units::TimePrefix::Sec);
1530
1531        // "heartbeat_interval: null" with no cli option => None
1532        let yaml = yaml_fmt_fn("heartbeat_interval: null");
1533        let config_file: ConfigFileOptions = serde_yaml::from_str(&yaml).unwrap();
1534        let cli: CliOptions = CliOptions::try_parse_from(["shadow", "-"]).unwrap();
1535
1536        let merged = ConfigOptions::new(config_file, cli);
1537        assert_eq!(merged.general.heartbeat_interval, None);
1538
1539        // "heartbeat_interval: null" with "--heartbeat-interval 5s" => 5s
1540        let yaml = yaml_fmt_fn("heartbeat_interval: null");
1541        let config_file: ConfigFileOptions = serde_yaml::from_str(&yaml).unwrap();
1542        let cli: CliOptions =
1543            CliOptions::try_parse_from(["shadow", "--heartbeat-interval", "5s", "-"]).unwrap();
1544
1545        let merged = ConfigOptions::new(config_file, cli);
1546        assert_eq!(
1547            merged.general.heartbeat_interval,
1548            Some(NullableOption::Value(time_5_sec))
1549        );
1550
1551        // "heartbeat_interval: null" with "--heartbeat-interval null" => NullableOption::Null
1552        let yaml = yaml_fmt_fn("heartbeat_interval: null");
1553        let config_file: ConfigFileOptions = serde_yaml::from_str(&yaml).unwrap();
1554        let cli: CliOptions =
1555            CliOptions::try_parse_from(["shadow", "--heartbeat-interval", "null", "-"]).unwrap();
1556
1557        let merged = ConfigOptions::new(config_file, cli);
1558        assert_eq!(
1559            merged.general.heartbeat_interval,
1560            Some(NullableOption::Null)
1561        );
1562
1563        // "heartbeat_interval: 5s" with no cli option => 5s
1564        let yaml = yaml_fmt_fn("heartbeat_interval: 5s");
1565        let config_file: ConfigFileOptions = serde_yaml::from_str(&yaml).unwrap();
1566        let cli: CliOptions = CliOptions::try_parse_from(["shadow", "-"]).unwrap();
1567
1568        let merged = ConfigOptions::new(config_file, cli);
1569        assert_eq!(
1570            merged.general.heartbeat_interval,
1571            Some(NullableOption::Value(time_5_sec))
1572        );
1573
1574        // "heartbeat_interval: 5s" with "--heartbeat-interval 5s" => 5s
1575        let yaml = yaml_fmt_fn("heartbeat_interval: 5s");
1576        let config_file: ConfigFileOptions = serde_yaml::from_str(&yaml).unwrap();
1577        let cli: CliOptions =
1578            CliOptions::try_parse_from(["shadow", "--heartbeat-interval", "5s", "-"]).unwrap();
1579
1580        let merged = ConfigOptions::new(config_file, cli);
1581        assert_eq!(
1582            merged.general.heartbeat_interval,
1583            Some(NullableOption::Value(time_5_sec))
1584        );
1585
1586        // "heartbeat_interval: 5s" with "--heartbeat-interval null" => NullableOption::Null
1587        let yaml = yaml_fmt_fn("heartbeat_interval: 5s");
1588        let config_file: ConfigFileOptions = serde_yaml::from_str(&yaml).unwrap();
1589        let cli: CliOptions =
1590            CliOptions::try_parse_from(["shadow", "--heartbeat-interval", "null", "-"]).unwrap();
1591
1592        let merged = ConfigOptions::new(config_file, cli);
1593        assert_eq!(
1594            merged.general.heartbeat_interval,
1595            Some(NullableOption::Null)
1596        );
1597
1598        // no config option with no cli option => 1s (default)
1599        let yaml = yaml_fmt_fn("");
1600        let config_file: ConfigFileOptions = serde_yaml::from_str(&yaml).unwrap();
1601        let cli: CliOptions = CliOptions::try_parse_from(["shadow", "-"]).unwrap();
1602
1603        let merged = ConfigOptions::new(config_file, cli);
1604        assert_eq!(
1605            merged.general.heartbeat_interval,
1606            Some(NullableOption::Value(time_1_sec))
1607        );
1608
1609        // no config option with "--heartbeat-interval 5s" => 5s
1610        let yaml = yaml_fmt_fn("");
1611        let config_file: ConfigFileOptions = serde_yaml::from_str(&yaml).unwrap();
1612        let cli: CliOptions =
1613            CliOptions::try_parse_from(["shadow", "--heartbeat-interval", "5s", "-"]).unwrap();
1614
1615        let merged = ConfigOptions::new(config_file, cli);
1616        assert_eq!(
1617            merged.general.heartbeat_interval,
1618            Some(NullableOption::Value(time_5_sec))
1619        );
1620
1621        // no config option with "--heartbeat-interval null" => NullableOption::Null
1622        let yaml = yaml_fmt_fn("");
1623        let config_file: ConfigFileOptions = serde_yaml::from_str(&yaml).unwrap();
1624        let cli: CliOptions =
1625            CliOptions::try_parse_from(["shadow", "--heartbeat-interval", "null", "-"]).unwrap();
1626
1627        let merged = ConfigOptions::new(config_file, cli);
1628        assert_eq!(
1629            merged.general.heartbeat_interval,
1630            Some(NullableOption::Null)
1631        );
1632    }
1633}
shadow_rs/core/configuration.rs

shadow_rs/core/
configuration.rs
