^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) Operational States
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) 1. Introduction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) ===============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) Linux distinguishes between administrative and operational state of an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) interface. Administrative state is the result of "ip link set dev
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) <dev> up or down" and reflects whether the administrator wants to use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) the device for traffic.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) However, an interface is not usable just because the admin enabled it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) - ethernet requires to be plugged into the switch and, depending on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) a site's networking policy and configuration, an 802.1X authentication
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) to be performed before user data can be transferred. Operational state
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) shows the ability of an interface to transmit this user data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) Thanks to 802.1X, userspace must be granted the possibility to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) influence operational state. To accommodate this, operational state is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) split into two parts: Two flags that can be set by the driver only, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) a RFC2863 compatible state that is derived from these flags, a policy,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) and changeable from userspace under certain rules.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) 2. Querying from userspace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) ==========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) Both admin and operational state can be queried via the netlink
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) operation RTM_GETLINK. It is also possible to subscribe to RTNLGRP_LINK
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) to be notified of updates while the interface is admin up. This is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) important for setting from userspace.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) These values contain interface state:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) ifinfomsg::if_flags & IFF_UP:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) Interface is admin up
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) ifinfomsg::if_flags & IFF_RUNNING:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) Interface is in RFC2863 operational state UP or UNKNOWN. This is for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) backward compatibility, routing daemons, dhcp clients can use this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) flag to determine whether they should use the interface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) ifinfomsg::if_flags & IFF_LOWER_UP:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) Driver has signaled netif_carrier_on()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) ifinfomsg::if_flags & IFF_DORMANT:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) Driver has signaled netif_dormant_on()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) TLV IFLA_OPERSTATE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) ------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) contains RFC2863 state of the interface in numeric representation:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) IF_OPER_UNKNOWN (0):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) Interface is in unknown state, neither driver nor userspace has set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) operational state. Interface must be considered for user data as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) setting operational state has not been implemented in every driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) IF_OPER_NOTPRESENT (1):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) Unused in current kernel (notpresent interfaces normally disappear),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) just a numerical placeholder.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) IF_OPER_DOWN (2):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) Interface is unable to transfer data on L1, f.e. ethernet is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) plugged or interface is ADMIN down.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) IF_OPER_LOWERLAYERDOWN (3):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) Interfaces stacked on an interface that is IF_OPER_DOWN show this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) state (f.e. VLAN).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) IF_OPER_TESTING (4):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) Unused in current kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) IF_OPER_DORMANT (5):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) Interface is L1 up, but waiting for an external event, f.e. for a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) protocol to establish. (802.1X)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) IF_OPER_UP (6):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) Interface is operational up and can be used.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) This TLV can also be queried via sysfs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) TLV IFLA_LINKMODE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) -----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) contains link policy. This is needed for userspace interaction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) described below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) This TLV can also be queried via sysfs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) 3. Kernel driver API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) ====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) Kernel drivers have access to two flags that map to IFF_LOWER_UP and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) IFF_DORMANT. These flags can be set from everywhere, even from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) interrupts. It is guaranteed that only the driver has write access,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) however, if different layers of the driver manipulate the same flag,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) the driver has to provide the synchronisation needed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) __LINK_STATE_NOCARRIER, maps to !IFF_LOWER_UP:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) The driver uses netif_carrier_on() to clear and netif_carrier_off() to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) set this flag. On netif_carrier_off(), the scheduler stops sending
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) packets. The name 'carrier' and the inversion are historical, think of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) it as lower layer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) Note that for certain kind of soft-devices, which are not managing any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) real hardware, it is possible to set this bit from userspace. One
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) should use TVL IFLA_CARRIER to do so.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) netif_carrier_ok() can be used to query that bit.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) __LINK_STATE_DORMANT, maps to IFF_DORMANT:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) Set by the driver to express that the device cannot yet be used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) because some driver controlled protocol establishment has to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) complete. Corresponding functions are netif_dormant_on() to set the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) flag, netif_dormant_off() to clear it and netif_dormant() to query.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) On device allocation, both flags __LINK_STATE_NOCARRIER and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) __LINK_STATE_DORMANT are cleared, so the effective state is equivalent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) to netif_carrier_ok() and !netif_dormant().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) Whenever the driver CHANGES one of these flags, a workqueue event is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) scheduled to translate the flag combination to IFLA_OPERSTATE as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) follows:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) !netif_carrier_ok():
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) IF_OPER_LOWERLAYERDOWN if the interface is stacked, IF_OPER_DOWN
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) otherwise. Kernel can recognise stacked interfaces because their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) ifindex != iflink.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) netif_carrier_ok() && netif_dormant():
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) IF_OPER_DORMANT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) netif_carrier_ok() && !netif_dormant():
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) IF_OPER_UP if userspace interaction is disabled. Otherwise
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) IF_OPER_DORMANT with the possibility for userspace to initiate the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) IF_OPER_UP transition afterwards.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) 4. Setting from userspace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) =========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) Applications have to use the netlink interface to influence the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) RFC2863 operational state of an interface. Setting IFLA_LINKMODE to 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) via RTM_SETLINK instructs the kernel that an interface should go to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) IF_OPER_DORMANT instead of IF_OPER_UP when the combination
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) netif_carrier_ok() && !netif_dormant() is set by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) driver. Afterwards, the userspace application can set IFLA_OPERSTATE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) to IF_OPER_DORMANT or IF_OPER_UP as long as the driver does not set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) netif_carrier_off() or netif_dormant_on(). Changes made by userspace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) are multicasted on the netlink group RTNLGRP_LINK.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) So basically a 802.1X supplicant interacts with the kernel like this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) - subscribe to RTNLGRP_LINK
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) - set IFLA_LINKMODE to 1 via RTM_SETLINK
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) - query RTM_GETLINK once to get initial state
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) - if initial flags are not (IFF_LOWER_UP && !IFF_DORMANT), wait until
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) netlink multicast signals this state
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) - do 802.1X, eventually abort if flags go down again
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) - send RTM_SETLINK to set operstate to IF_OPER_UP if authentication
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) succeeds, IF_OPER_DORMANT otherwise
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) - see how operstate and IFF_RUNNING is echoed via netlink multicast
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) - set interface back to IF_OPER_DORMANT if 802.1X reauthentication
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) fails
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) - restart if kernel changes IFF_LOWER_UP or IFF_DORMANT flag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) if supplicant goes down, bring back IFLA_LINKMODE to 0 and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) IFLA_OPERSTATE to a sane value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) A routing daemon or dhcp client just needs to care for IFF_RUNNING or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) waiting for operstate to go IF_OPER_UP/IF_OPER_UNKNOWN before
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) considering the interface / querying a DHCP address.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) For technical questions and/or comments please e-mail to Stefan Rompf
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) (stefan at loplof.de).
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags