Merge remote-tracking branch 'remotes/cschoenebeck/tags/pull-9p-20211027' into staging
[qemu.git] / qapi / net.json
1 # -*- Mode: Python -*-
2 # vim: filetype=python
3 #
4
5 ##
6 # = Net devices
7 ##
8
9 { 'include': 'common.json' }
10
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 #
20 # Returns: Nothing on success
21 #          If @name is not a valid network device, DeviceNotFound
22 #
23 # Since: 0.14
24 #
25 # Notes: Not all network adapters support setting link status.  This command
26 #        will succeed even if the network adapter does not support link status
27 #        notification.
28 #
29 # Example:
30 #
31 # -> { "execute": "set_link",
32 #      "arguments": { "name": "e1000.0", "up": false } }
33 # <- { "return": {} }
34 #
35 ##
36 { 'command': 'set_link', 'data': {'name': 'str', 'up': 'bool'} }
37
38 ##
39 # @netdev_add:
40 #
41 # Add a network backend.
42 #
43 # Additional arguments depend on the type.
44 #
45 # Since: 0.14
46 #
47 # Returns: Nothing on success
48 #          If @type is not a valid network backend, DeviceNotFound
49 #
50 # Example:
51 #
52 # -> { "execute": "netdev_add",
53 #      "arguments": { "type": "user", "id": "netdev1",
54 #                     "dnssearch": "example.org" } }
55 # <- { "return": {} }
56 #
57 ##
58 { 'command': 'netdev_add', 'data': 'Netdev', 'boxed': true,
59   'allow-preconfig': true }
60
61 ##
62 # @netdev_del:
63 #
64 # Remove a network backend.
65 #
66 # @id: the name of the network backend to remove
67 #
68 # Returns: Nothing on success
69 #          If @id is not a valid network backend, DeviceNotFound
70 #
71 # Since: 0.14
72 #
73 # Example:
74 #
75 # -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
76 # <- { "return": {} }
77 #
78 ##
79 { 'command': 'netdev_del', 'data': {'id': 'str'},
80   'allow-preconfig': true }
81
82 ##
83 # @NetLegacyNicOptions:
84 #
85 # Create a new Network Interface Card.
86 #
87 # @netdev: id of -netdev to connect to
88 #
89 # @macaddr: MAC address
90 #
91 # @model: device model (e1000, rtl8139, virtio etc.)
92 #
93 # @addr: PCI device address
94 #
95 # @vectors: number of MSI-x vectors, 0 to disable MSI-X
96 #
97 # Since: 1.2
98 ##
99 { 'struct': 'NetLegacyNicOptions',
100   'data': {
101     '*netdev':  'str',
102     '*macaddr': 'str',
103     '*model':   'str',
104     '*addr':    'str',
105     '*vectors': 'uint32' } }
106
107 ##
108 # @NetdevUserOptions:
109 #
110 # Use the user mode network stack which requires no administrator privilege to
111 # run.
112 #
113 # @hostname: client hostname reported by the builtin DHCP server
114 #
115 # @restrict: isolate the guest from the host
116 #
117 # @ipv4: whether to support IPv4, default true for enabled
118 #        (since 2.6)
119 #
120 # @ipv6: whether to support IPv6, default true for enabled
121 #        (since 2.6)
122 #
123 # @ip: legacy parameter, use net= instead
124 #
125 # @net: IP network address that the guest will see, in the
126 #       form addr[/netmask] The netmask is optional, and can be
127 #       either in the form a.b.c.d or as a number of valid top-most
128 #       bits. Default is 10.0.2.0/24.
129 #
130 # @host: guest-visible address of the host
131 #
132 # @tftp: root directory of the built-in TFTP server
133 #
134 # @bootfile: BOOTP filename, for use with tftp=
135 #
136 # @dhcpstart: the first of the 16 IPs the built-in DHCP server can
137 #             assign
138 #
139 # @dns: guest-visible address of the virtual nameserver
140 #
141 # @dnssearch: list of DNS suffixes to search, passed as DHCP option
142 #             to the guest
143 #
144 # @domainname: guest-visible domain name of the virtual nameserver
145 #              (since 3.0)
146 #
147 # @ipv6-prefix: IPv6 network prefix (default is fec0::) (since
148 #               2.6). The network prefix is given in the usual
149 #               hexadecimal IPv6 address notation.
150 #
151 # @ipv6-prefixlen: IPv6 network prefix length (default is 64)
152 #                  (since 2.6)
153 #
154 # @ipv6-host: guest-visible IPv6 address of the host (since 2.6)
155 #
156 # @ipv6-dns: guest-visible IPv6 address of the virtual
157 #            nameserver (since 2.6)
158 #
159 # @smb: root directory of the built-in SMB server
160 #
161 # @smbserver: IP address of the built-in SMB server
162 #
163 # @hostfwd: redirect incoming TCP or UDP host connections to guest
164 #           endpoints
165 #
166 # @guestfwd: forward guest TCP connections
167 #
168 # @tftp-server-name: RFC2132 "TFTP server name" string (Since 3.1)
169 #
170 # Since: 1.2
171 ##
172 { 'struct': 'NetdevUserOptions',
173   'data': {
174     '*hostname':  'str',
175     '*restrict':  'bool',
176     '*ipv4':      'bool',
177     '*ipv6':      'bool',
178     '*ip':        'str',
179     '*net':       'str',
180     '*host':      'str',
181     '*tftp':      'str',
182     '*bootfile':  'str',
183     '*dhcpstart': 'str',
184     '*dns':       'str',
185     '*dnssearch': ['String'],
186     '*domainname': 'str',
187     '*ipv6-prefix':      'str',
188     '*ipv6-prefixlen':   'int',
189     '*ipv6-host':        'str',
190     '*ipv6-dns':         'str',
191     '*smb':       'str',
192     '*smbserver': 'str',
193     '*hostfwd':   ['String'],
194     '*guestfwd':  ['String'],
195     '*tftp-server-name': 'str' } }
196
197 ##
198 # @NetdevTapOptions:
199 #
200 # Used to configure a host TAP network interface backend.
201 #
202 # @ifname: interface name
203 #
204 # @fd: file descriptor of an already opened tap
205 #
206 # @fds: multiple file descriptors of already opened multiqueue capable
207 #       tap
208 #
209 # @script: script to initialize the interface
210 #
211 # @downscript: script to shut down the interface
212 #
213 # @br: bridge name (since 2.8)
214 #
215 # @helper: command to execute to configure bridge
216 #
217 # @sndbuf: send buffer limit. Understands [TGMKkb] suffixes.
218 #
219 # @vnet_hdr: enable the IFF_VNET_HDR flag on the tap interface
220 #
221 # @vhost: enable vhost-net network accelerator
222 #
223 # @vhostfd: file descriptor of an already opened vhost net device
224 #
225 # @vhostfds: file descriptors of multiple already opened vhost net
226 #            devices
227 #
228 # @vhostforce: vhost on for non-MSIX virtio guests
229 #
230 # @queues: number of queues to be created for multiqueue capable tap
231 #
232 # @poll-us: maximum number of microseconds that could
233 #           be spent on busy polling for tap (since 2.7)
234 #
235 # Since: 1.2
236 ##
237 { 'struct': 'NetdevTapOptions',
238   'data': {
239     '*ifname':     'str',
240     '*fd':         'str',
241     '*fds':        'str',
242     '*script':     'str',
243     '*downscript': 'str',
244     '*br':         'str',
245     '*helper':     'str',
246     '*sndbuf':     'size',
247     '*vnet_hdr':   'bool',
248     '*vhost':      'bool',
249     '*vhostfd':    'str',
250     '*vhostfds':   'str',
251     '*vhostforce': 'bool',
252     '*queues':     'uint32',
253     '*poll-us':    'uint32'} }
254
255 ##
256 # @NetdevSocketOptions:
257 #
258 # Socket netdevs are used to establish a network connection to another
259 # QEMU virtual machine via a TCP socket.
260 #
261 # @fd: file descriptor of an already opened socket
262 #
263 # @listen: port number, and optional hostname, to listen on
264 #
265 # @connect: port number, and optional hostname, to connect to
266 #
267 # @mcast: UDP multicast address and port number
268 #
269 # @localaddr: source address and port for multicast and udp packets
270 #
271 # @udp: UDP unicast address and port number
272 #
273 # Since: 1.2
274 ##
275 { 'struct': 'NetdevSocketOptions',
276   'data': {
277     '*fd':        'str',
278     '*listen':    'str',
279     '*connect':   'str',
280     '*mcast':     'str',
281     '*localaddr': 'str',
282     '*udp':       'str' } }
283
284 ##
285 # @NetdevL2TPv3Options:
286 #
287 # Configure an Ethernet over L2TPv3 tunnel.
288 #
289 # @src: source address
290 #
291 # @dst: destination address
292 #
293 # @srcport: source port - mandatory for udp, optional for ip
294 #
295 # @dstport: destination port - mandatory for udp, optional for ip
296 #
297 # @ipv6: force the use of ipv6
298 #
299 # @udp: use the udp version of l2tpv3 encapsulation
300 #
301 # @cookie64: use 64 bit coookies
302 #
303 # @counter: have sequence counter
304 #
305 # @pincounter: pin sequence counter to zero -
306 #              workaround for buggy implementations or
307 #              networks with packet reorder
308 #
309 # @txcookie: 32 or 64 bit transmit cookie
310 #
311 # @rxcookie: 32 or 64 bit receive cookie
312 #
313 # @txsession: 32 bit transmit session
314 #
315 # @rxsession: 32 bit receive session - if not specified
316 #             set to the same value as transmit
317 #
318 # @offset: additional offset - allows the insertion of
319 #          additional application-specific data before the packet payload
320 #
321 # Since: 2.1
322 ##
323 { 'struct': 'NetdevL2TPv3Options',
324   'data': {
325     'src':          'str',
326     'dst':          'str',
327     '*srcport':     'str',
328     '*dstport':     'str',
329     '*ipv6':        'bool',
330     '*udp':         'bool',
331     '*cookie64':    'bool',
332     '*counter':     'bool',
333     '*pincounter':  'bool',
334     '*txcookie':    'uint64',
335     '*rxcookie':    'uint64',
336     'txsession':    'uint32',
337     '*rxsession':   'uint32',
338     '*offset':      'uint32' } }
339
340 ##
341 # @NetdevVdeOptions:
342 #
343 # Connect to a vde switch running on the host.
344 #
345 # @sock: socket path
346 #
347 # @port: port number
348 #
349 # @group: group owner of socket
350 #
351 # @mode: permissions for socket
352 #
353 # Since: 1.2
354 ##
355 { 'struct': 'NetdevVdeOptions',
356   'data': {
357     '*sock':  'str',
358     '*port':  'uint16',
359     '*group': 'str',
360     '*mode':  'uint16' } }
361
362 ##
363 # @NetdevBridgeOptions:
364 #
365 # Connect a host TAP network interface to a host bridge device.
366 #
367 # @br: bridge name
368 #
369 # @helper: command to execute to configure bridge
370 #
371 # Since: 1.2
372 ##
373 { 'struct': 'NetdevBridgeOptions',
374   'data': {
375     '*br':     'str',
376     '*helper': 'str' } }
377
378 ##
379 # @NetdevHubPortOptions:
380 #
381 # Connect two or more net clients through a software hub.
382 #
383 # @hubid: hub identifier number
384 # @netdev: used to connect hub to a netdev instead of a device (since 2.12)
385 #
386 # Since: 1.2
387 ##
388 { 'struct': 'NetdevHubPortOptions',
389   'data': {
390     'hubid':     'int32',
391     '*netdev':    'str' } }
392
393 ##
394 # @NetdevNetmapOptions:
395 #
396 # Connect a client to a netmap-enabled NIC or to a VALE switch port
397 #
398 # @ifname: Either the name of an existing network interface supported by
399 #          netmap, or the name of a VALE port (created on the fly).
400 #          A VALE port name is in the form 'valeXXX:YYY', where XXX and
401 #          YYY are non-negative integers. XXX identifies a switch and
402 #          YYY identifies a port of the switch. VALE ports having the
403 #          same XXX are therefore connected to the same switch.
404 #
405 # @devname: path of the netmap device (default: '/dev/netmap').
406 #
407 # Since: 2.0
408 ##
409 { 'struct': 'NetdevNetmapOptions',
410   'data': {
411     'ifname':     'str',
412     '*devname':    'str' } }
413
414 ##
415 # @NetdevVhostUserOptions:
416 #
417 # Vhost-user network backend
418 #
419 # @chardev: name of a unix socket chardev
420 #
421 # @vhostforce: vhost on for non-MSIX virtio guests (default: false).
422 #
423 # @queues: number of queues to be created for multiqueue vhost-user
424 #          (default: 1) (Since 2.5)
425 #
426 # Since: 2.1
427 ##
428 { 'struct': 'NetdevVhostUserOptions',
429   'data': {
430     'chardev':        'str',
431     '*vhostforce':    'bool',
432     '*queues':        'int' } }
433
434 ##
435 # @NetdevVhostVDPAOptions:
436 #
437 # Vhost-vdpa network backend
438 #
439 # vDPA device is a device that uses a datapath which complies with the virtio
440 # specifications with a vendor specific control path.
441 #
442 # @vhostdev: path of vhost-vdpa device
443 #            (default:'/dev/vhost-vdpa-0')
444 #
445 # @queues: number of queues to be created for multiqueue vhost-vdpa
446 #          (default: 1)
447 #
448 # Since: 5.1
449 ##
450 { 'struct': 'NetdevVhostVDPAOptions',
451   'data': {
452     '*vhostdev':     'str',
453     '*queues':       'int' } }
454
455 ##
456 # @NetClientDriver:
457 #
458 # Available netdev drivers.
459 #
460 # Since: 2.7
461 #
462 #        @vhost-vdpa since 5.1
463 ##
464 { 'enum': 'NetClientDriver',
465   'data': [ 'none', 'nic', 'user', 'tap', 'l2tpv3', 'socket', 'vde',
466             'bridge', 'hubport', 'netmap', 'vhost-user', 'vhost-vdpa' ] }
467
468 ##
469 # @Netdev:
470 #
471 # Captures the configuration of a network device.
472 #
473 # @id: identifier for monitor commands.
474 #
475 # @type: Specify the driver used for interpreting remaining arguments.
476 #
477 # Since: 1.2
478 #
479 #        'l2tpv3' - since 2.1
480 ##
481 { 'union': 'Netdev',
482   'base': { 'id': 'str', 'type': 'NetClientDriver' },
483   'discriminator': 'type',
484   'data': {
485     'nic':      'NetLegacyNicOptions',
486     'user':     'NetdevUserOptions',
487     'tap':      'NetdevTapOptions',
488     'l2tpv3':   'NetdevL2TPv3Options',
489     'socket':   'NetdevSocketOptions',
490     'vde':      'NetdevVdeOptions',
491     'bridge':   'NetdevBridgeOptions',
492     'hubport':  'NetdevHubPortOptions',
493     'netmap':   'NetdevNetmapOptions',
494     'vhost-user': 'NetdevVhostUserOptions',
495     'vhost-vdpa': 'NetdevVhostVDPAOptions' } }
496
497 ##
498 # @RxState:
499 #
500 # Packets receiving state
501 #
502 # @normal: filter assigned packets according to the mac-table
503 #
504 # @none: don't receive any assigned packet
505 #
506 # @all: receive all assigned packets
507 #
508 # Since: 1.6
509 ##
510 { 'enum': 'RxState', 'data': [ 'normal', 'none', 'all' ] }
511
512 ##
513 # @RxFilterInfo:
514 #
515 # Rx-filter information for a NIC.
516 #
517 # @name: net client name
518 #
519 # @promiscuous: whether promiscuous mode is enabled
520 #
521 # @multicast: multicast receive state
522 #
523 # @unicast: unicast receive state
524 #
525 # @vlan: vlan receive state (Since 2.0)
526 #
527 # @broadcast-allowed: whether to receive broadcast
528 #
529 # @multicast-overflow: multicast table is overflowed or not
530 #
531 # @unicast-overflow: unicast table is overflowed or not
532 #
533 # @main-mac: the main macaddr string
534 #
535 # @vlan-table: a list of active vlan id
536 #
537 # @unicast-table: a list of unicast macaddr string
538 #
539 # @multicast-table: a list of multicast macaddr string
540 #
541 # Since: 1.6
542 ##
543 { 'struct': 'RxFilterInfo',
544   'data': {
545     'name':               'str',
546     'promiscuous':        'bool',
547     'multicast':          'RxState',
548     'unicast':            'RxState',
549     'vlan':               'RxState',
550     'broadcast-allowed':  'bool',
551     'multicast-overflow': 'bool',
552     'unicast-overflow':   'bool',
553     'main-mac':           'str',
554     'vlan-table':         ['int'],
555     'unicast-table':      ['str'],
556     'multicast-table':    ['str'] }}
557
558 ##
559 # @query-rx-filter:
560 #
561 # Return rx-filter information for all NICs (or for the given NIC).
562 #
563 # @name: net client name
564 #
565 # Returns: list of @RxFilterInfo for all NICs (or for the given NIC).
566 #          Returns an error if the given @name doesn't exist, or given
567 #          NIC doesn't support rx-filter querying, or given net client
568 #          isn't a NIC.
569 #
570 # Since: 1.6
571 #
572 # Example:
573 #
574 # -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
575 # <- { "return": [
576 #         {
577 #             "promiscuous": true,
578 #             "name": "vnet0",
579 #             "main-mac": "52:54:00:12:34:56",
580 #             "unicast": "normal",
581 #             "vlan": "normal",
582 #             "vlan-table": [
583 #                 4,
584 #                 0
585 #             ],
586 #             "unicast-table": [
587 #             ],
588 #             "multicast": "normal",
589 #             "multicast-overflow": false,
590 #             "unicast-overflow": false,
591 #             "multicast-table": [
592 #                 "01:00:5e:00:00:01",
593 #                 "33:33:00:00:00:01",
594 #                 "33:33:ff:12:34:56"
595 #             ],
596 #             "broadcast-allowed": false
597 #         }
598 #       ]
599 #    }
600 #
601 ##
602 { 'command': 'query-rx-filter',
603   'data': { '*name': 'str' },
604   'returns': ['RxFilterInfo'] }
605
606 ##
607 # @NIC_RX_FILTER_CHANGED:
608 #
609 # Emitted once until the 'query-rx-filter' command is executed, the first event
610 # will always be emitted
611 #
612 # @name: net client name
613 #
614 # @path: device path
615 #
616 # Since: 1.6
617 #
618 # Example:
619 #
620 # <- { "event": "NIC_RX_FILTER_CHANGED",
621 #      "data": { "name": "vnet0",
622 #                "path": "/machine/peripheral/vnet0/virtio-backend" },
623 #      "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
624 #    }
625 #
626 ##
627 { 'event': 'NIC_RX_FILTER_CHANGED',
628   'data': { '*name': 'str', 'path': 'str' } }
629
630 ##
631 # @AnnounceParameters:
632 #
633 # Parameters for self-announce timers
634 #
635 # @initial: Initial delay (in ms) before sending the first GARP/RARP
636 #           announcement
637 #
638 # @max: Maximum delay (in ms) between GARP/RARP announcement packets
639 #
640 # @rounds: Number of self-announcement attempts
641 #
642 # @step: Delay increase (in ms) after each self-announcement attempt
643 #
644 # @interfaces: An optional list of interface names, which restricts the
645 #              announcement to the listed interfaces. (Since 4.1)
646 #
647 # @id: A name to be used to identify an instance of announce-timers
648 #      and to allow it to modified later.  Not for use as
649 #      part of the migration parameters. (Since 4.1)
650 #
651 # Since: 4.0
652 ##
653
654 { 'struct': 'AnnounceParameters',
655   'data': { 'initial': 'int',
656             'max': 'int',
657             'rounds': 'int',
658             'step': 'int',
659             '*interfaces': ['str'],
660             '*id' : 'str' } }
661
662 ##
663 # @announce-self:
664 #
665 # Trigger generation of broadcast RARP frames to update network switches.
666 # This can be useful when network bonds fail-over the active slave.
667 #
668 # Example:
669 #
670 # -> { "execute": "announce-self",
671 #      "arguments": {
672 #          "initial": 50, "max": 550, "rounds": 10, "step": 50,
673 #          "interfaces": ["vn2", "vn3"], "id": "bob" } }
674 # <- { "return": {} }
675 #
676 # Since: 4.0
677 ##
678 { 'command': 'announce-self', 'boxed': true,
679   'data' : 'AnnounceParameters'}
680
681 ##
682 # @FAILOVER_NEGOTIATED:
683 #
684 # Emitted when VIRTIO_NET_F_STANDBY was enabled during feature negotiation.
685 # Failover primary devices which were hidden (not hotplugged when requested)
686 # before will now be hotplugged by the virtio-net standby device.
687 #
688 # device-id: QEMU device id of the unplugged device
689 # Since: 4.2
690 #
691 # Example:
692 #
693 # <- { "event": "FAILOVER_NEGOTIATED",
694 #      "data": "net1" }
695 #
696 ##
697 { 'event': 'FAILOVER_NEGOTIATED',
698   'data': {'device-id': 'str'} }