qemu/qapi/net.json

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

##
# ***********
# Net devices
# ***********
##

{ 'include': 'sockets.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
#
# Errors:
#     - If @name is not a valid network device, DeviceNotFound
#
# Since: 0.14
#
# .. note:: Not all network adapters support setting link status.
#    This command will succeed even if the network adapter does not
#    support link status notification.
#
# .. qmp-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
#
# Errors:
#     - If @type is not a valid network backend, DeviceNotFound
#
# .. qmp-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
#
# Errors:
#     - If @id is not a valid network backend, DeviceNotFound
#
# Since: 0.14
#
# .. qmp-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' } }

##
# @PasstSearch:
#
# @str: DNS domain name suffix for host name lookup, or "none".  See
#     passt(1) option --search.
#
# Since: 10.1
##
{ 'struct': 'PasstSearch',
  'data': {
    'str': 'str' } }

##
# @PasstPortForward:
#
# @str: passt port forwarding specification, see passt(1) option
#     --tcp-ports and --udp-ports.
#
# Since: 10.1
##
{ 'struct': 'PasstPortForward',
  'data': {
    'str': 'str' } }

##
# @PasstParameter:
#
# @str: Additional arguments for the passt executable, see passt(1)
#
# Since: 10.1
##
{ 'struct': 'PasstParameter',
  'data': {
    'str': 'str' } }

##
# @NetdevPasstOptions:
#
# Unprivileged user-mode network connectivity using passt
#
# @path: Filename of the passt program to run (by default 'passt', and
#     use PATH)
#
# @quiet: don't print informational messages (default, passed as
#     '--quiet')
#
# @vhost-user: enable vhost-user
#
# @mtu: assign MTU via DHCP/NDP
#
# @address: IPv4 or IPv6 address
#
# @netmask: IPv4 mask
#
# @mac: source MAC address
#
# @gateway: IPv4 or IPv6 address as gateway
#
# @interface: interface for addresses and routes
#
# @outbound: bind to address as outbound source
#
# @outbound-if4: bind to outbound interface for IPv4
#
# @outbound-if6: bind to outbound interface for IPv6
#
# @dns: IPv4 or IPv6 address as DNS
#
# @search: search domains
#
# @fqdn: FQDN to configure client with
#
# @dhcp-dns: enable/disable DNS list in DHCP/DHCPv6/NDP
#
# @dhcp-search: enable/disable list in DHCP/DHCPv6/NDP
#
# @map-host-loopback: addresse to refer to host
#
# @map-guest-addr: addr to translate to guest's address
#
# @dns-forward: forward DNS queries sent to
#
# @dns-host: host nameserver to direct queries to
#
# @tcp: enable/disable TCP
#
# @udp: enable/disable UDP
#
# @icmp: enable/disable ICMP
#
# @dhcp: enable/disable DHCP
#
# @ndp: enable/disable NDP
#
# @dhcpv6: enable/disable DHCPv6
#
# @ra: enable/disable route advertisements
#
# @freebind: bind to any address for forwarding
#
# @ipv4: enable/disable IPv4
#
# @ipv6: enable/disable IPv6
#
# @tcp-ports: TCP ports to forward
#
# @udp-ports: UDP ports to forward
#
# @param: parameter to pass to passt command
#
# Since: 10.1
##
{ 'struct': 'NetdevPasstOptions',
  'data': {
    '*path':               'str',
    '*quiet':              'bool',
    '*vhost-user':         'bool',
    '*mtu':                'int',
    '*address':            'str',
    '*netmask':            'str',
    '*mac':                'str',
    '*gateway':            'str',
    '*interface':          'str',
    '*outbound':           'str',
    '*outbound-if4':       'str',
    '*outbound-if6':       'str',
    '*dns':                'str',
    '*search':             ['PasstSearch'],
    '*fqdn':               'str',
    '*dhcp-dns':           'bool',
    '*dhcp-search':        'bool',
    '*map-host-loopback':  'str',
    '*map-guest-addr':     'str',
    '*dns-forward':        'str',
    '*dns-host':           'str',
    '*tcp':                'bool',
    '*udp':                'bool',
    '*icmp':               'bool',
    '*dhcp':               'bool',
    '*ndp':                'bool',
    '*dhcpv6':             'bool',
    '*ra':                 'bool',
    '*freebind':           'bool',
    '*ipv4':               'bool',
    '*ipv6':               'bool',
    '*tcp-ports':          ['PasstPortForward'],
    '*udp-ports':          ['PasstPortForward'],
    '*param':              ['PasstParameter'] },
    'if': 'CONFIG_PASST' }

##
# @NetdevUserDomainSuffix:
#
# @str: DNS domain name suffix for host name lookup, similar to
#     resolv.conf(5)
#
# Since: 1.2
##
{ 'struct': 'NetdevUserDomainSuffix',
  'data': {
    'str': 'str' } }

##
# @NetdevUserHostForward:
#
# @str: Host port forwarding rule
#
# TODO: This string gets parsed by slirp_hostfwd().  We fail to
#    document syntax and semantics here.  We do in qemu-options.hx.
#    Parsing structured configuration from strings is a no-no for QMP.
#    This should really be a struct.  Not sure it's worth the bother
#    now.
#
# Since: 1.2
##
{ 'struct': 'NetdevUserHostForward',
  'data': {
    'str': 'str' } }

##
# @NetdevUserGuestForward:
#
# @str: Guest port forwarding rule
#
# TODO: This string gets parsed by slirp_guestfwd().  We fail to
#    document syntax and semantics here.  We do in qemu-options.hx.
#    Parsing structured configuration from strings is a no-no for QMP.
#    This should really be a struct.  Not sure it's worth the bother
#    now.
#
# Since: 1.2
##
{ 'struct': 'NetdevUserGuestForward',
  'data': {
    'str': 'str' } }

##
# @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::).  The network
#     prefix is given in the usual hexadecimal IPv6 address notation.
#     (since 2.6)
#
# @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, UDP or UNIX 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': ['NetdevUserDomainSuffix'],
    '*domainname': 'str',
    '*ipv6-prefix':      'str',
    '*ipv6-prefixlen':   'int',
    '*ipv6-host':        'str',
    '*ipv6-dns':         'str',
    '*smb':       'str',
    '*smbserver': 'str',
    '*hostfwd':   ['NetdevUserHostForward'],
    '*guestfwd':  ['NetdevUserGuestForward'],
    '*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.  An empty string
#     disables script execution.  Defaults to
#     ``<sysconfdir>/qemu-ifup``, where ``<sysconfdir>`` is the
#     system configuration directory at build time (typically /etc).
#     Using "no" to disable script execution is deprecated (since
#     11.2); use an empty string instead.  In a future version, "no"
#     will be treated as a plain file name.
#
# @downscript: script to shut down the interface.  An empty string
#     disables script execution.  Defaults to
#     ``<sysconfdir>/qemu-ifdown``, where ``<sysconfdir>`` is the
#     system configuration directory at build time (typically /etc).
#     Using "no" to disable script execution is deprecated (since
#     11.2); use an empty string instead.  In a future version, "no"
#     will be treated as a plain file name.
#
# @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)
#
# @x-permit-local-migration: permit local migration for this TAP
#     backend.  When set, local migration is enabled/disabled by
#     migration parameter @local for this TAP backend.  When unset,
#     migration parameter @local is ignored for this TAP backend.
#
#     To be able to do incoming local migration of a TAP backend,
#     migration parameter @local must be set _before_ creating the
#     TAP backend.  Otherwise, TAP backend is initialized as usual,
#     opening/creating TAP devices in kernel.  In this case further
#     local incoming migration (with migration parameter @local set
#     after creating TAP backend with @x-permit-local-migration
#     parameter set) will simply fail.
#
#     Moreover, when QEMU is in incoming migration state, migration
#     parameter @local is set and @x-permit-local-migration is set,
#     the following options are not supported and must not be set:
#     @fd, @fds, @helper, @br, @ifname, @sndbuf, @vnet_hdr.
#     Additionally, @script and @downscript must be explicitly
#     disabled then.
#     (default: false, since 11.2)
#
# Features:
#
# @unstable: Member @x-permit-local-migration is experimental.
#
# 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',
    '*x-permit-local-migration': {
      'type': 'bool', 'features' : [ 'unstable'] } } }

##
# @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' } }

##
# @AFXDPMode:
#
# Attach mode for a default XDP program
#
# @skb: generic mode, no driver support necessary
#
# @native: DRV mode, program is attached to a driver, packets are
#     passed to the socket without allocation of skb.
#
# Since: 8.2
##
{ 'enum': 'AFXDPMode',
  'data': [ 'native', 'skb' ],
  'if': 'CONFIG_AF_XDP' }

##
# @NetdevAFXDPOptions:
#
# AF_XDP network backend
#
# @ifname: The name of an existing network interface.
#
# @mode: Attach mode for a default XDP program.  If not specified,
#     then 'native' will be tried first, then 'skb'.
#
# @force-copy: Force XDP copy mode even if device supports zero-copy.
#     (default: false)
#
# @queues: number of queues to be used for multiqueue interfaces
#     (default: 1).
#
# @start-queue: Use @queues starting from this queue number
#     (default: 0).
#
# @inhibit: Don't load a default XDP program, use one already loaded
#     to the interface (default: false).  Requires @sock-fds or
#     @map-path.
#
# @sock-fds: A colon (:) separated list of file descriptors for
#     already open but not bound AF_XDP sockets in the queue order.
#     One fd per queue.  These descriptors should already be added
#     into XDP socket map for corresponding queues.  @sock-fds and
#     @map-path are mutually exclusive.  Requires @inhibit.
#
# @map-path: The path to a pinned xsk map to push file descriptors
#     for bound AF_XDP sockets into.  @map-path and @sock-fds are
#     mutually exclusive.  Requires @inhibit.  (Since 10.1)
#
# @map-start-index: Use @map-path to insert xsk sockets starting from
#     this index number (default: 0).  Requires @map-path.
#     (Since 10.1)
#
# Since: 8.2
##
{ 'struct': 'NetdevAFXDPOptions',
  'data': {
    'ifname':           'str',
    '*mode':            'AFXDPMode',
    '*force-copy':      'bool',
    '*queues':          'int',
    '*start-queue':     'int',
    '*inhibit':         'bool',
    '*sock-fds':        'str',
    '*map-path':        'str',
    '*map-start-index': 'int32' },
  'if': 'CONFIG_AF_XDP' }

##
# @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')
#
# @vhostfd: file descriptor of an already opened vhost vdpa device
#
# @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',
    '*vhostfd':      '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' }

##
# @NetdevStreamOptions:
#
# Configuration info for stream socket netdev
#
# @addr: socket address to listen on (server=true) or connect to
#     (server=false)
#
# @server: create server socket (default: false)
#
# @reconnect-ms: For a client socket, if a socket is disconnected,
#     then attempt a reconnect after the given number of milliseconds.
#     Setting this to zero disables this function.
#     (default: 0) (Since: 9.2)
#
# Only `SocketAddress` types 'unix', 'inet' and 'fd' are supported.
#
# Since: 7.2
##
{ 'struct': 'NetdevStreamOptions',
  'data': {
    'addr':   'SocketAddress',
    '*server': 'bool',
    '*reconnect-ms': 'int' } }

##
# @NetdevDgramOptions:
#
# Configuration info for datagram socket netdev.
#
# @remote: remote address
#
# @local: local address
#
# Only `SocketAddress` types 'unix', 'inet' and 'fd' are supported.
#
# If remote address is present and it's a multicast address, local
# address is optional.  Otherwise local address is required and remote
# address is optional.
#
# .. table:: Valid parameters combination table
#    :widths: auto
#
#    =============  ========  =====
#    remote         local     okay?
#    =============  ========  =====
#    absent         absent    no
#    absent         not fd    no
#    absent         fd        yes
#    multicast      absent    yes
#    multicast      present   yes
#    not multicast  absent    no
#    not multicast  present   yes
#    =============  ========  =====
#
# Since: 7.2
##
{ 'struct': 'NetdevDgramOptions',
  'data': {
    '*local':  'SocketAddress',
    '*remote': 'SocketAddress' } }

##
# @NetClientDriver:
#
# Available netdev drivers.
#
# @l2tpv3: since 2.1
#
# @vhost-vdpa: since 5.1
#
# @vmnet-host: since 7.1
#
# @vmnet-shared: since 7.1
#
# @vmnet-bridged: since 7.1
#
# @stream: since 7.2
#
# @dgram: since 7.2
#
# @af-xdp: since 8.2
#
# @passt: since 10.1
#
# Since: 2.7
##
{ 'enum': 'NetClientDriver',
  'data': [ 'none', 'nic',
            { 'name': 'user', 'if': 'CONFIG_SLIRP' },
            'tap', 'l2tpv3', 'socket', 'stream', 'dgram',
            { 'name': 'vde', 'if': 'CONFIG_VDE' },
            'bridge', 'hubport',
            { 'name': 'netmap', 'if': 'CONFIG_NETMAP' },
            'vhost-user', 'vhost-vdpa',
            { 'name': 'passt', 'if': 'CONFIG_PASST' },
            { 'name': 'af-xdp', 'if': 'CONFIG_AF_XDP' },
            { '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
##
{ 'union': 'Netdev',
  'base': { 'id': 'str', 'type': 'NetClientDriver' },
  'discriminator': 'type',
  'data': {
    'nic':      'NetLegacyNicOptions',
    'passt':    { 'type': 'NetdevPasstOptions',
                  'if': 'CONFIG_PASST' },
    'user':     { 'type': 'NetdevUserOptions',
                  'if': 'CONFIG_SLIRP' },
    'tap':      'NetdevTapOptions',
    'l2tpv3':   'NetdevL2TPv3Options',
    'socket':   'NetdevSocketOptions',
    'stream':   'NetdevStreamOptions',
    'dgram':    'NetdevDgramOptions',
    'vde':      { 'type': 'NetdevVdeOptions',
                  'if': 'CONFIG_VDE' },
    'bridge':   'NetdevBridgeOptions',
    'hubport':  'NetdevHubPortOptions',
    'netmap':   { 'type': 'NetdevNetmapOptions',
                  'if': 'CONFIG_NETMAP' },
    'af-xdp':   { 'type': 'NetdevAFXDPOptions',
                  'if': 'CONFIG_AF_XDP' },
    '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 info for all NICs (or for the given NIC).
#
# Errors:
#     - if the given @name doesn't exist
#     - if the given NIC doesn't support rx-filter querying
#     - if the given net client isn't a NIC
#
# Since: 1.6
#
# .. qmp-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
#
# .. qmp-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.
#
# TODO: This line is a hack to separate the example from the body
#
# .. qmp-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
#
# .. qmp-example::
#
#     <- { "event": "FAILOVER_NEGOTIATED",
#          "data": { "device-id": "net1" },
#          "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
##
{ 'event': 'FAILOVER_NEGOTIATED',
  'data': {'device-id': 'str'} }

##
# @NETDEV_STREAM_CONNECTED:
#
# Emitted when the netdev stream backend is connected
#
# @netdev-id: QEMU netdev id that is connected
#
# @addr: The destination address
#
# Since: 7.2
#
# .. qmp-example::
#
#     <- { "event": "NETDEV_STREAM_CONNECTED",
#          "data": { "netdev-id": "netdev0",
#                    "addr": { "port": "47666", "ipv6": true,
#                              "host": "::1", "type": "inet" } },
#          "timestamp": { "seconds": 1666269863, "microseconds": 311222 } }
#
# .. qmp-example::
#
#     <- { "event": "NETDEV_STREAM_CONNECTED",
#          "data": { "netdev-id": "netdev0",
#                    "addr": { "path": "/tmp/qemu0", "type": "unix" } },
#          "timestamp": { "seconds": 1666269706, "microseconds": 413651 } }
##
{ 'event': 'NETDEV_STREAM_CONNECTED',
  'data': { 'netdev-id': 'str',
            'addr': 'SocketAddress' } }

##
# @NETDEV_STREAM_DISCONNECTED:
#
# Emitted when the netdev stream backend is disconnected
#
# @netdev-id: QEMU netdev id that is disconnected
#
# Since: 7.2
#
# .. qmp-example::
#
#     <- { "event": "NETDEV_STREAM_DISCONNECTED",
#          "data": {"netdev-id": "netdev0"},
#          "timestamp": {"seconds": 1663330937, "microseconds": 526695} }
##
{ 'event': 'NETDEV_STREAM_DISCONNECTED',
  'data': { 'netdev-id': 'str' } }

##
# @NETDEV_VHOST_USER_CONNECTED:
#
# Emitted when the vhost-user chardev is connected
#
# @netdev-id: QEMU netdev id that is connected
#
# @chardev-id: The character device id used by the QEMU netdev
#
# Since: 10.0
#
# .. qmp-example::
#
#     <- { "timestamp": {"seconds": 1739538638, "microseconds": 354181 },
#          "event": "NETDEV_VHOST_USER_CONNECTED",
#          "data": { "netdev-id": "netdev0", "chardev-id": "chr0" } }
##
{ 'event': 'NETDEV_VHOST_USER_CONNECTED',
  'data': { 'netdev-id': 'str', 'chardev-id': 'str' } }

##
# @NETDEV_VHOST_USER_DISCONNECTED:
#
# Emitted when the vhost-user chardev is disconnected
#
# @netdev-id: QEMU netdev id that is disconnected
#
# Since: 10.0
#
# .. qmp-example::
#
#     <- { "timestamp": { "seconds": 1739538634, "microseconds": 920450 },
#          "event": "NETDEV_VHOST_USER_DISCONNECTED",
#          "data": { "netdev-id": "netdev0" } }
##
{ 'event': 'NETDEV_VHOST_USER_DISCONNECTED',
  'data': { 'netdev-id': 'str' } }

##
# @UsernetInfo:
#
# Information about a user-mode network stack (slirp).
#
# @hub-id: The hub id, if available.
#
# @hub-name: The name of the hub.
#
# @info: Network information from slirp.
#
# Since: 11.2
##
{ 'struct': 'UsernetInfo',
  'data': {
    '*hub-id': 'int',
    'hub-name': 'str',
    'info': 'str' },
  'if': 'CONFIG_SLIRP' }

##
# @x-query-usernet:
#
# Query user-mode network stack connection states.
#
# Features:
#
# @unstable: This command is meant for debugging.
#
# Returns: list of user-mode network stack information.
#
# Since: 11.2
#
# .. qmp-example::
#
#     -> { "execute": "x-query-usernet" }
#     <- { "return": [ { "hub-id": 0, "hub-name": "vnet",
#                        "info": "..." } ] }
##
{ 'command': 'x-query-usernet',
  'returns': ['UsernetInfo'],
  'if': 'CONFIG_SLIRP',
  'features': [ 'unstable' ] }

##
# @NetFilterInfo:
#
# Information about a netfilter attached to a network client.
#
# @name: filter object name (QOM path component)
#
# @type: QOM type name (e.g. "filter-mirror")
#
# @info: filter properties as comma-separated key=value pairs
#        (excluding @type)
#
# Since: 11.2
##
{ 'struct': 'NetFilterInfo',
  'data': {
    'name': 'str',
    'type': 'str',
    'info': 'str' } }

##
# @NetworkClientInfo:
#
# Information about a network client.
#
# @name: unique network client identifier
#
# @queue-index: index of this queue (0 for single-queue clients)
#
# @type: network client driver type
#
# @info-str: driver-specific formatted information string (e.g.
#            "model=e1000,macaddr=52:54:00:12:34:56")
#
# @peer: the connected peer client (always a leaf; the peer's own
#        peer field is never populated)
#
# @filters: attached netfilters
#
# Since: 11.2
##
{ 'struct': 'NetworkClientInfo',
  'data': {
    'name': 'str',
    'queue-index': 'uint32',
    'type': 'NetClientDriver',
    'info-str': 'str',
    '*peer': 'NetworkClientInfo',
    'filters': ['NetFilterInfo'] } }

##
# @NetHubPortInfo:
#
# Information about a hub port.
#
# @name: hub port identifier
#
# @peer: the network client connected through this port
#
# Since: 11.2
##
{ 'struct': 'NetHubPortInfo',
  'data': {
    'name': 'str',
    '*peer': 'NetworkClientInfo' } }

##
# @NetHubInfo:
#
# Information about a network hub.
#
# @id: hub identifier
#
# @ports: list of ports on this hub
#
# Since: 11.2
##
{ 'struct': 'NetHubInfo',
  'data': {
    'id': 'int',
    'ports': ['NetHubPortInfo'] } }

##
# @NetworkInfo:
#
# Information about the network configuration.
#
# @hubs: network hubs and their ports
#
# @clients: network clients not associated with a hub
#
# Since: 11.2
##
{ 'struct': 'NetworkInfo',
  'data': {
    'hubs': ['NetHubInfo'],
    'clients': ['NetworkClientInfo'] } }

##
# @x-query-network:
#
# Query the network configuration including hubs and clients.
#
# Features:
#
# @unstable: This command is meant for debugging.
#
# Returns: @NetworkInfo describing hubs and clients.
#
# Since: 11.2
#
# .. qmp-example::
#
#     -> { "execute": "x-query-network" }
#     <- { "return": { "clients": [ { "name": "st0",
#                      "queue-index": 0, "type": "stream",
#                      "info-str": "listening" } ] } }
##
{ 'command': 'x-query-network',
  'returns': 'NetworkInfo',
  'features': [ 'unstable' ] }