share/man/man4/wlan.4

   1 .\"
   2 .\" Copyright (c) 2003 Tom Rhodes
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd January 26, 2021
  29 .Dt WLAN 4
  30 .Os
  31 .Sh NAME
  32 .Nm wlan
  33 .Nd generic 802.11 link-layer support
  34 .Sh SYNOPSIS
  35 .Cd "device wlan"
  36 .Sh DESCRIPTION
  37 The
  38 .Nm
  39 module provides generic code to support 802.11 drivers.
  40 Where a device does not directly support 802.11 functionality
  41 this layer fills in.
  42 The
  43 .Nm
  44 module is required by all native 802.11 drivers.
  45 .Pp
  46 .Nm
  47 supports multi-mode devices capable of
  48 operating in both 2.4GHz and 5GHz bands and supports numerous
  49 802.11 standards: 802.11a, 802.11b, 802.11g, 802.11n, and 802.11s (Draft 3.0).
  50 The WPA, 802.11i, and 802.1x security protocols are supported
  51 through a combination of in-kernel code and user-mode applications.
  52 The WME/WMM multi-media protocols are supported entirely within
  53 the
  54 .Nm
  55 module but require a suitably capable hardware device.
  56 Likewise the 802.11h specification is supported only by suitably
  57 capable devices.
  58 .Pp
  59 Drivers provide 802.11 functionality through
  60 .Nm
  61 interfaces that are created at runtime using interface cloning.
  62 This is done with the
  63 .Xr ifconfig 8
  64 .Cm create
  65 command or using the
  66 .Va wlans_IFX
  67 variable in
  68 .Xr rc.conf 5 .
  69 Some drivers support the creation of multiple
  70 .Nm
  71 interfaces that share the same underlying device;
  72 this is the way by which ``multi-bss support'' is provided but it
  73 can also be used to create WDS links and other interesting applications.
  74 .Pp
  75 There are several types of
  76 .Nm
  77 interfaces that may be created:
  78 .Bl -tag -width monitor
  79 .It Cm sta
  80 A client station in an infrastructure bss
  81 (i.e. one that associates to an access point).
  82 .It Cm hostap
  83 An access point in an infrastructure bss.
  84 .It Cm mesh
  85 A mesh station in an MBSS network.
  86 .It Cm adhoc
  87 A station in an IBSS network.
  88 .It Cm ahdemo
  89 A station operating in ``adhoc demo mode''.
  90 This is essentially an IBSS station that does not use management
  91 frames (e.g. no beacons are transmitted).
  92 An
  93 .Cm ahdemo
  94 interface is especially useful for applications that want to transmit
  95 and receive raw 802.11 packets.
  96 .It Cm monitor
  97 An interface used exclusively for capturing 802.11 frames.
  98 In particular this specified to have read-only properties
  99 which enables it to be operated on frequencies where one
 100 would otherwise not be allowed.
 101 .It Cm wds
 102 A station that passes 4-address 802.11 traffic for the purpose
 103 of tunneling traffic over a wireless link.
 104 Typically this station would share the same MAC address as a
 105 .Cm hostap
 106 interface.
 107 It may be possible to create
 108 .Cm wds
 109 interfaces without a companion
 110 .Cm hostap
 111 interface but that is not guaranteed; one may need to create a
 112 .Cm hostap
 113 interface that does not send beacon frames before
 114 .Cm wds
 115 interfaces may be created.
 116 .El
 117 .Pp
 118 Note that an interface's type cannot be changed once it is created.
 119 .Pp
 120 .Nm
 121 defines several mechanisms by which plugin modules may
 122 be used to extend its functionality.
 123 Cryptographic support such as WEP, TKIP, and AES-CCMP are implemented
 124 as standalone modules (if not statically configured into a system)
 125 that register with
 126 .Nm .
 127 Similarly there is an authenticator framework for defining 802.11
 128 authentication services and a framework for integrating access
 129 control mechanisms specific to the 802.11 protocol.
 130 .Sh DEBUGGING
 131 If the
 132 .Dv IEEE80211_DEBUG
 133 option is included in the kernel configuration,
 134 debugging controls are available using:
 135 .Pp
 136 .Dl "sysctl net.wlan.X.debug=mask"
 137 .Pp
 138 where
 139 .Ar X
 140 is the number of the
 141 .Nm
 142 instance and mask is a bit-or of control bits that determine which
 143 debugging messages to enable.
 144 For example,
 145 .Pp
 146 .Dl "sysctl net.wlan.0.debug=0x00200000"
 147 .Pp
 148 enables debugging messages related to scanning for an access point,
 149 adhoc neighbor, or an unoccupied channel when operation as an access point.
 150 The
 151 .Xr wlandebug 8
 152 tool provides a more user-friendly mechanism for doing the same thing.
 153 Note that
 154 .Pp
 155 .Dl "sysctl net.wlan.debug=mask"
 156 .Pp
 157 defines the initial value of the debugging flags for each cloned
 158 .Nm
 159 interface; this is useful to enable debug messages during interface creation.
 160 .Sh COMPATIBILITY
 161 The module name of
 162 .Nm
 163 was used to be compatible with
 164 .Nx .
 165 .Pp
 166 Mesh stations follow the 802.11s Draft 3.0 specification which is
 167 not ratified and subject to change.
 168 Be aware that this specification is incompatible with earlier drafts.
 169 Stations implementing earlier drafts (e.g., Linux) may be incompatible.
 170 .Sh SEE ALSO
 171 .Xr an 4 ,
 172 .Xr ath 4 ,
 173 .Xr bwi 4 ,
 174 .Xr bwn 4 ,
 175 .Xr ipw 4 ,
 176 .Xr iwi 4 ,
 177 .Xr iwm 4 ,
 178 .Xr iwn 4 ,
 179 .Xr malo 4 ,
 180 .Xr mwl 4 ,
 181 .Xr netintro 4 ,
 182 .Xr otus 4 ,
 183 .Xr ral 4 ,
 184 .Xr rsu 4 ,
 185 .Xr rtwn 4 ,
 186 .Xr rum 4 ,
 187 .Xr run 4 ,
 188 .Xr uath 4 ,
 189 .Xr upgt 4 ,
 190 .Xr ural 4 ,
 191 .Xr urtw 4 ,
 192 .Xr wlan_acl 4 ,
 193 .Xr wlan_ccmp 4 ,
 194 .Xr wlan_tkip 4 ,
 195 .Xr wlan_wep 4 ,
 196 .Xr wlan_xauth 4 ,
 197 .Xr wpi 4 ,
 198 .Xr zyd 4
 199 .Sh STANDARDS
 200 More information can be found in the IEEE 802.11 Standards.
 201 .Sh HISTORY
 202 The
 203 .Nm
 204 driver first appeared in
 205 .Fx 5.0 .
 206 .Sh AUTHORS
 207 Atsushi Onoe is the author of original
 208 .Nx
 209 software from which this work began.
 210 .An -nosplit
 211 .An Sam Leffler
 212 brought the code into
 213 .Fx
 214 and then rewrote it to support multi-mode devices,
 215 802.11g, 802.11n, WPA/802.11i, WME, multi-bss, and
 216 add the extensible frameworks
 217 for cryptographic, authentication, and access control plugins.
 218 This manual page was written by
 219 .An Tom Rhodes Aq Mt trhodes@FreeBSD.org .