Add rtw(4) manual page.
[dragonfly.git] / share / man / man4 / rtw.4
1 .\"     $NetBSD: rtw.4,v 1.3 2005/09/09 14:11:39 drochner Exp $
2 .\"     $OpenBSD: rtw.4,v 1.18 2005/06/09 09:03:38 jmc Exp $
3 .\"     $DragonFly: src/share/man/man4/rtw.4,v 1.1 2006/09/03 20:02:06 swildner Exp $
4 .\"
5 .\" Copyright (c) 2004 Jonathan Gray <jsg@openbsd.org>
6 .\"
7 .\" Permission to use, copy, modify, and distribute this software for any
8 .\" purpose with or without fee is hereby granted, provided that the above
9 .\" copyright notice and this permission notice appear in all copies.
10 .\"
11 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
12 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
13 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
14 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
15 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
16 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
17 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18 .\"
19 .Dd September 3, 2006
20 .Dt RTW 4
21 .Os
22 .Sh NAME
23 .Nm rtw
24 .Nd Realtek RTL8180L IEEE 802.11b wireless network driver
25 .Sh SYNOPSIS
26 To compile this driver into the kernel,
27 place the following lines in your
28 kernel configuration file:
29 .Bd -ragged -offset indent
30 .Cd "device rtw"
31 .Cd "device wlan"
32 .Ed
33 .Pp
34 Alternatively, to load the driver as a
35 module at boot time, place the following line in
36 .Xr loader.conf 5 :
37 .Bd -literal -offset indent
38 if_rtw_load="YES"
39 .Ed
40 .Sh DESCRIPTION
41 The
42 .Nm
43 driver supports PCI/CardBus 802.11b wireless adapters based on the
44 Realtek RTL8180L.
45 .Pp
46 A variety of radio tranceivers can be found in these devices, including
47 the Philips SA2400A, Maxim MAX2820, and GCT GRF5101, though not all of them
48 are currently supported.
49 .Pp
50 These are the modes the
51 .Nm
52 driver can operate in:
53 .Bl -tag -width "monitor mode"
54 .It BSS mode
55 Also known as
56 .Em infrastructure
57 mode, this is used when associating with an access point, through
58 which all traffic passes.
59 This mode is the default.
60 .It IBSS mode
61 Also known as
62 .Em IEEE ad-hoc
63 mode or
64 .Em peer-to-peer
65 mode.
66 This is the standardized method of operating without an access point.
67 Stations associate with a service set.
68 However, actual connections between stations are peer-to-peer.
69 .It Host AP
70 In this mode the driver acts as an access point (base station)
71 for other cards.
72 .It monitor mode
73 In this mode the driver is able to receive packets without
74 associating with an access point.
75 This disables the internal receive filter and enables the card to
76 capture packets from networks which it wouldn't normally have access to,
77 or to scan for access points.
78 .El
79 .Pp
80 .Nm
81 supports software WEP.
82 Wired Equivalent Privacy (WEP) is the de facto encryption standard
83 for wireless networks.
84 It can be typically configured in one of three modes:
85 no encryption; 40-bit encryption; or 104-bit encryption.
86 Unfortunately, due to serious weaknesses in WEP protocol
87 it is strongly recommended that it not be used as the
88 sole mechanism to secure wireless communication.
89 WEP is not enabled by default.
90 .Sh CONFIGURATION
91 The
92 .Nm
93 driver can be configured at runtime with
94 .Xr ifconfig 8
95 using the following parameters:
96 .Bl -tag -width ".Fl mediaopt Ar opts"
97 .It Cm bssid Ar bssid
98 Set the desired BSSID.
99 .It Fl bssid
100 Unset the desired BSSID.
101 The interface will automatically select a BSSID in this mode, which is
102 the default.
103 .It Cm chan Ar n
104 Set the channel (radio frequency) to be used by the driver based on
105 the given channel ID
106 .Ar n .
107 .It Fl chan
108 Unset the desired channel to be used by the driver.
109 The driver will automatically select a channel in this mode, which is
110 the default.
111 .It Cm media Ar media
112 The
113 .Nm
114 driver supports the following
115 .Ar media
116 types:
117 .Pp
118 .Bl -tag -width ".Cm autoselect" -compact
119 .It Cm autoselect
120 Enable autoselection of the media type and options.
121 .It Cm DS1
122 Set 802.11b DS 1Mbps operation.
123 .It Cm DS2
124 Set 802.11b DS 2Mbps operation.
125 .It Cm DS5
126 Set 802.11b DS 5.5Mbps operation.
127 .It Cm DS11
128 Set 802.11b DS 11Mbps operation.
129 .El
130 .It Cm mediaopt Ar opts
131 The
132 .Nm
133 driver supports the following media options:
134 .Pp
135 .Bl -tag -width ".Cm monitor" -compact
136 .It Cm hostap
137 Select Host AP operation.
138 .It Cm ibss
139 Select IBSS operation.
140 .It Cm monitor
141 Select monitor mode.
142 .El
143 .It Fl mediaopt Ar opts
144 Disable the specified media options on the driver and return it to the
145 default mode of operation (BSS).
146 .It Cm ssid Ar id
147 Set the network ID.
148 The
149 .Ar id
150 can either be any text string up to 32 characters in length,
151 or a series of hexadecimal digits up to 64 digits.
152 An empty
153 .Ar id
154 string allows the interface to connect to any available access points.
155 By default the
156 .Nm
157 driver uses an empty string.
158 Note that network ID is synonymous with Extended Service Set ID (ESSID).
159 .It Cm nwkey Ar key
160 Enable WEP encryption using the specified
161 .Ar key .
162 The
163 .Ar key
164 can either be a string, a series of hexadecimal digits (preceded by
165 .Sq 0x ) ,
166 or a set of keys of the form
167 .Dq n:k1,k2,k3,k4 ,
168 where
169 .Sq n
170 specifies which of the keys will be used for transmitted packets,
171 and the four keys,
172 .Dq k1
173 through
174 .Dq k4 ,
175 are configured as WEP keys.
176 If a set of keys is specified, a comma
177 .Pq Sq \&,
178 within the key must be escaped with a backslash.
179 Note that if multiple keys are used, their order must be the same within
180 the network.
181 .Nm
182 is capable of using both 40-bit (5 characters or 10 hexadecimal digits)
183 or 104-bit (13 characters or 26 hexadecimal digits) keys.
184 .It Fl nwkey
185 Disable WEP encryption.
186 This is the default mode of operation.
187 .It Cm nwkey persist
188 Enable WEP encryption with the persistent key stored in the network card.
189 .El
190 .Sh HARDWARE
191 The following adapters should work:
192 .Pp
193 .Bl -column -compact ".Li Ovislink AirLive WL-1120PCM" "CardBus"
194 .It Em Card Ta Em Bus
195 .\".It Li "Acer Aspire 1357 LMi" Ta Mini PCI
196 .\".It Li "Belkin F5D6001 V3" Ta PCI
197 .It Li "Belkin F5D6020 V3" Ta CardBus
198 .It Li "Buffalo WLI-CB-B11" Ta CardBus
199 .It Li "Corega CG-WLCB11V3" Ta CardBus
200 .\".It Li "D-Link DWL-510" Ta PCI
201 .\".It Li "D-Link DWL-520 rev D" Ta PCI
202 .It Li "D-Link DWL-610" Ta CardBus
203 .\".It Li "Encore ENLWI-PCI1-NT" Ta PCI
204 .\".It Li "Gigabyte GN-WLMR101" Ta PCI
205 .It Li "Level-One WPC-0101" Ta CardBus
206 .It Li "Linksys WPC11 v4" Ta CardBus
207 .It Li "Netgear MA521" Ta CardBus
208 .It Li "Ovislink AirLive WL-1120PCM" Ta CardBus
209 .It Li "Planet WL-3553" Ta CardBus
210 .It Li "TrendNET TEW-266PC" Ta CardBus
211 .\".It Li "TrendNET TEW-288PI" Ta PCI
212 .It Li "VCTnet PC-11B1" Ta CardBus
213 .El
214 .Sh EXAMPLES
215 .\"Create a host-based access point on boot:
216 .\".Bd -literal -offset indent
217 .\"# ifconfig inet 192.168.1.1 netmask 0xffffff00 media autoselect \e
218 .\"     mediaopt hostap ssid my_net chan 11
219 .\".Ed
220 .\".Pp
221 Configure rtw0 for WEP, using hex key
222 .Dq 0x1deadbeef1 :
223 .Bd -literal -offset indent
224 # ifconfig rtw0 nwkey 0x1deadbeef1
225 .Ed
226 .Pp
227 Return rtw0 to its default settings:
228 .Bd -literal -offset indent
229 # ifconfig rtw0 -bssid -chan media autoselect \e
230         ssid "" -nwkey
231 .Ed
232 .Pp
233 Join an existing BSS network,
234 .Dq my_net :
235 .Bd -literal -offset indent
236 # ifconfig rtw0 192.168.1.1 netmask 0xffffff00 ssid my_net
237 .Ed
238 .Sh SEE ALSO
239 .Xr arp 4 ,
240 .Xr cardbus 4 ,
241 .\".Xr ifmedia 4 ,
242 .Xr intro 4 ,
243 .Xr netintro 4 ,
244 .Xr pci 4 ,
245 .Xr ifconfig 8
246 .Rs
247 .%T Realtek
248 .%O http://www.realtek.com.tw
249 .Re
250 .Sh HISTORY
251 The
252 .Nm
253 device driver first appeared in
254 .Nx 3.0
255 and then in
256 .Ox 3.7 .
257 It was imported into
258 .Dx 1.7 .
259 .Sh AUTHORS
260 .An -nosplit
261 The
262 .Nm
263 driver was written by
264 .An David Young
265 .Aq dyoung@NetBSD.org
266 and ported to
267 .Ox
268 by
269 .An Jonathan Gray Aq jsg@openbsd.org ,
270 who wrote this man page.
271 The
272 .Dx
273 port was done by
274 .An Sepherosa Ziehau
275 .Aq sepherosa@gmail.com .
276 .Sh BUGS
277 Only the Philips SA2400A and Maxim MAX2820 RF transceivers are known to work.
278 Devices incorporating a GCT RF transceiver are not supported due to a lack of
279 documentation from GCT.
280 .Pp
281 While PCI devices will attach most of them are not able to transmit.