[v2,6/6] docs/man: Add xenwatchdog manual page

Commit Message

Leigh Brown March 29, 2024, 11:10 a.m. UTC

From: Leigh Brown <[e-mail]>

Add a manual page for xenwatchdogd.

Signed-off-by: Leigh Brown <[e-mail]>
---
 docs/man/xenwatchdogd.8.pod | 54 +++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 docs/man/xenwatchdogd.8.pod

Comments

Anthony PERARD April 9, 2024, 5:03 p.m. UTC | #1

On Fri, Mar 29, 2024 at 11:10:56AM +0000, [e-mail] wrote:
> diff --git a/docs/man/xenwatchdogd.8.pod b/docs/man/xenwatchdogd.8.pod
> new file mode 100644
> index 0000000000..2f6454f183
> --- /dev/null
> +++ b/docs/man/xenwatchdogd.8.pod
> @@ -0,0 +1,54 @@
> +=head1 NAME
> +
> +xenwatchdogd - Xen hypercall based watchdog daemon
> +
> +=head1 SYNOPSIS
> +
> +B<xenwatchdogd> [ I<OPTIONS> ] <I<TIMEOUT>> [ <I<SLEEP>> ]
> +
> +=head1 DESCRIPTION
> +
> +B<xenwatchdogd> arms the Xen watchdog timer to I<TIMEOUT> every I<SLEEP>
> +seconds. If the xenwatchdogd process dies or is delayed for more than
> +I<TIMEOUT> seconds, then Xen will reboot the domain.

Xen will not reboot the domain, it will just kill the domain with
watchdog as explanation. I think the toolstack is in charge of rebooting
the domain. There's a setting for `xl` created VM named
on_watchdog="ACTION", which by default is "destroy". So it's more likely
that the domain will be killed rather than rebooted.

So something like:
    Depending on the configuration for the guest, the domain might be
    destroyed, rebooted, or other. See B<on_watchdog> in xl.cfg(5)

> + If the domain being
> +rebooted is domain 0, the whole system will reboot.

Maybe something like "if B<xenwatchdogd> is running in dom0, the whole
system will reboot". I'm not sure if the host reboot in this case by
default, probably.

> +=head1 SIGNALS
> +
> +B<SIGUSR1> Will cause the program to disarm the watchdog timer and exit,
> +regardless of whether the safe exit option was passed.

"whether B<--safe-exit> option" ..

I think it's better to call-out the option explicitly.

Thanks,

Patch

diff --git a/docs/man/xenwatchdogd.8.pod b/docs/man/xenwatchdogd.8.pod
new file mode 100644
index 0000000000..2f6454f183
--- /dev/null
+++ b/docs/man/xenwatchdogd.8.pod
@@ -0,0 +1,54 @@ 
+=head1 NAME
+
+xenwatchdogd - Xen hypercall based watchdog daemon
+
+=head1 SYNOPSIS
+
+B<xenwatchdogd> [ I<OPTIONS> ] <I<TIMEOUT>> [ <I<SLEEP>> ]
+
+=head1 DESCRIPTION
+
+B<xenwatchdogd> arms the Xen watchdog timer to I<TIMEOUT> every I<SLEEP>
+seconds. If the xenwatchdogd process dies or is delayed for more than
+I<TIMEOUT> seconds, then Xen will reboot the domain. If the domain being
+rebooted is domain 0, the whole system will reboot.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-h>, B<--help>
+
+Display a help message.
+
+=item B<-F>, B<--foreground>
+
+Run in the foreground. The default behaviour is to daemonize.
+
+=item B<-x>, B<--safe-exit>
+
+Disable watchdog on orderly exit. The default behaviour is to arm the
+watchdog to 300 seconds to allow time for the domain to shutdown.  See 
+also the B<SIGNALS> section.
+
+=item B<timeout>
+
+The number of seconds to arm the Xen watchdog timer. This must be set to
+a minimum of two.
+
+=item B<sleep>
+
+The number of seconds to sleep in between calls to arm the Xen watchdog
+timer. This must be at least one second, and less than the I<timeout>
+value. If not specified, it defaults to half the I<timeout> value.
+
+=back
+
+=head1 SIGNALS
+
+B<SIGUSR1> Will cause the program to disarm the watchdog timer and exit,
+regardless of whether the safe exit option was passed.
+
+=head1 AUTHOR
+
+Citrix Ltd and other contributors.