feat(gdb): start the gdb server when restoring from a snapshot

Upstream wires gdb only into the boot path; restored microVMs never
started the gdb server. Accept a gdb_socket_path restore-time override
on the load-snapshot request (alongside network_overrides and
clock_realtime) and wire attach_debug_info + gdb_thread into
build_microvm_from_snapshot (x86_64), arming the entry breakpoint at the
restored vCPU RIP so gdb takes control at the resume point.

Carrying the socket on LoadSnapshotParams keeps it a pure restore-time
knob: no machine-config update is needed before the load (which would
forbid the snapshot load), and there is no boot-time value to preserve
across restore. persist sets the restored machine config's
gdb_socket_path from the load param, which the snapshot builder reads.

Also add resolve_gdb_socket_path() with a FIRECRACKER_GDB_SOCKET env
fallback, so launchers that cannot set the load request can still enable
gdb.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: Nikita Kalyazin <nikita.kalyazin@e2b.dev>

Author: kalyazin

src/firecracker/src/api_server/request/snapshot.rs

@@ -119,6 +119,8 @@ fn parse_put_snapshot_load(body: &Body) -> Result<ParsedRequest, RequestError> {
         resume_vm: snapshot_config.resume_vm,
         network_overrides: snapshot_config.network_overrides,
         clock_realtime: snapshot_config.clock_realtime,
+        #[cfg(feature = "gdb")]
+        gdb_socket_path: snapshot_config.gdb_socket_path,
     };
 
     // Construct the `ParsedRequest` object.
@@ -198,6 +200,8 @@ mod tests {
             resume_vm: false,
             network_overrides: vec![],
             clock_realtime: false,
+            #[cfg(feature = "gdb")]
+            gdb_socket_path: None,
         };
         let mut parsed_request = parse_put_snapshot(&Body::new(body), Some("load")).unwrap();
         assert!(
@@ -230,6 +234,8 @@ mod tests {
             resume_vm: false,
             network_overrides: vec![],
             clock_realtime: false,
+            #[cfg(feature = "gdb")]
+            gdb_socket_path: None,
         };
         let mut parsed_request = parse_put_snapshot(&Body::new(body), Some("load")).unwrap();
         assert!(
@@ -262,6 +268,8 @@ mod tests {
             resume_vm: true,
             network_overrides: vec![],
             clock_realtime: false,
+            #[cfg(feature = "gdb")]
+            gdb_socket_path: None,
         };
         let mut parsed_request = parse_put_snapshot(&Body::new(body), Some("load")).unwrap();
         assert!(
@@ -303,6 +311,8 @@ mod tests {
                 host_dev_name: String::from("vmtap2"),
             }],
             clock_realtime: false,
+            #[cfg(feature = "gdb")]
+            gdb_socket_path: None,
         };
         let mut parsed_request = parse_put_snapshot(&Body::new(body), Some("load")).unwrap();
         assert!(
@@ -332,6 +342,8 @@ mod tests {
             resume_vm: true,
             network_overrides: vec![],
             clock_realtime: false,
+            #[cfg(feature = "gdb")]
+            gdb_socket_path: None,
         };
         let parsed_request = parse_put_snapshot(&Body::new(body), Some("load")).unwrap();
         assert_eq!(
@@ -435,6 +447,8 @@ mod tests {
             resume_vm: false,
             network_overrides: vec![],
             clock_realtime: false,
+            #[cfg(feature = "gdb")]
+            gdb_socket_path: None,
         };
         let mut parsed_request = parse_put_snapshot(&Body::new(body), Some("load")).unwrap();
         assert!(

src/firecracker/swagger/firecracker.yaml

@@ -1758,6 +1758,13 @@ definitions:
           elapsed since the snapshot was taken. When false (default), kvmclock resumes
           from where it was at snapshot time. This option may be extended to other clock
           sources and CPU architectures in the future."
+      gdb_socket_path:
+        type: string
+        description:
+          "Only available when Firecracker is built with the `gdb` feature. When set,
+          start the GDB server on this unix socket for the restored guest, for
+          source-level debugging of the guest kernel. Debug builds only; not for
+          production."
 
 
   TokenBucket:

src/vmm/src/builder.rs

@@ -133,6 +133,18 @@ impl std::convert::From<linux_loader::cmdline::Error> for StartMicrovmError {
     }
 }
 
+/// Resolves the GDB unix socket path. An explicit `machine-config.gdb_socket_path`
+/// takes precedence; otherwise fall back to the `FIRECRACKER_GDB_SOCKET` environment
+/// variable. The env fallback lets tooling that launches Firecracker (e.g. the e2b
+/// orchestrator / resume-build, which inherit the environment) enable GDB without
+/// setting machine-config.
+#[cfg(feature = "gdb")]
+fn resolve_gdb_socket_path(configured: &Option<String>) -> Option<String> {
+    configured
+        .clone()
+        .or_else(|| std::env::var("FIRECRACKER_GDB_SOCKET").ok())
+}
+
 /// Builds and starts a microVM based on the current Firecracker VmResources configuration.
 ///
 /// The built microVM and all the created vCPUs start off in the paused state.
@@ -343,9 +355,16 @@ pub fn build_microvm_for_boot(
         .map_err(VmmError::VcpuStart)?;
 
     #[cfg(feature = "gdb")]
-    if let Some(gdb_socket_path) = &vm_resources.machine_config.gdb_socket_path {
-        gdb::gdb_thread(vmm.clone(), gdb_rx, entry_point.entry_addr, gdb_socket_path)
-            .map_err(StartMicrovmError::GdbServer)?;
+    if let Some(gdb_socket_path) =
+        resolve_gdb_socket_path(&vm_resources.machine_config.gdb_socket_path)
+    {
+        gdb::gdb_thread(
+            vmm.clone(),
+            gdb_rx,
+            entry_point.entry_addr,
+            &gdb_socket_path,
+        )
+        .map_err(StartMicrovmError::GdbServer)?;
     } else {
         debug!("No GDB socket provided not starting gdb server.");
     }
@@ -528,6 +547,31 @@ pub fn build_microvm_from_snapshot(
         page_size: vm_resources.machine_config.huge_pages.page_size(),
     };
 
+    // GDB debug support for restored microVMs (x86_64 only). Mirror the boot
+    // path: attach the debug-event channel to every restored vCPU before they
+    // start, then start the GDB server thread once the vCPUs are running. The
+    // server arms a hardware breakpoint at the restored instruction pointer so
+    // GDB takes control at the resume point on the first continue.
+    //
+    // Only wire the channel up when a GDB socket is actually configured: with no
+    // socket, no server thread drains the receiver, so a vCPU debug event would
+    // `send` on a dropped receiver and panic. Gating the attach keeps the channel
+    // paired with its consumer (and leaves the vCPUs' gdb_event as None otherwise).
+    #[cfg(all(feature = "gdb", target_arch = "x86_64"))]
+    let gdb_socket_path =
+        resolve_gdb_socket_path(&vm_resources.machine_config.gdb_socket_path);
+
+    #[cfg(all(feature = "gdb", target_arch = "x86_64"))]
+    let gdb_rx = if gdb_socket_path.is_some() {
+        let (gdb_tx, gdb_rx) = mpsc::channel();
+        vcpus
+            .iter_mut()
+            .for_each(|vcpu| vcpu.attach_debug_info(gdb_tx.clone()));
+        Some(gdb_rx)
+    } else {
+        None
+    };
+
     // Move vcpus to their own threads and start their state machine in the 'Paused' state.
     vmm.start_vcpus(
         vcpus,
@@ -540,6 +584,17 @@ pub fn build_microvm_from_snapshot(
     let vmm = Arc::new(Mutex::new(vmm));
     event_manager.add_subscriber(vmm.clone());
 
+    #[cfg(all(feature = "gdb", target_arch = "x86_64"))]
+    if let Some(gdb_socket_path) = gdb_socket_path {
+        // On restore the vCPUs resume at their saved RIP; arm the entry
+        // breakpoint there so GDB stops at the resume point.
+        let entry_addr = GuestAddress(microvm_state.vcpu_states[0].regs.rip);
+        gdb::gdb_thread(vmm.clone(), gdb_rx.unwrap(), entry_addr, &gdb_socket_path)
+            .map_err(StartMicrovmError::GdbServer)?;
+    } else {
+        debug!("No GDB socket provided not starting gdb server.");
+    }
+
     // Load seccomp filters for the VMM thread.
     // Keep this as the last step of the building process.
     crate::seccomp::apply_filter(

src/vmm/src/persist/mod.rs

@@ -394,8 +394,11 @@ pub fn restore_from_snapshot(
             cpu_template: Some(microvm_state.vm_info.cpu_template),
             track_dirty_pages: Some(track_dirty_pages),
             huge_pages: Some(microvm_state.vm_info.huge_pages),
+            // GDB socket is a restore-time override carried on the load request,
+            // applied here so the restore-path gdb server (which reads
+            // machine_config.gdb_socket_path) starts.
             #[cfg(feature = "gdb")]
-            gdb_socket_path: None,
+            gdb_socket_path: params.gdb_socket_path.clone(),
         })
         .map_err(BuildMicrovmFromSnapshotError::VmUpdateConfig)?;
 

src/vmm/src/rpc_interface.rs

@@ -1443,6 +1443,8 @@ mod tests {
                 resume_vm: false,
                 network_overrides: vec![],
                 clock_realtime: false,
+                #[cfg(feature = "gdb")]
+                gdb_socket_path: None,
             },
         )));
         check_unsupported(runtime_request(VmmAction::SetEntropyDevice(

src/vmm/src/vmm_config/snapshot.rs

@@ -76,6 +76,10 @@ pub struct LoadSnapshotParams {
     /// advancing kvmclock by the wall-clock time elapsed since the snapshot was taken. When false
     /// (default), kvmclock resumes from where it was at snapshot time.
     pub clock_realtime: bool,
+    /// [gdb] When set, start the GDB server on this unix socket for the restored
+    /// guest. A restore-time override (not configured via machine-config).
+    #[cfg(feature = "gdb")]
+    pub gdb_socket_path: Option<String>,
 }
 
 /// Stores the configuration for loading a snapshot that is provided by the user.
@@ -108,6 +112,10 @@ pub struct LoadSnapshotConfig {
     /// [x86_64 only] When set to true, passes `KVM_CLOCK_REALTIME` to `KVM_SET_CLOCK` on restore.
     #[serde(default)]
     pub clock_realtime: bool,
+    /// [gdb] Unix socket path for the GDB server (debug builds only).
+    #[cfg(feature = "gdb")]
+    #[serde(default)]
+    pub gdb_socket_path: Option<String>,
 }
 
 /// Stores the configuration used for managing snapshot memory.

src/vmm/tests/integration_tests.rs

@@ -304,6 +304,8 @@ fn verify_load_snapshot(snapshot_file: TempFile, memory_file: TempFile) {
             resume_vm: true,
             network_overrides: vec![],
             clock_realtime: false,
+            #[cfg(feature = "gdb")]
+            gdb_socket_path: None,
         }))
         .unwrap();
 
@@ -390,6 +392,8 @@ fn verify_load_snap_disallowed_after_boot_resources(res: VmmAction, res_name: &s
         resume_vm: false,
         network_overrides: vec![],
         clock_realtime: false,
+        #[cfg(feature = "gdb")]
+        gdb_socket_path: None,
     });
     let err = preboot_api_controller.handle_preboot_request(req);
     assert!(