.\"	$OpenBSD: wicontrol.8,v 1.44 2002/12/19 00:39:57 deraadt Exp $
.\"
.\" Copyright (c) 1997, 1998, 1999
.\"	Bill Paul <wpaul@ctr.columbia.edu> All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by Bill Paul.
.\" 4. Neither the name of the author nor the names of any co-contributors
.\"    may be used to endorse or promote products derived from this software
.\"   without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY Bill Paul AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL Bill Paul OR THE VOICES IN HIS HEAD
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
.\" THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\"	$FreeBSD: wicontrol.8,v 1.6 1999/05/22 16:12:47 wpaul Exp $
.\"
.Dd June 7, 2001
.Dt WICONTROL 8
.Os
.Sh NAME
.Nm wicontrol
.Nd configure WaveLAN/IEEE devices
.Sh SYNOPSIS
.Nm wicontrol
.Op Ar interface
.Op Fl olL
.Op Fl e Ar 0|1
.Op Fl k Ar key "[ -v 1|2|3|4 ]"
.Op Fl x Ar 0|1
.Op Fl t Ar tx rate
.Op Fl n Ar network name
.Op Fl s Ar station name
.Op Fl c Ar 0|1
.Op Fl q Ar SSID
.Op Fl p Ar port type
.Op Fl a Ar access point density
.Op Fl m Ar MAC address
.Op Fl d Ar max data length
.Op Fl r Ar RTS threshold
.Op Fl f Ar frequency
.Op Fl A Ar 1|2|3
.Op Fl D Ar 0|1|2
.Op Fl F Ar 0|1
.Op Fl M Ar 0|1
.Op Fl P Ar 0|1
.Op Fl R Ar 1|3
.Op Fl S Ar max sleep duration
.Op Fl T Ar 1|2|3|4
.Sh DESCRIPTION
The
.Nm
command controls the operation of WaveLAN/IEEE wireless networking
devices via the
.Xr wi 4
and
.Xr awi 4
drivers.
Most of the parameters that can be changed relate to the
IEEE 802.11 protocol which the WaveLAN implements.
This includes
the station name, whether the station is operating in ad-hoc (point
to point) or BSS (service set) mode, and the network name of a service
set to join (IBSS) if BSS mode is enabled.
The
.Nm
command can also be used to view the current settings of these parameters
and to dump out the values of the card's statistics counters.
.Pp
The
.Ar interface
argument given to
.Nm
should be the logical interface name associated with the WaveLAN/IEEE
device (wi0, wi1, etc...).
If none is given, wi0 is assumed.
.Pp
The
.Nm
command given without any additional flags retrieves the current card
settings from the driver and prints them out.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl o
Display the statistics counters for the specified WaveLAN/IEEE
interface.
The statistics are updated about once a minute.
.It Fl l
[Prism2 only]
List associated stations if the card is in Host AP mode.
.It Fl L
List all available access points.
Only the superuser may use this option.
.It Fl e Ar 0|1
Enable or disable WEP encryption.
Permitted values are
.Ar 0
(encryption disabled) or
.Ar 1
(encryption enabled).
Encryption is off by default.
.It Fl k Ar key "[ -v 1|2|3|4 ]"
Set WEP encryption keys.
There are four default encryption keys that can be programmed.
A specific key can be set using the
.Fl v
flag.
If the
.Fl v
flag is not specified, the first key will be set.
Encryption keys can either
be normal text (i.e., "hello") or a series of hexadecimal digits
(i.e., "0x1234512345").
For WaveLAN Silver cards, the key is
restricted to 40 bits, hence the key can be either a 5-character text string
or 10 hexadecimal digits.
For WaveLAN Gold cards, the key can be up to
104 bits, which means the key can be specified as either a 13-character
text string or 26 hexadecimal digits.
Either way, the key will be concatenated with a 24-bit IV to generate
the seed for RC4.
Note that
.Nm
has no way to determine whether or not a card is capable of using
104 bit WEP.
Some cards accept a 104 bit key even though they only support 40 bit
keys, in which case WEP encryption will simply fail to work.
.It Fl T Ar 1|2|3|4
Specify which of the four WEP encryption keys will be used to encrypt
transmitted packets.
.It Fl x Ar 0|1
[Prism2/Symbol only]
Select between firmware-based (0) and software-based (1) WEP.
Firmware-based WEP is the default.
.It Fl t Ar tx rate
Set the transmit rate of the specified interface.
The legal values
for the transmit rate vary depending on the adapter type.
The standard WaveLAN/IEEE NICs support a maximum transmit rate of 2Mbps,
and the
.Sq Turbo
NICs support a maximum speed of 5.5Mbps.
The WaveLAN/IEEE
.Sq Turbo 11Mb ,
Prism-II and Prism-2.5
NICs support a maximum speed of 11Mbps.
The following table shows the legal transmit rate settings
and the corresponding transmit speeds:
.Bl -column "TX rate" "Auto Rate Select (Standard)" -offset indent
.It Em "TX rate" Ta Em "NIC speed"
.It 1 Ta "Fixed Low (1Mbps)"
.It 2 Ta "Fixed Standard (2Mbps)"
.It 3 Ta "Auto Rate Select (High)"
.It 4 Ta "Fixed Medium (4Mbps)"
.It 5 Ta "Fixed High (5.5Mbps)"
.It 6 Ta "Auto Rate Select (Standard)"
.It 7 Ta "Auto Rate Select (Medium)"
.It 11 Ta "Fixed Turbo (11Mbps)"
.El
.Pp
The standard NICs support only settings 1 through 3.
Turbo NICs support all the above listed speed settings.
The default driver setting is 3 (auto rate select).
.It Fl n Ar network name
Set the name of the service set (BSS or IBSS) or ad-hoc network
that this station wishes to join.
The
.Ar network name
can be any text string up to 30 characters in length.
The default name is the empty string which should allow
the station to connect to the first available access point.
.It Fl s Ar station name
Sets the
.Ar station name
for the specified interface.
The
.Ar station name
is used for diagnostic purposes.
The Lucent WaveMANAGER sofware can poll the names of remote hosts.
.It Fl c Ar 0|1
Allow the station to create a service set (IBSS).
Permitted values are 0 (do not create IBSS) and 1 (enable creation of IBSS).
The default is 0.
.Pp
Note: Symbol cards and older Lucent/Prism firmware revisions do not
support the creation of a service set.
.It Fl q Ar SSID
Specify the name (SSID) of an IBSS to create on a given interface.
The
.Ar SSID
can be any text string up to 32 characters long.
If the card is in IBSS creation or hostap mode, the IBSS name is
automatically set to be the same as the
.Em network name .
.It Fl p Ar port type
Set the
.Ar port type
for a specified interface.
The legal values for
.Ar port type
are 1 (BSS mode), 3 (ad-hoc mode), 4 (IBSS mode) and 6 (hostap mode).
The symbolic values
.Dq bss ,
.Dq adhoc ,
.Dq ibss ,
and
.Dq hostap
may also be used.
The hostap mode is only available on Prism-II and Prism-2.5-based NICs.
See below for an explanation of the various port types.
.It Fl a Ar access_point_density
Specify the
.Ar access point density
for a given interface.
Legal values are 1 (low), 2 (medium) and 3 (high).
This setting influences some of the radio modem threshold settings.
.It Fl m Ar MAC address
Set the station address for the specified interface.
The
.Ar MAC address
is specified as a series of six hexadecimal values separated by colons,
e.g.: 00:60:1d:12:34:56.
This programs the new address into the card and updates the interface as well.
.It Fl d Ar max_data_length
Set the maximum receive and transmit frame size for a specified interface.
The
.Ar max data length
can be any number from 350 to 2304.
The default is 2304.
.It Fl r Ar RTS threshold
Set the RTS/CTS threshold for a given interface.
This controls the number of bytes used for the RTS/CTS handshake boundary.
The
.Ar RTS threshold
can be any value between 0 and 2047.
The default is 2047.
.It Fl f Ar frequency
Set the radio frequency of a given interface.
The
.Ar frequency
should be specified as a channel ID as shown in the table below.
The list of available frequencies is dependent on radio regulations specified
by regional authorities.
Recognized regulatory authorities include
the FCC (United States), ETSI (Europe), France and Japan.
Frequencies in the table are specified in Mhz.
.Bl -column "Channel" "FCCXXXX" "ETSIXXX" "FranceX" "JapanXX" -offset indent
.Em "Channel	FCC	ETSI	France	Japan"
.It 1 Ta "2412	2412	-	2412"
.It 2 Ta "2417	2417	-	2417"
.It 3 Ta "2422*	2422*	-	2422"
.It 4 Ta "2427	2427	-	2427"
.It 5 Ta "2432	2432	-	2432"
.It 6 Ta "2437	2437	-	2437"
.It 7 Ta "2442	2442	-	2442"
.It 8 Ta "2447	2447	-	2447"
.It 9 Ta "2452	2452	-	2452"
.It 10 Ta "2457*	2457	2457	2457"
.It 11 Ta "2462*	2462	2462*	2462"
.It 12 Ta "-	2467	2467	2467"
.It 13 Ta "-	2472	2472	2472"
.It 14 Ta "-	-	-	2484*"
.El
.Pp
If an illegal channel is specified, the
NIC will revert to its default channel, normally one of those indicated
above with a *.
Note that two stations must be set to the same channel in order to
communicate.
Note also that the channels do overlap; the bandwidth required for
each channel is about 20Mhz.
When using multiple channels in close proximity it is suggested
that channels be separated by at least 25Mhz.
In the US, this means that only channels 1, 6, and 11 may be used
simultaneously without interference.
.It Fl A Ar 1|2|3
[Prism2/Symbol only] Sets the authentication type for a given interface.
Permitted values are
.Ar 1
(Open System Authentication),
.Ar 2
(Shared Key Authentication) and
.Ar 3
(104-bit Shared Key Authentication).
The 104-bit Shared Key Authentication mode is only available on Symbol cards.
.Pp
When
.Em Open System Authentication
is used, any station may associate with an access point.
In effect, no authentication is done.
Note, however, that if WEP is enabled on the access point, stations will
be able to associate with the access point but will be unable to send and
receive data packets unless they have the correct WEP key.
.br
With
.Em Shared Key Authentication,
on the other hand, only stations that have the same WEP key as the access
point may associate with it.
.br
The default is 1 (Open System Authentication).
.Pp
Note: It is not valid to enable Shared Key Authentication
when no valid WEP keys have been defined.
.It Fl D Ar 0|1|2
[Symbol only] Select the antenna diversity.
Symbol cards have both a primary and auxiliary antenna.
Either antenna may be used or the card can choose the antenna
with the best reception.
.Bl -column "Value" "Autoselect" -offset indent
.It Sy "Value" Ta Sy "Diversity"
.It 0 Ta Autoselect
.It 1 Ta Primary
.It 2 Ta Auxiliary
.El
.Pp
The default is 0 (Autoselect).
.It Fl F Ar 0|1
[Prism2 only]
Enable or disable processing of 802.11b frames.
When enabled, the
.Xr wi 4
driver will process entire frames instead of stripping
off the 802.11b header that is provided by the card.
Only the superuser may use this option.
.It Fl M Ar 0|1
Enable or disable
.Dq microwave oven robustness
on a given interface.
When enabled, smaller packets are used to reduce the impact of
consumer microwave ovens that operate in the 2.4Ghz frequency range.
This option may also be useful when there are 2.4Ghz cordless
telephones in the area.
Only works in BSS mode and requires access point support.
Requires Lucent firmware version >= 7.28.
.It Fl P Ar 0|1
Enable or disable power management on a given interface.
Enabling power management uses an alternating sleep/wake protocol to help
conserve power on mobile stations, at the cost of some increased
receive latency.
Power management is off by default.
Note that power management requires the cooperation of an access
point in order to function; it is not functional in ad-hoc mode.
Also, power management is only implemented in Lucent WavePOINT
firmware version 2.03 or later, and in WaveLAN PCMCIA adapter
firmware 2.00 or later.
Older revisions will silently ignore the power management setting.
Legal values for this parameter are 0 (off) and 1 (on).
.It Fl R Ar 1|3
Enable or disable roaming function on a given interface.
The legal values are
.Ar 1
(Roaming handled by firmware) and
.Ar 3
(Roaming Disabled).
The default is 1.
This option is not available on Symbol cards.
.It Fl S Ar max sleep interval
Specify the sleep interval to use when power management is enabled.
The
.Ar max sleep interval
is specified in milliseconds.
The default is 100.
.El
.Ss Explanation of port types
.Pp
There are five modes the NIC can operate in:
.Bl -tag -width Ds -offset indent
.It BSS mode
Also known as
.Em infrastructure
mode, this is used when associating with an access point, through
which all traffic passes.
If no service set is specified via the
.Fl n
flag, the NIC will associate with whichever access point has the
strongest signal.
In general, it is a good idea to specify a service set to prevent
possible hijacking of the association.
.It ad-hoc mode
More accurately known as
.Dq ad-hoc demo mode .
This mode does not require an access point; the NIC communicates with
other ad-hoc stations within range on a peer-to-peer basis.
This mode is not specified by the IEEE 802.11 standard and there
may be problems interoperating with NICs manufactured by different
vendors.
.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 created by an IBSS master (see below).
However, actual connections between stations are peer-to-peer as in ad-hoc mode.
Lucent firmware version 6.06 or higher, Prism2 firmware 0.8.0 or higher,
or Symbol firmware version 2.0.0 or higher is required for IBSS mode.
.It IBSS master
Also know as
.Em Host IBSS
mode.
In this mode, the station takes on part of the role of an access point,
however traffic does not pass through it to reach the other stations.
When a group of stations are operating in IBSS mode, one of them must be
the master, specifying the network name of the service set.
Symbol cards do not support operating as an IBSS master.
.It Host AP
In this mode, which is only available on Prism2 cards, the NIC acts
as an access point (base station).
Some tasks, such as beaconing and frame acknowledgement, are handled
automatically by the card firmware.
Authentication and general management of the associated stations,
however, is performed by the
.Xr wi 4
driver itself.
Note that there are bugs in Host AP mode in Prism firmware revisions
prior to 0.8.3.
.El
.Sh SEE ALSO
.Xr awi 4 ,
.Xr an 4 ,
.Xr wi 4 ,
.Xr hostname.if 5 ,
.Xr ancontrol 8 ,
.Xr ifconfig 8
.Sh HISTORY
The
.Nm
command first appeared in
.Ox 2.6 .
.Sh AUTHORS
The
.Nm
command was written by
.An Bill Paul Aq wpaul@ctr.columbia.edu .