.\"	$OpenBSD: rtw.4,v 1.30 2007/12/10 10:32:54 jmc Exp $
.\"
.\" Copyright (c) 2004 Jonathan Gray <jsg@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: December 10 2007 $
.Dt RTW 4
.Os
.Sh NAME
.Nm rtw
.Nd Realtek RTL8180L IEEE 802.11b wireless network device
.Sh SYNOPSIS
.Cd "rtw* at cardbus?"
.Cd "rtw* at pci?"
.Sh DESCRIPTION
The
.Nm
driver supports PCI/CardBus 802.11b wireless adapters based on the
Realtek RTL8180L.
.Pp
A variety of radio transceivers can be found in these devices, including
the Philips SA2400A, Maxim MAX2820, and GCT GRF5101.
.Pp
These are the modes the
.Nm
driver can operate in:
.Bl -tag -width "IBSS-masterXX"
.It BSS mode
Also known as
.Em infrastructure
mode, this is used when associating with an access point, through
which all traffic passes.
This mode is the default.
.It IBSS mode
Also known as
.Em IEEE ad-hoc
mode or
.Em peer-to-peer
mode.
This is the standardized method of operating without an access point.
Stations associate with a service set.
However, actual connections between stations are peer-to-peer.
.It Host AP
In this mode the driver acts as an access point (base station)
for other cards.
.It monitor mode
In this mode the driver is able to receive packets without
associating with an access point.
This disables the internal receive filter and enables the card to
capture packets from networks which it wouldn't normally have access to,
or to scan for access points.
.El
.Pp
.Nm
supports software WEP.
Wired Equivalent Privacy (WEP) is the de facto encryption standard
for wireless networks.
It can be typically configured in one of three modes:
no encryption; 40-bit encryption; or 104-bit encryption.
Unfortunately, due to serious weaknesses in WEP protocol
it is strongly recommended that it not be used as the
sole mechanism to secure wireless communication.
WEP is not enabled by default.
.Sh CONFIGURATION
The
.Nm
driver can be configured at runtime with
.Xr ifconfig 8
or on boot with
.Xr hostname.if 5
using the following parameters:
.Bl -tag -width Ds
.It Cm bssid Ar bssid
Set the desired BSSID.
.It Fl bssid
Unset the desired BSSID.
The interface will automatically select a BSSID in this mode, which is
the default.
.It Cm chan Ar n
Set the channel (radio frequency) to be used by the driver based on
the given channel ID
.Ar n .
.It Fl chan
Unset the desired channel to be used by the driver.
The driver will automatically select a channel in this mode, which is
the default.
.It Cm media Ar media
The
.Nm
driver supports the following
.Ar media
types:
.Pp
.Bl -tag -width autoselect -compact
.It Cm autoselect
Enable autoselection of the media type and options.
.It Cm DS1
Set 802.11b DS 1Mbps operation.
.It Cm DS2
Set 802.11b DS 2Mbps operation.
.It Cm DS5
Set 802.11b DS 5.5Mbps operation.
.It Cm DS11
Set 802.11b DS 11Mbps operation.
.El
.It Cm mediaopt Ar opts
The
.Nm
driver supports the following media options:
.Pp
.Bl -tag -width monitor -compact
.It Cm hostap
Select Host AP operation.
.It Cm ibss
Select IBSS operation.
.It Cm monitor
Select monitor mode.
.El
.It Fl mediaopt Ar opts
Disable the specified media options on the driver and return it to the
default mode of operation (BSS).
.It Cm nwflag Ar flag
Set a specified flag for the wireless network interface.
The flag name can be either
.Ql hidenwid
or
.Ql nobridge .
The
.Ql hidenwid
flag will hide the network ID (ESSID) in beacon frames when operating
in Host AP mode.
It will also prevent responses to probe requests with an unspecified
network ID.
The
.Ql nobridge
flag will disable the direct bridging of frames between associated
nodes when operating in Host AP mode.
Setting this flag will block and filter direct inter-station
communications.
.Pp
Note that the
.Ql hidenwid
and
.Ql nobridge
options do not provide any security.
The hidden network ID will be sent in clear text by associating
stations and can be easily discovered with tools like
.Xr tcpdump 8
and
.Xr hostapd 8 .
.It Fl nwflag Ar flag
Remove a specified flag for the wireless network interface.
.It Cm nwid Ar id
Set the network ID.
The
.Ar id
can either be any text string up to 32 characters in length,
or a series of hexadecimal digits up to 64 digits.
An empty
.Ar id
string allows the interface to connect to any available access points.
By default the
.Nm
driver uses an empty string.
Note that network ID is synonymous with Extended Service Set ID (ESSID).
.It Fl nwid
Set the network ID to the empty string to allow the interface to connect
to any available access point.
.It Cm nwkey Ar key
Enable WEP encryption using the specified
.Ar key .
The
.Ar key
can either be a string, a series of hexadecimal digits (preceded by
.Sq 0x ) ,
or a set of keys of the form
.Dq n:k1,k2,k3,k4 ,
where
.Sq n
specifies which of the keys will be used for transmitted packets,
and the four keys,
.Dq k1
through
.Dq k4 ,
are configured as WEP keys.
If a set of keys is specified, a comma
.Pq Sq \&,
within the key must be escaped with a backslash.
Note that if multiple keys are used, their order must be the same within
the network.
.Nm
is capable of using both 40-bit (5 characters or 10 hexadecimal digits)
or 104-bit (13 characters or 26 hexadecimal digits) keys.
.It Fl nwkey
Disable WEP encryption.
This is the default mode of operation.
.It Cm nwkey persist
Enable WEP encryption with the persistent key stored in the network card.
.El
.Sh HARDWARE
The following adapters should work:
.Pp
.Bl -column "Card                        " "Radio    " "Bus" -compact -offset 6n
.It Em "Card	Radio	Bus"
.\".It Li "Acer Aspire 1357 LMi" Ta SA2400 Ta Mini PCI
.It Li "Allnet ALL0182" Ta SA2400 Ta CardBus
.\".It Li "Belkin F5D6001 V3" Ta SA2400 Ta PCI
.It Li "Belkin F5D6020 V3" Ta SA2400 Ta CardBus
.It Li "Buffalo WLI-CB-B11" Ta SA2400 Ta CardBus
.It Li "Corega CG-WLCB11V3" Ta SA2400 Ta CardBus
.\".It Li "D-Link DWL-510" Ta SA2400 Ta PCI
.\".It Li "D-Link DWL-520 rev D" Ta ? Ta PCI
.It Li "D-Link DWL-610" Ta ? Ta CardBus
.\".It Li "Encore ENLWI-PCI1-NT" Ta SA2400 Ta PCI
.It Li "Edimax EW-7106" Ta SA2400 Ta CardBus
.\".It Li "Edimax EW-7126" Ta GRF5101 Ta PCI
.\".It Li "Gigabyte GN-WLMR101" Ta SA2400 Ta PCI
.It Li "GigaFast WF721-AEX (R* serial)" Ta "GRF5101" Ta CardBus
.\".It Li "HomeLine HLW-PCC200" Ta "GRF5101" Ta CardBus
.It Li "Jensen AirLink 6011" Ta GRF5101 Ta CardBus
.It Li "Level-One WPC-0101" Ta SA2400 Ta CardBus
.It Li "Linksys WPC11 v4" Ta MAX2820 Ta CardBus
.\.It Li "Longshine LCS-8031-R" Ta GRF5101 Ta PCI
.\".It Li "Mentor WLPCI04330073" Ta SA2400 Ta CardBus
.\".It Li "Micronet SP906BB" Ta ? Ta PCI
.It Li "Netgear MA521" Ta SA2400 Ta CardBus
.It Li "Ovislink AirLive WL-1120PCM" Ta SA2400 Ta CardBus
.\".It Li "Pheenet WL-11PCIR" Ta SA2400 Ta PCI
.It Li "Planet WL-3553" Ta SA2400 Ta CardBus
.It Li "Q-Tec 770WC" Ta SA2400 Ta CardBus
.It Li "Q-Tec 775WC" Ta SA2400 Ta CardBus
.\".It "Repotec RP-WP7126" Ta GRF5101 Ta PCI
.It Li "Roper FreeLan 802.11b" Ta SA2400 Ta CardBus
.It Li "SAFECOM SWLCR-1100" Ta SA2400 Ta CardBus
.\".It Li "Surecom EP-9428" Ta ? Ta CardBus
.\".It Li "Sweex LC700010" Ta GRF5101 Ta PCI
.\".It "Tonze PC-2100T" Ta GRF5101 Ta PCI
.\".It Li "Topcom Skyr@cer 4011b" Ta ? Ta CardBus
.\".It "TP-Link TL-WN250/251" Ta GRF5101 Ta PCI
.It Li "TRENDnet TEW-226PC" Ta ? Ta CardBus
.\".It Li "TRENDnet TEW-288PI" Ta SA2400 Ta PCI
.It Li "VCTnet PC-11B1" Ta SA2400 Ta CardBus
.It Li "Winstron CB-200B" Ta SA2400 Ta CardBus
.It Li "Zonet ZEW1000" Ta GRF5101 Ta CardBus
.El
.Sh EXAMPLES
The following
.Xr hostname.if 5
example configures rtw0 to join whatever network is available on boot,
using WEP key
.Dq 0x1deadbeef1 ,
channel 11, obtaining an IP address using DHCP:
.Bd -literal -offset indent
dhcp NONE NONE NONE nwkey 0x1deadbeef1 chan 11
.Ed
.Pp
The following
.Xr hostname.if 5
example creates a host-based access point on boot:
.Bd -literal -offset indent
inet 192.168.1.1 255.255.255.0 NONE media autoselect \e
	mediaopt hostap nwid my_net chan 11
.Ed
.Pp
Configure rtw0 for WEP, using hex key
.Dq 0x1deadbeef1 :
.Bd -literal -offset indent
# ifconfig rtw0 nwkey 0x1deadbeef1
.Ed
.Pp
Return rtw0 to its default settings:
.Bd -literal -offset indent
# ifconfig rtw0 -bssid -chan media autoselect \e
	nwid "" -nwkey
.Ed
.Pp
Join an existing BSS network,
.Dq my_net :
.Bd -literal -offset indent
# ifconfig rtw0 192.168.1.1 netmask 0xffffff00 nwid my_net
.Ed
.Sh SEE ALSO
.Xr arp 4 ,
.Xr cardbus 4 ,
.Xr ifmedia 4 ,
.Xr intro 4 ,
.Xr netintro 4 ,
.Xr pci 4 ,
.Xr hostname.if 5 ,
.Xr hostapd 8 ,
.Xr ifconfig 8
.Rs
.%T Realtek
.%O http://www.realtek.com.tw
.Sh HISTORY
The
.Nm
device driver first appeared in
.Ox 3.7 .
.Sh AUTHORS
.An -nosplit
The
.Nm
driver was written by
.An David Young
.Aq dyoung@NetBSD.org
and ported to
.Ox
by
.An Jonathan Gray Aq jsg@openbsd.org .
.Sh CAVEATS
GCT refuse to release any documentation on their GRF5101 RF transceiver.
.Pp
While PCI devices will attach most of them are not able to transmit.