Re: [PATCH docs v4 7/7] examples: add new hookscript phase to example hookscript

[Dominik Csapak <d.csapak@proxmox.com>]

On 9/3/26 10:41 AM, Elias Huhsovitz wrote:
> Comments inline.
> 
> On Tue Aug 25, 2026 at 3:54 PM CEST, Dominik Csapak wrote:
>> qemu-server has a new phase 'post-pci-prepare' that is called for vms
>> with pci passthrough for each device prepared.
>>
>> add that to the example hookscript and explain when it's called and its
>> parameters with a comment.
>>
>> Signed-off-by: Dominik Csapak <d.csapak@proxmox.com>
>> ---
>>   examples/guest-example-hookscript.pl | 29 ++++++++++++++++++++++++++++
>>   1 file changed, 29 insertions(+)
>>
>> diff --git a/examples/guest-example-hookscript.pl b/examples/guest-example-hookscript.pl
>> index 1cce2e3..02e7e7d 100755
>> --- a/examples/guest-example-hookscript.pl
>> +++ b/examples/guest-example-hookscript.pl
>> @@ -31,6 +31,35 @@ if ($phase eq 'pre-start') {
>>       # print "preparations failed, aborting."
>>       # exit(1);
>>   
>> +} elsif ($phase eq 'post-pci-prepare') {
> 
> The example hookscript ends with
> 
>   else {
>       die "got unknown phase '$phase'\n";
>   }	
> 
> Adding this new phase would then result in a breaking change.
> Current hookscripts do not check for 'post-pci-prepare', falling back to
> the else branch causing --> die "got unknown phase '$phase'\n";
> 
> So all vms using a passed-thorugh GPU would have to update their hookscript to respect
> the new phase in order to avoid dying.
> 
> I suggest 3 ways of handling this:
> 
> A:
> 
> Warn users in advance, so they are ready for the switch.
> 
> B:
> 
> Warn users in advance and change the
> 
> do not die at the end of a hookscript, e.g.
> 
>   else {
>       warn "got unknown phase '$phase'\n";
>   }
> 
> (altough this might defeat the purpose of using $stop_on_error=1 when
> executing the hookscript)
> 
> C:
> 
> seperate hookscripts for each phase. You would have
> * pre-start.pl
> * post-pci-prepare.pl
> * post-start.pl
> * pre-stop.pl
> * post-stop.pl
> 
> When no hookscript for a phase (e.g. post-pci-prepare) exists, the
> call to
> 
> PVE::GuestHelpers::exec_hookscript($conf, $vmid, 'post-pci-prepare', 1, $params);
> 
> is never made, treating them optional for each phase.
> 
> Although this would introduce significant overhead for simple uses, it
> would resolve this issue in "cleaner" way IMHO.
> 
> 
> All 3 Options that came to mind are not very elegant. Is there some
> obvious solution that I am missing?


I'd personally argue that this
is fine as is, even if it breaks some vm starts (the admin instantly 
notices that they have to adapt the hookscript)

There shouldn't be too many users with hookscripts and the number that
simply verbatim copied the example are (hopefully) also the minority...

Separate hookscripts seem overkill, especially we'd have to handle
the legacy case of a single hookscript anyway.

disarming the example (downgrade die to warn) makes sense IMO

but maybe @fiona has some more input on this.

> 
> 
>> +
>> +    # Only called for virtual machines, not containers.
>> +    #
>> +    # This phase will be called for each pci device that is passed through,
>> +    # after it was prepared by the Proxmox VE stack. In other words when either
>> +    # * the mdev/vGPU was created
>> +    # * the driver was changed to vfio-pci and the device was reset
>> +    #
>> +    # This phase can be useful to do additional preparation that the Proxmox VE
>> +    # stack does not do, like setting vgpu_params for NVIDIA vGPU.
>> +    #
>> +    # This phase has 3 additional parameters (one optional) given via the environment:
>> +
>> +    # the id from the config, e.g. 'hostpci0'
>> +    my $hostpci_id = $ENV{PVE_HOOK_ID};
>> +
>> +    # the pciid of the passed through device or the underlying device in case of an mdev/vGPU
>> +    # e.g. '0000:01:00.0'
>> +    my $pciid = $ENV{PVE_HOOK_PCIID};
>> +
>> +    # the uuid of the mediated device if it was one,
>> +    # e.g. '00000001-0000-0000-0000-000000008006'
>> +    # This is not set if the pci device is not an mdev.
>> +    my $mdev_uuid = $ENV{PVE_HOOK_MDEV_UUID};
>> +
>> +    print "Prepared PCI device for $hostpci_id with pciid: $pciid.\n";
>> +    print "It is a mediated device with UUID: $mdev_uuid\n" if $mdev_uuid;
>> +
>>   } elsif ($phase eq 'post-start') {
>>   
>>       # Second phase 'post-start' will be executed after the guest
>