diff --git a/MAINTAINERS b/MAINTAINERS index 2c768ed3d8..d9798c20c0 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -2519,6 +2519,7 @@ F: include/block/nbd* F: qemu-nbd.* F: blockdev-nbd.c F: docs/interop/nbd.txt +F: docs/interop/qemu-nbd.rst T: git https://repo.or.cz/qemu/ericb.git nbd NFS diff --git a/Makefile b/Makefile index 6562b0dc97..b4a6c28107 100644 --- a/Makefile +++ b/Makefile @@ -339,7 +339,9 @@ MANUAL_BUILDDIR := docs endif ifdef BUILD_DOCS -DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 qemu-nbd.8 $(MANUAL_BUILDDIR)/interop/qemu-ga.8 +DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 +DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-nbd.8 +DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-ga.8 DOCS+=docs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt docs/interop/qemu-qmp-ref.7 DOCS+=docs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt docs/interop/qemu-ga-ref.7 DOCS+=docs/qemu-block-drivers.7 @@ -829,7 +831,7 @@ ifdef CONFIG_POSIX ifeq ($(CONFIG_TOOLS),y) $(INSTALL_DATA) qemu-img.1 "$(DESTDIR)$(mandir)/man1" $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man8" - $(INSTALL_DATA) qemu-nbd.8 "$(DESTDIR)$(mandir)/man8" + $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-nbd.8 "$(DESTDIR)$(mandir)/man8" endif ifdef CONFIG_TRACE_SYSTEMTAP $(INSTALL_DATA) scripts/qemu-trace-stap.1 "$(DESTDIR)$(mandir)/man1" @@ -1007,7 +1009,9 @@ sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html $(MANUAL_BUILDDIR)/interop/index # a single doctree: https://github.com/sphinx-doc/sphinx/issues/2946 build-manual = $(call quiet-command,CONFDIR="$(qemu_confdir)" sphinx-build $(if $(V),,-q) -W -b $2 -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1-$2 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1") # We assume all RST files in the manual's directory are used in it -manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py +manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) \ + $(wildcard $(SRC_PATH)/docs/$1/*.rst.inc) \ + $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py $(MANUAL_BUILDDIR)/devel/index.html: $(call manual-deps,devel) $(call build-manual,devel,html) @@ -1021,6 +1025,9 @@ $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs) $(MANUAL_BUILDDIR)/interop/qemu-ga.8: $(call manual-deps,interop) $(call build-manual,interop,man) +$(MANUAL_BUILDDIR)/interop/qemu-nbd.8: $(call manual-deps,interop) + $(call build-manual,interop,man) + $(MANUAL_BUILDDIR)/index.html: $(SRC_PATH)/docs/index.html.in qemu-version.h @mkdir -p "$(MANUAL_BUILDDIR)" $(call quiet-command, sed "s|@@VERSION@@|${VERSION}|g" $< >$@, \ @@ -1048,7 +1055,6 @@ qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi qemu-monitor-info.texi qemu.1: qemu-option-trace.texi qemu-img.1: qemu-img.texi qemu-option-trace.texi qemu-img-cmds.texi fsdev/virtfs-proxy-helper.1: fsdev/virtfs-proxy-helper.texi -qemu-nbd.8: qemu-nbd.texi qemu-option-trace.texi docs/qemu-block-drivers.7: docs/qemu-block-drivers.texi docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi scripts/qemu-trace-stap.1: scripts/qemu-trace-stap.texi @@ -1059,7 +1065,7 @@ pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \ - qemu-img.texi qemu-nbd.texi qemu-options.texi \ + qemu-img.texi qemu-options.texi \ qemu-tech.texi qemu-option-trace.texi \ qemu-deprecated.texi qemu-monitor.texi qemu-img-cmds.texi \ qemu-monitor-info.texi docs/qemu-block-drivers.texi \ diff --git a/docs/interop/conf.py b/docs/interop/conf.py index e87b8c22be..40b1ad811d 100644 --- a/docs/interop/conf.py +++ b/docs/interop/conf.py @@ -18,5 +18,7 @@ # (source start file, name, description, authors, manual section). man_pages = [ ('qemu-ga', 'qemu-ga', u'QEMU Guest Agent', - ['Michael Roth '], 8) + ['Michael Roth '], 8), + ('qemu-nbd', 'qemu-nbd', u'QEMU Disk Network Block Device Server', + ['Anthony Liguori '], 8) ] diff --git a/docs/interop/index.rst b/docs/interop/index.rst index 049387ac6d..c28f7785a5 100644 --- a/docs/interop/index.rst +++ b/docs/interop/index.rst @@ -18,5 +18,6 @@ Contents: live-block-operations pr-helper qemu-ga + qemu-nbd vhost-user vhost-user-gpu diff --git a/docs/interop/qemu-nbd.rst b/docs/interop/qemu-nbd.rst new file mode 100644 index 0000000000..873bb9e17d --- /dev/null +++ b/docs/interop/qemu-nbd.rst @@ -0,0 +1,263 @@ +QEMU Disk Network Block Device Server +===================================== + +Synopsis +-------- + +**qemu-nbd** [*OPTION*]... *filename* + +**qemu-nbd** -L [*OPTION*]... + +**qemu-nbd** -d *dev* + +Description +----------- + +Export a QEMU disk image using the NBD protocol. + +Other uses: + +- Bind a /dev/nbdX block device to a QEMU server (on Linux). +- As a client to query exports of a remote NBD server. + +Options +------- + +.. program:: qemu-nbd + +*filename* is a disk image filename, or a set of block +driver options if ``--image-opts`` is specified. + +*dev* is an NBD device. + +.. option:: --object type,id=ID,...props... + + Define a new instance of the *type* object class identified by *ID*. + See the :manpage:`qemu(1)` manual page for full details of the properties + supported. The common object types that it makes sense to define are the + ``secret`` object, which is used to supply passwords and/or encryption + keys, and the ``tls-creds`` object, which is used to supply TLS + credentials for the qemu-nbd server or client. + +.. option:: -p, --port=PORT + + TCP port to listen on as a server, or connect to as a client + (default ``10809``). + +.. option:: -o, --offset=OFFSET + + The offset into the image. + +.. option:: -b, --bind=IFACE + + The interface to bind to as a server, or connect to as a client + (default ``0.0.0.0``). + +.. option:: -k, --socket=PATH + + Use a unix socket with path *PATH*. + +.. option:: --image-opts + + Treat *filename* as a set of image options, instead of a plain + filename. If this flag is specified, the ``-f`` flag should + not be used, instead the :option:`format=` option should be set. + +.. option:: -f, --format=FMT + + Force the use of the block driver for format *FMT* instead of + auto-detecting. + +.. option:: -r, --read-only + + Export the disk as read-only. + +.. option:: -P, --partition=NUM + + Deprecated: Only expose MBR partition *NUM*. Understands physical + partitions 1-4 and logical partition 5. New code should instead use + :option:`--image-opts` with the raw driver wrapping a subset of the + original image. + +.. option:: -B, --bitmap=NAME + + If *filename* has a qcow2 persistent bitmap *NAME*, expose + that bitmap via the ``qemu:dirty-bitmap:NAME`` context + accessible through NBD_OPT_SET_META_CONTEXT. + +.. option:: -s, --snapshot + + Use *filename* as an external snapshot, create a temporary + file with ``backing_file=``\ *filename*, redirect the write to + the temporary one. + +.. option:: -l, --load-snapshot=SNAPSHOT_PARAM + + Load an internal snapshot inside *filename* and export it + as an read-only device, SNAPSHOT_PARAM format is + ``snapshot.id=[ID],snapshot.name=[NAME]`` or ``[ID_OR_NAME]`` + +.. option:: --cache=CACHE + + The cache mode to be used with the file. See the documentation of + the emulator's ``-drive cache=...`` option for allowed values. + +.. option:: -n, --nocache + + Equivalent to :option:`--cache=none`. + +.. option:: --aio=AIO + + Set the asynchronous I/O mode between ``threads`` (the default) + and ``native`` (Linux only). + +.. option:: --discard=DISCARD + + Control whether ``discard`` (also known as ``trim`` or ``unmap``) + requests are ignored or passed to the filesystem. *DISCARD* is one of + ``ignore`` (or ``off``), ``unmap`` (or ``on``). The default is + ``ignore``. + +.. option:: --detect-zeroes=DETECT_ZEROES + + Control the automatic conversion of plain zero writes by the OS to + driver-specific optimized zero write commands. *DETECT_ZEROES* is one of + ``off``, ``on``, or ``unmap``. ``unmap`` + converts a zero write to an unmap operation and can only be used if + *DISCARD* is set to ``unmap``. The default is ``off``. + +.. option:: -c, --connect=DEV + + Connect *filename* to NBD device *DEV* (Linux only). + +.. option:: -d, --disconnect + + Disconnect the device *DEV* (Linux only). + +.. option:: -e, --shared=NUM + + Allow up to *NUM* clients to share the device (default + ``1``). Safe for readers, but for now, consistency is not + guaranteed between multiple writers. + +.. option:: -t, --persistent + + Don't exit on the last connection. + +.. option:: -x, --export-name=NAME + + Set the NBD volume export name (default of a zero-length string). + +.. option:: -D, --description=DESCRIPTION + + Set the NBD volume export description, as a human-readable + string. + +.. option:: -L, --list + + Connect as a client and list all details about the exports exposed by + a remote NBD server. This enables list mode, and is incompatible + with options that change behavior related to a specific export (such as + :option:`--export-name`, :option:`--offset`, ...). + +.. option:: --tls-creds=ID + + Enable mandatory TLS encryption for the server by setting the ID + of the TLS credentials object previously created with the --object + option; or provide the credentials needed for connecting as a client + in list mode. + +.. option:: --fork + + Fork off the server process and exit the parent once the server is running. + +.. option:: --pid-file=PATH + + Store the server's process ID in the given file. + +.. option:: --tls-authz=ID + + Specify the ID of a qauthz object previously created with the + :option:`--object` option. This will be used to authorize connecting users + against their x509 distinguished name. + +.. option:: -v, --verbose + + Display extra debugging information. + +.. option:: -h, --help + + Display this help and exit. + +.. option:: -V, --version + + Display version information and exit. + +.. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE] + + .. include:: qemu-option-trace.rst.inc + +Examples +-------- + +Start a server listening on port 10809 that exposes only the +guest-visible contents of a qcow2 file, with no TLS encryption, and +with the default export name (an empty string). The command is +one-shot, and will block until the first successful client +disconnects: + +:: + + qemu-nbd -f qcow2 file.qcow2 + +Start a long-running server listening with encryption on port 10810, +and whitelist clients with a specific X.509 certificate to connect to +a 1 megabyte subset of a raw file, using the export name 'subset': + +:: + + qemu-nbd \ + --object tls-creds-x509,id=tls0,endpoint=server,dir=/path/to/qemutls \ + --object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,\ + O=Example Org,,L=London,,ST=London,,C=GB' \ + --tls-creds tls0 --tls-authz auth0 \ + -t -x subset -p 10810 \ + --image-opts driver=raw,offset=1M,size=1M,file.driver=file,file.filename=file.raw + +Serve a read-only copy of just the first MBR partition of a guest +image over a Unix socket with as many as 5 simultaneous readers, with +a persistent process forked as a daemon: + +:: + + qemu-nbd --fork --persistent --shared=5 --socket=/path/to/sock \ + --partition=1 --read-only --format=qcow2 file.qcow2 + +Expose the guest-visible contents of a qcow2 file via a block device +/dev/nbd0 (and possibly creating /dev/nbd0p1 and friends for +partitions found within), then disconnect the device when done. +Access to bind qemu-nbd to an /dev/nbd device generally requires root +privileges, and may also require the execution of ``modprobe nbd`` +to enable the kernel NBD client module. *CAUTION*: Do not use +this method to mount filesystems from an untrusted guest image - a +malicious guest may have prepared the image to attempt to trigger +kernel bugs in partition probing or file system mounting. + +:: + + qemu-nbd -c /dev/nbd0 -f qcow2 file.qcow2 + qemu-nbd -d /dev/nbd0 + +Query a remote server to see details about what export(s) it is +serving on port 10809, and authenticating via PSK: + +:: + + qemu-nbd \ + --object tls-creds-psk,id=tls0,dir=/tmp/keys,username=eblake,endpoint=client \ + --tls-creds tls0 -L -b remote.example.com + +See also +-------- + +:manpage:`qemu(1)`, :manpage:`qemu-img(1)` diff --git a/docs/interop/qemu-option-trace.rst.inc b/docs/interop/qemu-option-trace.rst.inc new file mode 100644 index 0000000000..23cfcb4853 --- /dev/null +++ b/docs/interop/qemu-option-trace.rst.inc @@ -0,0 +1,30 @@ +.. + The contents of this file must be kept in sync with qemu-option-trace.texi + until all the users of the texi file have been converted to rst and + the texi file can be removed. + +Specify tracing options. + +.. option:: [enable=]PATTERN + + Immediately enable events matching *PATTERN* + (either event name or a globbing pattern). This option is only + available if QEMU has been compiled with the ``simple``, ``log`` + or ``ftrace`` tracing backend. To specify multiple events or patterns, + specify the :option:`-trace` option multiple times. + + Use :option:`-trace help` to print a list of names of trace points. + +.. option:: events=FILE + + Immediately enable events listed in *FILE*. + The file must contain one event name (as listed in the ``trace-events-all`` + file) per line; globbing patterns are accepted too. This option is only + available if QEMU has been compiled with the ``simple``, ``log`` or + ``ftrace`` tracing backend. + +.. option:: file=FILE + + Log output traces to *FILE*. + This option is only available if QEMU has been compiled with + the ``simple`` tracing backend. diff --git a/qemu-doc.texi b/qemu-doc.texi index 39f950471f..617485d146 100644 --- a/qemu-doc.texi +++ b/qemu-doc.texi @@ -633,7 +633,6 @@ encrypted disk images. * disk_images_snapshot_mode:: Snapshot mode * vm_snapshots:: VM snapshots * qemu_img_invocation:: qemu-img Invocation -* qemu_nbd_invocation:: qemu-nbd Invocation * disk_images_formats:: Disk image file formats * host_drives:: Using host drives * disk_images_fat_images:: Virtual FAT disk images @@ -724,11 +723,6 @@ state is not saved or restored properly (in particular USB). @include qemu-img.texi -@node qemu_nbd_invocation -@subsection @code{qemu-nbd} Invocation - -@include qemu-nbd.texi - @include docs/qemu-block-drivers.texi @node pcsys_network diff --git a/qemu-nbd.texi b/qemu-nbd.texi deleted file mode 100644 index 7f55657722..0000000000 --- a/qemu-nbd.texi +++ /dev/null @@ -1,214 +0,0 @@ -@example -@c man begin SYNOPSIS -@command{qemu-nbd} [OPTION]... @var{filename} - -@command{qemu-nbd} @option{-L} [OPTION]... - -@command{qemu-nbd} @option{-d} @var{dev} -@c man end -@end example - -@c man begin DESCRIPTION - -Export a QEMU disk image using the NBD protocol. - -Other uses: -@itemize -@item -Bind a /dev/nbdX block device to a QEMU server (on Linux). -@item -As a client to query exports of a remote NBD server. -@end itemize - -@c man end - -@c man begin OPTIONS -@var{filename} is a disk image filename, or a set of block -driver options if @option{--image-opts} is specified. - -@var{dev} is an NBD device. - -@table @option -@item --object type,id=@var{id},...props... -Define a new instance of the @var{type} object class identified by @var{id}. -See the @code{qemu(1)} manual page for full details of the properties -supported. The common object types that it makes sense to define are the -@code{secret} object, which is used to supply passwords and/or encryption -keys, and the @code{tls-creds} object, which is used to supply TLS -credentials for the qemu-nbd server or client. -@item -p, --port=@var{port} -The TCP port to listen on as a server, or connect to as a client -(default @samp{10809}). -@item -o, --offset=@var{offset} -The offset into the image. -@item -b, --bind=@var{iface} -The interface to bind to as a server, or connect to as a client -(default @samp{0.0.0.0}). -@item -k, --socket=@var{path} -Use a unix socket with path @var{path}. -@item --image-opts -Treat @var{filename} as a set of image options, instead of a plain -filename. If this flag is specified, the @var{-f} flag should -not be used, instead the '@code{format=}' option should be set. -@item -f, --format=@var{fmt} -Force the use of the block driver for format @var{fmt} instead of -auto-detecting. -@item -r, --read-only -Export the disk as read-only. -@item -P, --partition=@var{num} -Deprecated: Only expose MBR partition @var{num}. Understands physical -partitions 1-4 and logical partition 5. New code should instead use -@option{--image-opts} with the raw driver wrapping a subset of the -original image. -@item -B, --bitmap=@var{name} -If @var{filename} has a qcow2 persistent bitmap @var{name}, expose -that bitmap via the ``qemu:dirty-bitmap:@var{name}'' context -accessible through NBD_OPT_SET_META_CONTEXT. -@item -s, --snapshot -Use @var{filename} as an external snapshot, create a temporary -file with backing_file=@var{filename}, redirect the write to -the temporary one. -@item -l, --load-snapshot=@var{snapshot_param} -Load an internal snapshot inside @var{filename} and export it -as an read-only device, @var{snapshot_param} format is -'snapshot.id=[ID],snapshot.name=[NAME]' or '[ID_OR_NAME]' -@item -n, --nocache -@itemx --cache=@var{cache} -The cache mode to be used with the file. See the documentation of -the emulator's @code{-drive cache=...} option for allowed values. -@item --aio=@var{aio} -Set the asynchronous I/O mode between @samp{threads} (the default) -and @samp{native} (Linux only). -@item --discard=@var{discard} -Control whether @dfn{discard} (also known as @dfn{trim} or @dfn{unmap}) -requests are ignored or passed to the filesystem. @var{discard} is one of -@samp{ignore} (or @samp{off}), @samp{unmap} (or @samp{on}). The default is -@samp{ignore}. -@item --detect-zeroes=@var{detect-zeroes} -Control the automatic conversion of plain zero writes by the OS to -driver-specific optimized zero write commands. @var{detect-zeroes} is one of -@samp{off}, @samp{on} or @samp{unmap}. @samp{unmap} -converts a zero write to an unmap operation and can only be used if -@var{discard} is set to @samp{unmap}. The default is @samp{off}. -@item -c, --connect=@var{dev} -Connect @var{filename} to NBD device @var{dev} (Linux only). -@item -d, --disconnect -Disconnect the device @var{dev} (Linux only). -@item -e, --shared=@var{num} -Allow up to @var{num} clients to share the device (default -@samp{1}). Safe for readers, but for now, consistency is not -guaranteed between multiple writers. -@item -t, --persistent -Don't exit on the last connection. -@item -x, --export-name=@var{name} -Set the NBD volume export name (default of a zero-length string). -@item -D, --description=@var{description} -Set the NBD volume export description, as a human-readable -string. -@item -L, --list -Connect as a client and list all details about the exports exposed by -a remote NBD server. This enables list mode, and is incompatible -with options that change behavior related to a specific export (such as -@option{--export-name}, @option{--offset}, ...). -@item --tls-creds=ID -Enable mandatory TLS encryption for the server by setting the ID -of the TLS credentials object previously created with the --object -option; or provide the credentials needed for connecting as a client -in list mode. -@item --fork -Fork off the server process and exit the parent once the server is running. -@item --pid-file=PATH -Store the server's process ID in the given file. -@item --tls-authz=ID -Specify the ID of a qauthz object previously created with the ---object option. This will be used to authorize connecting users -against their x509 distinguished name. -@item -v, --verbose -Display extra debugging information. -@item -h, --help -Display this help and exit. -@item -V, --version -Display version information and exit. -@item -T, --trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}] -@findex --trace -@include qemu-option-trace.texi -@end table - -@c man end - -@c man begin EXAMPLES -Start a server listening on port 10809 that exposes only the -guest-visible contents of a qcow2 file, with no TLS encryption, and -with the default export name (an empty string). The command is -one-shot, and will block until the first successful client -disconnects: - -@example -qemu-nbd -f qcow2 file.qcow2 -@end example - -Start a long-running server listening with encryption on port 10810, -and whitelist clients with a specific X.509 certificate to connect to -a 1 megabyte subset of a raw file, using the export name 'subset': - -@example -qemu-nbd \ - --object tls-creds-x509,id=tls0,endpoint=server,dir=/path/to/qemutls \ - --object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,\ - O=Example Org,,L=London,,ST=London,,C=GB' \ - --tls-creds tls0 --tls-authz auth0 \ - -t -x subset -p 10810 \ - --image-opts driver=raw,offset=1M,size=1M,file.driver=file,file.filename=file.raw -@end example - -Serve a read-only copy of just the first MBR partition of a guest -image over a Unix socket with as many as 5 simultaneous readers, with -a persistent process forked as a daemon: - -@example -qemu-nbd --fork --persistent --shared=5 --socket=/path/to/sock \ - --partition=1 --read-only --format=qcow2 file.qcow2 -@end example - -Expose the guest-visible contents of a qcow2 file via a block device -/dev/nbd0 (and possibly creating /dev/nbd0p1 and friends for -partitions found within), then disconnect the device when done. -Access to bind qemu-nbd to an /dev/nbd device generally requires root -privileges, and may also require the execution of @code{modprobe nbd} -to enable the kernel NBD client module. @emph{CAUTION}: Do not use -this method to mount filesystems from an untrusted guest image - a -malicious guest may have prepared the image to attempt to trigger -kernel bugs in partition probing or file system mounting. - -@example -qemu-nbd -c /dev/nbd0 -f qcow2 file.qcow2 -qemu-nbd -d /dev/nbd0 -@end example - -Query a remote server to see details about what export(s) it is -serving on port 10809, and authenticating via PSK: - -@example -qemu-nbd \ - --object tls-creds-psk,id=tls0,dir=/tmp/keys,username=eblake,endpoint=client \ - --tls-creds tls0 -L -b remote.example.com -@end example - -@c man end - -@ignore - -@setfilename qemu-nbd -@settitle QEMU Disk Network Block Device Server - -@c man begin AUTHOR -Copyright (C) 2006 Anthony Liguori . -This is free software; see the source for copying conditions. There is NO -warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. -@c man end - -@c man begin SEEALSO -qemu(1), qemu-img(1) -@c man end - -@end ignore diff --git a/qemu-option-trace.texi b/qemu-option-trace.texi index 7d1b7f05c5..162f1528d2 100644 --- a/qemu-option-trace.texi +++ b/qemu-option-trace.texi @@ -1,3 +1,7 @@ +@c The contents of this file must be kept in sync with qemu-option-trace.rst.inc +@c until all the users of the texi file have been converted to rst and +@c the texi file can be removed. + Specify tracing options. @table @option