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 # @NetFilterDirection:
 472 #
 473 # Indicates whether a netfilter is attached to a netdev's transmit queue or
 474 # receive queue or both.
 475 #
 476 # @all: the filter is attached both to the receive and the transmit
 477 #       queue of the netdev (default).
 478 #
 479 # @rx: the filter is attached to the receive queue of the netdev,
 480 #      where it will receive packets sent to the netdev.
 481 #
 482 # @tx: the filter is attached to the transmit queue of the netdev,
 483 #      where it will receive packets sent by the netdev.
 484 #
 485 # Since: 2.5
 486 ##
 487 { 'enum': 'NetFilterDirection',
 488   'data': [ 'all', 'rx', 'tx' ] }
 489
 490 ##
 491 # @RxState:
 492 #
 493 # Packets receiving state
 494 #
 495 # @normal: filter assigned packets according to the mac-table
 496 #
 497 # @none: don't receive any assigned packet
 498 #
 499 # @all: receive all assigned packets
 500 #
 501 # Since: 1.6
 502 ##
 503 { 'enum': 'RxState', 'data': [ 'normal', 'none', 'all' ] }
 504
 505 ##
 506 # @RxFilterInfo:
 507 #
 508 # Rx-filter information for a NIC.
 509 #
 510 # @name: net client name
 511 #
 512 # @promiscuous: whether promiscuous mode is enabled
 513 #
 514 # @multicast: multicast receive state
 515 #
 516 # @unicast: unicast receive state
 517 #
 518 # @vlan: vlan receive state (Since 2.0)
 519 #
 520 # @broadcast-allowed: whether to receive broadcast
 521 #
 522 # @multicast-overflow: multicast table is overflowed or not
 523 #
 524 # @unicast-overflow: unicast table is overflowed or not
 525 #
 526 # @main-mac: the main macaddr string
 527 #
 528 # @vlan-table: a list of active vlan id
 529 #
 530 # @unicast-table: a list of unicast macaddr string
 531 #
 532 # @multicast-table: a list of multicast macaddr string
 533 #
 534 # Since: 1.6
 535 ##
 536 { 'struct': 'RxFilterInfo',
 537   'data': {
 538     'name':               'str',
 539     'promiscuous':        'bool',
 540     'multicast':          'RxState',
 541     'unicast':            'RxState',
 542     'vlan':               'RxState',
 543     'broadcast-allowed':  'bool',
 544     'multicast-overflow': 'bool',
 545     'unicast-overflow':   'bool',
 546     'main-mac':           'str',
 547     'vlan-table':         ['int'],
 548     'unicast-table':      ['str'],
 549     'multicast-table':    ['str'] }}
 550
 551 ##
 552 # @query-rx-filter:
 553 #
 554 # Return rx-filter information for all NICs (or for the given NIC).
 555 #
 556 # @name: net client name
 557 #
 558 # Returns: list of @RxFilterInfo for all NICs (or for the given NIC).
 559 #          Returns an error if the given @name doesn't exist, or given
 560 #          NIC doesn't support rx-filter querying, or given net client
 561 #          isn't a NIC.
 562 #
 563 # Since: 1.6
 564 #
 565 # Example:
 566 #
 567 # -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
 568 # <- { "return": [
 569 #         {
 570 #             "promiscuous": true,
 571 #             "name": "vnet0",
 572 #             "main-mac": "52:54:00:12:34:56",
 573 #             "unicast": "normal",
 574 #             "vlan": "normal",
 575 #             "vlan-table": [
 576 #                 4,
 577 #                 0
 578 #             ],
 579 #             "unicast-table": [
 580 #             ],
 581 #             "multicast": "normal",
 582 #             "multicast-overflow": false,
 583 #             "unicast-overflow": false,
 584 #             "multicast-table": [
 585 #                 "01:00:5e:00:00:01",
 586 #                 "33:33:00:00:00:01",
 587 #                 "33:33:ff:12:34:56"
 588 #             ],
 589 #             "broadcast-allowed": false
 590 #         }
 591 #       ]
 592 #    }
 593 #
 594 ##
 595 { 'command': 'query-rx-filter',
 596   'data': { '*name': 'str' },
 597   'returns': ['RxFilterInfo'] }
 598
 599 ##
 600 # @NIC_RX_FILTER_CHANGED:
 601 #
 602 # Emitted once until the 'query-rx-filter' command is executed, the first event
 603 # will always be emitted
 604 #
 605 # @name: net client name
 606 #
 607 # @path: device path
 608 #
 609 # Since: 1.6
 610 #
 611 # Example:
 612 #
 613 # <- { "event": "NIC_RX_FILTER_CHANGED",
 614 #      "data": { "name": "vnet0",
 615 #                "path": "/machine/peripheral/vnet0/virtio-backend" },
 616 #      "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
 617 #    }
 618 #
 619 ##
 620 { 'event': 'NIC_RX_FILTER_CHANGED',
 621   'data': { '*name': 'str', 'path': 'str' } }
 622
 623 ##
 624 # @AnnounceParameters:
 625 #
 626 # Parameters for self-announce timers
 627 #
 628 # @initial: Initial delay (in ms) before sending the first GARP/RARP
 629 #           announcement
 630 #
 631 # @max: Maximum delay (in ms) between GARP/RARP announcement packets
 632 #
 633 # @rounds: Number of self-announcement attempts
 634 #
 635 # @step: Delay increase (in ms) after each self-announcement attempt
 636 #
 637 # @interfaces: An optional list of interface names, which restricts the
 638 #              announcement to the listed interfaces. (Since 4.1)
 639 #
 640 # @id: A name to be used to identify an instance of announce-timers
 641 #      and to allow it to modified later.  Not for use as
 642 #      part of the migration parameters. (Since 4.1)
 643 #
 644 # Since: 4.0
 645 ##
 646
 647 { 'struct': 'AnnounceParameters',
 648   'data': { 'initial': 'int',
 649             'max': 'int',
 650             'rounds': 'int',
 651             'step': 'int',
 652             '*interfaces': ['str'],
 653             '*id' : 'str' } }
 654
 655 ##
 656 # @announce-self:
 657 #
 658 # Trigger generation of broadcast RARP frames to update network switches.
 659 # This can be useful when network bonds fail-over the active slave.
 660 #
 661 # Example:
 662 #
 663 # -> { "execute": "announce-self",
 664 #      "arguments": {
 665 #          "initial": 50, "max": 550, "rounds": 10, "step": 50,
 666 #          "interfaces": ["vn2", "vn3"], "id": "bob" } }
 667 # <- { "return": {} }
 668 #
 669 # Since: 4.0
 670 ##
 671 { 'command': 'announce-self', 'boxed': true,
 672   'data' : 'AnnounceParameters'}
 673
 674 ##
 675 # @FAILOVER_NEGOTIATED:
 676 #
 677 # Emitted when VIRTIO_NET_F_STANDBY was enabled during feature negotiation.
 678 # Failover primary devices which were hidden (not hotplugged when requested)
 679 # before will now be hotplugged by the virtio-net standby device.
 680 #
 681 # device-id: QEMU device id of the unplugged device
 682 # Since: 4.2
 683 #
 684 # Example:
 685 #
 686 # <- { "event": "FAILOVER_NEGOTIATED",
 687 #      "data": "net1" }
 688 #
 689 ##
 690 { 'event': 'FAILOVER_NEGOTIATED',
 691   'data': {'device-id': 'str'} }