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# Since: 1.2 178## 179{ 'struct': 'NetdevUserOptions', 180 'data': { 181 '*hostname': 'str', 182 '*restrict': 'bool', 183 '*ipv4': 'bool', 184 '*ipv6': 'bool', 185 '*ip': 'str', 186 '*net': 'str', 187 '*host': 'str', 188 '*tftp': 'str', 189 '*bootfile': 'str', 190 '*dhcpstart': 'str', 191 '*dns': 'str', 192 '*dnssearch': ['String'], 193 '*domainname': 'str', 194 '*ipv6-prefix': 'str', 195 '*ipv6-prefixlen': 'int', 196 '*ipv6-host': 'str', 197 '*ipv6-dns': 'str', 198 '*smb': 'str', 199 '*smbserver': 'str', 200 '*hostfwd': ['String'], 201 '*guestfwd': ['String'] } } 202 203## 204# @NetdevTapOptions: 205# 206# Used to configure a host TAP network interface backend. 207# 208# @ifname: interface name 209# 210# @fd: file descriptor of an already opened tap 211# 212# @fds: multiple file descriptors of already opened multiqueue capable 213# tap 214# 215# @script: script to initialize the interface 216# 217# @downscript: script to shut down the interface 218# 219# @br: bridge name (since 2.8) 220# 221# @helper: command to execute to configure bridge 222# 223# @sndbuf: send buffer limit. Understands [TGMKkb] suffixes. 224# 225# @vnet_hdr: enable the IFF_VNET_HDR flag on the tap interface 226# 227# @vhost: enable vhost-net network accelerator 228# 229# @vhostfd: file descriptor of an already opened vhost net device 230# 231# @vhostfds: file descriptors of multiple already opened vhost net 232# devices 233# 234# @vhostforce: vhost on for non-MSIX virtio guests 235# 236# @queues: number of queues to be created for multiqueue capable tap 237# 238# @poll-us: maximum number of microseconds that could 239# be spent on busy polling for tap (since 2.7) 240# 241# Since: 1.2 242## 243{ 'struct': 'NetdevTapOptions', 244 'data': { 245 '*ifname': 'str', 246 '*fd': 'str', 247 '*fds': 'str', 248 '*script': 'str', 249 '*downscript': 'str', 250 '*br': 'str', 251 '*helper': 'str', 252 '*sndbuf': 'size', 253 '*vnet_hdr': 'bool', 254 '*vhost': 'bool', 255 '*vhostfd': 'str', 256 '*vhostfds': 'str', 257 '*vhostforce': 'bool', 258 '*queues': 'uint32', 259 '*poll-us': 'uint32'} } 260 261## 262# @NetdevSocketOptions: 263# 264# Socket netdevs are used to establish a network connection to another 265# QEMU virtual machine via a TCP socket. 266# 267# @fd: file descriptor of an already opened socket 268# 269# @listen: port number, and optional hostname, to listen on 270# 271# @connect: port number, and optional hostname, to connect to 272# 273# @mcast: UDP multicast address and port number 274# 275# @localaddr: source address and port for multicast and udp packets 276# 277# @udp: UDP unicast address and port number 278# 279# Since: 1.2 280## 281{ 'struct': 'NetdevSocketOptions', 282 'data': { 283 '*fd': 'str', 284 '*listen': 'str', 285 '*connect': 'str', 286 '*mcast': 'str', 287 '*localaddr': 'str', 288 '*udp': 'str' } } 289 290## 291# @NetdevL2TPv3Options: 292# 293# Configure an Ethernet over L2TPv3 tunnel. 294# 295# @src: source address 296# 297# @dst: destination address 298# 299# @srcport: source port - mandatory for udp, optional for ip 300# 301# @dstport: destination port - mandatory for udp, optional for ip 302# 303# @ipv6: force the use of ipv6 304# 305# @udp: use the udp version of l2tpv3 encapsulation 306# 307# @cookie64: use 64 bit coookies 308# 309# @counter: have sequence counter 310# 311# @pincounter: pin sequence counter to zero - 312# workaround for buggy implementations or 313# networks with packet reorder 314# 315# @txcookie: 32 or 64 bit transmit cookie 316# 317# @rxcookie: 32 or 64 bit receive cookie 318# 319# @txsession: 32 bit transmit session 320# 321# @rxsession: 32 bit receive session - if not specified 322# set to the same value as transmit 323# 324# @offset: additional offset - allows the insertion of 325# additional application-specific data before the packet payload 326# 327# Since: 2.1 328## 329{ 'struct': 'NetdevL2TPv3Options', 330 'data': { 331 'src': 'str', 332 'dst': 'str', 333 '*srcport': 'str', 334 '*dstport': 'str', 335 '*ipv6': 'bool', 336 '*udp': 'bool', 337 '*cookie64': 'bool', 338 '*counter': 'bool', 339 '*pincounter': 'bool', 340 '*txcookie': 'uint64', 341 '*rxcookie': 'uint64', 342 'txsession': 'uint32', 343 '*rxsession': 'uint32', 344 '*offset': 'uint32' } } 345 346## 347# @NetdevVdeOptions: 348# 349# Connect to a vde switch running on the host. 350# 351# @sock: socket path 352# 353# @port: port number 354# 355# @group: group owner of socket 356# 357# @mode: permissions for socket 358# 359# Since: 1.2 360## 361{ 'struct': 'NetdevVdeOptions', 362 'data': { 363 '*sock': 'str', 364 '*port': 'uint16', 365 '*group': 'str', 366 '*mode': 'uint16' } } 367 368## 369# @NetdevBridgeOptions: 370# 371# Connect a host TAP network interface to a host bridge device. 372# 373# @br: bridge name 374# 375# @helper: command to execute to configure bridge 376# 377# Since: 1.2 378## 379{ 'struct': 'NetdevBridgeOptions', 380 'data': { 381 '*br': 'str', 382 '*helper': 'str' } } 383 384## 385# @NetdevHubPortOptions: 386# 387# Connect two or more net clients through a software hub. 388# 389# @hubid: hub identifier number 390# @netdev: used to connect hub to a netdev instead of a device (since 2.12) 391# 392# Since: 1.2 393## 394{ 'struct': 'NetdevHubPortOptions', 395 'data': { 396 'hubid': 'int32', 397 '*netdev': 'str' } } 398 399## 400# @NetdevNetmapOptions: 401# 402# Connect a client to a netmap-enabled NIC or to a VALE switch port 403# 404# @ifname: Either the name of an existing network interface supported by 405# netmap, or the name of a VALE port (created on the fly). 406# A VALE port name is in the form 'valeXXX:YYY', where XXX and 407# YYY are non-negative integers. XXX identifies a switch and 408# YYY identifies a port of the switch. VALE ports having the 409# same XXX are therefore connected to the same switch. 410# 411# @devname: path of the netmap device (default: '/dev/netmap'). 412# 413# Since: 2.0 414## 415{ 'struct': 'NetdevNetmapOptions', 416 'data': { 417 'ifname': 'str', 418 '*devname': 'str' } } 419 420## 421# @NetdevVhostUserOptions: 422# 423# Vhost-user network backend 424# 425# @chardev: name of a unix socket chardev 426# 427# @vhostforce: vhost on for non-MSIX virtio guests (default: false). 428# 429# @queues: number of queues to be created for multiqueue vhost-user 430# (default: 1) (Since 2.5) 431# 432# Since: 2.1 433## 434{ 'struct': 'NetdevVhostUserOptions', 435 'data': { 436 'chardev': 'str', 437 '*vhostforce': 'bool', 438 '*queues': 'int' } } 439 440## 441# @NetClientDriver: 442# 443# Available netdev drivers. 444# 445# Since: 2.7 446# 447# 'dump': dropped in 2.12 448## 449{ 'enum': 'NetClientDriver', 450 'data': [ 'none', 'nic', 'user', 'tap', 'l2tpv3', 'socket', 'vde', 451 'bridge', 'hubport', 'netmap', 'vhost-user' ] } 452 453## 454# @Netdev: 455# 456# Captures the configuration of a network device. 457# 458# @id: identifier for monitor commands. 459# 460# @type: Specify the driver used for interpreting remaining arguments. 461# 462# Since: 1.2 463# 464# 'l2tpv3' - since 2.1 465## 466{ 'union': 'Netdev', 467 'base': { 'id': 'str', 'type': 'NetClientDriver' }, 468 'discriminator': 'type', 469 'data': { 470 'nic': 'NetLegacyNicOptions', 471 'user': 'NetdevUserOptions', 472 'tap': 'NetdevTapOptions', 473 'l2tpv3': 'NetdevL2TPv3Options', 474 'socket': 'NetdevSocketOptions', 475 'vde': 'NetdevVdeOptions', 476 'bridge': 'NetdevBridgeOptions', 477 'hubport': 'NetdevHubPortOptions', 478 'netmap': 'NetdevNetmapOptions', 479 'vhost-user': 'NetdevVhostUserOptions' } } 480 481## 482# @NetLegacy: 483# 484# Captures the configuration of a network device; legacy. 485# 486# @id: identifier for monitor commands 487# 488# @name: identifier for monitor commands, ignored if @id is present 489# 490# @opts: device type specific properties (legacy) 491# 492# Since: 1.2 493# 494# 'vlan': dropped in 3.0 495## 496{ 'struct': 'NetLegacy', 497 'data': { 498 '*id': 'str', 499 '*name': 'str', 500 'opts': 'NetLegacyOptions' } } 501 502## 503# @NetLegacyOptionsType: 504# 505# Since: 1.2 506## 507{ 'enum': 'NetLegacyOptionsType', 508 'data': ['none', 'nic', 'user', 'tap', 'l2tpv3', 'socket', 'vde', 509 'bridge', 'netmap', 'vhost-user'] } 510 511## 512# @NetLegacyOptions: 513# 514# Like Netdev, but for use only by the legacy command line options 515# 516# Since: 1.2 517## 518{ 'union': 'NetLegacyOptions', 519 'base': { 'type': 'NetLegacyOptionsType' }, 520 'discriminator': 'type', 521 'data': { 522 'nic': 'NetLegacyNicOptions', 523 'user': 'NetdevUserOptions', 524 'tap': 'NetdevTapOptions', 525 'l2tpv3': 'NetdevL2TPv3Options', 526 'socket': 'NetdevSocketOptions', 527 'vde': 'NetdevVdeOptions', 528 'bridge': 'NetdevBridgeOptions', 529 'netmap': 'NetdevNetmapOptions', 530 'vhost-user': 'NetdevVhostUserOptions' } } 531 532## 533# @NetFilterDirection: 534# 535# Indicates whether a netfilter is attached to a netdev's transmit queue or 536# receive queue or both. 537# 538# @all: the filter is attached both to the receive and the transmit 539# queue of the netdev (default). 540# 541# @rx: the filter is attached to the receive queue of the netdev, 542# where it will receive packets sent to the netdev. 543# 544# @tx: the filter is attached to the transmit queue of the netdev, 545# where it will receive packets sent by the netdev. 546# 547# Since: 2.5 548## 549{ 'enum': 'NetFilterDirection', 550 'data': [ 'all', 'rx', 'tx' ] } 551 552## 553# @RxState: 554# 555# Packets receiving state 556# 557# @normal: filter assigned packets according to the mac-table 558# 559# @none: don't receive any assigned packet 560# 561# @all: receive all assigned packets 562# 563# Since: 1.6 564## 565{ 'enum': 'RxState', 'data': [ 'normal', 'none', 'all' ] } 566 567## 568# @RxFilterInfo: 569# 570# Rx-filter information for a NIC. 571# 572# @name: net client name 573# 574# @promiscuous: whether promiscuous mode is enabled 575# 576# @multicast: multicast receive state 577# 578# @unicast: unicast receive state 579# 580# @vlan: vlan receive state (Since 2.0) 581# 582# @broadcast-allowed: whether to receive broadcast 583# 584# @multicast-overflow: multicast table is overflowed or not 585# 586# @unicast-overflow: unicast table is overflowed or not 587# 588# @main-mac: the main macaddr string 589# 590# @vlan-table: a list of active vlan id 591# 592# @unicast-table: a list of unicast macaddr string 593# 594# @multicast-table: a list of multicast macaddr string 595# 596# Since: 1.6 597## 598{ 'struct': 'RxFilterInfo', 599 'data': { 600 'name': 'str', 601 'promiscuous': 'bool', 602 'multicast': 'RxState', 603 'unicast': 'RxState', 604 'vlan': 'RxState', 605 'broadcast-allowed': 'bool', 606 'multicast-overflow': 'bool', 607 'unicast-overflow': 'bool', 608 'main-mac': 'str', 609 'vlan-table': ['int'], 610 'unicast-table': ['str'], 611 'multicast-table': ['str'] }} 612 613## 614# @query-rx-filter: 615# 616# Return rx-filter information for all NICs (or for the given NIC). 617# 618# @name: net client name 619# 620# Returns: list of @RxFilterInfo for all NICs (or for the given NIC). 621# Returns an error if the given @name doesn't exist, or given 622# NIC doesn't support rx-filter querying, or given net client 623# isn't a NIC. 624# 625# Since: 1.6 626# 627# Example: 628# 629# -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } } 630# <- { "return": [ 631# { 632# "promiscuous": true, 633# "name": "vnet0", 634# "main-mac": "52:54:00:12:34:56", 635# "unicast": "normal", 636# "vlan": "normal", 637# "vlan-table": [ 638# 4, 639# 0 640# ], 641# "unicast-table": [ 642# ], 643# "multicast": "normal", 644# "multicast-overflow": false, 645# "unicast-overflow": false, 646# "multicast-table": [ 647# "01:00:5e:00:00:01", 648# "33:33:00:00:00:01", 649# "33:33:ff:12:34:56" 650# ], 651# "broadcast-allowed": false 652# } 653# ] 654# } 655# 656## 657{ 'command': 'query-rx-filter', 'data': { '*name': 'str' }, 658 'returns': ['RxFilterInfo'] } 659 660## 661# @NIC_RX_FILTER_CHANGED: 662# 663# Emitted once until the 'query-rx-filter' command is executed, the first event 664# will always be emitted 665# 666# @name: net client name 667# 668# @path: device path 669# 670# Since: 1.6 671# 672# Example: 673# 674# <- { "event": "NIC_RX_FILTER_CHANGED", 675# "data": { "name": "vnet0", 676# "path": "/machine/peripheral/vnet0/virtio-backend" }, 677# "timestamp": { "seconds": 1368697518, "microseconds": 326866 } } 678# } 679# 680## 681{ 'event': 'NIC_RX_FILTER_CHANGED', 682 'data': { '*name': 'str', 'path': 'str' } } 683