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