path: root/Documentation/netlink/specs/ovs_flow.yaml

# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)

name: ovs_flow
version: 1
protocol: genetlink-legacy
uapi-header: linux/openvswitch.h

doc:
  OVS flow configuration over generic netlink.

definitions:
  -
    name: ovs-header
    type: struct
    doc: |
      Header for OVS Generic Netlink messages.
    members:
      -
        name: dp-ifindex
        type: u32
        doc: |
          ifindex of local port for datapath (0 to make a request not specific
          to a datapath).
  -
    name: ovs-flow-stats
    type: struct
    members:
      -
        name: n-packets
        type: u64
        doc: Number of matched packets.
      -
        name: n-bytes
        type: u64
        doc: Number of matched bytes.
  -
    name: ovs-key-ethernet
    type: struct
    members:
      -
        name: eth-src
        type: binary
        len: 6
        display-hint: mac
      -
        name: eth-dst
        type: binary
        len: 6
        display-hint: mac
  -
    name: ovs-key-mpls
    type: struct
    members:
      -
        name: mpls-lse
        type: u32
        byte-order: big-endian
  -
    name: ovs-key-ipv4
    type: struct
    members:
      -
        name: ipv4-src
        type: u32
        byte-order: big-endian
        display-hint: ipv4
      -
        name: ipv4-dst
        type: u32
        byte-order: big-endian
        display-hint: ipv4
      -
        name: ipv4-proto
        type: u8
      -
        name: ipv4-tos
        type: u8
      -
        name: ipv4-ttl
        type: u8
      -
        name: ipv4-frag
        type: u8
        enum: ovs-frag-type
  -
    name: ovs-key-ipv6
    type: struct
    members:
      -
        name: ipv6-src
        type: binary
        len: 16
        byte-order: big-endian
        display-hint: ipv6
      -
        name: ipv6-dst
        type: binary
        len: 16
        byte-order: big-endian
        display-hint: ipv6
      -
        name: ipv6-label
        type: u32
        byte-order: big-endian
      -
        name: ipv6-proto
        type: u8
      -
        name: ipv6-tclass
        type: u8
      -
        name: ipv6-hlimit
        type: u8
      -
        name: ipv6-frag
        type: u8
  -
    name: ovs-key-ipv6-exthdrs
    type: struct
    members:
      -
        name: hdrs
        type: u16
  -
    name: ovs-frag-type
    name-prefix: ovs-frag-type-
    enum-name: ovs-frag-type
    type: enum
    entries:
      -
        name: none
        doc: Packet is not a fragment.
      -
        name: first
        doc: Packet is a fragment with offset 0.
      -
        name: later
        doc: Packet is a fragment with nonzero offset.
      -
        name: any
        value: 255
  -
    name: ovs-key-tcp
    type: struct
    members:
      -
        name: tcp-src
        type: u16
        byte-order: big-endian
      -
        name: tcp-dst
        type: u16
        byte-order: big-endian
  -
    name: ovs-key-udp
    type: struct
    members:
      -
        name: udp-src
        type: u16
        byte-order: big-endian
      -
        name: udp-dst
        type: u16
        byte-order: big-endian
  -
    name: ovs-key-sctp
    type: struct
    members:
      -
        name: sctp-src
        type: u16
        byte-order: big-endian
      -
        name: sctp-dst
        type: u16
        byte-order: big-endian
  -
    name: ovs-key-icmp
    type: struct
    members:
      -
        name: icmp-type
        type: u8
      -
        name: icmp-code
        type: u8
  -
    name: ovs-key-arp
    type: struct
    members:
      -
        name: arp-sip
        type: u32
        byte-order: big-endian
      -
        name: arp-tip
        type: u32
        byte-order: big-endian
      -
        name: arp-op
        type: u16
        byte-order: big-endian
      -
        name: arp-sha
        type: binary
        len: 6
        display-hint: mac
      -
        name: arp-tha
        type: binary
        len: 6
        display-hint: mac
  -
    name: ovs-key-nd
    type: struct
    members:
      -
        name: nd_target
        type: binary
        len: 16
        byte-order: big-endian
      -
        name: nd-sll
        type: binary
        len: 6
        display-hint: mac
      -
        name: nd-tll
        type: binary
        len: 6
        display-hint: mac
  -
    name: ovs-key-ct-tuple-ipv4
    type: struct
    members:
      -
        name: ipv4-src
        type: u32
        byte-order: big-endian
      -
        name: ipv4-dst
        type: u32
        byte-order: big-endian
      -
        name: src-port
        type: u16
        byte-order: big-endian
      -
        name: dst-port
        type: u16
        byte-order: big-endian
      -
        name: ipv4-proto
        type: u8
  -
    name: ovs-action-push-vlan
    type: struct
    members:
      -
        name: vlan_tpid
        type: u16
        byte-order: big-endian
        doc: Tag protocol identifier (TPID) to push.
      -
        name: vlan_tci
        type: u16
        byte-order: big-endian
        doc: Tag control identifier (TCI) to push.
  -
    name: ovs-ufid-flags
    name-prefix: ovs-ufid-f-
    enum-name:
    type: flags
    entries:
      - omit-key
      - omit-mask
      - omit-actions
  -
    name: ovs-action-hash
    type: struct
    members:
      -
        name: hash-alg
        type: u32
        doc: Algorithm used to compute hash prior to recirculation.
      -
        name: hash-basis
        type: u32
        doc: Basis used for computing hash.
  -
    name: ovs-hash-alg
    enum-name: ovs-hash-alg
    type: enum
    doc: |
      Data path hash algorithm for computing Datapath hash. The algorithm type only specifies
      the fields in a flow will be used as part of the hash. Each datapath is free to use its
      own hash algorithm. The hash value will be opaque to the user space daemon.
    entries:
      - ovs-hash-alg-l4

  -
    name: ovs-action-push-mpls
    type: struct
    members:
      -
        name: mpls-lse
        type: u32
        byte-order: big-endian
        doc: |
          MPLS label stack entry to push
      -
        name: mpls-ethertype
        type: u32
        byte-order: big-endian
        doc: |
          Ethertype to set in the encapsulating ethernet frame.  The only values
          ethertype should ever be given are ETH_P_MPLS_UC and ETH_P_MPLS_MC,
          indicating MPLS unicast or multicast. Other are rejected.
  -
    name: ovs-action-add-mpls
    type: struct
    members:
      -
        name: mpls-lse
        type: u32
        byte-order: big-endian
        doc: |
          MPLS label stack entry to push
      -
        name: mpls-ethertype
        type: u32
        byte-order: big-endian
        doc: |
          Ethertype to set in the encapsulating ethernet frame.  The only values
          ethertype should ever be given are ETH_P_MPLS_UC and ETH_P_MPLS_MC,
          indicating MPLS unicast or multicast. Other are rejected.
      -
        name: tun-flags
        type: u16
        doc: |
          MPLS tunnel attributes.
  -
    name: ct-state-flags
    enum-name:
    type: flags
    name-prefix: ovs-cs-f-
    entries:
      -
        name: new
        doc: Beginning of a new connection.
      -
        name: established
        doc: Part of an existing connenction
      -
        name: related
        doc: Related to an existing connection.
      -
        name: reply-dir
        doc: Flow is in the reply direction.
      -
        name: invalid
        doc: Could not track the connection.
      -
        name: tracked
        doc: Conntrack has occurred.
      -
        name: src-nat
        doc: Packet's source address/port was mangled by NAT.
      -
        name: dst-nat
        doc: Packet's destination address/port was mangled by NAT.

attribute-sets:
  -
    name: flow-attrs
    enum-name: ovs-flow-attr
    name-prefix: ovs-flow-attr-
    attributes:
      -
        name: key
        type: nest
        nested-attributes: key-attrs
        doc: |
          Nested attributes specifying the flow key. Always present in
          notifications. Required for all requests (except dumps).
      -
        name: actions
        type: nest
        nested-attributes: action-attrs
        doc: |
          Nested attributes specifying the actions to take for packets that
          match the key. Always present in notifications. Required for
          OVS_FLOW_CMD_NEW requests, optional for OVS_FLOW_CMD_SET requests.  An
          OVS_FLOW_CMD_SET without OVS_FLOW_ATTR_ACTIONS will not modify the
          actions.  To clear the actions, an OVS_FLOW_ATTR_ACTIONS without any
          nested attributes must be given.
      -
        name: stats
        type: binary
        struct: ovs-flow-stats
        doc: |
          Statistics for this flow. Present in notifications if the stats would
          be nonzero. Ignored in requests.
      -
        name: tcp-flags
        type: u8
        doc: |
          An 8-bit value giving the ORed value of all of the TCP flags seen on
          packets in this flow. Only present in notifications for TCP flows, and
          only if it would be nonzero. Ignored in requests.
      -
        name: used
        type: u64
        doc: |
          A 64-bit integer giving the time, in milliseconds on the system
          monotonic clock, at which a packet was last processed for this
          flow. Only present in notifications if a packet has been processed for
          this flow. Ignored in requests.
      -
        name: clear
        type: flag
        doc: |
          If present in a OVS_FLOW_CMD_SET request, clears the last-used time,
          accumulated TCP flags, and statistics for this flow.  Otherwise
          ignored in requests. Never present in notifications.
      -
        name: mask
        type: nest
        nested-attributes: key-attrs
        doc: |
          Nested attributes specifying the mask bits for wildcarded flow
          match. Mask bit value '1' specifies exact match with corresponding
          flow key bit, while mask bit value '0' specifies a wildcarded
          match. Omitting attribute is treated as wildcarding all corresponding
          fields. Optional for all requests. If not present, all flow key bits
          are exact match bits.
      -
        name: probe
        type: binary
        doc: |
          Flow operation is a feature probe, error logging should be suppressed.
      -
        name: ufid
        type: binary
        doc: |
          A value between 1-16 octets specifying a unique identifier for the
          flow. Causes the flow to be indexed by this value rather than the
          value of the OVS_FLOW_ATTR_KEY attribute. Optional for all
          requests. Present in notifications if the flow was created with this
          attribute.
        display-hint: uuid
      -
        name: ufid-flags
        type: u32
        enum: ovs-ufid-flags
        doc: |
          A 32-bit value of ORed flags that provide alternative semantics for
          flow installation and retrieval. Optional for all requests.
      -
        name: pad
        type: binary

  -
    name: key-attrs
    enum-name: ovs-key-attr
    name-prefix: ovs-key-attr-
    attributes:
      -
        name: encap
        type: nest
        nested-attributes: key-attrs
      -
        name: priority
        type: u32
      -
        name: in-port
        type: u32
      -
        name: ethernet
        type: binary
        struct: ovs-key-ethernet
        doc: struct ovs_key_ethernet
      -
        name: vlan
        type: u16
        byte-order: big-endian
      -
        name: ethertype
        type: u16
        byte-order: big-endian
      -
        name: ipv4
        type: binary
        struct: ovs-key-ipv4
      -
        name: ipv6
        type: binary
        struct: ovs-key-ipv6
        doc: struct ovs_key_ipv6
      -
        name: tcp
        type: binary
        struct: ovs-key-tcp
      -
        name: udp
        type: binary
        struct: ovs-key-udp
      -
        name: icmp
        type: binary
        struct: ovs-key-icmp
      -
        name: icmpv6
        type: binary
        struct: ovs-key-icmp
      -
        name: arp
        type: binary
        struct: ovs-key-arp
        doc: struct ovs_key_arp
      -
        name: nd
        type: binary
        struct: ovs-key-nd
        doc: struct ovs_key_nd
      -
        name: skb-mark
        type: u32
      -
        name: tunnel
        type: nest
        nested-attributes: tunnel-key-attrs
      -
        name: sctp
        type: binary
        struct: ovs-key-sctp
      -
        name: tcp-flags
        type: u16
        byte-order: big-endian
      -
        name: dp-hash
        type: u32
        doc: Value 0 indicates the hash is not computed by the datapath.
      -
        name: recirc-id
        type: u32
      -
        name: mpls
        type: binary
        struct: ovs-key-mpls
      -
        name: ct-state
        type: u32
        enum: ct-state-flags
        enum-as-flags: true
      -
        name: ct-zone
        type: u16
        doc: connection tracking zone
      -
        name: ct-mark
        type: u32
        doc: connection tracking mark
      -
        name: ct-labels
        type: binary
        display-hint: hex
        doc: 16-octet connection tracking label
      -
        name: ct-orig-tuple-ipv4
        type: binary
        struct: ovs-key-ct-tuple-ipv4
      -
        name: ct-orig-tuple-ipv6
        type: binary
        doc: struct ovs_key_ct_tuple_ipv6
      -
        name: nsh
        type: nest
        nested-attributes: ovs-nsh-key-attrs
      -
        name: packet-type
        type: u32
        byte-order: big-endian
        doc: Should not be sent to the kernel
      -
        name: nd-extensions
        type: binary
        doc: Should not be sent to the kernel
      -
        name: tunnel-info
        type: binary
        doc: struct ip_tunnel_info
      -
        name: ipv6-exthdrs
        type: binary
        struct: ovs-key-ipv6-exthdrs
        doc: struct ovs_key_ipv6_exthdr
  -
    name: action-attrs
    enum-name: ovs-action-attr
    name-prefix: ovs-action-attr-
    attributes:
      -
        name: output
        type: u32
        doc: ovs port number in datapath
      -
        name: userspace
        type: nest
        nested-attributes: userspace-attrs
      -
        name: set
        type: nest
        nested-attributes: key-attrs
        doc: Replaces the contents of an existing header. The single nested attribute specifies a header to modify and its value.
      -
        name: push-vlan
        type: binary
        struct: ovs-action-push-vlan
        doc: Push a new outermost 802.1Q or 802.1ad header onto the packet.
      -
        name: pop-vlan
        type: flag
        doc: Pop the outermost 802.1Q or 802.1ad header from the packet.
      -
        name: sample
        type: nest
        nested-attributes: sample-attrs
        doc: |
          Probabilistically executes actions, as specified in the nested attributes.
      -
        name: recirc
        type: u32
        doc: recirc id
      -
        name: hash
        type: binary
        struct: ovs-action-hash
      -
        name: push-mpls
        type: binary
        struct: ovs-action-push-mpls
        doc: |
          Push a new MPLS label stack entry onto the top of the packets MPLS
          label stack. Set the ethertype of the encapsulating frame to either
          ETH_P_MPLS_UC or ETH_P_MPLS_MC to indicate the new packet contents.
      -
        name: pop-mpls
        type: u16
        byte-order: big-endian
        doc: ethertype
      -
        name: set-masked
        type: nest
        nested-attributes: key-attrs
        doc: |
          Replaces the contents of an existing header. A nested attribute
          specifies a header to modify, its value, and a mask. For every bit set
          in the mask, the corresponding bit value is copied from the value to
          the packet header field, rest of the bits are left unchanged. The
          non-masked value bits must be passed in as zeroes. Masking is not
          supported for the OVS_KEY_ATTR_TUNNEL attribute.
      -
        name: ct
        type: nest
        nested-attributes: ct-attrs
        doc: |
          Track the connection. Populate the conntrack-related entries
          in the flow key.
      -
        name: trunc
        type: u32
        doc: struct ovs_action_trunc is a u32 max length
      -
        name: push-eth
        type: binary
        doc: struct ovs_action_push_eth
      -
        name: pop-eth
        type: flag
      -
        name: ct-clear
        type: flag
      -
        name: push-nsh
        type: nest
        nested-attributes: ovs-nsh-key-attrs
        doc: |
          Push NSH header to the packet.
      -
        name: pop-nsh
        type: flag
        doc: |
          Pop the outermost NSH header off the packet.
      -
        name: meter
        type: u32
        doc: |
          Run packet through a meter, which may drop the packet, or modify the
          packet (e.g., change the DSCP field)
      -
        name: clone
        type: nest
        nested-attributes: action-attrs
        doc: |
          Make a copy of the packet and execute a list of actions without
          affecting the original packet and key.
      -
        name: check-pkt-len
        type: nest
        nested-attributes: check-pkt-len-attrs
        doc: |
          Check the packet length and execute a set of actions if greater than
          the specified packet length, else execute another set of actions.
      -
        name: add-mpls
        type: binary
        struct: ovs-action-add-mpls
        doc: |
          Push a new MPLS label stack entry at the start of the packet or at the
          start of the l3 header depending on the value of l3 tunnel flag in the
          tun_flags field of this OVS_ACTION_ATTR_ADD_MPLS argument.
      -
        name: dec-ttl
        type: nest
        nested-attributes: dec-ttl-attrs
      -
        name: psample
        type: nest
        nested-attributes: psample-attrs
        doc: |
          Sends a packet sample to psample for external observation.
  -
    name: tunnel-key-attrs
    enum-name: ovs-tunnel-key-attr
    name-prefix: ovs-tunnel-key-attr-
    attributes:
      -
        name: id
        type: u64
        byte-order: big-endian
        value: 0
      -
        name: ipv4-src
        type: u32
        byte-order: big-endian
      -
        name: ipv4-dst
        type: u32
        byte-order: big-endian
      -
        name: tos
        type: u8
      -
        name: ttl
        type: u8
      -
        name: dont-fragment
        type: flag
      -
        name: csum
        type: flag
      -
        name: oam
        type: flag
      -
        name: geneve-opts
        type: binary
        sub-type: u32
      -
        name: tp-src
        type: u16
        byte-order: big-endian
      -
        name: tp-dst
        type: u16
        byte-order: big-endian
      -
        name: vxlan-opts
        type: nest
        nested-attributes: vxlan-ext-attrs
      -
        name: ipv6-src
        type: binary
        doc: |
          struct in6_addr source IPv6 address
      -
        name: ipv6-dst
        type: binary
        doc: |
          struct in6_addr destination IPv6 address
      -
        name: pad
        type: binary
      -
        name: erspan-opts
        type: binary
        doc: |
          struct erspan_metadata
      -
        name: ipv4-info-bridge
        type: flag
  -
    name: check-pkt-len-attrs
    enum-name: ovs-check-pkt-len-attr
    name-prefix: ovs-check-pkt-len-attr-
    attributes:
      -
        name: pkt-len
        type: u16
      -
        name: actions-if-greater
        type: nest
        nested-attributes: action-attrs
      -
        name: actions-if-less-equal
        type: nest
        nested-attributes: action-attrs
  -
    name: sample-attrs
    enum-name: ovs-sample-attr
    name-prefix: ovs-sample-attr-
    attributes:
      -
        name: probability
        type: u32
      -
        name: actions
        type: nest
        nested-attributes: action-attrs
  -
    name: userspace-attrs
    enum-name: ovs-userspace-attr
    name-prefix: ovs-userspace-attr-
    attributes:
      -
        name: pid
        type: u32
      -
        name: userdata
        type: binary
      -
        name: egress-tun-port
        type: u32
      -
        name: actions
        type: flag
  -
    name: ovs-nsh-key-attrs
    enum-name: ovs-nsh-key-attr
    name-prefix: ovs-nsh-key-attr-
    attributes:
      -
        name: base
        type: binary
      -
        name: md1
        type: binary
      -
        name: md2
        type: binary
  -
    name: ct-attrs
    enum-name: ovs-ct-attr
    name-prefix: ovs-ct-attr-
    attributes:
      -
        name: commit
        type: flag
      -
        name: zone
        type: u16
      -
        name: mark
        type: binary
      -
        name: labels
        type: binary
      -
        name: helper
        type: string
      -
        name: nat
        type: nest
        nested-attributes: nat-attrs
      -
        name: force-commit
        type: flag
      -
        name: eventmask
        type: u32
      -
        name: timeout
        type: string
  -
    name: nat-attrs
    enum-name: ovs-nat-attr
    name-prefix: ovs-nat-attr-
    attributes:
      -
        name: src
        type: flag
      -
        name: dst
        type: flag
      -
        name: ip-min
        type: binary
      -
        name: ip-max
        type: binary
      -
        name: proto-min
        type: u16
      -
        name: proto-max
        type: u16
      -
        name: persistent
        type: flag
      -
        name: proto-hash
        type: flag
      -
        name: proto-random
        type: flag
  -
    name: dec-ttl-attrs
    enum-name: ovs-dec-ttl-attr
    name-prefix: ovs-dec-ttl-attr-
    attributes:
      -
        name: action
        type: nest
        nested-attributes: action-attrs
  -
    name: vxlan-ext-attrs
    enum-name: ovs-vxlan-ext-
    name-prefix: ovs-vxlan-ext-
    attributes:
      -
        name: gbp
        type: u32
  -
    name: psample-attrs
    enum-name: ovs-psample-attr
    name-prefix: ovs-psample-attr-
    attributes:
      -
        name: group
        type: u32
      -
        name: cookie
        type: binary

operations:
  name-prefix: ovs-flow-cmd-
  fixed-header: ovs-header
  list:
    -
      name: get
      doc: Get / dump OVS flow configuration and state
      value: 3
      attribute-set: flow-attrs
      do: &flow-get-op
        request:
          attributes:
            - key
            - ufid
            - ufid-flags
        reply:
          attributes:
            - key
            - ufid
            - mask
            - stats
            - actions
      dump: *flow-get-op
    -
      name: new
      doc: Create OVS flow configuration in a data path
      value: 1
      attribute-set: flow-attrs
      do:
        request:
          attributes:
            - key
            - ufid
            - mask
            - actions

mcast-groups:
  list:
    -
      name: ovs_flow