Linux 6.7-rc7
[linux-modified.git] / Documentation / netlink / specs / ovs_flow.yaml
1 # SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
2
3 name: ovs_flow
4 version: 1
5 protocol: genetlink-legacy
6 uapi-header: linux/openvswitch.h
7
8 doc:
9   OVS flow configuration over generic netlink.
10
11 definitions:
12   -
13     name: ovs-header
14     type: struct
15     doc: |
16       Header for OVS Generic Netlink messages.
17     members:
18       -
19         name: dp-ifindex
20         type: u32
21         doc: |
22           ifindex of local port for datapath (0 to make a request not specific
23           to a datapath).
24   -
25     name: ovs-flow-stats
26     type: struct
27     members:
28       -
29         name: n-packets
30         type: u64
31         doc: Number of matched packets.
32       -
33         name: n-bytes
34         type: u64
35         doc: Number of matched bytes.
36   -
37     name: ovs-key-ethernet
38     type: struct
39     members:
40       -
41         name: eth-src
42         type: binary
43         len: 6
44         display-hint: mac
45       -
46         name: eth-dst
47         type: binary
48         len: 6
49         display-hint: mac
50   -
51     name: ovs-key-mpls
52     type: struct
53     members:
54       -
55         name: mpls-lse
56         type: u32
57         byte-order: big-endian
58   -
59     name: ovs-key-ipv4
60     type: struct
61     members:
62       -
63         name: ipv4-src
64         type: u32
65         byte-order: big-endian
66         display-hint: ipv4
67       -
68         name: ipv4-dst
69         type: u32
70         byte-order: big-endian
71         display-hint: ipv4
72       -
73         name: ipv4-proto
74         type: u8
75       -
76         name: ipv4-tos
77         type: u8
78       -
79         name: ipv4-ttl
80         type: u8
81       -
82         name: ipv4-frag
83         type: u8
84         enum: ovs-frag-type
85   -
86     name: ovs-key-ipv6
87     type: struct
88     members:
89       -
90         name: ipv6-src
91         type: binary
92         len: 16
93         byte-order: big-endian
94         display-hint: ipv6
95       -
96         name: ipv6-dst
97         type: binary
98         len: 16
99         byte-order: big-endian
100         display-hint: ipv6
101       -
102         name: ipv6-label
103         type: u32
104         byte-order: big-endian
105       -
106         name: ipv6-proto
107         type: u8
108       -
109         name: ipv6-tclass
110         type: u8
111       -
112         name: ipv6-hlimit
113         type: u8
114       -
115         name: ipv6-frag
116         type: u8
117   -
118     name: ovs-key-ipv6-exthdrs
119     type: struct
120     members:
121       -
122         name: hdrs
123         type: u16
124   -
125     name: ovs-frag-type
126     name-prefix: ovs-frag-type-
127     type: enum
128     entries:
129       -
130         name: none
131         doc: Packet is not a fragment.
132       -
133         name: first
134         doc: Packet is a fragment with offset 0.
135       -
136         name: later
137         doc: Packet is a fragment with nonzero offset.
138       -
139         name: any
140         value: 255
141   -
142     name: ovs-key-tcp
143     type: struct
144     members:
145       -
146         name: tcp-src
147         type: u16
148         byte-order: big-endian
149       -
150         name: tcp-dst
151         type: u16
152         byte-order: big-endian
153   -
154     name: ovs-key-udp
155     type: struct
156     members:
157       -
158         name: udp-src
159         type: u16
160         byte-order: big-endian
161       -
162         name: udp-dst
163         type: u16
164         byte-order: big-endian
165   -
166     name: ovs-key-sctp
167     type: struct
168     members:
169       -
170         name: sctp-src
171         type: u16
172         byte-order: big-endian
173       -
174         name: sctp-dst
175         type: u16
176         byte-order: big-endian
177   -
178     name: ovs-key-icmp
179     type: struct
180     members:
181       -
182         name: icmp-type
183         type: u8
184       -
185         name: icmp-code
186         type: u8
187   -
188     name: ovs-key-arp
189     type: struct
190     members:
191       -
192         name: arp-sip
193         type: u32
194         byte-order: big-endian
195       -
196         name: arp-tip
197         type: u32
198         byte-order: big-endian
199       -
200         name: arp-op
201         type: u16
202         byte-order: big-endian
203       -
204         name: arp-sha
205         type: binary
206         len: 6
207         display-hint: mac
208       -
209         name: arp-tha
210         type: binary
211         len: 6
212         display-hint: mac
213   -
214     name: ovs-key-nd
215     type: struct
216     members:
217       -
218         name: nd_target
219         type: binary
220         len: 16
221         byte-order: big-endian
222       -
223         name: nd-sll
224         type: binary
225         len: 6
226         display-hint: mac
227       -
228         name: nd-tll
229         type: binary
230         len: 6
231         display-hint: mac
232   -
233     name: ovs-key-ct-tuple-ipv4
234     type: struct
235     members:
236       -
237         name: ipv4-src
238         type: u32
239         byte-order: big-endian
240       -
241         name: ipv4-dst
242         type: u32
243         byte-order: big-endian
244       -
245         name: src-port
246         type: u16
247         byte-order: big-endian
248       -
249         name: dst-port
250         type: u16
251         byte-order: big-endian
252       -
253         name: ipv4-proto
254         type: u8
255   -
256     name: ovs-action-push-vlan
257     type: struct
258     members:
259       -
260         name: vlan_tpid
261         type: u16
262         byte-order: big-endian
263         doc: Tag protocol identifier (TPID) to push.
264       -
265         name: vlan_tci
266         type: u16
267         byte-order: big-endian
268         doc: Tag control identifier (TCI) to push.
269   -
270     name: ovs-ufid-flags
271     name-prefix: ovs-ufid-f-
272     type: flags
273     entries:
274       - omit-key
275       - omit-mask
276       - omit-actions
277   -
278     name: ovs-action-hash
279     type: struct
280     members:
281       -
282         name: hash-alg
283         type: u32
284         doc: Algorithm used to compute hash prior to recirculation.
285       -
286         name: hash-basis
287         type: u32
288         doc: Basis used for computing hash.
289   -
290     name: ovs-hash-alg
291     type: enum
292     doc: |
293       Data path hash algorithm for computing Datapath hash. The algorithm type only specifies
294       the fields in a flow will be used as part of the hash. Each datapath is free to use its
295       own hash algorithm. The hash value will be opaque to the user space daemon.
296     entries:
297       - ovs-hash-alg-l4
298
299   -
300     name: ovs-action-push-mpls
301     type: struct
302     members:
303       -
304         name: mpls-lse
305         type: u32
306         byte-order: big-endian
307         doc: |
308           MPLS label stack entry to push
309       -
310         name: mpls-ethertype
311         type: u32
312         byte-order: big-endian
313         doc: |
314           Ethertype to set in the encapsulating ethernet frame.  The only values
315           ethertype should ever be given are ETH_P_MPLS_UC and ETH_P_MPLS_MC,
316           indicating MPLS unicast or multicast. Other are rejected.
317   -
318     name: ovs-action-add-mpls
319     type: struct
320     members:
321       -
322         name: mpls-lse
323         type: u32
324         byte-order: big-endian
325         doc: |
326           MPLS label stack entry to push
327       -
328         name: mpls-ethertype
329         type: u32
330         byte-order: big-endian
331         doc: |
332           Ethertype to set in the encapsulating ethernet frame.  The only values
333           ethertype should ever be given are ETH_P_MPLS_UC and ETH_P_MPLS_MC,
334           indicating MPLS unicast or multicast. Other are rejected.
335       -
336         name: tun-flags
337         type: u16
338         doc: |
339           MPLS tunnel attributes.
340   -
341     name: ct-state-flags
342     type: flags
343     name-prefix: ovs-cs-f-
344     entries:
345       -
346         name: new
347         doc: Beginning of a new connection.
348       -
349         name: established
350         doc: Part of an existing connenction
351       -
352         name: related
353         doc: Related to an existing connection.
354       -
355         name: reply-dir
356         doc: Flow is in the reply direction.
357       -
358         name: invalid
359         doc: Could not track the connection.
360       -
361         name: tracked
362         doc: Conntrack has occurred.
363       -
364         name: src-nat
365         doc: Packet's source address/port was mangled by NAT.
366       -
367         name: dst-nat
368         doc: Packet's destination address/port was mangled by NAT.
369
370 attribute-sets:
371   -
372     name: flow-attrs
373     enum-name: ovs-flow-attr
374     name-prefix: ovs-flow-attr-
375     attributes:
376       -
377         name: key
378         type: nest
379         nested-attributes: key-attrs
380         doc: |
381           Nested attributes specifying the flow key. Always present in
382           notifications. Required for all requests (except dumps).
383       -
384         name: actions
385         type: nest
386         nested-attributes: action-attrs
387         doc: |
388           Nested attributes specifying the actions to take for packets that
389           match the key. Always present in notifications. Required for
390           OVS_FLOW_CMD_NEW requests, optional for OVS_FLOW_CMD_SET requests.  An
391           OVS_FLOW_CMD_SET without OVS_FLOW_ATTR_ACTIONS will not modify the
392           actions.  To clear the actions, an OVS_FLOW_ATTR_ACTIONS without any
393           nested attributes must be given.
394       -
395         name: stats
396         type: binary
397         struct: ovs-flow-stats
398         doc: |
399           Statistics for this flow. Present in notifications if the stats would
400           be nonzero. Ignored in requests.
401       -
402         name: tcp-flags
403         type: u8
404         doc: |
405           An 8-bit value giving the ORed value of all of the TCP flags seen on
406           packets in this flow. Only present in notifications for TCP flows, and
407           only if it would be nonzero. Ignored in requests.
408       -
409         name: used
410         type: u64
411         doc: |
412           A 64-bit integer giving the time, in milliseconds on the system
413           monotonic clock, at which a packet was last processed for this
414           flow. Only present in notifications if a packet has been processed for
415           this flow. Ignored in requests.
416       -
417         name: clear
418         type: flag
419         doc: |
420           If present in a OVS_FLOW_CMD_SET request, clears the last-used time,
421           accumulated TCP flags, and statistics for this flow.  Otherwise
422           ignored in requests. Never present in notifications.
423       -
424         name: mask
425         type: nest
426         nested-attributes: key-attrs
427         doc: |
428           Nested attributes specifying the mask bits for wildcarded flow
429           match. Mask bit value '1' specifies exact match with corresponding
430           flow key bit, while mask bit value '0' specifies a wildcarded
431           match. Omitting attribute is treated as wildcarding all corresponding
432           fields. Optional for all requests. If not present, all flow key bits
433           are exact match bits.
434       -
435         name: probe
436         type: binary
437         doc: |
438           Flow operation is a feature probe, error logging should be suppressed.
439       -
440         name: ufid
441         type: binary
442         doc: |
443           A value between 1-16 octets specifying a unique identifier for the
444           flow. Causes the flow to be indexed by this value rather than the
445           value of the OVS_FLOW_ATTR_KEY attribute. Optional for all
446           requests. Present in notifications if the flow was created with this
447           attribute.
448         display-hint: uuid
449       -
450         name: ufid-flags
451         type: u32
452         enum: ovs-ufid-flags
453         doc: |
454           A 32-bit value of ORed flags that provide alternative semantics for
455           flow installation and retrieval. Optional for all requests.
456       -
457         name: pad
458         type: binary
459
460   -
461     name: key-attrs
462     enum-name: ovs-key-attr
463     name-prefix: ovs-key-attr-
464     attributes:
465       -
466         name: encap
467         type: nest
468         nested-attributes: key-attrs
469       -
470         name: priority
471         type: u32
472       -
473         name: in-port
474         type: u32
475       -
476         name: ethernet
477         type: binary
478         struct: ovs-key-ethernet
479         doc: struct ovs_key_ethernet
480       -
481         name: vlan
482         type: u16
483         byte-order: big-endian
484       -
485         name: ethertype
486         type: u16
487         byte-order: big-endian
488       -
489         name: ipv4
490         type: binary
491         struct: ovs-key-ipv4
492       -
493         name: ipv6
494         type: binary
495         struct: ovs-key-ipv6
496         doc: struct ovs_key_ipv6
497       -
498         name: tcp
499         type: binary
500         struct: ovs-key-tcp
501       -
502         name: udp
503         type: binary
504         struct: ovs-key-udp
505       -
506         name: icmp
507         type: binary
508         struct: ovs-key-icmp
509       -
510         name: icmpv6
511         type: binary
512         struct: ovs-key-icmp
513       -
514         name: arp
515         type: binary
516         struct: ovs-key-arp
517         doc: struct ovs_key_arp
518       -
519         name: nd
520         type: binary
521         struct: ovs-key-nd
522         doc: struct ovs_key_nd
523       -
524         name: skb-mark
525         type: u32
526       -
527         name: tunnel
528         type: nest
529         nested-attributes: tunnel-key-attrs
530       -
531         name: sctp
532         type: binary
533         struct: ovs-key-sctp
534       -
535         name: tcp-flags
536         type: u16
537         byte-order: big-endian
538       -
539         name: dp-hash
540         type: u32
541         doc: Value 0 indicates the hash is not computed by the datapath.
542       -
543         name: recirc-id
544         type: u32
545       -
546         name: mpls
547         type: binary
548         struct: ovs-key-mpls
549       -
550         name: ct-state
551         type: u32
552         enum: ct-state-flags
553         enum-as-flags: true
554       -
555         name: ct-zone
556         type: u16
557         doc: connection tracking zone
558       -
559         name: ct-mark
560         type: u32
561         doc: connection tracking mark
562       -
563         name: ct-labels
564         type: binary
565         display-hint: hex
566         doc: 16-octet connection tracking label
567       -
568         name: ct-orig-tuple-ipv4
569         type: binary
570         struct: ovs-key-ct-tuple-ipv4
571       -
572         name: ct-orig-tuple-ipv6
573         type: binary
574         doc: struct ovs_key_ct_tuple_ipv6
575       -
576         name: nsh
577         type: nest
578         nested-attributes: ovs-nsh-key-attrs
579       -
580         name: packet-type
581         type: u32
582         byte-order: big-endian
583         doc: Should not be sent to the kernel
584       -
585         name: nd-extensions
586         type: binary
587         doc: Should not be sent to the kernel
588       -
589         name: tunnel-info
590         type: binary
591         doc: struct ip_tunnel_info
592       -
593         name: ipv6-exthdrs
594         type: binary
595         struct: ovs-key-ipv6-exthdrs
596         doc: struct ovs_key_ipv6_exthdr
597   -
598     name: action-attrs
599     enum-name: ovs-action-attr
600     name-prefix: ovs-action-attr-
601     attributes:
602       -
603         name: output
604         type: u32
605         doc: ovs port number in datapath
606       -
607         name: userspace
608         type: nest
609         nested-attributes: userspace-attrs
610       -
611         name: set
612         type: nest
613         nested-attributes: key-attrs
614         doc: Replaces the contents of an existing header. The single nested attribute specifies a header to modify and its value.
615       -
616         name: push-vlan
617         type: binary
618         struct: ovs-action-push-vlan
619         doc: Push a new outermost 802.1Q or 802.1ad header onto the packet.
620       -
621         name: pop-vlan
622         type: flag
623         doc: Pop the outermost 802.1Q or 802.1ad header from the packet.
624       -
625         name: sample
626         type: nest
627         nested-attributes: sample-attrs
628         doc: |
629           Probabilistically executes actions, as specified in the nested attributes.
630       -
631         name: recirc
632         type: u32
633         doc: recirc id
634       -
635         name: hash
636         type: binary
637         struct: ovs-action-hash
638       -
639         name: push-mpls
640         type: binary
641         struct: ovs-action-push-mpls
642         doc: |
643           Push a new MPLS label stack entry onto the top of the packets MPLS
644           label stack. Set the ethertype of the encapsulating frame to either
645           ETH_P_MPLS_UC or ETH_P_MPLS_MC to indicate the new packet contents.
646       -
647         name: pop-mpls
648         type: u16
649         byte-order: big-endian
650         doc: ethertype
651       -
652         name: set-masked
653         type: nest
654         nested-attributes: key-attrs
655         doc: |
656           Replaces the contents of an existing header. A nested attribute
657           specifies a header to modify, its value, and a mask. For every bit set
658           in the mask, the corresponding bit value is copied from the value to
659           the packet header field, rest of the bits are left unchanged. The
660           non-masked value bits must be passed in as zeroes. Masking is not
661           supported for the OVS_KEY_ATTR_TUNNEL attribute.
662       -
663         name: ct
664         type: nest
665         nested-attributes: ct-attrs
666         doc: |
667           Track the connection. Populate the conntrack-related entries
668           in the flow key.
669       -
670         name: trunc
671         type: u32
672         doc: struct ovs_action_trunc is a u32 max length
673       -
674         name: push-eth
675         type: binary
676         doc: struct ovs_action_push_eth
677       -
678         name: pop-eth
679         type: flag
680       -
681         name: ct-clear
682         type: flag
683       -
684         name: push-nsh
685         type: nest
686         nested-attributes: ovs-nsh-key-attrs
687         doc: |
688           Push NSH header to the packet.
689       -
690         name: pop-nsh
691         type: flag
692         doc: |
693           Pop the outermost NSH header off the packet.
694       -
695         name: meter
696         type: u32
697         doc: |
698           Run packet through a meter, which may drop the packet, or modify the
699           packet (e.g., change the DSCP field)
700       -
701         name: clone
702         type: nest
703         nested-attributes: action-attrs
704         doc: |
705           Make a copy of the packet and execute a list of actions without
706           affecting the original packet and key.
707       -
708         name: check-pkt-len
709         type: nest
710         nested-attributes: check-pkt-len-attrs
711         doc: |
712           Check the packet length and execute a set of actions if greater than
713           the specified packet length, else execute another set of actions.
714       -
715         name: add-mpls
716         type: binary
717         struct: ovs-action-add-mpls
718         doc: |
719           Push a new MPLS label stack entry at the start of the packet or at the
720           start of the l3 header depending on the value of l3 tunnel flag in the
721           tun_flags field of this OVS_ACTION_ATTR_ADD_MPLS argument.
722       -
723         name: dec-ttl
724         type: nest
725         nested-attributes: dec-ttl-attrs
726   -
727     name: tunnel-key-attrs
728     enum-name: ovs-tunnel-key-attr
729     name-prefix: ovs-tunnel-key-attr-
730     attributes:
731       -
732         name: id
733         type: u64
734         byte-order: big-endian
735         value: 0
736       -
737         name: ipv4-src
738         type: u32
739         byte-order: big-endian
740       -
741         name: ipv4-dst
742         type: u32
743         byte-order: big-endian
744       -
745         name: tos
746         type: u8
747       -
748         name: ttl
749         type: u8
750       -
751         name: dont-fragment
752         type: flag
753       -
754         name: csum
755         type: flag
756       -
757         name: oam
758         type: flag
759       -
760         name: geneve-opts
761         type: binary
762         sub-type: u32
763       -
764         name: tp-src
765         type: u16
766         byte-order: big-endian
767       -
768         name: tp-dst
769         type: u16
770         byte-order: big-endian
771       -
772         name: vxlan-opts
773         type: nest
774         nested-attributes: vxlan-ext-attrs
775       -
776         name: ipv6-src
777         type: binary
778         doc: |
779           struct in6_addr source IPv6 address
780       -
781         name: ipv6-dst
782         type: binary
783         doc: |
784           struct in6_addr destination IPv6 address
785       -
786         name: pad
787         type: binary
788       -
789         name: erspan-opts
790         type: binary
791         doc: |
792           struct erspan_metadata
793       -
794         name: ipv4-info-bridge
795         type: flag
796   -
797     name: check-pkt-len-attrs
798     enum-name: ovs-check-pkt-len-attr
799     name-prefix: ovs-check-pkt-len-attr-
800     attributes:
801       -
802         name: pkt-len
803         type: u16
804       -
805         name: actions-if-greater
806         type: nest
807         nested-attributes: action-attrs
808       -
809         name: actions-if-less-equal
810         type: nest
811         nested-attributes: action-attrs
812   -
813     name: sample-attrs
814     enum-name: ovs-sample-attr
815     name-prefix: ovs-sample-attr-
816     attributes:
817       -
818         name: probability
819         type: u32
820       -
821         name: actions
822         type: nest
823         nested-attributes: action-attrs
824   -
825     name: userspace-attrs
826     enum-name: ovs-userspace-attr
827     name-prefix: ovs-userspace-attr-
828     attributes:
829       -
830         name: pid
831         type: u32
832       -
833         name: userdata
834         type: binary
835       -
836         name: egress-tun-port
837         type: u32
838       -
839         name: actions
840         type: flag
841   -
842     name: ovs-nsh-key-attrs
843     enum-name: ovs-nsh-key-attr
844     name-prefix: ovs-nsh-key-attr-
845     attributes:
846       -
847         name: base
848         type: binary
849       -
850         name: md1
851         type: binary
852       -
853         name: md2
854         type: binary
855   -
856     name: ct-attrs
857     enum-name: ovs-ct-attr
858     name-prefix: ovs-ct-attr-
859     attributes:
860       -
861         name: commit
862         type: flag
863       -
864         name: zone
865         type: u16
866       -
867         name: mark
868         type: binary
869       -
870         name: labels
871         type: binary
872       -
873         name: helper
874         type: string
875       -
876         name: nat
877         type: nest
878         nested-attributes: nat-attrs
879       -
880         name: force-commit
881         type: flag
882       -
883         name: eventmask
884         type: u32
885       -
886         name: timeout
887         type: string
888   -
889     name: nat-attrs
890     enum-name: ovs-nat-attr
891     name-prefix: ovs-nat-attr-
892     attributes:
893       -
894         name: src
895         type: flag
896       -
897         name: dst
898         type: flag
899       -
900         name: ip-min
901         type: binary
902       -
903         name: ip-max
904         type: binary
905       -
906         name: proto-min
907         type: u16
908       -
909         name: proto-max
910         type: u16
911       -
912         name: persistent
913         type: flag
914       -
915         name: proto-hash
916         type: flag
917       -
918         name: proto-random
919         type: flag
920   -
921     name: dec-ttl-attrs
922     enum-name: ovs-dec-ttl-attr
923     name-prefix: ovs-dec-ttl-attr-
924     attributes:
925       -
926         name: action
927         type: nest
928         nested-attributes: action-attrs
929   -
930     name: vxlan-ext-attrs
931     enum-name: ovs-vxlan-ext-
932     name-prefix: ovs-vxlan-ext-
933     attributes:
934       -
935         name: gbp
936         type: u32
937
938 operations:
939   name-prefix: ovs-flow-cmd-
940   fixed-header: ovs-header
941   list:
942     -
943       name: get
944       doc: Get / dump OVS flow configuration and state
945       value: 3
946       attribute-set: flow-attrs
947       do: &flow-get-op
948         request:
949           attributes:
950             - dp-ifindex
951             - key
952             - ufid
953             - ufid-flags
954         reply:
955           attributes:
956             - dp-ifindex
957             - key
958             - ufid
959             - mask
960             - stats
961             - actions
962       dump: *flow-get-op
963     -
964       name: new
965       doc: Create OVS flow configuration in a data path
966       value: 1
967       attribute-set: flow-attrs
968       do:
969         request:
970           attributes:
971             - dp-ifindex
972             - key
973             - ufid
974             - mask
975             - actions
976
977 mcast-groups:
978   list:
979     -
980       name: ovs_flow