qemu-nbd.texi

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