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