System Administration Commands wificonfig(1M) NAME wificonfig - WLAN configuration SYNOPSIS wificonfig [-i interface] wificonfig [-R root_path] [-i interface] subcommand [parameter [=value...] [...]] wificonfig [-R root_path] -p profile setwepkey n wificonfig [-R root_path] -p profile getparam|setparam [parameter [=value...] [...]] DESCRIPTION wificonfig defines a set of subcommands and parameters to configure WIFI interfaces in the system. The command can create or load Configuration Profiles and get or set specific parameters on a WIFI interface. A driver may support all parameters or a subset of these parameters. wificonfig uses rbac(5) to control user access to the inter- face. Only users with the "solaris.network.wifi.config" authorization can manage a WIFI interface. Only users with "solaris.network.wifi.wep" authorizations can configure the WEP (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" author- izations are not granted to any user apart from root. In the first synopsis form, invoking wificonfig followed by an interface name displays the parameters that are supported by the driver. If wificonfig is invoked without the inter- face name, the usage information is printed. In the second synopsis form, wificonfig configures a WIFI interface according to the subcommand given. If the inter- ace is not specified (when the -i option is missing), wifi- config looks in the /dev/wifi/ directory and try to open the the wifi interface by directory order, the first one which is successfully opened is used as default interface. The Wi- Fi interfaces in /dev/wifi are automatically created by devfs. In the third and fourth synopsis form, the user can specify an arbitrary Configuration Profile to change the parameters. A wireless NIC can be associated with different Wireless LANs. The set of parameters used when associated with a given WLAN is called a Configuration Profile. A Configuration Profile is created in either of the follow- ing two cases: o A Configuration Profile can be explicitly created for a WLAN by using the createprofile subcommand (see below). The actual WLAN may be present or not. o A Configuration Profile is automatically created by the setparam subcommand (if the Configuration Profile does not already exist). Under this circumstance, the name of the Configuration Profile is the same as the essid of the WLAN which the wifi interface is connecting to. If the essid cannot be determined when the user sets parameters, the Configuration Profile is not created, and those parameters are saved temporarily, then after- wards theos parameters can be explicitly saved as a Configuration Profile by using the saveprofile sub- command. wificonfig also maintains a list of Configuration Profiles called the Preference List. This list makes automatic confi- guration possible. When the autoconf subcommand is used, wificonfig tries to connect to each pre-configured WLAN acc- ording to the order of the Preference List.if the Prefere- nce List is empty or none of the WLANs in the Preference List can be found, wificonfig uses its built-in heuristics to automatically configure the interface. See the autoconf subcommand for the heuristics). A few subcommands (listpre- fer, setprefer, removeprefer) are defined to manipulate the Preference List. OPTIONS The following options are supported: -i interface Specifies a wireless network interface to do the confi- guration. -R root_path Defines the full path name of a directory to use as the root_path. -p profile Specifies the Configuration Profile who's parameters are to be get/set. The -p option is only valid for 'getpa- ram', 'setparam' and 'setwepkey' subcommands. SUBCOMMANDS The following subcommands are supported: autoconf [wait n|FOREVER|-1] Configures the interface automatically. The interface is configured according to the previously saved Preference List found in /etc/inet/wifi. wificonfig first gets a list of available WLANs by scanning the radio. It then compares the list of available WLANs with the Preference List. If the Preference List is empty, or if none of the WLANs in the Preference List can be found, wificonfig uses the following heuristics to choose a WLAN to connect to: 1) the WLANs without encryption has higher priority, 2) the WLANs with stronger signal strength has higher priority, 3) the WLANs with higher transmit rates has higher priority. Optionaly, if the WLANs in the Preference list are avai- lable, the user can specify the number of seconds to wait before 'autoconf' returns using the 'wait' option. By default (without the 'wait' option), 'autoconf' returns within 10s. If FOREVER or -1 follows the 'wait' option, wificonfig blocks until the NIC is successfully connected to the WLAN specified by the profile in the Preference list. This subcommand requires the "solaris.network.wifi. config" authorization. createprofile [profile] parameter=value [...] Creates a Configuration Profile named 'profile' off- line. The specified parameters are saved as items of this Configuration Profile. The name 'profile' is optio- nal. If it's missing, wificonfig takes the name of the specified essid as the name of the Configuration Profile . The user can specify a group of parameters. At a mini- mum, the essid must be specified. This subcommand requires the "solaris.network.wifi.con- fig" authorization. This subcommand does not require the -i option. If '-i interface' is specified, it's ignored. showprofile [profile] Prints the parameters in the Configuration Profile according to 'profile'. WEP (wired equivalent privacy) keys are not printed because they are write-only parame- ters. If 'profile' is missing, all the profiles are shown. This subcommand does not require the -i option. If '-i interface' is specified, it's ignored. saveprofile [profile] Saves the temporarily saved parameters as a Configura- tion Profile with a name equal to 'profile'. Only those parameters set without knowing which WLAN the interface is connecting to are temporarily saved parameters. If 'profile' is missing, the parameters are saved in the current active profile of the interface. If there is no active profile for the interface, the essid is used as the profile name. This subcommand requires the "solaris.network.wifi.con- fig" authorization. deleteprofile profile1 profile2 ... Deletes one or more Configuration Profiles according to the specified names. If the specified Configuration Pro- file does not exist, this subcommand fails. The wildcart '\*' can be used to delete all profiles. This subcommand requires the "solaris.network.wifi.con- fig" authorization. This subcommand does not require the -i option. If '-i interface' is specified, it's ignored. history Lists the WLANs in the History List. wificonfig automatically records the WLANs appear in every scanning attempt. The History List contains a maximum of 10 records of the most recent WLANs, sorted by time. These records can be listed by using this subcommand. This subcommand does not require the -i option. If '-i interface' is specified, it's ignored. listprefer Lists the content of the Preference List. This subcommand does not require the -i option. If '-i interface' is specified, it's ignored. removeprefer profile Removes one or more profiles from the Preference List. The wildcart '\*' can be used to delete all profiles. This subcommand requires the "solaris.network.wifi.con- fig" authorization. This subcommand does not require the -i option. If '-i interface' is specified, it's ignored. setprefer profile [n] Sets the position of a profile in the Preference List. This may add or change the position of a profile in the Preference List. The valid values of n range from 1 to 10. If n is missing, the default value of 1 is assumed. If the specified position is already occupied, the occu- pying profile is moved lower on the list. If n is off the end of the list, 'profile' is added to the end of the list. The Preference List can also be created by us- ing this subcommand. If the autoconf subcommand is used at a later time, wificonfig tries to join the WLANs acc- ording to the Preference List. This subcommand requires the "solaris.network.wifi.con- fig" authorization. This subcommand does not require the -i option. If '-i interface' is specified, it's ignored. setwepkey 1|2|3|4 Sets one of the 4 WEP encryption keys. WEP keys are used to encrypt the content of the network packets which are transmitted on air. There are 4 WEP keys in the NIC according to the 802.11 specifications. The setwepkey subcommand is used to update one of the 4 keys by promp- ting the user for the key. The user must enter the key twice.The input is not echoed. For example, to update setwepkey2: example% wificonfig -i ath0 setwepkey 2 input wepkey2: < user input here> confirm wepkey2: < user input here> A WEP key can be 5 bytes or 13 bytes long. There are two ways to enter a WEP key, by ASCII values or by hex values. If the user enters 5 or 13 characters, it is considered the ASCII representation of the key. If the user enters 10 or 26 characters, it is considered the hex representation of the key. For example "12345" is equivalent to "6162636465". If the user enters other number of characters, the subcommand fails. WEP keys are write-only; they cannot be read back via wificonfig. Alternatively, the WEP keys can also be set in plain te- xt form by the 'setparam' subcommand. This makes setting WEP keys scriptable (See the parameters of 'setparam' for the details). This subcommand requires "solaris.network.wifi.wep" aut- horization. If '-p profile' is specified, the WEP keys are only saved in the named profile, but not updated in the NIC. loaddef Forces the NIC to reload the default values of all the parameters. See the getparam and setparam subcommands for the default values of the parameters. This subcom- mand requires the "solaris.network.wifi.config" authori- zation. connect profile [wait n|FOREVER|-1] Connects to a wireless network according to a pre-conf- igured 'profile'. If the specified Configuration Profile exists in /etc/inet/wifi, the 'connect' subcommand loa- ds that Configuration Profile to configure the interface . That profile subsequently becomes the current active profile of the interface after 'connect' succeeds. If no existing Configuration Profile matches the specified name, the behavior of 'connect' is equivalent to 'load- def' except that the 'essid' parameter is set as 'pro- file', and the process exit status is 3 (minor error). Optionaly, if the specified profile exists, the user can specify the number of seconds to wait before 'connect' returns (the 'wait' option). By default (without the 'wait' option), 'connect' returns within 10s. If FOREVER or -1 follows the 'wait' option, wificonfig blocks until the NIC is successfully connected to the WLAN specified by the existing profile. This subcommand requires the "solaris.network.wifi.con- fig" authorization. disconnect Disconnects the interface from the currently associated wireless network. The interface associates with none of the wireless networks. This subcommand requires the "solaris.network.wifi.config" authorization. scan Scans and lists the currently available WLANs. showstatus Display the basic status of a WLAN interface. If the WLAN interface is connected, the basic status includes: the name of the current active profile, the name of the network, whether the network is encrypted or not, and the signal strength. getparam | setparam Gets or sets parameters. If '-p profile' is specified, the parameters are only obtained from or saved in the named profile, but not obtained from or updated in the NIC. The setparam wepkey1|wepkey2|wepkey3|wepkey4 subcommand requires the "solaris.network.wifi.wep" authorization; The setparam other parameters subcommand requires the "solaris.network.wifi.config" authorization. For example, $ wificonfig setparam [-p profile] [parameter2 [...]] The current version supports the following parameters (the values are case insensitive). bssid MAC address of the associated Access Point. The valid value is a hex value of 6 bytes. The bssid can also be the IBSSID in a peer-to-peer configuration. If the bssid is all zero, the worksta- tion is not connected to any WLAN. If the bssid is non-zero, the workstation is connected to a WLAN. The default value is all zero. This parameter is read-only. essid Network name. The valid value is a string of up to 32 chars. If essid is an empty string, the driver automatically scans and joins the WLAN using the built-in heuristics. The default value is an empty string. bsstype Specifies whether the Access Point is used. The valid values are BSS or AP to join a WLAN through an Access Point. The valid values are IBSS or ADHOC 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 BSS createibss Specifies whether to create an IBSS if the connect does not result in finding the desired network. This enables the user to start a peer-to-peer network so that other workstations can join. The valid values are YES to start a new peer-to-peer WLAN (instead of joining one) and NO to not start a peer-to-peer WLAN. The default value is NO. The NIC always tries to join a WLAN first. If this is successful, createibss is ignored. channel An integer indicating the operating fre- quency. This channel number varies by regulatory domain. When the channel number is obtained by the getparam sub- command, the value indicates the actual channel the card uses to connect to the network. The channel number is set by the setparam subcommand, and the value is only applicable when the card is in ad-hoc mode. It indicates the operating channel of the IBSS. The default value is the channel number on the card. rates Specifies the transmission rates. The valid values are (in Mbit/s) are 1, 2, 5.5, 6, 9, 11, 12, 18, 22, 24, 33, 36, 48, and 54. A NIC may support multiple transmission rates depending on its capability. This is the only parameter that accepts multiple values. When mul- tiple values are supplied to set this parameter, each value must be separated by a comma (,). See the EXAMPLES sec- tion for details. The default values are the data rates supported by the chip. powermode Specifies the power management mode. The valid values are OFF to disable power management, MPS for maximum power sav- ing, and FAST for the best combination of speed and power saving. The default value is OFF authmode Specifies the authorization type. The valid values are OPENSYSTEM for an open system, where anyone can be authenti- cated and SHARED_KEY for a Shared Key authentication mode. The default value is OPENSYSTEM encryption Specifies the encryption algorithm to be used. The valid values are NONE for no encryption algorithm and WEP to turn on WEP encryption. The default value is NONE. wepkey1|wepkey2|wepkey3|wepkey4 WEP keys. A maximum of 4 WEP keys (inde- xed 1 through 4) can be set in a NIC. They are write-only parameters which can be set by 'setparam' but cannot be read back by 'getparam'. WEP keys can either be set by 'setwepkey' or 'setparam' sub- command. 'setparam' uses plain text but it's scriptable. See the 'sewepkey' sub- command for more information about how a WEP key is encoded. Setting WEP keys requires "solaris.network.wifi.wep" aut- horization. wepkeyindex 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 WEP is on. signal Specifies the strength of the received radio signal. The valid values are 0 - 15 , where 0 means the weakest signal and 15 means the strongest signal. This parameter is read-only and indicates the radio signal strength received by the workstation. radio 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. EXAMPLES Example 1: Listing the Parameters Supported by a Driver To display what parameters the ath driver supports and the read/write modes of the parameters: % wificonfig -i ath0 ... bssid - read essid - read/write nodename - read/write encryption - read/write signal - read ... Example 2: Getting and Setting Parameters on the WIFI inter- face To get the current rates and signal strength from the driver: % wificonfig -i ath2 getparam rates signal ath2: rates = 1,2,5.5,11 signal = 10 Example 3: Managing Configuration Profiles A Configuration Profile can be created offline and then con- nected to the network with the created Configuration Pro- file. The following series of commands creates the Confi- guration Profile, displays the contents of that profile, and connects to the network with the Configuration Profile: % wificonfig -i ath0 createprofile myXXXX essid=rover encryption=WEP wepkey1=12345 % wificonfig -i ath0 showprofile myXXX [myXXX] essid = rover encryption=WEP % wificonfig -i ath0 connect myXXX Example 4: Managing the Preference List A profile can be added to the Preference List and then used by the autoconf subcommand. The following series of commands adds a profile named my_home_ssid to the top of the Prefere- nce List, automatically connects ath0 to the first availa- ble WLAN in the Preference List, and removes my_neighbor from the Preference List % wificonfig -i ath0 setprefer my_home_ssid 1 % wificonfig -i ath0 autoconf % wificonfig -i ath0 removeprefer my_neighbor Example 5: Viewing the History List To display the history of the WLANs: % wificonfig -i ath0 history ... WLAN history: essid bssid encryption last seen my_home_ssid 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 ... Example 6: Automatic Configuration To configure the interface according to the previously saved Preference List: % wificonfig -i ath0 autoconf If the Preference List is empty, or none of the WLANs listed by the Proference List can be found, wificonfig uses the default configuration, directs the interface to scan and join the WLAN using the built-in heuristics. Example 7: Connecting To a WLAN To search for a Configuration Profile with the name my_home_ssid and configure the interface accordingly: % wificonfig -i ath0 connect my_home_ssid If the specified Configuration Profile does not exist, wifi- config sets the essid of the ath0 with the value my_home_ssid, and no other parameters are set. Example 8: Displaying the Content of a Configuration Profile To print the parameters of the previously configured profile named my_home_ssid: % wificonfig -i ath0 showprofile my_home_ssid Example 9: Saving a Configuration Profile When the interface is not connecting to any WLAN, setting parameters does not result in saving those parameters in any Configuration Profiles, but saving them temporarily, to save the temporarily saved parameters in the named Configuration Profile: % wificonfig -i ath0 saveprofile myXXX Example10: Monitoring the link status. % wificonfig -i ath0 showstatus ath0: linkstatus: not connected, or ath0: linkstauts: connected active profile: [home] essid: myhome encryption: WEP signal: strong EXIT STATUS 0 Successful operation 1 Fatal Error; the operation failed 2 Improper Use; help information will be printed 3 Minor error ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Availability | SUNWcsr | |_____________________________|_____________________________| | Interface Stability | Evolving | |_____________________________|_____________________________| SEE ALSO attributes(5), ath(7D)