path: root/qapi/net.json

# -*- Mode: Python -*-
# vim: filetype=python
#

##
# = Net devices
##

{ 'include': 'common.json' }

##
# @set_link:
#
# Sets the link status of a virtual network adapter.
#
# @name: the device name of the virtual network adapter
#
# @up: true to set the link status to be up
#
# Returns: Nothing on success
#          If @name is not a valid network device, DeviceNotFound
#
# Since: 0.14
#
# Notes: Not all network adapters support setting link status.  This command
#        will succeed even if the network adapter does not support link status
#        notification.
#
# Example:
#
# -> { "execute": "set_link",
#      "arguments": { "name": "e1000.0", "up": false } }
# <- { "return": {} }
#
##
{ 'command': 'set_link', 'data': {'name': 'str', 'up': 'bool'} }

##
# @netdev_add:
#
# Add a network backend.
#
# Additional arguments depend on the type.
#
# Since: 0.14
#
# Returns: Nothing on success
#          If @type is not a valid network backend, DeviceNotFound
#
# Example:
#
# -> { "execute": "netdev_add",
#      "arguments": { "type": "user", "id": "netdev1",
#                     "dnssearch": [ { "str": "example.org" } ] } }
# <- { "return": {} }
#
##
{ 'command': 'netdev_add', 'data': 'Netdev', 'boxed': true,
  'allow-preconfig': true }

##
# @netdev_del:
#
# Remove a network backend.
#
# @id: the name of the network backend to remove
#
# Returns: Nothing on success
#          If @id is not a valid network backend, DeviceNotFound
#
# Since: 0.14
#
# Example:
#
# -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
# <- { "return": {} }
#
##
{ 'command': 'netdev_del', 'data': {'id': 'str'},
  'allow-preconfig': true }

##
# @NetLegacyNicOptions:
#
# Create a new Network Interface Card.
#
# @netdev: id of -netdev to connect to
#
# @macaddr: MAC address
#
# @model: device model (e1000, rtl8139, virtio etc.)
#
# @addr: PCI device address
#
# @vectors: number of MSI-x vectors, 0 to disable MSI-X
#
# Since: 1.2
##
{ 'struct': 'NetLegacyNicOptions',
  'data': {
    '*netdev':  'str',
    '*macaddr': 'str',
    '*model':   'str',
    '*addr':    'str',
    '*vectors': 'uint32' } }

##
# @NetdevUserOptions:
#
# Use the user mode network stack which requires no administrator privilege to
# run.
#
# @hostname: client hostname reported by the builtin DHCP server
#
# @restrict: isolate the guest from the host
#
# @ipv4: whether to support IPv4, default true for enabled
#        (since 2.6)
#
# @ipv6: whether to support IPv6, default true for enabled
#        (since 2.6)
#
# @ip: legacy parameter, use net= instead
#
# @net: IP network address that the guest will see, in the
#       form addr[/netmask] The netmask is optional, and can be
#       either in the form a.b.c.d or as a number of valid top-most
#       bits. Default is 10.0.2.0/24.
#
# @host: guest-visible address of the host
#
# @tftp: root directory of the built-in TFTP server
#
# @bootfile: BOOTP filename, for use with tftp=
#
# @dhcpstart: the first of the 16 IPs the built-in DHCP server can
#             assign
#
# @dns: guest-visible address of the virtual nameserver
#
# @dnssearch: list of DNS suffixes to search, passed as DHCP option
#             to the guest
#
# @domainname: guest-visible domain name of the virtual nameserver
#              (since 3.0)
#
# @ipv6-prefix: IPv6 network prefix (default is fec0::) (since
#               2.6). The network prefix is given in the usual
#               hexadecimal IPv6 address notation.
#
# @ipv6-prefixlen: IPv6 network prefix length (default is 64)
#                  (since 2.6)
#
# @ipv6-host: guest-visible IPv6 address of the host (since 2.6)
#
# @ipv6-dns: guest-visible IPv6 address of the virtual
#            nameserver (since 2.6)
#
# @smb: root directory of the built-in SMB server
#
# @smbserver: IP address of the built-in SMB server
#
# @hostfwd: redirect incoming TCP or UDP host connections to guest
#           endpoints
#
# @guestfwd: forward guest TCP connections
#
# @tftp-server-name: RFC2132 "TFTP server name" string (Since 3.1)
#
# Since: 1.2
##
{ 'struct': 'NetdevUserOptions',
  'data': {
    '*hostname':  'str',
    '*restrict':  'bool',
    '*ipv4':      'bool',
    '*ipv6':      'bool',
    '*ip':        'str',
    '*net':       'str',
    '*host':      'str',
    '*tftp':      'str',
    '*bootfile':  'str',
    '*dhcpstart': 'str',
    '*dns':       'str',
    '*dnssearch': ['String'],
    '*domainname': 'str',
    '*ipv6-prefix':      'str',
    '*ipv6-prefixlen':   'int',
    '*ipv6-host':        'str',
    '*ipv6-dns':         'str',
    '*smb':       'str',
    '*smbserver': 'str',
    '*hostfwd':   ['String'],
    '*guestfwd':  ['String'],
    '*tftp-server-name': 'str' } }

##
# @NetdevTapOptions:
#
# Used to configure a host TAP network interface backend.
#
# @ifname: interface name
#
# @fd: file descriptor of an already opened tap
#
# @fds: multiple file descriptors of already opened multiqueue capable
#       tap
#
# @script: script to initialize the interface
#
# @downscript: script to shut down the interface
#
# @br: bridge name (since 2.8)
#
# @helper: command to execute to configure bridge
#
# @sndbuf: send buffer limit. Understands [TGMKkb] suffixes.
#
# @vnet_hdr: enable the IFF_VNET_HDR flag on the tap interface
#
# @vhost: enable vhost-net network accelerator
#
# @vhostfd: file descriptor of an already opened vhost net device
#
# @vhostfds: file descriptors of multiple already opened vhost net
#            devices
#
# @vhostforce: vhost on for non-MSIX virtio guests
#
# @queues: number of queues to be created for multiqueue capable tap
#
# @poll-us: maximum number of microseconds that could
#           be spent on busy polling for tap (since 2.7)
#
# Since: 1.2
##
{ 'struct': 'NetdevTapOptions',
  'data': {
    '*ifname':     'str',
    '*fd':         'str',
    '*fds':        'str',
    '*script':     'str',
    '*downscript': 'str',
    '*br':         'str',
    '*helper':     'str',
    '*sndbuf':     'size',
    '*vnet_hdr':   'bool',
    '*vhost':      'bool',
    '*vhostfd':    'str',
    '*vhostfds':   'str',
    '*vhostforce': 'bool',
    '*queues':     'uint32',
    '*poll-us':    'uint32'} }

##
# @NetdevSocketOptions:
#
# Socket netdevs are used to establish a network connection to another
# QEMU virtual machine via a TCP socket.
#
# @fd: file descriptor of an already opened socket
#
# @listen: port number, and optional hostname, to listen on
#
# @connect: port number, and optional hostname, to connect to
#
# @mcast: UDP multicast address and port number
#
# @localaddr: source address and port for multicast and udp packets
#
# @udp: UDP unicast address and port number
#
# Since: 1.2
##
{ 'struct': 'NetdevSocketOptions',
  'data': {
    '*fd':        'str',
    '*listen':    'str',
    '*connect':   'str',
    '*mcast':     'str',
    '*localaddr': 'str',
    '*udp':       'str' } }

##
# @NetdevL2TPv3Options:
#
# Configure an Ethernet over L2TPv3 tunnel.
#
# @src: source address
#
# @dst: destination address
#
# @srcport: source port - mandatory for udp, optional for ip
#
# @dstport: destination port - mandatory for udp, optional for ip
#
# @ipv6: force the use of ipv6
#
# @udp: use the udp version of l2tpv3 encapsulation
#
# @cookie64: use 64 bit cookies
#
# @counter: have sequence counter
#
# @pincounter: pin sequence counter to zero -
#              workaround for buggy implementations or
#              networks with packet reorder
#
# @txcookie: 32 or 64 bit transmit cookie
#
# @rxcookie: 32 or 64 bit receive cookie
#
# @txsession: 32 bit transmit session
#
# @rxsession: 32 bit receive session - if not specified
#             set to the same value as transmit
#
# @offset: additional offset - allows the insertion of
#          additional application-specific data before the packet payload
#
# Since: 2.1
##
{ 'struct': 'NetdevL2TPv3Options',
  'data': {
    'src':          'str',
    'dst':          'str',
    '*srcport':     'str',
    '*dstport':     'str',
    '*ipv6':        'bool',
    '*udp':         'bool',
    '*cookie64':    'bool',
    '*counter':     'bool',
    '*pincounter':  'bool',
    '*txcookie':    'uint64',
    '*rxcookie':    'uint64',
    'txsession':    'uint32',
    '*rxsession':   'uint32',
    '*offset':      'uint32' } }

##
# @NetdevVdeOptions:
#
# Connect to a vde switch running on the host.
#
# @sock: socket path
#
# @port: port number
#
# @group: group owner of socket
#
# @mode: permissions for socket
#
# Since: 1.2
##
{ 'struct': 'NetdevVdeOptions',
  'data': {
    '*sock':  'str',
    '*port':  'uint16',
    '*group': 'str',
    '*mode':  'uint16' } }

##
# @NetdevBridgeOptions:
#
# Connect a host TAP network interface to a host bridge device.
#
# @br: bridge name
#
# @helper: command to execute to configure bridge
#
# Since: 1.2
##
{ 'struct': 'NetdevBridgeOptions',
  'data': {
    '*br':     'str',
    '*helper': 'str' } }

##
# @NetdevHubPortOptions:
#
# Connect two or more net clients through a software hub.
#
# @hubid: hub identifier number
# @netdev: used to connect hub to a netdev instead of a device (since 2.12)
#
# Since: 1.2
##
{ 'struct': 'NetdevHubPortOptions',
  'data': {
    'hubid':     'int32',
    '*netdev':    'str' } }

##
# @NetdevNetmapOptions:
#
# Connect a client to a netmap-enabled NIC or to a VALE switch port
#
# @ifname: Either the name of an existing network interface supported by
#          netmap, or the name of a VALE port (created on the fly).
#          A VALE port name is in the form 'valeXXX:YYY', where XXX and
#          YYY are non-negative integers. XXX identifies a switch and
#          YYY identifies a port of the switch. VALE ports having the
#          same XXX are therefore connected to the same switch.
#
# @devname: path of the netmap device (default: '/dev/netmap').
#
# Since: 2.0
##
{ 'struct': 'NetdevNetmapOptions',
  'data': {
    'ifname':     'str',
    '*devname':    'str' } }

##
# @NetdevVhostUserOptions:
#
# Vhost-user network backend
#
# @chardev: name of a unix socket chardev
#
# @vhostforce: vhost on for non-MSIX virtio guests (default: false).
#
# @queues: number of queues to be created for multiqueue vhost-user
#          (default: 1) (Since 2.5)
#
# Since: 2.1
##
{ 'struct': 'NetdevVhostUserOptions',
  'data': {
    'chardev':        'str',
    '*vhostforce':    'bool',
    '*queues':        'int' } }

##
# @NetdevVhostVDPAOptions:
#
# Vhost-vdpa network backend
#
# vDPA device is a device that uses a datapath which complies with the virtio
# specifications with a vendor specific control path.
#
# @vhostdev: path of vhost-vdpa device
#            (default:'/dev/vhost-vdpa-0')
#
# @queues: number of queues to be created for multiqueue vhost-vdpa
#          (default: 1)
#
# @x-svq: Start device with (experimental) shadow virtqueue. (Since 7.1)
#         (default: false)
#
# Features:
# @unstable: Member @x-svq is experimental.
#
# Since: 5.1
##
{ 'struct': 'NetdevVhostVDPAOptions',
  'data': {
    '*vhostdev':     'str',
    '*queues':       'int',
    '*x-svq':        {'type': 'bool', 'features' : [ 'unstable'] } } }

##
# @NetdevVmnetHostOptions:
#
# vmnet (host mode) network backend.
#
# Allows the vmnet interface to communicate with other vmnet
# interfaces that are in host mode and also with the host.
#
# @start-address: The starting IPv4 address to use for the interface.
#                 Must be in the private IP range (RFC 1918). Must be
#                 specified along with @end-address and @subnet-mask.
#                 This address is used as the gateway address. The
#                 subsequent address up to and including end-address are
#                 placed in the DHCP pool.
#
# @end-address: The DHCP IPv4 range end address to use for the
#               interface. Must be in the private IP range (RFC 1918).
#               Must be specified along with @start-address and
#               @subnet-mask.
#
# @subnet-mask: The IPv4 subnet mask to use on the interface. Must
#               be specified along with @start-address and @subnet-mask.
#
# @isolated: Enable isolation for this interface. Interface isolation
#            ensures that vmnet interface is not able to communicate
#            with any other vmnet interfaces. Only communication with
#            host is allowed. Requires at least macOS Big Sur 11.0.
#
# @net-uuid: The identifier (UUID) to uniquely identify the isolated
#            network vmnet interface should be added to. If
#            set, no DHCP service is provided for this interface and
#            network communication is allowed only with other interfaces
#            added to this network identified by the UUID. Requires
#            at least macOS Big Sur 11.0.
#
# Since: 7.1
##
{ 'struct': 'NetdevVmnetHostOptions',
  'data': {
    '*start-address': 'str',
    '*end-address':   'str',
    '*subnet-mask':   'str',
    '*isolated':      'bool',
    '*net-uuid':      'str' },
  'if': 'CONFIG_VMNET' }

##
# @NetdevVmnetSharedOptions:
#
# vmnet (shared mode) network backend.
#
# Allows traffic originating from the vmnet interface to reach the
# Internet through a network address translator (NAT).
# The vmnet interface can communicate with the host and with
# other shared mode interfaces on the same subnet. If no DHCP
# settings, subnet mask and IPv6 prefix specified, the interface can
# communicate with any of other interfaces in shared mode.
#
# @start-address: The starting IPv4 address to use for the interface.
#                 Must be in the private IP range (RFC 1918). Must be
#                 specified along with @end-address and @subnet-mask.
#                 This address is used as the gateway address. The
#                 subsequent address up to and including end-address are
#                 placed in the DHCP pool.
#
# @end-address: The DHCP IPv4 range end address to use for the
#               interface. Must be in the private IP range (RFC 1918).
#               Must be specified along with @start-address and @subnet-mask.
#
# @subnet-mask: The IPv4 subnet mask to use on the interface. Must
#                be specified along with @start-address and @subnet-mask.
#
# @isolated: Enable isolation for this interface. Interface isolation
#            ensures that vmnet interface is not able to communicate
#            with any other vmnet interfaces. Only communication with
#            host is allowed. Requires at least macOS Big Sur 11.0.
#
# @nat66-prefix: The IPv6 prefix to use into guest network. Must be a
#                unique local address i.e. start with fd00::/8 and have
#                length of 64.
#
# Since: 7.1
##
{ 'struct': 'NetdevVmnetSharedOptions',
  'data': {
    '*start-address': 'str',
    '*end-address':   'str',
    '*subnet-mask':   'str',
    '*isolated':      'bool',
    '*nat66-prefix':  'str' },
  'if': 'CONFIG_VMNET' }

##
# @NetdevVmnetBridgedOptions:
#
# vmnet (bridged mode) network backend.
#
# Bridges the vmnet interface with a physical network interface.
#
# @ifname: The name of the physical interface to be bridged.
#
# @isolated: Enable isolation for this interface. Interface isolation
#            ensures that vmnet interface is not able to communicate
#            with any other vmnet interfaces. Only communication with
#            host is allowed. Requires at least macOS Big Sur 11.0.
#
# Since: 7.1
##
{ 'struct': 'NetdevVmnetBridgedOptions',
  'data': {
    'ifname':     'str',
    '*isolated':  'bool' },
  'if': 'CONFIG_VMNET' }

##
# @NetClientDriver:
#
# Available netdev drivers.
#
# Since: 2.7
#
#        @vhost-vdpa since 5.1
#        @vmnet-host since 7.1
#        @vmnet-shared since 7.1
#        @vmnet-bridged since 7.1
##
{ 'enum': 'NetClientDriver',
  'data': [ 'none', 'nic', 'user', 'tap', 'l2tpv3', 'socket', 'vde',
            'bridge', 'hubport', 'netmap', 'vhost-user', 'vhost-vdpa',
            { 'name': 'vmnet-host', 'if': 'CONFIG_VMNET' },
            { 'name': 'vmnet-shared', 'if': 'CONFIG_VMNET' },
            { 'name': 'vmnet-bridged', 'if': 'CONFIG_VMNET' }] }

##
# @Netdev:
#
# Captures the configuration of a network device.
#
# @id: identifier for monitor commands.
#
# @type: Specify the driver used for interpreting remaining arguments.
#
# Since: 1.2
#
#        'l2tpv3' - since 2.1
#        'vmnet-host' - since 7.1
#        'vmnet-shared' - since 7.1
#        'vmnet-bridged' - since 7.1
##
{ 'union': 'Netdev',
  'base': { 'id': 'str', 'type': 'NetClientDriver' },
  'discriminator': 'type',
  'data': {
    'nic':      'NetLegacyNicOptions',
    'user':     'NetdevUserOptions',
    'tap':      'NetdevTapOptions',
    'l2tpv3':   'NetdevL2TPv3Options',
    'socket':   'NetdevSocketOptions',
    'vde':      'NetdevVdeOptions',
    'bridge':   'NetdevBridgeOptions',
    'hubport':  'NetdevHubPortOptions',
    'netmap':   'NetdevNetmapOptions',
    'vhost-user': 'NetdevVhostUserOptions',
    'vhost-vdpa': 'NetdevVhostVDPAOptions',
    'vmnet-host': { 'type': 'NetdevVmnetHostOptions',
                    'if': 'CONFIG_VMNET' },
    'vmnet-shared': { 'type': 'NetdevVmnetSharedOptions',
                      'if': 'CONFIG_VMNET' },
    'vmnet-bridged': { 'type': 'NetdevVmnetBridgedOptions',
                       'if': 'CONFIG_VMNET' } } }

##
# @RxState:
#
# Packets receiving state
#
# @normal: filter assigned packets according to the mac-table
#
# @none: don't receive any assigned packet
#
# @all: receive all assigned packets
#
# Since: 1.6
##
{ 'enum': 'RxState', 'data': [ 'normal', 'none', 'all' ] }

##
# @RxFilterInfo:
#
# Rx-filter information for a NIC.
#
# @name: net client name
#
# @promiscuous: whether promiscuous mode is enabled
#
# @multicast: multicast receive state
#
# @unicast: unicast receive state
#
# @vlan: vlan receive state (Since 2.0)
#
# @broadcast-allowed: whether to receive broadcast
#
# @multicast-overflow: multicast table is overflowed or not
#
# @unicast-overflow: unicast table is overflowed or not
#
# @main-mac: the main macaddr string
#
# @vlan-table: a list of active vlan id
#
# @unicast-table: a list of unicast macaddr string
#
# @multicast-table: a list of multicast macaddr string
#
# Since: 1.6
##
{ 'struct': 'RxFilterInfo',
  'data': {
    'name':               'str',
    'promiscuous':        'bool',
    'multicast':          'RxState',
    'unicast':            'RxState',
    'vlan':               'RxState',
    'broadcast-allowed':  'bool',
    'multicast-overflow': 'bool',
    'unicast-overflow':   'bool',
    'main-mac':           'str',
    'vlan-table':         ['int'],
    'unicast-table':      ['str'],
    'multicast-table':    ['str'] }}

##
# @query-rx-filter:
#
# Return rx-filter information for all NICs (or for the given NIC).
#
# @name: net client name
#
# Returns: list of @RxFilterInfo for all NICs (or for the given NIC).
#          Returns an error if the given @name doesn't exist, or given
#          NIC doesn't support rx-filter querying, or given net client
#          isn't a NIC.
#
# Since: 1.6
#
# Example:
#
# -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
# <- { "return": [
#         {
#             "promiscuous": true,
#             "name": "vnet0",
#             "main-mac": "52:54:00:12:34:56",
#             "unicast": "normal",
#             "vlan": "normal",
#             "vlan-table": [
#                 4,
#                 0
#             ],
#             "unicast-table": [
#             ],
#             "multicast": "normal",
#             "multicast-overflow": false,
#             "unicast-overflow": false,
#             "multicast-table": [
#                 "01:00:5e:00:00:01",
#                 "33:33:00:00:00:01",
#                 "33:33:ff:12:34:56"
#             ],
#             "broadcast-allowed": false
#         }
#       ]
#    }
#
##
{ 'command': 'query-rx-filter',
  'data': { '*name': 'str' },
  'returns': ['RxFilterInfo'] }

##
# @NIC_RX_FILTER_CHANGED:
#
# Emitted once until the 'query-rx-filter' command is executed, the first event
# will always be emitted
#
# @name: net client name
#
# @path: device path
#
# Since: 1.6
#
# Example:
#
# <- { "event": "NIC_RX_FILTER_CHANGED",
#      "data": { "name": "vnet0",
#                "path": "/machine/peripheral/vnet0/virtio-backend" },
#      "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
#
##
{ 'event': 'NIC_RX_FILTER_CHANGED',
  'data': { '*name': 'str', 'path': 'str' } }

##
# @AnnounceParameters:
#
# Parameters for self-announce timers
#
# @initial: Initial delay (in ms) before sending the first GARP/RARP
#           announcement
#
# @max: Maximum delay (in ms) between GARP/RARP announcement packets
#
# @rounds: Number of self-announcement attempts
#
# @step: Delay increase (in ms) after each self-announcement attempt
#
# @interfaces: An optional list of interface names, which restricts the
#              announcement to the listed interfaces. (Since 4.1)
#
# @id: A name to be used to identify an instance of announce-timers
#      and to allow it to modified later.  Not for use as
#      part of the migration parameters. (Since 4.1)
#
# Since: 4.0
##

{ 'struct': 'AnnounceParameters',
  'data': { 'initial': 'int',
            'max': 'int',
            'rounds': 'int',
            'step': 'int',
            '*interfaces': ['str'],
            '*id' : 'str' } }

##
# @announce-self:
#
# Trigger generation of broadcast RARP frames to update network switches.
# This can be useful when network bonds fail-over the active slave.
#
# Example:
#
# -> { "execute": "announce-self",
#      "arguments": {
#          "initial": 50, "max": 550, "rounds": 10, "step": 50,
#          "interfaces": ["vn2", "vn3"], "id": "bob" } }
# <- { "return": {} }
#
# Since: 4.0
##
{ 'command': 'announce-self', 'boxed': true,
  'data' : 'AnnounceParameters'}

##
# @FAILOVER_NEGOTIATED:
#
# Emitted when VIRTIO_NET_F_STANDBY was enabled during feature negotiation.
# Failover primary devices which were hidden (not hotplugged when requested)
# before will now be hotplugged by the virtio-net standby device.
#
# @device-id: QEMU device id of the unplugged device
#
# Since: 4.2
#
# Example:
#
# <- { "event": "FAILOVER_NEGOTIATED",
#      "data": { "device-id": "net1" },
#      "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
#
##
{ 'event': 'FAILOVER_NEGOTIATED',
  'data': {'device-id': 'str'} }