[libvirt] [PATCH 0/2] Tiny adjustments to the virsh's man page
*** BLURB HERE, BLURB THERE, BLURB EVERYWHERE :) *** Erik Skultety (2): virsh: man: Be more explicit about 'create' creating transient domain virsh: man: Document the --validate option for create and define cmds tools/virsh.pod | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) -- 2.13.3
So we refer to terms 'persistent' and 'transient' across the whole man page, without explicitly stating that domain created via the 'create' command is in fact transient and will vanish once destroyed. Signed-off-by: Erik Skultety <eskultet@redhat.com> --- tools/virsh.pod | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/tools/virsh.pod b/tools/virsh.pod index c13f96f22..14a01e9ba 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -652,6 +652,11 @@ of open file descriptors which should be pass on into the guest. The file descriptors will be re-numbered in the guest, starting from 3. This is only supported with container based virtualization. +Note that a domain created using this command is transient (temporary), meaning +that such a domain simply disappears once shut off or destroyed and any +subsequent attempts to B<start> it will fail. See B<define> command on how to +make a domain persistent. + B<Example> virsh dumpxml <domain> > domain.xml -- 2.13.3
On Thu, Sep 07, 2017 at 03:48:13PM +0200, Erik Skultety wrote:
So we refer to terms 'persistent' and 'transient' across the whole man page, without explicitly stating that domain created via the 'create' command is in fact transient and will vanish once destroyed.
Signed-off-by: Erik Skultety <eskultet@redhat.com> --- tools/virsh.pod | 5 +++++ 1 file changed, 5 insertions(+)
diff --git a/tools/virsh.pod b/tools/virsh.pod index c13f96f22..14a01e9ba 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -652,6 +652,11 @@ of open file descriptors which should be pass on into the guest. The file descriptors will be re-numbered in the guest, starting from 3. This is only supported with container based virtualization.
+Note that a domain created using this command is transient (temporary), meaning +that such a domain simply disappears once shut off or destroyed and any +subsequent attempts to B<start> it will fail. See B<define> command on how to +make a domain persistent. +
Not really. With this command you can also start existing domain, just with a different configuration. Given that the example below shows exactly that usage, I think someone might get a bit confused. Would you mind rewriting it to accommodate all variants?
B<Example>
virsh dumpxml <domain> > domain.xml -- 2.13.3
-- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
On Fri, Sep 08, 2017 at 11:06:08AM +0200, Martin Kletzander wrote:
On Thu, Sep 07, 2017 at 03:48:13PM +0200, Erik Skultety wrote:
So we refer to terms 'persistent' and 'transient' across the whole man page, without explicitly stating that domain created via the 'create' command is in fact transient and will vanish once destroyed.
Signed-off-by: Erik Skultety <eskultet@redhat.com> --- tools/virsh.pod | 5 +++++ 1 file changed, 5 insertions(+)
diff --git a/tools/virsh.pod b/tools/virsh.pod index c13f96f22..14a01e9ba 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -652,6 +652,11 @@ of open file descriptors which should be pass on into the guest. The file descriptors will be re-numbered in the guest, starting from 3. This is only supported with container based virtualization.
+Note that a domain created using this command is transient (temporary), meaning +that such a domain simply disappears once shut off or destroyed and any +subsequent attempts to B<start> it will fail. See B<define> command on how to +make a domain persistent. +
Not really. With this command you can also start existing domain, just with a different configuration. Given that the example below shows exactly that usage, I think someone might get a bit confused. Would you mind rewriting it to accommodate all variants?
I pushed 2/2 and sent a v2 of this one, rewording things a bit. Thanks, Erik
Resolves: https://bugzilla.redhat.com/show_bug.cgi?id=1368753 Signed-off-by: Erik Skultety <eskultet@redhat.com> --- tools/virsh.pod | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/tools/virsh.pod b/tools/virsh.pod index 14a01e9ba..8ab93faf2 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -636,13 +636,15 @@ the I<--force> flag may be specified, requesting to disconnect any existing sessions, such as in a case of a broken connection. =item B<create> I<FILE> [I<--console>] [I<--paused>] [I<--autodestroy>] -[I<--pass-fds N,M,...>] +[I<--pass-fds N,M,...>] [I<--validate>] -Create a domain from an XML <file>. An easy way to create the XML -<file> is to use the B<dumpxml> command to obtain the definition of a -pre-existing guest. The domain will be paused if the I<--paused> option -is used and supported by the driver; otherwise it will be running. -If I<--console> is requested, attach to the console after creation. +Create a domain from an XML <file>. Optionally, I<--validate> option can be +passed to validate the format of the input XML file against an internal RNG +schema (identical to using L<virt-xml-validate(1)> tool). An easy way to create +the XML <file> is to use the B<dumpxml> command to obtain the definition of a +pre-existing guest. The domain will be paused if the I<--paused> option is used +and supported by the driver; otherwise it will be running. If I<--console> is +requested, attach to the console after creation. If I<--autodestroy> is requested, then the guest will be automatically destroyed when virsh closes its connection to libvirt, or otherwise exits. @@ -663,10 +665,12 @@ B<Example> vi domain.xml (or make changes with your other text editor) virsh create domain.xml -=item B<define> I<FILE> +=item B<define> I<FILE> [I<--validate>] -Define a domain from an XML <file>. The domain definition is registered -but not started. If domain is already running, the changes will take +Define a domain from an XML <file>. Optionally, the format of the input XML +file can be validated against an internal RNG schema with I<--validate> +(identical to using L<virt-xml-validate(1)> tool). The domain definition is +registered but not started. If domain is already running, the changes will take effect on the next boot. =item B<desc> I<domain> [[I<--live>] [I<--config>] | -- 2.13.3
On Thu, Sep 07, 2017 at 03:48:14PM +0200, Erik Skultety wrote:
Resolves: https://bugzilla.redhat.com/show_bug.cgi?id=1368753
Signed-off-by: Erik Skultety <eskultet@redhat.com> --- tools/virsh.pod | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-)
diff --git a/tools/virsh.pod b/tools/virsh.pod index 14a01e9ba..8ab93faf2 100644 --- a/tools/virsh.pod +++ b/tools/virsh.pod @@ -636,13 +636,15 @@ the I<--force> flag may be specified, requesting to disconnect any existing sessions, such as in a case of a broken connection.
=item B<create> I<FILE> [I<--console>] [I<--paused>] [I<--autodestroy>] -[I<--pass-fds N,M,...>] +[I<--pass-fds N,M,...>] [I<--validate>]
-Create a domain from an XML <file>. An easy way to create the XML -<file> is to use the B<dumpxml> command to obtain the definition of a -pre-existing guest. The domain will be paused if the I<--paused> option -is used and supported by the driver; otherwise it will be running. -If I<--console> is requested, attach to the console after creation. +Create a domain from an XML <file>. Optionally, I<--validate> option can be +passed to validate the format of the input XML file against an internal RNG +schema (identical to using L<virt-xml-validate(1)> tool). An easy way to create +the XML <file> is to use the B<dumpxml> command to obtain the definition of a +pre-existing guest. The domain will be paused if the I<--paused> option is used +and supported by the driver; otherwise it will be running. If I<--console> is +requested, attach to the console after creation. If I<--autodestroy> is requested, then the guest will be automatically destroyed when virsh closes its connection to libvirt, or otherwise exits. @@ -663,10 +665,12 @@ B<Example> vi domain.xml (or make changes with your other text editor) virsh create domain.xml
-=item B<define> I<FILE> +=item B<define> I<FILE> [I<--validate>]
-Define a domain from an XML <file>. The domain definition is registered -but not started. If domain is already running, the changes will take +Define a domain from an XML <file>. Optionally, the format of the input XML +file can be validated against an internal RNG schema with I<--validate> +(identical to using L<virt-xml-validate(1)> tool). The domain definition is +registered but not started. If domain is already running, the changes will take effect on the next boot.
I though we made this the default. It looks like we did that only for cmdEdit. In that case, Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
=item B<desc> I<domain> [[I<--live>] [I<--config>] | -- 2.13.3
-- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
participants (2)
-
Erik Skultety -
Martin Kletzander