iwi(4): Hook it into the build again and enable it everywhere else.
[dragonfly.git] / share / man / man4 / wlan.4
CommitLineData
4f6e3ad1
SZ
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.\"
fe3d6ebe 26.\" $FreeBSD: src/share/man/man4/wlan.4,v 1.23 2010/01/14 09:38:23 roam Exp $
4f6e3ad1 27.\"
fe3d6ebe 28.Dd April 14, 2010
4f6e3ad1
SZ
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
37The
38.Nm
39module provides generic code to support 802.11 drivers.
40Where a device does not directly support 802.11 functionality
41this layer fills in.
42The
43.Nm
fe3d6ebe
SW
44module is required by all native 802.11 drivers.
45.\" as well as the
46.\".Xr ndis 4
47.\"support.
4f6e3ad1 48.Pp
4f6e3ad1 49.Nm
fe3d6ebe 50supports multi-mode devices capable of
4f6e3ad1 51operating in both 2.4GHz and 5GHz bands and supports numerous
fe3d6ebe 52802.11 standards: 802.11a, 802.11b, 802.11g, 802.11n, and 802.11s (Draft 3.0).
4f6e3ad1
SZ
53The WPA, 802.11i, and 802.1x security protocols are supported
54through a combination of in-kernel code and user-mode applications.
fe3d6ebe 55The WME/WMM multi-media protocols are supported entirely within
4f6e3ad1
SZ
56the
57.Nm
58module but require a suitably capable hardware device.
fe3d6ebe
SW
59Likewise the 802.11h specification is supported only by suitably
60capable devices.
4f6e3ad1 61.Pp
fe3d6ebe 62Drivers provide 802.11 functionality through
4f6e3ad1 63.Nm
fe3d6ebe
SW
64interfaces that are created at runtime using interface cloning.
65This is done with the
66.Xr ifconfig 8
67.Cm create
68command or using the
69.Va wlans_IFX
70variable in
71.Xr rc.conf 5 .
72Some drivers support the creation of multiple
4f6e3ad1 73.Nm
fe3d6ebe
SW
74interfaces that share the same underlying device;
75this is the way by which ``multi-bss support'' is provided but it
76can also be used to create WDS links and other interesting applications.
4f6e3ad1 77.Pp
fe3d6ebe
SW
78There are several types of
79.Nm
80interfaces that may be created:
81.Bl -tag -width monitor
82.It Cm sta
83A client station in an infrastructure bss
84(i.e. one that associates to an access point).
85.It Cm hostap
86An access point in an infrastructure bss.
87.It Cm mesh
88A mesh station in an MBSS network.
89.It Cm adhoc
90A station in an IBSS network.
91.It Cm ahdemo
92A station operating in ``adhoc demo mode''.
93This is essentially an IBSS station that does not use management
94frames (e.g. no beacons are transmitted).
95An
96.Cm ahdemo
97interface is especially useful for applications that want to transmit
98and receive raw 802.11 packets.
99.It Cm monitor
100An interface used exclusively for capturing 802.11 frames.
101In particular this specified to have read-only properties
102which enables it to be operated on frequencies where one
103would otherwise not be allowed.
104.It Cm wds
105A station that passes 4-address 802.11 traffic for the purpose
106of tunneling traffic over a wireless link.
107Typically this station would share the same MAC address as a
108.Cm hostap
109interface.
110It may be possible to create
111.Cm wds
112interfaces without a companion
113.Cm hostap
114interface but that is not guaranteed; one may need to create a
115.Cm hostap
116interface that does not send beacon frames before
117.Cm wds
118interfaces may be created.
119.El
e2802b20 120.Pp
fe3d6ebe 121Note that an interface's type cannot be changed once it is created.
e2802b20 122.Pp
fe3d6ebe
SW
123.Nm
124defines several mechanisms by which plugin modules may
125be used to extend its' functionality.
126Cryptographic support such as WEP, TKIP, and AES-CCMP are implemented
127as standalone modules (if not statically configured into a system)
128that register with
129.Nm .
130Similarly there is an authenticator framework for defining 802.11
131authentication services and a framework for integrating access
132control mechanisms specific to the 802.11 protocol.
133.\".Sh EXAMPLES
134.\"Join an existing BSS network (i.e., connect to an access point):
135.\".Pp
136.\".Dl "ifconfig iface 192.168.0.20/24"
137.\".Pp
138.\"Join a specific BSS network with network name
139.\".Dq Li my_net :
140.\".Pp
141.\".Dl "ifconfig iface 192.168.0.20/24 ssid my_net"
142.\".Pp
143.\"Join a specific BSS network with 64 bit WEP encryption:
144.\".Bd -literal -offset indent
145.\"ifconfig iface 192.168.0.20/24 ssid my_net wepmode on \e
146.\" wepkey 0x1234567890 weptxkey 1
147.\".Ed
148.\".Pp
149.\"Join a specific BSS network with 128 bit WEP encryption:
150.\".Bd -literal -offset indent
151.\"ifconfig iface 192.168.0.20/24 ssid my_net wepmode on \e
152.\" wepkey 0x01020304050607080910111213 weptxkey 1
153.\".Ed
154.\".Pp
155.\"Join/create an 802.11b IBSS network:
156.\".Bd -literal -offset indent
157.\"ifconfig iface 192.168.0.20/24 ssid my_net mediaopt adhoc
158.\".Ed
159.\".Pp
160.\"To debug a network setup, you may wish to enable interface debugging:
161.\".Bd -literal -offset indent
162.\"ifconfig iface down debug up
163.\".Ed
164.\".Pp
165.\"To disable debugging, you may simply use:
166.\".Bd -literal -offset indent
167.\"ifconfig iface down -debug up
168.\".Ed
e2802b20
SW
169.\".Pp
170.\"Create an 802.11g host-based access point:
171.\".Bd -literal -offset indent
172.\"ifconfig iface 192.168.0.20/24 ssid my_net mode 11g mediaopt hostap
173.\".Ed
174.\".Pp
175.\"Create an 802.11a host-based access point with WEP enabled:
176.\".Bd -literal -offset indent
177.\"ifconfig iface 192.168.0.20/24 ssid my_net wepmode on \e
178.\" wepkey 0x1234567890 weptxkey 1 mode 11a mediaopt hostap
179.\".Ed
180.\".Pp
181.\"Create a host-based wireless bridge to fxp0:
182.\".Bd -literal -offset indent
183.\"ifconfig iface up ssid my_net media DS/11Mbps mediaopt hostap
184.\"sysctl net.inet.ip.check_interface=0
185.\"ifconfig bridge0 create
186.\"ifconfig bridge0 addm iface1 addm iface2 up
187.\".Ed
188.\".Pp
189.\"This will give you the same functionality as an access point.
fe3d6ebe
SW
190.Sh DEBUGGING
191If the
192.Dv IEEE80211_DEBUG
193option is included in the kernel configuration,
194debugging controls are available using:
195.Pp
196.Dl "sysctl net.wlan.X.debug=mask"
197.Pp
198where
199.Ar X
200is the number of the
201.Nm
202instance and mask is a bit-or of control bits that determine which
203debugging messages to enable.
204For example,
205.Pp
206.Dl "sysctl net.wlan.0.debug=0x00200000"
207.Pp
208enables debugging messages related to scanning for an access point,
209adhoc neighbor, or an unoccupied channel when operation as an access point.
210The
211.Xr wlandebug 8
212tool provides a more user-friendly mechanism for doing the same thing.
213Note that
214.Pp
215.Dl "sysctl net.wlan.debug=mask"
216.Pp
217defines the initial value of the debugging flags for each cloned
218.Nm
219interface; this is useful to enable debug messages during interface creation.
4f6e3ad1
SZ
220.Sh COMPATIBILITY
221The module name of
222.Nm
223was used to be compatible with
224.Nx .
fe3d6ebe
SW
225.Pp
226Mesh stations follow the 802.11s Draft 3.0 specification which is
227not ratified and subject to change.
228Beware that this specification is incompatible with earlier drafts;
229and stations implementing earlier drafts (e.g. Linux)
230may not interoperate.
4f6e3ad1 231.Sh SEE ALSO
fe3d6ebe
SW
232.\".Xr acx 4 ,
233.Xr an 4 ,
383e250a 234.Xr ath 4 ,
fe3d6ebe
SW
235.\".Xr bwi 4 ,
236.\".Xr ipw 4 ,
1d97534a 237.Xr iwi 4 ,
fe3d6ebe
SW
238.\".Xr iwl 4 ,
239.\".Xr iwn 4 ,
240.\".Xr malo 4 ,
4f6e3ad1 241.Xr netintro 4 ,
383e250a 242.Xr ral 4 ,
fe3d6ebe
SW
243.\".Xr rtw 4 ,
244.\".Xr rum 4 ,
245.\".Xr uath 4 ,
246.\".Xr upgt 4 ,
247.\".Xr ural 4 ,
248.\".Xr urtw 4 ,
4f6e3ad1
SZ
249.Xr wi 4 ,
250.Xr wlan_acl 4 ,
fe3d6ebe 251.Xr wlan_amrr 4 ,
4f6e3ad1
SZ
252.Xr wlan_ccmp 4 ,
253.Xr wlan_tkip 4 ,
254.Xr wlan_wep 4 ,
7fa17bc6
SW
255.Xr wlan_xauth 4 ,
256.Xr wpi 4
fe3d6ebe 257.\".Xr zyd 4
4f6e3ad1 258.Sh STANDARDS
fe3d6ebe 259More information can be found in the IEEE 802.11 Standards.
4f6e3ad1
SZ
260.Sh HISTORY
261The
262.Nm
263driver first appeared in
264.Fx 5.0 .
265.Sh AUTHORS
266Atsushi Onoe is the author of original
267.Nx
268software from which this work began.
269.An -nosplit
270.An Sam Leffler
271brought the code into
272.Fx
273and then rewrote it to support multi-mode devices,
fe3d6ebe
SW
274802.11g, 802.11n, WPA/802.11i, WME, multi-bss, and
275add the extensible frameworks
4f6e3ad1
SZ
276for cryptographic, authentication, and access control plugins.
277This manual page was written by
278.An Tom Rhodes Aq trhodes@FreeBSD.org .