path: root/usr/src/man/man8/wificonfig.8

'\" te
.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH WIFICONFIG 8 "December 28, 2020"
.SH NAME
wificonfig \- WLAN configuration
.SH SYNOPSIS
.nf
\fBwificonfig\fR [\fB-R\fR \fIroot_path\fR] [\fB-i\fR \fIinterface\fR] autoconf
     [\fIwait\fR={\fIn\fR|\fIforever\fR}]
.fi

.LP
.nf
\fBwificonfig\fR [\fB-R\fR \fIroot_path\fR] [\fB-i\fR \fIinterface\fR] connect profile
     [\fIwait\fR={\fIn\fR|\fIforever\fR}]
.fi

.LP
.nf
\fBwificonfig\fR [\fB-R\fR \fIroot_path\fR] [\fB-i\fR \fIinterface\fR] connect essid
     [\fIwait\fR={\fIn\fR|\fIforever\fR}]
.fi

.LP
.nf
\fBwificonfig\fR [\fB-R\fR \fIroot_path\fR] [\fB-i\fR \fIinterface\fR] disconnect
.fi

.LP
.nf
\fBwificonfig\fR [\fB-R\fR \fIroot_path\fR] [\fB-i\fR \fIinterface\fR] getparam
     [\fIparameter\fR []...]
.fi

.LP
.nf
\fBwificonfig\fR [\fB-R\fR \fIroot_path\fR] [\fB-i\fR \fIinterface\fR] setparam
     [\fIparameter\fR=\fIvalue\fR []...]
.fi

.LP
.nf
\fBwificonfig\fR [\fB-R\fR \fIroot_path\fR] [\fB-i\fR \fIinterface\fR] restoredef
.fi

.LP
.nf
\fBwificonfig\fR [\fB-R\fR \fIroot_path\fR] [\fB-i\fR \fIinterface\fR] scan
.fi

.LP
.nf
\fBwificonfig\fR [\fB-R\fR \fIroot_path\fR] [\fB-i\fR \fIinterface\fR] showstatus
.fi

.LP
.nf
\fBwificonfig\fR [\fB-R\fR \fIroot_path\fR] [\fB-i\fR \fIinterface\fR] setwepkey 1|2|3|4
.fi

.LP
.nf
\fBwificonfig\fR [\fB-R\fR \fIroot_path\fR] createprofile profile
     [\fIparameter\fR=\fIvalue\fR []...]
.fi

.LP
.nf
\fBwificonfig\fR [\fB-R\fR \fIroot_path\fR] deleteprofile \fIprofile1\fR
     [\fIprofile2\fR []...]
.fi

.LP
.nf
\fBwificonfig\fR [\fB-R\fR \fIroot_path\fR] showprofile [\fIprofile\fR]
.fi

.LP
.nf
\fBwificonfig\fR [\fB-R\fR \fIroot_path\fR] setprofilewepkey \fIprofile\fR 1|2|3|4
.fi

.LP
.nf
\fBwificonfig\fR [\fB-R\fR \fIroot_path\fR] getprofileparam \fIprofile\fR
     [\fIparameter\fR []...]
.fi

.LP
.nf
\fBwificonfig\fR [\fB-R\fR \fIroot_path\fR] setprofileparam
     [\fIparameter\fR=\fIvalue\fR []...]
.fi

.LP
.nf
\fBwificonfig\fR [\fB-R\fR \fIroot_path\fR] history
.fi

.LP
.nf
\fBwificonfig\fR [\fB-R\fR \fIroot_path\fR] listprefer
.fi

.LP
.nf
\fBwificonfig\fR [\fB-R\fR \fIroot_path\fR] removeprefer \fIprofile\fR
.fi

.LP
.nf
\fBwificonfig\fR [\fB-R\fR \fIroot_path\fR] setprefer \fIprofile\fR [\fIn\fR]
.fi

.SH DESCRIPTION
\fBwificonfig\fR defines a set of subcommands and parameters to configure
\fBWiFi\fR interfaces in the system. A driver may support all parameters or a
subset of these parameters.
.sp
.LP
\fBwificonfig\fR uses \fBrbac\fR(7) to control user access to the interface.
Only users with the "solaris.network.wifi.config" authorization can manage a
\fBWiFi\fR interface, while only users with
"solaris.network.wifi.wep"authorizations can configure the \fBWEP\fR (Wired
Equivalent Privacy) key. Other users can only read parameters from the
interface. By default, the "solaris.network.wifi.config" and
"solaris.network.wifi.wep" authorizations are not granted to any user apart
from root.
.sp
.LP
\fBWificonfig\fR comes in two classes of forms. The first class, shown as the
first set of synopsis combined with the optional interface name, is the
subcommands used to a manipulate a particular \fBWiFi\fR network interface. The
second class, shown as the second set of synopsis, is used to create and
operate on \fBWiFi\fR Configuration Profiles. A Configuration Profile allows
the user to pre-specify a set of parameters which can later be applied to a
\fBWiFi\fR network interface using the \fBconnect\fR or \fBautoconf\fR
subcommands.
.sp
.LP
In the interface subcommands, if the interface is not specified (that is, the
\fB-i\fR option is missing), \fBwificonfig\fR selects a random interface from
the known \fBWiFi\fR interfaces on the system. If there are multiple \fBWiFi\fR
network interfaces on the system, then the selection will be the same over time
as long as the number of and names of the \fBWiFi\fR interfaces does not
change.
.sp
.LP
A Configuration Profile can be created for a \fBWLAN\fR by using the
\fBcreateprofile\fR subcommand (see the SUBCOMMANDS section). The actual
\fBWLAN\fR may be present or not.
.sp
.LP
\fBwificonfig\fR also maintains a list of Configuration Profiles called the
Preference List. This list makes automatic configuration possible. When the
\fBautoconf\fR subcommand is used, \fBwificonfig\fR tries to connect to each
pre-configured \fBWLAN\fR according to the order of the Preference List. If the
Preference List is empty or none of the \fBWLAN\fRs in the Preference List can
be found, \fBwificonfig\fR uses its built-in heuristics to automatically
configure the interface. (See the \fBautoconf\fR subcommand for the
heuristics). A few subcommands (\fBlistprefer\fR, \fBsetprefer\fR,
\fBremoveprefer\fR) are defined to manipulate the Preference List.
.SH OPTIONS
The following options are supported:
.sp
.ne 2
.na
\fB\fB-i\fR \fIinterface\fR\fR
.ad
.RS 16n
Specifies a wireless network interface to do the configuration.
.RE

.sp
.ne 2
.na
\fB\fB-R\fR \fIroot_path\fR\fR
.ad
.RS 16n
Defines the full path name of a directory to use as the \fIroot_path\fR. This
affects the location of the private files where \fBwificonfig\fR stores the
Configuration Profiles and \fBWEP\fR keys.
.RE

.SS "OPERANDS"
The following operand is supported:
.sp
.ne 2
.na
\fBprofile\fR
.ad
.RS 11n
The name of a \fBWiFi\fR profile. It can be a string between 1 and 32
characters. However, "all", "{preference}", "{history}", "{active_profile}",
and any strings contained in brackets, such as "[foo]", are not allowed as a
profile name.
.RE

.SS "SUBCOMMANDS"
The following subcommands are supported:
.sp
.ne 2
.na
\fB\fBautoconf\fR [wait={\fIn\fR|\fIforever\fR}]\fR
.ad
.sp .6
.RS 4n
Configures the interface automatically. The interface is configured according
to the previously saved Preference List found in \fB/etc/inet/wifi\fR.
\fBwificonfig\fR first gets a list of available \fBWLAN\fRs by scanning the
radio. It then compares the list of available \fBWLAN\fRs with the Preference
List. If the Preference List is empty, or if none of the \fBWLAN\fRs in the
Preference List can be found, \fBwificonfig\fR chooses a \fBWLAN\fR to connect
to using the following priorities: 1) the \fBWLAN\fRs without encryption, 2)
the \fBWLAN\fRs with stronger signal strength, and 3) the \fBWLAN\fRs with
higher transmit rates.
.sp
If the \fBWLAN\fRs in the Preference list are available, the user can specify
the number of seconds to wait before \fBautoconf\fR returns using the wait
option. By default (without the wait option), \fBautoconf\fR returns within 10
seconds. If "\fIforever\fR" or -1 follows the wait option, \fBwificonfig\fR
waits until the \fBNIC\fR is successfully connected to the \fBWLAN\fR specified
by the profile in the Preference list.
.sp
The "solaris.network.wifi.config" authorization is required for this
subcommand.
.sp
The \fBWiFi\fR device driver can not guarantee to retain the state for the
connection when it is not held open. For this reason, it is strongly
recommended that the \fBplumb\fR subcommand for \fBifconfig\fR(8) is done
before the \fBwificonfig autoconf\fR subcommand is given.
.RE

.sp
.ne 2
.na
\fB\fBconnect\fR \fIprofile\fR[wait={\fIn\fR|\fIforever\fR}]\fR
.ad
.br
.na
\fB\fBconnect\fR \fIessid\fR[wait={\fIn\fR|\fIforever\fR}]\fR
.ad
.sp .6
.RS 4n
Connects to a wireless network according to a pre-configured "profile". If the
specified Configuration Profile exists in /etc/inet/wifi, the \fBconnect\fR
subcommand uses that Configuration Profile to configure the interface. That
profile subsequently becomes the current active profile of the interface after
the \fBconnect\fR subcommand succeeds. If no existing Configuration Profile
matches the specified name, the behavior of the \fBconnect\fR subcommand is
equivalent to the \fBrestoredef\fR subcommand, except that the "essid"
parameter is set as "profile".
.sp
If the \fBWLAN\fRs in the Preference list are available, the user can specify
the number of seconds to wait before \fBconnect\fR returns using the wait
option. By default (without the wait option), \fBconnect\fR tries for 10
seconds. If "\fIforever\fR" or -1 follows the wait option, \fBwificonfig\fR
tries until the \fBNIC\fR is successfully connected to the profile or essid
that was specified.
.sp
The \fBconnect\fR subcommand prints one of the following lines depending on
whether or not a Configuration Profile was found for the specified name:
.sp
.in +2
.nf
Connecting to profile <name>
Connecting to essid <name>
.fi
.in -2
.sp

The "solaris.network.wifi.config" authorization is required for this
subcommand.
.sp
The \fBWiFi\fR device driver can not guarantee to retain the state for the
connection when it is not held open. For this reason, it is strongly
recommended that the \fBplumb\fR subcommand for \fBifconfig\fR(8) is done
before the \fBwificonfig autoconf\fR subcommand is given.
.RE

.sp
.ne 2
.na
\fB\fBdisconnect\fR\fR
.ad
.sp .6
.RS 4n
Disconnects the interface from the currently associated wireless network. The
interface associates with none of the wireless networks.
.sp
The "solaris.network.wifi.config" authorization is required for this
subcommand.
.RE

.sp
.ne 2
.na
\fB\fBgetparam\fR [parameter [...]]\fR
.ad
.br
.na
\fB\fBsetparam\fR [parameter=value [...]]\fR
.ad
.sp .6
.RS 4n
Gets or sets parameters in the network interface. This does not affect any
profile. The \fBsetprofileparam\fR subcommand can be used to set and change
parameters in a profile that has already been created.
.sp
The \fBsetparam\fR subcommand without any parameters displays the set of
parameters supported by the network interface, including whether they are
read/write or read only. The \fBgetparam\fR subcommand without any parameters
displays all the parameters and their values.
.sp
The \fBsetparam wepkey1|wepkey2|wepkey3|wepkey4\fR subcommand requires the
"solaris.network.wifi.wep" authorization. For all other parameters, the
\fBsetparam\fR subcommand requires the
"solaris.network.wifi.config"authorization.
.sp
For example,
.sp
.in +2
.nf
$ wificonfig setparam <parameter1=value1> [parameter2=value2 [...]]
$ wificonfig getparam <parameter1> [parameter2 [...]]
.fi
.in -2
.sp

\fBwificonfig\fR currently supports the following parameters (the values are
case insensitive).
.sp
.ne 2
.na
\fB\fIbssid\fR\fR
.ad
.sp .6
.RS 4n
\fBMAC\fR address of the associated Access Point. The valid value is a hex
value of 6 bytes. The \fIbssid\fR can also be the \fBIBSSID\fR in an ad-hoc
configuration. If the network interface is not connected to any \fBWLAN\fR,
then the string "none" is shown instead of a 6 byte \fBMAC\fR address.
Otherwise, the network interface is connected to a \fBWLAN\fR. The default
value is "none". This parameter is read-only.
.RE

.sp
.ne 2
.na
\fB\fIessid\fR\fR
.ad
.sp .6
.RS 4n
Network name. The valid value is a string of up to 32 chars. If \fIessid\fR is
an empty string, the driver automatically scans and joins the \fBWLAN\fR using
the built-in heuristics. The default value is an empty string.
.RE

.sp
.ne 2
.na
\fB\fIbsstype\fR\fR
.ad
.sp .6
.RS 4n
Specifies whether the Infrastructure Mode or Ad-Hoc Mode is used. The valid
values are "ap", "bss", or "infrastructure" to join a \fBWLAN\fR through an
Access Point, that is, to use infrastructure mode. The valid values are "ibss"
or "ad-hoc" to join a peer-to-peer WLAN (also named "ad-hoc"). The valid value
of "auto" automatically switches between the two types. The default value is
"infrastructure'".
.RE

.sp
.ne 2
.na
\fB\fIcreateibss\fR\fR
.ad
.sp .6
.RS 4n
Specifies whether to create an ad-hoc network (also called an \fIIBSS\fR if the
\fBconnect\fR does not result in finding the desired network. This enables the
user to start an ad-hoc network so that other hosts can join. The valid values
are YES to start a new ad-hoc \fBWLAN\fR (instead of joining one) and NO to not
start an ad-hoc \fBWLAN\fR. The default value is NO. The \fBNIC\fR always tries
to join a \fBWLAN\fR first. If this is successful, the setting of
\fIcreateibss\fR is ignored.
.RE

.sp
.ne 2
.na
\fB\fIchannel\fR\fR
.ad
.sp .6
.RS 4n
An integer indicating the operating frequency. This channel number varies by
regulatory domain. When the channel number is obtained by the \fBgetparam\fR
subcommand, the value indicates the actual channel the card uses to connect to
the network. The channel number is set by the \fBsetparam\fR subcommand, and
the value is only applicable when the card is in ad-hoc mode. It indicates the
operating channel of the \fIIBSS\fR. The default value is the channel number on
the card.
.RE

.sp
.ne 2
.na
\fB\fIrates\fR\fR
.ad
.sp .6
.RS 4n
Specifies the transmission rates. The valid values (in Mbit/s) are 1, 2, 5.5,
6, 9, 11, 12, 18, 22, 24, 33, 36, 48, and 54. A \fBNIC\fR may support multiple
transmission rates depending on its capability. This is the only parameter that
accepts multiple values. When multiple values are supplied to set this
parameter, each value must be separated by a comma (,). See the \fBEXAMPLES\fR
section for details. The default values are the data rates supported by the
chip.
.RE

.sp
.ne 2
.na
\fB\fIpowermode\fR\fR
.ad
.sp .6
.RS 4n
Specifies the power management mode. The valid values are "off" to disable
power management, "mps" for maximum power saving, and "fast" for the best
combination of speed and power saving. The default value is "off".
.RE

.sp
.ne 2
.na
\fB\fIauthmode\fR\fR
.ad
.sp .6
.RS 4n
Specifies the authorization type. The valid values are "opensystem" for an open
system, where anyone can be authenticated and "shared_key" for a Shared Key
authentication mode. The default value is "opensystem".
.RE

.sp
.ne 2
.na
\fB\fIencryption\fR\fR
.ad
.sp .6
.RS 4n
Specifies the encryption algorithm to be used. The valid values are "none" for
no encryption algorithm and "wep" to turn on \fBWEP\fR encryption. The default
value is "none".
.RE

.sp
.ne 2
.na
\fB\fIwepkey1\fR|\fIwepkey2\fR|\fIwepkey3\fR|\fIwepkey4\fR\fR
.ad
.sp .6
.RS 4n
A maximum of 4 \fBWEP\fR keys (indexed 1 through 4) can be set in an \fBNIC\fR.
They are write-only parameters which can be set by the \fBsetparam\fR
subcommand, but cannot be read back by the \fBgetparam\fR subcommand. \fBWEP\fR
keys can either be set by the \fBsetwepkey\fR or the \fBsetparam\fR subcommand.
\fBsetparam\fR uses plain text but it's scriptable. See the \fBsetwepkey\fR
subcommand for more information about how a \fBWEP\fR key is encoded. Setting
\fBWEP\fR keys requires "solaris.network.wifi.wep"authorization.
.sp
When these subcommands are used to set a \fBWEP\fR key, any user on the system
can read the key from the \fBps\fR(1) output. Thus, the \fBsetwepkey\fR
subcommand is recommended for setting the \fBWEP\fR keys since it does not
allow \fBps\fR(1) to read the keys.
.RE

.sp
.ne 2
.na
\fB\fIwepkeyindex\fR\fR
.ad
.sp .6
.RS 4n
Specifies the encryption keys. The valid values are 1 to use wepkey1, 2 to use
wepkey2, 3 to use wepkey3, and 4 to use wepkey4. The default value is 1. This
subcommand is only valid when \fBWEP\fR is on.
.RE

.sp
.ne 2
.na
\fB\fIsignal\fR\fR
.ad
.sp .6
.RS 4n
Specifies the strength of the received radio signal. The valid values are 0 -
15 , where 0 is the weakest signal and 15 is the strongest signal. This
parameter is read-only and indicates the radio signal strength received by the
\fBNIC\fR.
.RE

.sp
.ne 2
.na
\fB\fIradio\fR\fR
.ad
.sp .6
.RS 4n
Specifies whether the radio is turned on or off. The valid values are "on" to
turn on the radio and "off" to turn off the radio. The default value is "on".
.RE

.RE

.sp
.ne 2
.na
\fB\fBrestoredef\fR\fR
.ad
.sp .6
.RS 4n
Forces the \fBNIC\fR to restore the network interface to use the default values
for all the parameters. See the \fBgetparam\fR and \fBsetparam\fR subcommands
for the default values of the parameters.
.sp
The "solaris.network.wifi.config" authorization is required for this
subcommand.
.RE

.sp
.ne 2
.na
\fB\fBscan\fR\fR
.ad
.sp .6
.RS 4n
Scans and lists the currently available \fBWLAN\fRs.
.RE

.sp
.ne 2
.na
\fB\fBshowstatus\fR\fR
.ad
.sp .6
.RS 4n
Display the basic status of a \fBWLAN\fR interface. If the \fBWLAN\fR interface
is connected, the basic status includes: the name of the current active
profile, the name of the network, the \fIbssid\fR, whether the network is
encrypted or not, and the signal strength.
.RE

.sp
.ne 2
.na
\fB\fBsetwepkey\fR 1|2|3|4\fR
.ad
.sp .6
.RS 4n
Sets one of the 4 \fBWEP\fR encryption keys. \fBWEP\fR keys are used to
encrypt the content of the network packets which are transmitted on air. There
are 4 \fBWEP\fR keys in the \fBNIC\fR according to the 802.11 standards. The
\fBsetwepkey\fR subcommand is used to update one of the 4 keys by prompting the
user for the key. The user must enter the key twice. The input is not echoed.
For example, to update setwepkey2:
.sp
.in +2
.nf
example% wificonfig -i ath0 setwepkey 2
input wepkey2: < user input here>
confirm wepkey2: < user input here>
.fi
.in -2
.sp

A \fBWEP\fR key can be 5 bytes or 13 bytes long. There are two ways to enter a
\fBWEP\fR key, by \fBASCII\fR values or by hex values. If the user enters 5 or
13 characters, it is considered the \fBASCII\fR representation of the key. If
the user enters 10 or 26 characters, it is considered the hex representation of
the key. For example "1234" is equivalent to "6162636465". If the user enters
other number of characters, the subcommand fails. \fBWEP\fR keys are
write-only; they cannot be read back via \fBwificonfig\fR.
.sp
The \fBWEP\fR keys can also be set in plain text form by the \fBsetparam\fR
subcommand. This makes setting \fBWEP\fR keys scriptable (see the parameters of
\fBsetparam\fR for the details).
.sp
The "solaris.network.wifi.wep" authorization is required for this subcommand.
.RE

.sp
.LP
The following profile subcommands are supported:
.sp
.ne 2
.na
\fB\fBcreateprofile\fR \fIprofile\fR [parameter=value] [...]\fR
.ad
.sp .6
.RS 4n
Creates a Configuration Profile named \fIprofile\fR off-line. The specified
parameters are saved as items of this Configuration Profile. The user can
specify a group of parameters. At a minimum, the \fIessid\fR must be specified.
.sp
The "solaris.network.wifi.config" authorization is required for this
subcommand.
.RE

.sp
.ne 2
.na
\fB\fBdeleteprofile\fR \fIprofile1\fR [\fIprofile2\fR [...]]\fR
.ad
.sp .6
.RS 4n
Deletes one or more Configuration Profiles according to the specified names. If
the specified Configuration Profile does not exist, this subcommand fails. The
wild-card "all" can be used to delete all profiles.
.sp
The "solaris.network.wifi.config" authorization is required for this
subcommand.
.RE

.sp
.ne 2
.na
\fB\fBshowprofile\fR [\fIprofile\fR]\fR
.ad
.sp .6
.RS 4n
Displays the parameters in the Configuration Profile according to the specified
\fIprofile\fR. \fBWEP\fR (wired equivalent privacy) keys are not printed
because they are write-only parameters. If no \fIprofile\fR is specified, all
the profiles are shown.
.RE

.sp
.ne 2
.na
\fB\fBsetprofilewepkey\fR 1|2|3|4\fR
.ad
.sp .6
.RS 4n
Sets one of the 4 \fBWEP\fR encryption keys in the specified Configuration
Profile "profile". Like the other \fBprofile\fR subcommands,
\fBsetprofilewepkey\fR does not affect the configuration of a network
interface, even if a \fBWiFi\fR interface is currently running with the
specified profile. In order for the modified profile to be applied to the
network interface, the \fBconnect\fR or \fBautoconf\fR subcommands have to be
used after the profile has been updated.
.sp
Other than that difference, the usage of \fBsetprofilewepkey\fR is the same as
the \fBsetwepkey\fR subcommand. For example, to update wepkey 2 in profile
"\fIhome\fR":
.sp
.in +2
.nf
example% wificonfig setprofilewepkey home 2
input wepkey2: < user input here>
confirm wepkey2: < user input here>
.fi
.in -2
.sp

The "solaris.network.wifi.wep" authorization is required for this subcommand.
.RE

.sp
.ne 2
.na
\fB\fBgetprofileparam\fR \fIprofile\fR [parameter]\  [...]]\fR
.ad
.br
.na
\fB\fBsetprofileparam\fR \fIprofile\fR [parameter=value]\  [...]]\fR
.ad
.sp .6
.RS 4n
Gets or sets parameters in the specified Configuration Profile "\fIprofile\fR".
Like the other profile subcommands, these subcommands do not affect the
configuration of a network interface, even if a \fBWiFi\fR interface is
currently running with the specified profile. In order for the modified
profile to be applied to the network interface, the \fBconnect\fR or
\fBautoconf\fR subcommands have to be used after the profile has been updated.
.sp
A \fBgetprofileparam\fR without any parameters will display all the parameters
and their values.
.sp
"Solaris.network.wifi.wep" authorization is required when the \fBsetparam\fR
subcommand is used with the
\fIwepkey1\fR|\fIwepkey2\fR|\fIwepkey3\fR|\fIwepkey4\fR parameter. For all
other parameters, the \fBsetparam\fR subcommand requires
"solaris.network.wifi.config"authorization.
.sp
For example, to change the settings for the "\fIhome\fR" Configuration Profile,
use:
.sp
.in +2
.nf
$ wificonfig setprofileparam home <parameter1=value1> \e
[parameter2=value2 [...]]
$ wificonfig getprofileparam home <parameter1> [parameter2 [...]]
.fi
.in -2
.sp

The set of parameters and their allowed values are the same as those specified
for the \fBsetparam\fR subcommand.
.RE

.sp
.ne 2
.na
\fB\fBhistory\fR\fR
.ad
.sp .6
.RS 4n
Lists the \fBWLAN\fRs in the History List. \fBwificonfig\fR automatically
records the \fBWLAN\fRs that appear in every scanning attempt. The History List
contains a maximum of 10 records of the most recent \fBWLAN\fRs, sorted by
time. These records can be listed by using this subcommand.
.RE

.sp
.ne 2
.na
\fB\fBlistprefer\fR\fR
.ad
.sp .6
.RS 4n
Lists the content of the Preference List.
.RE

.sp
.ne 2
.na
\fB\fBremoveprefer\fR \fIprofile\fR\fR
.ad
.sp .6
.RS 4n
Removes one or more profiles from the Preference List. The wild-card "all" can
be used to delete all profiles.
.sp
The "solaris.network.wifi.config" authorization is required for this
subcommand.
.RE

.sp
.ne 2
.na
\fB\fBsetprefer\fR \fIprofile\fR [\fIn\fR]\fR
.ad
.sp .6
.RS 4n
Sets the position of a \fIprofile\fR in the Preference List. This may add or
change the position of a \fIprofile\fR in the Preference List. The valid values
of "\fIn\fR" range from 1 to 10. If "\fIn\fR" is missing, the default value of
1 is assumed. If the specified position is already occupied, the occupying
\fIprofile\fR is moved lower on the list. If "\fIn\fR" is off the end of the
list, \fIprofile\fR is added to the end of the list. The Preference List can
also be created by using this subcommand. If the \fBautoconf\fR subcommand is
used at a later time, \fBwificonfig\fR tries to join the \fBWLAN\fRs according
to the Preference List.
.sp
The "solaris.network.wifi.config" authorization is required for this
subcommand.
.RE

.SH EXAMPLES
\fBExample 1 \fRListing the Parameters Supported by a Driver
.sp
.LP
To display what parameters the \fIath\fR driver supports and the read/write
modes of the parameters:

.sp
.in +2
.nf
% wificonfig -i ath0 setparam
          parameter     property
              bssid     read only
              essid     read/write
            bsstype     read/write
              rates     read/write
           authmode     read/write
         encryption     read/write
        wepkeyindex     read/write
             signal     read only

.fi
.in -2
.sp

.LP
\fBExample 2 \fRGetting and Setting Parameters on the WiFi interface
.sp
.LP
To get the current rates and signal strength from the driver:

.sp
.in +2
.nf
% wificonfig -i ath0 getparam rates signal
      ath0:
         rates = 1,2,5.5,11
         signal = 10
.fi
.in -2
.sp

.LP
\fBExample 3 \fRManaging Configuration Profiles
.sp
.LP
A Configuration Profile can be created offline and then connected to the
network with the created Configuration Profile. The following series of
commands creates the Configuration Profile, displays the contents of that
profile, and connects to the network with the Configuration Profile:

.sp
.in +2
.nf
% wificonfig createprofile myXXX essid=rover encryption=WEP \e
			wepkey1=12345
% wificonfig showprofile myXXX
  [myXXX]
  essid=rover
  encryption=WEP
  wepkey1=[secret]

% ifconfig ath0 plumb
% wificonfig -i ath0 connect myXXX
.fi
.in -2
.sp

.LP
\fBExample 4 \fRManaging the Preference List
.sp
.LP
A profile can be added to the Preference List and then used by the
\fBautoconf\fR subcommand. The following series of commands adds a profile
named \fImyXXX\fR to the top of the Preference List, automatically connects
\fIath0\fR to the first available \fBWLAN\fR in the Preference List, and
removes \fImy_neighbor\fR from the Preference List

.sp
.in +2
.nf
% wificonfig setprefer myXXX 1
% ifconfig ath0 plumb
% wificonfig -i ath0 autoconf
% wificonfig removeprefer my_neighbor
.fi
.in -2
.sp

.LP
\fBExample 5 \fRViewing the History List
.sp
.LP
To display the history of the \fBWLAN\fRs:

.sp
.in +2
.nf
% wificonfig history

    WLAN history:

  essid	        bssid	            encryption	last seen
  myXXX           00:0f:24:11:12:14  WEP        Fri Sep 13 09:15:24 2004
  my_office_ssid  00:0f:24:11:12:15  WEP        Fri Sep 13 13:20:04 2004
  my_neighbor1    00:0f:24:11:12:16  NONE       Fri Sep 14 08:01:26 2004
  my_neighbor2    00:0f:24:11:12:17  WEP        Fri Sep 18 21:33:12 2004
.fi
.in -2
.sp

.LP
\fBExample 6 \fRAutomatic Configuration
.sp
.LP
To configure the interface according to the previously saved Preference List:

.sp
.in +2
.nf
% ifconfig ath0 plumb
% wificonfig -i ath0 autoconf
.fi
.in -2
.sp

.sp
.LP
If the Preference List is empty, or none of the \fBWLAN\fRs listed by the
Preference List can be found, \fBwificonfig\fR uses the default configuration,
directs the interface to scan and join the \fBWLAN\fR using the built-in
heuristics specified above.

.LP
\fBExample 7 \fRConnecting To a WLAN
.sp
.LP
To search for a Configuration Profile with the name \fImyXXX\fR and configure
the interface accordingly:

.sp
.in +2
.nf
% ifconfig ath0 plumb
% wificonfig -i ath0 connect myXXX
.fi
.in -2
.sp

.sp
.LP
If the specified Configuration Profile does not exist, \fBwificonfig\fR
interprets it as an \fIessid\fR and sets \fIath0\fR to use \fIessid\fR
\fImyXXX\fR, and no other parameters are set.

.LP
\fBExample 8 \fRDisplaying the Content of a Configuration Profile
.sp
.LP
To print the parameters of the previously Configured Profile named
\fImy_home_ssid\fR:

.sp
.in +2
.nf
% wificonfig showprofile my_home_ssid
.fi
.in -2
.sp

.LP
\fBExample 9 \fRMonitoring the link status
.sp
.LP
To monitor the link status:

.sp
.in +2
.nf
% wificonfig -i ath0 showstatus
        ath0:
                linkstatus: not connected,
.fi
.in -2
.sp

.sp
.LP
or

.sp
.in +2
.nf
        ath0:
                linkstatus: connected
                active profile: [home]
                essid: myhome
                bssid: 00:0b:0e:12:e2:02
                encryption: WEP
                signal: medium(10)
.fi
.in -2
.sp

.LP
\fBExample 10 \fRScanning for available networks
.sp
.LP
To scan for available networks:

.sp
.in +2
.nf
% wificonfig -i ath0 scan
essid           bssid             type          encryption      signal
                                                                level
ietf64-secure   00:0b:0e:12:e2:02 access point  WEP             9
roomlinx        00:40:96:a1:13:70 access point  none            6
ietf64          00:0b:0e:13:32:00 access point  none            3
ietf64-secure   00:0b:0e:13:32:02 access point  WEP             3
ietf64          00:0b:0e:12:e2:00 access point  none            9
ietf64-secure   00:0b:0e:12:e4:c2 access point  WEP             8
ietf64          00:0b:0e:12:e4:c0 access point  none            8
roomlinx        00:40:96:a0:aa:aa access point  none            1
roomlinx        00:40:96:a0:ab:39 access point  none            8
.fi
.in -2
.sp

.SH EXIT STATUS
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 5n
Successful operation
.RE

.sp
.ne 2
.na
\fB\fB1\fR\fR
.ad
.RS 5n
Fatal Error; the operation failed. For example, a connect failed to associate
with an Access Point.
.RE

.sp
.ne 2
.na
\fB\fB2\fR\fR
.ad
.RS 5n
Improper Use; help information will be printed
.RE

.sp
.ne 2
.na
\fB\fB3\fR\fR
.ad
.RS 5n
Minor error
.RE

.SH ATTRIBUTES
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Unstable
.TE

.SH SEE ALSO
.BR ps (1),
.BR ath (4D),
.BR attributes (7),
.BR ifconfig (8)