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: src/share/man/man4/wlan.4,v 1.23 2010/01/14 09:38:23 roam Exp $
  27 .\"
  28 .Dd April 14, 2010
  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 .\" as well as the
  46 .\".Xr ndis 4
  47 .\"support.
  48 .Pp
  49 .Nm
  50 supports multi-mode devices capable of
  51 operating in both 2.4GHz and 5GHz bands and supports numerous
  52 802.11 standards: 802.11a, 802.11b, 802.11g, 802.11n, and 802.11s (Draft 3.0).
  53 The WPA, 802.11i, and 802.1x security protocols are supported
  54 through a combination of in-kernel code and user-mode applications.
  55 The WME/WMM multi-media protocols are supported entirely within
  56 the
  57 .Nm
  58 module but require a suitably capable hardware device.
  59 Likewise the 802.11h specification is supported only by suitably
  60 capable devices.
  61 .Pp
  62 Drivers provide 802.11 functionality through
  63 .Nm
  64 interfaces that are created at runtime using interface cloning.
  65 This is done with the
  66 .Xr ifconfig 8
  67 .Cm create
  68 command or using the
  69 .Va wlans_IFX
  70 variable in
  71 .Xr rc.conf 5 .
  72 Some drivers support the creation of multiple
  73 .Nm
  74 interfaces that share the same underlying device;
  75 this is the way by which ``multi-bss support'' is provided but it
  76 can also be used to create WDS links and other interesting applications.
  77 .Pp
  78 There are several types of
  79 .Nm
  80 interfaces that may be created:
  81 .Bl -tag -width monitor
  82 .It Cm sta
  83 A client station in an infrastructure bss
  84 (i.e. one that associates to an access point).
  85 .It Cm hostap
  86 An access point in an infrastructure bss.
  87 .It Cm mesh
  88 A mesh station in an MBSS network.
  89 .It Cm adhoc
  90 A station in an IBSS network.
  91 .It Cm ahdemo
  92 A station operating in ``adhoc demo mode''.
  93 This is essentially an IBSS station that does not use management
  94 frames (e.g. no beacons are transmitted).
  95 An
  96 .Cm ahdemo
  97 interface is especially useful for applications that want to transmit
  98 and receive raw 802.11 packets.
  99 .It Cm monitor
 100 An interface used exclusively for capturing 802.11 frames.
 101 In particular this specified to have read-only properties
 102 which enables it to be operated on frequencies where one
 103 would otherwise not be allowed.
 104 .It Cm wds
 105 A station that passes 4-address 802.11 traffic for the purpose
 106 of tunneling traffic over a wireless link.
 107 Typically this station would share the same MAC address as a
 108 .Cm hostap
 109 interface.
 110 It may be possible to create
 111 .Cm wds
 112 interfaces without a companion
 113 .Cm hostap
 114 interface but that is not guaranteed; one may need to create a
 115 .Cm hostap
 116 interface that does not send beacon frames before
 117 .Cm wds
 118 interfaces may be created.
 119 .El
 120 .Pp
 121 Note that an interface's type cannot be changed once it is created.
 122 .Pp
 123 .Nm
 124 defines several mechanisms by which plugin modules may
 125 be used to extend its' functionality.
 126 Cryptographic support such as WEP, TKIP, and AES-CCMP are implemented
 127 as standalone modules (if not statically configured into a system)
 128 that register with
 129 .Nm .
 130 Similarly there is an authenticator framework for defining 802.11
 131 authentication services and a framework for integrating access
 132 control 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
 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.
 190 .Sh DEBUGGING
 191 If the
 192 .Dv IEEE80211_DEBUG
 193 option is included in the kernel configuration,
 194 debugging controls are available using:
 195 .Pp
 196 .Dl "sysctl net.wlan.X.debug=mask"
 197 .Pp
 198 where
 199 .Ar X
 200 is the number of the
 201 .Nm
 202 instance and mask is a bit-or of control bits that determine which
 203 debugging messages to enable.
 204 For example,
 205 .Pp
 206 .Dl "sysctl net.wlan.0.debug=0x00200000"
 207 .Pp
 208 enables debugging messages related to scanning for an access point,
 209 adhoc neighbor, or an unoccupied channel when operation as an access point.
 210 The
 211 .Xr wlandebug 8
 212 tool provides a more user-friendly mechanism for doing the same thing.
 213 Note that
 214 .Pp
 215 .Dl "sysctl net.wlan.debug=mask"
 216 .Pp
 217 defines the initial value of the debugging flags for each cloned
 218 .Nm
 219 interface; this is useful to enable debug messages during interface creation.
 220 .Sh COMPATIBILITY
 221 The module name of
 222 .Nm
 223 was used to be compatible with
 224 .Nx .
 225 .Pp
 226 Mesh stations follow the 802.11s Draft 3.0 specification which is
 227 not ratified and subject to change.
 228 Beware that this specification is incompatible with earlier drafts;
 229 and stations implementing earlier drafts (e.g. Linux)
 230 may not interoperate.
 231 .Sh SEE ALSO
 232 .\".Xr acx 4 ,
 233 .Xr an 4 ,
 234 .Xr ath 4 ,
 235 .\".Xr bwi 4 ,
 236 .\".Xr ipw 4 ,
 237 .Xr iwi 4 ,
 238 .\".Xr iwl 4 ,
 239 .\".Xr iwn 4 ,
 240 .\".Xr malo 4 ,
 241 .Xr netintro 4 ,
 242 .Xr ral 4 ,
 243 .\".Xr rtw 4 ,
 244 .\".Xr rum 4 ,
 245 .\".Xr uath 4 ,
 246 .\".Xr upgt 4 ,
 247 .\".Xr ural 4 ,
 248 .\".Xr urtw 4 ,
 249 .Xr wi 4 ,
 250 .Xr wlan_acl 4 ,
 251 .Xr wlan_amrr 4 ,
 252 .Xr wlan_ccmp 4 ,
 253 .Xr wlan_tkip 4 ,
 254 .Xr wlan_wep 4 ,
 255 .Xr wlan_xauth 4 ,
 256 .Xr wpi 4
 257 .\".Xr zyd 4
 258 .Sh STANDARDS
 259 More information can be found in the IEEE 802.11 Standards.
 260 .Sh HISTORY
 261 The
 262 .Nm
 263 driver first appeared in
 264 .Fx 5.0 .
 265 .Sh AUTHORS
 266 Atsushi Onoe is the author of original
 267 .Nx
 268 software from which this work began.
 269 .An -nosplit
 270 .An Sam Leffler
 271 brought the code into
 272 .Fx
 273 and then rewrote it to support multi-mode devices,
 274 802.11g, 802.11n, WPA/802.11i, WME, multi-bss, and
 275 add the extensible frameworks
 276 for cryptographic, authentication, and access control plugins.
 277 This manual page was written by
 278 .An Tom Rhodes Aq trhodes@FreeBSD.org .