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