#[cfg(not(any(
all(
target_os = "linux",
target_env = "gnu",
any(target_arch = "x86_64", target_arch = "aarch64")
),
target_os = "macos",
all(windows, any(target_arch = "x86_64", target_arch = "aarch64"))
)))]
compile_error!(
"snare supports only x86_64/aarch64 Linux (glibc), macOS, and x86_64/aarch64 Windows; \
gate the dependency on `cfg(any(all(target_os = \"linux\", target_env = \"gnu\", \
any(target_arch = \"x86_64\", target_arch = \"aarch64\")), target_os = \"macos\", windows))`"
);
mod clock;
mod dns;
#[cfg(unix)]
mod ethtool;
mod events;
mod executive;
#[cfg(unix)]
mod fabric;
mod faults;
#[cfg(unix)]
mod fs_sim;
#[cfg(unix)]
mod ifaddrs;
#[cfg(windows)]
mod iphlp;
mod limits;
mod netif;
mod netpolicy;
mod netstats;
mod packet;
mod pcapng;
#[cfg(unix)]
mod proclimits;
#[cfg(target_os = "linux")]
mod procnet;
#[cfg(target_os = "linux")]
mod qdisc;
mod random;
mod readiness;
pub mod sched;
mod scope;
mod signals;
#[cfg(unix)]
mod simhost;
mod sockets;
mod stream;
#[cfg(target_os = "linux")]
mod tcp_transport;
mod tester;
#[cfg(unix)]
mod tstamp;
#[cfg(windows)]
mod win_adapter;
#[cfg(windows)]
mod win_host;
#[cfg(windows)]
mod win_net;
#[cfg(windows)]
mod win_sockopt;
use std::sync::Arc;
use std::time::Duration;
#[cfg(unix)]
use snare_interpose::Domain;
use crate::clock::Clock;
#[cfg(unix)]
use crate::clock::ClockLayer;
use crate::scope::SimShared;
pub use dns::{
DnsFailure, DnsPolicy, add_host, remove_host, set_default_dns_policy, set_dns_policy,
};
#[cfg(unix)]
pub use ethtool::{Channels, Coalesce, CoalesceParams, Eee, FlowRule, NicEthtool, Pause, Rings};
pub use events::{
Direction, Fault, LinkFault, RecordedEntry, RecordedEvent, Toward, Transport,
clear_recorded_events, recorded_events,
};
#[cfg(unix)]
pub use fabric::Fabric;
pub use faults::{
ListenerBehavior, inject_icmp_port_unreachable, quiesce, raise_socket_error,
set_listener_behavior,
};
#[cfg(unix)]
pub use fs_sim::{FsBuilder, VirtualFs};
pub use limits::{
Privileges, Rlimit, SysLimits, privileges, set_privileges, set_sys_limits, sys_limits,
};
pub use netif::{
IpNet, NicCounters, NicPolicy, NicSnapshot, NicSpec, ParseIpNetError, Route, RouteChoice,
add_nic, add_route, nic, nic_counters, nics, remove_nic, remove_route, route_lookup, routes,
schedule_link, set_default_route, set_link, set_nic, set_nic_counters, set_nic_policy,
};
pub use netpolicy::{TcpPolicy, UdpPolicy, set_tcp_policy, set_udp_policy};
pub use netstats::{ProtoCounters, TcpCounters, UdpCounters, proto_counters};
pub use packet::{
Bytes, Cr, CrLf, Delimited, Delimiter, Endian, FrameLength, LengthField, LengthPrefixed, Lf,
Line, Packet,
};
pub use signals::{PendingSignal, Signal, SignalDelivery, SignalHandle, SignalOrigin};
#[cfg(unix)]
pub use simhost::{
CAP_IPC_LOCK, CAP_NET_ADMIN, CAP_NET_BIND_SERVICE, CAP_NET_RAW, CAP_SYS_NICE, EasyBuilder,
HostProfile, LinkStats, Nic, PtpCaps, SimHost,
};
#[doc(hidden)]
pub use sockets::__set_pending_error;
pub use sockets::{
Membership, SocketEntry, SocketId, SocketKind, UnmodelledOption, closed_sockets,
inject_socket_drops, set_socket_device, socket_entry, socket_id, socket_table, sockets_bound,
};
pub use tester::{Recorder, Tester, TesterAction, connect_tester, udp_tester};
#[doc(hidden)]
pub use tester::{RunTester as __RunTester, run_testers as __run_testers};
#[cfg(windows)]
pub use win_adapter::{Adapter, AdapterKey, AdvancedProperty, RegValue};
#[cfg(windows)]
pub use win_host::{MmcssTask, PowerThrottling, Sim, SimBuilder, WinHost, WorkingSet};
#[cfg(unix)]
fn with_proc_net(
shared: &Arc<SimShared>,
fs: Arc<dyn snare_interpose::Fs>,
) -> Arc<dyn snare_interpose::Fs> {
#[cfg(target_os = "linux")]
return Arc::new(procnet::FsChain(vec![
Arc::new(procnet::ProcNetFs::new(shared)),
fs,
]));
#[cfg(not(target_os = "linux"))]
{
let _ = shared;
fs
}
}
pub use snare_interpose::real;
#[cfg(unix)]
pub struct Sim {
domain: Domain,
shared: Arc<SimShared>,
_fabric: Arc<Fabric>,
_fs: Option<Arc<VirtualFs>>,
_host: Option<Arc<SimHost>>,
_forward: Option<signals::forward::Registration>,
}
#[cfg(unix)]
impl std::fmt::Debug for Sim {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("Sim")
.field("id", &self.domain.id())
.finish_non_exhaustive()
}
}
#[cfg(unix)]
impl Drop for Sim {
fn drop(&mut self) {
if let Some(capture) = self.shared.capture() {
capture.finish();
}
}
}
#[cfg(unix)]
impl Default for Sim {
fn default() -> Self {
Self::new()
}
}
#[cfg(unix)]
impl Sim {
pub fn new() -> Self {
Self::builder().build()
}
pub fn builder() -> SimBuilder {
SimBuilder::default()
}
pub fn run<R>(&self, f: impl FnOnce() -> R) -> R {
let _registries = fabric::enter(self._fabric.registries());
self.domain.run(f)
}
#[track_caller]
pub fn pause_time(&self) {
self.time().pause();
}
#[track_caller]
pub fn resume_time(&self) {
self.time().resume();
}
#[track_caller]
pub fn advance_time(&self, by: Duration) {
self.time().advance(by);
}
#[track_caller]
pub fn set_time_rate(&self, rate: f64) {
self.time().set_rate(rate);
}
#[track_caller]
pub fn time_rate(&self) -> f64 {
self.time().rate()
}
#[track_caller]
pub fn set_time_value(&self, value: Duration) {
self.time().set_value(value);
}
#[track_caller]
pub fn time_value(&self) -> Duration {
self.time().value()
}
#[track_caller]
pub fn time(&self) -> TimeHandle {
self.shared.time()
}
pub fn recorded_events(&self) -> Vec<RecordedEntry> {
self.shared.events.snapshot()
}
pub fn clear_recorded_events(&self) {
self.shared.events.clear();
}
pub fn pcapng_path(&self) -> Option<&std::path::Path> {
self.shared.capture().map(|c| c.path())
}
pub fn socket_entry(&self, id: SocketId) -> Option<SocketEntry> {
self.shared.socket_entry(id)
}
pub fn socket_table(&self) -> Vec<SocketEntry> {
self.shared.socket_table()
}
pub fn closed_sockets(&self) -> Vec<SocketEntry> {
self.shared.closed_sockets()
}
pub fn inject_socket_drops(&self, id: SocketId, n: u32) -> std::io::Result<()> {
self.shared.inject_socket_drops(id, n)
}
pub fn set_socket_device(&self, id: SocketId, nic: Option<&str>) -> std::io::Result<()> {
self.shared.set_socket_device(id, nic)
}
pub fn proto_counters(&self) -> ProtoCounters {
self.shared.proto_counters()
}
pub fn privileges(&self) -> Privileges {
self.shared.sys.privileges()
}
pub fn set_privileges(&self, change: impl FnOnce(&mut Privileges)) {
self.shared.sys.set_privileges(change);
}
pub fn sys_limits(&self) -> SysLimits {
self.shared.sys.limits()
}
pub fn set_sys_limits(&self, change: impl FnOnce(&mut SysLimits)) {
self.shared.sys.set_limits(change);
}
pub fn add_nic(&self, spec: NicSpec) -> std::io::Result<u32> {
self.shared.add_nic(spec)
}
pub fn remove_nic(&self, name: &str) -> std::io::Result<()> {
self.shared.remove_nic(name)
}
pub fn set_nic(&self, name: &str, change: impl FnOnce(&mut NicSpec)) -> std::io::Result<()> {
self.shared.set_nic(name, change)
}
pub fn set_link(&self, name: &str, carrier: bool) -> std::io::Result<()> {
self.shared.set_link(name, carrier)
}
pub fn schedule_link(&self, name: &str, after: Duration, carrier: bool) -> std::io::Result<()> {
self.shared.schedule_link(name, after, carrier)
}
pub fn set_nic_policy(
&self,
name: &str,
change: impl FnOnce(&mut NicPolicy),
) -> std::io::Result<()> {
self.shared.set_nic_policy(name, change)
}
pub fn set_nic_counters(
&self,
name: &str,
change: impl FnOnce(&mut NicCounters),
) -> std::io::Result<()> {
self.shared.set_nic_counters(name, change)
}
pub fn nic(&self, name: &str) -> Option<NicSnapshot> {
self.shared.nic(name)
}
pub fn nics(&self) -> Vec<NicSnapshot> {
self.shared.nics()
}
pub fn nic_counters(&self, name: &str) -> Option<NicCounters> {
self.shared.nic_counters(name)
}
pub fn add_route(&self, route: Route) -> std::io::Result<()> {
self.shared.add_route(route)
}
pub fn remove_route(&self, dest: IpNet) -> bool {
self.shared.remove_route(dest)
}
pub fn set_default_route(&self, nic: Option<&str>) -> std::io::Result<()> {
self.shared.set_default_route(nic)
}
pub fn routes(&self) -> Vec<Route> {
self.shared.routes()
}
pub fn route_lookup(
&self,
src: Option<std::net::IpAddr>,
dst: std::net::IpAddr,
) -> std::io::Result<RouteChoice> {
self.shared.route_lookup(src, dst)
}
pub fn busy(&self, label: &'static str) -> sched::BusyLease {
sched::BusyLease::take(self.domain.clone(), label)
}
pub fn held_leases(&self) -> Vec<sched::LeaseInfo> {
self.domain.leases()
}
pub fn id(&self) -> sched::SimId {
self.domain.id()
}
pub fn thread_census(&self) -> Option<sched::ThreadCensus> {
snare_interpose::census(Some(&self.domain))
}
pub fn add_host(&self, name: &str, addrs: impl IntoIterator<Item = std::net::IpAddr>) {
self.shared.dns.add(name, addrs);
}
pub fn remove_host(&self, name: &str) {
self.shared.dns.remove(name);
}
pub fn set_dns_policy(&self, name: &str, change: impl FnOnce(&mut DnsPolicy)) {
self.shared.dns.update_policy(name, change);
}
pub fn set_default_dns_policy(&self, change: impl FnOnce(&mut DnsPolicy)) {
self.shared.dns.update_default_policy(change);
}
pub fn raise_signal(&self, signal: Signal) -> SignalDelivery {
self.signals().raise(signal)
}
pub fn raise_signal_after(&self, signal: Signal, delay: Duration) -> PendingSignal {
self.signals().raise_after(signal, delay)
}
pub fn signals(&self) -> SignalHandle {
SignalHandle::new(self.shared.clone())
}
pub fn set_listener_behavior(
&self,
addr: impl std::net::ToSocketAddrs,
behavior: ListenerBehavior,
) {
faults::set_listener_behavior_on(&self.shared, addr, behavior);
}
pub fn raise_socket_error(&self, addr: impl std::net::ToSocketAddrs, error: std::io::Error) {
crate::faults::raise_socket_error_on(&self.shared, addr, error);
}
pub fn inject_icmp_port_unreachable(
&self,
to: impl std::net::ToSocketAddrs,
from: impl std::net::ToSocketAddrs,
) {
crate::faults::inject_icmp_on(&self.shared, to, from);
}
pub fn quiesce(
&self,
addr: impl std::net::ToSocketAddrs,
span: Duration,
direction: crate::Direction,
) {
crate::faults::quiesce_on(&self.shared, addr, span, direction);
}
pub fn set_tcp_policy(
&self,
addr: impl std::net::ToSocketAddrs,
change: impl FnOnce(&mut crate::TcpPolicy),
) {
crate::netpolicy::set_tcp_policy_on(&self.shared, addr, change);
}
pub fn set_udp_policy(
&self,
addr: impl std::net::ToSocketAddrs,
change: impl FnOnce(&mut crate::UdpPolicy),
) {
crate::netpolicy::set_udp_policy_on(&self.shared, addr, change);
}
pub fn executive(
&self,
cfg: sched::ExecutiveConfig,
) -> Result<sched::Executive, sched::AttachError> {
executive::attach_to(self.shared.clone(), self.domain.clone(), cfg)
}
}
#[derive(Clone)]
pub struct TimeHandle {
clock: Arc<Clock>,
shared: Arc<SimShared>,
}
impl std::fmt::Debug for TimeHandle {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("TimeHandle")
.field("now", &self.clock.value())
.finish_non_exhaustive()
}
}
impl TimeHandle {
#[track_caller]
fn write(&self, op: impl FnOnce(&Clock)) {
self.shared.assert_clock_free();
snare_interpose::real(|| op(&self.clock));
self.shared.kick();
}
#[track_caller]
pub fn pause(&self) {
self.write(Clock::pause);
}
#[track_caller]
pub fn resume(&self) {
self.write(Clock::resume);
}
#[track_caller]
pub fn advance(&self, by: Duration) {
self.write(|clock| clock.advance_by(by));
}
#[track_caller]
pub fn set_rate(&self, rate: f64) {
self.shared.assert_clock_free();
self.clock.check_rate(rate);
self.write(|clock| clock.set_rate(rate));
}
pub fn rate(&self) -> f64 {
self.clock.rate()
}
#[track_caller]
pub fn set_value(&self, value: Duration) {
self.shared.assert_clock_free();
if let Err(now) = snare_interpose::real(|| self.clock.set_value(value)) {
panic!("time is monotonic: cannot set the clock back from {now:?} to {value:?}");
}
self.shared.kick();
}
pub fn value(&self) -> Duration {
self.clock.value()
}
pub fn is_paused(&self) -> bool {
self.clock.is_paused()
}
}
#[track_caller]
pub fn time() -> TimeHandle {
scope::here().time()
}
#[cfg(unix)]
#[derive(Default)]
pub struct SimBuilder {
fs: Option<Arc<VirtualFs>>,
host: Option<Arc<SimHost>>,
wall_clock: bool,
time_rate: Option<f64>,
seed: u64,
deterministic: bool,
quiet: bool,
nics: Vec<NicSpec>,
routes: Vec<Route>,
dns: dns::DnsSetup,
forward_signals: bool,
privileges: Option<Privileges>,
sys_limits: Option<SysLimits>,
pcapng: Option<std::path::PathBuf>,
pcapng_wall_comment: bool,
stuck_after: Option<Duration>,
strict_sockopts: bool,
#[cfg(target_os = "linux")]
rx_timestamp_startup_delay: Duration,
}
#[cfg(unix)]
impl SimBuilder {
pub fn privileges(mut self, privileges: Privileges) -> Self {
self.privileges = Some(privileges);
self
}
pub fn sys_limits(mut self, limits: SysLimits) -> Self {
self.sys_limits = Some(limits);
self
}
#[cfg(target_os = "linux")]
pub fn rx_timestamp_startup_delay(mut self, delay: Duration) -> Self {
self.rx_timestamp_startup_delay = delay;
self
}
pub fn nic(mut self, spec: NicSpec) -> Self {
self.nics.push(spec);
self
}
pub fn route(mut self, route: Route) -> Self {
self.routes.push(route);
self
}
pub fn fs(mut self, fs: Arc<VirtualFs>) -> Self {
self.fs = Some(fs);
self
}
pub fn virtual_clock(mut self) -> Self {
self.wall_clock = false;
self
}
pub fn deterministic(mut self) -> Self {
self.deterministic = true;
self.wall_clock = false;
self
}
pub fn wall_clock(mut self) -> Self {
self.wall_clock = true;
self
}
#[track_caller]
pub fn time_rate(mut self, rate: f64) -> Self {
clock::validate_rate(rate, false);
self.time_rate = Some(rate);
self
}
pub fn seed(mut self, seed: u64) -> Self {
self.seed = seed;
self
}
pub fn host(mut self, host: Arc<SimHost>) -> Self {
self.host = Some(host);
self
}
pub fn record_events(mut self, on: bool) -> Self {
self.quiet = !on;
self
}
pub fn strict_sockopts(mut self) -> Self {
self.strict_sockopts = true;
self
}
pub fn add_host(
mut self,
name: &str,
addrs: impl IntoIterator<Item = std::net::IpAddr>,
) -> Self {
self.dns.add_host(name, addrs);
self
}
pub fn forward_real_signals(mut self) -> Self {
self.forward_signals = true;
self
}
pub fn resolve_real(mut self, name: &str) -> Self {
self.dns.resolve_real(name);
self
}
pub fn real_dns(mut self) -> Self {
self.dns.real_dns();
self
}
pub fn pcapng(mut self, path: impl Into<std::path::PathBuf>) -> Self {
self.pcapng = Some(path.into());
self
}
pub fn pcapng_wall_comment(mut self, on: bool) -> Self {
self.pcapng_wall_comment = on;
self
}
#[track_caller]
pub fn stuck_after(mut self, after: Duration) -> Self {
assert!(!after.is_zero(), "stuck_after must be longer than zero");
self.stuck_after = Some(after);
self
}
#[track_caller]
pub fn build(self) -> Sim {
self.dns.check(self.deterministic);
let virtual_base = !self.wall_clock || self.time_rate.is_some();
let clock = match &self.host {
Some(host) => {
let clock = host.clock();
clock.set_discrete(virtual_base);
Some(clock)
}
None => virtual_base.then(|| Arc::new(Clock::new(37))),
};
if let Some(clock) = &clock {
clock.set_deterministic(self.deterministic);
if let Some(rate) = self.time_rate {
clock.check_rate(rate);
clock.set_rate(rate);
}
}
let shared = SimShared::new(self.seed, clock.clone());
#[cfg(target_os = "linux")]
shared
.rx_timestamp_startup
.set_delay(self.rx_timestamp_startup_delay);
shared.events.set_enabled(!self.quiet);
shared
.strict_sockopts
.store(self.strict_sockopts, std::sync::atomic::Ordering::Relaxed);
crate::pcapng::attach(&shared, self.pcapng, self.pcapng_wall_comment);
let (host_nics, host_routes) = match &self.host {
Some(host) => host.topology_facts(),
None => (Vec::new(), Vec::new()),
};
shared.init_topology(host_nics, host_routes, self.nics, self.routes);
self.dns.apply(&shared);
let fabric = Arc::new(Fabric::new(shared.clone()));
let mut builder = Domain::builder()
.resolver(dns::DnsSetup::resolver(&shared))
.signals(Arc::new(signals::SimSignals(shared.clone())))
.layers([
Arc::new(fabric::ScopeLayer(fabric.registries()))
as Arc<dyn snare_interpose::Layer>,
Arc::new(random::RandomLayer::new(shared.seed)),
]);
if self.deterministic {
builder = builder.deterministic();
}
if let Some(after) = self.stuck_after {
builder = builder.stuck_after(after);
}
if let (None, Some(clock)) = (&self.host, &clock) {
builder = builder
.layers([Arc::new(ClockLayer(clock.clone())) as Arc<dyn snare_interpose::Layer>]);
}
if let Some(host) = &self.host {
host.attach_fabric(fabric.registries());
}
if let Some(privileges) = self.privileges {
shared.sys.set_privileges(|p| *p = privileges);
}
if let Some(limits) = self.sys_limits {
shared.sys.set_limits(|l| *l = limits);
}
if let Some(host) = &self.host {
builder = builder
.layers([host.clock_layer()])
.net(host.clone())
.net(fabric.clone())
.fs(with_proc_net(&shared, host.clone()))
.host(host.clone());
if host.isolate_env() {
builder = builder.env(host.clone());
}
} else {
builder = builder
.net(fabric.clone())
.host(Arc::new(proclimits::ProcHost {
shared: shared.clone(),
}));
builder = match &self.fs {
Some(fs) => builder.fs(with_proc_net(&shared, fs.clone())),
None => builder.fs(with_proc_net(&shared, fabric.clone())),
};
}
let domain = builder.install();
let _ = shared.domain.set(domain.downgrade());
if let Some(clock) = &shared.clock {
clock.set_domain(&domain);
}
let forward = self
.forward_signals
.then(|| signals::forward::register(shared.clone()));
Sim {
domain,
shared,
_fabric: fabric,
_fs: self.fs,
_host: self.host,
_forward: forward,
}
}
}