0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ==================
0004 Operational States
0005 ==================
0006
0007
0008 1. Introduction
0009 ===============
0010
0011 Linux distinguishes between administrative and operational state of an
0012 interface. Administrative state is the result of "ip link set dev
0013 <dev> up or down" and reflects whether the administrator wants to use
0014 the device for traffic.
0015
0016 However, an interface is not usable just because the admin enabled it
0017 - ethernet requires to be plugged into the switch and, depending on
0018 a site's networking policy and configuration, an 802.1X authentication
0019 to be performed before user data can be transferred. Operational state
0020 shows the ability of an interface to transmit this user data.
0021
0022 Thanks to 802.1X, userspace must be granted the possibility to
0023 influence operational state. To accommodate this, operational state is
0024 split into two parts: Two flags that can be set by the driver only, and
0025 a RFC2863 compatible state that is derived from these flags, a policy,
0026 and changeable from userspace under certain rules.
0027
0028
0029 2. Querying from userspace
0030 ==========================
0031
0032 Both admin and operational state can be queried via the netlink
0033 operation RTM_GETLINK. It is also possible to subscribe to RTNLGRP_LINK
0034 to be notified of updates while the interface is admin up. This is
0035 important for setting from userspace.
0036
0037 These values contain interface state:
0038
0039 ifinfomsg::if_flags & IFF_UP:
0040 Interface is admin up
0041
0042 ifinfomsg::if_flags & IFF_RUNNING:
0043 Interface is in RFC2863 operational state UP or UNKNOWN. This is for
0044 backward compatibility, routing daemons, dhcp clients can use this
0045 flag to determine whether they should use the interface.
0046
0047 ifinfomsg::if_flags & IFF_LOWER_UP:
0048 Driver has signaled netif_carrier_on()
0049
0050 ifinfomsg::if_flags & IFF_DORMANT:
0051 Driver has signaled netif_dormant_on()
0052
0053 TLV IFLA_OPERSTATE
0054 ------------------
0055
0056 contains RFC2863 state of the interface in numeric representation:
0057
0058 IF_OPER_UNKNOWN (0):
0059 Interface is in unknown state, neither driver nor userspace has set
0060 operational state. Interface must be considered for user data as
0061 setting operational state has not been implemented in every driver.
0062
0063 IF_OPER_NOTPRESENT (1):
0064 Unused in current kernel (notpresent interfaces normally disappear),
0065 just a numerical placeholder.
0066
0067 IF_OPER_DOWN (2):
0068 Interface is unable to transfer data on L1, f.e. ethernet is not
0069 plugged or interface is ADMIN down.
0070
0071 IF_OPER_LOWERLAYERDOWN (3):
0072 Interfaces stacked on an interface that is IF_OPER_DOWN show this
0073 state (f.e. VLAN).
0074
0075 IF_OPER_TESTING (4):
0076 Interface is in testing mode, for example executing driver self-tests
0077 or media (cable) test. It can't be used for normal traffic until tests
0078 complete.
0079
0080 IF_OPER_DORMANT (5):
0081 Interface is L1 up, but waiting for an external event, f.e. for a
0082 protocol to establish. (802.1X)
0083
0084 IF_OPER_UP (6):
0085 Interface is operational up and can be used.
0086
0087 This TLV can also be queried via sysfs.
0088
0089 TLV IFLA_LINKMODE
0090 -----------------
0091
0092 contains link policy. This is needed for userspace interaction
0093 described below.
0094
0095 This TLV can also be queried via sysfs.
0096
0097
0098 3. Kernel driver API
0099 ====================
0100
0101 Kernel drivers have access to two flags that map to IFF_LOWER_UP and
0102 IFF_DORMANT. These flags can be set from everywhere, even from
0103 interrupts. It is guaranteed that only the driver has write access,
0104 however, if different layers of the driver manipulate the same flag,
0105 the driver has to provide the synchronisation needed.
0106
0107 __LINK_STATE_NOCARRIER, maps to !IFF_LOWER_UP:
0108
0109 The driver uses netif_carrier_on() to clear and netif_carrier_off() to
0110 set this flag. On netif_carrier_off(), the scheduler stops sending
0111 packets. The name 'carrier' and the inversion are historical, think of
0112 it as lower layer.
0113
0114 Note that for certain kind of soft-devices, which are not managing any
0115 real hardware, it is possible to set this bit from userspace. One
0116 should use TLV IFLA_CARRIER to do so.
0117
0118 netif_carrier_ok() can be used to query that bit.
0119
0120 __LINK_STATE_DORMANT, maps to IFF_DORMANT:
0121
0122 Set by the driver to express that the device cannot yet be used
0123 because some driver controlled protocol establishment has to
0124 complete. Corresponding functions are netif_dormant_on() to set the
0125 flag, netif_dormant_off() to clear it and netif_dormant() to query.
0126
0127 On device allocation, both flags __LINK_STATE_NOCARRIER and
0128 __LINK_STATE_DORMANT are cleared, so the effective state is equivalent
0129 to netif_carrier_ok() and !netif_dormant().
0130
0131
0132 Whenever the driver CHANGES one of these flags, a workqueue event is
0133 scheduled to translate the flag combination to IFLA_OPERSTATE as
0134 follows:
0135
0136 !netif_carrier_ok():
0137 IF_OPER_LOWERLAYERDOWN if the interface is stacked, IF_OPER_DOWN
0138 otherwise. Kernel can recognise stacked interfaces because their
0139 ifindex != iflink.
0140
0141 netif_carrier_ok() && netif_dormant():
0142 IF_OPER_DORMANT
0143
0144 netif_carrier_ok() && !netif_dormant():
0145 IF_OPER_UP if userspace interaction is disabled. Otherwise
0146 IF_OPER_DORMANT with the possibility for userspace to initiate the
0147 IF_OPER_UP transition afterwards.
0148
0149
0150 4. Setting from userspace
0151 =========================
0152
0153 Applications have to use the netlink interface to influence the
0154 RFC2863 operational state of an interface. Setting IFLA_LINKMODE to 1
0155 via RTM_SETLINK instructs the kernel that an interface should go to
0156 IF_OPER_DORMANT instead of IF_OPER_UP when the combination
0157 netif_carrier_ok() && !netif_dormant() is set by the
0158 driver. Afterwards, the userspace application can set IFLA_OPERSTATE
0159 to IF_OPER_DORMANT or IF_OPER_UP as long as the driver does not set
0160 netif_carrier_off() or netif_dormant_on(). Changes made by userspace
0161 are multicasted on the netlink group RTNLGRP_LINK.
0162
0163 So basically a 802.1X supplicant interacts with the kernel like this:
0164
0165 - subscribe to RTNLGRP_LINK
0166 - set IFLA_LINKMODE to 1 via RTM_SETLINK
0167 - query RTM_GETLINK once to get initial state
0168 - if initial flags are not (IFF_LOWER_UP && !IFF_DORMANT), wait until
0169 netlink multicast signals this state
0170 - do 802.1X, eventually abort if flags go down again
0171 - send RTM_SETLINK to set operstate to IF_OPER_UP if authentication
0172 succeeds, IF_OPER_DORMANT otherwise
0173 - see how operstate and IFF_RUNNING is echoed via netlink multicast
0174 - set interface back to IF_OPER_DORMANT if 802.1X reauthentication
0175 fails
0176 - restart if kernel changes IFF_LOWER_UP or IFF_DORMANT flag
0177
0178 if supplicant goes down, bring back IFLA_LINKMODE to 0 and
0179 IFLA_OPERSTATE to a sane value.
0180
0181 A routing daemon or dhcp client just needs to care for IFF_RUNNING or
0182 waiting for operstate to go IF_OPER_UP/IF_OPER_UNKNOWN before
0183 considering the interface / querying a DHCP address.
0184
0185
0186 For technical questions and/or comments please e-mail to Stefan Rompf
0187 (stefan at loplof.de).
