Firstboot script documentation #1218

Track2k · 2025-12-03T14:21:01Z

What this PR does / why we need it

Adds documentation for firstboot script usage.

Supported script formats for Windows and Linux guests
Step-by-step script deployment through the migration form
Detailed script execution flow and order of operations
Troubleshooting guide with log file locations and common issues
Links to readily available firstboot scripts

Which issue(s) this PR fixes

(optional, in fixes #<issue number>(, fixes #<issue_number>, ...) format, will close the issue(s) when PR gets merged)

fixes #

Special notes for your reviewer

Testing done

Verified overview accurately describes the Firstboot Script feature and its use cases
Verified supported script formats (Batch for Windows, sh/bash for Linux)
Verified ConfigMap naming convention: firstboot-config-<vmwaremachine-resource-name>
Verified file paths and locations:
1. Windows: C:\Program Files\Guestfs\Firstboot\ directories
2. Linux: /root/virt-sysprep-firstboot.log and /usr/lib/virt-sysprep/scripts/ paths
Verified external script reference links are functional
Verified Guestfs and virt-v2v documentation links are corrrect
Documentation renders properly in markdown preview
All images referenced exist in /public/images/ directory

Added user guide for VMware tool removal and disk-check Signed-off-by: Manjunath <84955053+Track2k@users.noreply.github.com>

bito-code-review · 2025-12-03T14:21:36Z

Bito Automatic Review Skipped - Draft PR

Bito didn't auto-review because this pull request is in draft status.
No action is needed if you didn't intend for the agent to review it. Otherwise, to manually trigger a review, type /review in a comment and save.
You can change draft PR review settings here, or contact your Bito workspace admin at ben@platform9.com.

bito-code-review · 2025-12-03T16:09:37Z

Bito Automatic Review Skipped - Draft PR

Bito didn't auto-review because this pull request is in draft status.
No action is needed if you didn't intend for the agent to review it. Otherwise, to manually trigger a review, type /review in a comment and save.
You can change draft PR review settings here, or contact your Bito workspace admin at ben@platform9.com.

bito-code-review · 2025-12-03T18:03:37Z

Bito Automatic Review Skipped - Draft PR

Bito didn't auto-review because this pull request is in draft status.
No action is needed if you didn't intend for the agent to review it. Otherwise, to manually trigger a review, type /review in a comment and save.
You can change draft PR review settings here, or contact your Bito workspace admin at ben@platform9.com.

bito-code-review · 2025-12-05T11:41:15Z

Bito Automatic Review Skipped - Draft PR

Bito didn't auto-review because this pull request is in draft status.
No action is needed if you didn't intend for the agent to review it. Otherwise, to manually trigger a review, type /review in a comment and save.
You can change draft PR review settings here, or contact your Bito workspace admin at ben@platform9.com.

windsurf-bot

💡 To request another review, post a new comment with "/windsurf-review".

windsurf-bot · 2025-12-11T11:57:32Z

docs/src/content/docs/guides/How-to/firstboot_script_doc.md

+
+| Issue | Location to Check |
+|-------|-------------------|
+| Script Not Executing | `C:\Program Files\Guestfs\log` for errors |


There's an inconsistency in the Windows log path. Line 66 specifies C:\Program Files\Guestfs\log.txt but the troubleshooting table on line 75 refers to C:\Program Files\Guestfs\log. Please ensure the log path is consistent throughout the documentation.

windsurf-bot · 2025-12-11T11:57:32Z

docs/src/content/docs/guides/How-to/firstboot_script_doc.md

+---
+
+***The script's success or failure can be determined by checking its location after migration:***
+1. If the script executed successfully, it will not appear in both: `/usr/lib/virt-sysprep/scripts/` and `/usr/lib/virt-sysprep/scripts-done/`


The explanation for Linux script success/failure status is unclear. Line 105 states that successful scripts "will not appear in both" directories, but doesn't explain where they go. Consider clarifying what actually happens to successful scripts (e.g., are they deleted after execution, moved to another location, etc.).

windsurf-bot · 2025-12-11T11:57:32Z

docs/src/content/docs/guides/How-to/firstboot_script_doc.md

+---
+
+***The script's success or failure can be determined by checking its location after migration:***
+1. If the script executed successfully, it will be moved to: `C:\Program Files\guestfs\Firstboot\scripts-done\`


There's an inconsistency in the capitalization of 'Guestfs' in Windows paths. Line 81 uses lowercase C:\Program Files\guestfs\Firstboot\scripts-done\ while other references use capitalized 'Guestfs'. For consistency, please use the same capitalization throughout the document.

bito-code-review · 2025-12-11T14:21:26Z

Bito Automatic Review Skipped - Files Excluded

Bito didn't auto-review this change because all changed files are in the exclusion list for automatic reviews. No action is needed if you didn't intend for the agent to review it. Otherwise, to manually trigger a review, type /review in a comment and save.
You can change the excluded files settings here, or contact your Bito workspace admin at ben@platform9.com.

Track2k · 2025-12-11T14:43:33Z

@OmkarDeshpande7 / @spai-p9 / @bhavin192 could you please review this PR?

OmkarDeshpande7 · 2025-12-11T15:26:58Z

docs/src/content/docs/guides/How-to/firstboot_script_doc.md

+The script executes **automatically after the migration completes and VM boots for the first time in PCD/OpenStack.**
+
+
+The firstboot Script feature uses [Guestfs](https://libguestfs.org/) (libguestfs) which is a set of tools for accessing and modifying virtual machine disk images. During migration, guestfs runs as part of [virt-v2v in-place](https://libguestfs.org/virt-v2v-in-place.1.html) conversion process which runs inside the v2v-helper pod.


Actually firstboot script does not use guestfish at all.
virt-v2v is the one who just injects the script inside the guest. So the statement "The firstboot Script feature uses Guestfs (libguestfs)" might not be entirely accurate

Ok, while the script is injected by virt-v2v, it is the libguestfs libraries that provide the capability to access the guest filesystem and modify the disk right? and virt-v2v uses these libraries. Correct me if i'm wrong.

@Track2k You are absolutely right. I am just referring to the statement "The firstboot Script feature uses Guestfs (libguestfs)".
The script does not use libguestfs.
virt-v2v uses libguestfs to inject the scripts, that is correct. But scripts do not use libguestfs.

Oh okay, I'll change the statement accordingly. "The firstboot script feature uses virt-v2v to inject the script which internally uses Guestfs libraries. During migration, the process runs inside the v2v-helper pod."

How does it sound @OmkarDeshpande7

OmkarDeshpande7 · 2025-12-11T15:28:09Z

docs/src/content/docs/guides/How-to/firstboot_script_doc.md

+#### 2. Controller Creates ConfigMap
+- The migration controller intercepts the script content
+- Creates a Kubernetes **ConfigMap** with the script data with the name as `firstboot-config-<vmwaremachine-resource-name>`
+- ConfigMap details:
+  - **Key**: `user_firstboot.sh`
+  - **Value**: User-provided script content
+
+#### 3. ConfigMap Mounted to v2v-helper Pod
+- The ConfigMap is mounted as a volume in the **v2v-helper pod**
+- Mount path allows virt-v2v to access the script
+
+#### 4. Guestfs Access and Execution
+- "virt-v2v" reads the script from the mounted ConfigMap
+- Script content is retrieved from the `user_firstboot.sh` key
+- Guestfs adds the scripts by applying changes to the VM disk image
+- When VM boots for the first time in PCD/OpenStack, the script executes automatically


we may not need these impl. details. Yes, good to have them, but it might confuse the users

Will remove this

bito-code-review · 2025-12-11T15:41:28Z

Bito Automatic Review Skipped - Files Excluded

Bito didn't auto-review this change because all changed files are in the exclusion list for automatic reviews. No action is needed if you didn't intend for the agent to review it. Otherwise, to manually trigger a review, type /review in a comment and save.
You can change the excluded files settings here, or contact your Bito workspace admin at ben@platform9.com.

Track2k and others added 6 commits November 28, 2025 20:18

Add files via upload

5d5b5af

Added user guide for VMware tool removal and disk-check Signed-off-by: Manjunath <84955053+Track2k@users.noreply.github.com>

added the firstboot script doc

26e1bd9

updated the firstboot doc

85df44c

updated the firstboot doc

8721c5f

updated the firstboot doc

cf11bd8

added linux-log-content image

54c6124

updated the doc

c72a87c

updated the firstboot_script_doc

90a687b

updated the Doc

3263618

Track2k changed the title ~~Firstboot script doc~~ Firstboot script documentation Dec 11, 2025

Track2k marked this pull request as ready for review December 11, 2025 11:56

windsurf-bot bot reviewed Dec 11, 2025

View reviewed changes

Track2k added 2 commits December 11, 2025 18:46

updated the doc format

75bb782

updated the path

c207eb8

updated the doc

19ddbde

OmkarDeshpande7 reviewed Dec 11, 2025

View reviewed changes

		The script executes automatically after the migration completes and VM boots for the first time in PCD/OpenStack.


		The firstboot Script feature uses [Guestfs](https://libguestfs.org/) (libguestfs) which is a set of tools for accessing and modifying virtual machine disk images. During migration, guestfs runs as part of [virt-v2v in-place](https://libguestfs.org/virt-v2v-in-place.1.html) conversion process which runs inside the v2v-helper pod.

Firstboot script documentation #1218

Are you sure you want to change the base?

Firstboot script documentation #1218

Uh oh!

Conversation

Track2k commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this PR does / why we need it

Which issue(s) this PR fixes

Special notes for your reviewer

Testing done

Uh oh!

bito-code-review bot commented Dec 3, 2025

Uh oh!

bito-code-review bot commented Dec 3, 2025

Uh oh!

bito-code-review bot commented Dec 3, 2025

Uh oh!

bito-code-review bot commented Dec 5, 2025

Uh oh!

windsurf-bot bot left a comment

Choose a reason for hiding this comment

Uh oh!

windsurf-bot bot Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

windsurf-bot bot Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

windsurf-bot bot Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

bito-code-review bot commented Dec 11, 2025

Uh oh!

Track2k commented Dec 11, 2025

Uh oh!

OmkarDeshpande7 Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

Track2k Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

OmkarDeshpande7 Dec 12, 2025

Choose a reason for hiding this comment

Uh oh!

Track2k Dec 12, 2025

Choose a reason for hiding this comment

Uh oh!

OmkarDeshpande7 Dec 11, 2025

Choose a reason for hiding this comment

Uh oh!

Track2k Dec 12, 2025

Choose a reason for hiding this comment

Uh oh!

bito-code-review bot commented Dec 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Track2k commented Dec 3, 2025 •

edited

Loading