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 # @NetClientDriver:
 433 #
 434 # Available netdev drivers.
 435 #
 436 # Since: 2.7
 437 ##
 438 { 'enum': 'NetClientDriver',
 439   'data': [ 'none', 'nic', 'user', 'tap', 'l2tpv3', 'socket', 'vde',
 440             'bridge', 'hubport', 'netmap', 'vhost-user' ] }
 441
 442 ##
 443 # @Netdev:
 444 #
 445 # Captures the configuration of a network device.
 446 #
 447 # @id: identifier for monitor commands.
 448 #
 449 # @type: Specify the driver used for interpreting remaining arguments.
 450 #
 451 # Since: 1.2
 452 #
 453 #        'l2tpv3' - since 2.1
 454 ##
 455 { 'union': 'Netdev',
 456   'base': { 'id': 'str', 'type': 'NetClientDriver' },
 457   'discriminator': 'type',
 458   'data': {
 459     'nic':      'NetLegacyNicOptions',
 460     'user':     'NetdevUserOptions',
 461     'tap':      'NetdevTapOptions',
 462     'l2tpv3':   'NetdevL2TPv3Options',
 463     'socket':   'NetdevSocketOptions',
 464     'vde':      'NetdevVdeOptions',
 465     'bridge':   'NetdevBridgeOptions',
 466     'hubport':  'NetdevHubPortOptions',
 467     'netmap':   'NetdevNetmapOptions',
 468     'vhost-user': 'NetdevVhostUserOptions' } }
 469
 470 ##
 471 # @NetLegacy:
 472 #
 473 # Captures the configuration of a network device; legacy.
 474 #
 475 # @id: identifier for monitor commands
 476 #
 477 # @name: identifier for monitor commands, ignored if @id is present
 478 #
 479 # @opts: device type specific properties (legacy)
 480 #
 481 # Since: 1.2
 482 ##
 483 { 'struct': 'NetLegacy',
 484   'data': {
 485     '*id':   'str',
 486     '*name': 'str',
 487     'opts':  'NetLegacyOptions' } }
 488
 489 ##
 490 # @NetLegacyOptionsType:
 491 #
 492 # Since: 1.2
 493 ##
 494 { 'enum': 'NetLegacyOptionsType',
 495   'data': ['none', 'nic', 'user', 'tap', 'l2tpv3', 'socket', 'vde',
 496            'bridge', 'netmap', 'vhost-user'] }
 497
 498 ##
 499 # @NetLegacyOptions:
 500 #
 501 # Like Netdev, but for use only by the legacy command line options
 502 #
 503 # Since: 1.2
 504 ##
 505 { 'union': 'NetLegacyOptions',
 506   'base': { 'type': 'NetLegacyOptionsType' },
 507   'discriminator': 'type',
 508   'data': {
 509     'nic':      'NetLegacyNicOptions',
 510     'user':     'NetdevUserOptions',
 511     'tap':      'NetdevTapOptions',
 512     'l2tpv3':   'NetdevL2TPv3Options',
 513     'socket':   'NetdevSocketOptions',
 514     'vde':      'NetdevVdeOptions',
 515     'bridge':   'NetdevBridgeOptions',
 516     'netmap':   'NetdevNetmapOptions',
 517     'vhost-user': 'NetdevVhostUserOptions' } }
 518
 519 ##
 520 # @NetFilterDirection:
 521 #
 522 # Indicates whether a netfilter is attached to a netdev's transmit queue or
 523 # receive queue or both.
 524 #
 525 # @all: the filter is attached both to the receive and the transmit
 526 #       queue of the netdev (default).
 527 #
 528 # @rx: the filter is attached to the receive queue of the netdev,
 529 #      where it will receive packets sent to the netdev.
 530 #
 531 # @tx: the filter is attached to the transmit queue of the netdev,
 532 #      where it will receive packets sent by the netdev.
 533 #
 534 # Since: 2.5
 535 ##
 536 { 'enum': 'NetFilterDirection',
 537   'data': [ 'all', 'rx', 'tx' ] }
 538
 539 ##
 540 # @RxState:
 541 #
 542 # Packets receiving state
 543 #
 544 # @normal: filter assigned packets according to the mac-table
 545 #
 546 # @none: don't receive any assigned packet
 547 #
 548 # @all: receive all assigned packets
 549 #
 550 # Since: 1.6
 551 ##
 552 { 'enum': 'RxState', 'data': [ 'normal', 'none', 'all' ] }
 553
 554 ##
 555 # @RxFilterInfo:
 556 #
 557 # Rx-filter information for a NIC.
 558 #
 559 # @name: net client name
 560 #
 561 # @promiscuous: whether promiscuous mode is enabled
 562 #
 563 # @multicast: multicast receive state
 564 #
 565 # @unicast: unicast receive state
 566 #
 567 # @vlan: vlan receive state (Since 2.0)
 568 #
 569 # @broadcast-allowed: whether to receive broadcast
 570 #
 571 # @multicast-overflow: multicast table is overflowed or not
 572 #
 573 # @unicast-overflow: unicast table is overflowed or not
 574 #
 575 # @main-mac: the main macaddr string
 576 #
 577 # @vlan-table: a list of active vlan id
 578 #
 579 # @unicast-table: a list of unicast macaddr string
 580 #
 581 # @multicast-table: a list of multicast macaddr string
 582 #
 583 # Since: 1.6
 584 ##
 585 { 'struct': 'RxFilterInfo',
 586   'data': {
 587     'name':               'str',
 588     'promiscuous':        'bool',
 589     'multicast':          'RxState',
 590     'unicast':            'RxState',
 591     'vlan':               'RxState',
 592     'broadcast-allowed':  'bool',
 593     'multicast-overflow': 'bool',
 594     'unicast-overflow':   'bool',
 595     'main-mac':           'str',
 596     'vlan-table':         ['int'],
 597     'unicast-table':      ['str'],
 598     'multicast-table':    ['str'] }}
 599
 600 ##
 601 # @query-rx-filter:
 602 #
 603 # Return rx-filter information for all NICs (or for the given NIC).
 604 #
 605 # @name: net client name
 606 #
 607 # Returns: list of @RxFilterInfo for all NICs (or for the given NIC).
 608 #          Returns an error if the given @name doesn't exist, or given
 609 #          NIC doesn't support rx-filter querying, or given net client
 610 #          isn't a NIC.
 611 #
 612 # Since: 1.6
 613 #
 614 # Example:
 615 #
 616 # -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
 617 # <- { "return": [
 618 #         {
 619 #             "promiscuous": true,
 620 #             "name": "vnet0",
 621 #             "main-mac": "52:54:00:12:34:56",
 622 #             "unicast": "normal",
 623 #             "vlan": "normal",
 624 #             "vlan-table": [
 625 #                 4,
 626 #                 0
 627 #             ],
 628 #             "unicast-table": [
 629 #             ],
 630 #             "multicast": "normal",
 631 #             "multicast-overflow": false,
 632 #             "unicast-overflow": false,
 633 #             "multicast-table": [
 634 #                 "01:00:5e:00:00:01",
 635 #                 "33:33:00:00:00:01",
 636 #                 "33:33:ff:12:34:56"
 637 #             ],
 638 #             "broadcast-allowed": false
 639 #         }
 640 #       ]
 641 #    }
 642 #
 643 ##
 644 { 'command': 'query-rx-filter',
 645   'data': { '*name': 'str' },
 646   'returns': ['RxFilterInfo'] }
 647
 648 ##
 649 # @NIC_RX_FILTER_CHANGED:
 650 #
 651 # Emitted once until the 'query-rx-filter' command is executed, the first event
 652 # will always be emitted
 653 #
 654 # @name: net client name
 655 #
 656 # @path: device path
 657 #
 658 # Since: 1.6
 659 #
 660 # Example:
 661 #
 662 # <- { "event": "NIC_RX_FILTER_CHANGED",
 663 #      "data": { "name": "vnet0",
 664 #                "path": "/machine/peripheral/vnet0/virtio-backend" },
 665 #      "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
 666 #    }
 667 #
 668 ##
 669 { 'event': 'NIC_RX_FILTER_CHANGED',
 670   'data': { '*name': 'str', 'path': 'str' } }
 671
 672 ##
 673 # @AnnounceParameters:
 674 #
 675 # Parameters for self-announce timers
 676 #
 677 # @initial: Initial delay (in ms) before sending the first GARP/RARP
 678 #           announcement
 679 #
 680 # @max: Maximum delay (in ms) between GARP/RARP announcement packets
 681 #
 682 # @rounds: Number of self-announcement attempts
 683 #
 684 # @step: Delay increase (in ms) after each self-announcement attempt
 685 #
 686 # @interfaces: An optional list of interface names, which restricts the
 687 #              announcement to the listed interfaces. (Since 4.1)
 688 #
 689 # @id: A name to be used to identify an instance of announce-timers
 690 #      and to allow it to modified later.  Not for use as
 691 #      part of the migration parameters. (Since 4.1)
 692 #
 693 # Since: 4.0
 694 ##
 695
 696 { 'struct': 'AnnounceParameters',
 697   'data': { 'initial': 'int',
 698             'max': 'int',
 699             'rounds': 'int',
 700             'step': 'int',
 701             '*interfaces': ['str'],
 702             '*id' : 'str' } }
 703
 704 ##
 705 # @announce-self:
 706 #
 707 # Trigger generation of broadcast RARP frames to update network switches.
 708 # This can be useful when network bonds fail-over the active slave.
 709 #
 710 # Example:
 711 #
 712 # -> { "execute": "announce-self",
 713 #      "arguments": {
 714 #          "initial": 50, "max": 550, "rounds": 10, "step": 50,
 715 #          "interfaces": ["vn2", "vn3"], "id": "bob" } }
 716 # <- { "return": {} }
 717 #
 718 # Since: 4.0
 719 ##
 720 { 'command': 'announce-self', 'boxed': true,
 721   'data' : 'AnnounceParameters'}
 722
 723 ##
 724 # @FAILOVER_NEGOTIATED:
 725 #
 726 # Emitted when VIRTIO_NET_F_STANDBY was enabled during feature negotiation.
 727 # Failover primary devices which were hidden (not hotplugged when requested)
 728 # before will now be hotplugged by the virtio-net standby device.
 729 #
 730 # device-id: QEMU device id of the unplugged device
 731 # Since: 4.2
 732 #
 733 # Example:
 734 #
 735 # <- { "event": "FAILOVER_NEGOTIATED",
 736 #      "data": "net1" }
 737 #
 738 ##
 739 { 'event': 'FAILOVER_NEGOTIATED',
 740   'data': {'device-id': 'str'} }