[Qemu-devel] [PATCH 0/8] qemu-options: Texinfo and --help fixes

[Qemu-devel] [PATCH 0/8] qemu-options: Texinfo and --help fixes

[Markus Armbruster]

Markus Armbruster (8):
  qemu-options: Remove stray colons from output of --help
  qemu-options: Fix markup of -netdev l2tpv3
  qemu-options qemu-doc: Move "Device URL Syntax" to qemu-doc
  qemu-options: Move -iscsi under "Block device options"
  qemu-options: Add missing -iscsi Texinfo documentation
  qemu-options: Polish section "TPM device options"
  qemu-options: Polish section "Character device options"
  qemu-options: Belatedly document --watchdog-action inject-nmi

 qemu-doc.texi          | 217 +++++++++++++++++++++++++++++++++++
 qemu-options-wrapper.h |   2 +-
 qemu-options.hx        | 306 ++++++++-----------------------------------------
 scripts/hxtool         |   3 +-
 4 files changed, 267 insertions(+), 261 deletions(-)

-- 
2.13.6

[Qemu-devel] [PATCH 1/8] qemu-options: Remove stray colons from output of --help

[Markus Armbruster]

Commit 43f187a broke --help: it put colons into blank lines.  It
removed the colon from DEFHEADING(TITLE:) and added it back in the
macro expansion of DEFHEADING(TITLE), so hxtool can emit "@subsection
TITLE" more easily.  Trouble is it's added back even for the blank
lines made with DEFHEADING().

Put the colons back where they were before commit 43f187a, and strip
them in hxtool instead.

Cc: Paolo Bonzini <pbonzini@redhat.com>
CC: qemu-stable@nongnu.org
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qemu-options-wrapper.h |  2 +-
 qemu-options.hx        | 27 ++++++++++++++-------------
 scripts/hxtool         |  3 ++-
 3 files changed, 17 insertions(+), 15 deletions(-)

diff --git a/qemu-options-wrapper.h b/qemu-options-wrapper.h
index 4d7aeb1352..13bfea0294 100644
--- a/qemu-options-wrapper.h
+++ b/qemu-options-wrapper.h
@@ -14,7 +14,7 @@
 
 #define ARCHHEADING(text, arch_mask) \
     if ((arch_mask) & arch_type)    \
-        puts(stringify(text) ":");
+        puts(stringify(text));
 
 #define DEFHEADING(text) ARCHHEADING(text, QEMU_ARCH_ALL)
 
diff --git a/qemu-options.hx b/qemu-options.hx
index 39225ae6c3..0fed2fc009 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -6,7 +6,7 @@ HXCOMM construct option structures, enums and help message for specified
 HXCOMM architectures.
 HXCOMM HXCOMM can be used for comments, discarded from both texi and C
 
-DEFHEADING(Standard options)
+DEFHEADING(Standard options:)
 STEXI
 @table @option
 ETEXI
@@ -578,7 +578,7 @@ STEXI
 ETEXI
 DEFHEADING()
 
-DEFHEADING(Block device options)
+DEFHEADING(Block device options:)
 STEXI
 @table @option
 ETEXI
@@ -1177,7 +1177,7 @@ STEXI
 ETEXI
 DEFHEADING()
 
-DEFHEADING(USB options)
+DEFHEADING(USB options:)
 STEXI
 @table @option
 ETEXI
@@ -1242,7 +1242,7 @@ STEXI
 ETEXI
 DEFHEADING()
 
-DEFHEADING(Display options)
+DEFHEADING(Display options:)
 STEXI
 @table @option
 ETEXI
@@ -1779,7 +1779,7 @@ STEXI
 ETEXI
 ARCHHEADING(, QEMU_ARCH_I386)
 
-ARCHHEADING(i386 target only, QEMU_ARCH_I386)
+ARCHHEADING(i386 target only:, QEMU_ARCH_I386)
 STEXI
 @table @option
 ETEXI
@@ -1895,7 +1895,7 @@ STEXI
 ETEXI
 DEFHEADING()
 
-DEFHEADING(Network options)
+DEFHEADING(Network options:)
 STEXI
 @table @option
 ETEXI
@@ -2476,7 +2476,7 @@ STEXI
 ETEXI
 DEFHEADING()
 
-DEFHEADING(Character device options)
+DEFHEADING(Character device options:)
 STEXI
 
 The general form of a character device option is:
@@ -2809,7 +2809,7 @@ STEXI
 ETEXI
 DEFHEADING()
 
-DEFHEADING(Device URL Syntax)
+DEFHEADING(Device URL Syntax:)
 STEXI
 
 In addition to using normal file images for the emulated storage devices,
@@ -3039,7 +3039,7 @@ STEXI
 @end table
 ETEXI
 
-DEFHEADING(Bluetooth(R) options)
+DEFHEADING(Bluetooth(R) options:)
 STEXI
 @table @option
 ETEXI
@@ -3115,7 +3115,7 @@ ETEXI
 DEFHEADING()
 
 #ifdef CONFIG_TPM
-DEFHEADING(TPM device options)
+DEFHEADING(TPM device options:)
 
 DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \
     "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n"
@@ -3189,7 +3189,7 @@ DEFHEADING()
 
 #endif
 
-DEFHEADING(Linux/Multiboot boot specific)
+DEFHEADING(Linux/Multiboot boot specific:)
 STEXI
 
 When using these options, you can use a given Linux or Multiboot
@@ -3245,7 +3245,7 @@ STEXI
 ETEXI
 DEFHEADING()
 
-DEFHEADING(Debug/Expert options)
+DEFHEADING(Debug/Expert options:)
 STEXI
 @table @option
 ETEXI
@@ -4160,7 +4160,8 @@ STEXI
 @end table
 ETEXI
 DEFHEADING()
-DEFHEADING(Generic object creation)
+
+DEFHEADING(Generic object creation:)
 STEXI
 @table @option
 ETEXI
diff --git a/scripts/hxtool b/scripts/hxtool
index 1e2c97c5e6..7d7c4289e3 100644
--- a/scripts/hxtool
+++ b/scripts/hxtool
@@ -19,7 +19,8 @@ hxtoh()
 print_texi_heading()
 {
     if test "$*" != ""; then
-        printf "@subsection %s\n" "$*"
+        title="$*"
+        printf "@subsection %s\n" "${title%:}"
     fi
 }
 
-- 
2.13.6

Re: [Qemu-devel] [PATCH 1/8] qemu-options: Remove stray colons from output of --help

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 972 bytes --]

On 10/02/2017 09:03 AM, Markus Armbruster wrote:
> Commit 43f187a broke --help: it put colons into blank lines.  It
> removed the colon from DEFHEADING(TITLE:) and added it back in the
> macro expansion of DEFHEADING(TITLE), so hxtool can emit "@subsection
> TITLE" more easily.  Trouble is it's added back even for the blank
> lines made with DEFHEADING().
> 
> Put the colons back where they were before commit 43f187a, and strip
> them in hxtool instead.
> 
> Cc: Paolo Bonzini <pbonzini@redhat.com>
> CC: qemu-stable@nongnu.org
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  qemu-options-wrapper.h |  2 +-
>  qemu-options.hx        | 27 ++++++++++++++-------------
>  scripts/hxtool         |  3 ++-
>  3 files changed, 17 insertions(+), 15 deletions(-)

Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 619 bytes --]

Re: [Qemu-devel] [PATCH 1/8] qemu-options: Remove stray colons from output of --help

[Marc-André Lureau]

On Mon, Oct 2, 2017 at 4:03 PM, Markus Armbruster <armbru@redhat.com> wrote:
> Commit 43f187a broke --help: it put colons into blank lines.  It
> removed the colon from DEFHEADING(TITLE:) and added it back in the
> macro expansion of DEFHEADING(TITLE), so hxtool can emit "@subsection
> TITLE" more easily.  Trouble is it's added back even for the blank
> lines made with DEFHEADING().
>
> Put the colons back where they were before commit 43f187a, and strip
> them in hxtool instead.
>
> Cc: Paolo Bonzini <pbonzini@redhat.com>
> CC: qemu-stable@nongnu.org
> Signed-off-by: Markus Armbruster <armbru@redhat.com>

Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>


> ---
>  qemu-options-wrapper.h |  2 +-
>  qemu-options.hx        | 27 ++++++++++++++-------------
>  scripts/hxtool         |  3 ++-
>  3 files changed, 17 insertions(+), 15 deletions(-)
>
> diff --git a/qemu-options-wrapper.h b/qemu-options-wrapper.h
> index 4d7aeb1352..13bfea0294 100644
> --- a/qemu-options-wrapper.h
> +++ b/qemu-options-wrapper.h
> @@ -14,7 +14,7 @@
>
>  #define ARCHHEADING(text, arch_mask) \
>      if ((arch_mask) & arch_type)    \
> -        puts(stringify(text) ":");
> +        puts(stringify(text));
>
>  #define DEFHEADING(text) ARCHHEADING(text, QEMU_ARCH_ALL)
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 39225ae6c3..0fed2fc009 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -6,7 +6,7 @@ HXCOMM construct option structures, enums and help message for specified
>  HXCOMM architectures.
>  HXCOMM HXCOMM can be used for comments, discarded from both texi and C
>
> -DEFHEADING(Standard options)
> +DEFHEADING(Standard options:)
>  STEXI
>  @table @option
>  ETEXI
> @@ -578,7 +578,7 @@ STEXI
>  ETEXI
>  DEFHEADING()
>
> -DEFHEADING(Block device options)
> +DEFHEADING(Block device options:)
>  STEXI
>  @table @option
>  ETEXI
> @@ -1177,7 +1177,7 @@ STEXI
>  ETEXI
>  DEFHEADING()
>
> -DEFHEADING(USB options)
> +DEFHEADING(USB options:)
>  STEXI
>  @table @option
>  ETEXI
> @@ -1242,7 +1242,7 @@ STEXI
>  ETEXI
>  DEFHEADING()
>
> -DEFHEADING(Display options)
> +DEFHEADING(Display options:)
>  STEXI
>  @table @option
>  ETEXI
> @@ -1779,7 +1779,7 @@ STEXI
>  ETEXI
>  ARCHHEADING(, QEMU_ARCH_I386)
>
> -ARCHHEADING(i386 target only, QEMU_ARCH_I386)
> +ARCHHEADING(i386 target only:, QEMU_ARCH_I386)
>  STEXI
>  @table @option
>  ETEXI
> @@ -1895,7 +1895,7 @@ STEXI
>  ETEXI
>  DEFHEADING()
>
> -DEFHEADING(Network options)
> +DEFHEADING(Network options:)
>  STEXI
>  @table @option
>  ETEXI
> @@ -2476,7 +2476,7 @@ STEXI
>  ETEXI
>  DEFHEADING()
>
> -DEFHEADING(Character device options)
> +DEFHEADING(Character device options:)
>  STEXI
>
>  The general form of a character device option is:
> @@ -2809,7 +2809,7 @@ STEXI
>  ETEXI
>  DEFHEADING()
>
> -DEFHEADING(Device URL Syntax)
> +DEFHEADING(Device URL Syntax:)
>  STEXI
>
>  In addition to using normal file images for the emulated storage devices,
> @@ -3039,7 +3039,7 @@ STEXI
>  @end table
>  ETEXI
>
> -DEFHEADING(Bluetooth(R) options)
> +DEFHEADING(Bluetooth(R) options:)
>  STEXI
>  @table @option
>  ETEXI
> @@ -3115,7 +3115,7 @@ ETEXI
>  DEFHEADING()
>
>  #ifdef CONFIG_TPM
> -DEFHEADING(TPM device options)
> +DEFHEADING(TPM device options:)
>
>  DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \
>      "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n"
> @@ -3189,7 +3189,7 @@ DEFHEADING()
>
>  #endif
>
> -DEFHEADING(Linux/Multiboot boot specific)
> +DEFHEADING(Linux/Multiboot boot specific:)
>  STEXI
>
>  When using these options, you can use a given Linux or Multiboot
> @@ -3245,7 +3245,7 @@ STEXI
>  ETEXI
>  DEFHEADING()
>
> -DEFHEADING(Debug/Expert options)
> +DEFHEADING(Debug/Expert options:)
>  STEXI
>  @table @option
>  ETEXI
> @@ -4160,7 +4160,8 @@ STEXI
>  @end table
>  ETEXI
>  DEFHEADING()
> -DEFHEADING(Generic object creation)
> +
> +DEFHEADING(Generic object creation:)
>  STEXI
>  @table @option
>  ETEXI
> diff --git a/scripts/hxtool b/scripts/hxtool
> index 1e2c97c5e6..7d7c4289e3 100644
> --- a/scripts/hxtool
> +++ b/scripts/hxtool
> @@ -19,7 +19,8 @@ hxtoh()
>  print_texi_heading()
>  {
>      if test "$*" != ""; then
> -        printf "@subsection %s\n" "$*"
> +        title="$*"
> +        printf "@subsection %s\n" "${title%:}"
>      fi
>  }
>
> --
> 2.13.6
>
>



-- 
Marc-André Lureau

[Qemu-devel] [PATCH 2/8] qemu-options: Fix markup of -netdev l2tpv3

[Markus Armbruster]

The table of option parameters lacks @table and @end table.  The
parameters become items in the enclosing table of options.  Screwed up
when l2tpv3 was added in commit 3fb69aa.  Fix the obvious way.

Cc: Jason Wang <jasowang@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qemu-options.hx | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/qemu-options.hx b/qemu-options.hx
index 0fed2fc009..39f0e1b990 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -2367,6 +2367,7 @@ two systems. It is present in routers, firewalls and the Linux kernel
 
 This transport allows a VM to communicate to another VM, router or firewall directly.
 
+@table @option
 @item src=@var{srcaddr}
     source address (mandatory)
 @item dst=@var{dstaddr}
@@ -2394,6 +2395,7 @@ draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
 networks which have packet reorder.
 @item offset=@var{offset}
     Add an extra offset between header and data
+@end table
 
 For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan
 on the remote Linux host 1.2.3.4:
-- 
2.13.6

Re: [Qemu-devel] [PATCH 2/8] qemu-options: Fix markup of -netdev l2tpv3

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 611 bytes --]

On 10/02/2017 09:03 AM, Markus Armbruster wrote:
> The table of option parameters lacks @table and @end table.  The
> parameters become items in the enclosing table of options.  Screwed up
> when l2tpv3 was added in commit 3fb69aa.  Fix the obvious way.
> 
> Cc: Jason Wang <jasowang@redhat.com>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  qemu-options.hx | 2 ++
>  1 file changed, 2 insertions(+)
> 

Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 619 bytes --]

Re: [Qemu-devel] [PATCH 2/8] qemu-options: Fix markup of -netdev l2tpv3

[Marc-André Lureau]

On Mon, Oct 2, 2017 at 4:03 PM, Markus Armbruster <armbru@redhat.com> wrote:
> The table of option parameters lacks @table and @end table.  The
> parameters become items in the enclosing table of options.  Screwed up
> when l2tpv3 was added in commit 3fb69aa.  Fix the obvious way.
>
> Cc: Jason Wang <jasowang@redhat.com>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>

Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>


> ---
>  qemu-options.hx | 2 ++
>  1 file changed, 2 insertions(+)
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 0fed2fc009..39f0e1b990 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -2367,6 +2367,7 @@ two systems. It is present in routers, firewalls and the Linux kernel
>
>  This transport allows a VM to communicate to another VM, router or firewall directly.
>
> +@table @option
>  @item src=@var{srcaddr}
>      source address (mandatory)
>  @item dst=@var{dstaddr}
> @@ -2394,6 +2395,7 @@ draft-mkonstan-l2tpext-keyed-ipv6-tunnel-00
>  networks which have packet reorder.
>  @item offset=@var{offset}
>      Add an extra offset between header and data
> +@end table
>
>  For example, to attach a VM running on host 4.3.2.1 via L2TPv3 to the bridge br-lan
>  on the remote Linux host 1.2.3.4:
> --
> 2.13.6
>
>



-- 
Marc-André Lureau

[Qemu-devel] [PATCH 3/8] qemu-options qemu-doc: Move "Device URL Syntax" to qemu-doc

[Markus Armbruster]

Commit 0f5314a (v1.0) added section "Device URL Syntax" to
qemu-options.hx.  It's enclosed in STEXI..ETEXI, thus affects only
qemu-options.texi, not --help.  It appears as a subsection under
section "Invocation".  Similarly, qemu.1 has it as a subsection under
"OPTIONS".

Commit f9dadc9 (v1.1.0) dropped new option -iscsi into the middle of
this section.  No effect on qemu-options.texi.  It appears in --help
run together with the "Bluetooth(R) options:" header.

Commit c70a01e (v1.5.0) gives it is own heading in --help by moving
commit 0f5314a's DEFHEADING(Device URL Syntax:) outside STEXI..ETEXI.
Trouble is the heading makes no sense for -iscsi.

Move all of the "Device URL Syntax" Texinfo to qemu-doc.texi.  Mark it
for inclusion in qemu.1 with '@c man begin NOTES'.  This turns it into
a separate section outside the list of options both in qemu-doc and in
qemu.1.

There's substantial overlap with the existing qemu-doc section "Disk
Images".  Mark with a TODO comment.

Output of --help will be fixed next.

Cc: Ronnie Sahlberg <ronniesahlberg@gmail.com>
Cc: Kevin Wolf <kwolf@redhat.com>
Cc: Max Reitz <mreitz@redhat.com>
Cc: qemu-block@nongnu.org
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qemu-doc.texi   | 217 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 qemu-options.hx | 222 --------------------------------------------------------
 2 files changed, 217 insertions(+), 222 deletions(-)

diff --git a/qemu-doc.texi b/qemu-doc.texi
index ecd186a159..848e49966a 100644
--- a/qemu-doc.texi
+++ b/qemu-doc.texi
@@ -245,6 +245,223 @@ targets do not need a disk image.
 
 @c man end
 
+@node device_url
+@subsection Device URL Syntax
+@c TODO merge this with section Disk Images
+
+@c man begin NOTES
+
+In addition to using normal file images for the emulated storage devices,
+QEMU can also use networked resources such as iSCSI devices. These are
+specified using a special URL syntax.
+
+@table @option
+@item iSCSI
+iSCSI support allows QEMU to access iSCSI resources directly and use as
+images for the guest storage. Both disk and cdrom images are supported.
+
+Syntax for specifying iSCSI LUNs is
+``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>''
+
+By default qemu will use the iSCSI initiator-name
+'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command
+line or a configuration file.
+
+Since version Qemu 2.4 it is possible to specify a iSCSI request timeout to detect
+stalled requests and force a reestablishment of the session. The timeout
+is specified in seconds. The default is 0 which means no timeout. Libiscsi
+1.15.0 or greater is required for this feature.
+
+Example (without authentication):
+@example
+qemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
+                 -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
+                 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
+@end example
+
+Example (CHAP username/password via URL):
+@example
+qemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
+@end example
+
+Example (CHAP username/password via environment variables):
+@example
+LIBISCSI_CHAP_USERNAME="user" \
+LIBISCSI_CHAP_PASSWORD="password" \
+qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
+@end example
+
+@item NBD
+QEMU supports NBD (Network Block Devices) both using TCP protocol as well
+as Unix Domain Sockets.
+
+Syntax for specifying a NBD device using TCP
+``nbd:<server-ip>:<port>[:exportname=<export>]''
+
+Syntax for specifying a NBD device using Unix Domain Sockets
+``nbd:unix:<domain-socket>[:exportname=<export>]''
+
+Example for TCP
+@example
+qemu-system-i386 --drive file=nbd:192.0.2.1:30000
+@end example
+
+Example for Unix Domain Sockets
+@example
+qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket
+@end example
+
+@item SSH
+QEMU supports SSH (Secure Shell) access to remote disks.
+
+Examples:
+@example
+qemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img
+qemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
+@end example
+
+Currently authentication must be done using ssh-agent.  Other
+authentication methods may be supported in future.
+
+@item Sheepdog
+Sheepdog is a distributed storage system for QEMU.
+QEMU supports using either local sheepdog devices or remote networked
+devices.
+
+Syntax for specifying a sheepdog device
+@example
+sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
+@end example
+
+Example
+@example
+qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
+@end example
+
+See also @url{https://sheepdog.github.io/sheepdog/}.
+
+@item GlusterFS
+GlusterFS is a user space distributed file system.
+QEMU supports the use of GlusterFS volumes for hosting VM disk images using
+TCP, Unix Domain Sockets and RDMA transport protocols.
+
+Syntax for specifying a VM disk image on GlusterFS volume is
+@example
+
+URI:
+gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
+
+JSON:
+'json:@{"driver":"qcow2","file":@{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
+@                                 "server":[@{"type":"tcp","host":"...","port":"..."@},
+@                                           @{"type":"unix","socket":"..."@}]@}@}'
+@end example
+
+
+Example
+@example
+URI:
+qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img,
+@                               file.debug=9,file.logfile=/var/log/qemu-gluster.log
+
+JSON:
+qemu-system-x86_64 'json:@{"driver":"qcow2",
+@                          "file":@{"driver":"gluster",
+@                                   "volume":"testvol","path":"a.img",
+@                                   "debug":9,"logfile":"/var/log/qemu-gluster.log",
+@                                   "server":[@{"type":"tcp","host":"1.2.3.4","port":24007@},
+@                                             @{"type":"unix","socket":"/var/run/glusterd.socket"@}]@}@}'
+qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
+@                                      file.debug=9,file.logfile=/var/log/qemu-gluster.log,
+@                                      file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
+@                                      file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
+@end example
+
+See also @url{http://www.gluster.org}.
+
+@item HTTP/HTTPS/FTP/FTPS
+QEMU supports read-only access to files accessed over http(s) and ftp(s).
+
+Syntax using a single filename:
+@example
+<protocol>://[<username>[:<password>]@@]<host>/<path>
+@end example
+
+where:
+@table @option
+@item protocol
+'http', 'https', 'ftp', or 'ftps'.
+
+@item username
+Optional username for authentication to the remote server.
+
+@item password
+Optional password for authentication to the remote server.
+
+@item host
+Address of the remote server.
+
+@item path
+Path on the remote server, including any query string.
+@end table
+
+The following options are also supported:
+@table @option
+@item url
+The full URL when passing options to the driver explicitly.
+
+@item readahead
+The amount of data to read ahead with each range request to the remote server.
+This value may optionally have the suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it
+does not have a suffix, it will be assumed to be in bytes. The value must be a
+multiple of 512 bytes. It defaults to 256k.
+
+@item sslverify
+Whether to verify the remote server's certificate when connecting over SSL. It
+can have the value 'on' or 'off'. It defaults to 'on'.
+
+@item cookie
+Send this cookie (it can also be a list of cookies separated by ';') with
+each outgoing request.  Only supported when using protocols such as HTTP
+which support cookies, otherwise ignored.
+
+@item timeout
+Set the timeout in seconds of the CURL connection. This timeout is the time
+that CURL waits for a response from the remote server to get the size of the
+image to be downloaded. If not set, the default timeout of 5 seconds is used.
+@end table
+
+Note that when passing options to qemu explicitly, @option{driver} is the value
+of <protocol>.
+
+Example: boot from a remote Fedora 20 live ISO image
+@example
+qemu-system-x86_64 --drive media=cdrom,file=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
+
+qemu-system-x86_64 --drive media=cdrom,file.driver=http,file.url=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
+@end example
+
+Example: boot from a remote Fedora 20 cloud image using a local overlay for
+writes, copy-on-read, and a readahead of 64k
+@example
+qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"http",, "file.url":"https://dl.fedoraproject.org/pub/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readahead":"64k"@}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2
+
+qemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
+@end example
+
+Example: boot from an image stored on a VMware vSphere server with a self-signed
+certificate using a local overlay for writes, a readahead of 64k and a timeout
+of 10 seconds.
+@example
+qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"https",, "file.url":"https://user:password@@vsphere.example.com/folder/test/test-flat.vmdk?dcPath=Datacenter&dsName=datastore1",, "file.sslverify":"off",, "file.readahead":"64k",, "file.timeout":10@}' /tmp/test.qcow2
+
+qemu-system-x86_64 -drive file=/tmp/test.qcow2
+@end example
+
+@end table
+
+@c man end
+
 @node pcsys_keys
 @section Keys in the graphical frontends
 
diff --git a/qemu-options.hx b/qemu-options.hx
index 39f0e1b990..f112281d37 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -2812,234 +2812,12 @@ ETEXI
 DEFHEADING()
 
 DEFHEADING(Device URL Syntax:)
-STEXI
-
-In addition to using normal file images for the emulated storage devices,
-QEMU can also use networked resources such as iSCSI devices. These are
-specified using a special URL syntax.
-
-@table @option
-@item iSCSI
-iSCSI support allows QEMU to access iSCSI resources directly and use as
-images for the guest storage. Both disk and cdrom images are supported.
-
-Syntax for specifying iSCSI LUNs is
-``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>''
-
-By default qemu will use the iSCSI initiator-name
-'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command
-line or a configuration file.
-
-Since version Qemu 2.4 it is possible to specify a iSCSI request timeout to detect
-stalled requests and force a reestablishment of the session. The timeout
-is specified in seconds. The default is 0 which means no timeout. Libiscsi
-1.15.0 or greater is required for this feature.
-
-Example (without authentication):
-@example
-qemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
-                 -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
-                 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
-@end example
-
-Example (CHAP username/password via URL):
-@example
-qemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
-@end example
-
-Example (CHAP username/password via environment variables):
-@example
-LIBISCSI_CHAP_USERNAME="user" \
-LIBISCSI_CHAP_PASSWORD="password" \
-qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
-@end example
-
-iSCSI support is an optional feature of QEMU and only available when
-compiled and linked against libiscsi.
-ETEXI
 DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
     "-iscsi [user=user][,password=password]\n"
     "       [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
     "       [,initiator-name=initiator-iqn][,id=target-iqn]\n"
     "       [,timeout=timeout]\n"
     "                iSCSI session parameters\n", QEMU_ARCH_ALL)
-STEXI
-
-iSCSI parameters such as username and password can also be specified via
-a configuration file. See qemu-doc for more information and examples.
-
-@item NBD
-QEMU supports NBD (Network Block Devices) both using TCP protocol as well
-as Unix Domain Sockets.
-
-Syntax for specifying a NBD device using TCP
-``nbd:<server-ip>:<port>[:exportname=<export>]''
-
-Syntax for specifying a NBD device using Unix Domain Sockets
-``nbd:unix:<domain-socket>[:exportname=<export>]''
-
-
-Example for TCP
-@example
-qemu-system-i386 --drive file=nbd:192.0.2.1:30000
-@end example
-
-Example for Unix Domain Sockets
-@example
-qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket
-@end example
-
-@item SSH
-QEMU supports SSH (Secure Shell) access to remote disks.
-
-Examples:
-@example
-qemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img
-qemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
-@end example
-
-Currently authentication must be done using ssh-agent.  Other
-authentication methods may be supported in future.
-
-@item Sheepdog
-Sheepdog is a distributed storage system for QEMU.
-QEMU supports using either local sheepdog devices or remote networked
-devices.
-
-Syntax for specifying a sheepdog device
-@example
-sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
-@end example
-
-Example
-@example
-qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
-@end example
-
-See also @url{https://sheepdog.github.io/sheepdog/}.
-
-@item GlusterFS
-GlusterFS is a user space distributed file system.
-QEMU supports the use of GlusterFS volumes for hosting VM disk images using
-TCP, Unix Domain Sockets and RDMA transport protocols.
-
-Syntax for specifying a VM disk image on GlusterFS volume is
-@example
-
-URI:
-gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
-
-JSON:
-'json:@{"driver":"qcow2","file":@{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
-@                                 "server":[@{"type":"tcp","host":"...","port":"..."@},
-@                                           @{"type":"unix","socket":"..."@}]@}@}'
-@end example
-
-
-Example
-@example
-URI:
-qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img,
-@                               file.debug=9,file.logfile=/var/log/qemu-gluster.log
-
-JSON:
-qemu-system-x86_64 'json:@{"driver":"qcow2",
-@                          "file":@{"driver":"gluster",
-@                                   "volume":"testvol","path":"a.img",
-@                                   "debug":9,"logfile":"/var/log/qemu-gluster.log",
-@                                   "server":[@{"type":"tcp","host":"1.2.3.4","port":24007@},
-@                                             @{"type":"unix","socket":"/var/run/glusterd.socket"@}]@}@}'
-qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
-@                                      file.debug=9,file.logfile=/var/log/qemu-gluster.log,
-@                                      file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
-@                                      file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
-@end example
-
-See also @url{http://www.gluster.org}.
-
-@item HTTP/HTTPS/FTP/FTPS
-QEMU supports read-only access to files accessed over http(s) and ftp(s).
-
-Syntax using a single filename:
-@example
-<protocol>://[<username>[:<password>]@@]<host>/<path>
-@end example
-
-where:
-@table @option
-@item protocol
-'http', 'https', 'ftp', or 'ftps'.
-
-@item username
-Optional username for authentication to the remote server.
-
-@item password
-Optional password for authentication to the remote server.
-
-@item host
-Address of the remote server.
-
-@item path
-Path on the remote server, including any query string.
-@end table
-
-The following options are also supported:
-@table @option
-@item url
-The full URL when passing options to the driver explicitly.
-
-@item readahead
-The amount of data to read ahead with each range request to the remote server.
-This value may optionally have the suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it
-does not have a suffix, it will be assumed to be in bytes. The value must be a
-multiple of 512 bytes. It defaults to 256k.
-
-@item sslverify
-Whether to verify the remote server's certificate when connecting over SSL. It
-can have the value 'on' or 'off'. It defaults to 'on'.
-
-@item cookie
-Send this cookie (it can also be a list of cookies separated by ';') with
-each outgoing request.  Only supported when using protocols such as HTTP
-which support cookies, otherwise ignored.
-
-@item timeout
-Set the timeout in seconds of the CURL connection. This timeout is the time
-that CURL waits for a response from the remote server to get the size of the
-image to be downloaded. If not set, the default timeout of 5 seconds is used.
-@end table
-
-Note that when passing options to qemu explicitly, @option{driver} is the value
-of <protocol>.
-
-Example: boot from a remote Fedora 20 live ISO image
-@example
-qemu-system-x86_64 --drive media=cdrom,file=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
-
-qemu-system-x86_64 --drive media=cdrom,file.driver=http,file.url=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
-@end example
-
-Example: boot from a remote Fedora 20 cloud image using a local overlay for
-writes, copy-on-read, and a readahead of 64k
-@example
-qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"http",, "file.url":"https://dl.fedoraproject.org/pub/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readahead":"64k"@}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2
-
-qemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
-@end example
-
-Example: boot from an image stored on a VMware vSphere server with a self-signed
-certificate using a local overlay for writes, a readahead of 64k and a timeout
-of 10 seconds.
-@example
-qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"https",, "file.url":"https://user:password@@vsphere.example.com/folder/test/test-flat.vmdk?dcPath=Datacenter&dsName=datastore1",, "file.sslverify":"off",, "file.readahead":"64k",, "file.timeout":10@}' /tmp/test.qcow2
-
-qemu-system-x86_64 -drive file=/tmp/test.qcow2
-@end example
-ETEXI
-
-STEXI
-@end table
-ETEXI
 
 DEFHEADING(Bluetooth(R) options:)
 STEXI
-- 
2.13.6

Re: [Qemu-devel] [PATCH 3/8] qemu-options qemu-doc: Move "Device URL Syntax" to qemu-doc

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 1536 bytes --]

On 10/02/2017 09:03 AM, Markus Armbruster wrote:
> Commit 0f5314a (v1.0) added section "Device URL Syntax" to
> qemu-options.hx.  It's enclosed in STEXI..ETEXI, thus affects only
> qemu-options.texi, not --help.  It appears as a subsection under
> section "Invocation".  Similarly, qemu.1 has it as a subsection under
> "OPTIONS".
> 
> Commit f9dadc9 (v1.1.0) dropped new option -iscsi into the middle of
> this section.  No effect on qemu-options.texi.  It appears in --help
> run together with the "Bluetooth(R) options:" header.
> 
> Commit c70a01e (v1.5.0) gives it is own heading in --help by moving
> commit 0f5314a's DEFHEADING(Device URL Syntax:) outside STEXI..ETEXI.
> Trouble is the heading makes no sense for -iscsi.
> 
> Move all of the "Device URL Syntax" Texinfo to qemu-doc.texi.  Mark it
> for inclusion in qemu.1 with '@c man begin NOTES'.  This turns it into
> a separate section outside the list of options both in qemu-doc and in
> qemu.1.
> 
> There's substantial overlap with the existing qemu-doc section "Disk
> Images".  Mark with a TODO comment.
> 
> Output of --help will be fixed next.
> 
> Cc: Ronnie Sahlberg <ronniesahlberg@gmail.com>
> Cc: Kevin Wolf <kwolf@redhat.com>
> Cc: Max Reitz <mreitz@redhat.com>
> Cc: qemu-block@nongnu.org
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 619 bytes --]

Re: [Qemu-devel] [PATCH 3/8] qemu-options qemu-doc: Move "Device URL Syntax" to qemu-doc

[Marc-André Lureau]

On Mon, Oct 2, 2017 at 4:03 PM, Markus Armbruster <armbru@redhat.com> wrote:
> Commit 0f5314a (v1.0) added section "Device URL Syntax" to
> qemu-options.hx.  It's enclosed in STEXI..ETEXI, thus affects only
> qemu-options.texi, not --help.  It appears as a subsection under
> section "Invocation".  Similarly, qemu.1 has it as a subsection under
> "OPTIONS".
>
> Commit f9dadc9 (v1.1.0) dropped new option -iscsi into the middle of
> this section.  No effect on qemu-options.texi.  It appears in --help
> run together with the "Bluetooth(R) options:" header.
>
> Commit c70a01e (v1.5.0) gives it is own heading in --help by moving
> commit 0f5314a's DEFHEADING(Device URL Syntax:) outside STEXI..ETEXI.
> Trouble is the heading makes no sense for -iscsi.
>
> Move all of the "Device URL Syntax" Texinfo to qemu-doc.texi.  Mark it
> for inclusion in qemu.1 with '@c man begin NOTES'.  This turns it into
> a separate section outside the list of options both in qemu-doc and in
> qemu.1.
>
> There's substantial overlap with the existing qemu-doc section "Disk
> Images".  Mark with a TODO comment.
>
> Output of --help will be fixed next.
>
> Cc: Ronnie Sahlberg <ronniesahlberg@gmail.com>
> Cc: Kevin Wolf <kwolf@redhat.com>
> Cc: Max Reitz <mreitz@redhat.com>
> Cc: qemu-block@nongnu.org
> Signed-off-by: Markus Armbruster <armbru@redhat.com>

Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>


> ---
>  qemu-doc.texi   | 217 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  qemu-options.hx | 222 --------------------------------------------------------
>  2 files changed, 217 insertions(+), 222 deletions(-)
>
> diff --git a/qemu-doc.texi b/qemu-doc.texi
> index ecd186a159..848e49966a 100644
> --- a/qemu-doc.texi
> +++ b/qemu-doc.texi
> @@ -245,6 +245,223 @@ targets do not need a disk image.
>
>  @c man end
>
> +@node device_url
> +@subsection Device URL Syntax
> +@c TODO merge this with section Disk Images
> +
> +@c man begin NOTES
> +
> +In addition to using normal file images for the emulated storage devices,
> +QEMU can also use networked resources such as iSCSI devices. These are
> +specified using a special URL syntax.
> +
> +@table @option
> +@item iSCSI
> +iSCSI support allows QEMU to access iSCSI resources directly and use as
> +images for the guest storage. Both disk and cdrom images are supported.
> +
> +Syntax for specifying iSCSI LUNs is
> +``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>''
> +
> +By default qemu will use the iSCSI initiator-name
> +'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command
> +line or a configuration file.
> +
> +Since version Qemu 2.4 it is possible to specify a iSCSI request timeout to detect
> +stalled requests and force a reestablishment of the session. The timeout
> +is specified in seconds. The default is 0 which means no timeout. Libiscsi
> +1.15.0 or greater is required for this feature.
> +
> +Example (without authentication):
> +@example
> +qemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
> +                 -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
> +                 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
> +@end example
> +
> +Example (CHAP username/password via URL):
> +@example
> +qemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
> +@end example
> +
> +Example (CHAP username/password via environment variables):
> +@example
> +LIBISCSI_CHAP_USERNAME="user" \
> +LIBISCSI_CHAP_PASSWORD="password" \
> +qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
> +@end example
> +
> +@item NBD
> +QEMU supports NBD (Network Block Devices) both using TCP protocol as well
> +as Unix Domain Sockets.
> +
> +Syntax for specifying a NBD device using TCP
> +``nbd:<server-ip>:<port>[:exportname=<export>]''
> +
> +Syntax for specifying a NBD device using Unix Domain Sockets
> +``nbd:unix:<domain-socket>[:exportname=<export>]''
> +
> +Example for TCP
> +@example
> +qemu-system-i386 --drive file=nbd:192.0.2.1:30000
> +@end example
> +
> +Example for Unix Domain Sockets
> +@example
> +qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket
> +@end example
> +
> +@item SSH
> +QEMU supports SSH (Secure Shell) access to remote disks.
> +
> +Examples:
> +@example
> +qemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img
> +qemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
> +@end example
> +
> +Currently authentication must be done using ssh-agent.  Other
> +authentication methods may be supported in future.
> +
> +@item Sheepdog
> +Sheepdog is a distributed storage system for QEMU.
> +QEMU supports using either local sheepdog devices or remote networked
> +devices.
> +
> +Syntax for specifying a sheepdog device
> +@example
> +sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
> +@end example
> +
> +Example
> +@example
> +qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
> +@end example
> +
> +See also @url{https://sheepdog.github.io/sheepdog/}.
> +
> +@item GlusterFS
> +GlusterFS is a user space distributed file system.
> +QEMU supports the use of GlusterFS volumes for hosting VM disk images using
> +TCP, Unix Domain Sockets and RDMA transport protocols.
> +
> +Syntax for specifying a VM disk image on GlusterFS volume is
> +@example
> +
> +URI:
> +gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
> +
> +JSON:
> +'json:@{"driver":"qcow2","file":@{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
> +@                                 "server":[@{"type":"tcp","host":"...","port":"..."@},
> +@                                           @{"type":"unix","socket":"..."@}]@}@}'
> +@end example
> +
> +
> +Example
> +@example
> +URI:
> +qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img,
> +@                               file.debug=9,file.logfile=/var/log/qemu-gluster.log
> +
> +JSON:
> +qemu-system-x86_64 'json:@{"driver":"qcow2",
> +@                          "file":@{"driver":"gluster",
> +@                                   "volume":"testvol","path":"a.img",
> +@                                   "debug":9,"logfile":"/var/log/qemu-gluster.log",
> +@                                   "server":[@{"type":"tcp","host":"1.2.3.4","port":24007@},
> +@                                             @{"type":"unix","socket":"/var/run/glusterd.socket"@}]@}@}'
> +qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
> +@                                      file.debug=9,file.logfile=/var/log/qemu-gluster.log,
> +@                                      file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
> +@                                      file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
> +@end example
> +
> +See also @url{http://www.gluster.org}.
> +
> +@item HTTP/HTTPS/FTP/FTPS
> +QEMU supports read-only access to files accessed over http(s) and ftp(s).
> +
> +Syntax using a single filename:
> +@example
> +<protocol>://[<username>[:<password>]@@]<host>/<path>
> +@end example
> +
> +where:
> +@table @option
> +@item protocol
> +'http', 'https', 'ftp', or 'ftps'.
> +
> +@item username
> +Optional username for authentication to the remote server.
> +
> +@item password
> +Optional password for authentication to the remote server.
> +
> +@item host
> +Address of the remote server.
> +
> +@item path
> +Path on the remote server, including any query string.
> +@end table
> +
> +The following options are also supported:
> +@table @option
> +@item url
> +The full URL when passing options to the driver explicitly.
> +
> +@item readahead
> +The amount of data to read ahead with each range request to the remote server.
> +This value may optionally have the suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it
> +does not have a suffix, it will be assumed to be in bytes. The value must be a
> +multiple of 512 bytes. It defaults to 256k.
> +
> +@item sslverify
> +Whether to verify the remote server's certificate when connecting over SSL. It
> +can have the value 'on' or 'off'. It defaults to 'on'.
> +
> +@item cookie
> +Send this cookie (it can also be a list of cookies separated by ';') with
> +each outgoing request.  Only supported when using protocols such as HTTP
> +which support cookies, otherwise ignored.
> +
> +@item timeout
> +Set the timeout in seconds of the CURL connection. This timeout is the time
> +that CURL waits for a response from the remote server to get the size of the
> +image to be downloaded. If not set, the default timeout of 5 seconds is used.
> +@end table
> +
> +Note that when passing options to qemu explicitly, @option{driver} is the value
> +of <protocol>.
> +
> +Example: boot from a remote Fedora 20 live ISO image
> +@example
> +qemu-system-x86_64 --drive media=cdrom,file=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
> +
> +qemu-system-x86_64 --drive media=cdrom,file.driver=http,file.url=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
> +@end example
> +
> +Example: boot from a remote Fedora 20 cloud image using a local overlay for
> +writes, copy-on-read, and a readahead of 64k
> +@example
> +qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"http",, "file.url":"https://dl.fedoraproject.org/pub/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readahead":"64k"@}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2
> +
> +qemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
> +@end example
> +
> +Example: boot from an image stored on a VMware vSphere server with a self-signed
> +certificate using a local overlay for writes, a readahead of 64k and a timeout
> +of 10 seconds.
> +@example
> +qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"https",, "file.url":"https://user:password@@vsphere.example.com/folder/test/test-flat.vmdk?dcPath=Datacenter&dsName=datastore1",, "file.sslverify":"off",, "file.readahead":"64k",, "file.timeout":10@}' /tmp/test.qcow2
> +
> +qemu-system-x86_64 -drive file=/tmp/test.qcow2
> +@end example
> +
> +@end table
> +
> +@c man end
> +
>  @node pcsys_keys
>  @section Keys in the graphical frontends
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 39f0e1b990..f112281d37 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -2812,234 +2812,12 @@ ETEXI
>  DEFHEADING()
>
>  DEFHEADING(Device URL Syntax:)
> -STEXI
> -
> -In addition to using normal file images for the emulated storage devices,
> -QEMU can also use networked resources such as iSCSI devices. These are
> -specified using a special URL syntax.
> -
> -@table @option
> -@item iSCSI
> -iSCSI support allows QEMU to access iSCSI resources directly and use as
> -images for the guest storage. Both disk and cdrom images are supported.
> -
> -Syntax for specifying iSCSI LUNs is
> -``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>''
> -
> -By default qemu will use the iSCSI initiator-name
> -'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command
> -line or a configuration file.
> -
> -Since version Qemu 2.4 it is possible to specify a iSCSI request timeout to detect
> -stalled requests and force a reestablishment of the session. The timeout
> -is specified in seconds. The default is 0 which means no timeout. Libiscsi
> -1.15.0 or greater is required for this feature.
> -
> -Example (without authentication):
> -@example
> -qemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
> -                 -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
> -                 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
> -@end example
> -
> -Example (CHAP username/password via URL):
> -@example
> -qemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
> -@end example
> -
> -Example (CHAP username/password via environment variables):
> -@example
> -LIBISCSI_CHAP_USERNAME="user" \
> -LIBISCSI_CHAP_PASSWORD="password" \
> -qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
> -@end example
> -
> -iSCSI support is an optional feature of QEMU and only available when
> -compiled and linked against libiscsi.
> -ETEXI
>  DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
>      "-iscsi [user=user][,password=password]\n"
>      "       [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
>      "       [,initiator-name=initiator-iqn][,id=target-iqn]\n"
>      "       [,timeout=timeout]\n"
>      "                iSCSI session parameters\n", QEMU_ARCH_ALL)
> -STEXI
> -
> -iSCSI parameters such as username and password can also be specified via
> -a configuration file. See qemu-doc for more information and examples.
> -
> -@item NBD
> -QEMU supports NBD (Network Block Devices) both using TCP protocol as well
> -as Unix Domain Sockets.
> -
> -Syntax for specifying a NBD device using TCP
> -``nbd:<server-ip>:<port>[:exportname=<export>]''
> -
> -Syntax for specifying a NBD device using Unix Domain Sockets
> -``nbd:unix:<domain-socket>[:exportname=<export>]''
> -
> -
> -Example for TCP
> -@example
> -qemu-system-i386 --drive file=nbd:192.0.2.1:30000
> -@end example
> -
> -Example for Unix Domain Sockets
> -@example
> -qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket
> -@end example
> -
> -@item SSH
> -QEMU supports SSH (Secure Shell) access to remote disks.
> -
> -Examples:
> -@example
> -qemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img
> -qemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
> -@end example
> -
> -Currently authentication must be done using ssh-agent.  Other
> -authentication methods may be supported in future.
> -
> -@item Sheepdog
> -Sheepdog is a distributed storage system for QEMU.
> -QEMU supports using either local sheepdog devices or remote networked
> -devices.
> -
> -Syntax for specifying a sheepdog device
> -@example
> -sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
> -@end example
> -
> -Example
> -@example
> -qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
> -@end example
> -
> -See also @url{https://sheepdog.github.io/sheepdog/}.
> -
> -@item GlusterFS
> -GlusterFS is a user space distributed file system.
> -QEMU supports the use of GlusterFS volumes for hosting VM disk images using
> -TCP, Unix Domain Sockets and RDMA transport protocols.
> -
> -Syntax for specifying a VM disk image on GlusterFS volume is
> -@example
> -
> -URI:
> -gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
> -
> -JSON:
> -'json:@{"driver":"qcow2","file":@{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
> -@                                 "server":[@{"type":"tcp","host":"...","port":"..."@},
> -@                                           @{"type":"unix","socket":"..."@}]@}@}'
> -@end example
> -
> -
> -Example
> -@example
> -URI:
> -qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img,
> -@                               file.debug=9,file.logfile=/var/log/qemu-gluster.log
> -
> -JSON:
> -qemu-system-x86_64 'json:@{"driver":"qcow2",
> -@                          "file":@{"driver":"gluster",
> -@                                   "volume":"testvol","path":"a.img",
> -@                                   "debug":9,"logfile":"/var/log/qemu-gluster.log",
> -@                                   "server":[@{"type":"tcp","host":"1.2.3.4","port":24007@},
> -@                                             @{"type":"unix","socket":"/var/run/glusterd.socket"@}]@}@}'
> -qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
> -@                                      file.debug=9,file.logfile=/var/log/qemu-gluster.log,
> -@                                      file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
> -@                                      file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
> -@end example
> -
> -See also @url{http://www.gluster.org}.
> -
> -@item HTTP/HTTPS/FTP/FTPS
> -QEMU supports read-only access to files accessed over http(s) and ftp(s).
> -
> -Syntax using a single filename:
> -@example
> -<protocol>://[<username>[:<password>]@@]<host>/<path>
> -@end example
> -
> -where:
> -@table @option
> -@item protocol
> -'http', 'https', 'ftp', or 'ftps'.
> -
> -@item username
> -Optional username for authentication to the remote server.
> -
> -@item password
> -Optional password for authentication to the remote server.
> -
> -@item host
> -Address of the remote server.
> -
> -@item path
> -Path on the remote server, including any query string.
> -@end table
> -
> -The following options are also supported:
> -@table @option
> -@item url
> -The full URL when passing options to the driver explicitly.
> -
> -@item readahead
> -The amount of data to read ahead with each range request to the remote server.
> -This value may optionally have the suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it
> -does not have a suffix, it will be assumed to be in bytes. The value must be a
> -multiple of 512 bytes. It defaults to 256k.
> -
> -@item sslverify
> -Whether to verify the remote server's certificate when connecting over SSL. It
> -can have the value 'on' or 'off'. It defaults to 'on'.
> -
> -@item cookie
> -Send this cookie (it can also be a list of cookies separated by ';') with
> -each outgoing request.  Only supported when using protocols such as HTTP
> -which support cookies, otherwise ignored.
> -
> -@item timeout
> -Set the timeout in seconds of the CURL connection. This timeout is the time
> -that CURL waits for a response from the remote server to get the size of the
> -image to be downloaded. If not set, the default timeout of 5 seconds is used.
> -@end table
> -
> -Note that when passing options to qemu explicitly, @option{driver} is the value
> -of <protocol>.
> -
> -Example: boot from a remote Fedora 20 live ISO image
> -@example
> -qemu-system-x86_64 --drive media=cdrom,file=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
> -
> -qemu-system-x86_64 --drive media=cdrom,file.driver=http,file.url=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
> -@end example
> -
> -Example: boot from a remote Fedora 20 cloud image using a local overlay for
> -writes, copy-on-read, and a readahead of 64k
> -@example
> -qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"http",, "file.url":"https://dl.fedoraproject.org/pub/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readahead":"64k"@}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2
> -
> -qemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
> -@end example
> -
> -Example: boot from an image stored on a VMware vSphere server with a self-signed
> -certificate using a local overlay for writes, a readahead of 64k and a timeout
> -of 10 seconds.
> -@example
> -qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"https",, "file.url":"https://user:password@@vsphere.example.com/folder/test/test-flat.vmdk?dcPath=Datacenter&dsName=datastore1",, "file.sslverify":"off",, "file.readahead":"64k",, "file.timeout":10@}' /tmp/test.qcow2
> -
> -qemu-system-x86_64 -drive file=/tmp/test.qcow2
> -@end example
> -ETEXI
> -
> -STEXI
> -@end table
> -ETEXI
>
>  DEFHEADING(Bluetooth(R) options:)
>  STEXI
> --
> 2.13.6
>
>



-- 
Marc-André Lureau

Re: [Qemu-devel] [PATCH 3/8] qemu-options qemu-doc: Move "Device URL Syntax" to qemu-doc

[ronnie sahlberg]

On Wed, Oct 4, 2017 at 8:12 PM, Marc-André Lureau
<marcandre.lureau@gmail.com> wrote:
> On Mon, Oct 2, 2017 at 4:03 PM, Markus Armbruster <armbru@redhat.com> wrote:
>> Commit 0f5314a (v1.0) added section "Device URL Syntax" to
>> qemu-options.hx.  It's enclosed in STEXI..ETEXI, thus affects only
>> qemu-options.texi, not --help.  It appears as a subsection under
>> section "Invocation".  Similarly, qemu.1 has it as a subsection under
>> "OPTIONS".
>>
>> Commit f9dadc9 (v1.1.0) dropped new option -iscsi into the middle of
>> this section.  No effect on qemu-options.texi.  It appears in --help
>> run together with the "Bluetooth(R) options:" header.
>>
>> Commit c70a01e (v1.5.0) gives it is own heading in --help by moving
>> commit 0f5314a's DEFHEADING(Device URL Syntax:) outside STEXI..ETEXI.
>> Trouble is the heading makes no sense for -iscsi.
>>
>> Move all of the "Device URL Syntax" Texinfo to qemu-doc.texi.  Mark it
>> for inclusion in qemu.1 with '@c man begin NOTES'.  This turns it into
>> a separate section outside the list of options both in qemu-doc and in
>> qemu.1.
>>
>> There's substantial overlap with the existing qemu-doc section "Disk
>> Images".  Mark with a TODO comment.
>>
>> Output of --help will be fixed next.
>>
>> Cc: Ronnie Sahlberg <ronniesahlberg@gmail.com>
>> Cc: Kevin Wolf <kwolf@redhat.com>
>> Cc: Max Reitz <mreitz@redhat.com>
>> Cc: qemu-block@nongnu.org
>> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>
> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
>
>
>> ---
>>  qemu-doc.texi   | 217 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>>  qemu-options.hx | 222 --------------------------------------------------------
>>  2 files changed, 217 insertions(+), 222 deletions(-)
>>
>> diff --git a/qemu-doc.texi b/qemu-doc.texi
>> index ecd186a159..848e49966a 100644
>> --- a/qemu-doc.texi
>> +++ b/qemu-doc.texi
>> @@ -245,6 +245,223 @@ targets do not need a disk image.
>>
>>  @c man end
>>
>> +@node device_url
>> +@subsection Device URL Syntax
>> +@c TODO merge this with section Disk Images
>> +
>> +@c man begin NOTES
>> +
>> +In addition to using normal file images for the emulated storage devices,
>> +QEMU can also use networked resources such as iSCSI devices. These are
>> +specified using a special URL syntax.
>> +
>> +@table @option
>> +@item iSCSI
>> +iSCSI support allows QEMU to access iSCSI resources directly and use as
>> +images for the guest storage. Both disk and cdrom images are supported.
>> +
>> +Syntax for specifying iSCSI LUNs is
>> +``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>''
>> +
>> +By default qemu will use the iSCSI initiator-name
>> +'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command
>> +line or a configuration file.
>> +
>> +Since version Qemu 2.4 it is possible to specify a iSCSI request timeout to detect
>> +stalled requests and force a reestablishment of the session. The timeout
>> +is specified in seconds. The default is 0 which means no timeout. Libiscsi
>> +1.15.0 or greater is required for this feature.
>> +
>> +Example (without authentication):
>> +@example
>> +qemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
>> +                 -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
>> +                 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
>> +@end example
>> +
>> +Example (CHAP username/password via URL):
>> +@example
>> +qemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
>> +@end example
>> +
>> +Example (CHAP username/password via environment variables):
>> +@example
>> +LIBISCSI_CHAP_USERNAME="user" \
>> +LIBISCSI_CHAP_PASSWORD="password" \
>> +qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
>> +@end example
>> +
>> +@item NBD
>> +QEMU supports NBD (Network Block Devices) both using TCP protocol as well
>> +as Unix Domain Sockets.
>> +
>> +Syntax for specifying a NBD device using TCP
>> +``nbd:<server-ip>:<port>[:exportname=<export>]''
>> +
>> +Syntax for specifying a NBD device using Unix Domain Sockets
>> +``nbd:unix:<domain-socket>[:exportname=<export>]''
>> +
>> +Example for TCP
>> +@example
>> +qemu-system-i386 --drive file=nbd:192.0.2.1:30000
>> +@end example
>> +
>> +Example for Unix Domain Sockets
>> +@example
>> +qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket
>> +@end example
>> +
>> +@item SSH
>> +QEMU supports SSH (Secure Shell) access to remote disks.
>> +
>> +Examples:
>> +@example
>> +qemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img
>> +qemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
>> +@end example
>> +
>> +Currently authentication must be done using ssh-agent.  Other
>> +authentication methods may be supported in future.
>> +
>> +@item Sheepdog
>> +Sheepdog is a distributed storage system for QEMU.
>> +QEMU supports using either local sheepdog devices or remote networked
>> +devices.
>> +
>> +Syntax for specifying a sheepdog device
>> +@example
>> +sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
>> +@end example
>> +
>> +Example
>> +@example
>> +qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
>> +@end example
>> +
>> +See also @url{https://sheepdog.github.io/sheepdog/}.
>> +
>> +@item GlusterFS
>> +GlusterFS is a user space distributed file system.
>> +QEMU supports the use of GlusterFS volumes for hosting VM disk images using
>> +TCP, Unix Domain Sockets and RDMA transport protocols.
>> +
>> +Syntax for specifying a VM disk image on GlusterFS volume is
>> +@example
>> +
>> +URI:
>> +gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
>> +
>> +JSON:
>> +'json:@{"driver":"qcow2","file":@{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
>> +@                                 "server":[@{"type":"tcp","host":"...","port":"..."@},
>> +@                                           @{"type":"unix","socket":"..."@}]@}@}'
>> +@end example
>> +
>> +
>> +Example
>> +@example
>> +URI:
>> +qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img,
>> +@                               file.debug=9,file.logfile=/var/log/qemu-gluster.log
>> +
>> +JSON:
>> +qemu-system-x86_64 'json:@{"driver":"qcow2",
>> +@                          "file":@{"driver":"gluster",
>> +@                                   "volume":"testvol","path":"a.img",
>> +@                                   "debug":9,"logfile":"/var/log/qemu-gluster.log",
>> +@                                   "server":[@{"type":"tcp","host":"1.2.3.4","port":24007@},
>> +@                                             @{"type":"unix","socket":"/var/run/glusterd.socket"@}]@}@}'
>> +qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
>> +@                                      file.debug=9,file.logfile=/var/log/qemu-gluster.log,
>> +@                                      file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
>> +@                                      file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
>> +@end example
>> +
>> +See also @url{http://www.gluster.org}.
>> +
>> +@item HTTP/HTTPS/FTP/FTPS
>> +QEMU supports read-only access to files accessed over http(s) and ftp(s).
>> +
>> +Syntax using a single filename:
>> +@example
>> +<protocol>://[<username>[:<password>]@@]<host>/<path>
>> +@end example
>> +
>> +where:
>> +@table @option
>> +@item protocol
>> +'http', 'https', 'ftp', or 'ftps'.
>> +
>> +@item username
>> +Optional username for authentication to the remote server.
>> +
>> +@item password
>> +Optional password for authentication to the remote server.
>> +
>> +@item host
>> +Address of the remote server.
>> +
>> +@item path
>> +Path on the remote server, including any query string.
>> +@end table
>> +
>> +The following options are also supported:
>> +@table @option
>> +@item url
>> +The full URL when passing options to the driver explicitly.
>> +
>> +@item readahead
>> +The amount of data to read ahead with each range request to the remote server.
>> +This value may optionally have the suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it
>> +does not have a suffix, it will be assumed to be in bytes. The value must be a
>> +multiple of 512 bytes. It defaults to 256k.
>> +
>> +@item sslverify
>> +Whether to verify the remote server's certificate when connecting over SSL. It
>> +can have the value 'on' or 'off'. It defaults to 'on'.
>> +
>> +@item cookie
>> +Send this cookie (it can also be a list of cookies separated by ';') with
>> +each outgoing request.  Only supported when using protocols such as HTTP
>> +which support cookies, otherwise ignored.
>> +
>> +@item timeout
>> +Set the timeout in seconds of the CURL connection. This timeout is the time
>> +that CURL waits for a response from the remote server to get the size of the
>> +image to be downloaded. If not set, the default timeout of 5 seconds is used.
>> +@end table
>> +
>> +Note that when passing options to qemu explicitly, @option{driver} is the value
>> +of <protocol>.
>> +
>> +Example: boot from a remote Fedora 20 live ISO image
>> +@example
>> +qemu-system-x86_64 --drive media=cdrom,file=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
>> +
>> +qemu-system-x86_64 --drive media=cdrom,file.driver=http,file.url=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
>> +@end example
>> +
>> +Example: boot from a remote Fedora 20 cloud image using a local overlay for
>> +writes, copy-on-read, and a readahead of 64k
>> +@example
>> +qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"http",, "file.url":"https://dl.fedoraproject.org/pub/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readahead":"64k"@}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2
>> +
>> +qemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
>> +@end example
>> +
>> +Example: boot from an image stored on a VMware vSphere server with a self-signed
>> +certificate using a local overlay for writes, a readahead of 64k and a timeout
>> +of 10 seconds.
>> +@example
>> +qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"https",, "file.url":"https://user:password@@vsphere.example.com/folder/test/test-flat.vmdk?dcPath=Datacenter&dsName=datastore1",, "file.sslverify":"off",, "file.readahead":"64k",, "file.timeout":10@}' /tmp/test.qcow2
>> +
>> +qemu-system-x86_64 -drive file=/tmp/test.qcow2
>> +@end example
>> +
>> +@end table
>> +
>> +@c man end
>> +
>>  @node pcsys_keys
>>  @section Keys in the graphical frontends
>>
>> diff --git a/qemu-options.hx b/qemu-options.hx
>> index 39f0e1b990..f112281d37 100644
>> --- a/qemu-options.hx
>> +++ b/qemu-options.hx
>> @@ -2812,234 +2812,12 @@ ETEXI
>>  DEFHEADING()
>>
>>  DEFHEADING(Device URL Syntax:)
>> -STEXI
>> -
>> -In addition to using normal file images for the emulated storage devices,
>> -QEMU can also use networked resources such as iSCSI devices. These are
>> -specified using a special URL syntax.
>> -
>> -@table @option
>> -@item iSCSI
>> -iSCSI support allows QEMU to access iSCSI resources directly and use as
>> -images for the guest storage. Both disk and cdrom images are supported.
>> -
>> -Syntax for specifying iSCSI LUNs is
>> -``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>''
>> -
>> -By default qemu will use the iSCSI initiator-name
>> -'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command
>> -line or a configuration file.
>> -
>> -Since version Qemu 2.4 it is possible to specify a iSCSI request timeout to detect
>> -stalled requests and force a reestablishment of the session. The timeout
>> -is specified in seconds. The default is 0 which means no timeout. Libiscsi
>> -1.15.0 or greater is required for this feature.
>> -
>> -Example (without authentication):
>> -@example
>> -qemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
>> -                 -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
>> -                 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
>> -@end example
>> -
>> -Example (CHAP username/password via URL):
>> -@example
>> -qemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
>> -@end example
>> -
>> -Example (CHAP username/password via environment variables):
>> -@example
>> -LIBISCSI_CHAP_USERNAME="user" \
>> -LIBISCSI_CHAP_PASSWORD="password" \
>> -qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
>> -@end example
>> -
>> -iSCSI support is an optional feature of QEMU and only available when
>> -compiled and linked against libiscsi.
>> -ETEXI
>>  DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
>>      "-iscsi [user=user][,password=password]\n"
>>      "       [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
>>      "       [,initiator-name=initiator-iqn][,id=target-iqn]\n"
>>      "       [,timeout=timeout]\n"
>>      "                iSCSI session parameters\n", QEMU_ARCH_ALL)
>> -STEXI
>> -
>> -iSCSI parameters such as username and password can also be specified via
>> -a configuration file. See qemu-doc for more information and examples.
>> -
>> -@item NBD
>> -QEMU supports NBD (Network Block Devices) both using TCP protocol as well
>> -as Unix Domain Sockets.
>> -
>> -Syntax for specifying a NBD device using TCP
>> -``nbd:<server-ip>:<port>[:exportname=<export>]''
>> -
>> -Syntax for specifying a NBD device using Unix Domain Sockets
>> -``nbd:unix:<domain-socket>[:exportname=<export>]''
>> -
>> -
>> -Example for TCP
>> -@example
>> -qemu-system-i386 --drive file=nbd:192.0.2.1:30000
>> -@end example
>> -
>> -Example for Unix Domain Sockets
>> -@example
>> -qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket
>> -@end example
>> -
>> -@item SSH
>> -QEMU supports SSH (Secure Shell) access to remote disks.
>> -
>> -Examples:
>> -@example
>> -qemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img
>> -qemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
>> -@end example
>> -
>> -Currently authentication must be done using ssh-agent.  Other
>> -authentication methods may be supported in future.
>> -
>> -@item Sheepdog
>> -Sheepdog is a distributed storage system for QEMU.
>> -QEMU supports using either local sheepdog devices or remote networked
>> -devices.
>> -
>> -Syntax for specifying a sheepdog device
>> -@example
>> -sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
>> -@end example
>> -
>> -Example
>> -@example
>> -qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
>> -@end example
>> -
>> -See also @url{https://sheepdog.github.io/sheepdog/}.
>> -
>> -@item GlusterFS
>> -GlusterFS is a user space distributed file system.
>> -QEMU supports the use of GlusterFS volumes for hosting VM disk images using
>> -TCP, Unix Domain Sockets and RDMA transport protocols.
>> -
>> -Syntax for specifying a VM disk image on GlusterFS volume is
>> -@example
>> -
>> -URI:
>> -gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
>> -
>> -JSON:
>> -'json:@{"driver":"qcow2","file":@{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
>> -@                                 "server":[@{"type":"tcp","host":"...","port":"..."@},
>> -@                                           @{"type":"unix","socket":"..."@}]@}@}'
>> -@end example
>> -
>> -
>> -Example
>> -@example
>> -URI:
>> -qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img,
>> -@                               file.debug=9,file.logfile=/var/log/qemu-gluster.log
>> -
>> -JSON:
>> -qemu-system-x86_64 'json:@{"driver":"qcow2",
>> -@                          "file":@{"driver":"gluster",
>> -@                                   "volume":"testvol","path":"a.img",
>> -@                                   "debug":9,"logfile":"/var/log/qemu-gluster.log",
>> -@                                   "server":[@{"type":"tcp","host":"1.2.3.4","port":24007@},
>> -@                                             @{"type":"unix","socket":"/var/run/glusterd.socket"@}]@}@}'
>> -qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
>> -@                                      file.debug=9,file.logfile=/var/log/qemu-gluster.log,
>> -@                                      file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
>> -@                                      file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
>> -@end example
>> -
>> -See also @url{http://www.gluster.org}.
>> -
>> -@item HTTP/HTTPS/FTP/FTPS
>> -QEMU supports read-only access to files accessed over http(s) and ftp(s).
>> -
>> -Syntax using a single filename:
>> -@example
>> -<protocol>://[<username>[:<password>]@@]<host>/<path>
>> -@end example
>> -
>> -where:
>> -@table @option
>> -@item protocol
>> -'http', 'https', 'ftp', or 'ftps'.
>> -
>> -@item username
>> -Optional username for authentication to the remote server.
>> -
>> -@item password
>> -Optional password for authentication to the remote server.
>> -
>> -@item host
>> -Address of the remote server.
>> -
>> -@item path
>> -Path on the remote server, including any query string.
>> -@end table
>> -
>> -The following options are also supported:
>> -@table @option
>> -@item url
>> -The full URL when passing options to the driver explicitly.
>> -
>> -@item readahead
>> -The amount of data to read ahead with each range request to the remote server.
>> -This value may optionally have the suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it
>> -does not have a suffix, it will be assumed to be in bytes. The value must be a
>> -multiple of 512 bytes. It defaults to 256k.
>> -
>> -@item sslverify
>> -Whether to verify the remote server's certificate when connecting over SSL. It
>> -can have the value 'on' or 'off'. It defaults to 'on'.
>> -
>> -@item cookie
>> -Send this cookie (it can also be a list of cookies separated by ';') with
>> -each outgoing request.  Only supported when using protocols such as HTTP
>> -which support cookies, otherwise ignored.
>> -
>> -@item timeout
>> -Set the timeout in seconds of the CURL connection. This timeout is the time
>> -that CURL waits for a response from the remote server to get the size of the
>> -image to be downloaded. If not set, the default timeout of 5 seconds is used.
>> -@end table
>> -
>> -Note that when passing options to qemu explicitly, @option{driver} is the value
>> -of <protocol>.
>> -
>> -Example: boot from a remote Fedora 20 live ISO image
>> -@example
>> -qemu-system-x86_64 --drive media=cdrom,file=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
>> -
>> -qemu-system-x86_64 --drive media=cdrom,file.driver=http,file.url=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
>> -@end example
>> -
>> -Example: boot from a remote Fedora 20 cloud image using a local overlay for
>> -writes, copy-on-read, and a readahead of 64k
>> -@example
>> -qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"http",, "file.url":"https://dl.fedoraproject.org/pub/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readahead":"64k"@}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2
>> -
>> -qemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
>> -@end example
>> -
>> -Example: boot from an image stored on a VMware vSphere server with a self-signed
>> -certificate using a local overlay for writes, a readahead of 64k and a timeout
>> -of 10 seconds.
>> -@example
>> -qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"https",, "file.url":"https://user:password@@vsphere.example.com/folder/test/test-flat.vmdk?dcPath=Datacenter&dsName=datastore1",, "file.sslverify":"off",, "file.readahead":"64k",, "file.timeout":10@}' /tmp/test.qcow2
>> -
>> -qemu-system-x86_64 -drive file=/tmp/test.qcow2
>> -@end example
>> -ETEXI
>> -
>> -STEXI
>> -@end table
>> -ETEXI
>>
>>  DEFHEADING(Bluetooth(R) options:)
>>  STEXI
>> --
>> 2.13.6
>>
>>
>
>
>
> --
> Marc-André Lureau

Reviewed-by: Ronnie Sahlberg <ronniesahlberg@gmail.com>


At some stage maybe getting rid of
+Example (CHAP username/password via URL):
+@example
+qemu-system-i386 -drive
file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
+@end example
+

and only document the "set user/password via ENV"
as it was probably a mistake to allow setting these via the URL in the
first place.

Possibly consider not document that it is possible to use the URL for
user/password
as to discourage its use?

Re: [Qemu-devel] [PATCH 3/8] qemu-options qemu-doc: Move "Device URL Syntax" to qemu-doc

[Markus Armbruster]

ronnie sahlberg <ronniesahlberg@gmail.com> writes:

> On Wed, Oct 4, 2017 at 8:12 PM, Marc-André Lureau
> <marcandre.lureau@gmail.com> wrote:
>> On Mon, Oct 2, 2017 at 4:03 PM, Markus Armbruster <armbru@redhat.com> wrote:
>>> Commit 0f5314a (v1.0) added section "Device URL Syntax" to
>>> qemu-options.hx.  It's enclosed in STEXI..ETEXI, thus affects only
>>> qemu-options.texi, not --help.  It appears as a subsection under
>>> section "Invocation".  Similarly, qemu.1 has it as a subsection under
>>> "OPTIONS".
>>>
>>> Commit f9dadc9 (v1.1.0) dropped new option -iscsi into the middle of
>>> this section.  No effect on qemu-options.texi.  It appears in --help
>>> run together with the "Bluetooth(R) options:" header.
>>>
>>> Commit c70a01e (v1.5.0) gives it is own heading in --help by moving
>>> commit 0f5314a's DEFHEADING(Device URL Syntax:) outside STEXI..ETEXI.
>>> Trouble is the heading makes no sense for -iscsi.
>>>
>>> Move all of the "Device URL Syntax" Texinfo to qemu-doc.texi.  Mark it
>>> for inclusion in qemu.1 with '@c man begin NOTES'.  This turns it into
>>> a separate section outside the list of options both in qemu-doc and in
>>> qemu.1.
>>>
>>> There's substantial overlap with the existing qemu-doc section "Disk
>>> Images".  Mark with a TODO comment.
>>>
>>> Output of --help will be fixed next.
>>>
>>> Cc: Ronnie Sahlberg <ronniesahlberg@gmail.com>
>>> Cc: Kevin Wolf <kwolf@redhat.com>
>>> Cc: Max Reitz <mreitz@redhat.com>
>>> Cc: qemu-block@nongnu.org
>>> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>>
>> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
>>
>>
>>> ---
>>>  qemu-doc.texi   | 217 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>>>  qemu-options.hx | 222 --------------------------------------------------------
>>>  2 files changed, 217 insertions(+), 222 deletions(-)
>>>
>>> diff --git a/qemu-doc.texi b/qemu-doc.texi
>>> index ecd186a159..848e49966a 100644
>>> --- a/qemu-doc.texi
>>> +++ b/qemu-doc.texi
>>> @@ -245,6 +245,223 @@ targets do not need a disk image.
>>>
>>>  @c man end
>>>
>>> +@node device_url
>>> +@subsection Device URL Syntax
>>> +@c TODO merge this with section Disk Images
>>> +
>>> +@c man begin NOTES
>>> +
>>> +In addition to using normal file images for the emulated storage devices,
>>> +QEMU can also use networked resources such as iSCSI devices. These are
>>> +specified using a special URL syntax.
>>> +
>>> +@table @option
>>> +@item iSCSI
>>> +iSCSI support allows QEMU to access iSCSI resources directly and use as
>>> +images for the guest storage. Both disk and cdrom images are supported.
>>> +
>>> +Syntax for specifying iSCSI LUNs is
>>> +``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>''
>>> +
>>> +By default qemu will use the iSCSI initiator-name
>>> +'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command
>>> +line or a configuration file.
>>> +
>>> +Since version Qemu 2.4 it is possible to specify a iSCSI request timeout to detect
>>> +stalled requests and force a reestablishment of the session. The timeout
>>> +is specified in seconds. The default is 0 which means no timeout. Libiscsi
>>> +1.15.0 or greater is required for this feature.
>>> +
>>> +Example (without authentication):
>>> +@example
>>> +qemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
>>> +                 -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
>>> +                 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
>>> +@end example
>>> +
>>> +Example (CHAP username/password via URL):
>>> +@example
>>> +qemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
>>> +@end example
>>> +
>>> +Example (CHAP username/password via environment variables):
>>> +@example
>>> +LIBISCSI_CHAP_USERNAME="user" \
>>> +LIBISCSI_CHAP_PASSWORD="password" \
>>> +qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
>>> +@end example
>>> +
>>> +@item NBD
>>> +QEMU supports NBD (Network Block Devices) both using TCP protocol as well
>>> +as Unix Domain Sockets.
>>> +
>>> +Syntax for specifying a NBD device using TCP
>>> +``nbd:<server-ip>:<port>[:exportname=<export>]''
>>> +
>>> +Syntax for specifying a NBD device using Unix Domain Sockets
>>> +``nbd:unix:<domain-socket>[:exportname=<export>]''
>>> +
>>> +Example for TCP
>>> +@example
>>> +qemu-system-i386 --drive file=nbd:192.0.2.1:30000
>>> +@end example
>>> +
>>> +Example for Unix Domain Sockets
>>> +@example
>>> +qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket
>>> +@end example
>>> +
>>> +@item SSH
>>> +QEMU supports SSH (Secure Shell) access to remote disks.
>>> +
>>> +Examples:
>>> +@example
>>> +qemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img
>>> +qemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
>>> +@end example
>>> +
>>> +Currently authentication must be done using ssh-agent.  Other
>>> +authentication methods may be supported in future.
>>> +
>>> +@item Sheepdog
>>> +Sheepdog is a distributed storage system for QEMU.
>>> +QEMU supports using either local sheepdog devices or remote networked
>>> +devices.
>>> +
>>> +Syntax for specifying a sheepdog device
>>> +@example
>>> +sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
>>> +@end example
>>> +
>>> +Example
>>> +@example
>>> +qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
>>> +@end example
>>> +
>>> +See also @url{https://sheepdog.github.io/sheepdog/}.
>>> +
>>> +@item GlusterFS
>>> +GlusterFS is a user space distributed file system.
>>> +QEMU supports the use of GlusterFS volumes for hosting VM disk images using
>>> +TCP, Unix Domain Sockets and RDMA transport protocols.
>>> +
>>> +Syntax for specifying a VM disk image on GlusterFS volume is
>>> +@example
>>> +
>>> +URI:
>>> +gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
>>> +
>>> +JSON:
>>> +'json:@{"driver":"qcow2","file":@{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
>>> +@                                 "server":[@{"type":"tcp","host":"...","port":"..."@},
>>> +@                                           @{"type":"unix","socket":"..."@}]@}@}'
>>> +@end example
>>> +
>>> +
>>> +Example
>>> +@example
>>> +URI:
>>> +qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img,
>>> +@                               file.debug=9,file.logfile=/var/log/qemu-gluster.log
>>> +
>>> +JSON:
>>> +qemu-system-x86_64 'json:@{"driver":"qcow2",
>>> +@                          "file":@{"driver":"gluster",
>>> +@                                   "volume":"testvol","path":"a.img",
>>> +@                                   "debug":9,"logfile":"/var/log/qemu-gluster.log",
>>> +@                                   "server":[@{"type":"tcp","host":"1.2.3.4","port":24007@},
>>> +@                                             @{"type":"unix","socket":"/var/run/glusterd.socket"@}]@}@}'
>>> +qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
>>> +@                                      file.debug=9,file.logfile=/var/log/qemu-gluster.log,
>>> +@                                      file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
>>> +@                                      file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
>>> +@end example
>>> +
>>> +See also @url{http://www.gluster.org}.
>>> +
>>> +@item HTTP/HTTPS/FTP/FTPS
>>> +QEMU supports read-only access to files accessed over http(s) and ftp(s).
>>> +
>>> +Syntax using a single filename:
>>> +@example
>>> +<protocol>://[<username>[:<password>]@@]<host>/<path>
>>> +@end example
>>> +
>>> +where:
>>> +@table @option
>>> +@item protocol
>>> +'http', 'https', 'ftp', or 'ftps'.
>>> +
>>> +@item username
>>> +Optional username for authentication to the remote server.
>>> +
>>> +@item password
>>> +Optional password for authentication to the remote server.
>>> +
>>> +@item host
>>> +Address of the remote server.
>>> +
>>> +@item path
>>> +Path on the remote server, including any query string.
>>> +@end table
>>> +
>>> +The following options are also supported:
>>> +@table @option
>>> +@item url
>>> +The full URL when passing options to the driver explicitly.
>>> +
>>> +@item readahead
>>> +The amount of data to read ahead with each range request to the remote server.
>>> +This value may optionally have the suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it
>>> +does not have a suffix, it will be assumed to be in bytes. The value must be a
>>> +multiple of 512 bytes. It defaults to 256k.
>>> +
>>> +@item sslverify
>>> +Whether to verify the remote server's certificate when connecting over SSL. It
>>> +can have the value 'on' or 'off'. It defaults to 'on'.
>>> +
>>> +@item cookie
>>> +Send this cookie (it can also be a list of cookies separated by ';') with
>>> +each outgoing request.  Only supported when using protocols such as HTTP
>>> +which support cookies, otherwise ignored.
>>> +
>>> +@item timeout
>>> +Set the timeout in seconds of the CURL connection. This timeout is the time
>>> +that CURL waits for a response from the remote server to get the size of the
>>> +image to be downloaded. If not set, the default timeout of 5 seconds is used.
>>> +@end table
>>> +
>>> +Note that when passing options to qemu explicitly, @option{driver} is the value
>>> +of <protocol>.
>>> +
>>> +Example: boot from a remote Fedora 20 live ISO image
>>> +@example
>>> +qemu-system-x86_64 --drive media=cdrom,file=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
>>> +
>>> +qemu-system-x86_64 --drive media=cdrom,file.driver=http,file.url=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
>>> +@end example
>>> +
>>> +Example: boot from a remote Fedora 20 cloud image using a local overlay for
>>> +writes, copy-on-read, and a readahead of 64k
>>> +@example
>>> +qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"http",, "file.url":"https://dl.fedoraproject.org/pub/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readahead":"64k"@}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2
>>> +
>>> +qemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
>>> +@end example
>>> +
>>> +Example: boot from an image stored on a VMware vSphere server with a self-signed
>>> +certificate using a local overlay for writes, a readahead of 64k and a timeout
>>> +of 10 seconds.
>>> +@example
>>> +qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"https",, "file.url":"https://user:password@@vsphere.example.com/folder/test/test-flat.vmdk?dcPath=Datacenter&dsName=datastore1",, "file.sslverify":"off",, "file.readahead":"64k",, "file.timeout":10@}' /tmp/test.qcow2
>>> +
>>> +qemu-system-x86_64 -drive file=/tmp/test.qcow2
>>> +@end example
>>> +
>>> +@end table
>>> +
>>> +@c man end
>>> +
>>>  @node pcsys_keys
>>>  @section Keys in the graphical frontends
>>>
>>> diff --git a/qemu-options.hx b/qemu-options.hx
>>> index 39f0e1b990..f112281d37 100644
>>> --- a/qemu-options.hx
>>> +++ b/qemu-options.hx
>>> @@ -2812,234 +2812,12 @@ ETEXI
>>>  DEFHEADING()
>>>
>>>  DEFHEADING(Device URL Syntax:)
>>> -STEXI
>>> -
>>> -In addition to using normal file images for the emulated storage devices,
>>> -QEMU can also use networked resources such as iSCSI devices. These are
>>> -specified using a special URL syntax.
>>> -
>>> -@table @option
>>> -@item iSCSI
>>> -iSCSI support allows QEMU to access iSCSI resources directly and use as
>>> -images for the guest storage. Both disk and cdrom images are supported.
>>> -
>>> -Syntax for specifying iSCSI LUNs is
>>> -``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>''
>>> -
>>> -By default qemu will use the iSCSI initiator-name
>>> -'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command
>>> -line or a configuration file.
>>> -
>>> -Since version Qemu 2.4 it is possible to specify a iSCSI request timeout to detect
>>> -stalled requests and force a reestablishment of the session. The timeout
>>> -is specified in seconds. The default is 0 which means no timeout. Libiscsi
>>> -1.15.0 or greater is required for this feature.
>>> -
>>> -Example (without authentication):
>>> -@example
>>> -qemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
>>> -                 -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
>>> -                 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
>>> -@end example
>>> -
>>> -Example (CHAP username/password via URL):
>>> -@example
>>> -qemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
>>> -@end example
>>> -
>>> -Example (CHAP username/password via environment variables):
>>> -@example
>>> -LIBISCSI_CHAP_USERNAME="user" \
>>> -LIBISCSI_CHAP_PASSWORD="password" \
>>> -qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
>>> -@end example
[...]
>
> Reviewed-by: Ronnie Sahlberg <ronniesahlberg@gmail.com>
>
>
> At some stage maybe getting rid of
> +Example (CHAP username/password via URL):
> +@example
> +qemu-system-i386 -drive
> file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
> +@end example
> +
>
> and only document the "set user/password via ENV"
> as it was probably a mistake to allow setting these via the URL in the
> first place.
>
> Possibly consider not document that it is possible to use the URL for
> user/password
> as to discourage its use?

I think the appropriate way to do that would be deprecating the feature
in a separate patch, in accordance with the policy laid down in
qemu-doc's appendix "Deprecated features".

I think backing out any documentation added in the current development
cycle in such a patch would be just fine.

[Qemu-devel] [PATCH 4/8] qemu-options: Move -iscsi under "Block device options"

[Markus Armbruster]

-iscsi ended up under the "Device URL Syntax" heading by a sequence of
errors, as explained in the previous commit.  Move it under the "Block
device options" heading.  Nothing left under "Device URL Syntax";
drop the heading.

Cc: Ronnie Sahlberg <ronniesahlberg@gmail.com>
Cc: Kevin Wolf <kwolf@redhat.com>
Cc: Max Reitz <mreitz@redhat.com>
Cc: qemu-block@nongnu.org
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qemu-options.hx | 15 +++++++--------
 1 file changed, 7 insertions(+), 8 deletions(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index f112281d37..c647fdde62 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -1172,6 +1172,13 @@ STEXI
 Create synthetic file system image
 ETEXI
 
+DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
+    "-iscsi [user=user][,password=password]\n"
+    "       [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
+    "       [,initiator-name=initiator-iqn][,id=target-iqn]\n"
+    "       [,timeout=timeout]\n"
+    "                iSCSI session parameters\n", QEMU_ARCH_ALL)
+
 STEXI
 @end table
 ETEXI
@@ -2811,14 +2818,6 @@ STEXI
 ETEXI
 DEFHEADING()
 
-DEFHEADING(Device URL Syntax:)
-DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
-    "-iscsi [user=user][,password=password]\n"
-    "       [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
-    "       [,initiator-name=initiator-iqn][,id=target-iqn]\n"
-    "       [,timeout=timeout]\n"
-    "                iSCSI session parameters\n", QEMU_ARCH_ALL)
-
 DEFHEADING(Bluetooth(R) options:)
 STEXI
 @table @option
-- 
2.13.6

Re: [Qemu-devel] [PATCH 4/8] qemu-options: Move -iscsi under "Block device options"

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 784 bytes --]

On 10/02/2017 09:03 AM, Markus Armbruster wrote:
> -iscsi ended up under the "Device URL Syntax" heading by a sequence of
> errors, as explained in the previous commit.  Move it under the "Block
> device options" heading.  Nothing left under "Device URL Syntax";
> drop the heading.
> 
> Cc: Ronnie Sahlberg <ronniesahlberg@gmail.com>
> Cc: Kevin Wolf <kwolf@redhat.com>
> Cc: Max Reitz <mreitz@redhat.com>
> Cc: qemu-block@nongnu.org
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  qemu-options.hx | 15 +++++++--------
>  1 file changed, 7 insertions(+), 8 deletions(-)
> 

Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 619 bytes --]

Re: [Qemu-devel] [PATCH 4/8] qemu-options: Move -iscsi under "Block device options"

[Marc-André Lureau]

On Mon, Oct 2, 2017 at 4:03 PM, Markus Armbruster <armbru@redhat.com> wrote:
> -iscsi ended up under the "Device URL Syntax" heading by a sequence of
> errors, as explained in the previous commit.  Move it under the "Block
> device options" heading.  Nothing left under "Device URL Syntax";
> drop the heading.
>
> Cc: Ronnie Sahlberg <ronniesahlberg@gmail.com>
> Cc: Kevin Wolf <kwolf@redhat.com>
> Cc: Max Reitz <mreitz@redhat.com>
> Cc: qemu-block@nongnu.org
> Signed-off-by: Markus Armbruster <armbru@redhat.com>

Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>


> ---
>  qemu-options.hx | 15 +++++++--------
>  1 file changed, 7 insertions(+), 8 deletions(-)
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index f112281d37..c647fdde62 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -1172,6 +1172,13 @@ STEXI
>  Create synthetic file system image
>  ETEXI
>
> +DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
> +    "-iscsi [user=user][,password=password]\n"
> +    "       [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
> +    "       [,initiator-name=initiator-iqn][,id=target-iqn]\n"
> +    "       [,timeout=timeout]\n"
> +    "                iSCSI session parameters\n", QEMU_ARCH_ALL)
> +
>  STEXI
>  @end table
>  ETEXI
> @@ -2811,14 +2818,6 @@ STEXI
>  ETEXI
>  DEFHEADING()
>
> -DEFHEADING(Device URL Syntax:)
> -DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
> -    "-iscsi [user=user][,password=password]\n"
> -    "       [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
> -    "       [,initiator-name=initiator-iqn][,id=target-iqn]\n"
> -    "       [,timeout=timeout]\n"
> -    "                iSCSI session parameters\n", QEMU_ARCH_ALL)
> -
>  DEFHEADING(Bluetooth(R) options:)
>  STEXI
>  @table @option
> --
> 2.13.6
>
>



-- 
Marc-André Lureau

Re: [Qemu-devel] [PATCH 4/8] qemu-options: Move -iscsi under "Block device options"

[ronnie sahlberg]

Reviewed-by: Ronnie Sahlberg <ronniesahlberg@gmail.com>

Would be nice if this died at some stage :
[,password=password]

But that is for a different patch.

On Wed, Oct 4, 2017 at 8:12 PM, Marc-André Lureau
<marcandre.lureau@gmail.com> wrote:
> On Mon, Oct 2, 2017 at 4:03 PM, Markus Armbruster <armbru@redhat.com> wrote:
>> -iscsi ended up under the "Device URL Syntax" heading by a sequence of
>> errors, as explained in the previous commit.  Move it under the "Block
>> device options" heading.  Nothing left under "Device URL Syntax";
>> drop the heading.
>>
>> Cc: Ronnie Sahlberg <ronniesahlberg@gmail.com>
>> Cc: Kevin Wolf <kwolf@redhat.com>
>> Cc: Max Reitz <mreitz@redhat.com>
>> Cc: qemu-block@nongnu.org
>> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>
> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
>
>
>> ---
>>  qemu-options.hx | 15 +++++++--------
>>  1 file changed, 7 insertions(+), 8 deletions(-)
>>
>> diff --git a/qemu-options.hx b/qemu-options.hx
>> index f112281d37..c647fdde62 100644
>> --- a/qemu-options.hx
>> +++ b/qemu-options.hx
>> @@ -1172,6 +1172,13 @@ STEXI
>>  Create synthetic file system image
>>  ETEXI
>>
>> +DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
>> +    "-iscsi [user=user][,password=password]\n"
>> +    "       [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
>> +    "       [,initiator-name=initiator-iqn][,id=target-iqn]\n"
>> +    "       [,timeout=timeout]\n"
>> +    "                iSCSI session parameters\n", QEMU_ARCH_ALL)
>> +
>>  STEXI
>>  @end table
>>  ETEXI
>> @@ -2811,14 +2818,6 @@ STEXI
>>  ETEXI
>>  DEFHEADING()
>>
>> -DEFHEADING(Device URL Syntax:)
>> -DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
>> -    "-iscsi [user=user][,password=password]\n"
>> -    "       [,header-digest=CRC32C|CR32C-NONE|NONE-CRC32C|NONE\n"
>> -    "       [,initiator-name=initiator-iqn][,id=target-iqn]\n"
>> -    "       [,timeout=timeout]\n"
>> -    "                iSCSI session parameters\n", QEMU_ARCH_ALL)
>> -
>>  DEFHEADING(Bluetooth(R) options:)
>>  STEXI
>>  @table @option
>> --
>> 2.13.6
>>
>>
>
>
>
> --
> Marc-André Lureau

[Qemu-devel] [PATCH 5/8] qemu-options: Add missing -iscsi Texinfo documentation

[Markus Armbruster]

Cc: Ronnie Sahlberg <ronniesahlberg@gmail.com>
Cc: Kevin Wolf <kwolf@redhat.com>
Cc: Max Reitz <mreitz@redhat.com>
Cc: qemu-block@nongnu.org
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qemu-options.hx | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/qemu-options.hx b/qemu-options.hx
index c647fdde62..8568ee388c 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -1180,6 +1180,12 @@ DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
     "                iSCSI session parameters\n", QEMU_ARCH_ALL)
 
 STEXI
+@item -iscsi
+@findex -iscsi
+Configure iSCSI session parameters.
+ETEXI
+
+STEXI
 @end table
 ETEXI
 DEFHEADING()
-- 
2.13.6

Re: [Qemu-devel] [PATCH 5/8] qemu-options: Add missing -iscsi Texinfo documentation

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 955 bytes --]

On 10/02/2017 09:03 AM, Markus Armbruster wrote:
> Cc: Ronnie Sahlberg <ronniesahlberg@gmail.com>
> Cc: Kevin Wolf <kwolf@redhat.com>
> Cc: Max Reitz <mreitz@redhat.com>
> Cc: qemu-block@nongnu.org
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  qemu-options.hx | 6 ++++++
>  1 file changed, 6 insertions(+)
> 

Reviewed-by: Eric Blake <eblake@redhat.com>

> diff --git a/qemu-options.hx b/qemu-options.hx
> index c647fdde62..8568ee388c 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -1180,6 +1180,12 @@ DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
>      "                iSCSI session parameters\n", QEMU_ARCH_ALL)
>  
>  STEXI
> +@item -iscsi
> +@findex -iscsi
> +Configure iSCSI session parameters.
> +ETEXI
> +
> +STEXI
>  @end table
>  ETEXI
>  DEFHEADING()
> 

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 619 bytes --]

Re: [Qemu-devel] [PATCH 5/8] qemu-options: Add missing -iscsi Texinfo documentation

[Marc-André Lureau]

On Mon, Oct 2, 2017 at 4:03 PM, Markus Armbruster <armbru@redhat.com> wrote:
> Cc: Ronnie Sahlberg <ronniesahlberg@gmail.com>
> Cc: Kevin Wolf <kwolf@redhat.com>
> Cc: Max Reitz <mreitz@redhat.com>
> Cc: qemu-block@nongnu.org
> Signed-off-by: Markus Armbruster <armbru@redhat.com>

Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
(that's very short doc)


> ---
>  qemu-options.hx | 6 ++++++
>  1 file changed, 6 insertions(+)
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index c647fdde62..8568ee388c 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -1180,6 +1180,12 @@ DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
>      "                iSCSI session parameters\n", QEMU_ARCH_ALL)
>
>  STEXI
> +@item -iscsi
> +@findex -iscsi
> +Configure iSCSI session parameters.
> +ETEXI
> +
> +STEXI
>  @end table
>  ETEXI
>  DEFHEADING()
> --
> 2.13.6
>
>



-- 
Marc-André Lureau

Re: [Qemu-devel] [PATCH 5/8] qemu-options: Add missing -iscsi Texinfo documentation

[Markus Armbruster]

Marc-André Lureau <marcandre.lureau@gmail.com> writes:

> On Mon, Oct 2, 2017 at 4:03 PM, Markus Armbruster <armbru@redhat.com> wrote:
>> Cc: Ronnie Sahlberg <ronniesahlberg@gmail.com>
>> Cc: Kevin Wolf <kwolf@redhat.com>
>> Cc: Max Reitz <mreitz@redhat.com>
>> Cc: qemu-block@nongnu.org
>> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>
> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> (that's very short doc)

No argument.  It's what I could do while cleaning up a mess that's
blocking my path to what I really want to do.  Patches welcome :)

>> ---
>>  qemu-options.hx | 6 ++++++
>>  1 file changed, 6 insertions(+)
>>
>> diff --git a/qemu-options.hx b/qemu-options.hx
>> index c647fdde62..8568ee388c 100644
>> --- a/qemu-options.hx
>> +++ b/qemu-options.hx
>> @@ -1180,6 +1180,12 @@ DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
>>      "                iSCSI session parameters\n", QEMU_ARCH_ALL)
>>
>>  STEXI
>> +@item -iscsi
>> +@findex -iscsi
>> +Configure iSCSI session parameters.
>> +ETEXI
>> +
>> +STEXI
>>  @end table
>>  ETEXI
>>  DEFHEADING()
>> --
>> 2.13.6
>>
>>

Re: [Qemu-devel] [PATCH 5/8] qemu-options: Add missing -iscsi Texinfo documentation

[ronnie sahlberg]

Reviewed-by: Ronnie Sahlberg <ronniesahlberg@gmail.com>

On Tue, Oct 3, 2017 at 12:03 AM, Markus Armbruster <armbru@redhat.com> wrote:
> Cc: Ronnie Sahlberg <ronniesahlberg@gmail.com>
> Cc: Kevin Wolf <kwolf@redhat.com>
> Cc: Max Reitz <mreitz@redhat.com>
> Cc: qemu-block@nongnu.org
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  qemu-options.hx | 6 ++++++
>  1 file changed, 6 insertions(+)
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index c647fdde62..8568ee388c 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -1180,6 +1180,12 @@ DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi,
>      "                iSCSI session parameters\n", QEMU_ARCH_ALL)
>
>  STEXI
> +@item -iscsi
> +@findex -iscsi
> +Configure iSCSI session parameters.
> +ETEXI
> +
> +STEXI
>  @end table
>  ETEXI
>  DEFHEADING()
> --
> 2.13.6
>

[Qemu-devel] [PATCH 6/8] qemu-options: Polish section "TPM device options"

[Markus Armbruster]

Cc: Stefan Berger <stefanb@linux.vnet.ibm.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qemu-options.hx | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index 8568ee388c..615cb230ab 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -2915,19 +2915,18 @@ The general form of a TPM device option is:
 
 @item -tpmdev @var{backend} ,id=@var{id} [,@var{options}]
 @findex -tpmdev
-Backend type must be:
-@option{passthrough}.
 
 The specific backend type will determine the applicable options.
 The @code{-tpmdev} option creates the TPM backend and requires a
 @code{-device} option that specifies the TPM frontend interface model.
 
-Options to each backend are described below.
+Use @code{-tpmdev help} to print all available TPM backend types.
 
-Use 'help' to print all available TPM backend types.
-@example
-qemu -tpmdev help
-@end example
+@end table
+
+The available backends are:
+
+@table @option
 
 @item -tpmdev passthrough, id=@var{id}, path=@var{path}, cancel-path=@var{cancel-path}
 
@@ -2966,10 +2965,11 @@ To create a passthrough TPM use the following two options:
 Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by
 @code{tpmdev=tpm0} in the device option.
 
+ETEXI
+
+STEXI
 @end table
-
 ETEXI
-
 DEFHEADING()
 
 #endif
-- 
2.13.6

Re: [Qemu-devel] [PATCH 6/8] qemu-options: Polish section "TPM device options"

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 440 bytes --]

On 10/02/2017 09:03 AM, Markus Armbruster wrote:
> Cc: Stefan Berger <stefanb@linux.vnet.ibm.com>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  qemu-options.hx | 18 +++++++++---------
>  1 file changed, 9 insertions(+), 9 deletions(-)
> 
Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 619 bytes --]

Re: [Qemu-devel] [PATCH 6/8] qemu-options: Polish section "TPM device options"

[Marc-André Lureau]

On Mon, Oct 2, 2017 at 4:03 PM, Markus Armbruster <armbru@redhat.com> wrote:
> Cc: Stefan Berger <stefanb@linux.vnet.ibm.com>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>

Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>



> ---
>  qemu-options.hx | 18 +++++++++---------
>  1 file changed, 9 insertions(+), 9 deletions(-)
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 8568ee388c..615cb230ab 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -2915,19 +2915,18 @@ The general form of a TPM device option is:
>
>  @item -tpmdev @var{backend} ,id=@var{id} [,@var{options}]
>  @findex -tpmdev
> -Backend type must be:
> -@option{passthrough}.
>
>  The specific backend type will determine the applicable options.
>  The @code{-tpmdev} option creates the TPM backend and requires a
>  @code{-device} option that specifies the TPM frontend interface model.
>
> -Options to each backend are described below.
> +Use @code{-tpmdev help} to print all available TPM backend types.
>
> -Use 'help' to print all available TPM backend types.
> -@example
> -qemu -tpmdev help
> -@end example
> +@end table
> +
> +The available backends are:
> +
> +@table @option
>
>  @item -tpmdev passthrough, id=@var{id}, path=@var{path}, cancel-path=@var{cancel-path}
>
> @@ -2966,10 +2965,11 @@ To create a passthrough TPM use the following two options:
>  Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by
>  @code{tpmdev=tpm0} in the device option.
>
> +ETEXI
> +
> +STEXI
>  @end table
> -
>  ETEXI
> -
>  DEFHEADING()
>
>  #endif
> --
> 2.13.6
>
>



-- 
Marc-André Lureau

[Qemu-devel] [PATCH 7/8] qemu-options: Polish section "Character device options"

[Markus Armbruster]

Cc: Paolo Bonzini <pbonzini@redhat.com>
CC: Marc-André Lureau <marcandre.lureau@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qemu-options.hx | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index 615cb230ab..b792c65149 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -2492,11 +2492,6 @@ ETEXI
 DEFHEADING()
 
 DEFHEADING(Character device options:)
-STEXI
-
-The general form of a character device option is:
-@table @option
-ETEXI
 
 DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
     "-chardev help\n"
@@ -2542,6 +2537,9 @@ DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
 )
 
 STEXI
+
+The general form of a character device option is:
+@table @option
 @item -chardev @var{backend} ,id=@var{id} [,mux=on|off] [,@var{options}]
 @findex -chardev
 Backend is one of:
@@ -2565,7 +2563,7 @@ Backend is one of:
 @option{spiceport}.
 The specific backend will determine the applicable options.
 
-Use "-chardev help" to print all available chardev backend types.
+Use @code{-chardev help} to print all available chardev backend types.
 
 All devices must have an id, which can be any string up to 127 characters long.
 It is used to uniquely identify this device in other command line directives.
@@ -2620,8 +2618,11 @@ to a file to record all data transmitted via the backend. The @option{logappend}
 option controls whether the log file will be truncated or appended to when
 opened.
 
-Further options to each backend are described below.
+@end table
 
+The available backends are:
+
+@table @option
 @item -chardev null ,id=@var{id}
 A void device. This device will not emit any data, and will drop any data it
 receives. The null backend does not take any options.
-- 
2.13.6

Re: [Qemu-devel] [PATCH 7/8] qemu-options: Polish section "Character device options"

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 488 bytes --]

On 10/02/2017 09:03 AM, Markus Armbruster wrote:
> Cc: Paolo Bonzini <pbonzini@redhat.com>
> CC: Marc-André Lureau <marcandre.lureau@redhat.com>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  qemu-options.hx | 15 ++++++++-------
>  1 file changed, 8 insertions(+), 7 deletions(-)
> 

Reviewed-by: Eric Blake <eblake@redhat.com>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 619 bytes --]

Re: [Qemu-devel] [PATCH 7/8] qemu-options: Polish section "Character device options"

[Marc-André Lureau]

On Mon, Oct 2, 2017 at 4:03 PM, Markus Armbruster <armbru@redhat.com> wrote:
> Cc: Paolo Bonzini <pbonzini@redhat.com>
> CC: Marc-André Lureau <marcandre.lureau@redhat.com>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>

Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>


> ---
>  qemu-options.hx | 15 ++++++++-------
>  1 file changed, 8 insertions(+), 7 deletions(-)
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 615cb230ab..b792c65149 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -2492,11 +2492,6 @@ ETEXI
>  DEFHEADING()
>
>  DEFHEADING(Character device options:)
> -STEXI
> -
> -The general form of a character device option is:
> -@table @option
> -ETEXI
>
>  DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
>      "-chardev help\n"
> @@ -2542,6 +2537,9 @@ DEF("chardev", HAS_ARG, QEMU_OPTION_chardev,
>  )
>
>  STEXI
> +
> +The general form of a character device option is:
> +@table @option
>  @item -chardev @var{backend} ,id=@var{id} [,mux=on|off] [,@var{options}]
>  @findex -chardev
>  Backend is one of:
> @@ -2565,7 +2563,7 @@ Backend is one of:
>  @option{spiceport}.
>  The specific backend will determine the applicable options.
>
> -Use "-chardev help" to print all available chardev backend types.
> +Use @code{-chardev help} to print all available chardev backend types.
>
>  All devices must have an id, which can be any string up to 127 characters long.
>  It is used to uniquely identify this device in other command line directives.
> @@ -2620,8 +2618,11 @@ to a file to record all data transmitted via the backend. The @option{logappend}
>  option controls whether the log file will be truncated or appended to when
>  opened.
>
> -Further options to each backend are described below.
> +@end table
>
> +The available backends are:
> +
> +@table @option
>  @item -chardev null ,id=@var{id}
>  A void device. This device will not emit any data, and will drop any data it
>  receives. The null backend does not take any options.
> --
> 2.13.6
>
>



-- 
Marc-André Lureau

[Qemu-devel] [PATCH 8/8] qemu-options: Belatedly document --watchdog-action inject-nmi

[Markus Armbruster]

Missed in commit 795dc6e46d, v2.4.0.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qemu-options.hx | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/qemu-options.hx b/qemu-options.hx
index b792c65149..32afc11296 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -3596,7 +3596,7 @@ A virtual watchdog for s390x backed by the diagnose 288 hypercall
 ETEXI
 
 DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
-    "-watchdog-action reset|shutdown|poweroff|pause|debug|none\n" \
+    "-watchdog-action reset|shutdown|poweroff|inject-nmi|pause|debug|none\n" \
     "                action when watchdog fires [default=reset]\n",
     QEMU_ARCH_ALL)
 STEXI
@@ -3610,6 +3610,7 @@ The default is
 Other possible actions are:
 @code{shutdown} (attempt to gracefully shutdown the guest),
 @code{poweroff} (forcefully poweroff the guest),
+@code{inject-nmi} (inject a NMI into the guest),
 @code{pause} (pause the guest),
 @code{debug} (print a debug message and continue), or
 @code{none} (do nothing).
-- 
2.13.6

Re: [Qemu-devel] [PATCH 8/8] qemu-options: Belatedly document --watchdog-action inject-nmi

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 1363 bytes --]

On 10/02/2017 09:03 AM, Markus Armbruster wrote:
> Missed in commit 795dc6e46d, v2.4.0.
> 
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  qemu-options.hx | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)

Reviewed-by: Eric Blake <eblake@redhat.com>

> 
> diff --git a/qemu-options.hx b/qemu-options.hx
> index b792c65149..32afc11296 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -3596,7 +3596,7 @@ A virtual watchdog for s390x backed by the diagnose 288 hypercall
>  ETEXI
>  
>  DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
> -    "-watchdog-action reset|shutdown|poweroff|pause|debug|none\n" \
> +    "-watchdog-action reset|shutdown|poweroff|inject-nmi|pause|debug|none\n" \
>      "                action when watchdog fires [default=reset]\n",
>      QEMU_ARCH_ALL)
>  STEXI
> @@ -3610,6 +3610,7 @@ The default is
>  Other possible actions are:
>  @code{shutdown} (attempt to gracefully shutdown the guest),
>  @code{poweroff} (forcefully poweroff the guest),
> +@code{inject-nmi} (inject a NMI into the guest),
>  @code{pause} (pause the guest),
>  @code{debug} (print a debug message and continue), or
>  @code{none} (do nothing).
> 

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 619 bytes --]

Re: [Qemu-devel] [PATCH 8/8] qemu-options: Belatedly document --watchdog-action inject-nmi

[Marc-André Lureau]

On Mon, Oct 2, 2017 at 4:03 PM, Markus Armbruster <armbru@redhat.com> wrote:
> Missed in commit 795dc6e46d, v2.4.0.
>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>

Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>


> ---
>  qemu-options.hx | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
>
> diff --git a/qemu-options.hx b/qemu-options.hx
> index b792c65149..32afc11296 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -3596,7 +3596,7 @@ A virtual watchdog for s390x backed by the diagnose 288 hypercall
>  ETEXI
>
>  DEF("watchdog-action", HAS_ARG, QEMU_OPTION_watchdog_action, \
> -    "-watchdog-action reset|shutdown|poweroff|pause|debug|none\n" \
> +    "-watchdog-action reset|shutdown|poweroff|inject-nmi|pause|debug|none\n" \
>      "                action when watchdog fires [default=reset]\n",
>      QEMU_ARCH_ALL)
>  STEXI
> @@ -3610,6 +3610,7 @@ The default is
>  Other possible actions are:
>  @code{shutdown} (attempt to gracefully shutdown the guest),
>  @code{poweroff} (forcefully poweroff the guest),
> +@code{inject-nmi} (inject a NMI into the guest),
>  @code{pause} (pause the guest),
>  @code{debug} (print a debug message and continue), or
>  @code{none} (do nothing).
> --
> 2.13.6
>
>



-- 
Marc-André Lureau