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