[Libguestfs] [PATCH] builder: add a doc snippet about firstboot scripts

Document basic information about them for Linux and Windows guests. --- builder/virt-builder.pod | 36 ++++++++++++++++++++++++++++++++++++ generator/customize.ml | 6 ++++++ 2 files changed, 42 insertions(+) diff --git a/builder/virt-builder.pod b/builder/virt-builder.pod index b68845b..f44c165 100644 --- a/builder/virt-builder.pod +++ b/builder/virt-builder.pod @@ -805,6 +805,42 @@ In any case, the C<~USER/.ssh> directory and the C<~USER/.ssh/authorized_keys> file will be created if not existing already. +=head2 FIRST BOOT SCRIPTS + +The I<--firstboot> and I<--firstboot-command> options allow to execute +commands at the first boot of the guest. To do so, an init script for +the guest init system is installed, which takes care of running all +the added scripts and commands. + +Supported operating systems are: + +=over 4 + +=item Linux + +Init systems supported are: systemd, System-V init (known also as sysvinit), +and Upstart (using the System-V scripts). + +Note that usually init scripts run as root, but with a more limited +environment than what could be available from a normal shell: +for example, C<$HOME> may be unset or empty. + +=item Windows + +F<rhsrvany.exe>, available from sources at +L<https://github.com/rwmjones/rhsrvany>, is installed to run the +first boot scripts. It is required, and the setup of first boot +scripts will fail if it is not present. + +F<rhsrvany.exe> is copied from the location pointed to by the +C<VIRT_TOOLS_DATA_DIR> environment variable; if not set, a compiled-in +default will be used (something like "/usr/share/virt-tools"). + +=back + +The output of the first boot scripts is available in the guest as +F<~root/virt-sysprep-firstboot.log>. + =head2 INSTALLATION PROCESS When you invoke virt-builder, installation proceeds as follows: diff --git a/generator/customize.ml b/generator/customize.ml index 2980d39..f57aba6 100644 --- a/generator/customize.ml +++ b/generator/customize.ml @@ -148,6 +148,9 @@ conveniently wraps the command up in a single line script for you. You can have multiple I<--firstboot> options. They run in the same order that they appear on the command line. +Please take a look at L<virt-builder(1)/FIRST BOOT SCRIPTS> for more +information and caveats about the first boot scripts. + See also I<--run>."; }; @@ -162,6 +165,9 @@ boots up (as root, late in the boot process). You can have multiple I<--firstboot> options. They run in the same order that they appear on the command line. +Please take a look at L<virt-builder(1)/FIRST BOOT SCRIPTS> for more +information and caveats about the first boot scripts. + See also I<--run>."; }; -- 2.1.0