[libvirt] First Virsh command Reference Pages online
Hi all, Started work on a Virsh "Command Reference" a few days ago, as a way to "Officially Document" (!) the many virsh commands. My plan is to add to the commands here as I work on related sections. So, as I'm working on "Virtual Networking" at the moment, it's the net-* commands that have been added. This is a first go, and it's on the wiki: http://wiki.libvirt.org/page/VirshCmdRef The net-* commands there should all be accurate at this point: http://wiki.libvirt.org/page/VirshCmdNetAutostart http://wiki.libvirt.org/page/VirshCmdNetCreate http://wiki.libvirt.org/page/VirshCmdNetDefine http://wiki.libvirt.org/page/VirshCmdNetDestroy http://wiki.libvirt.org/page/VirshCmdNetDumpXML http://wiki.libvirt.org/page/VirshCmdNetEdit http://wiki.libvirt.org/page/VirshCmdNetList http://wiki.libvirt.org/page/VirshCmdNetName http://wiki.libvirt.org/page/VirshCmdNetStart http://wiki.libvirt.org/page/VirshCmdNetUndefine http://wiki.libvirt.org/page/VirshCmdNetUUID Does anyone have time to look over them, and make sure there aren't any obvious mistakes? If things are ok, I'll convert them to standard HTML tomorrow and move them to the main libvirt docs. Regards and best wishes, Justin Clift
[snip] Creates a new temporary virtual network from an XML file [/snip] libvirt and virsh use term "persistent" and "transient", :-) - Osier 于 2010年11月10日 01:03, Justin Clift 写道:
Hi all,
Started work on a Virsh "Command Reference" a few days ago, as a way to "Officially Document" (!) the many virsh commands.
My plan is to add to the commands here as I work on related sections. So, as I'm working on "Virtual Networking" at the moment, it's the net-* commands that have been added.
This is a first go, and it's on the wiki:
http://wiki.libvirt.org/page/VirshCmdRef
The net-* commands there should all be accurate at this point:
http://wiki.libvirt.org/page/VirshCmdNetAutostart http://wiki.libvirt.org/page/VirshCmdNetCreate http://wiki.libvirt.org/page/VirshCmdNetDefine http://wiki.libvirt.org/page/VirshCmdNetDestroy http://wiki.libvirt.org/page/VirshCmdNetDumpXML http://wiki.libvirt.org/page/VirshCmdNetEdit http://wiki.libvirt.org/page/VirshCmdNetList http://wiki.libvirt.org/page/VirshCmdNetName http://wiki.libvirt.org/page/VirshCmdNetStart http://wiki.libvirt.org/page/VirshCmdNetUndefine http://wiki.libvirt.org/page/VirshCmdNetUUID
Does anyone have time to look over them, and make sure there aren't any obvious mistakes?
If things are ok, I'll convert them to standard HTML tomorrow and move them to the main libvirt docs.
Regards and best wishes,
Justin Clift
-- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
On 10/11/2010, at 3:42 PM, Osier Yang wrote:
[snip] Creates a new temporary virtual network from an XML file [/snip]
libvirt and virsh use term "persistent" and "transient", :-)
Yeah. I think "transient" might need some work. It's something worth discussing, then doing a search-n-replace through the source if "temporary" turns out to be better. :)
On Wed, Nov 10, 2010 at 04:03:16AM +1100, Justin Clift wrote:
Hi all,
Started work on a Virsh "Command Reference" a few days ago, as a way to "Officially Document" (!) the many virsh commands.
My plan is to add to the commands here as I work on related sections. So, as I'm working on "Virtual Networking" at the moment, it's the net-* commands that have been added.
This is a first go, and it's on the wiki:
http://wiki.libvirt.org/page/VirshCmdRef
The net-* commands there should all be accurate at this point:
http://wiki.libvirt.org/page/VirshCmdNetAutostart http://wiki.libvirt.org/page/VirshCmdNetCreate http://wiki.libvirt.org/page/VirshCmdNetDefine http://wiki.libvirt.org/page/VirshCmdNetDestroy http://wiki.libvirt.org/page/VirshCmdNetDumpXML http://wiki.libvirt.org/page/VirshCmdNetEdit http://wiki.libvirt.org/page/VirshCmdNetList http://wiki.libvirt.org/page/VirshCmdNetName http://wiki.libvirt.org/page/VirshCmdNetStart http://wiki.libvirt.org/page/VirshCmdNetUndefine http://wiki.libvirt.org/page/VirshCmdNetUUID
Does anyone have time to look over them, and make sure there aren't any obvious mistakes?
If things are ok, I'll convert them to standard HTML tomorrow and move them to the main libvirt docs.
Where are you thinking of putting them ? A cut down version of the content would work in the man page, but for the full content, it seems like a good basis for starting a second docbook guide 'Libvirt Administrators Guide', as a counterpart to our 'libvirt Development Guide'. Regards, Daniel -- |: Red Hat, Engineering, London -o- http://people.redhat.com/berrange/ :| |: http://libvirt.org -o- http://virt-manager.org -o- http://deltacloud.org :| |: http://autobuild.org -o- http://search.cpan.org/~danberr/ :| |: GnuPG: 7D3B9505 -o- F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|
On 10/11/2010, at 10:03 PM, Daniel P. Berrange wrote:
Where are you thinking of putting them ? A cut down version of the content would work in the man page, but for the full content, it seems like a good basis for starting a second docbook guide 'Libvirt Administrators Guide', as a counterpart to our 'libvirt Development Guide'.
That's a good idea. I've gone with creating a "virshcmdref" subdirectory under the docs, and converting them to html manually. But, the DocBook approach would probably be better. It would allow multiple output formats rather than the html only output. Ok, I'll lets try DocBook. For "Libvirt Administrators Guide", not yet. We definitely need an Admin Guide of some sort, but I don't think this is the right place to start one just yet. Lets see how further Admin type content shapes up, and decide at that point. :) For now, I'd prefer to stick with "Virsh Command Reference" (keeping it simple).
----- "Justin Clift" <jclift@redhat.com> wrote:
On 10/11/2010, at 10:03 PM, Daniel P. Berrange wrote:
Where are you thinking of putting them ? A cut down version of the content would work in the man page, but for the full content, it seems like a good basis for starting a second docbook guide 'Libvirt Administrators Guide', as a counterpart to our 'libvirt Development Guide'.
That's a good idea. I've gone with creating a "virshcmdref" subdirectory under the docs, and converting them to html manually.
update Makefile to help you do it? :-)
But, the DocBook approach would probably be better. It would allow multiple output formats rather than the html only output.
Ok, I'll lets try DocBook.
For "Libvirt Administrators Guide", not yet. We definitely need an Admin Guide of some sort, but I don't think this is the right place to start one just yet.
Lets see how further Admin type content shapes up, and decide at that point. :)
For now, I'd prefer to stick with "Virsh Command Reference" (keeping it simple).
-- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
On 11/11/2010, at 1:06 AM, Osier wrote:
update Makefile to help you do it? :-)
That would be nice. :) Daniel Veillard has created a new git repository for the DocBook version: http://libvirt.org/git/?p=libvirt-virshcmdref.git;a=summary It's empty right at the moment, but I'll commit the first version of things to it in a little while. Still copying-and-pasting stuff over. :)
Hi Daniel, The "Virtual Networking" commands are now all in the new "Virsh Command Reference", DocBook version. http://justinclift.fedorapeople.org/virshcmdref/chap-Virsh_Command_Reference... We can output to multiple formats (html, single-page-html, pdf, epub, txt), so it's probably a decent idea to put the downloadable ones somewhere, and have the html pages viewable online. My initial thinking is adding the downloads to the Downloads page, with the files themselves in the libvirt FTP area. Something like: ftp://libvirt.org/libvirt/virshcmdref/<stuff> Unsure what a good menu placement for the online html pages are though. This is just the first few commands, and not a "widely comprehensive" reference thing yet. Any suggestions? :) Regards and best wishes, Justin Clift On 11/11/2010, at 2:08 AM, Justin Clift wrote:
On 11/11/2010, at 1:06 AM, Osier wrote:
update Makefile to help you do it? :-)
That would be nice. :)
Daniel Veillard has created a new git repository for the DocBook version:
http://libvirt.org/git/?p=libvirt-virshcmdref.git;a=summary
It's empty right at the moment, but I'll commit the first version of things to it in a little while. Still copying-and-pasting stuff over. :)
-- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
On 11/12/2010 03:27 AM, Justin Clift wrote:
Hi Daniel,
The "Virtual Networking" commands are now all in the new "Virsh Command Reference", DocBook version.
http://justinclift.fedorapeople.org/virshcmdref/chap-Virsh_Command_Reference...
looks pretty good, though missed "net-info", it still need to be ACKed.. :-)
We can output to multiple formats (html, single-page-html, pdf, epub, txt), so it's probably a decent idea to put the downloadable ones somewhere, and have the html pages viewable online.
My initial thinking is adding the downloads to the Downloads page, with the files themselves in the libvirt FTP area.
Something like:
ftp://libvirt.org/libvirt/virshcmdref/<stuff>
also git repo?
Unsure what a good menu placement for the online html pages are though. This is just the first few commands, and not a "widely comprehensive" reference thing yet.
will it be fine as a submenu of top "Documentation" memu? the development guide is there, as Daniel P.Berrange said, probly these docs will be part of "Admin guide". If so, it's reasonable to put there IMHO.
Any suggestions? :)
Regards and best wishes,
Justin Clift
On 11/11/2010, at 2:08 AM, Justin Clift wrote:
On 11/11/2010, at 1:06 AM, Osier wrote:
update Makefile to help you do it? :-)
That would be nice. :)
Daniel Veillard has created a new git repository for the DocBook version:
http://libvirt.org/git/?p=libvirt-virshcmdref.git;a=summary
It's empty right at the moment, but I'll commit the first version of things to it in a little while. Still copying-and-pasting stuff over. :)
-- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
-- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
On 12/11/2010, at 9:38 AM, Osier Yang wrote:
looks pretty good, though missed "net-info", it still need to be ACKed.. :-)
Yeah, trying out the net-info patch is on my list of things to try today (time dependant). :) The code looked pretty straight forward from a visual inspection, so I'm not thinking there will be any problems with it.
We can output to multiple formats (html, single-page-html, pdf, epub, txt), so it's probably a decent idea to put the downloadable ones somewhere, and have the html pages viewable online.
My initial thinking is adding the downloads to the Downloads page, with the files themselves in the libvirt FTP area.
Something like:
ftp://libvirt.org/libvirt/virshcmdref/<stuff>
also git repo?
Very good point yes. And probably also worth including my email address under it directly, as it's easier than people having to go through the mailing list sign up process. (same thought for the App Dev Guide and David Jorm's email)
Unsure what a good menu placement for the online html pages are though. This is just the first few commands, and not a "widely comprehensive" reference thing yet.
will it be fine as a submenu of top "Documentation" memu? the development guide is there, as Daniel P.Berrange said, probly these docs will be part of "Admin guide". If so, it's reasonable to put there IMHO.
Submenu of top Doc menu, yeah, that's probably workable. Thanks Osier. :)
----- "Justin Clift" <jclift@redhat.com> wrote:
On 12/11/2010, at 9:38 AM, Osier Yang wrote:
looks pretty good, though missed "net-info", it still need to be ACKed.. :-)
Yeah, trying out the net-info patch is on my list of things to try today (time dependant). :)
great just note: I didn't implemente the codes to display the domain interfaces which are attached to the network, it need arbitrary API. probly we can do it as a next step.. :-)
The code looked pretty straight forward from a visual inspection, so I'm not thinking there will be any problems with it.
We can output to multiple formats (html, single-page-html, pdf, epub, txt), so it's probably a decent idea to put the downloadable ones somewhere, and have the html pages viewable online.
My initial thinking is adding the downloads to the Downloads page, with the files themselves in the libvirt FTP area.
Something like:
ftp://libvirt.org/libvirt/virshcmdref/<stuff>
also git repo?
Very good point yes. And probably also worth including my email address under it directly, as it's easier than people having to go through the mailing list sign up process. (same thought for the App Dev Guide and David Jorm's email)
Unsure what a good menu placement for the online html pages are though. This is just the first few commands, and not a "widely comprehensive" reference thing yet.
will it be fine as a submenu of top "Documentation" memu? the development guide is there, as Daniel P.Berrange said, probly these docs will be part of "Admin guide". If so, it's reasonable to put there IMHO.
Submenu of top Doc menu, yeah, that's probably workable.
Thanks Osier. :)
Using temporary location links for the moment, until we get a proper place to store the files on the libvirt.org server. --- docs/sitemap.html.in | 4 ++ docs/virshcmdref.html.in | 92 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 96 insertions(+), 0 deletions(-) create mode 100644 docs/virshcmdref.html.in diff --git a/docs/sitemap.html.in b/docs/sitemap.html.in index f09b2c0..692da29 100644 --- a/docs/sitemap.html.in +++ b/docs/sitemap.html.in @@ -266,6 +266,10 @@ <a href="devguide.html">Development Guide</a> <span>A guide and reference for developing with libvirt</span> </li> + <li> + <a href="virshcmdref.html">Virsh Commands</a> + <span>Command reference for virsh</span> + </li> </ul> </li> <li> diff --git a/docs/virshcmdref.html.in b/docs/virshcmdref.html.in new file mode 100644 index 0000000..f965ba0 --- /dev/null +++ b/docs/virshcmdref.html.in @@ -0,0 +1,92 @@ +<?xml version="1.0"?> +<html> + <body> + <h1>Virsh Command Reference</h1> + + <ul id="toc"></ul> + + <h2><a name="description">Description</a></h2> + + <p> + The new <b>Virsh Command Reference</b>, for documenting the commands + in virsh, has recently been started. Only covering the Virtual + Networking commands initially, it will expand to cover all virsh + commands over time. + </p> + + <p> + If you would like to assist, content contributions are gladly accepted. + Please email <a href="mailto:jclift@redhat.com">Justin Clift</a> + directly, or get in contact through any of the + <a href="contact.html">official libvirt mailing lists</a>. + </p> + + <p> </p> + + <h2><a name="viewing">Viewing Online</a></h2> + + <p> + The latest version can be viewed directly online: + </p> + + <ul> + <li> + <a href="http://justinclift.fedorapeople.org/virshcmdref/html/">Standard HTML format, multiple pages</a> + </li> + <li> + <a href="http://justinclift.fedorapeople.org/virshcmdref/html-single/">HTML format, one long page</a> + </li> + </ul> + + <p> </p> + + <h2><a name="downloading">Downloading</a></h2> + + <p> + The latest versions of the Virsh Command Reference can be downloaded: + </p> + + <ul> + <li> + Standard HTML format, multiple pages + (<a href="http://justinclift.fedorapeople.org/virshcmdref/Virsh_Command_Reference-0.8.6-0-html-multi-page.tar.gz">.tar.gz</a>) + (<a href="http://justinclift.fedorapeople.org/virshcmdref/Virsh_Command_Reference-0.8.6-0-html-multi-page.tar.bz2">.tar.bz2</a>) + (<a href="http://justinclift.fedorapeople.org/virshcmdref/Virsh_Command_Reference-0.8.6-0-html-multi-page.zip">.zip</a>) + </li> + <li> + HTML format, one long page + (<a href="http://justinclift.fedorapeople.org/virshcmdref/Virsh_Command_Reference-0.8.6-0-html-single.tar.gz">.tar.gz</a>) + (<a href="http://justinclift.fedorapeople.org/virshcmdref/Virsh_Command_Reference-0.8.6-0-html-single.tar.bz2">.tar.bz2</a>) + (<a href="http://justinclift.fedorapeople.org/virshcmdref/Virsh_Command_Reference-0.8.6-0-html-single.zip">.zip</a>) + </li> + <li> + <a href="http://justinclift.fedorapeople.org/virshcmdref/Virsh_Command_Reference-0.8.6-0.pdf">PDF format</a> + </li> + <li> + <a href="http://justinclift.fedorapeople.org/virshcmdref/Virsh_Command_Reference-0.8.6-0.epub">ePub format</a> + </li> + </ul> + + <h2><a name="git">DocBook source GIT repository</a></h2> + <p> + The DocBook source is maintained in a <a + href="http://git-scm.com/">git</a> repository available on + <a href="http://libvirt.org/git/">libvirt.org</a>: + </p> + +<pre> +git clone git://libvirt.org/libvirt-virshcmdref.git +</pre> + + <p> + It can also be browsed online: + </p> + +<pre> +<a href="http://libvirt.org/git/?p=libvirt-virshcmdref.git">http://libvirt.org/git/?p=libvirt-virshcmdref.git</a> +</pre> + + <p> </p> + + </body> +</html> -- 1.7.3
On 11/12/2010 09:58 AM, Justin Clift wrote:
Using temporary location links for the moment, until we get a proper place to store the files on the libvirt.org server. --- docs/sitemap.html.in | 4 ++ docs/virshcmdref.html.in | 92 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 96 insertions(+), 0 deletions(-) create mode 100644 docs/virshcmdref.html.in
ACK. -- Eric Blake eblake@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org
On 13/11/2010, at 4:06 AM, Eric Blake wrote:
On 11/12/2010 09:58 AM, Justin Clift wrote:
Using temporary location links for the moment, until we get a proper place to store the files on the libvirt.org server. --- docs/sitemap.html.in | 4 ++ docs/virshcmdref.html.in | 92 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 96 insertions(+), 0 deletions(-) create mode 100644 docs/virshcmdref.html.in
ACK.
Thanks Eric. Pushed. :)
On Sat, Nov 13, 2010 at 03:58:39AM +1100, Justin Clift wrote:
Using temporary location links for the moment, until we get a proper place to store the files on the libvirt.org server. --- docs/sitemap.html.in | 4 ++ docs/virshcmdref.html.in | 92 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 96 insertions(+), 0 deletions(-) create mode 100644 docs/virshcmdref.html.in
NACK to this. Although this docs/ location is how we populate the website, this also all goes into the released tar.gz and thus lives forever. We shouldn't be referencing shortlived temporary URLs in this eg all these
+ Standard HTML format, multiple pages + (<a href="http://justinclift.fedorapeople.org/virshcmdref/Virsh_Command_Reference-0.8.6-0-html-multi-page.tar.gz">.tar.gz</a>) + (<a href="http://justinclift.fedorapeople.org/virshcmdref/Virsh_Command_Reference-0.8.6-0-html-multi-page.tar.bz2">.tar.bz2</a>) + (<a href="http://justinclift.fedorapeople.org/virshcmdref/Virsh_Command_Reference-0.8.6-0-html-multi-page.zip">.zip</a>) + </li> + <li> + HTML format, one long page + (<a href="http://justinclift.fedorapeople.org/virshcmdref/Virsh_Command_Reference-0.8.6-0-html-single.tar.gz">.tar.gz</a>) + (<a href="http://justinclift.fedorapeople.org/virshcmdref/Virsh_Command_Reference-0.8.6-0-html-single.tar.bz2">.tar.bz2</a>) + (<a href="http://justinclift.fedorapeople.org/virshcmdref/Virsh_Command_Reference-0.8.6-0-html-single.zip">.zip</a>) + </li> + <li> + <a href="http://justinclift.fedorapeople.org/virshcmdref/Virsh_Command_Reference-0.8.6-0.pdf">PDF format</a> + </li> + <li> + <a href="http://justinclift.fedorapeople.org/virshcmdref/Virsh_Command_Reference-0.8.6-0.epub">ePub format</a> + </li> + </ul>
Just link to this content from the wiki site, until we get a permanent home for it that is stable & we can include in releases. Regards, Daniel -- |: Red Hat, Engineering, London -o- http://people.redhat.com/berrange/ :| |: http://libvirt.org -o- http://virt-manager.org -o- http://deltacloud.org :| |: http://autobuild.org -o- http://search.cpan.org/~danberr/ :| |: GnuPG: 7D3B9505 -o- F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|
On 13/11/2010, at 5:20 AM, Daniel P. Berrange wrote:
On Sat, Nov 13, 2010 at 03:58:39AM +1100, Justin Clift wrote:
Using temporary location links for the moment, until we get a proper place to store the files on the libvirt.org server. --- docs/sitemap.html.in | 4 ++ docs/virshcmdref.html.in | 92 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 96 insertions(+), 0 deletions(-) create mode 100644 docs/virshcmdref.html.in
NACK to this. Although this docs/ location is how we populate the website, this also all goes into the released tar.gz and thus lives forever. We shouldn't be referencing shortlived temporary URLs in this eg all these
It's already been pushed. :/
Just link to this content from the wiki site, until we get a permanent home for it that is stable & we can include in releases.
Already nuked the wiki version of pages. Planning on moving the stuff into the libvirt.org ftp dir as soon as DV creates the needed subdir. :)
On Sat, Nov 13, 2010 at 05:22:56AM +1100, Justin Clift wrote:
On 13/11/2010, at 5:20 AM, Daniel P. Berrange wrote:
On Sat, Nov 13, 2010 at 03:58:39AM +1100, Justin Clift wrote:
Using temporary location links for the moment, until we get a proper place to store the files on the libvirt.org server. --- docs/sitemap.html.in | 4 ++ docs/virshcmdref.html.in | 92 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 96 insertions(+), 0 deletions(-) create mode 100644 docs/virshcmdref.html.in
NACK to this. Although this docs/ location is how we populate the website, this also all goes into the released tar.gz and thus lives forever. We shouldn't be referencing shortlived temporary URLs in this eg all these
It's already been pushed. :/
Just link to this content from the wiki site, until we get a permanent home for it that is stable & we can include in releases.
Already nuked the wiki version of pages.
Planning on moving the stuff into the libvirt.org ftp dir as soon as DV creates the needed subdir. :)
Ok, as long as these links are removed/updated before the next release. Regards, Daniel -- |: Red Hat, Engineering, London -o- http://people.redhat.com/berrange/ :| |: http://libvirt.org -o- http://virt-manager.org -o- http://deltacloud.org :| |: http://autobuild.org -o- http://search.cpan.org/~danberr/ :| |: GnuPG: 7D3B9505 -o- F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|
On 13/11/2010, at 6:13 AM, Daniel P. Berrange wrote:
Planning on moving the stuff into the libvirt.org ftp dir as soon as DV creates the needed subdir. :)
Ok, as long as these links are removed/updated before the next release.
No worries. All in place and fixed now. :)
participants (5)
-
Daniel P. Berrange -
Eric Blake -
Justin Clift -
Osier -
Osier Yang