1.\" $OpenBSD: ifmedia.4,v 1.30 2023/08/15 00:43:00 jsg Exp $ 2.\" $NetBSD: ifmedia.4,v 1.14 2001/06/30 17:57:56 bjh21 Exp $ 3.\" 4.\" Copyright (c) 1998 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by Jason R. Thorpe of the Numerical Aerospace Simulation Facility, 9.\" NASA Ames Research Center. 10.\" 11.\" Redistribution and use in source and binary forms, with or without 12.\" modification, are permitted provided that the following conditions 13.\" are met: 14.\" 1. Redistributions of source code must retain the above copyright 15.\" notice, this list of conditions and the following disclaimer. 16.\" 2. Redistributions in binary form must reproduce the above copyright 17.\" notice, this list of conditions and the following disclaimer in the 18.\" documentation and/or other materials provided with the distribution. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 21.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 22.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 23.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 24.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 25.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 26.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 27.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 28.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 29.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 30.\" POSSIBILITY OF SUCH DAMAGE. 31.\" 32.Dd $Mdocdate: August 15 2023 $ 33.Dt IFMEDIA 4 34.Os 35.Sh NAME 36.Nm ifmedia 37.Nd network interface media settings 38.Sh SYNOPSIS 39.In sys/socket.h 40.In net/if.h 41.In net/if_media.h 42.Sh DESCRIPTION 43The 44.Nm 45interface provides a consistent method for querying and setting 46network interface media and media options. 47The media is typically set using the 48.Xr ifconfig 8 49command. 50.Pp 51Currently these link types are supported by 52.Nm ifmedia : 53.Pp 54.Bl -tag -offset indent -width IFM_IEEE80211 -compact 55.It Dv IFM_ETHER 56Ethernet 57.It Dv IFM_FDDI 58FDDI 59.It Dv IFM_IEEE80211 60IEEE802.11 Wireless LAN 61.It Dv IFM_TDM 62Time Division Multiplex 63.It Dv IFM_CARP 64CARP 65.El 66.Pp 67The following sections describe the possible media settings for each 68link type. 69Not all of these are supported by every device; refer to 70your device's manual page for more information. 71.Pp 72The lists below provide the possible names of each media type or option. 73The first name in the list is the canonical name of the media type or 74option. 75Additional names are acceptable aliases for the media type or option. 76.Sh COMMON MEDIA TYPES AND OPTIONS 77The following media types are shared by all link types: 78.Pp 79.Bl -tag -offset indent -width IFM_MANUAL -compact 80.It Dv IFM_AUTO 81Autoselect the best media. 82[autoselect, auto] 83.It Dv IFM_MANUAL 84Jumper or switch on device selects media. 85[manual] 86.It Dv IFM_NONE 87Deselect all media. 88[none] 89.El 90.Pp 91The following media options are shared by all link types: 92.Bl -tag -offset indent -width IFM_FLAG0 93.It Dv IFM_FDX 94Place the device into full-duplex mode. 95This option only has meaning if the device is normally not full-duplex. 96.It Dv IFM_HDX 97Place the device into half-duplex mode. 98This option only has meaning if the device is normally not half-duplex. 99[half-duplex, hdx] 100.It Dv IFM_FLOW 101Enable hardware flow control on device. 102.It Dv IFM_FLAG0 103Driver-defined flag. 104[flag0] 105.It Dv IFM_FLAG1 106Driver-defined flag. 107[flag1] 108.It Dv IFM_FLAG2 109Driver-defined flag. 110[flag2] 111.It Dv IFM_LOOP 112Place the device into hardware loopback mode. 113[loopback, hw-loopback, loop] 114.El 115.Sh MEDIA TYPES AND OPTIONS FOR ETHERNET 116The following media types are defined for Ethernet: 117.Bl -tag -offset indent -width IFM_10G_SFP_CU 118.It Dv IFM_10_T 11910BASE-T, 10Mb/s over unshielded twisted pair, RJ45 connector. 120[10baseT, UTP, 10UTP] 121.It Dv IFM_10_2 12210BASE2, 10Mb/s over coaxial cable, BNC connector; also called Thinnet. 123[10base2, BNC, 10BNC] 124.It Dv IFM_10_5 12510BASE5, 10Mb/s over 15-wire cables, DB15 connector; also called AUI. 126[10base5, AUI, 10AUI] 127.It Dv IFM_10_STP 12810BASE-STP, 10Mb/s over shielded twisted pair, DB9 connector. 129[10baseSTP, STP, 10STP] 130.It Dv IFM_10_FL 13110BASE-FL, 10Mb/s over fiber optic cables. 132[10baseFL, FL, 10FL] 133.It Dv IFM_100_TX 134100BASE-TX, 100Mb/s over unshielded twisted pair, RJ45 connector. 135[100baseTX, 100TX] 136.It Dv IFM_100_FX 137100BASE-FX, 100Mb/s over fiber optic cables. 138[100baseFX, 100FX] 139.It Dv IFM_100_T4 140100BASE-T4, 100Mb/s over 4-wire (category 3) unshielded twisted pair, RJ45 141connector. 142[100baseT4, 100T4] 143.It Dv IFM_100_T2 144100BASE-T2. 145[100baseT2, 100T2] 146.It Dv IFM_100_VG 147100VG-AnyLAN. 148[100baseVG, 100VG] 149.It Dv IFM_1000_SX 1501000BASE-SX, 1Gb/s over multi-mode fiber optic cables. 151[1000baseSX, 1000SX] 152.It Dv IFM_1000_LX 1531000BASE-LX, 1Gb/s over single-mode fiber optic cables. 154[1000baseLX, 1000LX] 155.It Dv IFM_1000_CX 1561000BASE-CX, 1Gb/s over shielded twisted pair. 157[1000baseCX, 1000CX] 158.It Dv IFM_1000_T 1591000BASE-T, 1Gb/s over category 5 unshielded twisted pair, RJ45 connector. 160[1000baseT, 1000T] 161.It Dv IFM_1000_TX 162Compatibility for 1000BASE-T. 163[1000baseTX, 1000TX] 164.It Dv IFM_2500_SX 1652500BASE-SX, 2.5Gb/s over multi-mode fiber optic cables. 166[2500baseSX, 2500SX] 167.It Dv IFM_2500_T 1682500BASE-T, 2.5Gb/s over unshielded twisted pair, RJ45 connector. 169[2500baseT, 2500BASE-T] 170.It Dv IFM_10G_CX4 17110GBASE-CX4, 10Gb/s over XAUI 4-lane PCS and copper cables. 172[10GbaseCX4, 10GCX4, 10GBASE-CX4] 173.It Dv IFM_10G_LR 17410GBASE-LR, 10Gb/s over single-mode fiber optic cables. 175[10GbaseLR, 10GLR, 10GBASE-LR] 176.It Dv IFM_10G_SFP_CU 17710GSFP+Cu, 10Gb/s over SFP+ Direct Attach cables. 178[10GSFP+Cu, 10GCu] 179.It Dv IFM_10G_SR 18010GBASE-SR, 10Gb/s over multi-mode fiber optic cables. 181[10GbaseSR, 10GSR, 10GBASE-SR] 182.It Dv IFM_10G_T 18310GBASE-T, 10Gb/s over unshielded twisted pair, RJ45 connector. 184[10GbaseT, 10GT, 10GBASE-T] 185.It Dv IFM_HPNA_1 186HomePNA 1.0, 1Mb/s over 2-wire (category 3) unshielded twisted pair 187[HomePNA1, HPNA1] 188.El 189.Pp 190The following media options are defined for Ethernet: 191.Bl -tag -offset indent -width IFM_ETH_RXPAUSE 192.It Dv IFM_ETH_MASTER 193Configure a 1000BASE-T PHY as a MASTER PHY. 194.It Dv IFM_ETH_RXPAUSE 195Receive flow control is enabled on the 1000BASE-T PHY. 196.It Dv IFM_ETH_TXPAUSE 197Transmit flow control is enabled on the 1000BASE-T PHY. 198.El 199.Sh MEDIA TYPES AND OPTIONS FOR FDDI 200The following media types are defined for FDDI: 201.Pp 202.Bl -tag -offset indent -width IFM_FDDI_SMF -compact 203.It Dv IFM_FDDI_SMF 204Single-mode fiber. 205[Single-mode, SMF] 206.It Dv IFM_FDDI_MMF 207Multi-mode fiber. 208[Multi-mode, MMF] 209.It Dv IFM_FDDI_UTP 210Unshielded twisted pair, RJ45 connector. 211[UTP, CDDI] 212.El 213.Pp 214The following media options are defined for FDDI: 215.Bl -tag -offset indent -width IFM_FDDI_DA 216.It Dv IFM_FDDI_DA 217Dual-attached station vs. Single-attached station. 218[dual-attach, das] 219.El 220.Sh MEDIA TYPES AND OPTIONS FOR IEEE802.11 WIRELESS LAN 221The following media modes are defined for IEEE802.11 Wireless LAN: 222.Pp 223.Bl -tag -offset indent -width IFM_IEEE80211_11AC -compact 224.It Dv IFM_IEEE80211_11A 2255GHz, OFDM mode. 226[11a] 227.It Dv IFM_IEEE80211_11B 2282GHz, DSSS/CCK mode. 229[11b] 230.It Dv IFM_IEEE80211_11G 2312GHz, DSSS/CCK/OFDM mode. 232[11g] 233.It Dv IFM_IEEE80211_FH 2342GHz, GFSK mode. 235[fh] 236.It Dv IFM_IEEE80211_11N 2372GHz/5GHz, HT mode. 238[11n] 239.It Dv IFM_IEEE80211_11AC 2405GHz, VHT mode. 241[11ac] 242.El 243.Pp 244The following media options are defined for IEEE802.11 Wireless LAN: 245.Pp 246.Bl -tag -offset indent -width IFM_IEEE80211_IBSSMASTER -compact 247.It Dv IFM_IEEE80211_ADHOC 248Ad-hoc mode. 249[adhoc] 250.It Dv IFM_IEEE80211_HOSTAP 251Host Access Point mode. 252[hostap] 253.It Dv IFM_IEEE80211_IBSS 254IBSS mode. 255[ibss] 256.It Dv IFM_IEEE80211_IBSSMASTER 257IBSS master mode. 258[ibssmaster] 259.It Dv IFM_IEEE80211_MONITOR 260Monitor mode. 261[monitor] 262.El 263.Pp 264All of the above media options are mutually exclusive. 265If no media option is used, the wireless interface will try to find an 266access point to connect to. 267.Cm hostap 268mode allows the wireless interface to act as an access point for other 269802.11 devices. 270.Cm ibss 271mode is the standardized method of operating without an access point, with 272each participating device taking on part of the role of an access point. 273.Cm adhoc 274mode, more accurately known as 275.Em ad-hoc demo mode , 276is not specified by the IEEE 802.11 standard and only works with 277.Xr wi 4 278devices. 279Likewise, 280.Cm ibssmaster 281mode only works with 282.Xr wi 4 283devices. 284On standard 802.11 networks the IBSS master role is assigned automatically. 285.Pp 286The channels detailed below are defined for IEEE802.11 Wireless LAN 287in the 2.4GHz band. 288The list of available frequencies is dependent on radio regulations 289specified by regional authorities. 290Recognized regulatory authorities include 291the FCC (United States), ETSI (Europe), and Japan. 292Frequencies in the table are specified in MHz. 293.Bl -column "Channel " "2412" "ETSI" "Japan" -offset indent 294.It Em Channel Ta Em FCC Ta Em ETSI Ta Em Japan 295.It 1 Ta 2412 Ta 2412 Ta 2412 296.It 2 Ta 2417 Ta 2417 Ta 2417 297.It 3 Ta 2422 Ta 2422 Ta 2422 298.It 4 Ta 2427 Ta 2427 Ta 2427 299.It 5 Ta 2432 Ta 2432 Ta 2432 300.It 6 Ta 2437 Ta 2437 Ta 2437 301.It 7 Ta 2442 Ta 2442 Ta 2442 302.It 8 Ta 2447 Ta 2447 Ta 2447 303.It 9 Ta 2452 Ta 2452 Ta 2452 304.It 10 Ta 2457 Ta 2457 Ta 2457 305.It 11 Ta 2462 Ta 2462 Ta 2462 306.It 12 Ta - Ta 2467 Ta 2467 307.It 13 Ta - Ta 2472 Ta 2472 308.It 14 Ta - Ta - Ta 2484 309.El 310.Pp 311The channels do overlap; the bandwidth required for each channel is about 20MHz. 312When using multiple channels in close proximity, it is suggested 313that channels be separated by at least 25MHz. 314In the US, this means that only channels 1, 6, and 11 may be used 315simultaneously without interference. 316.Pp 317Channels in the 5GHz band are too numerous to list here. 318Regulation of their use, particularly outdoors, varies between countries. 319Users are advised to inform themselves about applicable regulations before 320configuring wireless LAN devices for use in the 5GHz band. 321.Pp 322The following media types are defined for IEEE802.11 Wireless LAN: 323.Pp 324.Bl -tag -offset indent -width IFM_IEEE80211_FH1 -compact 325.It Dv IFM_IEEE80211_FH1 326Frequency Hopping 1Mbps. 327[FH1] 328.It Dv IFM_IEEE80211_FH2 329Frequency Hopping 2Mbps. 330[FH2] 331.It Dv IFM_IEEE80211_DS1 332Direct Sequence 1Mbps. 333[DS1] 334.It Dv IFM_IEEE80211_DS2 335Direct Sequence 2Mbps. 336[DS2] 337.El 338.Pp 339The above media types were first introduced in the IEEE 802.11-1997 standard 340and are used in the 2.4GHz band only. 341Frequency Hopping Spread Spectrum modulation is incompatible with modern 342802.11 networks. 343Direct Sequence Spread Spectrum modulation (DSSS) frames can still be used if 344backwards compatibility to 802.11b is enabled. 345.Pp 346.Bl -tag -offset indent -width IFM_IEEE80211_DS22 -compact 347.It Dv IFM_IEEE80211_DS5 348Direct Sequence 5.5Mbps. 349[DS5] 350.It Dv IFM_IEEE80211_DS11 351Direct Sequence 11Mbps. 352[DS11] 353.It Dv IFM_IEEE80211_DS22 354Direct Sequence 22Mbps. 355[DS22] 356.El 357.Pp 358The above media types were first introduced in the IEEE 802.11b-1999 standard 359and are used in the 2.4GHz band only. 360They use Complementary Code Keying (CCK) which, compared to frames sent at 3611Mbps or 2Mbps, reduces the possible distance between transmitter and receiver. 362.Pp 363Modern 802.11 networks remain compatible with 802.11b, even though DSSS frames 364are incompatible with modern 802.11 frames using OFDM. 365Co-existence with 802.11b requires OFDM transmitters to either risk frame 366collisions or 367.Dq reserve 368the medium with a separate preceding transmission that DSSS receivers are 369able to decode. 370This causes additional overhead which some 802.11 deployments avoid by 371deliberately disabling backwards compatibility with 802.11b. 372.Pp 373.Bl -tag -offset indent -width IFM_IEEE80211_VHT_MCSx -compact 374.It Dv IFM_IEEE80211_OFDM6 375OFDM 6Mbps. 376[OFDM6] 377.It Dv IFM_IEEE80211_OFDM9 378OFDM 9Mbps. 379[OFDM9] 380.It Dv IFM_IEEE80211_OFDM12 381OFDM 12Mbps. 382[OFDM12] 383.It Dv IFM_IEEE80211_OFDM18 384OFDM 18Mbps. 385[OFDM18] 386.It Dv IFM_IEEE80211_OFDM24 387OFDM 24Mbps. 388[OFDM24] 389.It Dv IFM_IEEE80211_OFDM36 390OFDM 36Mbps. 391[OFDM36] 392.It Dv IFM_IEEE80211_OFDM48 393OFDM 48Mbps. 394[OFDM48] 395.It Dv IFM_IEEE80211_OFDM54 396OFDM 54Mbps. 397[OFDM54] 398.It Dv IFM_IEEE80211_OFDM72 399OFDM 72Mbps. 400[OFDM72] 401.El 402.Pp 403The above media types were first introduced in the IEEE 802.11a-1999 404standard for the 5GHz band, and in the IEEE 802.11g-2003 standard 405for the 2.4GHz band. 406OFDM with 72Mbps is a proprietary extension and was never standardized 407by IEEE. 408.Pp 409Orthogonal Frequency Division Multiplexing (OFDM) is the current 410standard modulation technique for 802.11. 411Each 20MHz channel used by 802.11a and 802.11g provides space for 41248 OFDM sub-carriers for data. 413The sub-carriers use BPSK, QPSK, 16QAM, or 64QAM modulation, combined with 414a particular coding rate for error correction at the receiver. 415The coding rate specifies how many data bits in a frame are transmitted 416without redundancy. 417.Bl -column "Modulation" "Coding Rate " "Mbit/s" -offset 6n 418.It Em Modulation Ta Em Coding Rate Ta Em Mbit/s 419.It BPSK Ta 1/2 Ta 6 420.It BPSK Ta 3/4 Ta 9 421.It QPSK Ta 1/2 Ta 12 422.It QPSK Ta 3/4 Ta 18 423.It 16QAM Ta 1/2 Ta 24 424.It 16QAM Ta 3/4 Ta 36 425.It 64QAM Ta 1/2 Ta 48 426.It 64QAM Ta 3/4 Ta 52 427.El 428.Pp 429The IEEE 802.11n-2009 standard for 430.Dq High Throughput 431(HT) wireless LAN defines additional sub-carriers, modulations, and 432coding rates. 433The channel bandwidth for data frame transmissions was optionally extended 434to 40MHz, with full backwards compatibility to 802.11a/b/g devices which 435cannot decode 40MHz transmissions. 436Several additional features were introduced, most notably MIMO (multiple-input, 437multiple-output). 438With MIMO, a data stream is divided across up to 4 439.Dq spatial streams , 440which are transmitted in parallel by a corresponding amount of antennas. 441Each spatial stream is received with a dedicated antenna, and the spatial 442streams are de-multiplexed to obtain the original data stream. 443.Pp 444802.11n assigns a numeric identifier to all possible combinations of 445modulation, coding rate, and number of spatial streams. 446This results in 77 distinct modulation and coding schemes, abbreviated as 447.Dq MCS . 448.Pp 449.Nm ifmedia 450supports HT_MCS0 up to HT_MCS31: 451.Pp 452.Bl -tag -offset indent -width IFM_IEEE80211_VHT_MCSx -compact 453.It Dv IFM_IEEE80211_HT_MCSx 454HT OFDM MCS x (where x is in the range 0 - 31, inclusive). 455[HT-MCSx] 456.El 457.Pp 458In practice, only MCS-0 to MCS-32 are supported by commonly available devices. 459The remaining MCS define combinations where distinct spatial streams employ 460distinct modulations, a feature which was not widely implemented by hardware 461vendors. 462.Pp 463The IEEE 802.11ac-2013 standard for 464.Dq Very High Throughput 465(VHT) wireless LAN operates in the 5GHz band only. 466The channel bandwidth for data frame transmissions can be up to 160MHz wide. 467The MCS identifiers were redefined and vastly reduced in number. 468As a result, only VHT_MCS0 to VHT_MCS9 are defined for 802.11ac: 469.Pp 470.Bl -tag -offset indent -width IFM_IEEE80211_VHT_MCSx -compact 471.It Dv IFM_IEEE80211_VHT_MCSx 472VHT OFDM MCS x (where x is in the range 0 - 9, inclusive). 473[VHT-MCSx] 474.El 475.Pp 476The number of spatial streams is no longer associated with a given VHT MCS 477identifier and must be specified as a separate 478.Dq NSS 479parameter. 480This parameter is not yet implemented by 481.Nm ifmedia . 482.Sh MEDIA TYPES AND OPTIONS FOR TDM 483The following media types are defined for TDM: 484.Bl -tag -offset indent -width IFM_TDM_E1_G704_CRC4 485.It Dv IFM_TDM_E1 486E1, 2048kb/s HDB3 encoded, G.703 clearchannel serial line. 487[e1] 488.It Dv IFM_TDM_E1_AMI 489E1, 2048kb/s AMI encoded, G.703 clearchannel serial line. 490[e1-ami] 491.It Dv IFM_TDM_E1_AMI_G704 492E1, 2048kb/s AMI encoded, G.704 structured serial line. 493[e1-ami-g.704] 494.It Dv IFM_TDM_E1_G704 495E1, 2048kb/s HDB3 encoded, G.704 structured serial line. 496[e1-g.704] 497.It Dv IFM_TDM_E1_G704_CRC4 498E1, 2048kb/s HDB3 encoded, G.704 structured serial line with CRC4 checksum. 499[e1-g.704-crc4] 500.It Dv IFM_TDM_E3 501E3, 34368kb/s HDB3 encoded, G.703 clearchannel serial line. 502[e3] 503.It Dv IFM_TDM_E3_G751 504E3, 34368kb/s HDB3 encoded, G.751 structured serial line. 505[e3-g.751] 506.It Dv IFM_TDM_E3_G832 507E3, 34368kb/s HDB3 encoded, G.832 structured serial line. 508[e3-g.832] 509.It Dv IFM_TDM_T1 510T1, 1536xkb/s B8ZS encoded, extended super frame (ESF) structured serial line. 511[t1] 512.It Dv IFM_TDM_T1_AMI 513T1, 1536kb/s AMI encoded, super frame (SF) structured serial line. 514[t1-ami] 515.It Dv IFM_TDM_T3 516T3, 44736kb/s B3ZS, C-bit structured serial line. 517[t3] 518.It Dv IFM_TDM_T3_M13 519T3, 44736kb/s B3ZS, M13 structured serial line. 520[t3-m13] 521.El 522.Pp 523The following media options are defined for TDM: 524.Bl -tag -offset indent -width IFM_TDM_HDLC_CRC16 525.It Dv IFM_TDM_HDLC_CRC16 526Cisco HDLC with 16-bit CRC checksum encoding. 527[hdlc-crc16] 528.It Dv IFM_TDM_FR_ANSI 529ANSI/ITU Framerelay encoding. 530[framerelay-ansi, framerelay-itu] 531.It Dv IFM_TDM_FR_CISCO 532Cisco Framerelay encoding. 533[framerelay-cisco] 534.It Dv IFM_TDM_PPP 535PPP encoding. 536[ppp] 537.El 538.Pp 539By default TDM interfaces will use Cisco HDLC encoding with a 32-bit CRC 540checksum. 541.Pp 542The following media modes are defined for TDM: 543.Bl -tag -offset indent -width IFM_TDM_MASTER 544.It Dv IFM_TDM_MASTER 545Use local clock source as master clock. 546[master] 547.El 548.Sh MEDIA TYPES AND OPTIONS FOR CARP 549.Xr carp 4 550does not support any media types or options. 551.Sh SEE ALSO 552.Xr netintro 4 , 553.Xr ifconfig 8 554.Sh HISTORY 555The 556.Nm 557interface first appeared in 558.Bsx 3.0 . 559The implementation that appeared in 560.Nx 1.3 561was written by Jonathan Stone and Jason R. Thorpe to be compatible with 562the BSDI API. 563It has since gone through several revisions which have extended the 564API while maintaining backwards compatibility with the original API. 565.Pp 566Support for the 567.Sy IEEE802.11 Wireless LAN 568link type was added in 569.Nx 1.5 . 570.Pp 571.Sy Host AP 572mode was added in 573.Ox 3.1 . 574