Patchwork [2/2] Documentation: Add syntax for using sheepdog devices

login
register
mail settings
Submitter ronniesahlberg@gmail.com
Date Oct. 28, 2011, 9:13 a.m.
Message ID <1319793219-12163-3-git-send-email-ronniesahlberg@gmail.com>
Download mbox | patch
Permalink /patch/122365/
State New
Headers show

Comments

Eric Sunshine - Oct. 28, 2011, 9:13 a.m.
On Oct 28, 2011, at 5:13 AM, Ronnie Sahlberg wrote:
> Signed-off-by: Ronnie Sahlberg <ronniesahlberg@gmail.com>
> ---
> qemu-options.hx |   27 +++++++++++++++++++++++++++
> 1 files changed, 27 insertions(+), 0 deletions(-)
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index c55080c..38d0f57 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -1778,6 +1778,33 @@ Example for Unix Domain Sockets
> qemu --drive file=nbd:unix:/tmp/nbd-socket
> @end example
>
> +@item Sheepdog
> +Sheepdog is a distributed storage system for QEMU.
> +QEMU sopports using either local sheepdog devices or remote networked

s/sopports/supports/

-- ES
ronniesahlberg@gmail.com - Oct. 28, 2011, 9:13 a.m.
Signed-off-by: Ronnie Sahlberg <ronniesahlberg@gmail.com>
---
 qemu-options.hx |   27 +++++++++++++++++++++++++++
 1 files changed, 27 insertions(+), 0 deletions(-)
Kevin Wolf - Oct. 28, 2011, 9:32 a.m.
Am 28.10.2011 11:13, schrieb Eric Sunshine:
> On Oct 28, 2011, at 5:13 AM, Ronnie Sahlberg wrote:
>> Signed-off-by: Ronnie Sahlberg <ronniesahlberg@gmail.com>
>> ---
>> qemu-options.hx |   27 +++++++++++++++++++++++++++
>> 1 files changed, 27 insertions(+), 0 deletions(-)
>>
>> diff --git a/qemu-options.hx b/qemu-options.hx
>> index c55080c..38d0f57 100644
>> --- a/qemu-options.hx
>> +++ b/qemu-options.hx
>> @@ -1778,6 +1778,33 @@ Example for Unix Domain Sockets
>> qemu --drive file=nbd:unix:/tmp/nbd-socket
>> @end example
>>
>> +@item Sheepdog
>> +Sheepdog is a distributed storage system for QEMU.
>> +QEMU sopports using either local sheepdog devices or remote networked
> 
> s/sopports/supports/

Thanks, applied to the block branch with fixed typo.

I took a look at qemu-doc.html now, and I think that this information is
very hard to find. We should probably consider moving it to it's own
section that is referenced in the table of contents. Alternatively, I
saw that there are already sections about NBD and Sheepdog under "3.6
Disk images". Maybe moving the new information there would be an option,
too.

Kevin
ronniesahlberg@gmail.com - Oct. 29, 2011, 3:40 a.m.
Hi Kevin,

I agree that maybe we should have a link from the TOC down to the
"Device URL Syntax".
I can create a patch to do so.

For moving the existing "Device URL Syntax" information into "3.6 Disk
Images", I am not sure.
I think both have their place and they serve different purposes even
if there is some overlap.

Device URL Syntax:
This contains a terse description of the syntax on how to specify
these devices on the command line.
This is really needed in the manpage.
Very basic syntax description and an example command line or two.

Qemu-doc:
I see as much more detailed documentation than a simple manpage. It
also includes "howto" type descriptions that show how to set it up
end-to-end from creating a device image, how to configure a basic NDB
server, and then how to make it available to QEMU.
This I think is more a full end-to-end description with howto examples.

I think it would make sense to have both.

What do you think?
If you agree this makes sense I will continue adding terse sections to
"Device URL Syntax" but also start going through section "3.6" and
make sure we also have "howto-like" examples on how to set it up on
the server side as well.
A section in 3.6 for iscsi could for example show how to create an
image and export via STGT so that QEMU can access it as an iscsi lun.


regards
ronnie sahlberg


On Fri, Oct 28, 2011 at 8:32 PM, Kevin Wolf <kwolf@redhat.com> wrote:
> Am 28.10.2011 11:13, schrieb Eric Sunshine:
>> On Oct 28, 2011, at 5:13 AM, Ronnie Sahlberg wrote:
>>> Signed-off-by: Ronnie Sahlberg <ronniesahlberg@gmail.com>
>>> ---
>>> qemu-options.hx |   27 +++++++++++++++++++++++++++
>>> 1 files changed, 27 insertions(+), 0 deletions(-)
>>>
>>> diff --git a/qemu-options.hx b/qemu-options.hx
>>> index c55080c..38d0f57 100644
>>> --- a/qemu-options.hx
>>> +++ b/qemu-options.hx
>>> @@ -1778,6 +1778,33 @@ Example for Unix Domain Sockets
>>> qemu --drive file=nbd:unix:/tmp/nbd-socket
>>> @end example
>>>
>>> +@item Sheepdog
>>> +Sheepdog is a distributed storage system for QEMU.
>>> +QEMU sopports using either local sheepdog devices or remote networked
>>
>> s/sopports/supports/
>
> Thanks, applied to the block branch with fixed typo.
>
> I took a look at qemu-doc.html now, and I think that this information is
> very hard to find. We should probably consider moving it to it's own
> section that is referenced in the table of contents. Alternatively, I
> saw that there are already sections about NBD and Sheepdog under "3.6
> Disk images". Maybe moving the new information there would be an option,
> too.
>
> Kevin
>
Kevin Wolf - Oct. 31, 2011, 8:04 a.m.
Am 29.10.2011 05:40, schrieb ronnie sahlberg:
> Hi Kevin,
> 
> I agree that maybe we should have a link from the TOC down to the
> "Device URL Syntax".
> I can create a patch to do so.
> 
> For moving the existing "Device URL Syntax" information into "3.6 Disk
> Images", I am not sure.
> I think both have their place and they serve different purposes even
> if there is some overlap.
> 
> Device URL Syntax:
> This contains a terse description of the syntax on how to specify
> these devices on the command line.
> This is really needed in the manpage.
> Very basic syntax description and an example command line or two.
> 
> Qemu-doc:
> I see as much more detailed documentation than a simple manpage. It
> also includes "howto" type descriptions that show how to set it up
> end-to-end from creating a device image, how to configure a basic NDB
> server, and then how to make it available to QEMU.
> This I think is more a full end-to-end description with howto examples.
> 
> I think it would make sense to have both.
> 
> What do you think?
> If you agree this makes sense I will continue adding terse sections to
> "Device URL Syntax" but also start going through section "3.6" and
> make sure we also have "howto-like" examples on how to set it up on
> the server side as well.
> A section in 3.6 for iscsi could for example show how to create an
> image and export via STGT so that QEMU can access it as an iscsi lun.

Sure, that sounds good. I just had the impression that currently the
"terse" URL syntax description is in fact more extensive than section
3.6 which should be the full documentation.

Kevin

Patch

diff --git a/qemu-options.hx b/qemu-options.hx
index c55080c..38d0f57 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -1778,6 +1778,33 @@  Example for Unix Domain Sockets
 qemu --drive file=nbd:unix:/tmp/nbd-socket
 @end example
 
+@item Sheepdog
+Sheepdog is a distributed storage system for QEMU.
+QEMU sopports using either local sheepdog devices or remote networked
+devices.
+
+Syntax for specifying a sheepdog device
+@table @list
+``sheepdog:<vdiname>''
+
+``sheepdog:<vdiname>:<snapid>''
+
+``sheepdog:<vdiname>:<tag>''
+
+``sheepdog:<host>:<port>:<vdiname>''
+
+``sheepdog:<host>:<port>:<vdiname>:<snapid>''
+
+``sheepdog:<host>:<port>:<vdiname>:<tag>''
+@end table
+
+Example
+@example
+qemu --drive file=sheepdog:192.0.2.1:30000:MyVirtualMachine
+@end example
+
+See also @url{http://http://www.osrg.net/sheepdog/}.
+
 @end table
 ETEXI