You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

qemu-nbd.texi 7.8KB

  1. @example
  2. @c man begin SYNOPSIS
  3. @command{qemu-nbd} [OPTION]... @var{filename}
  4. @command{qemu-nbd} @option{-L} [OPTION]...
  5. @command{qemu-nbd} @option{-d} @var{dev}
  6. @c man end
  7. @end example
  8. @c man begin DESCRIPTION
  9. Export a QEMU disk image using the NBD protocol.
  10. Other uses:
  11. @itemize
  12. @item
  13. Bind a /dev/nbdX block device to a QEMU server (on Linux).
  14. @item
  15. As a client to query exports of a remote NBD server.
  16. @end itemize
  17. @c man end
  18. @c man begin OPTIONS
  19. @var{filename} is a disk image filename, or a set of block
  20. driver options if @option{--image-opts} is specified.
  21. @var{dev} is an NBD device.
  22. @table @option
  23. @item --object type,id=@var{id},...props...
  24. Define a new instance of the @var{type} object class identified by @var{id}.
  25. See the @code{qemu(1)} manual page for full details of the properties
  26. supported. The common object types that it makes sense to define are the
  27. @code{secret} object, which is used to supply passwords and/or encryption
  28. keys, and the @code{tls-creds} object, which is used to supply TLS
  29. credentials for the qemu-nbd server or client.
  30. @item -p, --port=@var{port}
  31. The TCP port to listen on as a server, or connect to as a client
  32. (default @samp{10809}).
  33. @item -o, --offset=@var{offset}
  34. The offset into the image.
  35. @item -b, --bind=@var{iface}
  36. The interface to bind to as a server, or connect to as a client
  37. (default @samp{}).
  38. @item -k, --socket=@var{path}
  39. Use a unix socket with path @var{path}.
  40. @item --image-opts
  41. Treat @var{filename} as a set of image options, instead of a plain
  42. filename. If this flag is specified, the @var{-f} flag should
  43. not be used, instead the '@code{format=}' option should be set.
  44. @item -f, --format=@var{fmt}
  45. Force the use of the block driver for format @var{fmt} instead of
  46. auto-detecting.
  47. @item -r, --read-only
  48. Export the disk as read-only.
  49. @item -P, --partition=@var{num}
  50. Deprecated: Only expose MBR partition @var{num}. Understands physical
  51. partitions 1-4 and logical partition 5. New code should instead use
  52. @option{--image-opts} with the raw driver wrapping a subset of the
  53. original image.
  54. @item -B, --bitmap=@var{name}
  55. If @var{filename} has a qcow2 persistent bitmap @var{name}, expose
  56. that bitmap via the ``qemu:dirty-bitmap:@var{name}'' context
  57. accessible through NBD_OPT_SET_META_CONTEXT.
  58. @item -s, --snapshot
  59. Use @var{filename} as an external snapshot, create a temporary
  60. file with backing_file=@var{filename}, redirect the write to
  61. the temporary one.
  62. @item -l, --load-snapshot=@var{snapshot_param}
  63. Load an internal snapshot inside @var{filename} and export it
  64. as an read-only device, @var{snapshot_param} format is
  65. '[ID],[NAME]' or '[ID_OR_NAME]'
  66. @item -n, --nocache
  67. @itemx --cache=@var{cache}
  68. The cache mode to be used with the file. See the documentation of
  69. the emulator's @code{-drive cache=...} option for allowed values.
  70. @item --aio=@var{aio}
  71. Set the asynchronous I/O mode between @samp{threads} (the default)
  72. and @samp{native} (Linux only).
  73. @item --discard=@var{discard}
  74. Control whether @dfn{discard} (also known as @dfn{trim} or @dfn{unmap})
  75. requests are ignored or passed to the filesystem. @var{discard} is one of
  76. @samp{ignore} (or @samp{off}), @samp{unmap} (or @samp{on}). The default is
  77. @samp{ignore}.
  78. @item --detect-zeroes=@var{detect-zeroes}
  79. Control the automatic conversion of plain zero writes by the OS to
  80. driver-specific optimized zero write commands. @var{detect-zeroes} is one of
  81. @samp{off}, @samp{on} or @samp{unmap}. @samp{unmap}
  82. converts a zero write to an unmap operation and can only be used if
  83. @var{discard} is set to @samp{unmap}. The default is @samp{off}.
  84. @item -c, --connect=@var{dev}
  85. Connect @var{filename} to NBD device @var{dev} (Linux only).
  86. @item -d, --disconnect
  87. Disconnect the device @var{dev} (Linux only).
  88. @item -e, --shared=@var{num}
  89. Allow up to @var{num} clients to share the device (default
  90. @samp{1}). Safe for readers, but for now, consistency is not
  91. guaranteed between multiple writers.
  92. @item -t, --persistent
  93. Don't exit on the last connection.
  94. @item -x, --export-name=@var{name}
  95. Set the NBD volume export name (default of a zero-length string).
  96. @item -D, --description=@var{description}
  97. Set the NBD volume export description, as a human-readable
  98. string.
  99. @item -L, --list
  100. Connect as a client and list all details about the exports exposed by
  101. a remote NBD server. This enables list mode, and is incompatible
  102. with options that change behavior related to a specific export (such as
  103. @option{--export-name}, @option{--offset}, ...).
  104. @item --tls-creds=ID
  105. Enable mandatory TLS encryption for the server by setting the ID
  106. of the TLS credentials object previously created with the --object
  107. option; or provide the credentials needed for connecting as a client
  108. in list mode.
  109. @item --fork
  110. Fork off the server process and exit the parent once the server is running.
  111. @item --pid-file=PATH
  112. Store the server's process ID in the given file.
  113. @item --tls-authz=ID
  114. Specify the ID of a qauthz object previously created with the
  115. --object option. This will be used to authorize connecting users
  116. against their x509 distinguished name.
  117. @item -v, --verbose
  118. Display extra debugging information.
  119. @item -h, --help
  120. Display this help and exit.
  121. @item -V, --version
  122. Display version information and exit.
  123. @item -T, --trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}]
  124. @findex --trace
  125. @include qemu-option-trace.texi
  126. @end table
  127. @c man end
  128. @c man begin EXAMPLES
  129. Start a server listening on port 10809 that exposes only the
  130. guest-visible contents of a qcow2 file, with no TLS encryption, and
  131. with the default export name (an empty string). The command is
  132. one-shot, and will block until the first successful client
  133. disconnects:
  134. @example
  135. qemu-nbd -f qcow2 file.qcow2
  136. @end example
  137. Start a long-running server listening with encryption on port 10810,
  138. and whitelist clients with a specific X.509 certificate to connect to
  139. a 1 megabyte subset of a raw file, using the export name 'subset':
  140. @example
  141. qemu-nbd \
  142. --object tls-creds-x509,id=tls0,endpoint=server,dir=/path/to/qemutls \
  143. --object 'authz-simple,id=auth0,,,\
  144. O=Example Org,,L=London,,ST=London,,C=GB' \
  145. --tls-creds tls0 --tls-authz auth0 \
  146. -t -x subset -p 10810 \
  147. --image-opts driver=raw,offset=1M,size=1M,file.driver=file,file.filename=file.raw
  148. @end example
  149. Serve a read-only copy of just the first MBR partition of a guest
  150. image over a Unix socket with as many as 5 simultaneous readers, with
  151. a persistent process forked as a daemon:
  152. @example
  153. qemu-nbd --fork --persistent --shared=5 --socket=/path/to/sock \
  154. --partition=1 --read-only --format=qcow2 file.qcow2
  155. @end example
  156. Expose the guest-visible contents of a qcow2 file via a block device
  157. /dev/nbd0 (and possibly creating /dev/nbd0p1 and friends for
  158. partitions found within), then disconnect the device when done.
  159. Access to bind qemu-nbd to an /dev/nbd device generally requires root
  160. privileges, and may also require the execution of @code{modprobe nbd}
  161. to enable the kernel NBD client module. @emph{CAUTION}: Do not use
  162. this method to mount filesystems from an untrusted guest image - a
  163. malicious guest may have prepared the image to attempt to trigger
  164. kernel bugs in partition probing or file system mounting.
  165. @example
  166. qemu-nbd -c /dev/nbd0 -f qcow2 file.qcow2
  167. qemu-nbd -d /dev/nbd0
  168. @end example
  169. Query a remote server to see details about what export(s) it is
  170. serving on port 10809, and authenticating via PSK:
  171. @example
  172. qemu-nbd \
  173. --object tls-creds-psk,id=tls0,dir=/tmp/keys,username=eblake,endpoint=client \
  174. --tls-creds tls0 -L -b
  175. @end example
  176. @c man end
  177. @ignore
  178. @setfilename qemu-nbd
  179. @settitle QEMU Disk Network Block Device Server
  180. @c man begin AUTHOR
  181. Copyright (C) 2006 Anthony Liguori <>.
  182. This is free software; see the source for copying conditions. There is NO
  184. @c man end
  185. @c man begin SEEALSO
  186. qemu(1), qemu-img(1)
  187. @c man end
  188. @end ignore