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

[Fiona Ebner <f.ebner@proxmox.com>]

Am 04.09.26 um 1:51 PM schrieb Dominik Csapak:
> 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.
> 

I too prefer simply disarming the example and using 'warn' instead of
'die'. In almost all cases, existing hook scripts will just continue
working if we add a new phase, so it is much more natural as an example.
People can still adapt it to 'die' if they really prefer.