linux/Documentation/netlink/specs/ovs_flow.yaml
Adrian Moreno aae0b82b46 net: openvswitch: add psample action
Add support for a new action: psample.

This action accepts a u32 group id and a variable-length cookie and uses
the psample multicast group to make the packet available for
observability.

The maximum length of the user-defined cookie is set to 16, same as
tc_cookie, to discourage using cookies that will not be offloadable.

Reviewed-by: Michal Kubiak <michal.kubiak@intel.com>
Reviewed-by: Aaron Conole <aconole@redhat.com>
Reviewed-by: Ilya Maximets <i.maximets@ovn.org>
Acked-by: Eelco Chaudron <echaudro@redhat.com>
Signed-off-by: Adrian Moreno <amorenoz@redhat.com>
Link: https://patch.msgid.link/20240704085710.353845-6-amorenoz@redhat.com
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
2024-07-05 17:45:47 -07:00

999 lines
23 KiB
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