[PATCH] docs: man: Unify wording for the description of '--timeout' of daemons
Use a common wording for all various daemons to prevent having to adjust the documentation any further by just outlining that neither clients nor anything else needing the attention of the daemon must be present in order to shut down. Resolves: https://bugzilla.redhat.com/show_bug.cgi?id=2035985 Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/manpages/virtbhyved.rst | 3 ++- docs/manpages/virtinterfaced.rst | 3 ++- docs/manpages/virtlockd.rst | 5 +++-- docs/manpages/virtlogd.rst | 5 +++-- docs/manpages/virtlxcd.rst | 3 ++- docs/manpages/virtnetworkd.rst | 3 ++- docs/manpages/virtnodedevd.rst | 3 ++- docs/manpages/virtnwfilterd.rst | 3 ++- docs/manpages/virtproxyd.rst | 3 ++- docs/manpages/virtqemud.rst | 3 ++- docs/manpages/virtsecretd.rst | 3 ++- docs/manpages/virtstoraged.rst | 3 ++- docs/manpages/virtvboxd.rst | 3 ++- docs/manpages/virtvzd.rst | 3 ++- docs/manpages/virtxend.rst | 3 ++- 15 files changed, 32 insertions(+), 17 deletions(-) diff --git a/docs/manpages/virtbhyved.rst b/docs/manpages/virtbhyved.rst index 9fdaca6da2..2e56514914 100644 --- a/docs/manpages/virtbhyved.rst +++ b/docs/manpages/virtbhyved.rst @@ -61,7 +61,8 @@ Use this name for the PID file, overriding the default value. ``-t``, ``--timeout *SECONDS*`` Exit after timeout period (in seconds), provided there are neither any client -connections nor any running domains. +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon. ``-v``, ``--verbose`` diff --git a/docs/manpages/virtinterfaced.rst b/docs/manpages/virtinterfaced.rst index 5777dba638..9b836b0b12 100644 --- a/docs/manpages/virtinterfaced.rst +++ b/docs/manpages/virtinterfaced.rst @@ -83,7 +83,8 @@ Use this name for the PID file, overriding the default value. ``-t``, ``--timeout *SECONDS*`` Exit after timeout period (in seconds), provided there are neither any client -connections nor any running domains. +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon. ``-v``, ``--verbose`` diff --git a/docs/manpages/virtlockd.rst b/docs/manpages/virtlockd.rst index 0bbee5a5f7..7ea720d1b7 100644 --- a/docs/manpages/virtlockd.rst +++ b/docs/manpages/virtlockd.rst @@ -50,8 +50,9 @@ Use this configuration file, overriding the default value. ``-t``, ``--timeout`` *SECONDS* -Automatically shutdown after *SECONDS* have elapsed with -no active client or lock. +Exit after timeout period (in seconds), provided there are neither any client +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon. ``-p``, ``--pid-file`` *FILE* diff --git a/docs/manpages/virtlogd.rst b/docs/manpages/virtlogd.rst index 1e39ff1b49..0b00595a85 100644 --- a/docs/manpages/virtlogd.rst +++ b/docs/manpages/virtlogd.rst @@ -50,8 +50,9 @@ Use this configuration file, overriding the default value. ``-t``, ``--timeout`` *SECONDS* -Automatically shutdown after *SECONDS* have elapsed with -no active console log. +Exit after timeout period (in seconds), provided there are neither any client +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon. ``-p``, ``--pid-file`` *FILE* diff --git a/docs/manpages/virtlxcd.rst b/docs/manpages/virtlxcd.rst index 2e9d8fd14b..4c9a441d0d 100644 --- a/docs/manpages/virtlxcd.rst +++ b/docs/manpages/virtlxcd.rst @@ -83,7 +83,8 @@ Use this name for the PID file, overriding the default value. ``-t``, ``--timeout *SECONDS*`` Exit after timeout period (in seconds), provided there are neither any client -connections nor any running domains. +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon. ``-v``, ``--verbose`` diff --git a/docs/manpages/virtnetworkd.rst b/docs/manpages/virtnetworkd.rst index 6d9c5e5fa3..b9409723fb 100644 --- a/docs/manpages/virtnetworkd.rst +++ b/docs/manpages/virtnetworkd.rst @@ -83,7 +83,8 @@ Use this name for the PID file, overriding the default value. ``-t``, ``--timeout *SECONDS*`` Exit after timeout period (in seconds), provided there are neither any client -connections nor any running domains. +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon. ``-v``, ``--verbose`` diff --git a/docs/manpages/virtnodedevd.rst b/docs/manpages/virtnodedevd.rst index ef968e486e..1c79529bd8 100644 --- a/docs/manpages/virtnodedevd.rst +++ b/docs/manpages/virtnodedevd.rst @@ -82,7 +82,8 @@ Use this name for the PID file, overriding the default value. ``-t``, ``--timeout *SECONDS*`` Exit after timeout period (in seconds), provided there are neither any client -connections nor any running domains. +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon. ``-v``, ``--verbose`` diff --git a/docs/manpages/virtnwfilterd.rst b/docs/manpages/virtnwfilterd.rst index 4faa6b225d..0690c795d9 100644 --- a/docs/manpages/virtnwfilterd.rst +++ b/docs/manpages/virtnwfilterd.rst @@ -83,7 +83,8 @@ Use this name for the PID file, overriding the default value. ``-t``, ``--timeout *SECONDS*`` Exit after timeout period (in seconds), provided there are neither any client -connections nor any running domains. +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon. ``-v``, ``--verbose`` diff --git a/docs/manpages/virtproxyd.rst b/docs/manpages/virtproxyd.rst index 0366935b9a..918aae6c2b 100644 --- a/docs/manpages/virtproxyd.rst +++ b/docs/manpages/virtproxyd.rst @@ -105,7 +105,8 @@ Use this name for the PID file, overriding the default value. ``-t``, ``--timeout *SECONDS*`` Exit after timeout period (in seconds), provided there are neither any client -connections nor any running domains. +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon. ``-v``, ``--verbose`` diff --git a/docs/manpages/virtqemud.rst b/docs/manpages/virtqemud.rst index ea8d6e3105..f1f1710393 100644 --- a/docs/manpages/virtqemud.rst +++ b/docs/manpages/virtqemud.rst @@ -83,7 +83,8 @@ Use this name for the PID file, overriding the default value. ``-t``, ``--timeout *SECONDS*`` Exit after timeout period (in seconds), provided there are neither any client -connections nor any running domains. +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon. ``-v``, ``--verbose`` diff --git a/docs/manpages/virtsecretd.rst b/docs/manpages/virtsecretd.rst index fffb3a24f6..f35bfb6b5a 100644 --- a/docs/manpages/virtsecretd.rst +++ b/docs/manpages/virtsecretd.rst @@ -82,7 +82,8 @@ Use this name for the PID file, overriding the default value. ``-t``, ``--timeout *SECONDS*`` Exit after timeout period (in seconds), provided there are neither any client -connections nor any running domains. +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon. ``-v``, ``--verbose`` diff --git a/docs/manpages/virtstoraged.rst b/docs/manpages/virtstoraged.rst index 4ceae57e40..ae25a90040 100644 --- a/docs/manpages/virtstoraged.rst +++ b/docs/manpages/virtstoraged.rst @@ -83,7 +83,8 @@ Use this name for the PID file, overriding the default value. ``-t``, ``--timeout *SECONDS*`` Exit after timeout period (in seconds), provided there are neither any client -connections nor any running domains. +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon. ``-v``, ``--verbose`` diff --git a/docs/manpages/virtvboxd.rst b/docs/manpages/virtvboxd.rst index d7339d99f2..0be68d87b8 100644 --- a/docs/manpages/virtvboxd.rst +++ b/docs/manpages/virtvboxd.rst @@ -81,7 +81,8 @@ Use this name for the PID file, overriding the default value. ``-t``, ``--timeout *SECONDS*`` Exit after timeout period (in seconds), provided there are neither any client -connections nor any running domains. +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon. ``-v``, ``--verbose`` diff --git a/docs/manpages/virtvzd.rst b/docs/manpages/virtvzd.rst index 42dfa263e4..d2d6fecce6 100644 --- a/docs/manpages/virtvzd.rst +++ b/docs/manpages/virtvzd.rst @@ -83,7 +83,8 @@ Use this name for the PID file, overriding the default value. ``-t``, ``--timeout *SECONDS*`` Exit after timeout period (in seconds), provided there are neither any client -connections nor any running domains. +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon. ``-v``, ``--verbose`` diff --git a/docs/manpages/virtxend.rst b/docs/manpages/virtxend.rst index b08346b489..d12196956c 100644 --- a/docs/manpages/virtxend.rst +++ b/docs/manpages/virtxend.rst @@ -83,7 +83,8 @@ Use this name for the PID file, overriding the default value. ``-t``, ``--timeout *SECONDS*`` Exit after timeout period (in seconds), provided there are neither any client -connections nor any running domains. +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon. ``-v``, ``--verbose`` -- 2.34.1
On Wed, Jan 19, 2022 at 04:05:05PM +0100, Peter Krempa wrote:
Use a common wording for all various daemons to prevent having to adjust the documentation any further by just outlining that neither clients nor anything else needing the attention of the daemon must be present in order to shut down.
I don't think this is a good idea. The --timeout arg should be specific about exactly what scenarios block timeout for the daemon in question.
Resolves: https://bugzilla.redhat.com/show_bug.cgi?id=2035985
THis bug is reporting that they were expecting virtnetworkd to stay running as long as any domains were still running. ie they thought there was a link between virtqemud and virtnetworkd staying running. The proposed text still leaves that confusion present so doesn't address the problem reported IMHO.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/manpages/virtbhyved.rst | 3 ++- docs/manpages/virtinterfaced.rst | 3 ++- docs/manpages/virtlockd.rst | 5 +++-- docs/manpages/virtlogd.rst | 5 +++-- docs/manpages/virtlxcd.rst | 3 ++- docs/manpages/virtnetworkd.rst | 3 ++- docs/manpages/virtnodedevd.rst | 3 ++- docs/manpages/virtnwfilterd.rst | 3 ++- docs/manpages/virtproxyd.rst | 3 ++- docs/manpages/virtqemud.rst | 3 ++- docs/manpages/virtsecretd.rst | 3 ++- docs/manpages/virtstoraged.rst | 3 ++- docs/manpages/virtvboxd.rst | 3 ++- docs/manpages/virtvzd.rst | 3 ++- docs/manpages/virtxend.rst | 3 ++- 15 files changed, 32 insertions(+), 17 deletions(-)
diff --git a/docs/manpages/virtbhyved.rst b/docs/manpages/virtbhyved.rst index 9fdaca6da2..2e56514914 100644 --- a/docs/manpages/virtbhyved.rst +++ b/docs/manpages/virtbhyved.rst @@ -61,7 +61,8 @@ Use this name for the PID file, overriding the default value. ``-t``, ``--timeout *SECONDS*``
Exit after timeout period (in seconds), provided there are neither any client -connections nor any running domains. +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon.
``-v``, ``--verbose``
diff --git a/docs/manpages/virtinterfaced.rst b/docs/manpages/virtinterfaced.rst index 5777dba638..9b836b0b12 100644 --- a/docs/manpages/virtinterfaced.rst +++ b/docs/manpages/virtinterfaced.rst @@ -83,7 +83,8 @@ Use this name for the PID file, overriding the default value. ``-t``, ``--timeout *SECONDS*``
Exit after timeout period (in seconds), provided there are neither any client -connections nor any running domains. +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon.
``-v``, ``--verbose``
diff --git a/docs/manpages/virtlockd.rst b/docs/manpages/virtlockd.rst index 0bbee5a5f7..7ea720d1b7 100644 --- a/docs/manpages/virtlockd.rst +++ b/docs/manpages/virtlockd.rst @@ -50,8 +50,9 @@ Use this configuration file, overriding the default value.
``-t``, ``--timeout`` *SECONDS*
-Automatically shutdown after *SECONDS* have elapsed with -no active client or lock. +Exit after timeout period (in seconds), provided there are neither any client +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon.
``-p``, ``--pid-file`` *FILE*
diff --git a/docs/manpages/virtlogd.rst b/docs/manpages/virtlogd.rst index 1e39ff1b49..0b00595a85 100644 --- a/docs/manpages/virtlogd.rst +++ b/docs/manpages/virtlogd.rst @@ -50,8 +50,9 @@ Use this configuration file, overriding the default value.
``-t``, ``--timeout`` *SECONDS*
-Automatically shutdown after *SECONDS* have elapsed with -no active console log. +Exit after timeout period (in seconds), provided there are neither any client +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon.
``-p``, ``--pid-file`` *FILE*
diff --git a/docs/manpages/virtlxcd.rst b/docs/manpages/virtlxcd.rst index 2e9d8fd14b..4c9a441d0d 100644 --- a/docs/manpages/virtlxcd.rst +++ b/docs/manpages/virtlxcd.rst @@ -83,7 +83,8 @@ Use this name for the PID file, overriding the default value. ``-t``, ``--timeout *SECONDS*``
Exit after timeout period (in seconds), provided there are neither any client -connections nor any running domains. +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon.
``-v``, ``--verbose``
diff --git a/docs/manpages/virtnetworkd.rst b/docs/manpages/virtnetworkd.rst index 6d9c5e5fa3..b9409723fb 100644 --- a/docs/manpages/virtnetworkd.rst +++ b/docs/manpages/virtnetworkd.rst @@ -83,7 +83,8 @@ Use this name for the PID file, overriding the default value. ``-t``, ``--timeout *SECONDS*``
Exit after timeout period (in seconds), provided there are neither any client -connections nor any running domains. +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon.
``-v``, ``--verbose``
diff --git a/docs/manpages/virtnodedevd.rst b/docs/manpages/virtnodedevd.rst index ef968e486e..1c79529bd8 100644 --- a/docs/manpages/virtnodedevd.rst +++ b/docs/manpages/virtnodedevd.rst @@ -82,7 +82,8 @@ Use this name for the PID file, overriding the default value. ``-t``, ``--timeout *SECONDS*``
Exit after timeout period (in seconds), provided there are neither any client -connections nor any running domains. +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon.
``-v``, ``--verbose``
diff --git a/docs/manpages/virtnwfilterd.rst b/docs/manpages/virtnwfilterd.rst index 4faa6b225d..0690c795d9 100644 --- a/docs/manpages/virtnwfilterd.rst +++ b/docs/manpages/virtnwfilterd.rst @@ -83,7 +83,8 @@ Use this name for the PID file, overriding the default value. ``-t``, ``--timeout *SECONDS*``
Exit after timeout period (in seconds), provided there are neither any client -connections nor any running domains. +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon.
``-v``, ``--verbose``
diff --git a/docs/manpages/virtproxyd.rst b/docs/manpages/virtproxyd.rst index 0366935b9a..918aae6c2b 100644 --- a/docs/manpages/virtproxyd.rst +++ b/docs/manpages/virtproxyd.rst @@ -105,7 +105,8 @@ Use this name for the PID file, overriding the default value. ``-t``, ``--timeout *SECONDS*``
Exit after timeout period (in seconds), provided there are neither any client -connections nor any running domains. +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon.
``-v``, ``--verbose``
diff --git a/docs/manpages/virtqemud.rst b/docs/manpages/virtqemud.rst index ea8d6e3105..f1f1710393 100644 --- a/docs/manpages/virtqemud.rst +++ b/docs/manpages/virtqemud.rst @@ -83,7 +83,8 @@ Use this name for the PID file, overriding the default value. ``-t``, ``--timeout *SECONDS*``
Exit after timeout period (in seconds), provided there are neither any client -connections nor any running domains. +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon.
``-v``, ``--verbose``
diff --git a/docs/manpages/virtsecretd.rst b/docs/manpages/virtsecretd.rst index fffb3a24f6..f35bfb6b5a 100644 --- a/docs/manpages/virtsecretd.rst +++ b/docs/manpages/virtsecretd.rst @@ -82,7 +82,8 @@ Use this name for the PID file, overriding the default value. ``-t``, ``--timeout *SECONDS*``
Exit after timeout period (in seconds), provided there are neither any client -connections nor any running domains. +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon.
``-v``, ``--verbose``
diff --git a/docs/manpages/virtstoraged.rst b/docs/manpages/virtstoraged.rst index 4ceae57e40..ae25a90040 100644 --- a/docs/manpages/virtstoraged.rst +++ b/docs/manpages/virtstoraged.rst @@ -83,7 +83,8 @@ Use this name for the PID file, overriding the default value. ``-t``, ``--timeout *SECONDS*``
Exit after timeout period (in seconds), provided there are neither any client -connections nor any running domains. +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon.
``-v``, ``--verbose``
diff --git a/docs/manpages/virtvboxd.rst b/docs/manpages/virtvboxd.rst index d7339d99f2..0be68d87b8 100644 --- a/docs/manpages/virtvboxd.rst +++ b/docs/manpages/virtvboxd.rst @@ -81,7 +81,8 @@ Use this name for the PID file, overriding the default value. ``-t``, ``--timeout *SECONDS*``
Exit after timeout period (in seconds), provided there are neither any client -connections nor any running domains. +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon.
``-v``, ``--verbose``
diff --git a/docs/manpages/virtvzd.rst b/docs/manpages/virtvzd.rst index 42dfa263e4..d2d6fecce6 100644 --- a/docs/manpages/virtvzd.rst +++ b/docs/manpages/virtvzd.rst @@ -83,7 +83,8 @@ Use this name for the PID file, overriding the default value. ``-t``, ``--timeout *SECONDS*``
Exit after timeout period (in seconds), provided there are neither any client -connections nor any running domains. +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon.
``-v``, ``--verbose``
diff --git a/docs/manpages/virtxend.rst b/docs/manpages/virtxend.rst index b08346b489..d12196956c 100644 --- a/docs/manpages/virtxend.rst +++ b/docs/manpages/virtxend.rst @@ -83,7 +83,8 @@ Use this name for the PID file, overriding the default value. ``-t``, ``--timeout *SECONDS*``
Exit after timeout period (in seconds), provided there are neither any client -connections nor any running domains. +connections nor any other resources (e.g. running domains, locks, etc.) needing +attention of the daemon.
``-v``, ``--verbose``
-- 2.34.1
Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
On Wed, Jan 19, 2022 at 15:31:48 +0000, Daniel P. Berrangé wrote:
On Wed, Jan 19, 2022 at 04:05:05PM +0100, Peter Krempa wrote:
Use a common wording for all various daemons to prevent having to adjust the documentation any further by just outlining that neither clients nor anything else needing the attention of the daemon must be present in order to shut down.
I don't think this is a good idea. The --timeout arg should be specific about exactly what scenarios block timeout for the daemon in question.
Resolves: https://bugzilla.redhat.com/show_bug.cgi?id=2035985
THis bug is reporting that they were expecting virtnetworkd to stay running as long as any domains were still running. ie they thought there was a link between virtqemud and virtnetworkd staying running. The proposed text still leaves that confusion present so doesn't address the problem reported IMHO.
I wanted to be vague so that once another condition blocking the shutdown will be added we will not need to go back and modify the documentation. Given that all the daemons are a copy&paste of the original one (even those which don't deal with domains, such as the storage driver) I can't see how that will be better the next time. Thus I'd still strongly prefer a wording that will not require naming all the specific objects blocking the shutdown.
On Wed, Jan 19, 2022 at 04:35:10PM +0100, Peter Krempa wrote:
On Wed, Jan 19, 2022 at 15:31:48 +0000, Daniel P. Berrangé wrote:
On Wed, Jan 19, 2022 at 04:05:05PM +0100, Peter Krempa wrote:
Use a common wording for all various daemons to prevent having to adjust the documentation any further by just outlining that neither clients nor anything else needing the attention of the daemon must be present in order to shut down.
I don't think this is a good idea. The --timeout arg should be specific about exactly what scenarios block timeout for the daemon in question.
Resolves: https://bugzilla.redhat.com/show_bug.cgi?id=2035985
THis bug is reporting that they were expecting virtnetworkd to stay running as long as any domains were still running. ie they thought there was a link between virtqemud and virtnetworkd staying running. The proposed text still leaves that confusion present so doesn't address the problem reported IMHO.
I wanted to be vague so that once another condition blocking the shutdown will be added we will not need to go back and modify the documentation.
Given that all the daemons are a copy&paste of the original one (even those which don't deal with domains, such as the storage driver) I can't see how that will be better the next time.
Thus I'd still strongly prefer a wording that will not require naming all the specific objects blocking the shutdown.
Being vague like that is not good for users wanting to understand the behaviour. This ability to be specific is why we have separate man pages for each daemon to start off with. Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
participants (2)
-
Daniel P. Berrangé -
Peter Krempa