path: root/Documentation/netlink/specs/rt-route.yaml

# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
---
name: rt-route
protocol: netlink-raw
uapi-header: linux/rtnetlink.h
protonum: 0

doc: >-
  Route configuration over rtnetlink.

definitions:
  -
    name: rtm-type
    name-prefix: rtn-
    enum-name:
    type: enum
    entries:
      - unspec
      - unicast
      - local
      - broadcast
      - anycast
      - multicast
      - blackhole
      - unreachable
      - prohibit
      - throw
      - nat
      - xresolve
  -
    name: rtmsg
    type: struct
    members:
      -
        name: rtm-family
        type: u8
      -
        name: rtm-dst-len
        type: u8
      -
        name: rtm-src-len
        type: u8
      -
        name: rtm-tos
        type: u8
      -
        name: rtm-table
        type: u8
      -
        name: rtm-protocol
        type: u8
      -
        name: rtm-scope
        type: u8
      -
        name: rtm-type
        type: u8
        enum: rtm-type
      -
        name: rtm-flags
        type: u32
  -
    name: rta-cacheinfo
    type: struct
    members:
      -
        name: rta-clntref
        type: u32
      -
        name: rta-lastuse
        type: u32
      -
        name: rta-expires
        type: u32
      -
        name: rta-error
        type: u32
      -
        name: rta-used
        type: u32
  -
    name: del-reason
    type: enum
    name-prefix: rt-del-reason-
    enum-name: rt-del-reason
    doc: |
      Why the kernel deleted a route. New causes may be appended. The
      value space is family-agnostic, a value is never reinterpreted
      per address family.
    entries:
      -
        name: unspec
        doc: The deletion path does not record a cause.
      -
        name: expired
        doc: The RTF_EXPIRES lifetime ran out and the route was garbage
          collected.
      -
        name: ra-withdrawn
        doc: A Router Advertisement withdrew the route with a zero
          lifetime.
  -
    name: encap-type
    type: enum
    name-prefix: lwtunnel-encap-
    enum-name:
    entries:
      - none
      - mpls
      - ip
      - ila
      - ip6
      - seg6
      - bpf
      - seg6-local
      - rpl
      - ioam6
      - xfrm
  -
    name: seg6-local-actions
    type: enum
    name-prefix: seg6-local-action-
    enum-name:
    entries:
      - unspec
      - end
      - end-x
      - end-t
      - end-dx2
      - end-dx6
      - end-dx4
      - end-dt6
      - end-dt4
      - end-b6
      - end-b6-encap
      - end-bm
      - end-s
      - end-as
      - end-am
      - end-bpf
      - end-dt46
  -
    name: seg6-local-flv-ops
    type: enum
    name-prefix: seg6-local-flv-op-
    enum-name:
    entries:
      -
        name: unspec
      -
        name: psp
      -
        name: usp
      -
        name: usd
      -
        name: next-csid

sub-messages:
  -
    name: encap-data
    formats:
      -
        value: mpls
        attribute-set: mpls-iptunnel
      -
        value: ip
        attribute-set: lwtunnel-ip
      -
        value: ila
        attribute-set: ila-attrs
      -
        value: ip6
        attribute-set: lwtunnel-ip6
      -
        value: seg6
        attribute-set: seg6-iptunnel
      -
        value: bpf
        attribute-set: lwt-bpf
      -
        value: seg6-local
        attribute-set: seg6-local
      -
        value: rpl
        attribute-set: rpl-iptunnel
      -
        value: ioam6
        attribute-set: ioam6-iptunnel
      -
        value: xfrm
        attribute-set: lwt-xfrm

attribute-sets:
  -
    name: route-attrs
    name-prefix: rta-
    attributes:
      -
        name: dst
        type: binary
        display-hint: ipv4-or-v6
      -
        name: src
        type: binary
        display-hint: ipv4-or-v6
      -
        name: iif
        type: u32
      -
        name: oif
        type: u32
      -
        name: gateway
        type: binary
        display-hint: ipv4-or-v6
      -
        name: priority
        type: u32
      -
        name: prefsrc
        type: binary
        display-hint: ipv4-or-v6
      -
        name: metrics
        type: nest
        nested-attributes: metrics
      -
        name: multipath
        type: binary
      -
        name: protoinfo  # not used
        type: binary
      -
        name: flow
        type: u32
      -
        name: cacheinfo
        type: binary
        struct: rta-cacheinfo
      -
        name: session  # not used
        type: binary
      -
        name: mp-algo  # not used
        type: binary
      -
        name: table
        type: u32
      -
        name: mark
        type: u32
      -
        name: mfc-stats
        type: binary
      -
        name: via
        type: binary
      -
        name: newdst
        type: binary
      -
        name: pref
        type: u8
      -
        name: encap-type
        type: u16
        enum: encap-type
      -
        name: encap
        type: sub-message
        sub-message: encap-data
        selector: encap-type
      -
        name: expires
        type: u32
      -
        name: pad
        type: binary
      -
        name: uid
        type: u32
      -
        name: ttl-propagate
        type: u8
      -
        name: ip-proto
        type: u8
      -
        name: sport
        type: u16
      -
        name: dport
        type: u16
      -
        name: nh-id
        type: u32
      -
        name: flowlabel
        type: u32
        byte-order: big-endian
        display-hint: hex
      -
        name: del-reason
        type: u32
        enum: del-reason
        doc: |
          Emitted only on RTM_DELROUTE notifications, and only when the
          deletion path records a cause. An absent attribute means
          either an older kernel or a deletion path that does not
          record its cause, consumers must treat absent and unspec
          identically. Currently only IPv6 deletion paths record a
          cause. The attribute is notification-only, the kernel rejects
          it in requests.
  -
    name: metrics
    name-prefix: rtax-
    attributes:
      -
        name: unspec
        type: unused
        value: 0
      -
        name: lock
        type: u32
      -
        name: mtu
        type: u32
      -
        name: window
        type: u32
      -
        name: rtt
        type: u32
      -
        name: rttvar
        type: u32
      -
        name: ssthresh
        type: u32
      -
        name: cwnd
        type: u32
      -
        name: advmss
        type: u32
      -
        name: reordering
        type: u32
      -
        name: hoplimit
        type: u32
      -
        name: initcwnd
        type: u32
      -
        name: features
        type: u32
      -
        name: rto-min
        type: u32
      -
        name: initrwnd
        type: u32
      -
        name: quickack
        type: u32
      -
        name: cc-algo
        type: string
      -
        name: fastopen-no-cookie
        type: u32
  -
    name: mpls-iptunnel
    name-prefix: mpls-iptunnel-
    header: linux/mpls_iptunnel.h
    attributes:
      -
        name: dst
        type: binary
      -
        name: ttl
        type: u8
  -
    name: lwtunnel-ip
    name-prefix: lwtunnel-ip-
    header: linux/lwtunnel.h
    attributes:
      -
        name: id
        type: u64
        byte-order: big-endian
      -
        name: dst
        type: u32
        byte-order: big-endian
        display-hint: ipv4
      -
        name: src
        type: u32
        byte-order: big-endian
        display-hint: ipv4
      -
        name: ttl
        type: u8
      -
        name: tos
        type: u8
      -
        name: flags
        type: u16
        byte-order: big-endian
      -
        name: pad
        type: pad
      -
        name: opts
        type: nest
        nested-attributes: lwtunnel-ip-opts
  -
    name: ila-attrs
    name-prefix: ila-attr-
    header: linux/ila.h
    attributes:
      -
        name: locator
        type: u64
        byte-order: big-endian
      -
        name: identifier
        type: u64
      -
        name: locator-match
        type: u64
        byte-order: big-endian
      -
        name: ifindex
        type: s32
      -
        name: dir
        type: u32
      -
        name: pad
        type: pad
      -
        name: csum-mode
        type: u8
      -
        name: ident-type
        type: u8
      -
        name: hook-type
        type: u8
  -
    name: lwtunnel-ip6
    name-prefix: lwtunnel-ip6-
    header: linux/lwtunnel.h
    attributes:
      -
        name: id
        type: u64
        byte-order: big-endian
      -
        name: dst
        type: binary
        display-hint: ipv6
      -
        name: src
        type: binary
        display-hint: ipv6
      -
        name: hoplimit
        type: u8
      -
        name: tc
        type: u8
      -
        name: flags
        type: u16
        byte-order: big-endian
      -
        name: pad
        type: pad
      -
        name: opts
        type: nest
        nested-attributes: lwtunnel-ip-opts
  -
    name: seg6-iptunnel
    name-prefix: seg6-iptunnel-
    header: linux/seg6_iptunnel.h
    attributes:
      -
        name: srh
        type: binary
      -
        name: src
        type: binary
        display-hint: ipv6
      -
        name: table
        type: u32
  -
    name: lwt-bpf
    name-prefix: lwt-bpf-
    header: linux/lwtunnel.h
    attributes:
      -
        name: in
        type: nest
        nested-attributes: lwt-bpf-prog
      -
        name: out
        type: nest
        nested-attributes: lwt-bpf-prog
      -
        name: xmit
        type: nest
        nested-attributes: lwt-bpf-prog
      -
        name: xmit-headroom
        type: u32
  -
    name: seg6-local
    name-prefix: seg6-local-
    header: linux/seg6_local.h
    attributes:
      -
        name: action
        type: u32
        enum: seg6-local-actions
      -
        name: srh
        type: binary
      -
        name: table
        type: u32
      -
        name: nh4
        type: u32
        byte-order: big-endian
        display-hint: ipv4
      -
        name: nh6
        type: binary
        display-hint: ipv6
      -
        name: iif
        type: u32
      -
        name: oif
        type: u32
      -
        name: bpf
        type: nest
        nested-attributes: seg6-local-bpf
      -
        name: vrftable
        type: u32
      -
        name: counters
        type: nest
        nested-attributes: seg6-local-cnt
      -
        name: flavors
        type: nest
        nested-attributes: seg6-local-flv
  -
    name: rpl-iptunnel
    name-prefix: rpl-iptunnel-
    header: linux/rpl_iptunnel.h
    attributes:
      -
        name: srh
        type: binary
  -
    name: ioam6-iptunnel
    name-prefix: ioam6-iptunnel-
    header: linux/ioam6_iptunnel.h
    attributes:
      -
        name: mode
        type: u8
      -
        name: dst
        type: binary
        display-hint: ipv6
      -
        name: trace
        type: binary
      -
        name: freq-k
        type: u32
      -
        name: freq-n
        type: u32
      -
        name: src
        type: binary
        display-hint: ipv6
  -
    name: lwt-xfrm
    name-prefix: lwt-xfrm-
    header: linux/lwtunnel.h
    attributes:
      -
        name: if-id
        type: u32
      -
        name: link
        type: u32
  -
    name: lwtunnel-ip-opts
    name-prefix: lwtunnel-ip-opts-
    attributes:
      -
        name: geneve
        type: binary
      -
        name: vxlan
        type: nest
        nested-attributes: lwtunnel-ip-opt-vxlan
      -
        name: erspan
        type: nest
        nested-attributes: lwtunnel-ip-opt-erspan
  -
    name: lwtunnel-ip-opt-vxlan
    name-prefix: lwtunnel-ip-opt-vxlan-
    attributes:
      -
        name: gbp
        type: u32
  -
    name: lwtunnel-ip-opt-erspan
    name-prefix: lwtunnel-ip-opt-erspan-
    attributes:
      -
        name: ver
        type: u8
      -
        name: index
        type: u32
        byte-order: big-endian
      -
        name: dir
        type: u8
      -
        name: hwid
        type: u8
  -
    name: lwt-bpf-prog
    name-prefix: lwt-bpf-prog-
    attributes:
      -
        name: fd
        type: u32
      -
        name: name
        type: string
        checks:
          max-len: 256
  -
    name: seg6-local-bpf
    name-prefix: seg6-local-bpf-
    attr-max-name: seg6-local-bpf-prog-max
    attributes:
      -
        name: prog
        type: u32
      -
        name: prog-name
        type: string
        checks:
          max-len: 256
  -
    name: seg6-local-cnt
    name-prefix: seg6-local-cnt-
    attributes:
      -
        name: pad
        type: pad
      -
        name: packets
        type: u64
      -
        name: bytes
        type: u64
      -
        name: errors
        type: u64
  -
    name: seg6-local-flv
    name-prefix: seg6-local-flv-
    attributes:
      -
        name: operation
        type: u32
        enum: seg6-local-flv-ops
        enum-as-flags: true
      -
        name: lcblock-bits
        type: u8
      -
        name: lcnode-fn-bits
        type: u8

operations:
  enum-model: directional
  fixed-header: rtmsg
  name-prefix: rtm-
  list:
    -
      name: getroute
      doc: Dump route information.
      attribute-set: route-attrs
      do:
        request:
          value: 26
          attributes:
            - src
            - dst
            - iif
            - oif
            - ip-proto
            - sport
            - dport
            - mark
            - uid
            - flowlabel
        reply:
          value: 24
          attributes: &all-route-attrs
            - dst
            - src
            - iif
            - oif
            - gateway
            - priority
            - prefsrc
            - metrics
            - multipath
            - flow
            - cacheinfo
            - table
            - mark
            - mfc-stats
            - via
            - newdst
            - pref
            - encap-type
            - encap
            - expires
            - pad
            - uid
            - ttl-propagate
            - ip-proto
            - sport
            - dport
            - nh-id
            - flowlabel
            - del-reason
      dump:
        request:
          value: 26
          attributes: []
        reply:
          value: 24
          attributes: *all-route-attrs
    -
      name: newroute
      doc: Create a new route
      attribute-set: route-attrs
      do:
        request:
          value: 24
          attributes: &route-req-attrs
            - dst
            - src
            - iif
            - oif
            - gateway
            - priority
            - prefsrc
            - metrics
            - multipath
            - flow
            - cacheinfo
            - table
            - mark
            - mfc-stats
            - via
            - newdst
            - pref
            - encap-type
            - encap
            - expires
            - pad
            - uid
            - ttl-propagate
            - ip-proto
            - sport
            - dport
            - nh-id
            - flowlabel
    -
      name: delroute
      doc: Delete an existing route
      attribute-set: route-attrs
      do:
        request:
          value: 25
          attributes: *route-req-attrs
    -
      name: newroute-ntf
      doc: Notification about a created route.
      value: 24
      notify: getroute
    -
      name: delroute-ntf
      doc: Notification about a deleted route.
      value: 25
      notify: getroute

mcast-groups:
  list:
    -
      name: rtnlgrp-ipv4-route
      value: 7
    -
      name: rtnlgrp-ipv6-route
      value: 11