feat(snapshot): allow vsock uds path override on restore by Swchexit · Pull Request #5323 · firecracker-microvm/firecracker

Swchexit · 2025-07-23T18:12:16Z

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 · 2025-11-14T14:39:28Z

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

JamesC1305 · 2026-01-21T15:51:12Z

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!

JamesC1305 · 2026-03-03T15:32:11Z

Hi @Swchexit,

I've gone ahead and added some tests and documentation to your branch. Hopefully we can get this merged soon :)

Thanks,
James

codecov · 2026-03-03T16:15:42Z

Codecov Report

❌ Patch coverage is 13.63636% with 19 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.08%. Comparing base (d86ae0d) to head (825ba8c).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
src/vmm/src/persist.rs	9.52%	19 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5323      +/-   ##
==========================================
- Coverage   83.13%   83.08%   -0.06%     
==========================================
  Files         277      277              
  Lines       29466    29488      +22     
==========================================
+ Hits        24498    24501       +3     
- Misses       4968     4987      +19

Flag	Coverage Δ
5.10-m5n.metal	`83.37% <13.63%> (-0.06%)`	⬇️
5.10-m6a.metal	`82.70% <13.63%> (-0.06%)`	⬇️
5.10-m6g.metal	`80.09% <13.63%> (-0.06%)`	⬇️
5.10-m6i.metal	`83.37% <13.63%> (-0.07%)`	⬇️
5.10-m7a.metal-48xl	`82.69% <13.63%> (-0.06%)`	⬇️
5.10-m7g.metal	`80.09% <13.63%> (-0.06%)`	⬇️
5.10-m7i.metal-24xl	`83.34% <13.63%> (-0.07%)`	⬇️
5.10-m7i.metal-48xl	`83.34% <13.63%> (-0.07%)`	⬇️
5.10-m8g.metal-24xl	`80.08% <13.63%> (-0.06%)`	⬇️
5.10-m8g.metal-48xl	`80.08% <13.63%> (-0.06%)`	⬇️
5.10-m8i.metal-48xl	`83.34% <13.63%> (-0.07%)`	⬇️
5.10-m8i.metal-96xl	`83.34% <13.63%> (-0.06%)`	⬇️
6.1-m5n.metal	`83.40% <13.63%> (-0.06%)`	⬇️
6.1-m6a.metal	`82.73% <13.63%> (-0.07%)`	⬇️
6.1-m6g.metal	`80.09% <13.63%> (-0.06%)`	⬇️
6.1-m6i.metal	`83.40% <13.63%> (-0.06%)`	⬇️
6.1-m7a.metal-48xl	`82.72% <13.63%> (-0.06%)`	⬇️
6.1-m7g.metal	`80.08% <13.63%> (-0.07%)`	⬇️
6.1-m7i.metal-24xl	`83.41% <13.63%> (-0.07%)`	⬇️
6.1-m7i.metal-48xl	`83.41% <13.63%> (-0.06%)`	⬇️
6.1-m8g.metal-24xl	`80.07% <13.63%> (-0.07%)`	⬇️
6.1-m8g.metal-48xl	`80.08% <13.63%> (-0.06%)`	⬇️
6.1-m8i.metal-48xl	`83.42% <13.63%> (-0.06%)`	⬇️
6.1-m8i.metal-96xl	`83.41% <13.63%> (-0.06%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

This commit introduces the ability to override the vsock's backing Unix Domain Socket (UDS) path when restoring a VM from a snapshot. This is useful in scenarios where the original UDS path is not available on the host where the snapshot is being restored, for example when restoring on a different machine. A new `vsock_override` field has been added to the `/snapshot/load` API endpoint to specify the new UDS path. Authored-by: Sheng-Wei (Way) Chen <waychensw@gmail.com> Co-authored-by: James Curtis <jxcurtis@amazon.co.uk> Signed-off-by: James Curtis <jxcurtis@amazon.co.uk>

Add integration tests for overriding the host UDS path used by the vsock device. Signed-off-by: James Curtis <jxcurtis@amazon.co.uk>

Add a section that highlights the new vsock renaming capabilities. It somewhat mirrors the TAP renaming documentation. Signed-off-by: James Curtis <jxcurtis@amazon.co.uk>

Add a changelog entry for UDS renaming that links to the relevant PR and documentation. Signed-off-by: James Curtis <jxcurtis@amazon.co.uk>

JamesC1305 · 2026-03-11T16:52:16Z

Thanks for your contribution @Swchexit! @eduardoboucas, this has now landed in main and will be included in the next release (v1.16)!

vsock_override was added in PR firecracker-microvm#5323 which merged after v1.15.1. The cherry-pick of drive_overrides (firecracker-microvm#5774) brought references to vsock_override that don't compile against v1.15.1 base. Removed: persist.rs vsock_override processing block, snapshot.rs test struct field.

Swchexit requested review from Manciukic, kalyazin, pb8o and xmarcalx as code owners July 23, 2025 18:12

Swchexit marked this pull request as draft July 23, 2025 18:12

Swchexit mentioned this pull request Jul 23, 2025

[Feature Request] Support changing the vsock CID on snapshot restore #3344

Closed

3 tasks

Manciukic assigned bchalios Jul 30, 2025

bchalios reviewed Nov 12, 2025

View reviewed changes

JamesC1305 assigned JamesC1305 and unassigned bchalios Jan 21, 2026

JamesC1305 force-pushed the vsock-uds-override branch from 206dbfb to 66ee60f Compare March 3, 2026 15:30

JamesC1305 marked this pull request as ready for review March 3, 2026 15:33

JamesC1305 added Status: WIP Indicates that an issue is currently being worked on or triaged and removed Status: WIP Indicates that an issue is currently being worked on or triaged labels Mar 3, 2026

JamesC1305 changed the title ~~[RFC] feat(snapshot): allow vsock uds path override on restore~~ feat(snapshot): allow vsock uds path override on restore Mar 3, 2026

JamesC1305 force-pushed the vsock-uds-override branch from 66ee60f to d0a857b Compare March 3, 2026 16:06

JamesC1305 added the Status: Awaiting review Indicates that a pull request is ready to be reviewed label Mar 3, 2026

JackThomson2 reviewed Mar 3, 2026

View reviewed changes

Comment thread tests/integration_tests/functional/test_vsock.py

JamesC1305 force-pushed the vsock-uds-override branch 3 times, most recently from a074abd to 3ea9476 Compare March 5, 2026 15:00

Swchexit and others added 4 commits March 5, 2026 16:03

tests(snapshot): add tests for vsock uds path override

f8ea5f6

Add integration tests for overriding the host UDS path used by the vsock device. Signed-off-by: James Curtis <jxcurtis@amazon.co.uk>

docs(vsock): add a section for UDS renaming

df67404

Add a section that highlights the new vsock renaming capabilities. It somewhat mirrors the TAP renaming documentation. Signed-off-by: James Curtis <jxcurtis@amazon.co.uk>

changelog: add an entry for vsock UDS renaming

2692811

Add a changelog entry for UDS renaming that links to the relevant PR and documentation. Signed-off-by: James Curtis <jxcurtis@amazon.co.uk>

JamesC1305 force-pushed the vsock-uds-override branch from 3ea9476 to 2692811 Compare March 5, 2026 16:03

JackThomson2 approved these changes Mar 10, 2026

View reviewed changes

JackThomson2 and others added 2 commits March 10, 2026 17:06

Merge branch 'main' into vsock-uds-override

6ce057e

Merge branch 'main' into vsock-uds-override

825ba8c

Manciukic approved these changes Mar 11, 2026

View reviewed changes

JamesC1305 enabled auto-merge (rebase) March 11, 2026 16:12

JamesC1305 merged commit 3839f6a into firecracker-microvm:main Mar 11, 2026
6 of 7 checks passed

This was referenced Mar 19, 2026

feat(snapshot): allow block device path override on restore #5774

Open

[Snaps] Drive mounts for block device disk paths during snapshot loading #4014

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(snapshot): allow vsock uds path override on restore#5323

feat(snapshot): allow vsock uds path override on restore#5323
JamesC1305 merged 6 commits intofirecracker-microvm:mainfrom
Swchexit:vsock-uds-override

Swchexit commented Jul 23, 2025 •

edited by JamesC1305

Loading

Uh oh!

bchalios left a comment

Uh oh!

eduardoboucas commented Nov 14, 2025

Uh oh!

JamesC1305 commented Jan 21, 2026

Uh oh!

JamesC1305 commented Mar 3, 2026

Uh oh!

codecov Bot commented Mar 3, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

JamesC1305 commented Mar 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Conversation

Swchexit commented Jul 23, 2025 • edited by JamesC1305 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Reason

License Acceptance

PR Checklist

Uh oh!

bchalios left a comment

Choose a reason for hiding this comment

Uh oh!

eduardoboucas commented Nov 14, 2025

Uh oh!

JamesC1305 commented Jan 21, 2026

Uh oh!

JamesC1305 commented Mar 3, 2026

Uh oh!

codecov Bot commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

JamesC1305 commented Mar 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Swchexit commented Jul 23, 2025 •

edited by JamesC1305

Loading

codecov Bot commented Mar 3, 2026 •

edited

Loading