feat(network): support packet capture file creation

Allows creating packet capture files in the pcap format.

Author: cagatay-y

.github/workflows/ci.yml

@@ -42,24 +42,24 @@ jobs:
       - run: rustup component add clippy
       - name: cargo hack clippy (x86_64)
         run: |
-          cargo hack clippy --package hermit-kernel --each-feature --no-dev-deps --target x86_64-unknown-none --exclude-features dhcpv4,dns,gem-net,net,rtl8139,virtio-net
-          cargo hack clippy --package hermit-kernel --each-feature --no-dev-deps --target x86_64-unknown-none --exclude-features dhcpv4,dns,gem-net,net,rtl8139,virtio-net --features pci
+          cargo hack clippy --package hermit-kernel --each-feature --no-dev-deps --target x86_64-unknown-none --exclude-features dhcpv4,dns,gem-net,net,rtl8139,virtio-net,write-pcap-file
+          cargo hack clippy --package hermit-kernel --each-feature --no-dev-deps --target x86_64-unknown-none --exclude-features dhcpv4,dns,gem-net,net,rtl8139,virtio-net,write-pcap-file --features pci
           cargo hack clippy --package hermit-kernel --each-feature --no-dev-deps --target x86_64-unknown-none --exclude-features gem-net,rtl8139 --features tcp,virtio-net
           cargo hack clippy --package hermit-kernel --each-feature --no-dev-deps --target x86_64-unknown-none --exclude-features gem-net,rtl8139 --features pci,tcp,virtio-net
           cargo hack clippy --package hermit-kernel --each-feature --no-dev-deps --target x86_64-unknown-none --exclude-features gem-net,virtio-net --features tcp,rtl8139
           cargo hack clippy --package hermit-kernel --each-feature --no-dev-deps --target x86_64-unknown-none --exclude-features gem-net,virtio-net --features pci,tcp,rtl8139
       - name: cargo hack clippy (aarch64)
         run: |
-          cargo hack clippy --package hermit-kernel --each-feature --no-dev-deps --target aarch64-unknown-none-softfloat --exclude-features dhcpv4,dns,gem-net,net,rtl8139,virtio-net
-          cargo hack clippy --package hermit-kernel --each-feature --no-dev-deps --target aarch64-unknown-none-softfloat --exclude-features dhcpv4,dns,gem-net,net,rtl8139,virtio-net --features pci
+          cargo hack clippy --package hermit-kernel --each-feature --no-dev-deps --target aarch64-unknown-none-softfloat --exclude-features dhcpv4,dns,gem-net,net,rtl8139,virtio-net,write-pcap-file
+          cargo hack clippy --package hermit-kernel --each-feature --no-dev-deps --target aarch64-unknown-none-softfloat --exclude-features dhcpv4,dns,gem-net,net,rtl8139,virtio-net,write-pcap-file --features pci
           cargo hack clippy --package hermit-kernel --each-feature --no-dev-deps --target aarch64-unknown-none-softfloat --exclude-features gem-net,rtl8139 --features tcp,virtio-net
           cargo hack clippy --package hermit-kernel --each-feature --no-dev-deps --target aarch64-unknown-none-softfloat --exclude-features gem-net,rtl8139 --features pci,tcp,virtio-net
           cargo hack clippy --package hermit-kernel --each-feature --no-dev-deps --target aarch64-unknown-none-softfloat --exclude-features gem-net,virtio-net --features tcp,rtl8139
           cargo hack clippy --package hermit-kernel --each-feature --no-dev-deps --target aarch64-unknown-none-softfloat --exclude-features gem-net,virtio-net --features pci,tcp,rtl8139
       - name: cargo hack clippy (riscv64)
         run: |
-          cargo hack clippy --package hermit-kernel --each-feature --no-dev-deps --target riscv64gc-unknown-none-elf --exclude-features dhcpv4,dns,gem-net,net,rtl8139,virtio-net
-          cargo hack clippy --package hermit-kernel --each-feature --no-dev-deps --target riscv64gc-unknown-none-elf --exclude-features dhcpv4,dns,gem-net,net,rtl8139,virtio-net --features pci
+          cargo hack clippy --package hermit-kernel --each-feature --no-dev-deps --target riscv64gc-unknown-none-elf --exclude-features dhcpv4,dns,gem-net,net,rtl8139,virtio-net,write-pcap-file
+          cargo hack clippy --package hermit-kernel --each-feature --no-dev-deps --target riscv64gc-unknown-none-elf --exclude-features dhcpv4,dns,gem-net,net,rtl8139,virtio-net,write-pcap-file --features pci
           cargo hack clippy --package hermit-kernel --each-feature --no-dev-deps --target riscv64gc-unknown-none-elf --exclude-features gem-net,rtl8139 --features tcp,virtio-net
           cargo hack clippy --package hermit-kernel --each-feature --no-dev-deps --target riscv64gc-unknown-none-elf --exclude-features gem-net,rtl8139 --features pci,tcp,virtio-net
           cargo hack clippy --package hermit-kernel --each-feature --no-dev-deps --target riscv64gc-unknown-none-elf --exclude-features rtl8139,virtio-net --features tcp,gem-net

Cargo.toml

@@ -164,6 +164,12 @@ dns = ["net", "smoltcp", "smoltcp/socket-dns"]
 ## Enables pretty-printing the network traffic to the serial device.
 net-trace = ["smoltcp?/log", "smoltcp?/verbose"]
 
+## Enables generation of packet capture files. The files are placed under the
+## mount point on the host, with the name provided via the HERMIT_PCAP_NAME environment
+## variable, or the device name by default.
+write-pcap-file = []
+
+
 #! ### Network Drivers
 #!
 #! Currently, Hermit does not support multiple network drivers at the same time.

src/executor/device.rs

@@ -13,6 +13,13 @@ use smoltcp::socket::dns;
 use smoltcp::wire::{EthernetAddress, HardwareAddress};
 #[cfg(not(feature = "dhcpv4"))]
 use smoltcp::wire::{IpCidr, Ipv4Address, Ipv4Cidr};
+#[cfg(feature = "write-pcap-file")]
+use {
+	crate::drivers::Driver,
+	crate::fs::File,
+	embedded_io::Write,
+	smoltcp::phy::{PcapMode, PcapSink, PcapWriter},
+};
 
 use super::network::{NetworkInterface, NetworkState};
 use crate::arch;
@@ -42,19 +49,26 @@ impl<'a> NetworkInterface<'a> {
 				feature = "rtl8139",
 				feature = "virtio-net",
 			) => {
-				#[cfg_attr(feature = "net-trace", expect(unused_mut))]
+				#[cfg_attr(any(feature = "net-trace", feature = "write-pcap-file"), expect(unused_mut))]
 				let Some(mut device) = NETWORK_DEVICE.lock().take() else {
 					return NetworkState::InitializationFailed;
 				};
 			}
 			_ => {
-				#[cfg_attr(feature = "net-trace", expect(unused_mut))]
+				#[cfg_attr(any(feature = "net-trace", feature = "write-pcap-file"), expect(unused_mut))]
 				let mut device = LoopbackDriver::new();
 			}
 		}
 
 		let mac = device.get_mac_address();
 
+		#[cfg_attr(feature = "net-trace", expect(unused_mut))]
+		#[cfg(feature = "write-pcap-file")]
+		let mut device = {
+			let default_name = device.get_name();
+			PcapWriter::new(device, FileSink::new(default_name), PcapMode::Both)
+		};
+
 		#[cfg(feature = "net-trace")]
 		let mut device = Tracer::new(device, |timestamp, printer| trace!("{timestamp} {printer}"));
 
@@ -132,3 +146,67 @@ impl<'a> NetworkInterface<'a> {
 		}))
 	}
 }
+
+#[cfg(feature = "write-pcap-file")]
+/// Sink for packet captures. If the file Option is None, the writes are ignored.
+/// This is useful when we fail to create the sink file at runtime.
+pub(in crate::executor) struct FileSink(Option<File>);
+
+#[cfg(feature = "write-pcap-file")]
+impl FileSink {
+	fn new(default_name: &str) -> Self {
+		use core::ops::ControlFlow;
+
+		use crate::errno::Errno;
+
+		let file_name_base = option_env!("HERMIT_PCAP_NAME").unwrap_or(default_name);
+		let mut file_name = format!("{file_name_base}.pcap");
+		let file = (1..)
+			.try_for_each(|i| {
+				let path = format!("/root/{file_name}");
+				match File::create_new(path.as_str()) {
+					Err(Errno::Exist) => {
+						file_name = format!("{file_name_base} ({i}).pcap");
+						ControlFlow::Continue(())
+					}
+					r => ControlFlow::Break(r),
+				}
+			})
+			.break_value()
+			.unwrap();
+
+		if let Err(e) = file {
+			if e == Errno::Noent {
+				error!("/root is not mounted. Are there any mount points for the VM?");
+			}
+			error!(
+				"Error {e:?} encountered while creating the pcap file. No pcap file will be written."
+			);
+		} else {
+			info!(
+				"The packet capture will be written to a file called \"{file_name}\" under the mount point."
+			);
+		}
+
+		FileSink(file.ok())
+	}
+}
+
+#[cfg(feature = "write-pcap-file")]
+impl PcapSink for FileSink {
+	fn write(&mut self, data: &[u8]) {
+		if let Some(file) = self.0.as_mut()
+			&& let Some(err) = file.write(data).err()
+		{
+			error!("Error while writing to the pcap file: {err}");
+		}
+	}
+
+	fn flush(&mut self) {
+		if let Some(file) = self.0.as_mut()
+			&& let Some(err) = file.flush().err()
+		{
+			error!("Error while flushing the pcap file: {err}");
+		}
+	}
+}

src/executor/network.rs

@@ -45,7 +45,11 @@ pub(crate) enum NetworkState<'a> {
 	feature = "virtio-net",
 ))]
 pub(crate) fn network_handler() {
-	NIC.lock().as_nic_mut().unwrap().handle_interrupt();
+	// It is possible for us to receive interrupts before we are done with initializing the network interface.
+	// This may for example be caused by an interrupt that was meant for the filesystem driver.
+	if let Ok(nic) = NIC.lock().as_nic_mut() {
+		nic.handle_interrupt();
+	}
 }
 
 impl<'a> NetworkState<'a> {
@@ -63,13 +67,25 @@ static LOCAL_ENDPOINT: AtomicU16 = AtomicU16::new(0);
 pub(crate) static NIC: InterruptTicketMutex<NetworkState<'_>> =
 	InterruptTicketMutex::new(NetworkState::Missing);
 
+type InterfaceDevice = cfg_select! {
+	all(feature = "net-trace", feature = "write-pcap-file") => {
+		smoltcp::phy::Tracer<smoltcp::phy::PcapWriter<NetworkDevice, crate::executor::device::FileSink>>
+	}
+	feature = "net-trace" => {
+		smoltcp::phy::Tracer<NetworkDevice>
+	}
+	feature = "write-pcap-file" => {
+		smoltcp::phy::PcapWriter<NetworkDevice, crate::executor::device::FileSink>
+	}
+	_ => {
+		NetworkDevice
+	}
+};
+
 pub(crate) struct NetworkInterface<'a> {
 	pub(super) iface: smoltcp::iface::Interface,
 	pub(super) sockets: SocketSet<'a>,
-	#[cfg(feature = "net-trace")]
-	pub(super) device: smoltcp::phy::Tracer<NetworkDevice>,
-	#[cfg(not(feature = "net-trace"))]
-	pub(super) device: NetworkDevice,
+	pub(super) device: InterfaceDevice,
 	#[cfg(feature = "dhcpv4")]
 	pub(super) dhcp_handle: SocketHandle,
 	#[cfg(feature = "dns")]
@@ -368,24 +384,21 @@ impl<'a> NetworkInterface<'a> {
 		feature = "virtio-net",
 	))]
 	fn handle_interrupt(&mut self) {
-		cfg_select! {
-			feature = "net-trace" => {
-				self.device.get_mut().handle_interrupt();
-			}
-			_ => {
-				self.device.handle_interrupt();
-			}
-		}
+		self.get_inner_device().handle_interrupt();
 	}
 
 	pub(crate) fn set_polling_mode(&mut self, value: bool) {
-		cfg_select! {
-			feature = "net-trace" => {
-				self.device.get_mut().set_polling_mode(value);
-			}
-			_ => {
-				self.device.set_polling_mode(value);
-			}
-		}
+		self.get_inner_device().set_polling_mode(value);
+	}
+
+	/// Gets the device inside the [smoltcp::phy::Tracer] and [smoltcp::phy::PcapWriter] layers.
+	fn get_inner_device(&mut self) -> &mut impl NetworkDriver {
+		let device = &mut self.device;
+		#[cfg(feature = "net-trace")]
+		let device = device.get_mut();
+		#[cfg(feature = "write-pcap-file")]
+		let device = device.get_mut();
+
+		device
 	}
 }

src/lib.rs

@@ -175,10 +175,11 @@ extern "C" fn initd(_arg: usize) {
 
 	// Initialize Drivers
 	drivers::init();
+	// The filesystem needs to be initialized before network to allow writing packet captures to a file.
+	fs::init();
 	crate::executor::init();
 
 	syscalls::init();
-	fs::init();
 	#[cfg(feature = "shell")]
 	shell::init();