[RFC] feat(snapshot): allow vsock uds path override on restore

[Swchexit]

Support overriding vsock UDS path on snapshot restore (as documented in #3344)

This is an RFC. I’d appreciate your feedback on whether this is a viable direction. If it makes sense, I’m happy to follow up with test coverage and documentation.

Changes

• Introduced a new vsock_override field to the /snapshot/load API.
• This field allows users to override the vsock’s uds_path during snapshot restore.
• The guest CID remains unchanged; only the host-facing UDS path is updated.
• No impact on existing behavior unless vsock_override is explicitly used.

Reason

Currently, Firecracker does not support restoring a VM with a vsock device to a new host or environment if the original uds_path is unavailable or in conflict. This prevents cloning snapshots or running multiple restored instances with configured vsocks on the same host.

While the CID is used to construct guest-side packet headers, it’s the Unix domain socket that routes traffic on the host. Since each VM connects to its own UDS socket, multiple VMs can safely share the same CID as long as they use different socket paths.

This patch proposes a minimal change to enable such use cases by allowing the UDS path to be overridden on restore, without requiring changes to the CID. This resolves the snapshot clone limitation described in issue #3344 and aligns with the vsock man page’s expectations around post-migration reattachment.

License Acceptance

By submitting this pull request, I confirm that my contribution is made under
the terms of the Apache 2.0 license. For more information on following Developer
Certificate of Origin and signing off your commits, please check
CONTRIBUTING.md.

PR Checklist

• I have read and understand CONTRIBUTING.md.
• I have run tools/devtool checkbuild --all to verify that the PR passes
  build checks on all supported architectures.
• I have run tools/devtool checkstyle to verify that the PR passes the
  automated style checks.
• I have described what is done in these changes, why they are needed, and
  how they are solving the problem in a clear and encompassing way.

For docs and new tests, I will finish them it this patch seems reasonable

• I have updated any relevant documentation (both in code and in the docs)
  in the PR.
• I have mentioned all user-facing changes in CHANGELOG.md.
• If a specific issue led to this PR, this PR closes the issue.
• When making API changes, I have followed the
  Runbook for Firecracker API changes.
• I have tested all new and changed functionalities in unit tests and/or
  integration tests.
• I have linked an issue to every new TODO.

---

• This functionality cannot be added in rust-vmm.

[bchalios]

The approach LGTM. Could you add tests for this? I'm not sure how easy it would be for you to force the integration tests system to change the UDS path because it is using the jailer, but it'd be nice if we could find a way. At the very least we could add negative tests, e.g. an override when vsock is not present should fail and also unit tests.

[eduardoboucas]

I'd love to see this landing. If there's anything I can do to help, let me know.

[JamesC1305]

Hi @eduardoboucas,

Thank you for your interest in this feature, and apologies for leaving this PR stale for so long! We would be happy to support this feature, we just need some test cases for this (as previously stated).

@Swchexit, are you still working on this? If not, feel free to pick this up @eduardoboucas.

Thank you for your contributions!