qapi/net.json

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