xref: /qemu/docs/tools/qemu-nbd.rst (revision 8f75cae2dda8a55eb3a6c712bd22b18a90c0a5ac)
18a1f7d29SPaolo Bonzini=====================================
287c0868fSPeter MaydellQEMU Disk Network Block Device Server
387c0868fSPeter Maydell=====================================
487c0868fSPeter Maydell
587c0868fSPeter MaydellSynopsis
687c0868fSPeter Maydell--------
787c0868fSPeter Maydell
887c0868fSPeter Maydell**qemu-nbd** [*OPTION*]... *filename*
987c0868fSPeter Maydell
1087c0868fSPeter Maydell**qemu-nbd** -L [*OPTION*]...
1187c0868fSPeter Maydell
1287c0868fSPeter Maydell**qemu-nbd** -d *dev*
1387c0868fSPeter Maydell
1487c0868fSPeter MaydellDescription
1587c0868fSPeter Maydell-----------
1687c0868fSPeter Maydell
1787c0868fSPeter MaydellExport a QEMU disk image using the NBD protocol.
1887c0868fSPeter Maydell
1987c0868fSPeter MaydellOther uses:
2087c0868fSPeter Maydell
2187c0868fSPeter Maydell- Bind a /dev/nbdX block device to a QEMU server (on Linux).
2287c0868fSPeter Maydell- As a client to query exports of a remote NBD server.
2387c0868fSPeter Maydell
2487c0868fSPeter MaydellOptions
2587c0868fSPeter Maydell-------
2687c0868fSPeter Maydell
2787c0868fSPeter Maydell.. program:: qemu-nbd
2887c0868fSPeter Maydell
2987c0868fSPeter Maydell*filename* is a disk image filename, or a set of block
3087c0868fSPeter Maydelldriver options if ``--image-opts`` is specified.
3187c0868fSPeter Maydell
3287c0868fSPeter Maydell*dev* is an NBD device.
3387c0868fSPeter Maydell
34*8f75cae2SRao, Lei.. option:: --object type,id=ID,...
3587c0868fSPeter Maydell
3687c0868fSPeter Maydell  Define a new instance of the *type* object class identified by *ID*.
3787c0868fSPeter Maydell  See the :manpage:`qemu(1)` manual page for full details of the properties
3887c0868fSPeter Maydell  supported. The common object types that it makes sense to define are the
3987c0868fSPeter Maydell  ``secret`` object, which is used to supply passwords and/or encryption
4087c0868fSPeter Maydell  keys, and the ``tls-creds`` object, which is used to supply TLS
4187c0868fSPeter Maydell  credentials for the qemu-nbd server or client.
4287c0868fSPeter Maydell
4387c0868fSPeter Maydell.. option:: -p, --port=PORT
4487c0868fSPeter Maydell
4587c0868fSPeter Maydell  TCP port to listen on as a server, or connect to as a client
4687c0868fSPeter Maydell  (default ``10809``).
4787c0868fSPeter Maydell
4887c0868fSPeter Maydell.. option:: -o, --offset=OFFSET
4987c0868fSPeter Maydell
5087c0868fSPeter Maydell  The offset into the image.
5187c0868fSPeter Maydell
5287c0868fSPeter Maydell.. option:: -b, --bind=IFACE
5387c0868fSPeter Maydell
5487c0868fSPeter Maydell  The interface to bind to as a server, or connect to as a client
5587c0868fSPeter Maydell  (default ``0.0.0.0``).
5687c0868fSPeter Maydell
5787c0868fSPeter Maydell.. option:: -k, --socket=PATH
5887c0868fSPeter Maydell
5987c0868fSPeter Maydell  Use a unix socket with path *PATH*.
6087c0868fSPeter Maydell
6187c0868fSPeter Maydell.. option:: --image-opts
6287c0868fSPeter Maydell
6387c0868fSPeter Maydell  Treat *filename* as a set of image options, instead of a plain
6487c0868fSPeter Maydell  filename. If this flag is specified, the ``-f`` flag should
6587c0868fSPeter Maydell  not be used, instead the :option:`format=` option should be set.
6687c0868fSPeter Maydell
6787c0868fSPeter Maydell.. option:: -f, --format=FMT
6887c0868fSPeter Maydell
6987c0868fSPeter Maydell  Force the use of the block driver for format *FMT* instead of
7087c0868fSPeter Maydell  auto-detecting.
7187c0868fSPeter Maydell
7287c0868fSPeter Maydell.. option:: -r, --read-only
7387c0868fSPeter Maydell
7487c0868fSPeter Maydell  Export the disk as read-only.
7587c0868fSPeter Maydell
76dbc7b014SEric Blake.. option:: -A, --allocation-depth
77dbc7b014SEric Blake
78dbc7b014SEric Blake  Expose allocation depth information via the
79dbc7b014SEric Blake  ``qemu:allocation-depth`` metadata context accessible through
80dbc7b014SEric Blake  NBD_OPT_SET_META_CONTEXT.
81dbc7b014SEric Blake
8287c0868fSPeter Maydell.. option:: -B, --bitmap=NAME
8387c0868fSPeter Maydell
8487c0868fSPeter Maydell  If *filename* has a qcow2 persistent bitmap *NAME*, expose
85dbc7b014SEric Blake  that bitmap via the ``qemu:dirty-bitmap:NAME`` metadata context
8687c0868fSPeter Maydell  accessible through NBD_OPT_SET_META_CONTEXT.
8787c0868fSPeter Maydell
8887c0868fSPeter Maydell.. option:: -s, --snapshot
8987c0868fSPeter Maydell
9087c0868fSPeter Maydell  Use *filename* as an external snapshot, create a temporary
9187c0868fSPeter Maydell  file with ``backing_file=``\ *filename*, redirect the write to
9287c0868fSPeter Maydell  the temporary one.
9387c0868fSPeter Maydell
9487c0868fSPeter Maydell.. option:: -l, --load-snapshot=SNAPSHOT_PARAM
9587c0868fSPeter Maydell
9687c0868fSPeter Maydell  Load an internal snapshot inside *filename* and export it
9787c0868fSPeter Maydell  as an read-only device, SNAPSHOT_PARAM format is
9887c0868fSPeter Maydell  ``snapshot.id=[ID],snapshot.name=[NAME]`` or ``[ID_OR_NAME]``
9987c0868fSPeter Maydell
10087c0868fSPeter Maydell.. option:: --cache=CACHE
10187c0868fSPeter Maydell
10209615257SNir Soffer  The cache mode to be used with the file. Valid values are:
10309615257SNir Soffer  ``none``, ``writeback`` (the default), ``writethrough``,
10409615257SNir Soffer  ``directsync`` and ``unsafe``. See the documentation of
10509615257SNir Soffer  the emulator's ``-drive cache=...`` option for more info.
10687c0868fSPeter Maydell
10787c0868fSPeter Maydell.. option:: -n, --nocache
10887c0868fSPeter Maydell
10987c0868fSPeter Maydell  Equivalent to :option:`--cache=none`.
11087c0868fSPeter Maydell
11187c0868fSPeter Maydell.. option:: --aio=AIO
11287c0868fSPeter Maydell
1137680274dSAarushi Mehta  Set the asynchronous I/O mode between ``threads`` (the default),
1147680274dSAarushi Mehta  ``native`` (Linux only), and ``io_uring`` (Linux 5.1+).
11587c0868fSPeter Maydell
11687c0868fSPeter Maydell.. option:: --discard=DISCARD
11787c0868fSPeter Maydell
11887c0868fSPeter Maydell  Control whether ``discard`` (also known as ``trim`` or ``unmap``)
11987c0868fSPeter Maydell  requests are ignored or passed to the filesystem. *DISCARD* is one of
12087c0868fSPeter Maydell  ``ignore`` (or ``off``), ``unmap`` (or ``on``).  The default is
12187c0868fSPeter Maydell  ``ignore``.
12287c0868fSPeter Maydell
12387c0868fSPeter Maydell.. option:: --detect-zeroes=DETECT_ZEROES
12487c0868fSPeter Maydell
12587c0868fSPeter Maydell  Control the automatic conversion of plain zero writes by the OS to
12687c0868fSPeter Maydell  driver-specific optimized zero write commands.  *DETECT_ZEROES* is one of
12787c0868fSPeter Maydell  ``off``, ``on``, or ``unmap``.  ``unmap``
12887c0868fSPeter Maydell  converts a zero write to an unmap operation and can only be used if
12987c0868fSPeter Maydell  *DISCARD* is set to ``unmap``.  The default is ``off``.
13087c0868fSPeter Maydell
13187c0868fSPeter Maydell.. option:: -c, --connect=DEV
13287c0868fSPeter Maydell
13387c0868fSPeter Maydell  Connect *filename* to NBD device *DEV* (Linux only).
13487c0868fSPeter Maydell
13587c0868fSPeter Maydell.. option:: -d, --disconnect
13687c0868fSPeter Maydell
13787c0868fSPeter Maydell  Disconnect the device *DEV* (Linux only).
13887c0868fSPeter Maydell
13987c0868fSPeter Maydell.. option:: -e, --shared=NUM
14087c0868fSPeter Maydell
14187c0868fSPeter Maydell  Allow up to *NUM* clients to share the device (default
1423dcf56e6SEric Blake  ``1``), 0 for unlimited. Safe for readers, but for now,
1433dcf56e6SEric Blake  consistency is not guaranteed between multiple writers.
14487c0868fSPeter Maydell
14587c0868fSPeter Maydell.. option:: -t, --persistent
14687c0868fSPeter Maydell
14787c0868fSPeter Maydell  Don't exit on the last connection.
14887c0868fSPeter Maydell
14987c0868fSPeter Maydell.. option:: -x, --export-name=NAME
15087c0868fSPeter Maydell
15187c0868fSPeter Maydell  Set the NBD volume export name (default of a zero-length string).
15287c0868fSPeter Maydell
15387c0868fSPeter Maydell.. option:: -D, --description=DESCRIPTION
15487c0868fSPeter Maydell
15587c0868fSPeter Maydell  Set the NBD volume export description, as a human-readable
15687c0868fSPeter Maydell  string.
15787c0868fSPeter Maydell
15887c0868fSPeter Maydell.. option:: -L, --list
15987c0868fSPeter Maydell
16087c0868fSPeter Maydell  Connect as a client and list all details about the exports exposed by
16187c0868fSPeter Maydell  a remote NBD server.  This enables list mode, and is incompatible
16287c0868fSPeter Maydell  with options that change behavior related to a specific export (such as
16387c0868fSPeter Maydell  :option:`--export-name`, :option:`--offset`, ...).
16487c0868fSPeter Maydell
16587c0868fSPeter Maydell.. option:: --tls-creds=ID
16687c0868fSPeter Maydell
16787c0868fSPeter Maydell  Enable mandatory TLS encryption for the server by setting the ID
16887c0868fSPeter Maydell  of the TLS credentials object previously created with the --object
16987c0868fSPeter Maydell  option; or provide the credentials needed for connecting as a client
17087c0868fSPeter Maydell  in list mode.
17187c0868fSPeter Maydell
17287c0868fSPeter Maydell.. option:: --fork
17387c0868fSPeter Maydell
17487c0868fSPeter Maydell  Fork off the server process and exit the parent once the server is running.
17587c0868fSPeter Maydell
17687c0868fSPeter Maydell.. option:: --pid-file=PATH
17787c0868fSPeter Maydell
17887c0868fSPeter Maydell  Store the server's process ID in the given file.
17987c0868fSPeter Maydell
18087c0868fSPeter Maydell.. option:: --tls-authz=ID
18187c0868fSPeter Maydell
18287c0868fSPeter Maydell  Specify the ID of a qauthz object previously created with the
18387c0868fSPeter Maydell  :option:`--object` option. This will be used to authorize connecting users
18487c0868fSPeter Maydell  against their x509 distinguished name.
18587c0868fSPeter Maydell
18687c0868fSPeter Maydell.. option:: -v, --verbose
18787c0868fSPeter Maydell
18887c0868fSPeter Maydell  Display extra debugging information.
18987c0868fSPeter Maydell
19087c0868fSPeter Maydell.. option:: -h, --help
19187c0868fSPeter Maydell
19287c0868fSPeter Maydell  Display this help and exit.
19387c0868fSPeter Maydell
19487c0868fSPeter Maydell.. option:: -V, --version
19587c0868fSPeter Maydell
19687c0868fSPeter Maydell  Display version information and exit.
19787c0868fSPeter Maydell
19887c0868fSPeter Maydell.. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
19987c0868fSPeter Maydell
200bb43ee6cSPeter Maydell  .. include:: ../qemu-option-trace.rst.inc
20187c0868fSPeter Maydell
20287c0868fSPeter MaydellExamples
20387c0868fSPeter Maydell--------
20487c0868fSPeter Maydell
20587c0868fSPeter MaydellStart a server listening on port 10809 that exposes only the
20687c0868fSPeter Maydellguest-visible contents of a qcow2 file, with no TLS encryption, and
20787c0868fSPeter Maydellwith the default export name (an empty string). The command is
20887c0868fSPeter Maydellone-shot, and will block until the first successful client
20987c0868fSPeter Maydelldisconnects:
21087c0868fSPeter Maydell
21187c0868fSPeter Maydell::
21287c0868fSPeter Maydell
21387c0868fSPeter Maydell  qemu-nbd -f qcow2 file.qcow2
21487c0868fSPeter Maydell
21587c0868fSPeter MaydellStart a long-running server listening with encryption on port 10810,
21687c0868fSPeter Maydelland whitelist clients with a specific X.509 certificate to connect to
21787c0868fSPeter Maydella 1 megabyte subset of a raw file, using the export name 'subset':
21887c0868fSPeter Maydell
21987c0868fSPeter Maydell::
22087c0868fSPeter Maydell
22187c0868fSPeter Maydell  qemu-nbd \
22287c0868fSPeter Maydell    --object tls-creds-x509,id=tls0,endpoint=server,dir=/path/to/qemutls \
22387c0868fSPeter Maydell    --object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,\
22487c0868fSPeter Maydell              O=Example Org,,L=London,,ST=London,,C=GB' \
22587c0868fSPeter Maydell    --tls-creds tls0 --tls-authz auth0 \
22687c0868fSPeter Maydell    -t -x subset -p 10810 \
22787c0868fSPeter Maydell    --image-opts driver=raw,offset=1M,size=1M,file.driver=file,file.filename=file.raw
22887c0868fSPeter Maydell
2290bc16997SEric BlakeServe a read-only copy of a guest image over a Unix socket with as
2300bc16997SEric Blakemany as 5 simultaneous readers, with a persistent process forked as a
2310bc16997SEric Blakedaemon:
23287c0868fSPeter Maydell
23387c0868fSPeter Maydell::
23487c0868fSPeter Maydell
23587c0868fSPeter Maydell  qemu-nbd --fork --persistent --shared=5 --socket=/path/to/sock \
2360bc16997SEric Blake    --read-only --format=qcow2 file.qcow2
23787c0868fSPeter Maydell
23887c0868fSPeter MaydellExpose the guest-visible contents of a qcow2 file via a block device
23987c0868fSPeter Maydell/dev/nbd0 (and possibly creating /dev/nbd0p1 and friends for
24087c0868fSPeter Maydellpartitions found within), then disconnect the device when done.
24187c0868fSPeter MaydellAccess to bind qemu-nbd to an /dev/nbd device generally requires root
24287c0868fSPeter Maydellprivileges, and may also require the execution of ``modprobe nbd``
24387c0868fSPeter Maydellto enable the kernel NBD client module.  *CAUTION*: Do not use
24487c0868fSPeter Maydellthis method to mount filesystems from an untrusted guest image - a
24587c0868fSPeter Maydellmalicious guest may have prepared the image to attempt to trigger
24687c0868fSPeter Maydellkernel bugs in partition probing or file system mounting.
24787c0868fSPeter Maydell
24887c0868fSPeter Maydell::
24987c0868fSPeter Maydell
25087c0868fSPeter Maydell  qemu-nbd -c /dev/nbd0 -f qcow2 file.qcow2
25187c0868fSPeter Maydell  qemu-nbd -d /dev/nbd0
25287c0868fSPeter Maydell
25387c0868fSPeter MaydellQuery a remote server to see details about what export(s) it is
25487c0868fSPeter Maydellserving on port 10809, and authenticating via PSK:
25587c0868fSPeter Maydell
25687c0868fSPeter Maydell::
25787c0868fSPeter Maydell
25887c0868fSPeter Maydell  qemu-nbd \
25987c0868fSPeter Maydell    --object tls-creds-psk,id=tls0,dir=/tmp/keys,username=eblake,endpoint=client \
26087c0868fSPeter Maydell    --tls-creds tls0 -L -b remote.example.com
26187c0868fSPeter Maydell
26287c0868fSPeter MaydellSee also
26387c0868fSPeter Maydell--------
26487c0868fSPeter Maydell
26587c0868fSPeter Maydell:manpage:`qemu(1)`, :manpage:`qemu-img(1)`
266