blob: 31b3417d6547c45074b3531e588b30e64d3219f8 [file] [log] [blame]
Markus Armbruster3c0bd372017-08-24 21:13:59 +02001# -*- Mode: Python -*-
Andrea Bolognanif7160f32020-07-29 20:50:24 +02002# vim: filetype=python
Markus Armbruster3c0bd372017-08-24 21:13:59 +02003#
4
5##
6# = Net devices
7##
8
Laurent Vivier5166fe02022-10-21 11:09:11 +02009{ 'include': 'sockets.json' }
Markus Armbruster3c0bd372017-08-24 21:13:59 +020010
11##
12# @set_link:
13#
14# Sets the link status of a virtual network adapter.
15#
16# @name: the device name of the virtual network adapter
17#
18# @up: true to set the link status to be up
19#
Markus Armbruster2746f062024-02-27 12:39:12 +010020# Errors:
Markus Armbrusterae7ccd52024-01-20 10:53:25 +010021# - If @name is not a valid network device, DeviceNotFound
Markus Armbruster3c0bd372017-08-24 21:13:59 +020022#
Markus Armbruster9bc6e892020-11-18 07:41:58 +010023# Since: 0.14
Markus Armbruster3c0bd372017-08-24 21:13:59 +020024#
John Snowd461c272024-06-26 18:21:16 -040025# .. note:: Not all network adapters support setting link status. This
26# command will succeed even if the network adapter does not support
27# link status notification.
Markus Armbruster3c0bd372017-08-24 21:13:59 +020028#
John Snow14b48aa2024-07-16 22:13:08 -040029# .. qmp-example::
Markus Armbruster3c0bd372017-08-24 21:13:59 +020030#
Markus Armbrusterd23055b2024-02-16 15:58:34 +010031# -> { "execute": "set_link",
32# "arguments": { "name": "e1000.0", "up": false } }
33# <- { "return": {} }
Markus Armbruster3c0bd372017-08-24 21:13:59 +020034##
35{ 'command': 'set_link', 'data': {'name': 'str', 'up': 'bool'} }
36
37##
38# @netdev_add:
39#
40# Add a network backend.
41#
Markus Armbruster3c0bd372017-08-24 21:13:59 +020042# Additional arguments depend on the type.
43#
Markus Armbruster9bc6e892020-11-18 07:41:58 +010044# Since: 0.14
Markus Armbruster3c0bd372017-08-24 21:13:59 +020045#
Markus Armbruster2746f062024-02-27 12:39:12 +010046# Errors:
Markus Armbrusterae7ccd52024-01-20 10:53:25 +010047# - If @type is not a valid network backend, DeviceNotFound
Markus Armbruster3c0bd372017-08-24 21:13:59 +020048#
John Snow14b48aa2024-07-16 22:13:08 -040049# .. qmp-example::
Markus Armbruster3c0bd372017-08-24 21:13:59 +020050#
Markus Armbrusterd23055b2024-02-16 15:58:34 +010051# -> { "execute": "netdev_add",
52# "arguments": { "type": "user", "id": "netdev1",
53# "dnssearch": [ { "str": "example.org" } ] } }
54# <- { "return": {} }
Markus Armbruster3c0bd372017-08-24 21:13:59 +020055##
Paolo Bonzini48f596c2021-05-11 11:39:55 -040056{ 'command': 'netdev_add', 'data': 'Netdev', 'boxed': true,
57 'allow-preconfig': true }
Markus Armbruster3c0bd372017-08-24 21:13:59 +020058
59##
60# @netdev_del:
61#
62# Remove a network backend.
63#
64# @id: the name of the network backend to remove
65#
Markus Armbruster2746f062024-02-27 12:39:12 +010066# Errors:
Markus Armbrusterae7ccd52024-01-20 10:53:25 +010067# - If @id is not a valid network backend, DeviceNotFound
Markus Armbruster3c0bd372017-08-24 21:13:59 +020068#
Markus Armbruster9bc6e892020-11-18 07:41:58 +010069# Since: 0.14
Markus Armbruster3c0bd372017-08-24 21:13:59 +020070#
John Snow14b48aa2024-07-16 22:13:08 -040071# .. qmp-example::
Markus Armbruster3c0bd372017-08-24 21:13:59 +020072#
Markus Armbrusterd23055b2024-02-16 15:58:34 +010073# -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
74# <- { "return": {} }
Markus Armbruster3c0bd372017-08-24 21:13:59 +020075##
Paolo Bonzini48f596c2021-05-11 11:39:55 -040076{ 'command': 'netdev_del', 'data': {'id': 'str'},
77 'allow-preconfig': true }
Markus Armbruster3c0bd372017-08-24 21:13:59 +020078
79##
Markus Armbruster3c0bd372017-08-24 21:13:59 +020080# @NetLegacyNicOptions:
81#
82# Create a new Network Interface Card.
83#
84# @netdev: id of -netdev to connect to
85#
86# @macaddr: MAC address
87#
88# @model: device model (e1000, rtl8139, virtio etc.)
89#
90# @addr: PCI device address
91#
92# @vectors: number of MSI-x vectors, 0 to disable MSI-X
93#
94# Since: 1.2
95##
96{ 'struct': 'NetLegacyNicOptions',
97 'data': {
98 '*netdev': 'str',
99 '*macaddr': 'str',
100 '*model': 'str',
101 '*addr': 'str',
102 '*vectors': 'uint32' } }
103
104##
Markus Armbruster8bf69542024-02-05 08:47:08 +0100105# @String:
106#
107# A fat type wrapping 'str', to be embedded in lists.
108#
109# Since: 1.2
110##
111{ 'struct': 'String',
112 'data': {
113 'str': 'str' } }
114
115##
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200116# @NetdevUserOptions:
117#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200118# Use the user mode network stack which requires no administrator
119# privilege to run.
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200120#
121# @hostname: client hostname reported by the builtin DHCP server
122#
123# @restrict: isolate the guest from the host
124#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200125# @ipv4: whether to support IPv4, default true for enabled (since 2.6)
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200126#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200127# @ipv6: whether to support IPv6, default true for enabled (since 2.6)
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200128#
129# @ip: legacy parameter, use net= instead
130#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200131# @net: IP network address that the guest will see, in the form
132# addr[/netmask] The netmask is optional, and can be either in the
133# form a.b.c.d or as a number of valid top-most bits. Default is
134# 10.0.2.0/24.
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200135#
136# @host: guest-visible address of the host
137#
138# @tftp: root directory of the built-in TFTP server
139#
140# @bootfile: BOOTP filename, for use with tftp=
141#
142# @dhcpstart: the first of the 16 IPs the built-in DHCP server can
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200143# assign
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200144#
145# @dns: guest-visible address of the virtual nameserver
146#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200147# @dnssearch: list of DNS suffixes to search, passed as DHCP option to
148# the guest
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200149#
Benjamin Drungf18d1372018-02-27 17:06:01 +0100150# @domainname: guest-visible domain name of the virtual nameserver
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200151# (since 3.0)
Benjamin Drungf18d1372018-02-27 17:06:01 +0100152#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200153# @ipv6-prefix: IPv6 network prefix (default is fec0::) (since 2.6).
154# The network prefix is given in the usual hexadecimal IPv6
155# address notation.
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200156#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200157# @ipv6-prefixlen: IPv6 network prefix length (default is 64) (since
158# 2.6)
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200159#
160# @ipv6-host: guest-visible IPv6 address of the host (since 2.6)
161#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200162# @ipv6-dns: guest-visible IPv6 address of the virtual nameserver
163# (since 2.6)
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200164#
165# @smb: root directory of the built-in SMB server
166#
167# @smbserver: IP address of the built-in SMB server
168#
169# @hostfwd: redirect incoming TCP or UDP host connections to guest
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200170# endpoints
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200171#
172# @guestfwd: forward guest TCP connections
173#
Fam Zheng0fca92b2018-09-14 15:26:16 +0800174# @tftp-server-name: RFC2132 "TFTP server name" string (Since 3.1)
175#
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200176# Since: 1.2
177##
178{ 'struct': 'NetdevUserOptions',
179 'data': {
180 '*hostname': 'str',
181 '*restrict': 'bool',
182 '*ipv4': 'bool',
183 '*ipv6': 'bool',
184 '*ip': 'str',
185 '*net': 'str',
186 '*host': 'str',
187 '*tftp': 'str',
188 '*bootfile': 'str',
189 '*dhcpstart': 'str',
190 '*dns': 'str',
191 '*dnssearch': ['String'],
Benjamin Drungf18d1372018-02-27 17:06:01 +0100192 '*domainname': 'str',
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200193 '*ipv6-prefix': 'str',
194 '*ipv6-prefixlen': 'int',
195 '*ipv6-host': 'str',
196 '*ipv6-dns': 'str',
197 '*smb': 'str',
198 '*smbserver': 'str',
199 '*hostfwd': ['String'],
Fam Zheng0fca92b2018-09-14 15:26:16 +0800200 '*guestfwd': ['String'],
201 '*tftp-server-name': 'str' } }
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200202
203##
204# @NetdevTapOptions:
205#
Thomas Huthaf1a5c32018-04-30 20:02:23 +0200206# Used to configure a host TAP network interface backend.
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200207#
208# @ifname: interface name
209#
210# @fd: file descriptor of an already opened tap
211#
212# @fds: multiple file descriptors of already opened multiqueue capable
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200213# tap
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200214#
215# @script: script to initialize the interface
216#
217# @downscript: script to shut down the interface
218#
219# @br: bridge name (since 2.8)
220#
221# @helper: command to execute to configure bridge
222#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200223# @sndbuf: send buffer limit. Understands [TGMKkb] suffixes.
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200224#
225# @vnet_hdr: enable the IFF_VNET_HDR flag on the tap interface
226#
227# @vhost: enable vhost-net network accelerator
228#
229# @vhostfd: file descriptor of an already opened vhost net device
230#
231# @vhostfds: file descriptors of multiple already opened vhost net
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200232# devices
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200233#
234# @vhostforce: vhost on for non-MSIX virtio guests
235#
236# @queues: number of queues to be created for multiqueue capable tap
237#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200238# @poll-us: maximum number of microseconds that could be spent on busy
239# polling for tap (since 2.7)
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200240#
241# Since: 1.2
242##
243{ 'struct': 'NetdevTapOptions',
244 'data': {
245 '*ifname': 'str',
246 '*fd': 'str',
247 '*fds': 'str',
248 '*script': 'str',
249 '*downscript': 'str',
250 '*br': 'str',
251 '*helper': 'str',
252 '*sndbuf': 'size',
253 '*vnet_hdr': 'bool',
254 '*vhost': 'bool',
255 '*vhostfd': 'str',
256 '*vhostfds': 'str',
257 '*vhostforce': 'bool',
258 '*queues': 'uint32',
259 '*poll-us': 'uint32'} }
260
261##
262# @NetdevSocketOptions:
263#
Thomas Huthaf1a5c32018-04-30 20:02:23 +0200264# Socket netdevs are used to establish a network connection to another
265# QEMU virtual machine via a TCP socket.
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200266#
267# @fd: file descriptor of an already opened socket
268#
269# @listen: port number, and optional hostname, to listen on
270#
271# @connect: port number, and optional hostname, to connect to
272#
273# @mcast: UDP multicast address and port number
274#
275# @localaddr: source address and port for multicast and udp packets
276#
277# @udp: UDP unicast address and port number
278#
279# Since: 1.2
280##
281{ 'struct': 'NetdevSocketOptions',
282 'data': {
283 '*fd': 'str',
284 '*listen': 'str',
285 '*connect': 'str',
286 '*mcast': 'str',
287 '*localaddr': 'str',
288 '*udp': 'str' } }
289
290##
291# @NetdevL2TPv3Options:
292#
Thomas Huthaf1a5c32018-04-30 20:02:23 +0200293# Configure an Ethernet over L2TPv3 tunnel.
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200294#
295# @src: source address
296#
297# @dst: destination address
298#
299# @srcport: source port - mandatory for udp, optional for ip
300#
301# @dstport: destination port - mandatory for udp, optional for ip
302#
303# @ipv6: force the use of ipv6
304#
305# @udp: use the udp version of l2tpv3 encapsulation
306#
Dr. David Alan Gilbert118d4ed2022-06-14 11:40:44 +0100307# @cookie64: use 64 bit cookies
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200308#
309# @counter: have sequence counter
310#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200311# @pincounter: pin sequence counter to zero - workaround for buggy
312# implementations or networks with packet reorder
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200313#
314# @txcookie: 32 or 64 bit transmit cookie
315#
316# @rxcookie: 32 or 64 bit receive cookie
317#
318# @txsession: 32 bit transmit session
319#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200320# @rxsession: 32 bit receive session - if not specified set to the
321# same value as transmit
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200322#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200323# @offset: additional offset - allows the insertion of additional
324# application-specific data before the packet payload
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200325#
326# Since: 2.1
327##
328{ 'struct': 'NetdevL2TPv3Options',
329 'data': {
330 'src': 'str',
331 'dst': 'str',
332 '*srcport': 'str',
333 '*dstport': 'str',
334 '*ipv6': 'bool',
335 '*udp': 'bool',
336 '*cookie64': 'bool',
337 '*counter': 'bool',
338 '*pincounter': 'bool',
339 '*txcookie': 'uint64',
340 '*rxcookie': 'uint64',
341 'txsession': 'uint32',
342 '*rxsession': 'uint32',
343 '*offset': 'uint32' } }
344
345##
346# @NetdevVdeOptions:
347#
Thomas Huthaf1a5c32018-04-30 20:02:23 +0200348# Connect to a vde switch running on the host.
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200349#
350# @sock: socket path
351#
352# @port: port number
353#
354# @group: group owner of socket
355#
356# @mode: permissions for socket
357#
358# Since: 1.2
359##
360{ 'struct': 'NetdevVdeOptions',
361 'data': {
362 '*sock': 'str',
363 '*port': 'uint16',
364 '*group': 'str',
365 '*mode': 'uint16' } }
366
367##
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200368# @NetdevBridgeOptions:
369#
370# Connect a host TAP network interface to a host bridge device.
371#
372# @br: bridge name
373#
374# @helper: command to execute to configure bridge
375#
376# Since: 1.2
377##
378{ 'struct': 'NetdevBridgeOptions',
379 'data': {
380 '*br': 'str',
381 '*helper': 'str' } }
382
383##
384# @NetdevHubPortOptions:
385#
386# Connect two or more net clients through a software hub.
387#
388# @hubid: hub identifier number
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200389#
390# @netdev: used to connect hub to a netdev instead of a device (since
391# 2.12)
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200392#
393# Since: 1.2
394##
395{ 'struct': 'NetdevHubPortOptions',
396 'data': {
Thomas Huth18d65d22018-01-15 20:50:55 +0100397 'hubid': 'int32',
398 '*netdev': 'str' } }
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200399
400##
401# @NetdevNetmapOptions:
402#
403# Connect a client to a netmap-enabled NIC or to a VALE switch port
404#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200405# @ifname: Either the name of an existing network interface supported
406# by netmap, or the name of a VALE port (created on the fly). A
407# VALE port name is in the form 'valeXXX:YYY', where XXX and YYY
408# are non-negative integers. XXX identifies a switch and YYY
409# identifies a port of the switch. VALE ports having the same XXX
410# are therefore connected to the same switch.
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200411#
412# @devname: path of the netmap device (default: '/dev/netmap').
413#
414# Since: 2.0
415##
416{ 'struct': 'NetdevNetmapOptions',
417 'data': {
418 'ifname': 'str',
419 '*devname': 'str' } }
420
421##
Ilya Maximetscb039ef2023-09-13 20:34:37 +0200422# @AFXDPMode:
423#
424# Attach mode for a default XDP program
425#
426# @skb: generic mode, no driver support necessary
427#
Markus Armbruster209e64d2024-03-22 15:09:08 +0100428# @native: DRV mode, program is attached to a driver, packets are
429# passed to the socket without allocation of skb.
Ilya Maximetscb039ef2023-09-13 20:34:37 +0200430#
431# Since: 8.2
432##
433{ 'enum': 'AFXDPMode',
434 'data': [ 'native', 'skb' ],
435 'if': 'CONFIG_AF_XDP' }
436
437##
438# @NetdevAFXDPOptions:
439#
440# AF_XDP network backend
441#
442# @ifname: The name of an existing network interface.
443#
Markus Armbruster209e64d2024-03-22 15:09:08 +0100444# @mode: Attach mode for a default XDP program. If not specified,
445# then 'native' will be tried first, then 'skb'.
Ilya Maximetscb039ef2023-09-13 20:34:37 +0200446#
447# @force-copy: Force XDP copy mode even if device supports zero-copy.
448# (default: false)
449#
Markus Armbruster209e64d2024-03-22 15:09:08 +0100450# @queues: number of queues to be used for multiqueue interfaces
451# (default: 1).
Ilya Maximetscb039ef2023-09-13 20:34:37 +0200452#
Markus Armbruster209e64d2024-03-22 15:09:08 +0100453# @start-queue: Use @queues starting from this queue number
454# (default: 0).
Ilya Maximetscb039ef2023-09-13 20:34:37 +0200455#
Markus Armbruster209e64d2024-03-22 15:09:08 +0100456# @inhibit: Don't load a default XDP program, use one already loaded
457# to the interface (default: false). Requires @sock-fds.
Ilya Maximetscb039ef2023-09-13 20:34:37 +0200458#
Markus Armbruster209e64d2024-03-22 15:09:08 +0100459# @sock-fds: A colon (:) separated list of file descriptors for
460# already open but not bound AF_XDP sockets in the queue order.
461# One fd per queue. These descriptors should already be added
462# into XDP socket map for corresponding queues. Requires
463# @inhibit.
Ilya Maximetscb039ef2023-09-13 20:34:37 +0200464#
465# Since: 8.2
466##
467{ 'struct': 'NetdevAFXDPOptions',
468 'data': {
469 'ifname': 'str',
470 '*mode': 'AFXDPMode',
471 '*force-copy': 'bool',
472 '*queues': 'int',
473 '*start-queue': 'int',
474 '*inhibit': 'bool',
475 '*sock-fds': 'str' },
476 'if': 'CONFIG_AF_XDP' }
477
478##
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200479# @NetdevVhostUserOptions:
480#
481# Vhost-user network backend
482#
483# @chardev: name of a unix socket chardev
484#
485# @vhostforce: vhost on for non-MSIX virtio guests (default: false).
486#
487# @queues: number of queues to be created for multiqueue vhost-user
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200488# (default: 1) (Since 2.5)
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200489#
490# Since: 2.1
491##
492{ 'struct': 'NetdevVhostUserOptions',
493 'data': {
494 'chardev': 'str',
495 '*vhostforce': 'bool',
496 '*queues': 'int' } }
497
498##
Cindy Lu1e0a84e2020-07-01 22:55:38 +0800499# @NetdevVhostVDPAOptions:
500#
501# Vhost-vdpa network backend
502#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200503# vDPA device is a device that uses a datapath which complies with the
504# virtio specifications with a vendor specific control path.
Cindy Lu1e0a84e2020-07-01 22:55:38 +0800505#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200506# @vhostdev: path of vhost-vdpa device (default:'/dev/vhost-vdpa-0')
Cindy Lu1e0a84e2020-07-01 22:55:38 +0800507#
Si-Wei Liu8801ccd2022-10-08 00:58:58 -0700508# @vhostfd: file descriptor of an already opened vhost vdpa device
509#
Cindy Lu1e0a84e2020-07-01 22:55:38 +0800510# @queues: number of queues to be created for multiqueue vhost-vdpa
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200511# (default: 1)
Cindy Lu1e0a84e2020-07-01 22:55:38 +0800512#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200513# @x-svq: Start device with (experimental) shadow virtqueue. (Since
514# 7.1) (default: false)
Eugenio Pérez1576dbb2022-07-20 08:59:46 +0200515#
516# Features:
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200517#
Eugenio Pérez1576dbb2022-07-20 08:59:46 +0200518# @unstable: Member @x-svq is experimental.
519#
Cindy Lu1e0a84e2020-07-01 22:55:38 +0800520# Since: 5.1
521##
522{ 'struct': 'NetdevVhostVDPAOptions',
523 'data': {
524 '*vhostdev': 'str',
Si-Wei Liu8801ccd2022-10-08 00:58:58 -0700525 '*vhostfd': 'str',
Eugenio Pérez1576dbb2022-07-20 08:59:46 +0200526 '*queues': 'int',
527 '*x-svq': {'type': 'bool', 'features' : [ 'unstable'] } } }
Cindy Lu1e0a84e2020-07-01 22:55:38 +0800528
529##
Vladislav Yaroshchuk81ad2962022-03-17 20:28:34 +0300530# @NetdevVmnetHostOptions:
531#
532# vmnet (host mode) network backend.
533#
534# Allows the vmnet interface to communicate with other vmnet
535# interfaces that are in host mode and also with the host.
536#
537# @start-address: The starting IPv4 address to use for the interface.
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200538# Must be in the private IP range (RFC 1918). Must be specified
539# along with @end-address and @subnet-mask. This address is used
540# as the gateway address. The subsequent address up to and
541# including end-address are placed in the DHCP pool.
Vladislav Yaroshchuk81ad2962022-03-17 20:28:34 +0300542#
543# @end-address: The DHCP IPv4 range end address to use for the
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200544# interface. Must be in the private IP range (RFC 1918). Must be
545# specified along with @start-address and @subnet-mask.
Vladislav Yaroshchuk81ad2962022-03-17 20:28:34 +0300546#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200547# @subnet-mask: The IPv4 subnet mask to use on the interface. Must be
548# specified along with @start-address and @subnet-mask.
Vladislav Yaroshchuk81ad2962022-03-17 20:28:34 +0300549#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200550# @isolated: Enable isolation for this interface. Interface isolation
551# ensures that vmnet interface is not able to communicate with any
552# other vmnet interfaces. Only communication with host is
553# allowed. Requires at least macOS Big Sur 11.0.
Vladislav Yaroshchuk81ad2962022-03-17 20:28:34 +0300554#
555# @net-uuid: The identifier (UUID) to uniquely identify the isolated
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200556# network vmnet interface should be added to. If set, no DHCP
557# service is provided for this interface and network communication
558# is allowed only with other interfaces added to this network
559# identified by the UUID. Requires at least macOS Big Sur 11.0.
Vladislav Yaroshchuk81ad2962022-03-17 20:28:34 +0300560#
561# Since: 7.1
562##
563{ 'struct': 'NetdevVmnetHostOptions',
564 'data': {
565 '*start-address': 'str',
566 '*end-address': 'str',
567 '*subnet-mask': 'str',
568 '*isolated': 'bool',
569 '*net-uuid': 'str' },
570 'if': 'CONFIG_VMNET' }
571
572##
573# @NetdevVmnetSharedOptions:
574#
575# vmnet (shared mode) network backend.
576#
577# Allows traffic originating from the vmnet interface to reach the
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200578# Internet through a network address translator (NAT). The vmnet
579# interface can communicate with the host and with other shared mode
580# interfaces on the same subnet. If no DHCP settings, subnet mask and
581# IPv6 prefix specified, the interface can communicate with any of
582# other interfaces in shared mode.
Vladislav Yaroshchuk81ad2962022-03-17 20:28:34 +0300583#
584# @start-address: The starting IPv4 address to use for the interface.
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200585# Must be in the private IP range (RFC 1918). Must be specified
586# along with @end-address and @subnet-mask. This address is used
587# as the gateway address. The subsequent address up to and
588# including end-address are placed in the DHCP pool.
Vladislav Yaroshchuk81ad2962022-03-17 20:28:34 +0300589#
590# @end-address: The DHCP IPv4 range end address to use for the
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200591# interface. Must be in the private IP range (RFC 1918). Must be
592# specified along with @start-address and @subnet-mask.
Vladislav Yaroshchuk81ad2962022-03-17 20:28:34 +0300593#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200594# @subnet-mask: The IPv4 subnet mask to use on the interface. Must be
595# specified along with @start-address and @subnet-mask.
Vladislav Yaroshchuk81ad2962022-03-17 20:28:34 +0300596#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200597# @isolated: Enable isolation for this interface. Interface isolation
598# ensures that vmnet interface is not able to communicate with any
599# other vmnet interfaces. Only communication with host is
600# allowed. Requires at least macOS Big Sur 11.0.
Vladislav Yaroshchuk81ad2962022-03-17 20:28:34 +0300601#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200602# @nat66-prefix: The IPv6 prefix to use into guest network. Must be a
603# unique local address i.e. start with fd00::/8 and have length of
604# 64.
Vladislav Yaroshchuk81ad2962022-03-17 20:28:34 +0300605#
606# Since: 7.1
607##
608{ 'struct': 'NetdevVmnetSharedOptions',
609 'data': {
610 '*start-address': 'str',
611 '*end-address': 'str',
612 '*subnet-mask': 'str',
613 '*isolated': 'bool',
614 '*nat66-prefix': 'str' },
615 'if': 'CONFIG_VMNET' }
616
617##
618# @NetdevVmnetBridgedOptions:
619#
620# vmnet (bridged mode) network backend.
621#
622# Bridges the vmnet interface with a physical network interface.
623#
624# @ifname: The name of the physical interface to be bridged.
625#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200626# @isolated: Enable isolation for this interface. Interface isolation
627# ensures that vmnet interface is not able to communicate with any
628# other vmnet interfaces. Only communication with host is
629# allowed. Requires at least macOS Big Sur 11.0.
Vladislav Yaroshchuk81ad2962022-03-17 20:28:34 +0300630#
631# Since: 7.1
632##
633{ 'struct': 'NetdevVmnetBridgedOptions',
634 'data': {
635 'ifname': 'str',
636 '*isolated': 'bool' },
637 'if': 'CONFIG_VMNET' }
638
639##
Laurent Vivier5166fe02022-10-21 11:09:11 +0200640# @NetdevStreamOptions:
641#
642# Configuration info for stream socket netdev
643#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200644# @addr: socket address to listen on (server=true) or connect to
645# (server=false)
646#
Laurent Vivier5166fe02022-10-21 11:09:11 +0200647# @server: create server socket (default: false)
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200648#
649# @reconnect: For a client socket, if a socket is disconnected, then
650# attempt a reconnect after the given number of seconds. Setting
651# this to zero disables this function. (default: 0) (since 8.0)
Laurent Vivier5166fe02022-10-21 11:09:11 +0200652#
Laurent Vivier13c6be92022-10-21 11:09:14 +0200653# Only SocketAddress types 'unix', 'inet' and 'fd' are supported.
Laurent Vivier5166fe02022-10-21 11:09:11 +0200654#
655# Since: 7.2
656##
657{ 'struct': 'NetdevStreamOptions',
658 'data': {
659 'addr': 'SocketAddress',
Laurent Vivier148fbf02023-01-19 11:16:45 +0100660 '*server': 'bool',
661 '*reconnect': 'uint32' } }
Laurent Vivier5166fe02022-10-21 11:09:11 +0200662
663##
664# @NetdevDgramOptions:
665#
666# Configuration info for datagram socket netdev.
667#
668# @remote: remote address
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200669#
Laurent Vivier5166fe02022-10-21 11:09:11 +0200670# @local: local address
671#
Laurent Vivier784e7a22022-10-21 11:09:17 +0200672# Only SocketAddress types 'unix', 'inet' and 'fd' are supported.
Laurent Vivier5166fe02022-10-21 11:09:11 +0200673#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200674# If remote address is present and it's a multicast address, local
675# address is optional. Otherwise local address is required and remote
676# address is optional.
Laurent Vivier5166fe02022-10-21 11:09:11 +0200677#
678# .. table:: Valid parameters combination table
679# :widths: auto
680#
681# ============= ======== =====
682# remote local okay?
683# ============= ======== =====
684# absent absent no
685# absent not fd no
686# absent fd yes
687# multicast absent yes
688# multicast present yes
689# not multicast absent no
690# not multicast present yes
691# ============= ======== =====
692#
693# Since: 7.2
694##
695{ 'struct': 'NetdevDgramOptions',
696 'data': {
697 '*local': 'SocketAddress',
698 '*remote': 'SocketAddress' } }
699
700##
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200701# @NetClientDriver:
702#
703# Available netdev drivers.
704#
Markus Armbruster86bf13a2023-04-25 08:42:20 +0200705# @l2tpv3: since 2.1
706# @vhost-vdpa: since 5.1
707# @vmnet-host: since 7.1
708# @vmnet-shared: since 7.1
709# @vmnet-bridged: since 7.1
710# @stream: since 7.2
711# @dgram: since 7.2
Ilya Maximetscb039ef2023-09-13 20:34:37 +0200712# @af-xdp: since 8.2
Cindy Lu1e0a84e2020-07-01 22:55:38 +0800713#
Markus Armbruster86bf13a2023-04-25 08:42:20 +0200714# Since: 2.7
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200715##
716{ 'enum': 'NetClientDriver',
Laurent Vivier5166fe02022-10-21 11:09:11 +0200717 'data': [ 'none', 'nic', 'user', 'tap', 'l2tpv3', 'socket', 'stream',
718 'dgram', 'vde', 'bridge', 'hubport', 'netmap', 'vhost-user',
719 'vhost-vdpa',
Ilya Maximetscb039ef2023-09-13 20:34:37 +0200720 { 'name': 'af-xdp', 'if': 'CONFIG_AF_XDP' },
Vladislav Yaroshchuk81ad2962022-03-17 20:28:34 +0300721 { 'name': 'vmnet-host', 'if': 'CONFIG_VMNET' },
722 { 'name': 'vmnet-shared', 'if': 'CONFIG_VMNET' },
723 { 'name': 'vmnet-bridged', 'if': 'CONFIG_VMNET' }] }
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200724
725##
726# @Netdev:
727#
728# Captures the configuration of a network device.
729#
730# @id: identifier for monitor commands.
731#
732# @type: Specify the driver used for interpreting remaining arguments.
733#
734# Since: 1.2
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200735##
736{ 'union': 'Netdev',
737 'base': { 'id': 'str', 'type': 'NetClientDriver' },
738 'discriminator': 'type',
739 'data': {
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200740 'nic': 'NetLegacyNicOptions',
741 'user': 'NetdevUserOptions',
742 'tap': 'NetdevTapOptions',
743 'l2tpv3': 'NetdevL2TPv3Options',
744 'socket': 'NetdevSocketOptions',
Laurent Vivier5166fe02022-10-21 11:09:11 +0200745 'stream': 'NetdevStreamOptions',
746 'dgram': 'NetdevDgramOptions',
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200747 'vde': 'NetdevVdeOptions',
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200748 'bridge': 'NetdevBridgeOptions',
749 'hubport': 'NetdevHubPortOptions',
750 'netmap': 'NetdevNetmapOptions',
Ilya Maximetscb039ef2023-09-13 20:34:37 +0200751 'af-xdp': { 'type': 'NetdevAFXDPOptions',
752 'if': 'CONFIG_AF_XDP' },
Cindy Lu1e0a84e2020-07-01 22:55:38 +0800753 'vhost-user': 'NetdevVhostUserOptions',
Vladislav Yaroshchuk81ad2962022-03-17 20:28:34 +0300754 'vhost-vdpa': 'NetdevVhostVDPAOptions',
755 'vmnet-host': { 'type': 'NetdevVmnetHostOptions',
756 'if': 'CONFIG_VMNET' },
757 'vmnet-shared': { 'type': 'NetdevVmnetSharedOptions',
758 'if': 'CONFIG_VMNET' },
759 'vmnet-bridged': { 'type': 'NetdevVmnetBridgedOptions',
760 'if': 'CONFIG_VMNET' } } }
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200761
762##
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200763# @RxState:
764#
765# Packets receiving state
766#
767# @normal: filter assigned packets according to the mac-table
768#
769# @none: don't receive any assigned packet
770#
771# @all: receive all assigned packets
772#
773# Since: 1.6
774##
775{ 'enum': 'RxState', 'data': [ 'normal', 'none', 'all' ] }
776
777##
778# @RxFilterInfo:
779#
780# Rx-filter information for a NIC.
781#
782# @name: net client name
783#
784# @promiscuous: whether promiscuous mode is enabled
785#
786# @multicast: multicast receive state
787#
788# @unicast: unicast receive state
789#
790# @vlan: vlan receive state (Since 2.0)
791#
792# @broadcast-allowed: whether to receive broadcast
793#
794# @multicast-overflow: multicast table is overflowed or not
795#
796# @unicast-overflow: unicast table is overflowed or not
797#
798# @main-mac: the main macaddr string
799#
800# @vlan-table: a list of active vlan id
801#
802# @unicast-table: a list of unicast macaddr string
803#
804# @multicast-table: a list of multicast macaddr string
805#
806# Since: 1.6
807##
808{ 'struct': 'RxFilterInfo',
809 'data': {
810 'name': 'str',
811 'promiscuous': 'bool',
812 'multicast': 'RxState',
813 'unicast': 'RxState',
814 'vlan': 'RxState',
815 'broadcast-allowed': 'bool',
816 'multicast-overflow': 'bool',
817 'unicast-overflow': 'bool',
818 'main-mac': 'str',
819 'vlan-table': ['int'],
820 'unicast-table': ['str'],
821 'multicast-table': ['str'] }}
822
823##
824# @query-rx-filter:
825#
826# Return rx-filter information for all NICs (or for the given NIC).
827#
828# @name: net client name
829#
830# Returns: list of @RxFilterInfo for all NICs (or for the given NIC).
Markus Armbruster2746f062024-02-27 12:39:12 +0100831#
832# Errors:
833# - if the given @name doesn't exist
834# - if the given NIC doesn't support rx-filter querying
835# - if the given net client isn't a NIC
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200836#
837# Since: 1.6
838#
John Snow14b48aa2024-07-16 22:13:08 -0400839# .. qmp-example::
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200840#
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100841# -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
842# <- { "return": [
843# {
844# "promiscuous": true,
845# "name": "vnet0",
846# "main-mac": "52:54:00:12:34:56",
847# "unicast": "normal",
848# "vlan": "normal",
849# "vlan-table": [
850# 4,
851# 0
852# ],
853# "unicast-table": [
854# ],
855# "multicast": "normal",
856# "multicast-overflow": false,
857# "unicast-overflow": false,
858# "multicast-table": [
859# "01:00:5e:00:00:01",
860# "33:33:00:00:00:01",
861# "33:33:ff:12:34:56"
862# ],
863# "broadcast-allowed": false
864# }
865# ]
866# }
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200867##
Marc-André Lureaub0ddeba2018-12-08 15:16:04 +0400868{ 'command': 'query-rx-filter',
869 'data': { '*name': 'str' },
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200870 'returns': ['RxFilterInfo'] }
871
872##
873# @NIC_RX_FILTER_CHANGED:
874#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200875# Emitted once until the 'query-rx-filter' command is executed, the
876# first event will always be emitted
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200877#
878# @name: net client name
879#
880# @path: device path
881#
882# Since: 1.6
883#
John Snow14b48aa2024-07-16 22:13:08 -0400884# .. qmp-example::
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200885#
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100886# <- { "event": "NIC_RX_FILTER_CHANGED",
887# "data": { "name": "vnet0",
888# "path": "/machine/peripheral/vnet0/virtio-backend" },
889# "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
Markus Armbruster3c0bd372017-08-24 21:13:59 +0200890##
891{ 'event': 'NIC_RX_FILTER_CHANGED',
892 'data': { '*name': 'str', 'path': 'str' } }
Dr. David Alan Gilbert50510ea2019-02-27 13:24:05 +0000893
894##
895# @AnnounceParameters:
896#
897# Parameters for self-announce timers
898#
899# @initial: Initial delay (in ms) before sending the first GARP/RARP
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200900# announcement
Dr. David Alan Gilbert50510ea2019-02-27 13:24:05 +0000901#
902# @max: Maximum delay (in ms) between GARP/RARP announcement packets
903#
904# @rounds: Number of self-announcement attempts
905#
906# @step: Delay increase (in ms) after each self-announcement attempt
907#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200908# @interfaces: An optional list of interface names, which restricts
909# the announcement to the listed interfaces. (Since 4.1)
Dr. David Alan Gilbertef2fdbf2019-06-20 19:47:02 +0100910#
Dr. David Alan Gilbert944458b2019-06-20 19:47:04 +0100911# @id: A name to be used to identify an instance of announce-timers
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200912# and to allow it to modified later. Not for use as part of the
913# migration parameters. (Since 4.1)
Dr. David Alan Gilbert944458b2019-06-20 19:47:04 +0100914#
Dr. David Alan Gilbert50510ea2019-02-27 13:24:05 +0000915# Since: 4.0
916##
917
918{ 'struct': 'AnnounceParameters',
919 'data': { 'initial': 'int',
920 'max': 'int',
921 'rounds': 'int',
Dr. David Alan Gilbertef2fdbf2019-06-20 19:47:02 +0100922 'step': 'int',
Dr. David Alan Gilbert944458b2019-06-20 19:47:04 +0100923 '*interfaces': ['str'],
924 '*id' : 'str' } }
Dr. David Alan Gilberta06cd482019-02-27 13:24:11 +0000925
926##
927# @announce-self:
928#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200929# Trigger generation of broadcast RARP frames to update network
930# switches. This can be useful when network bonds fail-over the
931# active slave.
Dr. David Alan Gilberta06cd482019-02-27 13:24:11 +0000932#
John Snow14b48aa2024-07-16 22:13:08 -0400933# TODO: This line is a hack to separate the example from the body
934#
935# .. qmp-example::
Dr. David Alan Gilberta06cd482019-02-27 13:24:11 +0000936#
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100937# -> { "execute": "announce-self",
938# "arguments": {
939# "initial": 50, "max": 550, "rounds": 10, "step": 50,
940# "interfaces": ["vn2", "vn3"], "id": "bob" } }
941# <- { "return": {} }
Dr. David Alan Gilberta06cd482019-02-27 13:24:11 +0000942#
943# Since: 4.0
944##
945{ 'command': 'announce-self', 'boxed': true,
946 'data' : 'AnnounceParameters'}
Jens Freimann70d04972019-10-29 12:49:00 +0100947
948##
949# @FAILOVER_NEGOTIATED:
950#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200951# Emitted when VIRTIO_NET_F_STANDBY was enabled during feature
952# negotiation. Failover primary devices which were hidden (not
953# hotplugged when requested) before will now be hotplugged by the
954# virtio-net standby device.
Jens Freimann70d04972019-10-29 12:49:00 +0100955#
Victor Toso121c25b2022-03-28 16:05:58 +0200956# @device-id: QEMU device id of the unplugged device
957#
Jens Freimann70d04972019-10-29 12:49:00 +0100958# Since: 4.2
959#
John Snow14b48aa2024-07-16 22:13:08 -0400960# .. qmp-example::
Jens Freimann70d04972019-10-29 12:49:00 +0100961#
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100962# <- { "event": "FAILOVER_NEGOTIATED",
963# "data": { "device-id": "net1" },
964# "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
Jens Freimann70d04972019-10-29 12:49:00 +0100965##
966{ 'event': 'FAILOVER_NEGOTIATED',
967 'data': {'device-id': 'str'} }
Laurent Viviere506fee2022-10-21 11:09:22 +0200968
969##
970# @NETDEV_STREAM_CONNECTED:
971#
972# Emitted when the netdev stream backend is connected
973#
974# @netdev-id: QEMU netdev id that is connected
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200975#
Laurent Viviere506fee2022-10-21 11:09:22 +0200976# @addr: The destination address
977#
978# Since: 7.2
979#
John Snow14b48aa2024-07-16 22:13:08 -0400980# .. qmp-example::
Laurent Viviere506fee2022-10-21 11:09:22 +0200981#
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100982# <- { "event": "NETDEV_STREAM_CONNECTED",
983# "data": { "netdev-id": "netdev0",
984# "addr": { "port": "47666", "ipv6": true,
985# "host": "::1", "type": "inet" } },
986# "timestamp": { "seconds": 1666269863, "microseconds": 311222 } }
Laurent Viviere506fee2022-10-21 11:09:22 +0200987#
John Snow14b48aa2024-07-16 22:13:08 -0400988# .. qmp-example::
989#
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100990# <- { "event": "NETDEV_STREAM_CONNECTED",
991# "data": { "netdev-id": "netdev0",
992# "addr": { "path": "/tmp/qemu0", "type": "unix" } },
993# "timestamp": { "seconds": 1666269706, "microseconds": 413651 } }
Laurent Viviere506fee2022-10-21 11:09:22 +0200994##
995{ 'event': 'NETDEV_STREAM_CONNECTED',
996 'data': { 'netdev-id': 'str',
997 'addr': 'SocketAddress' } }
998
999##
1000# @NETDEV_STREAM_DISCONNECTED:
1001#
1002# Emitted when the netdev stream backend is disconnected
1003#
1004# @netdev-id: QEMU netdev id that is disconnected
1005#
1006# Since: 7.2
1007#
John Snow14b48aa2024-07-16 22:13:08 -04001008# .. qmp-example::
Laurent Viviere506fee2022-10-21 11:09:22 +02001009#
John Snow9f2b8482024-06-26 18:21:14 -04001010# <- { "event": "NETDEV_STREAM_DISCONNECTED",
1011# "data": {"netdev-id": "netdev0"},
1012# "timestamp": {"seconds": 1663330937, "microseconds": 526695} }
Laurent Viviere506fee2022-10-21 11:09:22 +02001013##
1014{ 'event': 'NETDEV_STREAM_DISCONNECTED',
1015 'data': { 'netdev-id': 'str' } }