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