Clean up the USB driver directories, remove unbuilt source.
[dragonfly.git] / 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: head/share/man/man4/wlan.4 290127 2015-10-29 03:22:27Z kevlo $
27 .\"
28 .Dd May 26, 2016
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 as well as the
45 .Xr ndis 4
46 support.
47 .Pp
48 .Nm
49 supports multi-mode devices capable of
50 operating in both 2.4GHz and 5GHz bands and supports numerous
51 802.11 standards: 802.11a, 802.11b, 802.11g, 802.11n, and 802.11s (Draft 3.0).
52 The WPA, 802.11i, and 802.1x security protocols are supported
53 through a combination of in-kernel code and user-mode applications.
54 The WME/WMM multi-media protocols are supported entirely within
55 the
56 .Nm
57 module but require a suitably capable hardware device.
58 Likewise the 802.11h specification is supported only by suitably
59 capable devices.
60 .Pp
61 Drivers provide 802.11 functionality through
62 .Nm
63 interfaces that are created at runtime using interface cloning.
64 This is done with the
65 .Xr ifconfig 8
66 .Cm create
67 command or using the
68 .Va wlans_IFX
69 variable in
70 .Xr rc.conf 5 .
71 Some drivers support the creation of multiple
72 .Nm
73 interfaces that share the same underlying device;
74 this is the way by which ``multi-bss support'' is provided but it
75 can also be used to create WDS links and other interesting applications.
76 .Pp
77 There are several types of
78 .Nm
79 interfaces that may be created:
80 .Bl -tag -width monitor
81 .It Cm sta
82 A client station in an infrastructure bss
83 (i.e. one that associates to an access point).
84 .It Cm hostap
85 An access point in an infrastructure bss.
86 .It Cm mesh
87 A mesh station in an MBSS network.
88 .It Cm adhoc
89 A station in an IBSS network.
90 .It Cm ahdemo
91 A station operating in ``adhoc demo mode''.
92 This is essentially an IBSS station that does not use management
93 frames (e.g. no beacons are transmitted).
94 An
95 .Cm ahdemo
96 interface is especially useful for applications that want to transmit
97 and receive raw 802.11 packets.
98 .It Cm monitor
99 An interface used exclusively for capturing 802.11 frames.
100 In particular this specified to have read-only properties
101 which enables it to be operated on frequencies where one
102 would otherwise not be allowed.
103 .It Cm wds
104 A station that passes 4-address 802.11 traffic for the purpose
105 of tunneling traffic over a wireless link.
106 Typically this station would share the same MAC address as a
107 .Cm hostap
108 interface.
109 It may be possible to create
110 .Cm wds
111 interfaces without a companion
112 .Cm hostap
113 interface but that is not guaranteed; one may need to create a
114 .Cm hostap
115 interface that does not send beacon frames before
116 .Cm wds
117 interfaces may be created.
118 .El
119 .Pp
120 Note that an interface's type cannot be changed once it is created.
121 .Pp
122 .Nm
123 defines several mechanisms by which plugin modules may
124 be used to extend its functionality.
125 Cryptographic support such as WEP, TKIP, and AES-CCMP are implemented
126 as standalone modules (if not statically configured into a system)
127 that register with
128 .Nm .
129 Similarly there is an authenticator framework for defining 802.11
130 authentication services and a framework for integrating access
131 control mechanisms specific to the 802.11 protocol.
132 .Sh DEBUGGING
133 If the
134 .Dv IEEE80211_DEBUG
135 option is included in the kernel configuration,
136 debugging controls are available using:
137 .Pp
138 .Dl "sysctl net.wlan.X.debug=mask"
139 .Pp
140 where
141 .Ar X
142 is the number of the
143 .Nm
144 instance and mask is a bit-or of control bits that determine which
145 debugging messages to enable.
146 For example,
147 .Pp
148 .Dl "sysctl net.wlan.0.debug=0x00200000"
149 .Pp
150 enables debugging messages related to scanning for an access point,
151 adhoc neighbor, or an unoccupied channel when operation as an access point.
152 The
153 .Xr wlandebug 8
154 tool provides a more user-friendly mechanism for doing the same thing.
155 Note that
156 .Pp
157 .Dl "sysctl net.wlan.debug=mask"
158 .Pp
159 defines the initial value of the debugging flags for each cloned
160 .Nm
161 interface; this is useful to enable debug messages during interface creation.
162 .Sh COMPATIBILITY
163 The module name of
164 .Nm
165 was used to be compatible with
166 .Nx .
167 .Pp
168 Mesh stations follow the 802.11s Draft 3.0 specification which is
169 not ratified and subject to change.
170 Beware that this specification is incompatible with earlier drafts;
171 and stations implementing earlier drafts (e.g. Linux)
172 may not interoperate.
173 .Sh SEE ALSO
174 .Xr ath 4 ,
175 .\".Xr bwi 4 ,
176 .Xr bwn 4 ,
177 .\".Xr ipw 4 ,
178 .Xr iwi 4 ,
179 .Xr iwm 4 ,
180 .Xr iwn 4 ,
181 .\".Xr malo 4 ,
182 .\".Xr mwl 4 ,
183 .Xr netintro 4 ,
184 .\".Xr otus 4 ,
185 .Xr ral 4 ,
186 .\".Xr rsu 4 ,
187 .Xr rum 4 ,
188 .Xr run 4 ,
189 .Xr urtwn 4 ,
190 .Xr wi 4 ,
191 .Xr wlan_acl 4 ,
192 .Xr wlan_ccmp 4 ,
193 .Xr wlan_tkip 4 ,
194 .Xr wlan_wep 4 ,
195 .Xr wlan_xauth 4 ,
196 .Xr wpi 4
197 .Sh STANDARDS
198 More information can be found in the IEEE 802.11 Standards.
199 .Sh HISTORY
200 The
201 .Nm
202 driver first appeared in
203 .Fx 5.0 .
204 .Sh AUTHORS
205 .An -nosplit
206 .An Atsushi Onoe
207 is the author of the original
208 .Nx
209 software from which this work began.
210 .An Sam Leffler
211 brought the code into
212 .Fx
213 and then rewrote it to support multi-mode devices,
214 802.11g, 802.11n, WPA/802.11i, WME, multi-bss, and
215 add the extensible frameworks
216 for cryptographic, authentication, and access control plugins.
217 This manual page was written by
218 .An Tom Rhodes Aq Mt trhodes@FreeBSD.org .