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