docs: networking: convert operstates.txt to ReST

Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git

kernel os linux

- add SPDX header;
- add a document title;
- adjust chapters, adding proper markups;
- mark lists as such;
- adjust identation, whitespaces and blank lines where needed;
- add to networking/index.rst.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: David S. Miller <davem@davemloft.net>

authored by

Mauro Carvalho Chehab and committed by

David S. Miller 6 years ago f5c39ef3 63893472

+34 -12

2 changed files

expand all

Documentation

networking

index.rst

operstates.rst

Documentation/networking/index.rst

··· 88 88 nf_conntrack-sysctl 89 89 nf_flowtable 90 90 openvswitch 91 + operstates 91 92 92 93 .. only:: subproject and html 93 94

+33 -12

Documentation/networking/operstates.txt Documentation/networking/operstates.rst

··· 1 + .. SPDX-License-Identifier: GPL-2.0 2 + 3 + ================== 4 + Operational States 5 + ================== 6 + 1 7 2 8 1. Introduction 9 + =============== 3 10 4 11 Linux distinguishes between administrative and operational state of an 5 12 interface. Administrative state is the result of "ip link set dev ··· 27 20 28 21 29 22 2. Querying from userspace 23 + ========================== 30 24 31 25 Both admin and operational state can be queried via the netlink 32 26 operation RTM_GETLINK. It is also possible to subscribe to RTNLGRP_LINK ··· 38 30 39 31 ifinfomsg::if_flags & IFF_UP: 40 32 Interface is admin up 33 + 41 34 ifinfomsg::if_flags & IFF_RUNNING: 42 35 Interface is in RFC2863 operational state UP or UNKNOWN. This is for 43 36 backward compatibility, routing daemons, dhcp clients can use this 44 37 flag to determine whether they should use the interface. 38 + 45 39 ifinfomsg::if_flags & IFF_LOWER_UP: 46 40 Driver has signaled netif_carrier_on() 41 + 47 42 ifinfomsg::if_flags & IFF_DORMANT: 48 43 Driver has signaled netif_dormant_on() 49 44 50 45 TLV IFLA_OPERSTATE 46 + ------------------ 51 47 52 48 contains RFC2863 state of the interface in numeric representation: 53 49 ··· 59 47 Interface is in unknown state, neither driver nor userspace has set 60 48 operational state. Interface must be considered for user data as 61 49 setting operational state has not been implemented in every driver. 50 + 62 51 IF_OPER_NOTPRESENT (1): 63 52 Unused in current kernel (notpresent interfaces normally disappear), 64 53 just a numerical placeholder. 54 + 65 55 IF_OPER_DOWN (2): 66 56 Interface is unable to transfer data on L1, f.e. ethernet is not 67 57 plugged or interface is ADMIN down. 58 + 68 59 IF_OPER_LOWERLAYERDOWN (3): 69 60 Interfaces stacked on an interface that is IF_OPER_DOWN show this 70 61 state (f.e. VLAN). 62 + 71 63 IF_OPER_TESTING (4): 72 64 Unused in current kernel. 65 + 73 66 IF_OPER_DORMANT (5): 74 67 Interface is L1 up, but waiting for an external event, f.e. for a 75 68 protocol to establish. (802.1X) 69 + 76 70 IF_OPER_UP (6): 77 71 Interface is operational up and can be used. 78 72 79 73 This TLV can also be queried via sysfs. 80 74 81 75 TLV IFLA_LINKMODE 76 + ----------------- 82 77 83 78 contains link policy. This is needed for userspace interaction 84 79 described below. ··· 94 75 95 76 96 77 3. Kernel driver API 78 + ==================== 97 79 98 80 Kernel drivers have access to two flags that map to IFF_LOWER_UP and 99 81 IFF_DORMANT. These flags can be set from everywhere, even from ··· 146 126 147 127 148 128 4. Setting from userspace 129 + ========================= 149 130 150 131 Applications have to use the netlink interface to influence the 151 132 RFC2863 operational state of an interface. Setting IFLA_LINKMODE to 1 ··· 160 139 161 140 So basically a 802.1X supplicant interacts with the kernel like this: 162 141 163 - -subscribe to RTNLGRP_LINK 164 - -set IFLA_LINKMODE to 1 via RTM_SETLINK 165 - -query RTM_GETLINK once to get initial state 166 - -if initial flags are not (IFF_LOWER_UP && !IFF_DORMANT), wait until 167 - netlink multicast signals this state 168 - -do 802.1X, eventually abort if flags go down again 169 - -send RTM_SETLINK to set operstate to IF_OPER_UP if authentication 170 - succeeds, IF_OPER_DORMANT otherwise 171 - -see how operstate and IFF_RUNNING is echoed via netlink multicast 172 - -set interface back to IF_OPER_DORMANT if 802.1X reauthentication 173 - fails 174 - -restart if kernel changes IFF_LOWER_UP or IFF_DORMANT flag 142 + - subscribe to RTNLGRP_LINK 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 175 154 176 155 if supplicant goes down, bring back IFLA_LINKMODE to 0 and 177 156 IFLA_OPERSTATE to a sane value.