Merge remote-tracking branch 'remotes/mst/tags/for_upstream' into staging
[qemu/ar7.git] / qemu-nbd.texi
blob9a84e81eed9c82a7bc62451151659366f79c20db
1 @example
2 @c man begin SYNOPSIS
3 @command{qemu-nbd} [OPTION]... @var{filename}
5 @command{qemu-nbd} @option{-d} @var{dev}
6 @c man end
7 @end example
9 @c man begin DESCRIPTION
11 Export a QEMU disk image using the NBD protocol.
13 @c man end
15 @c man begin OPTIONS
16 @var{filename} is a disk image filename, or a set of block
17 driver options if @var{--image-opts} is specified.
19 @var{dev} is an NBD device.
21 @table @option
22 @item --object type,id=@var{id},...props...
23 Define a new instance of the @var{type} object class identified by @var{id}.
24 See the @code{qemu(1)} manual page for full details of the properties
25 supported. The common object types that it makes sense to define are the
26 @code{secret} object, which is used to supply passwords and/or encryption
27 keys, and the @code{tls-creds} object, which is used to supply TLS
28 credentials for the qemu-nbd server.
29 @item -p, --port=@var{port}
30 The TCP port to listen on (default @samp{10809})
31 @item -o, --offset=@var{offset}
32 The offset into the image
33 @item -b, --bind=@var{iface}
34 The interface to bind to (default @samp{0.0.0.0})
35 @item -k, --socket=@var{path}
36 Use a unix socket with path @var{path}
37 @item --image-opts
38 Treat @var{filename} as a set of image options, instead of a plain
39 filename. If this flag is specified, the @var{-f} flag should
40 not be used, instead the '@code{format=}' option should be set.
41 @item -f, --format=@var{fmt}
42 Force the use of the block driver for format @var{fmt} instead of
43 auto-detecting
44 @item -r, --read-only
45 Export the disk as read-only
46 @item -P, --partition=@var{num}
47 Only expose partition @var{num}
48 @item -s, --snapshot
49 Use @var{filename} as an external snapshot, create a temporary
50 file with backing_file=@var{filename}, redirect the write to
51 the temporary one
52 @item -l, --load-snapshot=@var{snapshot_param}
53 Load an internal snapshot inside @var{filename} and export it
54 as an read-only device, @var{snapshot_param} format is
55 'snapshot.id=[ID],snapshot.name=[NAME]' or '[ID_OR_NAME]'
56 @item -n, --nocache
57 @itemx --cache=@var{cache}
58 The cache mode to be used with the file.  See the documentation of
59 the emulator's @code{-drive cache=...} option for allowed values.
60 @item --aio=@var{aio}
61 Set the asynchronous I/O mode between @samp{threads} (the default)
62 and @samp{native} (Linux only).
63 @item --discard=@var{discard}
64 Control whether @dfn{discard} (also known as @dfn{trim} or @dfn{unmap})
65 requests are ignored or passed to the filesystem.  @var{discard} is one of
66 @samp{ignore} (or @samp{off}), @samp{unmap} (or @samp{on}).  The default is
67 @samp{ignore}.
68 @item --detect-zeroes=@var{detect-zeroes}
69 Control the automatic conversion of plain zero writes by the OS to
70 driver-specific optimized zero write commands.  @var{detect-zeroes} is one of
71 @samp{off}, @samp{on} or @samp{unmap}.  @samp{unmap}
72 converts a zero write to an unmap operation and can only be used if
73 @var{discard} is set to @samp{unmap}.  The default is @samp{off}.
74 @item -c, --connect=@var{dev}
75 Connect @var{filename} to NBD device @var{dev}
76 @item -d, --disconnect
77 Disconnect the device @var{dev}
78 @item -e, --shared=@var{num}
79 Allow up to @var{num} clients to share the device (default @samp{1})
80 @item -t, --persistent
81 Don't exit on the last connection
82 @item -x, --export-name=@var{name}
83 Set the NBD volume export name. This switches the server to use
84 the new style NBD protocol negotiation
85 @item -D, --description=@var{description}
86 Set the NBD volume export description, as a human-readable
87 string. Requires the use of @option{-x}
88 @item --tls-creds=ID
89 Enable mandatory TLS encryption for the server by setting the ID
90 of the TLS credentials object previously created with the --object
91 option.
92 @item --fork
93 Fork off the server process and exit the parent once the server is running.
94 @item -v, --verbose
95 Display extra debugging information
96 @item -h, --help
97 Display this help and exit
98 @item -V, --version
99 Display version information and exit
100 @item -T, --trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}]
101 @findex --trace
102 @include qemu-option-trace.texi
103 @end table
105 @c man end
107 @ignore
109 @setfilename qemu-nbd
110 @settitle QEMU Disk Network Block Device Server
112 @c man begin AUTHOR
113 Copyright (C) 2006 Anthony Liguori <anthony@codemonkey.ws>.
114 This is free software; see the source for copying conditions.  There is NO
115 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
116 @c man end
118 @c man begin SEEALSO
119 qemu(1), qemu-img(1)
120 @c man end
122 @end ignore