No empty .Rs/.Re
[netbsd-mini2440.git] / share / man / man4 / rum.4
blobbd9a59e569a45af8f728aa8c22358f9ec8db7ae4
1 .\" $OpenBSD: rum.4,v 1.17 2006/10/22 08:29:01 damien Exp $
2 .\" $NetBSD: rum.4,v 1.4 2007/02/06 23:42:34 wiz Exp $
3 .\"
4 .\" Copyright (c) 2005, 2006
5 .\"     Damien Bergamini <damien.bergamini@free.fr>
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 February 7, 2007
20 .Dt RUM 4
21 .Os
22 .Sh NAME
23 .Nm rum
24 .Nd Ralink Technology USB IEEE 802.11a/b/g wireless network device
25 .Sh SYNOPSIS
26 .Cd "rum* at uhub? port ?"
27 .Sh DESCRIPTION
28 The
29 .Nm
30 driver supports USB 2.0 wireless adapters based on the Ralink RT2501USB
31 and RT2601USB chipsets.
32 .Pp
33 The RT2501USB chipset is the second generation of 802.11a/b/g adapters from
34 Ralink.
35 It consists of two integrated chips, an RT2571W MAC/BBP and an RT2528 or
36 RT5226 radio transceiver.
37 .Pp
38 The RT2601USB chipset consists of two integrated chips, an RT2671 MAC/BBP and
39 an RT2527 or RT5225 radio transceiver.
40 This chipset uses the MIMO (multiple-input multiple-output) technology with
41 multiple antennas to extend the operating range of the adapter and to achieve
42 higher throughput.
43 MIMO is the basis of the forthcoming IEEE 802.11n standard.
44 .Pp
45 These are the modes the
46 .Nm
47 driver can operate in:
48 .Bl -tag -width "IBSS-masterXX"
49 .It BSS mode
50 Also known as
51 .Em infrastructure
52 mode, this is used when associating with an access point, through
53 which all traffic passes.
54 This mode is the default.
55 .It IBSS mode
56 Also known as
57 .Em IEEE ad-hoc
58 mode or
59 .Em peer-to-peer
60 mode.
61 This is the standardized method of operating without an access point.
62 Stations associate with a service set.
63 However, actual connections between stations are peer-to-peer.
64 .It Host AP
65 In this mode the driver acts as an access point (base station)
66 for other cards.
67 .It monitor mode
68 In this mode the driver is able to receive packets without
69 associating with an access point.
70 This disables the internal receive filter and enables the card to
71 capture packets from networks which it wouldn't normally have access to,
72 or to scan for access points.
73 .El
74 .Pp
75 .Nm
76 supports software WEP.
77 Wired Equivalent Privacy (WEP) is the de facto encryption standard
78 for wireless networks.
79 It can be typically configured in one of three modes:
80 no encryption; 40-bit encryption; or 104-bit encryption.
81 Unfortunately, due to serious weaknesses in WEP protocol
82 it is strongly recommended that it not be used as the
83 sole mechanism to secure wireless communication.
84 WEP is not enabled by default.
85 .Sh CONFIGURATION
86 The
87 .Nm
88 driver can be configured at runtime with
89 .Xr ifconfig 8
90 or on boot with
91 .Xr ifconfig.if 5
92 using the following parameters:
93 .Bl -tag -width Ds
94 .It Cm bssid Ar bssid
95 Set the desired BSSID.
96 .It Fl bssid
97 Unset the desired BSSID.
98 The interface will automatically select a BSSID in this mode, which is
99 the default.
100 .It Cm chan Ar n
101 Set the channel (radio frequency) to be used by the driver based on
102 the given channel ID
103 .Ar n .
104 .It Fl chan
105 Unset the desired channel to be used by the driver.
106 The driver will automatically select a channel in this mode, which is
107 the default.
108 .It Cm media Ar media
111 driver supports the following
112 .Ar media
113 types:
115 .Bl -tag -width autoselect -compact
116 .It Cm autoselect
117 Enable autoselection of the media type and options.
118 .It Cm DS1
119 Set 802.11b DS 1Mbps operation.
120 .It Cm DS2
121 Set 802.11b DS 2Mbps operation.
122 .It Cm DS5
123 Set 802.11b DS 5.5Mbps operation.
124 .It Cm DS11
125 Set 802.11b DS 11Mbps operation.
126 .It Cm OFDM6
127 Set 802.11a/g OFDM 6Mbps operation.
128 .It Cm OFDM9
129 Set 802.11a/g OFDM 9Mbps operation.
130 .It Cm OFDM12
131 Set 802.11a/g OFDM 12Mbps operation.
132 .It Cm OFDM18
133 Set 802.11a/g OFDM 18Mbps operation.
134 .It Cm OFDM24
135 Set 802.11a/g OFDM 24Mbps operation.
136 .It Cm OFDM36
137 Set 802.11a/g OFDM 36Mbps operation.
138 .It Cm OFDM48
139 Set 802.11a/g OFDM 48Mbps operation.
140 .It Cm OFDM54
141 Set 802.11a/g OFDM 54Mbps operation.
143 .It Cm mediaopt Ar opts
146 driver supports the following media options:
148 .Bl -tag -width monitor -compact
149 .It Cm hostap
150 Select Host AP operation.
151 .It Cm ibss
152 Select IBSS operation.
153 .It Cm monitor
154 Select monitor mode.
156 .It Fl mediaopt Ar opts
157 Disable the specified media options on the driver and return it to the
158 default mode of operation (BSS).
159 .It Cm mode Ar mode
162 driver supports the following modes:
164 .Bl -tag -width 11b -compact
165 .It Cm 11a
166 Force 802.11a operation.
167 .It Cm 11b
168 Force 802.11b operation.
169 .It Cm 11g
170 Force 802.11g operation.
172 .It Cm nwid Ar id
173 Set the network ID.
175 .Ar id
176 can either be any text string up to 32 characters in length,
177 or a series of hexadecimal digits up to 64 digits.
178 An empty
179 .Ar id
180 string allows the interface to connect to any available access points.
181 By default the
183 driver uses an empty string.
184 Note that network ID is synonymous with Extended Service Set ID (ESSID).
185 .It Cm nwkey Ar key
186 Enable WEP encryption using the specified
187 .Ar key .
189 .Ar key
190 can either be a string, a series of hexadecimal digits (preceded by
191 .Sq 0x ) ,
192 or a set of keys of the form
193 .Dq n:k1,k2,k3,k4 ,
194 where
195 .Sq n
196 specifies which of the keys will be used for transmitted packets,
197 and the four keys,
198 .Dq k1
199 through
200 .Dq k4 ,
201 are configured as WEP keys.
202 If a set of keys is specified, a comma
203 .Pq Sq \&,
204 within the key must be escaped with a backslash.
205 Note that if multiple keys are used, their order must be the same within
206 the network.
208 is capable of using both 40-bit (5 characters or 10 hexadecimal digits)
209 or 104-bit (13 characters or 26 hexadecimal digits) keys.
210 .It Fl nwkey
211 Disable WEP encryption.
212 This is the default mode of operation.
214 .Sh FILES
215 The following firmware file is loaded when an interface is brought up:
217 .Bl -tag -width Ds -offset indent -compact
218 .It /libdata/firmware/rum/rum-rt2573
221 .Xr firmload 9
222 for how to change this.
223 .Sh HARDWARE
224 The following adapters should work:
226 .Bl -tag -width Ds -offset indent -compact
227 .It Airlink101 AWLL5025
228 .It ASUS WL-167g ver 2
229 .It Belkin F5D7050 ver 3
230 .It Belkin F5D9050 ver 3
231 .It CNet CWD-854 ver F
232 .It Conceptronic C54RU ver 2
233 .It D-Link DWL-G122 rev C1
234 .It D-Link WUA-1340
235 .It Edimax EW-7318USG
236 .It Gigabyte GN-WB01GS
237 .It Hawking HWUG1
238 .It LevelOne WNC-0301USB
239 .It Linksys WUSB54G rev C
240 .It Planex GW-USMM
241 .It Senao NUB-3701
242 .It Sitecom WL-113 ver 2
243 .It Sitecom WL-172
244 .It TP-LINK TL-WN321G
246 .Sh EXAMPLES
247 The following
248 .Xr ifconfig.if 5
249 example configures rum0 to join whatever network is available on boot,
250 using WEP key
251 .Dq 0x1deadbeef1 ,
252 channel 11:
253 .Bd -literal -offset indent
254 inet 192.168.1.1 netmask 255.255.255.0 nwkey 0x1deadbeef1 chan 11
257 The following
258 .Xr ifconfig.if 5
259 example creates a host-based access point on boot:
260 .Bd -literal -offset indent
261 inet 192.168.1.1 netmask 255.255.255.0 media autoselect \e
262         mediaopt hostap nwid my_net chan 11
265 Configure rum0 for WEP, using hex key
266 .Dq 0x1deadbeef1 :
267 .Bd -literal -offset indent
268 # ifconfig rum0 nwkey 0x1deadbeef1
271 Return rum0 to its default settings:
272 .Bd -literal -offset indent
273 # ifconfig rum0 -bssid -chan media autoselect \e
274         nwid "" -nwkey
277 Join an existing BSS network,
278 .Dq my_net :
279 .Bd -literal -offset indent
280 # ifconfig rum0 192.168.1.1 netmask 0xffffff00 nwid my_net
282 .Sh DIAGNOSTICS
283 .Bl -diag
284 .It "rum%d: failed loadfirmware of file %s"
285 For some reason, the driver was unable to read the microcode file from the
286 filesystem.
287 The file might be missing or corrupted.
288 .It "rum%d: could not load 8051 microcode"
289 An error occurred while attempting to upload the microcode to the onboard 8051
290 microcontroller unit.
291 .It "rum%d: device timeout"
292 A frame dispatched to the hardware for transmission did not complete in time.
293 The driver will reset the hardware.
294 This should not happen.
296 .Sh SEE ALSO
297 .Xr arp 4 ,
298 .Xr ifmedia 4 ,
299 .Xr netintro 4 ,
300 .Xr usb 4 ,
301 .Xr ifconfig.if 5 ,
302 .Xr hostapd 8 ,
303 .Xr ifconfig 8 ,
304 .Xr firmload 9
306 Ralink Technology:
307 .Pa http://www.ralinktech.com
308 .Sh HISTORY
311 driver first appeared in
312 .Nx 4.0
314 .Ox 4.0 .
315 .Sh AUTHORS
318 driver was written by
319 .An Niall O'Higgins Aq niallo@openbsd.org
321 .An Damien Bergamini Aq damien@openbsd.org .
322 .Sh CAVEATS
325 driver supports automatic control of the transmit speed in BSS mode only.
326 Therefore the use of a
328 adapter in Host AP mode is discouraged.